@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/agent/controller.js

@@ -20,6 +20,11 @@ import { TeamHumanQueue } from '../team/human-queue.js';
 import { createTaskTool } from '../team/task-tool.js';
 import { buildTeamBlock } from '../team/prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
+import { ProcSupervisor } from '../proc/supervisor.js';
+import { buildBackgroundServicesBlock } from '../proc/prompt.js';
+import { PROC_LIMITS } from '../proc/limits.js';
+import { makeBashKill, makeBashOutput } from '../tools/proc-tools.js';
+import { addSignalHook } from '../logging/install.js';
 import { describeFastTierProblem, fastProviderOf, resolveFastTier } from '../fast/resolve.js';
 import { FastWiring, offFastStatus } from '../fast/wiring.js';
 import { CompactionWiring, offCompactionSnapshot } from '../compaction/wiring.js';
@@ -33,6 +38,15 @@ import { createNodeSkillHost } from '../skills/node-host.js';
 import { SkillService } from '../skills/service.js';
 import { createSkillTools } from '../skills/tools.js';
 import { buildSystemPrompt } from './system-prompt.js';
+/**
+ * Extra budget, on top of `PROC_LIMITS.killGraceMs`, that `prompt()` allows a
+ * force-stopped engine to unwind in before it starts a new run anyway (I-8).
+ *
+ * `bash`'s own kill grace is what a wedged foreground command costs; this covers
+ * the loop's own unwinding on top of it. Waiting FOREVER is not an option - a
+ * tool that never settles is exactly why rung two exists.
+ */
+const ENGINE_UNWIND_GRACE_MS = 3000;
 /** Approval gate used whenever there is provably no human to ask (headless). */
 export const DENY_ALL_APPROVAL = {
     canPrompt: () => false,
@@ -172,6 +186,48 @@ export class AgentController {
     // to subscribe to the Agent, and this class cannot do both in one step.
     // -----------------------------------------------------------------------
     compaction;
+    // -----------------------------------------------------------------------
+    // Background services (background-service-supervision §3.3 / §3.6)
+    //
+    // CONSTRUCTED UNCONDITIONALLY, and that is the one thing about this field that
+    // is easy to get wrong (P1-6 / D-9). `cfg.bash.background` gates the SERVICE
+    // half - the `background` tool param, `bash_output`/`bash_kill`, the prompt
+    // block, the status chip - and NEVER the foreground half, because G2 ("bash
+    // always settles") and G3 ("Esc, Esc always works, and the session stays
+    // usable") are promised unconditionally. Gating the whole supervisor on the
+    // flag would make rung two of the Esc ladder a silent no-op for every user who
+    // turned background services off.
+    //
+    // With the flag off it holds foreground pids, nothing else, and allocates no
+    // timers.
+    // -----------------------------------------------------------------------
+    procs;
+    /**
+     * The host's notice channel, kept so `prompt()`'s totality has somewhere to
+     * report to (I-8). Every other consumer reads `deps.notify` through a closure
+     * built in the constructor; this one is called from a method, which is why it
+     * needs a field.
+     */
+    notifyHostFn;
+    /** Whether the SERVICE half is on: tools, prompt block, `background` param. */
+    bashBackgroundRegistered;
+    /** Release the exit reaper. Called by `dispose()`. */
+    releaseSignalHook;
+    /**
+     * Bumped by `forceStop()`; captured by `App` when it subscribes to a run.
+     *
+     * THE VIEW AND THE ENGINE DELIBERATELY DISAGREE AFTER A FORCE-STOP (D-10 /
+     * I-7). Rung two dispatches `runEnd` locally so the composer is usable
+     * immediately, but the engine keeps unwinding and keeps EMITTING -
+     * `turn_start`, `tool_call_start`, `turn_end`, `agent_end` - and
+     * `runStart`/`turnStart` would set `status: 'running'` again, bouncing the
+     * view straight back out of the `idle` the user was just given and appending
+     * entries to a transcript they believe is finished. `App` drops every event
+     * whose generation is stale, which is the same shape as `abortRequested`
+     * above and exists for the same reason: the loop legitimately emits after an
+     * abort lands.
+     */
+    runGen = 0;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -290,6 +346,19 @@ export class AgentController {
         // reason the field's own comment gives: the binding below is spread
         // conditionally on it (§3.1.3 / P1-6).
         this.toolOutputs = config.liveToolOutput ? createToolOutputStore() : null;
+        // ALSO ABOVE `createBuiltinTools`, and UNCONDITIONAL - see the field's own
+        // comment. `readyTimeoutMs` is read through a closure rather than captured,
+        // so a live config change reaches the next service rather than the next
+        // launch of the CLI.
+        this.procs = new ProcSupervisor({ readyTimeoutMs: () => this.config.bash.readyTimeoutMs });
+        this.notifyHostFn = deps.notify;
+        this.bashBackgroundRegistered = config.bash.background;
+        // THE EXIT REAPER (G5 / P1-2 / R-10). An APPEND-ONLY hook rather than a
+        // second `setSignalTerminator`: that is a single slot `cli.tsx` already owns
+        // for the alternate-screen restore, and replacing it is the documented bug
+        // that leaves the user staring at a blank alternate screen. `reapSync` is
+        // the only entry point it calls, and it is synchronous end to end (I-9).
+        this.releaseSignalHook = addSignalHook(() => this.procs.reapSync());
         this.tools = createBuiltinTools({
             getCwd: () => this.cwd,
             // OWNED HERE, NOT IN `cli.tsx` (D-18): `createBuiltinTools` is called from
@@ -306,6 +375,28 @@ export class AgentController {
             ...(this.toolOutputs
                 ? { recordOutput: (id, chunk) => this.emitToolOutput('lead', id, chunk) }
                 : {}),
+            // THE SERVICE HALF, AND ONLY THE SERVICE HALF (P1-6 / I-2). With
+            // `bash.background: false` the options bag has no `procs` key at all, so
+            // `createBuiltinTools` adds no property to `deps`, `bash` gets its default
+            // `{}` second argument, and the tool is the pre-feature one: no
+            // `background` in its schema, the pre-feature description string, no
+            // supervisor call. The FOREGROUND half of `this.procs` is still live, and
+            // `forceStop()` still reaches it.
+            ...(this.bashBackgroundRegistered
+                ? {
+                    procs: this.procs,
+                    // Read LIVE for the reason every other closure in this bag is:
+                    // `aragon config set bash.autoBackground false` must take effect in
+                    // the running session.
+                    autoBackground: () => this.config.bash.autoBackground,
+                    startupSettleMs: () => this.config.bash.startupSettleMs,
+                    // D-15 / P1-8. `planInteractive` is the SAME signal `planTools`
+                    // already uses to decide that no overlay can be rendered, which is
+                    // exactly the question being asked here: can a card be drawn, and is
+                    // there a user who could keep a service alive?
+                    interactive: this.planInteractive,
+                }
+                : {}),
             confirmTools: config.confirmTools,
             // Routed through the same watchdog pause as the plan tools. This is a
             // pre-existing bug being fixed in passing: a `--confirm` user who took
@@ -345,6 +436,12 @@ export class AgentController {
                     }),
                 ]
                 : [],
+            // THROUGH THE FACTORY for the reason `teamTools` records below (P0-2), and
+            // empty when background services were off at construction - which leaves
+            // the array byte-identical to the pre-feature build (I-2).
+            procTools: this.bashBackgroundRegistered
+                ? [makeBashOutput({ supervisor: this.procs }), makeBashKill({ supervisor: this.procs })]
+                : [],
             // THROUGH THE FACTORY, NEVER APPENDED AFTERWARDS (D-15 / P0-1).
             // `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what
             // `createBuiltinTools` produces, so appending `task` here would turn that
@@ -612,6 +709,12 @@ export class AgentController {
                     review: this.config.fast.review,
                 })
                 : '',
+            // ONE FLAG, unlike team/todo's two: there is no live on/off switch for
+            // background services - `bash.background` is read once at construction,
+            // and the tools it registers cannot be unregistered (the `team.enabled` /
+            // `todo.enabled` rule). So the block is present exactly when the tools are,
+            // and can never advertise a capability the model does not have.
+            backgroundBlock: this.bashBackgroundRegistered ? buildBackgroundServicesBlock() : '',
             // Read from the FIELD on every rebuild, for the reason the field's own
             // comment gives. Empty everywhere but `aragon exec`, and `buildSystemPrompt`
             // splices it conditionally, so every existing prompt is byte-identical.
@@ -700,7 +803,64 @@ export class AgentController {
      * underlying promise so headless mode can await completion. `agent.prompt()`
      * never rejects, so callers must not treat resolution as success.
      */
-    prompt(text) {
+    async prompt(text) {
+        // I-8 - THIS METHOD NEVER REJECTS, AND THAT HAS TO BE A PROPERTY OF THE
+        // METHOD RATHER THAN A COMMENT ABOVE IT (P0-1).
+        //
+        // `App` calls this as `void controller.prompt(...)`, and
+        // `logging/install.ts` routes an `unhandledRejection` into `handleFatal`,
+        // which EXITS THE PROCESS. `Agent.prompt()` throws SYNCHRONOUSLY while
+        // `Agent.running` is true - so before the force-stop ladder existed this was
+        // merely nearly-true (the view was only ever idle when the engine was), and
+        // rung two makes the view idle while the engine is still unwinding. Without
+        // the wait and the guard below, "Esc, Esc, then type" would kill the CLI on
+        // the very screen this feature exists to rescue.
+        //
+        // TWO PARTS, BOTH REQUIRED. First WAIT the engine out, bounded, so the
+        // common case (the engine unwinds in a few hundred ms) starts a real run
+        // rather than reporting a failure. Then swallow anything that still escapes
+        // and surface it through the existing notify channel, because a message that
+        // cannot be started must produce a visible sentence - never a crash, and
+        // never silence.
+        if (this.agent.state.isRunning) {
+            this.abort();
+            await this.waitForEngineIdle();
+        }
+        try {
+            await this.startPrompt(text);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            getLogger().warn('agent', 'prompt_failed', { reason });
+            this.notifyHostFn?.('error', `Could not start the run: ${reason}`);
+        }
+    }
+    /**
+     * Wait for the engine to unwind, bounded.
+     *
+     * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
+     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * alone would hang here for as long as it hangs there. The budget is the two
+     * graces a wedged `bash` can legitimately spend, plus the executor's own.
+     */
+    waitForEngineIdle() {
+        const budget = PROC_LIMITS.killGraceMs + ENGINE_UNWIND_GRACE_MS;
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(finish, budget);
+            timer.unref?.();
+            void this.agent.waitForIdle().then(finish, finish);
+        });
+    }
+    /** The pre-round body of `prompt`, unchanged apart from being private. */
+    startPrompt(text) {
         // A new user message is a new intent, so the previous turn's tool ceiling
         // expires here and anything a slash command queued is promoted (D-G1 / D-G2).
         // This and `steer()` below are the ONLY two places a user message enters the
@@ -746,6 +906,115 @@ export class AgentController {
         // `App.tsx` records for `cancelPendingHuman()` on `agent_end`.
         this.teamRuntime?.abortAll();
     }
+    /**
+     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * (§3.6 / G3).
+     *
+     * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
+     *
+     *   1. `abort()` - everything it does today, unchanged.
+     *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
+     *      child. THIS is what actually unblocks a wedged `await tool.execute`;
+     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      precisely the tools that ignore it.
+     *   3. `runGen += 1` - so `App` can drop the events the engine will keep
+     *      emitting while it unwinds (I-7). Without it the view bounces straight
+     *      back out of the `idle` the user was just given.
+     *   4. IT DOES NOT TOUCH BACKGROUND SERVICES. `Esc` interrupts the AGENT;
+     *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
+     *      sentences and it is exactly the kind of thing a later reader will
+     *      "fix" by making this kill everything - which would mean a user who
+     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      had been working against for an hour. It is invariant I-4.
+     *
+     * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always
+     * constructed; with services off its foreground registry is all there is, and
+     * that is the half this method uses.
+     */
+    forceStop() {
+        this.abort();
+        const killed = this.procs.killForeground('force');
+        this.runGen += 1;
+        getLogger().info('agent', 'force_stop', { generation: this.runGen, killed });
+    }
+    /**
+     * The current run generation (I-7).
+     *
+     * `App` captures it when it subscribes to a run and drops every engine event
+     * whose generation is stale. Same shape as the `abortRequested` guard the fast
+     * reviewer already uses, and for the same reason: the loop legitimately emits
+     * after an abort lands.
+     */
+    get runGeneration() {
+        return this.runGen;
+    }
+    // -----------------------------------------------------------------------
+    // Background services (background-service-supervision §3.5 / §3.6)
+    // -----------------------------------------------------------------------
+    /** Whether `bash_output` / `bash_kill` are in `this.tools`. Fixed at construction. */
+    isBackgroundRegistered() {
+        return this.bashBackgroundRegistered;
+    }
+    /**
+     * Subscribe to the CLI-local `ProcEvent` stream.
+     *
+     * Returns a live unsubscribe even when services are off, because the
+     * supervisor exists either way - the contract `subscribeTeam` /
+     * `subscribeTodos` / `subscribeFast` / `subscribeToolOutput` already set. With
+     * services off nothing is ever emitted, so an unconditional subscription in
+     * `App` costs one `Set` entry.
+     */
+    subscribeProc(listener) {
+        return this.procs.subscribe(listener);
+    }
+    getServiceSnapshot(id) {
+        return this.procs.get(id);
+    }
+    listServices() {
+        return this.procs.list();
+    }
+    /** `starting | ready | running`. Drives the status chip and the Ctrl+C rung. */
+    liveServiceCount() {
+        return this.procs.liveCount();
+    }
+    readServiceLog(id, since) {
+        return this.procs.read(id, since);
+    }
+    /**
+     * Stop one service, or every service when `id` is `'all'`.
+     *
+     * The GRACEFUL ladder (`SIGTERM` -> `SIGKILL` after `stopGraceMs`), because
+     * this path has a live event loop to run it on. `reapServicesSync` is the
+     * other one, and it is the only one an exit path may use.
+     */
+    stopService(id) {
+        return this.procs.stop(id);
+    }
+    /**
+     * Rung one of `Ctrl+C`: stop every live service (§3.6 / G4).
+     *
+     * `force: true` means `reapSync()` SEMANTICS - immediate `SIGKILL`, no
+     * `stopGraceMs` - and is what `doExit` uses, because `doExit` awaits nothing
+     * and must not start (§3.6 step 3). The graceful ladder belongs to `Ctrl+C`,
+     * `bash_kill` and `/bg stop`.
+     */
+    stopAllServices(opts = {}) {
+        if (opts.force) {
+            this.procs.reapSync();
+            return Promise.resolve(this.procs.list());
+        }
+        return this.procs.stop('all');
+    }
+    /**
+     * The synchronous reaper (I-9).
+     *
+     * Exposed so `doExit` can call it without awaiting anything. It is also what
+     * the signal hook registered in the constructor calls, and it is idempotent -
+     * which it has to be, since a normal quit reaches it twice.
+     */
+    reapServicesSync() {
+        this.procs.reapSync();
+    }
     steer(text) {
         // Mid-run interjection: promote the queue, keep what is already in force
         // (D-G3). Clearing here would make "ask a follow-up" the way around the
@@ -938,6 +1207,11 @@ export class AgentController {
         this.teamRuntime?.dispose();
         this.fast?.dispose();
         this.compaction?.dispose();
+        // REAP BEFORE RELEASING THE HOOK, in that order: disposal is a teardown, and
+        // a service that outlives it has nothing left that could ever stop it.
+        this.procs.reapSync();
+        this.releaseSignalHook();
+        this.procs.dispose();
     }
     // -----------------------------------------------------------------------
     // Todo planning (todo-plan-execution §3.6a)

package/dist/agent/reducer.d.ts

@@ -16,6 +16,7 @@ import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '.
 import type { FastReview, FastSnapshot } from '../fast/types.js';
 import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger } from '../compaction/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
+import type { ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
@@ -274,6 +275,56 @@ export type Entry = {
         charsRemoved: number;
     };
     live: boolean;
+}
+/**
+ * One supervised background service (background-service-supervision §3.10).
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
+ *
+ * IT IS THE ONE LIVE CARD THAT DOES **NOT** BLOCK THE SETTLED BOUNDARY ONCE IT
+ * IS UP (D-11 / P0-4). Every other live clause in
+ * `Transcript.tsx::computeSettledCount` is bounded by an OPERATION — a
+ * dispatch, a turn, one LLM call, one countdown — and each carries a comment
+ * saying that an entry which never settles is re-rendered on every frame for
+ * the rest of the session. A service is bounded by the USER'S INTENT: a dev
+ * server left up for an hour is the normal case. So only `starting` blocks
+ * (bounded by `readyTimeoutMs`), a `ready`/`running` card commits its body to
+ * `<Static>`, and a later terminal transition appends a NEW one-row entry
+ * rather than trying to rewrite a card `<Static>` has already printed.
+ *
+ * `terminal: true` marks that second entry. `session/persist.ts` rewrites any
+ * restored non-terminal card to `stopped`, next to `team.active`, `todo.live`,
+ * the retry phase, `fast.live` and `compaction.live`, and for the identical
+ * reason.
+ */
+ | {
+    id: string;
+    kind: 'service';
+    /** `s1`, `s2`, ... — the id the model quotes back. */
+    serviceId: string;
+    command: string;
+    status: ServiceStatus;
+    url?: string;
+    port?: number;
+    exitCode: number | null;
+    startedAt: number;
+    readyAt?: number;
+    endedAt?: number;
+    rows: readonly string[];
+    /**
+     * MONOTONIC row cursor — the revision term, NEVER `rows.length` (P0-3).
+     *
+     * The tail is a FIXED-SIZE RING: it evicts its oldest row while appending
+     * a new one, so the joined length is unchanged while the content is not.
+     * That is verbatim the non-append mutation the `tool` branch's `liveSeq`
+     * comment was written for, and a length term would go on matching while
+     * the card changed underneath it.
+     */
+    rowsSeen: number;
+    /** The one-row entry a terminal transition appends (D-11). */
+    terminal?: boolean;
+    /** The stop reported the pid still alive afterwards (R-2 / P2-6). */
+    killIncomplete?: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
@@ -606,6 +657,24 @@ export type ViewAction = {
  | {
     type: 'contextTokensEstimated';
     tokens: number;
+} | {
+    type: 'serviceStart';
+    service: ServiceSnapshot;
+} | {
+    type: 'serviceUpdate';
+    service: ServiceSnapshot;
+}
+/**
+ * A service reached a terminal state.
+ *
+ * IT APPENDS A NEW ONE-ROW ENTRY rather than rewriting the card (D-11). The
+ * card may already have been printed into `<Static>`, and `<Static>` cannot
+ * un-print — so any design that rewrites a printed card is wrong whatever it
+ * claims. A second event at a second time is also simply more honest.
+ */
+ | {
+    type: 'serviceEnd';
+    service: ServiceSnapshot;
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;

package/dist/agent/reducer.js

@@ -1005,6 +1005,12 @@ export function viewReducer(state, action) {
         case 'fastTier':
             return { ...state, fast: action.snapshot };
         // --- Context compaction (context-auto-compaction §5.5) ----------------
+        // NOT A TOTAL FUNCTION OVER COMPACTION ATTEMPTS (quiet-noop §3.1). A
+        // `pressure` compaction that declines before calling a model or changing the
+        // history dispatches NOTHING - no `compactionStart`, no `compactionEnd`, no
+        // entry - exactly as a checkpoint below the threshold dispatches nothing.
+        // Counting cards here counts compactions that RAN, never checkpoints that
+        // fired; `/compact status` and the diagnostic log are where the attempts are.
         case 'compactionStart': {
             const { id, seq } = nextId(state);
             let entries = state.entries;
@@ -1317,10 +1323,104 @@ export function viewReducer(state, action) {
                 fastEntryId: undefined,
             };
         }
+        // --- Background services (§3.10 / D-11) -----------------------------
+        case 'serviceStart': {
+            const { id, seq } = nextId(state);
+            const entry = { id, ...serviceFields(action.service) };
+            const appended = appendEntry(state, state.entries, entry);
+            return {
+                ...state,
+                seq,
+                entries: appended.entries,
+                droppedEntries: appended.droppedEntries,
+            };
+        }
+        /**
+         * Rewrite the LIVE card in place.
+         *
+         * SAFE ONLY BECAUSE OF D-11'S OTHER HALF: a `ready` / `running` card has
+         * reached `<Static>` and cannot be re-printed, so `serviceEnd` appends a new
+         * entry instead of routing through here. What this handles is the window in
+         * which the card is still in the live region — `starting`, and the one
+         * transition out of it — plus the output tail while it is there.
+         *
+         * The lookup is by `serviceId` and SKIPS terminal entries, so a stray update
+         * cannot rewrite the one-row record `serviceEnd` appended.
+         */
+        case 'serviceUpdate': {
+            const target = findServiceEntryId(state, action.service.id);
+            if (!target)
+                return state;
+            return {
+                ...state,
+                entries: mapEntry(state.entries, target, (e) => e.kind === 'service' ? { ...e, ...serviceFields(action.service) } : e),
+            };
+        }
+        /**
+         * A service reached a terminal state.
+         *
+         * TWO WRITES, AND BOTH ARE REQUIRED. The live card is settled in place so
+         * `computeSettledCount` can move past it and `estimateEntryRows` stops
+         * charging for a tail nothing will add to; the NEW one-row entry is what the
+         * user actually reads, because the card may already be printed into
+         * `<Static>` and `<Static>` cannot un-print (D-11 / R-13).
+         */
+        case 'serviceEnd': {
+            const target = findServiceEntryId(state, action.service.id);
+            const settled = target
+                ? mapEntry(state.entries, target, (e) => e.kind === 'service' ? { ...e, ...serviceFields(action.service) } : e)
+                : state.entries;
+            const { id, seq } = nextId(state);
+            const appended = appendEntry(state, settled, {
+                id,
+                ...serviceFields(action.service),
+                terminal: true,
+            });
+            return {
+                ...state,
+                seq,
+                entries: appended.entries,
+                droppedEntries: appended.droppedEntries,
+            };
+        }
         default:
             return state;
     }
 }
+/**
+ * Project a supervisor snapshot onto the entry's own fields.
+ *
+ * ONE PROJECTION FOR ALL THREE ACTIONS, so a field that reaches the card through
+ * `serviceStart` can never fail to reach it through `serviceUpdate` — the kind of
+ * asymmetry that produces a card frozen at its first values with nothing
+ * reporting it.
+ */
+function serviceFields(service) {
+    return {
+        kind: 'service',
+        serviceId: service.id,
+        command: service.command,
+        status: service.status,
+        ...(service.url !== undefined ? { url: service.url } : {}),
+        ...(service.port !== undefined ? { port: service.port } : {}),
+        exitCode: service.exitCode,
+        startedAt: service.startedAt,
+        ...(service.readyAt !== undefined ? { readyAt: service.readyAt } : {}),
+        ...(service.endedAt !== undefined ? { endedAt: service.endedAt } : {}),
+        rows: service.rows,
+        rowsSeen: service.rowsSeen,
+        ...(service.killIncomplete ? { killIncomplete: true } : {}),
+    };
+}
+/** The LIVE card for a service id, newest first; terminal records are skipped. */
+function findServiceEntryId(state, serviceId) {
+    for (let i = state.entries.length - 1; i >= 0; i -= 1) {
+        const e = state.entries[i];
+        if (e && e.kind === 'service' && e.serviceId === serviceId && !e.terminal)
+            return e.id;
+    }
+    return undefined;
+}
 function safeStringify(value) {
     try {
         return JSON.stringify(value);

package/dist/agent/system-prompt.d.ts

@@ -88,6 +88,20 @@ export interface SystemPromptParams {
      * for a fixed `tools` array. Every existing caller passes nothing.
      */
     appendSystemPrompt?: string;
+    /**
+     * The rendered `<background_services>` block, or `''`
+     * (background-service-supervision §5.2).
+     *
+     * Spliced conditionally exactly as `skillsBlock`, the plan block, `teamBlock`,
+     * `todoBlock` and `fastBlock` are, which is what keeps I-2 true:
+     * `bash.background: false` produces the pre-feature prompt BYTE FOR BYTE for a
+     * fixed tool array.
+     *
+     * A CHILD'S PROMPT NEVER CARRIES IT: subagents build tools from the same
+     * factory but are given no supervisor, so telling one about `bash_output` /
+     * `bash_kill` would describe tools it does not have.
+     */
+    backgroundBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -41,6 +41,7 @@ export function buildSystemPrompt(params) {
     const subagentBlock = params.subagentBlock ?? '';
     const todoBlock = params.todoBlock ?? '';
     const fastBlock = params.fastBlock ?? '';
+    const backgroundBlock = params.backgroundBlock ?? '';
     const appended = (params.appendSystemPrompt ?? '').trim();
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
@@ -59,6 +60,7 @@ export function buildSystemPrompt(params) {
         ...(subagentBlock ? ['', subagentBlock] : []),
         ...(todoBlock ? ['', todoBlock] : []),
         ...(fastBlock ? ['', fastBlock] : []),
+        ...(backgroundBlock ? ['', backgroundBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',