@hwip/cli 0.1.22 → 0.1.24

package/dist/listener.js

@@ -26,8 +26,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = exports.withSettledPrompts = exports.PROMPT_SEAL_WAIT_MS = exports.withBlockedPrompts = exports.setPromptSealer = exports.deriveSessionState = exports.resetSessionStates = exports.continueRuns = exports.runIdOfEpoch = exports.__checkoutCacheSize = exports.parseSessionName = exports.resetPaneFitClaims = exports.tmuxTargetFor = exports.subagentTranscriptFor = exports.recordTargets = exports.recordSubagentTranscripts = exports.isSubagentSessionName = exports.detectRemoteAgent = exports.sessionLiveness = exports.sessionExists = exports.liveSessionNames = exports.tmuxArgs = exports.silenceListenerLog = exports.invalidateTmuxSocketCache = exports.wheelInput = exports.wheelEvents = exports.WHEEL_STATE_FORMAT = exports.resolveWheel = exports.resolveKeys = exports.probePane = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = exports.commandsReportDue = exports.commandsFingerprint = exports.COMMAND_SCAN_INTERVAL_MS = exports.sessionsReportDue = exports.sessionsFingerprint = exports.withRunSeqs = exports.staleConnectionAction = exports.askedToReconnect = exports.MAX_STALE_CONNECTION_DROPS = exports.createReportAckWatch = exports.REPORT_ACK_TIMEOUT_MS = exports.SESSION_REPORT_HEARTBEAT_MS = exports.SESSION_REPORT_INTERVAL_MS = exports.heartbeatVerdict = exports.pingDue = exports.PING_IDLE_MS = void 0;
-exports.collectSessionsVerbose = exports.handleCommandInput = exports.pendingInputDecrypts = exports.MAX_PENDING_DECRYPTS = exports.MAX_INPUT_LANES = exports.validateInputMessage = exports.MAX_INPUT_BODY_CHARS = exports.MAX_INPUT_KEYS = exports.handleStreamControl = exports.buildStreamFrame = exports.isStreamCapReached = exports.fitSealedFrame = exports.SEALED_FRAME_MAX_BYTES = exports.stopAllStreams = exports.stopStream = exports.stopStreamOf = exports.handleTurnWatch = exports.sealTurnBatch = exports.resolveWatchTranscript = exports.MAX_CONCURRENT_STREAMS = exports.STREAM_RENEW_FRESH_MS = exports.STREAM_LEASE_MS = exports.claimFrameSend = exports.hasFrameBudget = exports.streamCadence = exports.MAX_FRAMES_PER_SEC = exports.BURST_WINDOW_MS = exports.BURST_INTERVAL_MS = exports.STREAM_INTERVAL_MS = exports.STREAM_CAPTURE_LINES = exports.scheduleInjectSnapshots = exports.historyLinesIn = exports.cursorLineFor = exports.parsePaneGeometry = exports.STREAM_GEOMETRY_FORMAT = exports.handleScreenHistoryRequest = exports.SCREEN_HISTORY_MAX_LINES = exports.handleSessionForgetRequest = exports.handleSessionExitRequest = exports.SESSION_EXIT_STEP_MS = exports.handleSessionResumeRequest = exports.SHELL_START_KIND = exports.handleScheduleListRequest = exports.handleFileBlobRequest = exports.handleFileTreeRequest = exports.handleDiffFileRequest = exports.handleDiffFilesRequest = exports.fileViewBytes = exports.handleScreenRequest = exports.setSubscriberTrust = void 0;
-exports.handleListener = exports.liveScheduleRunnerDeps = exports.listenerSettings = exports.resolveWsUrl = exports.streamSession = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.displayFolder = exports.claimLanFile = exports.saveFileFromS3 = exports.downloadSealedEach = exports.answerFileBound = exports.downloadAttachments = exports.setAttachmentContext = exports.shellTextRefusal = exports.writeRemoteMarker = exports.isInventoried = exports.syncTmuxAgentNames = exports.recordInventory = void 0;
+exports.MAX_PENDING_DECRYPTS = exports.MAX_INPUT_LANES = exports.validateInputMessage = exports.MAX_INPUT_BODY_CHARS = exports.MAX_INPUT_KEYS = exports.handleStreamControl = exports.buildStreamFrame = exports.isStreamCapReached = exports.fitSealedFrame = exports.SEALED_FRAME_MAX_BYTES = exports.stopAllStreams = exports.stopStream = exports.stopStreamOf = exports.handleTurnWatch = exports.sealTurnBatch = exports.resolveWatchTranscript = exports.MAX_CONCURRENT_STREAMS = exports.STREAM_RENEW_FRESH_MS = exports.STREAM_LEASE_MS = exports.claimFrameSend = exports.hasFrameBudget = exports.streamCadence = exports.MAX_FRAMES_PER_SEC = exports.BURST_WINDOW_MS = exports.BURST_INTERVAL_MS = exports.STREAM_INTERVAL_MS = exports.STREAM_CAPTURE_LINES = exports.scheduleInjectSnapshots = exports.historyLinesIn = exports.cursorLineFor = exports.parsePaneGeometry = exports.STREAM_GEOMETRY_FORMAT = exports.handleScreenHistoryRequest = exports.SCREEN_HISTORY_MAX_LINES = exports.handleSessionForgetRequest = exports.handleSessionExitRequest = exports.SESSION_EXIT_STEP_MS = exports.handleSessionResumeRequest = exports.SHELL_START_KIND = exports.handleBackgroundTaskOutputRequest = exports.handleBackgroundTaskStopRequest = exports.handleBackgroundTasksRequest = exports.handleScheduleListRequest = exports.handleFileBlobRequest = exports.handleFileTreeRequest = exports.handleDiffFileRequest = exports.handleDiffFilesRequest = exports.fileViewBytes = exports.handleScreenRequest = exports.setSubscriberTrust = void 0;
+exports.handleListener = exports.liveScheduleRunnerDeps = exports.listenerSettings = exports.resolveWsUrl = exports.streamSession = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.displayFolder = exports.claimLanFile = exports.saveFileFromS3 = exports.downloadSealedEach = exports.answerFileBound = exports.downloadAttachments = exports.setAttachmentContext = exports.shellTextRefusal = exports.writeRemoteMarker = exports.isInventoried = exports.syncTmuxAgentNames = exports.recordInventory = exports.collectSessionsVerbose = exports.handleCommandInput = exports.pendingInputDecrypts = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -51,6 +51,10 @@ const gate_js_1 = require("./gate.js");
 const session_registry_js_1 = require("./session-registry.js");
 const remote_agents_js_1 = require("./remote-agents.js");
 const subagent_transcripts_js_1 = require("./subagent-transcripts.js");
+const background_tasks_js_1 = require("./background-tasks.js");
+const background_tasks_requests_js_1 = require("./background-tasks-requests.js");
+const background_tasks_output_js_1 = require("./background-tasks-output.js");
+const background_tasks_stop_js_1 = require("./background-tasks-stop.js");
 const transcript_tail_js_1 = require("./transcript-tail.js");
 const listener_service_js_1 = require("./listener-service.js");
 const agent_state_js_1 = require("./agent-state.js");
@@ -1429,6 +1433,232 @@ const handleScheduleListRequest = (req, send) => {
     return true;
 };
 exports.handleScheduleListRequest = handleScheduleListRequest;
+/**
+ * Answer a phone's request for the background commands a Claude session runs
+ * (`Bash` with `run_in_background`). The rows are Claude's descriptions of
+ * them, which can say what a command is for, so the answer is sealed for a key
+ * that checked out and bound to the session — never in the clear, whatever
+ * this listener's seal history. Each task is checked for a live writer on its
+ * output now, not only at the last sweep, so a dead one is not listed.
+ */
+const handleBackgroundTasksRequest = (req, send) => {
+    if (req.subtype !== 'agent.tasks.request')
+        return false;
+    if (typeof req.requestId !== 'string' || !req.requestId || req.requestId.length > MAX_REQUEST_ID_LENGTH)
+        return false;
+    if (typeof req.sessionName !== 'string' || !req.sessionName || req.sessionName.length > MAX_REQUEST_ID_LENGTH)
+        return false;
+    if (req.targetDeviceId !== (0, exports.computeListenerDeviceId)())
+        return false;
+    const { requestId, sessionName } = req;
+    const frame = {
+        subtype: 'agent.tasks.result',
+        requestId,
+        sessionName,
+        ...(typeof req.deviceId === 'string' && req.deviceId ? { targetDeviceId: req.deviceId } : {}),
+        at: new Date().toISOString(),
+    };
+    const reply = (fields) => { send({ ...frame, ...fields }); };
+    const asker = typeof req.deviceId === 'string' && /^[\w-]{1,64}$/.test(req.deviceId) ? req.deviceId : '';
+    if (!(0, exports.checkRateLimit)(`tasks:list:${asker}`)) {
+        reply({ error: 'rate_limited' });
+        return true;
+    }
+    // No key, no list: a plaintext request is refused even where screens still go out in the clear.
+    if (!asksForSeal(req)) {
+        reply({ error: 'e2ee_required' });
+        return true;
+    }
+    whenSealAdmitted(req, (phoneKey) => {
+        (0, background_tasks_requests_js_1.liveTaskRows)((0, background_tasks_js_1.backgroundTasksFor)(sessionName)?.tasks ?? [])
+            .then(async (tasks) => {
+            await (0, crypto_js_1.initDeviceCrypto)();
+            return (0, crypto_js_1.sealV2)('agent.tasks', JSON.stringify({ v: 1, requestId, at: frame.at, tasks }), phoneKey, sessionName);
+        })
+            .then((encrypted) => reply({ encrypted }))
+            .catch((err) => {
+            // A seal that fails is an error, never a plaintext list.
+            (0, listener_log_js_1.log)(`⧉ tasks ${sessionName}: seal failed (${err instanceof Error ? err.message : err})`);
+            reply({ error: 'encrypt_failed' });
+        });
+    }, (reason) => { reply({ error: reason }); });
+    return true;
+};
+exports.handleBackgroundTasksRequest = handleBackgroundTasksRequest;
+/** Task ids as Claude Code writes them (`STARTED` in background-tasks.ts). */
+const TASK_ID_PATTERN = /^[A-Za-z0-9]{1,32}$/;
+/** How far a stop request's own clock may sit from this machine's. */
+const STOP_CLOCK_SKEW_MS = 5 * 60_000;
+/**
+ * Stop requests already acted on, by phone key and request id → when. Kept for
+ * twice the skew: an envelope is taken while its own `at` is within the skew
+ * of now, and a phone clock running ahead keeps it takeable past one window
+ * from when it was acted on. In memory only: a listener restarted inside the
+ * window would take a replayed stop again, which can end only a command the
+ * session still runs, found again from this machine's own probes.
+ */
+const actedStops = new Map();
+const MAX_ACTED_STOPS = 512;
+/** True the first time a phone's request id is seen. */
+const firstStop = (key, now) => {
+    for (const [seen, at] of actedStops)
+        if (now - at > 2 * STOP_CLOCK_SKEW_MS)
+            actedStops.delete(seen);
+    if (actedStops.has(key))
+        return false;
+    if (actedStops.size >= MAX_ACTED_STOPS)
+        actedStops.delete(actedStops.keys().next().value);
+    actedStops.set(key, now);
+    return true;
+};
+/**
+ * Stop a background command a Claude session runs, for a trusted phone. The
+ * one remote path here that ends a process, so the request has to prove who
+ * sent it: it is sealed by the phone's key, which must be the asking device's
+ * trusted key, and names the request, the task and its time inside the seal.
+ * A key alone is public and proves nothing. The phone names a task by id;
+ * which process group that is, and whether it may be signalled at all, is
+ * decided on this machine (`background-tasks-stop.ts`). The answer is a status
+ * in the clear: it says nothing about the task beyond whether it was stopped.
+ */
+const handleBackgroundTaskStopRequest = (req, send) => {
+    if (req.subtype !== 'agent.task.stop.request')
+        return false;
+    if (typeof req.requestId !== 'string' || !req.requestId || req.requestId.length > MAX_REQUEST_ID_LENGTH)
+        return false;
+    if (typeof req.sessionName !== 'string' || !req.sessionName || req.sessionName.length > MAX_REQUEST_ID_LENGTH)
+        return false;
+    if (req.targetDeviceId !== (0, exports.computeListenerDeviceId)())
+        return false;
+    const { requestId, sessionName } = req;
+    const frame = {
+        subtype: 'agent.task.stop.result',
+        requestId,
+        sessionName,
+        ...(typeof req.deviceId === 'string' && req.deviceId ? { targetDeviceId: req.deviceId } : {}),
+        at: new Date().toISOString(),
+    };
+    const reply = (fields) => { send({ ...frame, ...fields }); };
+    const asker = typeof req.deviceId === 'string' && /^[\w-]{1,64}$/.test(req.deviceId) ? req.deviceId : '';
+    if (!(0, exports.checkRateLimit)(`tasks:stop:${asker}`)) {
+        reply({ error: 'rate_limited' });
+        return true;
+    }
+    if (!asksForSeal(req)) {
+        reply({ error: 'e2ee_required' });
+        return true;
+    }
+    const sealedRequest = req.encrypted;
+    if (!(0, crypto_js_1.isSealedV2)(sealedRequest)) {
+        reply({ error: 'bad_request' });
+        return true;
+    }
+    const answer = async (phoneKey) => {
+        let asked;
+        try {
+            // Untrusted until the checks below: every field is `unknown`.
+            asked = JSON.parse(await (0, crypto_js_1.openV2)('agent.task.stop', sealedRequest, phoneKey, sessionName));
+        }
+        catch {
+            return { error: 'bad_request' };
+        }
+        if (typeof asked !== 'object' || asked === null || asked.v !== 1 || asked.requestId !== requestId)
+            return { error: 'bad_request' };
+        if (typeof asked.taskId !== 'string' || !TASK_ID_PATTERN.test(asked.taskId))
+            return { error: 'bad_request' };
+        const now = Date.now();
+        const at = typeof asked.at === 'string' ? Date.parse(asked.at) : Number.NaN;
+        if (!Number.isFinite(at) || Math.abs(now - at) > STOP_CLOCK_SKEW_MS)
+            return { error: 'bad_request' };
+        // A relay that kept a sealed stop can hand it back; the seal names the request, so the second one is refused.
+        if (!firstStop(`${phoneKey}\n${requestId}`, now))
+            return { error: 'bad_request' };
+        const { taskId } = asked;
+        const running = (0, background_tasks_js_1.backgroundTasksFor)(sessionName);
+        const task = running?.tasks.find((t) => t.id === taskId);
+        if (!task || running?.panePid == null)
+            return { result: 'not_found' };
+        const result = await (0, background_tasks_stop_js_1.stopBackgroundTask)(task, running.panePid);
+        (0, listener_log_js_1.log)(`⧉ tasks ${sessionName}: stop ${taskId} → ${result}`);
+        return { result };
+    };
+    whenSealAdmitted(req, (phoneKey) => {
+        answer(phoneKey)
+            .then(reply)
+            .catch((err) => {
+            (0, listener_log_js_1.log)(`⧉ tasks ${sessionName}: stop failed (${err instanceof Error ? err.message : err})`);
+            reply({ result: 'kill_failed' });
+        });
+    }, (reason) => { reply({ error: reason }); });
+    return true;
+};
+exports.handleBackgroundTaskStopRequest = handleBackgroundTaskStopRequest;
+/**
+ * Answer a phone's request for the end of a background command's output
+ * (`readTaskOutputTail`: the last 16 KB of the file the transcript named, if
+ * it is that task's `tasks/<id>.output`). A log can hold anything a command
+ * printed, so the answer is sealed for a key that checked out and bound to
+ * the session, the request and the task — never in the clear.
+ */
+const handleBackgroundTaskOutputRequest = (req, send) => {
+    if (req.subtype !== 'agent.task.output.request')
+        return false;
+    if (typeof req.requestId !== 'string' || !req.requestId || req.requestId.length > MAX_REQUEST_ID_LENGTH)
+        return false;
+    if (typeof req.sessionName !== 'string' || !req.sessionName || req.sessionName.length > MAX_REQUEST_ID_LENGTH)
+        return false;
+    if (req.targetDeviceId !== (0, exports.computeListenerDeviceId)())
+        return false;
+    const { requestId, sessionName } = req;
+    const frame = {
+        subtype: 'agent.task.output.result',
+        requestId,
+        sessionName,
+        ...(typeof req.deviceId === 'string' && req.deviceId ? { targetDeviceId: req.deviceId } : {}),
+        at: new Date().toISOString(),
+    };
+    const reply = (fields) => { send({ ...frame, ...fields }); };
+    const asker = typeof req.deviceId === 'string' && /^[\w-]{1,64}$/.test(req.deviceId) ? req.deviceId : '';
+    if (!(0, exports.checkRateLimit)(`tasks:output:${asker}`)) {
+        reply({ error: 'rate_limited' });
+        return true;
+    }
+    if (!asksForSeal(req)) {
+        reply({ error: 'e2ee_required' });
+        return true;
+    }
+    const { taskId } = req;
+    if (typeof taskId !== 'string' || !TASK_ID_PATTERN.test(taskId)) {
+        reply({ error: 'bad_request' });
+        return true;
+    }
+    whenSealAdmitted(req, (phoneKey) => {
+        const task = (0, background_tasks_js_1.backgroundTasksFor)(sessionName)?.tasks.find((t) => t.id === taskId);
+        if (!task)
+            return reply({ error: 'not_found' });
+        const answer = async () => {
+            const tail = await (0, background_tasks_output_js_1.readTaskOutputTail)(task);
+            if ('error' in tail)
+                return { error: tail.error };
+            const body = (0, background_tasks_output_js_1.fitTaskOutputBody)({ requestId, at: frame.at, taskId }, tail, exports.SEALED_FRAME_MAX_BYTES);
+            try {
+                await (0, crypto_js_1.initDeviceCrypto)();
+                return { encrypted: await (0, crypto_js_1.sealV2)('agent.task.output', body, phoneKey, sessionName) };
+            }
+            catch (err) {
+                // A seal that fails is an error, never the output in the clear.
+                (0, listener_log_js_1.log)(`⧉ tasks ${sessionName}: output seal failed (${err instanceof Error ? err.message : err})`);
+                return { error: 'encrypt_failed' };
+            }
+        };
+        answer().then(reply, (err) => {
+            (0, listener_log_js_1.log)(`⧉ tasks ${sessionName}: output read failed (${err instanceof Error ? err.message : err})`);
+            reply({ error: 'read_failed' });
+        });
+    }, (reason) => { reply({ error: reason }); });
+    return true;
+};
+exports.handleBackgroundTaskOutputRequest = handleBackgroundTaskOutputRequest;
 /** A run id as the registry writes it: tmux `session_created`, epoch seconds. */
 const RUN_ID = /^\d{1,12}$/;
 /** The name a wrapper family counts from: `hwip-x-3` → `hwip-x`. */
@@ -3497,6 +3727,8 @@ exports.handleCommandInput = handleCommandInput;
  * viewer nothing but a re-render.
  */
 const subagentScans = new Map();
+/** Per Claude session: what its transcript says is running in the background. */
+const backgroundTaskStates = new Map();
 /**
  * Inventory pass that also records *why* each `hwip-*` session was
  * skipped. The verbose log uses the rejection notes to explain empty
@@ -3524,7 +3756,7 @@ const collectSessionsVerbose = () => {
         // Invalidate so the next cycle re-runs full discovery instead of
         // wedging the listener at "reported 0 session(s)" forever.
         (0, tmux_socket_js_1.invalidateTmuxSocketCache)();
-        return { sessions: [], rejected: [], targets: {}, subagentTranscripts: {}, recordable: {} };
+        return { sessions: [], rejected: [], targets: {}, subagentTranscripts: {}, recordable: {}, backgroundTasks: {} };
     }
     const rawLines = (list.stdout ?? '').split('\n').filter(Boolean);
     // Sanity-check that the format separator actually survived. tmux is
@@ -3587,6 +3819,7 @@ const collectSessionsVerbose = () => {
     const resumeIdOf = new Map();
     const targets = {};
     const subagentTranscripts = {};
+    const backgroundTasks = {};
     const recordable = {};
     for (const [name, group] of groups) {
         // Main pane = the lowest (window, pane) index that runs an agent.
@@ -3664,7 +3897,7 @@ const collectSessionsVerbose = () => {
         if (resumeId)
             resumeIdOf.set(name, resumeId);
         targets[name] = main.row.paneId;
-        sessions.push({
+        const mainSession = {
             name,
             attached: group.attached,
             agentKind: main.agent.kind,
@@ -3678,7 +3911,8 @@ const collectSessionsVerbose = () => {
             runId: (0, exports.runIdOfEpoch)(group.created),
             lastActivityAt: epochToIso(group.activity),
             ...(0, exports.deriveSessionState)(name, main.agent.kind, capturePaneText(name, main.row.paneId)),
-        });
+        };
+        sessions.push(mainSession);
         // Subagent panes: every OTHER pane of this session whose tty's
         // foreground process group runs a registered agent (measured:
         // pane_current_command alone says `bash` for a pi subagent — the
@@ -3740,6 +3974,15 @@ const collectSessionsVerbose = () => {
         }
         const transcriptPath = main.agent.kind === 'claude' ? mainTranscript : null;
         if (transcriptPath) {
+            // Background commands (`Bash` with run_in_background): the phone
+            // shows how many, and asks for the rows themselves sealed.
+            const tracked = backgroundTaskStates.get(name) ?? (0, background_tasks_js_1.initialBackgroundTaskState)();
+            backgroundTaskStates.set(name, tracked);
+            const tasks = (0, background_tasks_js_1.trackBackgroundTasks)(transcriptPath, tracked);
+            if (tasks.length > 0)
+                backgroundTasks[name] = { tasks, panePid: info.panePid ?? null };
+            if (tasks.length > 0)
+                mainSession.backgroundTaskCount = tasks.length;
             const scan = subagentScans.get(name) ?? (0, subagent_transcripts_js_1.initialSubagentScanState)();
             subagentScans.set(name, scan);
             const reserved = new Set(extras.map(paneNum));
@@ -3781,6 +4024,7 @@ const collectSessionsVerbose = () => {
         }
     }
     pruneToLive(subagentScans, new Set(groups.keys()));
+    pruneToLive(backgroundTaskStates, new Set(groups.keys()));
     pruneToLive(sessionStates, new Set(sessions.map((s) => s.name)));
     // An id two panes both answer to belongs to at most one of them, and the
     // sweep cannot tell which — opencode names the busiest session in the
@@ -3821,7 +4065,7 @@ const collectSessionsVerbose = () => {
         providerSessionName: s.providerSessionName,
         providerSessionNameSource: s.providerSessionNameSource,
     })));
-    return { sessions, rejected, targets, subagentTranscripts, recordable };
+    return { sessions, rejected, targets, subagentTranscripts, recordable, backgroundTasks };
 };
 exports.collectSessionsVerbose = collectSessionsVerbose;
 /**
@@ -3841,6 +4085,7 @@ const collectSessions = () => {
     // back to the (focus-following) bare session name.
     (0, tmux_pane_js_1.recordTargets)(result.targets);
     (0, tmux_pane_js_1.recordSubagentTranscripts)(result.subagentTranscripts);
+    (0, background_tasks_js_1.recordBackgroundTasks)(result.backgroundTasks);
     return result.sessions;
 };
 /** Names from the most recent inventory sweep; null until the first one lands —
@@ -5295,11 +5540,12 @@ const streamSession = (wsUrl, apiKey) => {
             }
         };
         const publishSessions = (inventory, sessions) => {
-            const { rejected, targets, subagentTranscripts, recordable } = inventory;
+            const { rejected, targets, subagentTranscripts, recordable, backgroundTasks } = inventory;
             (0, exports.recordInventory)(sessions);
             worktreeCleanup.observe(sessions.map((s) => s.name));
             (0, tmux_pane_js_1.recordTargets)(targets);
             (0, tmux_pane_js_1.recordSubagentTranscripts)(subagentTranscripts);
+            (0, background_tasks_js_1.recordBackgroundTasks)(backgroundTasks);
             turnRecorder?.observe(recordable);
             // Let the user's own status bar say what the phone says. Change-gated
             // internally, so an unchanged sweep spawns nothing.
@@ -5532,7 +5778,11 @@ const streamSession = (wsUrl, apiKey) => {
                     && !(0, exports.handleFileTreeRequest)(m.data, sendEphemeral)
                     && !(0, exports.handleFileBlobRequest)(m.data, sendEphemeral)
                     // Reading the schedules: files this machine wrote itself, sealed for the asker.
-                    && !(0, exports.handleScheduleListRequest)(m.data, sendEphemeral)) {
+                    && !(0, exports.handleScheduleListRequest)(m.data, sendEphemeral)
+                    // A session's background commands: what Claude said they are, sealed for the asker.
+                    && !(0, exports.handleBackgroundTasksRequest)(m.data, sendEphemeral)
+                    && !(0, exports.handleBackgroundTaskStopRequest)(m.data, sendEphemeral)
+                    && !(0, exports.handleBackgroundTaskOutputRequest)(m.data, sendEphemeral)) {
                     void (0, exports.handleScreenRequest)(m.data)
                         .then((reply) => { if (reply)
                         sendEphemeral(reply); })

package/dist/resume-hint.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The line `hwip cc` / `hwip pi` leaves once its tmux session has ended: the
+ * command that picks the conversation back up (`claude --resume <id>`).
+ */
+import { type RemoteAgent } from './remote-agents.js';
+import { type KnownSession } from './session-registry.js';
+export interface ResumeHintDeps {
+    recall: (name: string, agentKind: string) => KnownSession | null;
+    /** Whether tmux still has the session: a detach returns from `tmux new` as well as an exit does. */
+    alive: (name: string) => boolean;
+    cwd: string;
+}
+/**
+ * What to print after the tmux session `session` of `agent` returned, or null
+ * when there is nothing true to say. `since` is when this `hwip` launched (ms):
+ * a record the sweep has not touched since is an earlier run of the same name,
+ * whose conversation is not the one just closed. A session shorter than one
+ * sweep has no record yet, and gets no line rather than a guess.
+ */
+export declare const resumeHint: (session: string, agent: Pick<RemoteAgent, "kind" | "binary" | "subcommands" | "resumeArgs">, since: number, deps?: ResumeHintDeps) => string | null;
+/**
+ * `hwip resume-hint --session <tmux name> --type <agent kind> --at <ms>` — the
+ * call `withResumeHint` leaves after tmux. Not for people: it always exits 0,
+ * so a missing record or a failed read never changes the agent's exit status.
+ */
+export declare const handleResumeHint: (args: Record<string, string | boolean>) => number;
+//# sourceMappingURL=resume-hint.d.ts.map

package/dist/resume-hint.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * The line `hwip cc` / `hwip pi` leaves once its tmux session has ended: the
+ * command that picks the conversation back up (`claude --resume <id>`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleResumeHint = exports.resumeHint = void 0;
+const remote_agents_js_1 = require("./remote-agents.js");
+const session_registry_js_1 = require("./session-registry.js");
+const tmux_liveness_js_1 = require("./tmux-liveness.js");
+const wrapper_js_1 = require("./wrapper.js");
+const defaultDeps = () => ({
+    recall: (name, kind) => (0, session_registry_js_1.recallRun)(name, kind),
+    // `unknown` included: no tmux server answering after `tmux new` returned is the last session gone with it.
+    alive: (name) => (0, tmux_liveness_js_1.sessionLiveness)(name) === 'running',
+    cwd: process.cwd(),
+});
+/**
+ * What to print after the tmux session `session` of `agent` returned, or null
+ * when there is nothing true to say. `since` is when this `hwip` launched (ms):
+ * a record the sweep has not touched since is an earlier run of the same name,
+ * whose conversation is not the one just closed. A session shorter than one
+ * sweep has no record yet, and gets no line rather than a guess.
+ */
+const resumeHint = (session, agent, since, deps = defaultDeps()) => {
+    if (!agent.resumeArgs || deps.alive(session))
+        return null;
+    const run = deps.recall(session, agent.kind);
+    if (!run?.agentSessionId || Date.parse(run.lastSeenAt) < since)
+        return null;
+    const args = agent.resumeArgs(run.agentSessionId, run.cwd);
+    if (!args)
+        return null;
+    const where = run.cwd === deps.cwd ? '' : ` in ${(0, wrapper_js_1.shellQuote)(run.cwd)}`;
+    const rest = args.map(wrapper_js_1.shellQuote).join(' ');
+    return `hwip: to resume${where}: ${agent.binary} ${rest}  (or hwip ${agent.subcommands[0]} ${rest})`;
+};
+exports.resumeHint = resumeHint;
+/**
+ * `hwip resume-hint --session <tmux name> --type <agent kind> --at <ms>` — the
+ * call `withResumeHint` leaves after tmux. Not for people: it always exits 0,
+ * so a missing record or a failed read never changes the agent's exit status.
+ */
+const handleResumeHint = (args) => {
+    const agent = remote_agents_js_1.REMOTE_AGENTS.find((a) => a.kind === args.type);
+    const since = Number(args.at);
+    if (typeof args.session !== 'string' || !agent || !Number.isFinite(since))
+        return 0;
+    try {
+        const line = (0, exports.resumeHint)(args.session, agent, since);
+        if (line)
+            console.log(line);
+    }
+    catch {
+        return 0;
+    }
+    return 0;
+};
+exports.handleResumeHint = handleResumeHint;

package/dist/subagent-transcripts.d.ts

@@ -150,6 +150,11 @@ export declare const subagentDirFor: (parentTranscriptPath: string) => string;
  * cares about the second.
  */
 export declare const isSubagentTranscriptPath: (transcriptPath: string) => boolean;
+/** The four ways Claude Code reports a background subagent stopping — measured
+ *  2026-09-14 over every parent transcript on this machine (787 completed, 12
+ *  failed, 12 killed, 2 stopped, nothing else). */
+export declare const TASK_END: RegExp;
+export declare const TASK_ID: RegExp;
 /**
  * The live subagents of one Claude Code session, in chip order (by number).
  *

package/dist/subagent-transcripts.js

@@ -23,7 +23,7 @@
  * the alternative failure is this feature vanishing in silence.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scanSubagents = exports.isSubagentTranscriptPath = exports.subagentDirFor = exports.initialSubagentScanState = exports.MAX_SUBAGENT_ROWS = exports.SUBAGENT_STALE_RECHECK_MS = exports.SUBAGENT_CATCH_UP_BYTES = exports.SUBAGENT_END_SLACK_MS = exports.SUBAGENT_ADDRESSABLE_MS = exports.SUBAGENT_LIVE_MS = exports.SUBAGENT_WORKING_MS = void 0;
+exports.scanSubagents = exports.TASK_ID = exports.TASK_END = exports.isSubagentTranscriptPath = exports.subagentDirFor = exports.initialSubagentScanState = exports.MAX_SUBAGENT_ROWS = exports.SUBAGENT_STALE_RECHECK_MS = exports.SUBAGENT_CATCH_UP_BYTES = exports.SUBAGENT_END_SLACK_MS = exports.SUBAGENT_ADDRESSABLE_MS = exports.SUBAGENT_LIVE_MS = exports.SUBAGENT_WORKING_MS = void 0;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const transcript_tail_js_1 = require("./transcript-tail.js");
@@ -147,8 +147,8 @@ const isAgentToolUse = (line) => {
 /** The four ways Claude Code reports a background subagent stopping — measured
  *  2026-09-14 over every parent transcript on this machine (787 completed, 12
  *  failed, 12 killed, 2 stopped, nothing else). */
-const TASK_END = /<status>(?:completed|failed|killed|stopped)<\/status>/;
-const TASK_ID = /<task-id>([^<]{1,200})<\/task-id>/;
+exports.TASK_END = /<status>(?:completed|failed|killed|stopped)<\/status>/;
+exports.TASK_ID = /<task-id>([^<]{1,200})<\/task-id>/;
 /**
  * The subagent a parent line says has ended, and when — or null.
  *
@@ -182,9 +182,9 @@ const subagentEndOf = (line) => {
     if (result?.status === 'completed' && typeof result.agentId === 'string')
         return { agentId: result.agentId, at };
     const content = entry.message?.content;
-    if (entry.origin?.kind !== 'task-notification' || typeof content !== 'string' || !TASK_END.test(content))
+    if (entry.origin?.kind !== 'task-notification' || typeof content !== 'string' || !exports.TASK_END.test(content))
         return null;
-    const agentId = TASK_ID.exec(content)?.[1];
+    const agentId = exports.TASK_ID.exec(content)?.[1];
     return agentId ? { agentId, at } : null;
 };
 /**

package/dist/wrapper.d.ts

@@ -121,7 +121,18 @@ export declare const splitAgentOptions: (extra: string[]) => {
     rest: string[];
     error?: string;
 };
+export declare const shellQuote: (s: string) => string;
 export declare const targetForAgent: (agent: string, extra: string[], agentKind?: string, opts?: AgentLaunchOptions) => SpawnTarget;
+/**
+ * `target` (an attached `tmux new`) run under `sh`, which outlives tmux by the
+ * one `hwip resume-hint` call and then exits with tmux's status. `sh` rather
+ * than this process waiting: the wrapper hands itself over with execve so no
+ * node heap sits resident for the whole session, and `sh` costs next to none.
+ */
+export declare const withResumeHint: (target: SpawnTarget, agent: Pick<RemoteAgent, "kind" | "resumeArgs">, since: number, hwip?: {
+    node: string;
+    cli: string;
+}) => SpawnTarget;
 /**
  * Whether the daemon on record is running a different build than the one
  * we're launching from. `npm i -g @hwip/cli` swaps dist/ but leaves the

package/dist/wrapper.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleShellSession = exports.startShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.targetForAgent = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.familyNames = exports.firstFreeSession = exports.tmuxSessionName = exports.installedTmuxVersion = exports.agentLaunchArgs = exports.agentLaunchEnv = exports.herdrEnvArgs = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
+exports.handleShellSession = exports.startShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.withResumeHint = exports.targetForAgent = exports.shellQuote = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.familyNames = exports.firstFreeSession = exports.tmuxSessionName = exports.installedTmuxVersion = exports.agentLaunchArgs = exports.agentLaunchEnv = exports.herdrEnvArgs = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
 /**
  * `hwip cc` / `hwip codex` / `hwip gemini` — spawn an agent inside a named
  * tmux session so the resident listener (`hwip listener`) can address it
@@ -331,6 +331,7 @@ exports.splitAgentOptions = splitAgentOptions;
 /** POSIX shell-quote so passthrough args survive being joined into a tmux shell-command string. */
 const SHELL_SAFE = /^[\w\-./=:@%+,]+$/;
 const shellQuote = (s) => s.length > 0 && SHELL_SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+exports.shellQuote = shellQuote;
 const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     // Already inside tmux → no nested session, just run the agent in the
     // current pane. Nested tmux prefix collisions are confusing and the
@@ -364,7 +365,7 @@ const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     // tmux joins trailing argv into a single shell-command, so flags like
     // `--resume` would be eaten by tmux's own parser. Build one quoted
     // shell string instead, which tmux passes through verbatim.
-    const shellCmd = [agent, ...extra].map(shellQuote).join(' ');
+    const shellCmd = [agent, ...extra].map(exports.shellQuote).join(' ');
     // `-d`: create without attaching, so no TTY is needed and `new` fails
     // loudly on a taken name instead of `-A` silently attaching to whatever
     // runs there. `-c`: the agent's cwd must be the directory the session is
@@ -383,6 +384,22 @@ const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     return { kind: 'tmux-new', cmd: 'tmux', args: ['new', '-A', '-s', session, ...herdrEnv, ...agentEnv, shellCmd, ...sidecar, ...(0, exports.herdrSessionArgs)(session)], session };
 };
 exports.targetForAgent = targetForAgent;
+/**
+ * `target` (an attached `tmux new`) run under `sh`, which outlives tmux by the
+ * one `hwip resume-hint` call and then exits with tmux's status. `sh` rather
+ * than this process waiting: the wrapper hands itself over with execve so no
+ * node heap sits resident for the whole session, and `sh` costs next to none.
+ */
+const withResumeHint = (target, agent, since, hwip = { node: process.execPath, cli: process.argv[1] ?? '' }) => {
+    if (target.kind !== 'tmux-new' || !target.session || !agent.resumeArgs || !hwip.cli)
+        return target;
+    const hint = [hwip.node, hwip.cli, 'resume-hint', '--session', target.session, '--type', agent.kind, '--at', String(since)]
+        .map(exports.shellQuote)
+        .join(' ');
+    const script = `tmux "$@"; s=$?; ${hint} || :; exit $s`;
+    return { ...target, cmd: 'sh', args: ['-c', script, 'sh', ...target.args] };
+};
+exports.withResumeHint = withResumeHint;
 // ── Background listener auto-start ────────────────────────────────────
 /**
  * Whether the daemon on record is running a different build than the one
@@ -444,6 +461,15 @@ const ensureListenerRunning = async (launchedByListener = (0, exports.takeListen
         }
         if (reportFailedStart(await (0, listener_process_js_1.awaitServiceListener)(logOffset, pid)))
             return;
+        // The service starts whatever install it was registered from, which
+        // need not be this one (`hwip` from Homebrew, the plist from an nvm
+        // node). Restarting it brings the same old build back, and every
+        // `hwip cc` after would restart it again without ever saying why.
+        const restarted = (0, listener_process_js_1.runningListenerVersion)();
+        if ((0, exports.listenerVersionDrifted)(restarted, config_js_1.VERSION)) {
+            console.error(staleServiceNote(restarted, (0, listener_service_js_1.serviceStatus)().cliPath));
+            return;
+        }
         if (pid === null)
             console.log(`hwip: listener started by ${owner} (log: ${listener_process_js_1.LISTENER_LOG_FILE})`);
         else
@@ -474,6 +500,10 @@ const ensureListenerRunning = async (launchedByListener = (0, exports.takeListen
     }
 };
 exports.ensureListenerRunning = ensureListenerRunning;
+/** What to say when the login service came back on an older install than this one. */
+const staleServiceNote = (running, serviceCli) => `hwip: the login service restarted the listener on ${running ?? 'an unstamped build'}, not ${config_js_1.VERSION} — ` +
+    `it runs ${serviceCli ?? 'another install'}.\n` +
+    '      Point it at this install: hwip listener --install-service';
 /** Say why a just-started listener is not running; true when it said anything. */
 const reportFailedStart = (started) => {
     const why = (0, listener_process_js_1.startFailure)(started);
@@ -558,6 +588,8 @@ const tmuxMissing = (command) => (0, exports.tmuxMissingMessage)(command, (0, tm
 const handleAgentSession = async (agent, extra = [], opts = {}, deps = {}) => {
     // First of all, before `ensureWorktree` runs git (its hooks would inherit the marker).
     const launchedByListener = (0, exports.takeListenerLaunchMarker)();
+    // The resume hint trusts only a registry record the sweep wrote after this.
+    const launchedAt = Date.now();
     // Best-effort: make sure the phone-bridge daemon is running, and running
     // the build we were launched from. The user shouldn't need to remember a
     // second command for the picker on their phone to work.
@@ -609,7 +641,8 @@ const handleAgentSession = async (agent, extra = [], opts = {}, deps = {}) => {
             return 1;
         }
     }
-    return (deps.launch ?? launchTarget)({ kind, cmd, args, session, env }, agent.binary);
+    const target = { kind, cmd, args, session, env };
+    return (deps.launch ?? launchTarget)((0, exports.withResumeHint)(target, agent, launchedAt), agent.binary);
 };
 exports.handleAgentSession = handleAgentSession;
 /**
@@ -666,7 +699,7 @@ const launchTarget = async ({ kind, cmd, args, session, env: agentEnv }, what) =
             // someone whose agent died inside a perfectly good pane to "run
             // from a plain shell pane" would send them after the wrong thing.
             if (kind === 'tmux-new' && code && code !== 0 && dur < 2000) {
-                console.error(`hwip: ${cmd} ${args.join(' ')} exited ${code} after ${dur}ms.\n` +
+                console.error(`hwip: tmux exited ${code} after ${dur}ms.\n` +
                     `  If this terminal is itself inside tmux (or an iTerm/Warp\n` +
                     `  tmux-integration pane), run \`hwip cc\` from a plain shell\n` +
                     `  pane instead — \`tmux new\` needs a real TTY to attach.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hwip/cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Hwip CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",