@hwip/cli 0.1.23 → 0.1.25

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/http-failure.d.ts

@@ -76,16 +76,26 @@ export interface ProxyConfig {
  *
  * Not through Node's own `http.setGlobalProxyFromEnv`: it exists only from 24.14
  * and 25.4, and the CLI runs on older Nodes. `fetch` gets undici's
- * `EnvHttpProxyAgent` as the global dispatcher (undici 6, Node >= 18.17); `ws`
+ * `EnvHttpProxyAgent` as the global dispatcher (undici 6, Node >= 18.17 — Node 26's
+ * own fetch ignores it; the daemon swaps in undici's fetch, `useHttp1Transport`); `ws`
  * opens its own connection, so it gets a CONNECT-tunnelling agent from
- * `https-proxy-agent` (`webSocketProxyOptions`). Both libraries load only here,
- * so a run with no proxy pays nothing for them.
+ * `https-proxy-agent` (`webSocketProxyOptions`). Both libraries load only here
+ * (undici also in the daemon), so a command run with no proxy pays nothing for them.
  *
  * A proxy that cannot be set up is an error, not a direct connection: going
  * around a proxy someone configured is the wrong way to fail. The error names
  * the setting and never quotes it: the value may carry the proxy's password.
  */
 export declare const useProxyFromEnv: (env?: ProxyEnv, config?: ProxyConfig) => Promise<void>;
+/**
+ * Pin the daemon's `fetch` to HTTP/1.1: an aborted HTTP/2 upload on Node 26 wedged the
+ * event loop in nghttp2's send loop (one shared session); HTTP/1.1 gives each request its
+ * own socket. Node 26's fetch (undici 8) reads `undici.globalDispatcher.2`, undici 6 writes
+ * `.1`, and an undici 6 dispatcher handed to Node 26's fetch fails "invalid onError method"
+ * — so the fetch is swapped for undici 6's own, which also makes `useProxyFromEnv`'s proxy
+ * agent apply again. Daemon only (`cli-lazy-load.test.ts`); call after `useProxyFromEnv`.
+ */
+export declare const useHttp1Transport: () => Promise<void>;
 /**
  * Options for the listener's `new WebSocket`: `ws` opens its own connection
  * and never reaches fetch's dispatcher, so with a proxy set it is handed an

package/dist/http-failure.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.webSocketProxyOptions = exports.useProxyFromEnv = exports.proxyForUrl = exports.AUTH_HINT = exports.httpFailureMessage = exports.readJsonBody = exports.networkFailureMessage = exports.isUnsendableHeader = exports.isConfigFailure = exports.isInvalidUrl = exports.neverConnected = exports.isRedirectRefusal = void 0;
+exports.webSocketProxyOptions = exports.useHttp1Transport = exports.useProxyFromEnv = exports.proxyForUrl = exports.AUTH_HINT = exports.httpFailureMessage = exports.readJsonBody = exports.networkFailureMessage = exports.isUnsendableHeader = exports.isConfigFailure = exports.isInvalidUrl = exports.neverConnected = exports.isRedirectRefusal = void 0;
 const redact_js_1 = require("./redact.js");
 const ws_url_js_1 = require("./ws-url.js");
 /**
@@ -273,10 +273,11 @@ const configProxyValue = (key, config) => {
  *
  * Not through Node's own `http.setGlobalProxyFromEnv`: it exists only from 24.14
  * and 25.4, and the CLI runs on older Nodes. `fetch` gets undici's
- * `EnvHttpProxyAgent` as the global dispatcher (undici 6, Node >= 18.17); `ws`
+ * `EnvHttpProxyAgent` as the global dispatcher (undici 6, Node >= 18.17 — Node 26's
+ * own fetch ignores it; the daemon swaps in undici's fetch, `useHttp1Transport`); `ws`
  * opens its own connection, so it gets a CONNECT-tunnelling agent from
- * `https-proxy-agent` (`webSocketProxyOptions`). Both libraries load only here,
- * so a run with no proxy pays nothing for them.
+ * `https-proxy-agent` (`webSocketProxyOptions`). Both libraries load only here
+ * (undici also in the daemon), so a command run with no proxy pays nothing for them.
  *
  * A proxy that cannot be set up is an error, not a direct connection: going
  * around a proxy someone configured is the wrong way to fail. The error names
@@ -334,6 +335,22 @@ const useProxyFromEnv = async (env = process.env, config = {}) => {
     };
 };
 exports.useProxyFromEnv = useProxyFromEnv;
+/**
+ * Pin the daemon's `fetch` to HTTP/1.1: an aborted HTTP/2 upload on Node 26 wedged the
+ * event loop in nghttp2's send loop (one shared session); HTTP/1.1 gives each request its
+ * own socket. Node 26's fetch (undici 8) reads `undici.globalDispatcher.2`, undici 6 writes
+ * `.1`, and an undici 6 dispatcher handed to Node 26's fetch fails "invalid onError method"
+ * — so the fetch is swapped for undici 6's own, which also makes `useProxyFromEnv`'s proxy
+ * agent apply again. Daemon only (`cli-lazy-load.test.ts`); call after `useProxyFromEnv`.
+ */
+const useHttp1Transport = async () => {
+    const undici = await import('undici');
+    // With a proxy, its agent is already the dispatcher (HTTP/1.1, undici 6's default).
+    if (!active)
+        undici.setGlobalDispatcher(new undici.Agent({ allowH2: false }));
+    globalThis.fetch = undici.fetch;
+};
+exports.useHttp1Transport = useHttp1Transport;
 /**
  * Options for the listener's `new WebSocket`: `ws` opens its own connection
  * and never reaches fetch's dispatcher, so with a proxy set it is handed an

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