@hwip/cli 0.1.23 → 0.1.24

package/README.md

@@ -877,6 +877,19 @@ The phone also reads this machine's schedules (see [Scheduled sessions](#schedul
 
 `schedules` is the list as a JSON string; `encrypted` is the list sealed for the asking device (purpose `schedule.list`, bound to this machine's device id) as `{ v: 1, requestId, at, schedules: [...], unreadable? }` — the app checks that the `requestId` inside is the one it asked, so an older sealed list is not taken for a newer answer. `unreadable` is how many schedule files could not be read; a directory that cannot be listed at all, or that holds more than 20 files, is the error `read_failed`, never an empty list (and a remove then fails as `schedule_failed`; `hwip schedule rm` still works on the computer). A list too long for one frame has its prompts shortened, step by step (`too_large` only when it does not fit even without them). Each entry holds `id`, `source`, `agentKind`, `project` (the directory's name, not its path), `session`, `when`, `prompt` (cut to 500 characters, shorter when the list would not fit; `promptLocked: true` says the phone cannot change it — it is not the whole text, or the schedule has agent arguments — so the app leaves it to `hwip schedule edit`), `maxRuntimeMin`, `nextAt` and the `last` result — never a directory path or the agent's arguments. `when` is `{ kind: 'daily', at, days }`, `{ kind: 'every', minutes }` or `{ kind: 'once', at }` (an ISO 8601 instant). A schedule into a session also holds `target: 'session'` and the `runId` it types into, and `sessionEnded: true` when that run is over (absent while it runs, or when tmux could not say). `last.outcome` may be `session_busy` or `session_ended` for those.
 
+Background commands a Claude session runs (`Bash` with `run_in_background`) are read off its transcript. The session report carries only their number, `backgroundTaskCount`; the phone asks for the rest:
+
+```
+{ subtype: 'agent.tasks.request',      targetDeviceId, sessionName, requestId, subscriberPublicKey }
+{ subtype: 'agent.tasks.result',       requestId, sessionName, at, encrypted | error }
+{ subtype: 'agent.task.output.request', targetDeviceId, sessionName, requestId, taskId, subscriberPublicKey }
+{ subtype: 'agent.task.output.result',  requestId, sessionName, at, encrypted | error }
+{ subtype: 'agent.task.stop.request',  targetDeviceId, sessionName, requestId, subscriberPublicKey, encrypted }
+{ subtype: 'agent.task.stop.result',   requestId, sessionName, at, result | error }
+```
+
+The list is sealed for the asking device (purpose `agent.tasks`, bound to the session) as `{ v: 1, requestId, at, tasks: [{ id, description, startedAt }] }` — Claude's description of each command, never the command line or where its output goes, and only commands whose output some process still writes (`lsof`). The end of one command's output is sealed the same way (purpose `agent.task.output`) as `{ v: 1, requestId, at, taskId, text, size, truncated }`: the last 16 KB of the file the transcript named, cut to whole characters and from the top again when the sealed frame would pass 20 KB (a coloured log's escape codes grow six-fold in JSON), read only when its real path is a `tasks/<taskId>.output` file with no other name (a symlink out of there, a hard link, a directory or another task's file is `path_refused`; a task this session does not run, or a file that is gone, is `not_found`; `read_failed` and `encrypt_failed` say what broke). A stop request seals `{ v: 1, requestId, taskId, at }` for this machine (purpose `agent.task.stop`). The listener finds the process group to signal on its own: the one group whose leader writes the task's output file and descends from the session's pane, never this listener's group, the pane's foreground group (Claude itself) or one between the leader and the pane. It sends that group `SIGTERM` and answers `result: 'stopped'`; otherwise it signals nothing and answers `not_found` (nobody writes the output, or the command left its group), `ambiguous` (more than one group qualifies), `refused` (a group a stop never ends, or an output that is not the task's own `tasks/<taskId>.output` file) or `kill_failed`. Claude then writes the task's end, and the count drops on the next report. Errors are `e2ee_required` (no key), `subscriber_unverified`, `bad_request` (an envelope that does not open, a mismatch, a stale or repeated request, a task id that is not one) and `rate_limited`.
+
 ### Your API key and redirects
 
 Every request that carries your API key refuses to follow a redirect: a host
@@ -1012,7 +1025,8 @@ handing the listener a key:
   inside envelope v2: ECDH P-256 between the two device keys, HKDF-SHA256
   with a fresh salt and the message's purpose (`stream.frame`,
   `stream.input`, `stream.alive`, `stream.started`, `screen.snapshot`,
-  `screen.history`, `session.diff`, `schedule.list`, `turn.batch`) as the key's info, and
+  `screen.history`, `session.diff`, `schedule.list`, `agent.tasks`,
+  `agent.task.output`, `agent.task.stop`, `turn.batch`) as the key's info, and
   AES-256-GCM over data that names the purpose, both keys in send →
   receive order and the session. The sealed frame also holds the
   session name, its `seq`/`epoch` and that nonce, so a relay that cannot
@@ -1083,6 +1097,16 @@ request without a key while this listener pins no device, and otherwise an
 error code (`e2ee_required`, `subscriber_unverified`, …) and no schedule. Prompts are in
 it, so a request that asked for a seal is never answered in the clear.
 
+A Claude session's background commands — the answer to `agent.tasks.request`,
+and the end of one's output for `agent.task.output.request` — are sealed for a
+key that checked out, always: there is no plaintext answer,
+pinned devices or not. Stopping one (`agent.task.stop.request`) ends a
+process, so the request itself is sealed by the phone's key (purpose
+`agent.task.stop`, bound to the session) and that key has to be the asking
+device's trusted one; the request id, task id and time inside the seal must
+match the frame, sit within five minutes of this machine's clock, and not have
+been acted on before.
+
 **Reading a session's changes** (`agent.diff.files.request` and
 `agent.diff.file.request`) is sealed both ways and never answered in the
 clear: a request without a key gets `e2ee_required` whether or not this

package/dist/background-tasks-output.d.ts

@@ -0,0 +1,28 @@
+import type { BackgroundTask } from './background-tasks.js';
+/** How much of the end of an output the phone sees: a few screens of a log. */
+export declare const TASK_OUTPUT_TAIL_BYTES: number;
+/** Whether `path` names this task's own output file: `…/tasks/<id>.output`. */
+export declare const isTaskOutputPath: (path: string, taskId: string) => boolean;
+export type TaskOutputTail = {
+    readonly text: string;
+    readonly size: number;
+    readonly truncated: boolean;
+} | {
+    readonly error: 'not_found' | 'path_refused' | 'read_failed';
+};
+export declare const readTaskOutputTail: (task: BackgroundTask, limit?: number) => Promise<TaskOutputTail>;
+/**
+ * The sealed answer's body, with `text` cut from the top until the JSON fits
+ * `maxBytes`. JSON writes each ESC byte of a coloured log as `\\u001b`, six
+ * bytes, so 16 KB of output can come to far more than a frame holds.
+ */
+export declare const fitTaskOutputBody: (head: {
+    readonly requestId: string;
+    readonly at: string;
+    readonly taskId: string;
+}, tail: {
+    readonly text: string;
+    readonly size: number;
+    readonly truncated: boolean;
+}, maxBytes: number) => string;
+//# sourceMappingURL=background-tasks-output.d.ts.map

package/dist/background-tasks-output.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fitTaskOutputBody = exports.readTaskOutputTail = exports.isTaskOutputPath = exports.TASK_OUTPUT_TAIL_BYTES = void 0;
+/**
+ * The end of a background command's output, for the phone
+ * (`agent.task.output.request`, handled in listener.ts).
+ *
+ * The phone names a task by id and never a path. The file is the one the
+ * transcript said the task writes, and is read only when its real path is a
+ * `tasks/<id>.output` file for that same id — a transcript line that names
+ * some other file, a symlink planted where the output should be, or a hard
+ * link to some other file, reads nothing.
+ */
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+/** How much of the end of an output the phone sees: a few screens of a log. */
+exports.TASK_OUTPUT_TAIL_BYTES = 16 * 1024;
+/** Whether `path` names this task's own output file: `…/tasks/<id>.output`. */
+const isTaskOutputPath = (path, taskId) => (0, node_path_1.basename)(path) === `${taskId}.output` && (0, node_path_1.basename)((0, node_path_1.dirname)(path)) === 'tasks';
+exports.isTaskOutputPath = isTaskOutputPath;
+/** Where a cut from the end lands inside a UTF-8 character: skip its continuation bytes. */
+const wholeCharacterStart = (bytes) => {
+    let start = 0;
+    while (start < bytes.length && start < 4 && (bytes[start] & 0xc0) === 0x80)
+        start++;
+    return start;
+};
+/** Where a read ends inside a UTF-8 character a running command has not finished writing: drop that character. */
+const wholeCharacterEnd = (bytes) => {
+    for (let back = 1; back <= Math.min(4, bytes.length); back++) {
+        const byte = bytes[bytes.length - back];
+        if ((byte & 0xc0) === 0x80)
+            continue;
+        const width = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+        return width > back ? bytes.length - back : bytes.length;
+    }
+    return bytes.length;
+};
+const readTaskOutputTail = async (task, limit = exports.TASK_OUTPUT_TAIL_BYTES) => {
+    let real;
+    try {
+        real = await (0, promises_1.realpath)(task.outputPath);
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? { error: 'not_found' } : { error: 'read_failed' };
+    }
+    if (!(0, exports.isTaskOutputPath)(real, task.id))
+        return { error: 'path_refused' };
+    let checked;
+    let handle;
+    try {
+        checked = await (0, promises_1.lstat)(real);
+        handle = await (0, promises_1.open)(real, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW);
+    }
+    catch (err) {
+        const code = err.code;
+        return code === 'ENOENT' ? { error: 'not_found' } : code === 'ELOOP' ? { error: 'path_refused' } : { error: 'read_failed' };
+    }
+    try {
+        const stat = await handle.stat();
+        // The file opened must be the one checked (a directory on the way swapped for a symlink opens another), a plain
+        // file, and have no other name: a hard link to a secret has the output's real path too.
+        if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== checked.dev || stat.ino !== checked.ino)
+            return { error: 'path_refused' };
+        const size = stat.size;
+        const length = Math.min(size, limit);
+        const bytes = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(bytes, 0, length, size - length);
+        const read = bytes.subarray(0, bytesRead);
+        const truncated = size > length;
+        const whole = read.subarray(0, wholeCharacterEnd(read));
+        const text = (truncated ? whole.subarray(wholeCharacterStart(whole)) : whole).toString('utf8');
+        return { text, size, truncated };
+    }
+    catch {
+        return { error: 'read_failed' };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+exports.readTaskOutputTail = readTaskOutputTail;
+/**
+ * The sealed answer's body, with `text` cut from the top until the JSON fits
+ * `maxBytes`. JSON writes each ESC byte of a coloured log as `\\u001b`, six
+ * bytes, so 16 KB of output can come to far more than a frame holds.
+ */
+const fitTaskOutputBody = (head, tail, maxBytes) => {
+    let { text, truncated } = tail;
+    let body = JSON.stringify({ v: 1, ...head, text, size: tail.size, truncated });
+    let bytes = Buffer.byteLength(body);
+    while (bytes > maxBytes && text.length > 0) {
+        // Cut about the share that is over, at the next line break; one runaway line loses its first half.
+        const from = Math.floor(text.length * (1 - maxBytes / bytes));
+        const cut = text.indexOf('\n', from);
+        let start = cut === -1 ? Math.max(from, Math.ceil(text.length / 2)) : cut + 1;
+        if (/[\uDC00-\uDFFF]/.test(text.charAt(start)))
+            start += 1;
+        text = text.slice(start);
+        truncated = true;
+        body = JSON.stringify({ v: 1, ...head, text, size: tail.size, truncated });
+        bytes = Buffer.byteLength(body);
+    }
+    return body;
+};
+exports.fitTaskOutputBody = fitTaskOutputBody;

package/dist/background-tasks-requests.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What the phone is told about a Claude session's background commands when it
+ * asks (`agent.tasks.request`). The handler that admits the request and seals
+ * the answer is `handleBackgroundTasksRequest` in listener.ts, beside the
+ * other sealed requests; this is what it answers with.
+ */
+import { type AsyncWriterProbe, type BackgroundTask } from './background-tasks.js';
+/** One row as the phone sees it. The output path stays on this machine: the phone names a task by id. */
+export interface TaskRow {
+    readonly id: string;
+    readonly description: string | null;
+    readonly startedAt: string | null;
+}
+/**
+ * The tasks whose output some process still writes, asked once for all of
+ * them. A probe that cannot answer keeps every task: not knowing is not dead.
+ * The sweep's own check runs at most every 15 s; this one runs on every
+ * request, so a phone opening the list never sees a task that died since.
+ * Asynchronous: it runs on the main thread, which serves the socket.
+ */
+export declare const liveTaskRows: (tasks: readonly BackgroundTask[], probe?: AsyncWriterProbe) => Promise<TaskRow[]>;
+//# sourceMappingURL=background-tasks-requests.d.ts.map

package/dist/background-tasks-requests.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveTaskRows = void 0;
+/**
+ * What the phone is told about a Claude session's background commands when it
+ * asks (`agent.tasks.request`). The handler that admits the request and seals
+ * the answer is `handleBackgroundTasksRequest` in listener.ts, beside the
+ * other sealed requests; this is what it answers with.
+ */
+const background_tasks_js_1 = require("./background-tasks.js");
+/**
+ * The tasks whose output some process still writes, asked once for all of
+ * them. A probe that cannot answer keeps every task: not knowing is not dead.
+ * The sweep's own check runs at most every 15 s; this one runs on every
+ * request, so a phone opening the list never sees a task that died since.
+ * Asynchronous: it runs on the main thread, which serves the socket.
+ */
+const liveTaskRows = async (tasks, probe = background_tasks_js_1.lsofWritersAsync) => {
+    if (tasks.length === 0)
+        return [];
+    const open = await probe(tasks.map((t) => t.outputPath));
+    return tasks
+        .filter((t) => !open || open.has(t.outputPath))
+        .map(({ id, description, startedAt }) => ({ id, description, startedAt }));
+};
+exports.liveTaskRows = liveTaskRows;

package/dist/background-tasks-stop.d.ts

@@ -0,0 +1,43 @@
+import { type BackgroundTask } from './background-tasks.js';
+import { type ProcTable } from './remote-agents.js';
+/** What a stop found. Only `group` is ever signalled. */
+export type StopTarget = {
+    readonly kind: 'group';
+    readonly pgid: number;
+}
+/** Nobody writes the output, no writer leads a group under the pane, or `lsof`/`ps` could not say. */
+ | {
+    readonly kind: 'not_found';
+}
+/** More than one group qualifies: which one the task is cannot be told. */
+ | {
+    readonly kind: 'ambiguous';
+}
+/** The group is one a stop must never signal: this listener's, the pane shell's, claude's, or the system's. */
+ | {
+    readonly kind: 'refused';
+};
+export type StopOutcome = 'stopped' | 'not_found' | 'ambiguous' | 'refused' | 'kill_failed';
+export interface StopProbes {
+    /** Pids with the file open (lsof does not tell a reader from a writer), or null when that cannot be told. */
+    readonly writerPids: (path: string) => Promise<readonly number[] | null>;
+    readonly procTable: () => Promise<ProcTable | null>;
+    /** This listener's pid, whose group is never signalled. */
+    readonly selfPid: number;
+}
+export declare const defaultStopProbes: StopProbes;
+/**
+ * The process group that runs the task writing `outputPath` under the pane
+ * whose shell is `panePid`: the group of a writer whose LEADER is a writer too
+ * and descends from the pane. A group a stop must never end — this listener's,
+ * the pane's foreground group (claude's), or any on the way from the leader up
+ * to the pane — is refused even when it qualifies.
+ */
+export declare const findTaskProcessGroup: (outputPath: string, panePid: number, probes?: StopProbes) => Promise<StopTarget>;
+export interface StopDeps {
+    readonly probes?: StopProbes;
+    readonly kill?: (pid: number, signal: NodeJS.Signals) => void;
+}
+/** Find the task's process group and send it SIGTERM — the group, so the command's children end with it. */
+export declare const stopBackgroundTask: (task: BackgroundTask, panePid: number, deps?: StopDeps) => Promise<StopOutcome>;
+//# sourceMappingURL=background-tasks-stop.d.ts.map

package/dist/background-tasks-stop.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stopBackgroundTask = exports.findTaskProcessGroup = exports.defaultStopProbes = void 0;
+/**
+ * Stopping a background command a Claude session runs, for the phone's Stop
+ * (`agent.task.stop.request`, handled in listener.ts).
+ *
+ * The phone names a task by id; nothing it sends says which process to
+ * signal. The target is found here, from this machine's own answers, and only
+ * when every one agrees. Measured 2026-11-11 (Claude Code 2.x): Claude starts
+ * each background command under a wrapper shell that leads its own process
+ * group, as a child of `claude`; `lsof` on the task's output file names the
+ * wrapper and its children; `kill -TERM -<pgid>` ends the whole tree, and
+ * Claude then writes the task's `<task-notification>` with status `failed`.
+ *
+ * So the target is the one process group whose leader writes the output and
+ * descends from the session's pane. Anything less certain signals nothing.
+ */
+const promises_1 = require("node:fs/promises");
+const background_tasks_output_js_1 = require("./background-tasks-output.js");
+const background_tasks_js_1 = require("./background-tasks.js");
+const remote_agents_js_1 = require("./remote-agents.js");
+/** Deepest ancestor chain walked from a group leader up to the pane. */
+const MAX_ANCESTRY = 64;
+/** `lsof -t -- <path>`: one pid per line. Exit 1 is "open nowhere", still an answer. */
+const lsofPids = async (path) => {
+    const bin = (0, background_tasks_js_1.lsofBin)();
+    if (!bin)
+        return null;
+    const out = await (0, background_tasks_js_1.runProbe)(bin, ['-t', '--', path], [1]);
+    if (out === null)
+        return null;
+    return out.split('\n').map(Number).filter((pid) => Number.isInteger(pid) && pid > 0);
+};
+const psTable = async () => {
+    const out = await (0, background_tasks_js_1.runProbe)('ps', ['-axo', 'pid=,ppid=,pgid=,tpgid=,comm='], []);
+    return out === null ? null : (0, remote_agents_js_1.parseProcTable)(out);
+};
+exports.defaultStopProbes = { writerPids: lsofPids, procTable: psTable, selfPid: process.pid };
+const parentsOf = (table) => {
+    const parentOf = new Map();
+    for (const [ppid, kids] of table.children)
+        for (const pid of kids)
+            parentOf.set(pid, ppid);
+    return parentOf;
+};
+/**
+ * The processes from `leader`'s parent up to and including `panePid`, or null
+ * when the pane is not an ancestor of the leader.
+ */
+const chainToPane = (leader, panePid, parentOf) => {
+    const chain = [];
+    let pid = parentOf.get(leader);
+    for (let hop = 0; pid !== undefined && pid > 0 && hop < MAX_ANCESTRY; hop++) {
+        chain.push(pid);
+        if (pid === panePid)
+            return chain;
+        pid = parentOf.get(pid);
+    }
+    return null;
+};
+/**
+ * The process group that runs the task writing `outputPath` under the pane
+ * whose shell is `panePid`: the group of a writer whose LEADER is a writer too
+ * and descends from the pane. A group a stop must never end — this listener's,
+ * the pane's foreground group (claude's), or any on the way from the leader up
+ * to the pane — is refused even when it qualifies.
+ */
+const findTaskProcessGroup = async (outputPath, panePid, probes = exports.defaultStopProbes) => {
+    if (!Number.isInteger(panePid) || panePid <= 1)
+        return { kind: 'not_found' };
+    const [writers, table] = await Promise.all([probes.writerPids(outputPath), probes.procTable()]);
+    if (!writers || writers.length === 0 || !table)
+        return { kind: 'not_found' };
+    const writing = new Set(writers);
+    const parentOf = parentsOf(table);
+    const forbidden = new Set();
+    // This listener's group, the pane shell's, and the pane's foreground group:
+    // the program the user sees in the pane (claude), which background
+    // commands never lead.
+    for (const group of [table.pgidOf.get(probes.selfPid), table.pgidOf.get(panePid), table.tpgidOf.get(panePid)]) {
+        if (group !== undefined)
+            forbidden.add(group);
+    }
+    const candidates = new Set();
+    for (const pid of writing) {
+        const pgid = table.pgidOf.get(pid);
+        if (pgid === undefined || !writing.has(pgid))
+            continue;
+        const chain = chainToPane(pgid, panePid, parentOf);
+        if (!chain)
+            continue;
+        for (const up of chain) {
+            const upGroup = table.pgidOf.get(up);
+            if (upGroup !== undefined)
+                forbidden.add(upGroup);
+        }
+        candidates.add(pgid);
+    }
+    if (candidates.size === 0)
+        return { kind: 'not_found' };
+    if (candidates.size > 1)
+        return { kind: 'ambiguous' };
+    const pgid = candidates.values().next().value;
+    if (pgid <= 1 || forbidden.has(pgid))
+        return { kind: 'refused' };
+    return { kind: 'group', pgid };
+};
+exports.findTaskProcessGroup = findTaskProcessGroup;
+/** Find the task's process group and send it SIGTERM — the group, so the command's children end with it. */
+const stopBackgroundTask = async (task, panePid, deps = {}) => {
+    // Only the task's own output file says who runs it: a transcript line naming another file points at whoever has that
+    // open. A file already gone keeps its name, and lsof then finds nobody.
+    const real = await (0, promises_1.realpath)(task.outputPath).catch(() => task.outputPath);
+    if (!(0, background_tasks_output_js_1.isTaskOutputPath)(real, task.id))
+        return 'refused';
+    const target = await (0, exports.findTaskProcessGroup)(task.outputPath, panePid, deps.probes ?? exports.defaultStopProbes);
+    if (target.kind !== 'group')
+        return target.kind;
+    try {
+        (deps.kill ?? process.kill)(-target.pgid, 'SIGTERM');
+        return 'stopped';
+    }
+    catch {
+        return 'kill_failed';
+    }
+};
+exports.stopBackgroundTask = stopBackgroundTask;

package/dist/background-tasks.d.ts

@@ -0,0 +1,65 @@
+import { type TailState } from './transcript-tail.js';
+/** How often a session's tasks have their output writers checked. */
+export declare const BACKGROUND_TASK_PROBE_MS = 15000;
+/** Most tasks one session keeps — a runaway loop of launches cannot grow the listener without bound. */
+export declare const MAX_BACKGROUND_TASKS = 50;
+export interface BackgroundTask {
+    readonly id: string;
+    readonly description: string | null;
+    /** When the launch result was written, or null when the line had no stamp. */
+    readonly startedAt: string | null;
+    /** Where Claude Code writes the task's output, exactly as the transcript said. */
+    readonly outputPath: string;
+}
+/**
+ * Which of `paths` some process still has open, or null when that cannot be
+ * told (no `lsof`, a timeout). Null keeps every task: not knowing is not dead.
+ */
+export type WriterProbe = (paths: readonly string[]) => ReadonlySet<string> | null;
+export interface BackgroundTaskState {
+    tail: TailState | null;
+    /** Background launches whose result has not been read yet: tool_use id → description. */
+    readonly launches: Map<string, string | null>;
+    /** Running tasks by id, in launch order. */
+    readonly running: Map<string, BackgroundTask>;
+    /** When writers were last checked; -Infinity before the first check. */
+    probedAt: number;
+}
+export declare const initialBackgroundTaskState: () => BackgroundTaskState;
+/** The lsof binary, or null when this machine has none. */
+export declare const lsofBin: () => string | null;
+/**
+ * Run a probe (`lsof`, `ps`) without blocking the main thread, which serves
+ * the socket (inventory-offload.ts). Its stdout, or null on a spawn failure,
+ * a timeout or an exit status outside `okCodes` — lsof's exit 1 ("open
+ * nowhere") is still an answer.
+ */
+export declare const runProbe: (bin: string, args: string[], okCodes: readonly number[]) => Promise<string | null>;
+/**
+ * `lsof -F n -- <paths>`: one `n<name>` line per open file. lsof exits 1 when
+ * any one of the paths is open nowhere — still an answer, printed for the
+ * rest; a spawn failure, a timeout or another status is no answer.
+ */
+export declare const lsofWriters: WriterProbe;
+/** An answer that resolves later: what the phone's requests use on the main thread. */
+export type AsyncWriterProbe = (paths: readonly string[]) => Promise<ReadonlySet<string> | null>;
+/** `lsofWriters` without blocking: a synchronous spawn on the main thread delays frames and pongs. */
+export declare const lsofWritersAsync: AsyncWriterProbe;
+/**
+ * Fold what the transcript appended since the last call, then drop tasks
+ * whose output nobody writes any more (at most once per probe window).
+ * Returns the running tasks in launch order.
+ */
+export declare const trackBackgroundTasks: (transcriptPath: string, state: BackgroundTaskState, opts?: {
+    probe?: WriterProbe;
+    now?: number;
+}) => BackgroundTask[];
+/** A Claude session's running background commands, with the pane they run under (what Stop checks ancestry against). */
+export interface SessionBackgroundTasks {
+    readonly tasks: readonly BackgroundTask[];
+    readonly panePid: number | null;
+}
+export declare const recordBackgroundTasks: (bySession: Record<string, SessionBackgroundTasks> | null | undefined) => void;
+/** The session's running background commands as of the last sweep; null when it has none. */
+export declare const backgroundTasksFor: (sessionName: string) => SessionBackgroundTasks | null;
+//# sourceMappingURL=background-tasks.d.ts.map

package/dist/background-tasks.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backgroundTasksFor = exports.recordBackgroundTasks = exports.trackBackgroundTasks = exports.lsofWritersAsync = exports.lsofWriters = exports.runProbe = exports.lsofBin = exports.initialBackgroundTaskState = exports.MAX_BACKGROUND_TASKS = exports.BACKGROUND_TASK_PROBE_MS = void 0;
+/**
+ * Background commands a Claude Code session is running (`Bash` with
+ * `run_in_background: true`), read off its transcript.
+ *
+ * The phone shows them above the composer and can stop one. Measured
+ * 2026-11-11 (Claude Code 2.x, `hwip cc`):
+ *
+ * - The launch is an assistant `tool_use` named `Bash` whose input has
+ *   `run_in_background: true` and a `description` Claude wrote for it.
+ * - Its `tool_result` reads `Command running in background with ID: <id>.
+ *   Output is being written to: <path>` and carries the id again on
+ *   `toolUseResult.backgroundTaskId`.
+ * - The end is a `<task-notification>` naming the id. Current builds write it
+ *   the moment the task ends — mid-turn too — as a `queue-operation`
+ *   (`operation: enqueue`) and a `queued_command` attachment; earlier ones as
+ *   a user turn with `origin.kind: 'task-notification'`. All three are read.
+ *
+ * Only the harness's own records count as an end: a tool result that prints
+ * a notice (a session reading a transcript) carries the words but is not an
+ * event. The command line is never kept — it is what a secret would be typed
+ * into; the description is what the phone shows.
+ *
+ * A session whose Claude died never writes the notice, and the task's process
+ * may be gone with it. So a running task also needs a live writer on its
+ * output file, asked at most once per `BACKGROUND_TASK_PROBE_MS` for all of a
+ * session's tasks together.
+ */
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const subagent_transcripts_js_1 = require("./subagent-transcripts.js");
+const transcript_tail_js_1 = require("./transcript-tail.js");
+/** How often a session's tasks have their output writers checked. */
+exports.BACKGROUND_TASK_PROBE_MS = 15_000;
+/** Most tasks one session keeps — a runaway loop of launches cannot grow the listener without bound. */
+exports.MAX_BACKGROUND_TASKS = 50;
+/** Longest description kept; Claude writes a few words. */
+const MAX_DESCRIPTION_CHARS = 200;
+const initialBackgroundTaskState = () => ({
+    tail: null,
+    launches: new Map(),
+    running: new Map(),
+    probedAt: Number.NEGATIVE_INFINITY,
+});
+exports.initialBackgroundTaskState = initialBackgroundTaskState;
+const STARTED = /Command running in background with ID: ([A-Za-z0-9]{1,32})\. Output is being written to: (\S+?\.output)\b/;
+const textOf = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const texts = content.flatMap((b) => b?.type === 'text' && typeof b.text === 'string' ? [b.text] : []);
+    return texts.length > 0 ? texts.join('\n') : null;
+};
+/** The notice text of a harness record that reports a task ending, or null. */
+const noticeOf = (entry) => {
+    if (entry.type === 'queue-operation' && entry.operation === 'enqueue')
+        return typeof entry.content === 'string' ? entry.content : null;
+    if (entry.type === 'attachment' && entry.attachment?.commandMode === 'task-notification') {
+        return typeof entry.attachment.prompt === 'string' ? entry.attachment.prompt : null;
+    }
+    if (entry.type === 'user' && entry.origin?.kind === 'task-notification')
+        return textOf(entry.message?.content);
+    return null;
+};
+const fold = (state, line) => {
+    // Cheap reject: every line the session writes passes through here.
+    if (!line.includes('run_in_background') && !line.includes('in background with ID') && !line.includes('<task-notification>'))
+        return;
+    let entry;
+    try {
+        entry = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    const notice = noticeOf(entry);
+    if (notice !== null) {
+        const id = subagent_transcripts_js_1.TASK_END.test(notice) ? subagent_transcripts_js_1.TASK_ID.exec(notice)?.[1] : undefined;
+        if (id)
+            state.running.delete(id);
+        return;
+    }
+    const content = entry.message?.content;
+    if (!Array.isArray(content))
+        return;
+    for (const block of content) {
+        if (entry.type === 'assistant' && block?.type === 'tool_use' && block.name === 'Bash' && typeof block.id === 'string') {
+            const input = block.input;
+            if (input?.run_in_background !== true)
+                continue;
+            const description = typeof input.description === 'string' && input.description.trim()
+                ? input.description.trim().slice(0, MAX_DESCRIPTION_CHARS)
+                : null;
+            // A launch whose result never comes is forgotten past the cap, like the running list.
+            if (state.launches.size >= exports.MAX_BACKGROUND_TASKS)
+                state.launches.delete(state.launches.keys().next().value);
+            state.launches.set(block.id, description);
+        }
+        else if (entry.type === 'user' && block?.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+            if (!state.launches.has(block.tool_use_id))
+                continue;
+            const description = state.launches.get(block.tool_use_id) ?? null;
+            state.launches.delete(block.tool_use_id);
+            const match = STARTED.exec(textOf(block.content) ?? '');
+            if (!match)
+                continue;
+            const id = match[1];
+            // The structured id, when there, must agree with the text: two answers to "which task" are no answer.
+            const structured = entry.toolUseResult?.backgroundTaskId;
+            if (structured !== undefined && structured !== id)
+                continue;
+            if (state.running.size >= exports.MAX_BACKGROUND_TASKS)
+                continue;
+            state.running.set(id, {
+                id,
+                description,
+                startedAt: typeof entry.timestamp === 'string' ? entry.timestamp : null,
+                outputPath: match[2],
+            });
+        }
+    }
+};
+const realPathOrSelf = (p) => {
+    try {
+        return (0, node_fs_1.realpathSync)(p);
+    }
+    catch {
+        return p;
+    }
+};
+const LSOF_CANDIDATES = ['/usr/sbin/lsof', '/usr/bin/lsof'];
+const PROBE_TIMEOUT_MS = 3_000;
+const PROBE_MAX_BUFFER = 16 * 1024 * 1024;
+/** The lsof binary, or null when this machine has none. */
+const lsofBin = () => LSOF_CANDIDATES.find((candidate) => (0, node_fs_1.existsSync)(candidate)) ?? null;
+exports.lsofBin = lsofBin;
+/**
+ * Run a probe (`lsof`, `ps`) without blocking the main thread, which serves
+ * the socket (inventory-offload.ts). Its stdout, or null on a spawn failure,
+ * a timeout or an exit status outside `okCodes` — lsof's exit 1 ("open
+ * nowhere") is still an answer.
+ */
+const runProbe = (bin, args, okCodes) => new Promise((resolve) => {
+    (0, node_child_process_1.execFile)(bin, args, { encoding: 'utf8', timeout: PROBE_TIMEOUT_MS, maxBuffer: PROBE_MAX_BUFFER, env: { ...process.env, LC_ALL: 'C' } }, (err, stdout) => {
+        const code = err?.code;
+        resolve(!err || (typeof code === 'number' && okCodes.includes(code)) ? stdout : null);
+    });
+});
+exports.runProbe = runProbe;
+/**
+ * `lsof -F n -- <paths>`: one `n<name>` line per open file. lsof exits 1 when
+ * any one of the paths is open nowhere — still an answer, printed for the
+ * rest; a spawn failure, a timeout or another status is no answer.
+ */
+const lsofWriters = (paths) => {
+    const bin = (0, exports.lsofBin)();
+    if (!bin || paths.length === 0)
+        return null;
+    const r = (0, node_child_process_1.spawnSync)(bin, ['-F', 'n', '--', ...paths], { encoding: 'utf8', timeout: PROBE_TIMEOUT_MS });
+    if (r.error || (r.status !== 0 && r.status !== 1))
+        return null;
+    return openAmong(paths, r.stdout);
+};
+exports.lsofWriters = lsofWriters;
+/** `lsofWriters` without blocking: a synchronous spawn on the main thread delays frames and pongs. */
+const lsofWritersAsync = async (paths) => {
+    const bin = (0, exports.lsofBin)();
+    if (!bin || paths.length === 0)
+        return null;
+    const out = await (0, exports.runProbe)(bin, ['-F', 'n', '--', ...paths], [1]);
+    return out === null ? null : openAmong(paths, out);
+};
+exports.lsofWritersAsync = lsofWritersAsync;
+/** Which of `paths` lsof's `-F n` output names. lsof names a file by its real path (/tmp is /private/tmp on macOS). */
+const openAmong = (paths, stdout) => {
+    const open = new Set();
+    for (const row of stdout.split('\n'))
+        if (row.startsWith('n'))
+            open.add(row.slice(1));
+    return new Set(paths.filter((p) => open.has(p) || open.has(realPathOrSelf(p))));
+};
+/**
+ * Fold what the transcript appended since the last call, then drop tasks
+ * whose output nobody writes any more (at most once per probe window).
+ * Returns the running tasks in launch order.
+ */
+const trackBackgroundTasks = (transcriptPath, state, opts = {}) => {
+    // From the start: a command launched before the last 256 KB of turns is still running (a dev server), and a
+    // window off the end would never see its launch. A long transcript catches up one tick's read at a time.
+    const read = (0, transcript_tail_js_1.readTranscriptDelta)(transcriptPath, state.tail, { fromStart: true });
+    if (read) {
+        state.tail = read.state;
+        for (const line of read.lines)
+            fold(state, line);
+    }
+    const now = opts.now ?? Date.now();
+    if (state.running.size > 0 && now - state.probedAt >= exports.BACKGROUND_TASK_PROBE_MS) {
+        state.probedAt = now;
+        const tasks = [...state.running.values()];
+        const open = (opts.probe ?? exports.lsofWriters)(tasks.map((t) => t.outputPath));
+        if (open)
+            for (const t of tasks)
+                if (!open.has(t.outputPath))
+                    state.running.delete(t.id);
+    }
+    return [...state.running.values()];
+};
+exports.trackBackgroundTasks = trackBackgroundTasks;
+/**
+ * The main thread's copy of the last sweep's tasks. The sweep may run on the
+ * inventory worker, whose module state the main thread cannot see, so the
+ * result travels back on `CollectResult` and lands here — the phone's
+ * requests are answered from this.
+ */
+let tasksBySession = new Map();
+const recordBackgroundTasks = (bySession) => {
+    tasksBySession = new Map(Object.entries(bySession ?? {}));
+};
+exports.recordBackgroundTasks = recordBackgroundTasks;
+/** The session's running background commands as of the last sweep; null when it has none. */
+const backgroundTasksFor = (sessionName) => tasksBySession.get(sessionName) ?? null;
+exports.backgroundTasksFor = backgroundTasksFor;

package/dist/crypto.d.ts

@@ -204,7 +204,7 @@ export declare const decryptPushBodyForDevice: (body: string, entryJson: string,
     schedule?: Record<string, unknown>;
     context?: SealedAskContext;
 }>;
-export type SealPurpose = 'stream.frame' | 'stream.input' | 'stream.alive' | 'stream.started' | 'screen.snapshot' | 'screen.history' | 'session.diff' | 'schedule.list' | 'turn.batch';
+export type SealPurpose = 'stream.frame' | 'stream.input' | 'stream.alive' | 'stream.started' | 'screen.snapshot' | 'screen.history' | 'session.diff' | 'schedule.list' | 'agent.tasks' | 'agent.task.stop' | 'agent.task.output' | 'turn.batch';
 export interface SealedV2 {
     v: 2;
     /** Base64, 32 bytes — the HKDF salt, fresh per message. */

package/dist/listener.d.ts

@@ -25,6 +25,7 @@ import { type ShellAuditEntry } from './shell-audit.js';
 import { type KnownSession } from './session-registry.js';
 import { type AgentKind } from './remote-agents.js';
 import type { ProviderNameSource } from './session-title.js';
+import { type SessionBackgroundTasks } from './background-tasks.js';
 import { type TranscriptSource } from './transcript-tail.js';
 import { type AgentState } from './agent-state.js';
 import { type SealedFileMeta, type SealedV2 } from './crypto.js';
@@ -101,6 +102,9 @@ interface AgentSession {
      *  transcript subagent has one: a pane subagent is watched as a screen, and
      *  nothing counts what happens on it. */
     toolCount?: number;
+    /** Background commands this Claude session is running — a count only;
+     *  what they are travels sealed (`agent.tasks.request`). Absent at zero. */
+    backgroundTaskCount?: number;
     /** Set on a subagent with no pane at all (Claude Code's `Agent` tool): there
      *  is no screen to stream, only its transcript. Absent on a pane subagent —
      *  which can run Claude Code too, so the kind cannot stand in for this. */
@@ -515,6 +519,63 @@ export interface ScheduleListRequest {
  * seal is never answered in the clear. Directories and agent arguments are not in the list at all.
  */
 export declare const handleScheduleListRequest: (req: ScheduleListRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export interface BackgroundTasksRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+    subscriberPublicKey?: string;
+    /** The asking device, stamped by the relay: whose registered key the one above has to be. */
+    deviceId?: string;
+}
+/**
+ * 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.
+ */
+export declare const handleBackgroundTasksRequest: (req: BackgroundTasksRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export interface BackgroundTaskStopRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+    subscriberPublicKey?: string;
+    /** `{v: 1, requestId, taskId, at}`, sealed by the phone for this listener (`agent.task.stop`), bound to the session. */
+    encrypted?: unknown;
+    deviceId?: string;
+}
+/**
+ * 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.
+ */
+export declare const handleBackgroundTaskStopRequest: (req: BackgroundTaskStopRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export interface BackgroundTaskOutputRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+    /** Which task, by the id the list gave. Never a path: the path is the one the transcript gave. */
+    taskId?: unknown;
+    subscriberPublicKey?: string;
+    deviceId?: string;
+}
+/**
+ * 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.
+ */
+export declare const handleBackgroundTaskOutputRequest: (req: BackgroundTaskOutputRequest, send: (data: Record<string, unknown>) => void) => boolean;
 export interface SessionResumeRequest {
     subtype?: string;
     targetDeviceId?: string;
@@ -1155,6 +1216,10 @@ export interface CollectResult {
      *  name → the transcript it writes and the agent kind whose projector reads
      *  it. Only sessions this machine can actually read; no subagent rows. */
     recordable: Record<string, RecordableSession>;
+    /** Also local: Claude session name → its running background commands and
+     *  pane pid. Built on whichever thread sweeps; the main thread, which
+     *  answers the phone's requests, stores it (`recordBackgroundTasks`). */
+    backgroundTasks: Record<string, SessionBackgroundTasks>;
 }
 /**
  * Inventory pass that also records *why* each `hwip-*` session was

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/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/package.json

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