@hwip/cli 0.1.22 → 0.1.24

package/README.md

@@ -799,6 +799,13 @@ installs on one machine don't fight over it):
 hwip: listener 1.25.0 is stale — restarting on 1.26.0
 ```
 
+With the login service installed, launchd (or systemd) does the restart —
+and it starts the install the plist was written from, which need not be
+the `hwip` on your PATH (Homebrew's next to an nvm node's, say). When the
+restarted daemon is still the older build, `hwip cc` says which install
+the service runs instead of restarting it again on every launch; re-run
+`hwip listener --install-service` from the `hwip` you use to repoint it.
+
 If the PID file is missing (a different account started the daemon, or
 it was removed by hand) the singleton guard can't see it. Find the real
 process instead:
@@ -870,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
@@ -1005,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
@@ -1076,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
@@ -1353,7 +1384,7 @@ hwip notify --title "Hello" --json
 | `forget <session>` | Drop an ended session from this machine's record, so it leaves the app's past list (and the resume whitelist — the same thing deleting the row on the phone does). Refuses a session that is still running: kill it first. `--ended` forgets every remembered session tmux no longer has, which is what a machine that launches agents under a fresh name per task eventually needs |
 | `test` | Verify connection and API key |
 | `trust [deviceId]` | Advanced — nothing needs it: every device on the account is pinned the first time hwip seals for it, and a changed key replaces its pin with a warning. Shows this computer's key fingerprint and the devices pinned here — compare each with the fingerprint the app shows on that device's page. It also lists the computers of the account not pinned here yet, with their fingerprints; the first send seals for each and pins it. With a `deviceId`, pin the key the account now lists for that device: prints the pinned and the listed fingerprint and asks first, `--yes` skips the question. `--reset` forgets every pin (each is pinned again as hwip sees it), and until then the listener answers a request for a screen in plaintext. Exit 0 done, 1 refused or declined, 2 not a device id |
-| `cc` · `codex` · `gemini` · `cursor` · `hermes` · `pi` · `opencode` · `kimi` · `grok` · `agy` · `qwen` · `auggie` · `kilo` · `copilot` · `kiro-cli` · `droid` | Run the agent in a `hwip-<project>` tmux session — reattaches a detached session of that project (newest suffix first) when there is one, else auto-suffixes `-2`, `-3`, …. Auto-spawns the background listener on first invocation so the phone picker just works; when that daemon stops within a second and a half (no key, no tmux, a rejected key) it prints the daemon's last log line instead of "autostarted". Once a day it asks npm whether a newer hwip is out and prints the update line (cached in `~/.hwip/update-check.json`; skipped under `CI` or `HWIP_NO_UPDATE_CHECK`). Trailing args pass through to the agent (`hwip cc --resume "..."`). On node 22.15+ the wrapper hands its process to tmux rather than waiting on it, so a running session shows no `hwip cc` of its own in `ps` — older runtimes and Windows keep the waiting wrapper `--detach` / `--label <x>` (front of the args) create without attaching / pin the name; `--wt <name>` runs it in a git worktree made for the session — see "Run agents through the wrapper" above. |
+| `cc` · `codex` · `gemini` · `cursor` · `hermes` · `pi` · `opencode` · `kimi` · `grok` · `agy` · `qwen` · `auggie` · `kilo` · `copilot` · `kiro-cli` · `droid` | Run the agent in a `hwip-<project>` tmux session — reattaches a detached session of that project (newest suffix first) when there is one, else auto-suffixes `-2`, `-3`, …. Auto-spawns the background listener on first invocation so the phone picker just works; when that daemon stops within a second and a half (no key, no tmux, a rejected key) it prints the daemon's last log line instead of "autostarted". Once a day it asks npm whether a newer hwip is out and prints the update line (cached in `~/.hwip/update-check.json`; skipped under `CI` or `HWIP_NO_UPDATE_CHECK`). Trailing args pass through to the agent (`hwip cc --resume "..."`). When the tmux session ends (not on a detach), it prints the command that picks the conversation back up — `hwip: to resume: claude --resume <id>  (or hwip cc --resume <id>)` — for `cc` · `codex` · `hermes` · `pi` · `opencode`, from the id the listener recorded while the session ran (a session shorter than one 5 s sweep has none yet, and gets no line); the tmux command runs under a small `sh` for this, so no node process waits on the session. On node 22.15+ the wrapper hands its process to tmux rather than waiting on it, so a running session shows no `hwip cc` of its own in `ps` — older runtimes and Windows keep the waiting wrapper `--detach` / `--label <x>` (front of the args) create without attaching / pin the name; `--wt <name>` runs it in a git worktree made for the session — see "Run agents through the wrapper" above. |
 | `worktree [clean]` | List the git worktrees `--wt` made (path, branch, and `in use` / `clean` / `never used` / what keeps it: uncommitted, untracked or ignored files, commits not pushed). `clean` removes the ones nothing keeps and prints why the others stay; `--dry-run` removes nothing and records nothing. A worktree you made by hand is never listed or removed. Exit 0, also when some stay; `clean` exits 1 when git refused a removal it had cleared or tmux could not be asked (the list still prints, without `in use`); 2 for an unknown subcommand. See "Run agents through the wrapper" for when the listener does the same on its own |
 | `schedule` | Start an agent session on a timer, in the background. The listener starts it, so it has to be running (installing the listener as a login service keeps it up). A run missed while the computer slept or the listener was down is skipped, never started late, and the phone is told. At most 20 schedules and 3 scheduled sessions at once; a session is asked to end after `--max-runtime` (never killed). Schedules live in `~/.local/state/hwip/schedules`. `schedule add <agent> (--at HH:MM \| --on YYYY-MM-DD --at HH:MM \| --every <N>m\|<N>h) [-- <agent args…>]` adds one: `<agent>` is an agent command above (`cc`, `codex`, …) and the project is this one; `--on` runs it once. `schedule add --session <name> (…) --prompt <text>` types the prompt into that running session instead of starting one (waits up to 30 min for it to be idle and its terminal quiet). `schedule [list]` shows them, with the next run and the last result (`--json` for scripts). `schedule rm <id>` removes one; a session it already started keeps running. Options: `--days <days>` (with `--at`: `daily`, `weekdays`, or day names like `mon,wed,fri`), `--prompt <text>` (typed into the session once the agent's status rules say it is idle: Claude Code, Codex, Gemini CLI and pi only), `--label <x>`, `--wt <branch>` (a git worktree for the branch, not with `--label`), `--max-runtime <N>m\|<N>h` (default 2h, at most the `--every` period; 5m to 24h). See *Scheduled sessions* |
 | `sh` | Open (or reattach) `hwip-<project>-sh`, a login shell the phone may type into — the one shell pane the listener does not refuse. `--label <x>` / `--detach` as for the agents; inside tmux it never attaches and prints a `switch-client` hint. Refuses a session of that name it did not open. Input must be addressed to this machine, is audited, and agents (`agent send`, `hwip_agent_send`) skip it — see [Defense](#defense) |

package/dist/args.js

@@ -203,6 +203,7 @@ exports.COMMAND_FLAGS = {
         'install-service', 'uninstall-service', 'service-status',
     ],
     'remote-hook': [],
+    'resume-hint': ['session', 'type', 'at'],
 };
 /**
  * Flags the command would ignore, in the order typed. A typo (`--titel`) used

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