[cold-review] feat: session-attached long-running jobs (#1404)

AGENTS.md

@@ -24,6 +24,7 @@ Start with the task's files; read only relevant sections of these references, no
 | Shared wire types and validation | `shared/src/types.ts`, `schemas.ts`, `socket.ts`, `modes.ts` |
 | Native API contract, chat conformance | [client contract](docs/api/client-contract/index.md), [iOS](ios/README.md), [Android](android/README.md) |
 | Encrypted native push relay | [relay/README.md](relay/README.md) |
+| Session-attached jobs (outliving work) | [session jobs guide](docs/guide/session-jobs.md), `cli/src/commands/job.ts` |
 | User docs / marketing site | `docs/` (VitePress) / `website/` |
 
 ## Repository conventions
@@ -39,6 +40,20 @@ Start with the task's files; read only relevant sections of these references, no
 - Metadata/state updates are versioned; preserve stale-update rejection. Permission controls use per-flavor catalogs in `shared/src/modes.ts`, further constrained by session capabilities.
 - `shared/fixtures/**` is generated from the web chat pipeline, the source of truth for native conformance. Never hand-edit fixtures. For changes to fixture inputs or generation (paths in [.github/workflows/fixtures.yml](.github/workflows/fixtures.yml)), run `bun run gen:fixtures` and include any generated changes in the deliverable. CI checks drift and runs native conformance on fixture changes.
 
+## Session-attached jobs (outliving work)
+
+When an agent starts process-shaped work that will keep running after the agent goes idle (`nohup`, batch imports, long scripts, external daemons), attach it so the session list stays truthful while `active: false`. This is **not** thinking progress / todos / in-agent background tools.
+
+Agent contract (idle agents cannot heartbeat — bare set + nohup freezes the bar):
+
+1. **Required for process-shaped work:** Shell `hapi job run <session-id> <key> --label … -- <cmd>` (auto-heartbeat + exit status). Use `"$HAPI_SESSION_ID"` only when it matches the operator chat row (`/sessions/<id>` in the web URL).
+2. MCP `session_job` **refuses `action=set`**. Use it only for `update` / `clear` / `list` on a job the supervisor already created.
+3. Manual CLI `set` only with a self-heartbeating wrapper (`update` ≥~10m); never MCP set + nohup.
+4. Prefer honest `--remaining` or `--done`/`--total`; omit counts if unknown — never invent a percent.
+5. Elapsed wall clock is always shown from `startedAt` (not an ETA).
+
+Full guide: [docs/guide/session-jobs.md](docs/guide/session-jobs.md). CLI: `hapi job --help`.
+
 ## Verification and completion
 
 Choose checks by the change's impact, not by the number of workflow steps:

android/app/src/main/kotlin/app/hapi/companion/feature/settings/LanguagePrefs.kt

@@ -12,9 +12,10 @@ import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.map
 
 /**
- * App language choice. [ENGLISH]/[SIMPLIFIED_CHINESE] mirror the web's
- * `Locale` (`'en' | 'zh-Hans'`); [SYSTEM] is the Android-only default —
- * follow the device language (empty per-app locale list).
+ * App language choice. [ENGLISH]/[SIMPLIFIED_CHINESE]/[RUSSIAN] mirror the
+ * web's `Locale` (`'en' | 'zh-Hans'` plus the fork's `'ru'`); [SYSTEM] is the
+ * Android-only default — follow the device language (empty per-app locale
+ * list).
  *
  * B-M5a wires the selection through `AppCompatDelegate.setApplicationLocales`
  * ([localeTags] is the BCP-47 tag list to apply); the Settings screen applies
@@ -24,7 +25,8 @@ import kotlinx.coroutines.flow.map
 enum class AppLanguage(val storageKey: String, val localeTags: String) {
     SYSTEM("system", ""),
     ENGLISH("en", "en"),
-    SIMPLIFIED_CHINESE("zh-Hans", "zh-Hans");
+    SIMPLIFIED_CHINESE("zh-Hans", "zh-Hans"),
+    RUSSIAN("ru", "ru");
 
     companion object {
         fun fromStorageKey(raw: String?): AppLanguage =

android/app/src/main/kotlin/app/hapi/companion/feature/settings/SettingsScreen.kt

@@ -377,4 +377,5 @@ private fun languageLabel(language: AppLanguage): String = when (language) {
     AppLanguage.SYSTEM -> stringResource(R.string.settings_language_system)
     AppLanguage.ENGLISH -> "English"
     AppLanguage.SIMPLIFIED_CHINESE -> "简体中文"
+    AppLanguage.RUSSIAN -> "Русский"
 }

android/app/src/main/res/xml/locales_config.xml

@@ -4,4 +4,5 @@
 <locale-config xmlns:android="http://schemas.android.com/apk/res/android">
     <locale android:name="en" />
     <locale android:name="zh-CN" />
+    <locale android:name="ru" />
 </locale-config>

cli/README.md

@@ -44,6 +44,7 @@ Choose a supported coding agent from your terminal and control its sessions remo
 - `hapi resume [sessionId]` - List resumable sessions for this machine or resume one locally.
 - `hapi ping-peer <session-id-prefix> <message>` - Resume (if needed) and message another session. Prefer this or MCP `ping_peer` / `list_peers` over reinventing JWT+curl. Also `--message-file` / `--list`.
 - `hapi inspect-peer <session-id-or-prefix>` - Read-only peer metadata + recent message text (no resume). Prefer this or MCP `inspect_peer` when a user cites `[title](/sessions/<id>)` or Copy-reference `See session "…" (/sessions/<id>) for context`. `/sessions/<id>` is a hub path, not a local file. Optional `--limit`.
+- `hapi job set|update|clear|list|run` - Attach long-running outliving work to a session so the list UI shows progress while the agent is idle (`tiann/hapi#1404`). Prefer `"$HAPI_SESSION_ID"`. Heartbeat via `update` (or `run`); honest `--remaining` or `--done`/`--total` (omit counts if unknown — never invent a percent). Late-attach clock fix: `set --started-at <epoch-ms>` or clear+set. See `docs/guide/session-jobs.md` and `hapi job --help`.
 
 The picker lists agents alphabetically by command name. Use Up/Down and Enter
 to choose; Esc or Ctrl-C cancels. It appears on every bare invocation, even

cli/src/agent/backends/acp/AcpSdkBackend.ts

@@ -5,6 +5,15 @@ import { AcpStdioTransport, type AcpStderrError } from './AcpStdioTransport';
 import { AcpMessageHandler, type AcpTextChunkMode } from './AcpMessageHandler';
 import { ACP_SESSION_UPDATE_TYPES } from './constants';
 import { thinkingHintFromSessionUpdate } from './shouldBumpThinkingFromSessionUpdate';
+
+/** Why the backend is bumping/clearing hub thinking — launchers filter chatter here (#1553). */
+export type AgentActivitySource =
+    | 'state_update_running'
+    | 'state_update_idle'
+    | 'state_update_requires_action'
+    | 'permission';
+
+export type AgentActivityListener = (thinking: boolean, source: AgentActivitySource) => void;
 import { logger } from '@/ui/logger';
 import { withRetry } from '@/utils/time';
 import packageJson from '../../../../package.json';
@@ -93,7 +102,7 @@ export class AcpSdkBackend implements AgentBackend {
     private usageUpdateListener: ((msg: AgentMessage) => void) | null = null;
     private sessionInfoUpdateListener: ((update: AcpSessionInfoUpdate) => void) | null = null;
     /** Fired on foreground ACP state / permission so launchers can bump hub thinking (#1470). */
-    private agentActivityListener: ((thinking: boolean) => void) | null = null;
+    private agentActivityListener: AgentActivityListener | null = null;
     /** Debounce timer for state_update running → thinking (#1502 chatter). */
     private runningThinkingTimer: ReturnType<typeof setTimeout> | null = null;
     private lastForwardedUsageUpdate: AcpUsageUpdate | null = null;
@@ -524,7 +533,7 @@ export class AcpSdkBackend implements AgentBackend {
      * `false` = `state_update` idle (skipped while a HAPI prompt turn is still draining).
      * Launchers should ignore no-ops when session.thinking already matches.
      */
-    setAgentActivityListener(listener: ((thinking: boolean) => void) | null): void {
+    setAgentActivityListener(listener: AgentActivityListener | null): void {
         this.agentActivityListener = listener;
     }
 
@@ -988,7 +997,7 @@ export class AcpSdkBackend implements AgentBackend {
             if (this.isProcessingMessage) {
                 return;
             }
-            this.agentActivityListener(false);
+            this.agentActivityListener(false, 'state_update_idle');
             return;
         }
 
@@ -999,13 +1008,17 @@ export class AcpSdkBackend implements AgentBackend {
             }
             this.runningThinkingTimer = setTimeout(() => {
                 this.runningThinkingTimer = null;
-                this.agentActivityListener?.(true);
+                this.agentActivityListener?.(true, 'state_update_running');
             }, AcpSdkBackend.RUNNING_THINKING_DEBOUNCE_MS);
             return;
         }
 
         this.clearRunningThinkingTimer();
-        this.agentActivityListener(true);
+        const source: AgentActivitySource = update.sessionUpdate === 'state_update'
+            && update.state === 'requires_action'
+            ? 'state_update_requires_action'
+            : 'state_update_running';
+        this.agentActivityListener(true, source);
     }
 
     private clearRunningThinkingTimer(): void {
@@ -1191,7 +1204,7 @@ export class AcpSdkBackend implements AgentBackend {
         if (this.permissionHandler) {
             try {
                 // Permission prompts imply the agent is awake (#1470).
-                this.agentActivityListener?.(true);
+                this.agentActivityListener?.(true, 'permission');
                 this.permissionHandler(request);
             } catch (error) {
                 this.pendingPermissions.delete(toolCallId);

cli/src/agent/runners/runAgentSession.test.ts

@@ -74,7 +74,7 @@ vi.mock('@/claude/utils/startHappyServer', () => ({
         harness.startHappyServerOptions = options
         return {
             url: 'http://127.0.0.1:1234',
-            toolNames: ['change_title', 'display_image', 'display_video', 'display_media', 'list_peers', 'ping_peer', 'inspect_peer', 'skill_lookup'],
+            toolNames: ['change_title', 'display_image', 'list_peers', 'ping_peer', 'inspect_peer', 'session_job', 'skill_lookup'],
             stop: harness.stopServer
         }
     })
@@ -167,7 +167,7 @@ describe('runAgentSession', () => {
             '--url',
             'http://127.0.0.1:1234',
             '--tools',
-            'change_title,display_image,display_video,display_media,list_peers,ping_peer,inspect_peer,skill_lookup'
+            'change_title,display_image,list_peers,ping_peer,inspect_peer,session_job,skill_lookup'
         ])
         expect(harness.newSessionOptions).toMatchObject({
             cwd: '/tmp/project',

cli/src/agent/sessionFactory.test.ts

@@ -135,6 +135,41 @@ describe('bootstrapExistingSession', () => {
         )
     })
 
+    it('exports the requested existing session id for Cursor runner resume (#1404)', async () => {
+        // Runner passes --existing-session-id (buildCliArgs); child bootstrap must
+        // publish that same hub row into HAPI_SESSION_ID for shell `hapi job run`.
+        const session = createSession()
+        session.metadata = {
+            ...session.metadata!,
+            flavor: 'cursor',
+            cursorSessionId: 'cursor-csid-1',
+            cursorSessionProtocol: 'acp'
+        }
+        const sessionClient = { updateMetadata: vi.fn() }
+        getSessionMock.mockResolvedValue(session)
+        getOrCreateMachineMock.mockResolvedValue({ id: 'machine-1' })
+        sessionSyncClientMock.mockReturnValue(sessionClient)
+        readSettingsMock.mockResolvedValue({ machineId: 'machine-1' })
+
+        await bootstrapExistingSession({
+            sessionId: 'hapi-session-1',
+            flavor: 'cursor',
+            startedBy: 'runner',
+            workingDirectory: '/tmp/project'
+        })
+
+        expect(getSessionMock).toHaveBeenCalledWith('hapi-session-1')
+        expect(process.env[HAPI_SESSION_ID_ENV]).toBe('hapi-session-1')
+        expect(notifyRunnerSessionStartedMock).toHaveBeenCalledWith(
+            'hapi-session-1',
+            expect.objectContaining({
+                flavor: 'cursor',
+                startedBy: 'runner',
+                startedFromRunner: true
+            })
+        )
+    })
+
     it('refuses to reopen a hub-archived session (hub-archive resurrection guard)', async () => {
         // #1911 M1 belt: hub-archived only (matches store merge-preserve scope).
         const session = createSession()

cli/src/claude/utils/startHappyServer.test.ts

@@ -44,6 +44,7 @@ describe('startHappyServer skill_lookup', () => {
     async function connect(enableSkillLookup = true): Promise<Client> {
         sendAgentMessage = vi.fn()
         const sessionClient = {
+            sessionId: 'test-session-id',
             updateMetadata: vi.fn(),
             sendAgentMessage,
             sendClaudeSessionMessage: vi.fn()
@@ -107,15 +108,16 @@ describe('startHappyServer skill_lookup', () => {
         const mcp = await connect(false)
         const tools = await mcp.listTools()
 
-        expect(tools.tools.map((tool) => tool.name)).toEqual([
+        expect(tools.tools.map((tool) => tool.name).sort()).toEqual([
             'change_title',
             'display_image',
             'display_video',
             'display_media',
-            'ping_peer',
             'inspect_peer',
-            'list_peers'
-        ])
+            'list_peers',
+            'ping_peer',
+            'session_job',
+        ].sort())
     })
 
     it('describes display_image as user output rather than image input', async () => {
@@ -170,6 +172,7 @@ describe('startHappyServer skill_lookup', () => {
 
     it('does not expose change_title when native ACP titles are enabled', async () => {
         const sessionClient = {
+            sessionId: 'test-session-id',
             updateMetadata: vi.fn(),
             sendAgentMessage: vi.fn(),
             sendClaudeSessionMessage: vi.fn()
@@ -182,15 +185,24 @@ describe('startHappyServer skill_lookup', () => {
         await mcp.connect(new StreamableHTTPClientTransport(new URL(server.url)))
         const tools = await mcp.listTools()
 
-        expect(server.toolNames).toEqual(['display_image', 'display_video', 'display_media', 'list_peers', 'ping_peer', 'inspect_peer'])
-        expect(tools.tools.map((tool) => tool.name)).toEqual([
+        expect(server.toolNames).toEqual([
             'display_image',
             'display_video',
             'display_media',
+            'list_peers',
             'ping_peer',
             'inspect_peer',
-            'list_peers'
+            'session_job',
         ])
+        expect(tools.tools.map((tool) => tool.name).sort()).toEqual([
+            'display_image',
+            'display_media',
+            'display_video',
+            'inspect_peer',
+            'list_peers',
+            'ping_peer',
+            'session_job',
+        ].sort())
     })
 
 })
@@ -317,11 +329,13 @@ describe('toClaudeAllowedHapiMcpTools', () => {
             'list_peers',
             'ping_peer',
             'inspect_peer',
+            'session_job',
             'skill_lookup'
         ])).toEqual([
             'mcp__hapi__change_title',
             'mcp__hapi__display_image',
             'mcp__hapi__list_peers',
+            'mcp__hapi__session_job',
             'mcp__hapi__skill_lookup'
         ])
         expect(toClaudeAllowedHapiMcpTools(['display_video'])).not.toContain('mcp__hapi__display_video')

cli/src/claude/utils/startHappyServer.ts

@@ -28,6 +28,13 @@ import {
 } from '@hapi/protocol/sessionCitation'
 import { PingPeerError, formatInspectPeerReport, formatPeerSessionsList, inspectPeer, listPeerSessions, peerListFetchLimit, pingPeer } from "@/modules/pingPeer/pingPeer";
 import { applySessionDisplayRename, normalizeSessionDisplayTitle } from "@/agent/sessionDisplayRename";
+import {
+    SESSION_JOB_TOOL_DESCRIPTION,
+    SESSION_JOB_TOOL_NAME,
+    handleSessionJobTool,
+    sessionJobInputSchema,
+    type SessionJobToolArgs,
+} from "@/modules/sessionJob/sessionJobMcp";
 
 type StartHappyServerOptions = {
     /**
@@ -376,6 +383,19 @@ function createHapiMcpServer(
         }
     });
 
+    mcp.registerTool<any, any>(SESSION_JOB_TOOL_NAME, {
+        description: SESSION_JOB_TOOL_DESCRIPTION,
+        title: 'Session-Attached Job',
+        inputSchema: sessionJobInputSchema,
+    }, async (args: SessionJobToolArgs) => {
+        logger.debug('[hapiMCP] session_job:', args.action, args.jobKey);
+        const result = await handleSessionJobTool(args, client.sessionId);
+        return {
+            content: [{ type: 'text' as const, text: result.text }],
+            isError: result.isError,
+        };
+    });
+
     mcp.registerTool<any, any>('list_peers', {
         description: 'List peer HAPI sessions on the same hub/namespace (id prefix, active, flavor, name). Uses this session\'s hub credentials - works from runner-spawned agents without being on the hub host. Prefer this over shelling `hapi ping-peer --list`. Then call inspect_peer / ping_peer with a listed id.',
         title: 'List Peer Sessions',
@@ -541,8 +561,8 @@ export async function startHappyServer(client: ApiSessionClient, options: StartH
     }));
 
     const toolNames = enableChangeTitle
-        ? ['change_title', 'display_image', 'display_video', 'display_media', 'list_peers', 'ping_peer', 'inspect_peer']
-        : ['display_image', 'display_video', 'display_media', 'list_peers', 'ping_peer', 'inspect_peer'];
+        ? ['change_title', 'display_image', 'display_video', 'display_media', 'list_peers', 'ping_peer', 'inspect_peer', SESSION_JOB_TOOL_NAME]
+        : ['display_image', 'display_video', 'display_media', 'list_peers', 'ping_peer', 'inspect_peer', SESSION_JOB_TOOL_NAME];
     if (options.skillLookup) {
         toolNames.push('skill_lookup');
     }

cli/src/claude/utils/systemPrompt.ts

@@ -2,6 +2,7 @@ import { trimIdent } from "@/utils/trimIdent";
 import { buildSessionCitationSteerInstruction } from "@hapi/protocol/sessionCitation";
 import { shouldIncludeCoAuthoredBy } from "./claudeSettings";
 import { DISPLAY_IMAGE_PROMPT_CLAUDE, DISPLAY_MEDIA_PROMPT_CLAUDE, DISPLAY_VIDEO_PROMPT_CLAUDE } from "@/modules/common/displayImagePrompt";
+import { withSessionJobInstruction } from "@/modules/common/sessionJobInstruction";
 import { withSessionSummaryInstruction } from "@/modules/common/sessionSummaryInstruction";
 
 /**
@@ -42,5 +43,5 @@ export function getSystemPrompt(): string {
     const base = includeCoAuthored
         ? BASE_SYSTEM_PROMPT + '\n\n' + CO_AUTHORED_CREDITS
         : BASE_SYSTEM_PROMPT;
-    return withSessionSummaryInstruction(base);
+    return withSessionSummaryInstruction(withSessionJobInstruction(base));
 }

cli/src/codex/happyMcpStdioBridge.test.ts

@@ -70,16 +70,20 @@ describe('runHappyMcpStdioBridge tool forwarding', () => {
             '--url',
             'http://127.0.0.1:43006',
             '--tools',
-            'change_title,display_image,display_video,display_media,skill_lookup'
+            'change_title,display_image,display_video,display_media,list_peers,ping_peer,inspect_peer,session_job,skill_lookup'
         ])
 
-        expect([...harness.tools.keys()]).toEqual([
+        expect([...harness.tools.keys()].sort()).toEqual([
             'change_title',
             'display_image',
-            'display_video',
             'display_media',
-            'skill_lookup'
-        ])
+            'display_video',
+            'inspect_peer',
+            'list_peers',
+            'ping_peer',
+            'session_job',
+            'skill_lookup',
+        ].sort())
 
         const handler = harness.tools.get('skill_lookup')
         expect(handler).toBeDefined()
@@ -140,6 +144,24 @@ describe('runHappyMcpStdioBridge tool forwarding', () => {
         ])
     })
 
+    it('registers session_job when included in --tools', async () => {
+        await runHappyMcpStdioBridge([
+            '--url',
+            'http://127.0.0.1:43006',
+            '--tools',
+            'change_title,display_image,list_peers,ping_peer,inspect_peer,session_job'
+        ])
+
+        expect([...harness.tools.keys()].sort()).toEqual([
+            'change_title',
+            'display_image',
+            'inspect_peer',
+            'list_peers',
+            'ping_peer',
+            'session_job',
+        ].sort())
+    })
+
     it('registers inspect_peer when included in --tools', async () => {
         await runHappyMcpStdioBridge([
             '--url',