@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/session/persist.js

@@ -59,6 +59,24 @@ function stripLiveToolOutput(entries) {
         ? { ...e, live: undefined, liveSeq: undefined, lastOutputAt: undefined }
         : e);
 }
+/**
+ * Drop the service tail on the way to disk, beside `stripLiveToolOutput` and for
+ * the same three reasons (background-service-supervision §6).
+ *
+ * A resumed card's tail describes a PROCESS THAT NO LONGER EXISTS - it died with
+ * the session, because nothing in this package outlives the CLI by design. The
+ * tail is also the only unbounded field a service entry carries, and dropping it
+ * keeps a saved session's size a function of how many services ran rather than
+ * of how chatty they were.
+ *
+ * `rowsSeen` IS KEPT. It is the revision cursor, not display data, and a
+ * restored card that reported 0 rows seen while `normalizeLoadedEntries` was
+ * flipping its status would produce a revision collision with a live card that
+ * genuinely has none.
+ */
+function stripServiceTail(entries) {
+    return entries.map((e) => (e.kind === 'service' && e.rows.length > 0 ? { ...e, rows: [] } : e));
+}
 /**
  * `data` GAINS `todos`, AND WIDENING `SavedSession` ALONE IS NOT ENOUGH (P0-2):
  * the writer below builds its payload from THIS parameter, not from the type, so
@@ -81,7 +99,7 @@ export function saveSession(filePath, data) {
         savedAt: Date.now(),
         model: data.model,
         messages: data.messages,
-        entries: stripLiveToolOutput(data.entries),
+        entries: stripServiceTail(stripLiveToolOutput(data.entries)),
         todos: data.todos,
         ...(data.meta ? { meta: data.meta } : {}),
     };
@@ -158,6 +176,23 @@ export function normalizeLoadedEntries(entries) {
                 reason: 'interrupted (session resumed)',
             };
         }
+        // THE SIXTH CLAUSE (background-service-supervision §6 / R-7). A card saved
+        // while its service was up resumes claiming to be running while nothing is -
+        // the process died with the session, because nothing here outlives the CLI.
+        //
+        // AND `starting` IS THE ONE THAT ACTUALLY COSTS: it is the single service
+        // status that blocks `Transcript`'s MONOTONIC settled boundary (D-11), so a
+        // restored `starting` card would never settle and every frame for the rest of
+        // the session would re-render the whole tail. `ready` / `running` would
+        // "only" be a lie; this one is a lie that gets slower.
+        //
+        // `stopped` rather than `exited`: we did not observe an exit code, and
+        // claiming one would be inventing a number. The terminal record the session
+        // may also carry is already terminal and is left alone.
+        if (entry.kind === 'service' &&
+            (entry.status === 'starting' || entry.status === 'ready' || entry.status === 'running')) {
+            return { ...entry, status: 'stopped', rows: [] };
+        }
         return entry;
     });
 }

package/dist/tools/bash-tool.d.ts

@@ -1,12 +1,61 @@
 /**
- * bash tool — run a shell command at full permission (spec §3.6).
+ * bash tool — run a shell command at full permission (spec §3.6), and, since
+ * background-service-supervision, supervise the ones that do not exit.
  *
  * Shell selection: Windows uses `process.env.ComSpec` (cmd.exe by default);
  * POSIX uses `/bin/sh -c`. The command's stdout+stderr and exit code are
  * captured. The `timeout?` param can only SHRINK within the executor ceiling
  * (the core ToolExecutor owns the real timeout + 100 KB truncation — R4), so
  * this tool does not re-implement an output cap.
+ *
+ * I-1 — THIS TOOL NEVER LEAVES ITS PROMISE PENDING. Every exit path goes through
+ * `settle`, and `settle` is reachable from FIVE places: `'error'`, `'close'`,
+ * `'exit'` plus a drain timer, an abort plus a kill grace, and the `timeout`
+ * param plus the same grace. That is the whole of W1, and each of the five
+ * closes a way the old implementation could hang:
+ *
+ *   1. It settled on `'close'`, which fires only when the process has exited AND
+ *      every stdio stream is closed. A child that spawns a detached grandchild
+ *      inheriting the pipe — `Start-Process`, `&`, `nohup`, and every
+ *      `npm run dev` that re-execs — keeps that pipe open after the shell is
+ *      long gone. The shell exited; the promise did not.
+ *   2. `stdio` defaulted to `'pipe'` for stdin, so a command that PROMPTS —
+ *      `npm init`, a package manager asking to install something, `sudo`, a git
+ *      credential prompt — blocked on a read that could never be satisfied.
+ *   3. An abort killed the tree and then went on waiting for a `'close'` that a
+ *      detached grandchild was still holding.
+ *
+ * The happy path is BYTE-IDENTICAL to the pre-change build: `$ cmd\n<output>\n
+ * [exit code N]`, same truncation, same footer. That is what keeps the existing
+ * `bash` assertions meaningful rather than rewritten.
  */
 import { type AgentTool } from '@aragon-agent/core';
+import type { ProcSupervisorPort } from '../proc/types.js';
 import type { ToolDeps } from './fs-tools.js';
-export declare function makeBash(deps: ToolDeps): AgentTool;
+export interface BashToolOptions {
+    /**
+     * Present only when background launches are on for this session.
+     *
+     * ITS ABSENCE IS WHAT MAKES I-2 CHECKABLE: no `background` property in the
+     * schema, no supervisor call, no readiness timer, and a description string
+     * identical to the pre-feature one.
+     */
+    supervisor?: ProcSupervisorPort;
+    /** `cfg.bash.autoBackground`, read LIVE. */
+    autoBackground?: () => boolean;
+    /** `cfg.bash.startupSettleMs`, read LIVE. */
+    startupSettleMs?: () => number;
+    /**
+     * Whether a card can be rendered and a user can keep a service alive (D-15 /
+     * P1-8).
+     *
+     * FALSE IN `aragon exec` AND `-p`. It suppresses only the CLASSIFIER: an
+     * explicit `background: true` is still honoured — the model asked for it —
+     * and the result then carries one extra line saying the service dies with the
+     * run. Without this rule `aragon -p "npm run dev"` would background a server,
+     * return in `startupSettleMs`, and reap it at process exit with no card, no
+     * `/bg`, no event and nothing in the result saying so.
+     */
+    interactive?: boolean;
+}
+export declare function makeBash(deps: ToolDeps, options?: BashToolOptions): AgentTool;

package/dist/tools/bash-tool.js

@@ -1,59 +1,150 @@
 /**
- * bash tool — run a shell command at full permission (spec §3.6).
+ * bash tool — run a shell command at full permission (spec §3.6), and, since
+ * background-service-supervision, supervise the ones that do not exit.
  *
  * Shell selection: Windows uses `process.env.ComSpec` (cmd.exe by default);
  * POSIX uses `/bin/sh -c`. The command's stdout+stderr and exit code are
  * captured. The `timeout?` param can only SHRINK within the executor ceiling
  * (the core ToolExecutor owns the real timeout + 100 KB truncation — R4), so
  * this tool does not re-implement an output cap.
+ *
+ * I-1 — THIS TOOL NEVER LEAVES ITS PROMISE PENDING. Every exit path goes through
+ * `settle`, and `settle` is reachable from FIVE places: `'error'`, `'close'`,
+ * `'exit'` plus a drain timer, an abort plus a kill grace, and the `timeout`
+ * param plus the same grace. That is the whole of W1, and each of the five
+ * closes a way the old implementation could hang:
+ *
+ *   1. It settled on `'close'`, which fires only when the process has exited AND
+ *      every stdio stream is closed. A child that spawns a detached grandchild
+ *      inheriting the pipe — `Start-Process`, `&`, `nohup`, and every
+ *      `npm run dev` that re-execs — keeps that pipe open after the shell is
+ *      long gone. The shell exited; the promise did not.
+ *   2. `stdio` defaulted to `'pipe'` for stdin, so a command that PROMPTS —
+ *      `npm init`, a package manager asking to install something, `sudo`, a git
+ *      credential prompt — blocked on a read that could never be satisfied.
+ *   3. An abort killed the tree and then went on waiting for a `'close'` that a
+ *      detached grandchild was still holding.
+ *
+ * The happy path is BYTE-IDENTICAL to the pre-change build: `$ cmd\n<output>\n
+ * [exit code N]`, same truncation, same footer. That is what keeps the existing
+ * `bash` assertions meaningful rather than rewritten.
  */
 import { spawn } from 'node:child_process';
 import process from 'node:process';
 import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
+import { looksLongRunning } from '../proc/classify.js';
+import { killTree } from '../proc/kill-tree.js';
+import { PROC_LIMITS } from '../proc/limits.js';
 /**
- * Kill the whole process tree. With `shell:true` the direct child is the shell
- * wrapper, so on Windows we must `taskkill /t` to reach the grandchild; a plain
- * `child.kill()` would orphan it (leaving pipes open and cwd locked).
+ * The two sentences appended to the tool description when background launches
+ * are available.
+ *
+ * MODEL-FACING POLICY, so their wording is versioned with the prompt block in
+ * `proc/prompt.ts` rather than treated as a comment. They are appended
+ * CONDITIONALLY, which is half of what keeps I-2 true: with the feature off the
+ * description — and therefore the system prompt's tool list — is the pre-feature
+ * string, byte for byte.
  */
-function killTree(child) {
-    if (child.pid === undefined)
-        return;
-    if (process.platform === 'win32') {
-        try {
-            spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true });
-        }
-        catch {
-            try {
-                child.kill('SIGKILL');
-            }
-            catch {
-                /* ignore */
-            }
-        }
+const BACKGROUND_DESCRIPTION = ' Set `background: true` for anything that does not exit on its own - dev ' +
+    'servers, watchers, `docker compose up`. Never use `Start-Process`, `&`, ' +
+    '`nohup` or `screen` to detach a command yourself; the runtime supervises ' +
+    'background commands, and a self-detached process cannot be reported on or ' +
+    'stopped.';
+/**
+ * The settle window used when a supervisor is supplied WITHOUT one.
+ *
+ * Only reachable from a test that builds the tool by hand: `AgentController`
+ * always passes `cfg.bash.startupSettleMs`. It mirrors `DEFAULT_BASH_CONFIG`
+ * rather than importing it, because nothing in `tools/` imports `config/` — a
+ * tool takes its policy through the closures below, which is what
+ * `startupSettleMs` is. It is NOT expressed in terms of `PROC_LIMITS`: those are
+ * structural bounds, this is policy, and a multiple of `killGraceMs` that
+ * happens to equal the default today would silently move if that bound ever did.
+ */
+const FALLBACK_STARTUP_SETTLE_MS = 4000;
+/**
+ * The foreground registry a `bash` child registers with, so `forceStop()` can
+ * reach it. `undefined` on the paths that build tools without a supervisor
+ * (every existing test), which is what keeps those byte-identical.
+ */
+function trackForeground(supervisor, pid) {
+    return supervisor ? supervisor.trackForeground(pid) : () => { };
+}
+/** Render a background launch's result block for the model (§3.5). */
+function renderServiceResult(service, opts) {
+    const lines = [`$ ${service.command}`];
+    lines.push(`[background] service ${service.id} started (pid ${service.pid ?? '?'})`);
+    const elapsed = ((service.readyAt ?? service.endedAt ?? Date.now()) - service.startedAt) / 1000;
+    if (service.status === 'ready') {
+        const how = service.detectedBy === 'probe' ? 'port probe' : 'output';
+        const where = service.url ?? (service.port ? `port ${service.port}` : '');
+        lines.push(`[ready] ${where}  (detected from ${how} after ${elapsed.toFixed(1)}s)`);
+    }
+    else if (service.status === 'running') {
+        lines.push(`[running] still alive, nothing to connect to (a watcher, most likely)`);
+    }
+    else if (service.status === 'exited' || service.status === 'failed') {
+        const code = service.exitCode === null ? `signal ${service.signal}` : `code ${service.exitCode}`;
+        lines.push(`[exited] ${code} after ${elapsed.toFixed(1)}s`);
     }
     else {
-        try {
-            child.kill('SIGKILL');
-        }
-        catch {
-            /* ignore */
-        }
+        lines.push(`[starting] not ready yet after ${elapsed.toFixed(1)}s - still coming up`);
+    }
+    if (service.portPreoccupied && service.port !== undefined) {
+        lines.push(`[note] port ${service.port} was already in use before start`);
+    }
+    if (service.rows.length > 0) {
+        lines.push('[log tail]');
+        for (const row of service.rows)
+            lines.push(`  ${row}`);
+    }
+    if (opts.ephemeral) {
+        // D-15 / P1-8: headless has no user who could keep it alive, and saying so
+        // is the difference between a surprise and a documented behaviour.
+        lines.push('[note] this service will be stopped when the run ends.');
     }
+    lines.push(`Read more with bash_output({ service: "${service.id}" }); ` +
+        `stop it with bash_kill({ service: "${service.id}" }).`);
+    const body = lines.join('\n');
+    // A service that DIED is an error result, so the model treats it as one: this
+    // is the failure the user actually cares about, reported in 400 ms instead of
+    // three minutes of stall (G1).
+    return service.status === 'exited' && service.exitCode !== 0
+        ? errorResult(body)
+        : service.status === 'failed'
+            ? errorResult(body)
+            : textResult(body);
 }
-export function makeBash(deps) {
+export function makeBash(deps, options = {}) {
+    const supervisor = options.supervisor;
+    const backgroundAvailable = supervisor !== undefined;
     return defineTool({
         name: 'bash',
         label: 'Shell',
         description: 'Run a shell command at full permission and return its combined ' +
             'stdout+stderr and exit code. `timeout` (ms) may only shrink within the ' +
             'agent tool-timeout ceiling; `cwd` defaults to the working directory. ' +
-            'Emit shell syntax compatible with the OS/shell stated in the system prompt.',
+            'Emit shell syntax compatible with the OS/shell stated in the system prompt.' +
+            (backgroundAvailable ? BACKGROUND_DESCRIPTION : ''),
         parameters: {
             type: 'object',
             properties: {
                 command: { type: 'string', description: 'The shell command to run.' },
                 timeout: { type: 'number', description: 'Optional timeout in milliseconds (shrinks within the ceiling).' },
                 cwd: { type: 'string', description: 'Working directory for this command.' },
+                // SPREAD CONDITIONALLY. With the feature off the schema is the object it
+                // is today, which is what `buildSystemPrompt`'s byte-identity claim (I-2)
+                // is measured against.
+                ...(backgroundAvailable
+                    ? {
+                        background: {
+                            type: 'boolean',
+                            description: 'true = supervise this command and return immediately with a ' +
+                                'service id. false = never background it. Omit to let the ' +
+                                'runtime decide from the command.',
+                        },
+                    }
+                    : {}),
             },
             required: ['command'],
         },
@@ -63,6 +154,25 @@ export function makeBash(deps) {
             const params = rawParams;
             const command = params.command;
             const cwd = params.cwd ? params.cwd : deps.getCwd();
+            // --- The three-valued background decision (D-2 / §3.5) ----------------
+            //
+            // `true`  -> background, always.
+            // `false` -> foreground, always. The escape hatch; nothing overrides it.
+            // absent  -> the classifier, and only where a card can be rendered.
+            if (supervisor && params.background !== false) {
+                const auto = options.interactive !== false &&
+                    options.autoBackground?.() !== false &&
+                    looksLongRunning(command);
+                if (params.background === true || auto) {
+                    return runBackground(supervisor, {
+                        command,
+                        cwd,
+                        toolCallId: id,
+                        settleMs: options.startupSettleMs?.() ?? FALLBACK_STARTUP_SETTLE_MS,
+                        ephemeral: options.interactive === false,
+                    });
+                }
+            }
             return new Promise((resolvePromise) => {
                 let child;
                 try {
@@ -74,40 +184,144 @@ export function makeBash(deps) {
                         cwd,
                         env: process.env,
                         windowsHide: true,
+                        // W1.2 — NO UNANSWERABLE READ. `spawn` defaults every descriptor to
+                        // a pipe, so a command that prompts blocks on a read nobody will
+                        // ever satisfy and the promise never settles. `'ignore'` turns that
+                        // into an EOF the command can react to.
+                        stdio: ['ignore', 'pipe', 'pipe'],
                     });
                 }
                 catch (err) {
                     resolvePromise(errorResult(err instanceof Error ? err.message : String(err)));
                     return;
                 }
+                const releaseForeground = trackForeground(supervisor, child.pid);
                 let output = '';
-                let killedByTimeout = false;
                 let settled = false;
-                const finish = (fn) => {
+                let drainTimer;
+                let graceTimer;
+                let selfTimer;
+                /**
+                 * WHY the child is being killed, when it is.
+                 *
+                 * THE FLAG OUTRANKS `'close'`, AND THAT ORDERING IS THE WHOLE POINT.
+                 * Killing a tree usually DOES produce a prompt `'close'`, so a `'close'`
+                 * handler that rendered the ordinary `[signal SIGTERM]` body would win
+                 * the race in the common case and the honest footer would only ever be
+                 * seen in the rare one - the model would be told "the command was
+                 * signalled" instead of "the command was still running when the ceiling
+                 * fired, re-run it in the background", which is precisely the sentence
+                 * that stops it reaching for `Start-Process`. The pre-change build made
+                 * the same choice for its `killedByTimeout` flag, for the same reason.
+                 */
+                let killReason;
+                /**
+                 * The result body, from whatever is known at settle time.
+                 *
+                 * ONE BUILDER FOR ALL FIVE SETTLE PATHS, so a footer can never depend on
+                 * WHICH of them got there first - the property that makes the abort and
+                 * timeout wordings deterministic rather than a race.
+                 */
+                const buildBody = (opts) => {
+                    const body = captured();
+                    if (killReason === 'timeout') {
+                        // BYTE-IDENTICAL TO THE PRE-CHANGE BUILD for the `timeout` param.
+                        return errorResult(`Command timed out after ${params.timeout}ms.\n${body}`);
+                    }
+                    if (killReason === 'abort') {
+                        // P1-5. The captured output is the evidence the model needs, and
+                        // `ctx.abortCause` is what separates "the ceiling fired" (which earns
+                        // the advice) from "the user pressed Esc" (which does not - they did
+                        // not ask for a workaround).
+                        const footer = ctx.abortCause === 'timeout'
+                            ? '[aborted - the command was still running]\n' +
+                                'It does not look like this command terminates on its own. ' +
+                                'Re-run it with `background: true` if it is a server or a watcher.'
+                            : '[aborted]';
+                        return errorResult(`$ ${command}\n${body}\n${footer}`);
+                    }
+                    const status = opts.code === null ? `signal ${opts.signalName}` : `exit code ${opts.code}`;
+                    const note = opts.note
+                        ? '[note] the command exited but a background child is still holding its ' +
+                            'output stream.\n'
+                        : '';
+                    const text = `$ ${command}\n${body}\n${note}[${status}]`;
+                    return opts.code === 0 ? textResult(text) : errorResult(text);
+                };
+                /**
+                 * THE ONE FUNNEL. Idempotent, clears every timer, removes the abort
+                 * listener and releases the foreground registration. Five call sites;
+                 * see the module header for which ways of hanging each one closes.
+                 */
+                const settle = (build) => {
                     if (settled)
                         return;
                     settled = true;
-                    cleanup();
-                    resolvePromise(fn());
+                    if (drainTimer)
+                        clearTimeout(drainTimer);
+                    if (graceTimer)
+                        clearTimeout(graceTimer);
+                    if (selfTimer)
+                        clearTimeout(selfTimer);
+                    ctx.signal?.removeEventListener('abort', onAbort);
+                    releaseForeground();
+                    resolvePromise(build());
+                };
+                const captured = () => (output.length > 0 ? output : '(no output)');
+                /**
+                 * Arm the post-kill force-settle. AT MOST ONCE.
+                 *
+                 * Both kill paths reach it and the executor's ceiling aborts through
+                 * `ctx.signal` a moment after the tool's own timer fires, so a plain
+                 * assignment would overwrite a pending timer with a second one — and
+                 * `settle` clears only the reference it can see, leaving the orphan to
+                 * hold the loop for another `killGraceMs` after the promise resolved.
+                 */
+                const armGrace = () => {
+                    if (graceTimer)
+                        return;
+                    graceTimer = setTimeout(() => {
+                        settle(() => buildBody({ code: null, signalName: null }));
+                    }, PROC_LIMITS.killGraceMs);
                 };
                 // Self-timer for the `timeout` param (shrinks within the executor ceiling).
-                let timer;
                 if (params.timeout && params.timeout > 0) {
-                    timer = setTimeout(() => {
-                        killedByTimeout = true;
-                        killTree(child);
+                    selfTimer = setTimeout(() => {
+                        killReason = 'timeout';
+                        killTree(child.pid, 'SIGKILL');
+                        // THE SAME GRACE THE ABORT PATH USES. Killing is not settling: a
+                        // detached grandchild can hold the pipe open past the kill, and the
+                        // old build then waited for a `'close'` that never came.
+                        armGrace();
                     }, params.timeout);
                 }
-                // Cooperative cancellation via the executor/agent AbortSignal.
+                /**
+                 * Cooperative cancellation via the executor/agent AbortSignal.
+                 *
+                 * THE FORCE-SETTLED BODY CARRIES THE CAPTURED OUTPUT AND NAMES THE CAUSE
+                 * (P1-5), and that is not a nicety. Today an abort kills the tree,
+                 * `'close'` fires, and the model receives `$ cmd`, everything printed,
+                 * and `[signal SIGTERM]`. The executor's own ceiling
+                 * (`DEFAULT_TOOL_TIMEOUT_MS`) aborts through this SAME signal — so a bare
+                 * `Command aborted.` would hand the model three words and no evidence at
+                 * exactly the moment it needs to learn that the command does not
+                 * terminate, which is the evidence that makes it reach for
+                 * `background: true` instead of `Start-Process`.
+                 *
+                 * `ctx.abortCause` is what separates the two: `'timeout'` earns the
+                 * advice, `'external'` (an Esc) does not — the user did not ask the model
+                 * for a workaround.
+                 */
                 const onAbort = () => {
-                    killTree(child);
+                    // NOT OVERWRITTEN when a `timeout` kill is already in force: the
+                    // executor's ceiling aborts through this same signal a moment after
+                    // the tool's own timer fired, and the `timeout` wording is the more
+                    // specific of the two.
+                    killReason ??= 'abort';
+                    killTree(child.pid, 'SIGKILL');
+                    armGrace();
                 };
                 ctx.signal?.addEventListener('abort', onAbort, { once: true });
-                function cleanup() {
-                    if (timer)
-                        clearTimeout(timer);
-                    ctx.signal?.removeEventListener('abort', onAbort);
-                }
                 // `output` IS UNTOUCHED BY THE RECORDER, and that is what makes AC-30
                 // checkable by comparison rather than by inspection: the string the
                 // model receives, its truncation and the `[exit code N]` footer are all
@@ -129,19 +343,75 @@ export function makeBash(deps) {
                     deps.recordOutput?.(id, s);
                 });
                 child.on('error', (err) => {
-                    finish(() => errorResult(`Failed to run command: ${err.message}`));
+                    settle(() => errorResult(`Failed to run command: ${err.message}`));
                 });
-                child.on('close', (code, signalName) => {
-                    const trimmed = output.length > 0 ? output : '(no output)';
-                    if (killedByTimeout) {
-                        finish(() => errorResult(`Command timed out after ${params.timeout}ms.\n${trimmed}`));
+                /**
+                 * DEFENCE 1. `'exit'` fires when the PROCESS ends; `'close'` waits for
+                 * every stdio stream, which a detached grandchild can hold open forever.
+                 * So `'exit'` starts a short drain and `'close'` — if it arrives — wins
+                 * the race and produces the byte-identical happy-path body.
+                 */
+                child.on('exit', (code, signalName) => {
+                    if (settled || drainTimer)
                         return;
-                    }
-                    const status = code === null ? `signal ${signalName}` : `exit code ${code}`;
-                    const body = `$ ${command}\n${trimmed}\n[${status}]`;
-                    finish(() => (code === 0 ? textResult(body) : errorResult(body)));
+                    drainTimer = setTimeout(() => {
+                        settle(() => buildBody({ code, signalName, note: true }));
+                    }, PROC_LIMITS.drainMs);
+                });
+                child.on('close', (code, signalName) => {
+                    settle(() => buildBody({ code, signalName }));
                 });
             });
         },
     });
 }
+/**
+ * Start a supervised service and return as soon as there is something true to
+ * say (D-3).
+ *
+ * THE FIRST OF THREE: ready, exit, or `startupSettleMs`. Never later. A 400 ms
+ * crash is reported in 400 ms with the stack in the tool result, and a slow
+ * server never costs more than the settle window of turn time.
+ *
+ * IT DOES NOT CALL `deps.recordOutput` (P2-9). The tool call settles within the
+ * window and `tool_execution_end` then clears the live-output slot, so a tail
+ * written there would flash and vanish; the `ServiceCard` owns this service's
+ * output for its whole life and is the only surface that can keep it.
+ */
+async function runBackground(supervisor, args) {
+    const started = await supervisor.start({
+        command: args.command,
+        cwd: args.cwd,
+        toolCallId: args.toolCallId,
+    });
+    if (!started.ok || !started.service) {
+        return errorResult(started.error ?? 'Could not start the background service.');
+    }
+    const id = started.service.id;
+    const settled = await new Promise((resolve) => {
+        let done = false;
+        const finish = (snapshot) => {
+            if (done)
+                return;
+            done = true;
+            unsubscribe();
+            clearTimeout(timer);
+            resolve(snapshot);
+        };
+        const unsubscribe = supervisor.subscribe((event) => {
+            if (event.service.id !== id)
+                return;
+            if (event.type === 'ready' || event.type === 'exited' || event.type === 'stopped') {
+                finish(event.service);
+            }
+        });
+        const timer = setTimeout(() => finish(supervisor.get(id) ?? started.service), args.settleMs);
+        timer.unref?.();
+        // A service that finished between `start()` and this subscription (a crash
+        // inside 1 ms is not hypothetical) would otherwise wait out the whole window.
+        const now = supervisor.get(id);
+        if (now && now.status !== 'starting')
+            finish(now);
+    });
+    return renderServiceResult(settled, { ephemeral: args.ephemeral });
+}

package/dist/tools/fs-tools.d.ts

@@ -8,6 +8,7 @@
  */
 import { type AgentTool } from '@aragon-agent/core';
 import { type FilePatch } from './patch.js';
+import type { ProcSupervisorPort } from '../proc/types.js';
 export interface ToolDeps {
     getCwd: () => string;
     /**
@@ -35,6 +36,22 @@ export interface ToolDeps {
      * name, so a future long-running tool costs one call site.
      */
     recordOutput?: (toolCallId: string, chunk: string) => void;
+    /**
+     * The process supervisor, when background launches are on for this session
+     * (background-service-supervision §3.5).
+     *
+     * THE TWO-INTERFACE RULE ABOVE APPLIES VERBATIM, and this package has already
+     * made that mistake twice (`recordChange` in round 1, `recordOutput` in round
+     * 2): adding the field HERE alone type-checks and forwards nothing, so `bash`
+     * never sees a supervisor, every long-running command runs in the foreground
+     * exactly as it does today, and NOTHING ANYWHERE ERRORS. It must be added here
+     * AND forwarded in `tools/index.ts`.
+     *
+     * OPTIONAL: omitting it leaves `bash` byte-identical to the pre-feature build —
+     * no `background` property in its schema, no supervisor call, and the
+     * pre-feature description string (I-2).
+     */
+    procs?: ProcSupervisorPort;
 }
 export declare function makeReadFile(deps: ToolDeps): AgentTool;
 export declare function makeWriteFile(deps: ToolDeps): AgentTool;