@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/proc/kill-tree.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Killing a process TREE, on both platform families
+ * (background-service-supervision §3.5 / P1-1 / P1-2).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * ONE OWNER FOR BOTH KINDS OF CHILD. This was `bash-tool.ts`'s private helper;
+ * hoisting it is what lets a foreground `bash` child and a supervised service be
+ * reaped by the same code, which is the only way "no service outlives the CLI"
+ * can be true on every exit path.
+ *
+ * THE POSIX BRANCH IS A PROCESS-GROUP KILL, NOT `child.kill()` (P1-1). With
+ * `shell: true` the direct child is the shell wrapper, and `npm run dev` re-execs
+ * into node children that survive a signal aimed at the shell alone — which is
+ * why every `npm run dev` grandchild used to survive today's `killTree` on
+ * POSIX. `process.kill(-pid, sig)` reaches the whole group, and a group only
+ * EXISTS because `supervisor.ts` spawns with `detached: true` there. On Windows
+ * the flag is irrelevant to reaping: `taskkill /t` walks the parent-child table.
+ *
+ * THE SYNC VARIANT EXISTS BECAUSE `spawn` IS ASYNCHRONOUS (P1-2). A process that
+ * is already exiting will not live long enough for an async `taskkill`, and
+ * `process.on('exit')` permits only synchronous work — so the reaper an exit hook
+ * calls must be `spawnSync` end to end.
+ */
+/** Is the pid still there? `signal 0` tests for existence without delivering. */
+export declare function isAlive(pid: number | undefined): boolean;
+/**
+ * Kill the tree rooted at `pid`, asynchronously. Best-effort; never throws.
+ *
+ * `signal` is honoured on POSIX (so a graceful `SIGTERM` -> `SIGKILL` ladder is
+ * possible); Windows `taskkill /f` has no gentle mode, so a `SIGTERM` there is a
+ * plain `taskkill` without `/f` and the escalation adds it.
+ */
+export declare function killTree(pid: number | undefined, signal?: NodeJS.Signals): void;
+/**
+ * Kill the tree rooted at `pid`, SYNCHRONOUSLY. Never throws, never awaits.
+ *
+ * The only kill primitive a signal handler, `process.on('exit')` or
+ * `handleFatal` may reach (I-9). No escalation ladder and no logging: a reaper
+ * that can block or throw is worse than one that misses a child.
+ */
+export declare function killTreeSync(pid: number | undefined): void;

package/dist/proc/kill-tree.js

@@ -0,0 +1,119 @@
+/**
+ * Killing a process TREE, on both platform families
+ * (background-service-supervision §3.5 / P1-1 / P1-2).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * ONE OWNER FOR BOTH KINDS OF CHILD. This was `bash-tool.ts`'s private helper;
+ * hoisting it is what lets a foreground `bash` child and a supervised service be
+ * reaped by the same code, which is the only way "no service outlives the CLI"
+ * can be true on every exit path.
+ *
+ * THE POSIX BRANCH IS A PROCESS-GROUP KILL, NOT `child.kill()` (P1-1). With
+ * `shell: true` the direct child is the shell wrapper, and `npm run dev` re-execs
+ * into node children that survive a signal aimed at the shell alone — which is
+ * why every `npm run dev` grandchild used to survive today's `killTree` on
+ * POSIX. `process.kill(-pid, sig)` reaches the whole group, and a group only
+ * EXISTS because `supervisor.ts` spawns with `detached: true` there. On Windows
+ * the flag is irrelevant to reaping: `taskkill /t` walks the parent-child table.
+ *
+ * THE SYNC VARIANT EXISTS BECAUSE `spawn` IS ASYNCHRONOUS (P1-2). A process that
+ * is already exiting will not live long enough for an async `taskkill`, and
+ * `process.on('exit')` permits only synchronous work — so the reaper an exit hook
+ * calls must be `spawnSync` end to end.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import process from 'node:process';
+/** Is the pid still there? `signal 0` tests for existence without delivering. */
+export function isAlive(pid) {
+    if (pid === undefined || !Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists and belongs to somebody else, which for our purposes
+        // is still "alive" - reporting it dead would make the honest
+        // "may have left a detached child" warning silently unreachable.
+        return err?.code === 'EPERM';
+    }
+}
+/**
+ * Kill the tree rooted at `pid`, asynchronously. Best-effort; never throws.
+ *
+ * `signal` is honoured on POSIX (so a graceful `SIGTERM` -> `SIGKILL` ladder is
+ * possible); Windows `taskkill /f` has no gentle mode, so a `SIGTERM` there is a
+ * plain `taskkill` without `/f` and the escalation adds it.
+ */
+export function killTree(pid, signal = 'SIGKILL') {
+    if (pid === undefined || !Number.isFinite(pid) || pid <= 0)
+        return;
+    if (process.platform === 'win32') {
+        const args = ['/pid', String(pid), '/t'];
+        if (signal === 'SIGKILL')
+            args.push('/f');
+        try {
+            const child = spawn('taskkill', args, { windowsHide: true, stdio: 'ignore' });
+            // A reaper must never be the reason the CLI does not exit (I-3), and it
+            // must never crash it either: `taskkill` missing from PATH emits 'error'.
+            child.unref();
+            child.on('error', () => { });
+        }
+        catch {
+            /* ignore */
+        }
+        return;
+    }
+    // THE GROUP FIRST, THE PID SECOND. The group is what reaches the grandchild;
+    // the single-pid fallback covers a child that was NOT spawned detached (a
+    // foreground `bash` child), where `-pid` is not a group at all.
+    try {
+        process.kill(-pid, signal);
+        return;
+    }
+    catch {
+        /* fall through to the single-process attempt */
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * Kill the tree rooted at `pid`, SYNCHRONOUSLY. Never throws, never awaits.
+ *
+ * The only kill primitive a signal handler, `process.on('exit')` or
+ * `handleFatal` may reach (I-9). No escalation ladder and no logging: a reaper
+ * that can block or throw is worse than one that misses a child.
+ */
+export function killTreeSync(pid) {
+    if (pid === undefined || !Number.isFinite(pid) || pid <= 0)
+        return;
+    if (process.platform === 'win32') {
+        try {
+            spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], {
+                windowsHide: true,
+                stdio: 'ignore',
+                timeout: 2000,
+            });
+        }
+        catch {
+            /* ignore */
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}

package/dist/proc/limits.d.ts

@@ -0,0 +1,84 @@
+/**
+ * PROC_LIMITS — the single authority on every structural bound the process
+ * supervisor enforces (background-service-supervision §6).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), whose hardcoded directory regex this feature
+ * extends. A NEW TREE IS INVISIBLE TO THAT SCAN UNTIL IT IS NAMED THERE, and a
+ * guard rail that silently stops guarding is worse than no guard rail — this
+ * package has now paid for that edit eleven times.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE — the distinction
+ * `TODO_LIMITS` and `TEAM_LIMITS` each record at length:
+ *
+ *  - Everything below is STRUCTURAL: how many rows a tail can physically carry,
+ *    how many children one session may hold, how long a kill may take before it
+ *    stops being a kill. A user has no business tuning them, so they are
+ *    constants.
+ *  - The four `bash.*` config keys (`config/schema.ts`) are POLICY: register the
+ *    tools at all, let the classifier fire, how long a launch may block the
+ *    turn, how long to wait for readiness. They are clamped, persisted and
+ *    user-facing.
+ */
+export declare const PROC_LIMITS: {
+    /**
+     * Rows the per-service ring retains.
+     *
+     * DELIBERATELY A DIFFERENT NUMBER FROM `cardTailRows` BELOW, and from
+     * `LIVE_TAIL_ROWS` (8) in `tools/tool-output-store.ts`. They bound unrelated
+     * things — what `bash_output` can page back through, versus what one card
+     * draws — and a shared literal is how a later edit collapses two bounds into
+     * one.
+     */
+    readonly serviceTailRows: 200;
+    /** Rows a snapshot (and therefore a card) carries. */
+    readonly cardTailRows: 8;
+    /**
+     * Service RECORDS one session may hold.
+     *
+     * Eviction only ever removes a record in a TERMINAL state
+     * (`exited | failed | stopped`). When all 16 are live `start()` refuses and
+     * names the oldest ids rather than evicting: evicting a live record would
+     * orphan a running server that nothing can any longer name or stop.
+     */
+    readonly maxServices: 16;
+    /**
+     * How long `bash` waits after `'exit'` for the stdio streams to close before
+     * settling anyway.
+     *
+     * This number IS defence 1. `'close'` fires only once every stream is closed,
+     * and a detached grandchild that inherited the pipe keeps it open after the
+     * shell is long gone — so a tool that settles on `'close'` alone has a path
+     * that never settles at all.
+     */
+    readonly drainMs: 250;
+    /**
+     * How long an aborted/timed-out `bash` waits after the kill before settling
+     * WHETHER OR NOT the child ever reported exit.
+     *
+     * A pending promise after an abort is the bug; a possibly-premature result is
+     * not.
+     */
+    readonly killGraceMs: 2000;
+    /** Readiness port probe interval. */
+    readonly probeIntervalMs: 500;
+    /** Socket timeout for one readiness probe. */
+    readonly probeSocketTimeoutMs: 1000;
+    /**
+     * Output-event coalescing window inside the supervisor.
+     *
+     * At the SOURCE rather than in the view, because the same event is also
+     * consumed by `/bg` and by `bash_output`. A webpack build emitting thousands
+     * of lines a second must not become thousands of React renders.
+     */
+    readonly outputCoalesceMs: 100;
+    /** `SIGTERM` -> `SIGKILL` escalation window for a graceful stop. */
+    readonly stopGraceMs: 3000;
+    /** Below this many terminal columns the status chip degrades to `[N]`. */
+    readonly statusCompactCols: 92;
+};
+/**
+ * Bumped whenever the wording of the `<background_services>` block changes, so a
+ * behaviour report can be tied to a block revision with one grep.
+ */
+export declare const BACKGROUND_SERVICES_BLOCK_VERSION = "v1";

package/dist/proc/limits.js

@@ -0,0 +1,84 @@
+/**
+ * PROC_LIMITS — the single authority on every structural bound the process
+ * supervisor enforces (background-service-supervision §6).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), whose hardcoded directory regex this feature
+ * extends. A NEW TREE IS INVISIBLE TO THAT SCAN UNTIL IT IS NAMED THERE, and a
+ * guard rail that silently stops guarding is worse than no guard rail — this
+ * package has now paid for that edit eleven times.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE — the distinction
+ * `TODO_LIMITS` and `TEAM_LIMITS` each record at length:
+ *
+ *  - Everything below is STRUCTURAL: how many rows a tail can physically carry,
+ *    how many children one session may hold, how long a kill may take before it
+ *    stops being a kill. A user has no business tuning them, so they are
+ *    constants.
+ *  - The four `bash.*` config keys (`config/schema.ts`) are POLICY: register the
+ *    tools at all, let the classifier fire, how long a launch may block the
+ *    turn, how long to wait for readiness. They are clamped, persisted and
+ *    user-facing.
+ */
+export const PROC_LIMITS = {
+    /**
+     * Rows the per-service ring retains.
+     *
+     * DELIBERATELY A DIFFERENT NUMBER FROM `cardTailRows` BELOW, and from
+     * `LIVE_TAIL_ROWS` (8) in `tools/tool-output-store.ts`. They bound unrelated
+     * things — what `bash_output` can page back through, versus what one card
+     * draws — and a shared literal is how a later edit collapses two bounds into
+     * one.
+     */
+    serviceTailRows: 200,
+    /** Rows a snapshot (and therefore a card) carries. */
+    cardTailRows: 8,
+    /**
+     * Service RECORDS one session may hold.
+     *
+     * Eviction only ever removes a record in a TERMINAL state
+     * (`exited | failed | stopped`). When all 16 are live `start()` refuses and
+     * names the oldest ids rather than evicting: evicting a live record would
+     * orphan a running server that nothing can any longer name or stop.
+     */
+    maxServices: 16,
+    /**
+     * How long `bash` waits after `'exit'` for the stdio streams to close before
+     * settling anyway.
+     *
+     * This number IS defence 1. `'close'` fires only once every stream is closed,
+     * and a detached grandchild that inherited the pipe keeps it open after the
+     * shell is long gone — so a tool that settles on `'close'` alone has a path
+     * that never settles at all.
+     */
+    drainMs: 250,
+    /**
+     * How long an aborted/timed-out `bash` waits after the kill before settling
+     * WHETHER OR NOT the child ever reported exit.
+     *
+     * A pending promise after an abort is the bug; a possibly-premature result is
+     * not.
+     */
+    killGraceMs: 2000,
+    /** Readiness port probe interval. */
+    probeIntervalMs: 500,
+    /** Socket timeout for one readiness probe. */
+    probeSocketTimeoutMs: 1000,
+    /**
+     * Output-event coalescing window inside the supervisor.
+     *
+     * At the SOURCE rather than in the view, because the same event is also
+     * consumed by `/bg` and by `bash_output`. A webpack build emitting thousands
+     * of lines a second must not become thousands of React renders.
+     */
+    outputCoalesceMs: 100,
+    /** `SIGTERM` -> `SIGKILL` escalation window for a graceful stop. */
+    stopGraceMs: 3000,
+    /** Below this many terminal columns the status chip degrades to `[N]`. */
+    statusCompactCols: 92,
+};
+/**
+ * Bumped whenever the wording of the `<background_services>` block changes, so a
+ * behaviour report can be tied to a block revision with one grep.
+ */
+export const BACKGROUND_SERVICES_BLOCK_VERSION = 'v1';

package/dist/proc/log-ring.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The bounded, sanitised output tail one supervised service keeps
+ * (background-service-supervision §4).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * DELIBERATELY NOT `tools/tool-output-store.ts` (P2-4), which is the closest
+ * existing thing and would be the reflex merge. Three differences, each
+ * load-bearing:
+ *
+ *  - that store keeps 8 rows, this keeps 200 — one is what a card DRAWS, the
+ *    other is what `bash_output` can page back through;
+ *  - that store is cleared at `tool_execution_end`, and a service outlives by
+ *    minutes or hours the tool call that started it;
+ *  - that store has no cursor, and paging is the whole point of `since`.
+ *
+ * It reuses `sanitizeChunk` for the same reason that store does — the contract
+ * is "terminal-safe rows", and no consumer can forget — and it follows the same
+ * "two bounds are two different literals" rule.
+ */
+export interface LogRingPage {
+    rows: readonly string[];
+    /** Pass as the next `since`. */
+    cursor: number;
+    /** Rows between `since` and the first row returned were evicted. */
+    truncated: boolean;
+}
+/**
+ * A per-service ring.
+ *
+ * `rowsSeen` is the MONOTONIC count of completed rows ever appended, which is
+ * both the paging cursor and the transcript's revision term. It is deliberately
+ * not `rows.length`: the ring evicts while appending, so the length can be
+ * identical across two different tails.
+ */
+export declare class LogRing {
+    private readonly capacity;
+    private readonly rows;
+    private carry;
+    private seen;
+    private evicted;
+    constructor(capacity?: number);
+    /**
+     * Append a raw chunk; returns the rows it completed.
+     *
+     * The IN-PROGRESS line is NOT a row and is not counted: a command whose output
+     * is one continuously-rewritten line (every progress bar there is) would
+     * otherwise burn the whole ring on one logical line. It is rendered through
+     * `toDisplayRow` by `tail()` instead, so the display still shows it.
+     */
+    append(chunk: string): readonly string[];
+    /** The last `n` display rows, in-progress line included when non-empty. */
+    tail(n: number): readonly string[];
+    /** Every completed row plus the in-progress line. */
+    all(): readonly string[];
+    /** Completed rows ever appended — the paging cursor and the revision term. */
+    get rowsSeen(): number;
+    /** The ring has dropped at least one row. */
+    get truncated(): boolean;
+    /**
+     * Rows after cursor `since`, or the whole tail when `since` is omitted.
+     *
+     * `truncated` reports that the cursor FELL OFF the ring — the caller asked for
+     * row 3 and the oldest row still held is 57 — which is a real loss the model
+     * is entitled to be told about rather than have silently papered over.
+     */
+    page(since?: number): LogRingPage;
+}

package/dist/proc/log-ring.js

@@ -0,0 +1,102 @@
+/**
+ * The bounded, sanitised output tail one supervised service keeps
+ * (background-service-supervision §4).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * DELIBERATELY NOT `tools/tool-output-store.ts` (P2-4), which is the closest
+ * existing thing and would be the reflex merge. Three differences, each
+ * load-bearing:
+ *
+ *  - that store keeps 8 rows, this keeps 200 — one is what a card DRAWS, the
+ *    other is what `bash_output` can page back through;
+ *  - that store is cleared at `tool_execution_end`, and a service outlives by
+ *    minutes or hours the tool call that started it;
+ *  - that store has no cursor, and paging is the whole point of `since`.
+ *
+ * It reuses `sanitizeChunk` for the same reason that store does — the contract
+ * is "terminal-safe rows", and no consumer can forget — and it follows the same
+ * "two bounds are two different literals" rule.
+ */
+import { sanitizeChunk, toDisplayRow } from '../tools/terminal-output.js';
+import { PROC_LIMITS } from './limits.js';
+/**
+ * A per-service ring.
+ *
+ * `rowsSeen` is the MONOTONIC count of completed rows ever appended, which is
+ * both the paging cursor and the transcript's revision term. It is deliberately
+ * not `rows.length`: the ring evicts while appending, so the length can be
+ * identical across two different tails.
+ */
+export class LogRing {
+    capacity;
+    rows = [];
+    carry = '';
+    seen = 0;
+    evicted = 0;
+    constructor(capacity = PROC_LIMITS.serviceTailRows) {
+        this.capacity = capacity;
+    }
+    /**
+     * Append a raw chunk; returns the rows it completed.
+     *
+     * The IN-PROGRESS line is NOT a row and is not counted: a command whose output
+     * is one continuously-rewritten line (every progress bar there is) would
+     * otherwise burn the whole ring on one logical line. It is rendered through
+     * `toDisplayRow` by `tail()` instead, so the display still shows it.
+     */
+    append(chunk) {
+        const { rows, carry } = sanitizeChunk(this.carry, chunk);
+        this.carry = carry;
+        if (rows.length === 0)
+            return [];
+        this.rows.push(...rows);
+        this.seen += rows.length;
+        if (this.rows.length > this.capacity) {
+            const drop = this.rows.length - this.capacity;
+            this.rows.splice(0, drop);
+            this.evicted += drop;
+        }
+        return rows;
+    }
+    /** The last `n` display rows, in-progress line included when non-empty. */
+    tail(n) {
+        const live = toDisplayRow(this.carry);
+        const all = live.length > 0 ? [...this.rows, live] : this.rows;
+        return Object.freeze(all.length > n ? all.slice(-n) : [...all]);
+    }
+    /** Every completed row plus the in-progress line. */
+    all() {
+        return this.tail(this.capacity + 1);
+    }
+    /** Completed rows ever appended — the paging cursor and the revision term. */
+    get rowsSeen() {
+        return this.seen;
+    }
+    /** The ring has dropped at least one row. */
+    get truncated() {
+        return this.evicted > 0;
+    }
+    /**
+     * Rows after cursor `since`, or the whole tail when `since` is omitted.
+     *
+     * `truncated` reports that the cursor FELL OFF the ring — the caller asked for
+     * row 3 and the oldest row still held is 57 — which is a real loss the model
+     * is entitled to be told about rather than have silently papered over.
+     */
+    page(since) {
+        const oldest = this.seen - this.rows.length;
+        if (since === undefined || since < 0) {
+            return { rows: this.all(), cursor: this.seen, truncated: this.truncated };
+        }
+        const from = Math.max(since, oldest);
+        const rows = this.rows.slice(from - oldest);
+        const live = toDisplayRow(this.carry);
+        const withLive = live.length > 0 ? [...rows, live] : rows;
+        return {
+            rows: Object.freeze(withLive),
+            cursor: this.seen,
+            truncated: since < oldest,
+        };
+    }
+}

package/dist/proc/prompt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `<background_services>` system-prompt block
+ * (background-service-supervision §5.2).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope, and this string
+ * also reaches a model that may be running in a `cmd.exe` terminal.
+ *
+ * SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what preserves I-2:
+ * with `bash.background: false` the prompt is BYTE-IDENTICAL to the pre-feature
+ * output for a fixed tool array. An unconditional guidance line anywhere here
+ * would quietly break that, `--no-todo`, `--no-team` and `--no-skills` all at
+ * once.
+ *
+ * IT NAMES THE `[note]` SENTENCE VERBATIM. That line is the whole of defence 1
+ * as the model experiences it, and telling it what the words mean is the
+ * difference between "re-run with background: true" and reaching for
+ * `Start-Process` - which is exactly what produced the reported screenshot.
+ *
+ * `BACKGROUND_SERVICES_BLOCK_VERSION` exists so a change to this wording is
+ * greppable from a behaviour report.
+ */
+import { BACKGROUND_SERVICES_BLOCK_VERSION } from './limits.js';
+export { BACKGROUND_SERVICES_BLOCK_VERSION };
+export declare function buildBackgroundServicesBlock(): string;

package/dist/proc/prompt.js

@@ -0,0 +1,49 @@
+/**
+ * The `<background_services>` system-prompt block
+ * (background-service-supervision §5.2).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope, and this string
+ * also reaches a model that may be running in a `cmd.exe` terminal.
+ *
+ * SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what preserves I-2:
+ * with `bash.background: false` the prompt is BYTE-IDENTICAL to the pre-feature
+ * output for a fixed tool array. An unconditional guidance line anywhere here
+ * would quietly break that, `--no-todo`, `--no-team` and `--no-skills` all at
+ * once.
+ *
+ * IT NAMES THE `[note]` SENTENCE VERBATIM. That line is the whole of defence 1
+ * as the model experiences it, and telling it what the words mean is the
+ * difference between "re-run with background: true" and reaching for
+ * `Start-Process` - which is exactly what produced the reported screenshot.
+ *
+ * `BACKGROUND_SERVICES_BLOCK_VERSION` exists so a change to this wording is
+ * greppable from a behaviour report.
+ */
+import { BACKGROUND_SERVICES_BLOCK_VERSION } from './limits.js';
+export { BACKGROUND_SERVICES_BLOCK_VERSION };
+export function buildBackgroundServicesBlock() {
+    return [
+        '<background_services>',
+        'Some commands never exit on their own: dev servers, watchers, `docker compose up`,',
+        '`tail -f`. Running one in the foreground stalls the turn until the tool timeout',
+        'kills it, and you learn nothing.',
+        '',
+        'Rules:',
+        '- Set `background: true` on `bash` for anything that does not exit on its own.',
+        '  The call returns within a few seconds with a service id, a status, and a log tail.',
+        '- NEVER detach a command yourself with `Start-Process`, `&`, `nohup` or `screen`.',
+        '  A self-detached process cannot be reported on, read from, or stopped.',
+        '- A background result is PROVISIONAL. `ready` means a port answered or a URL was',
+        '  printed - it does not mean the app works. Verify with `bash_output({ service })`',
+        '  AND with an actual request against the URL (for example `curl -s <url>`).',
+        '- Read more output at any time with `bash_output({ service, since })`; `since` is the',
+        '  cursor returned by the previous call.',
+        '- Stop a service with `bash_kill({ service })`, or `bash_kill({ service: "all" })`,',
+        '  when you are finished with it - unless the user asked for it to stay up.',
+        '- If a foreground result ends with',
+        '  `[note] the command exited but a background child is still holding its output stream.`',
+        '  then the command detached something. Re-run it with `background: true`.',
+        '- Services are stopped when this CLI exits. They do not survive the session.',
+        '</background_services>',
+    ].join('\n');
+}

package/dist/proc/readiness.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Readiness detection (background-service-supervision §3.5).
+ *
+ * Two detectors, raced, first one wins:
+ *
+ *  - the URL detector, which is PURE and therefore testable without a socket;
+ *  - the port probe, which is one TCP connect and only runs when the command
+ *    text named a port.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * EVERY TIMER AND SOCKET HERE IS `unref()`d (I-3). Readiness detection must
+ * never be the reason the CLI does not exit; only the child processes themselves
+ * hold the loop open, and they are reaped on exit.
+ */
+/**
+ * A loopback/wildcard `http(s)` URL, with an optional port and path.
+ *
+ * ONE ANCHORED SOURCE OF TRUTH, and written out rather than assembled, because
+ * the obvious shorthand is not a regex at all: `[::1]` inside a pattern is a
+ * CHARACTER CLASS matching `:` or `1`, and unescaped dots match any character.
+ * Both mistakes read as correct.
+ */
+export declare const READY_URL_RE: RegExp;
+export interface ReadyUrlMatch {
+    /** Normalised so a human can click it; absent for a bare-port phrase. */
+    url?: string;
+    port?: number;
+}
+/**
+ * Normalise a wildcard/IPv6-loopback host to something clickable.
+ *
+ * `0.0.0.0` means "every interface", which a browser cannot open; `::1` and
+ * `[::1]` are correct but unfamiliar. All three become `127.0.0.1`.
+ */
+export declare function normalizeHost(url: string): string;
+/**
+ * The first readiness candidate in `rows`, or `undefined`.
+ *
+ * A MATCH IS A CANDIDATE, NOT A VERDICT (P2-2). A loopback URL printed in a
+ * banner or a `--help` blurb appears BEFORE anything binds, and a bare pattern
+ * would call that service ready in the first 40 ms. Two guards make the trade
+ * explicit, and neither lives here:
+ *
+ *   1. only rows emitted AFTER spawn are scanned (the ring starts empty, so this
+ *      is free), and
+ *   2. when the match yields a PORT, `ReadinessWatcher` confirms with one TCP
+ *      connect before the status flips.
+ *
+ * When the match yields no port the URL is accepted as-is: there is nothing to
+ * probe, and a hostname-only loopback URL in a banner is rare enough to trade
+ * against the complexity of guessing 80 vs 443.
+ */
+export declare function detectReadyUrl(rows: readonly string[]): ReadyUrlMatch | undefined;
+/**
+ * One TCP connect. Resolves `true` when something answered.
+ *
+ * Never rejects, and the socket is destroyed on every path — a probe that leaked
+ * a socket would hold the event loop open exactly as long as the service runs.
+ */
+export declare function probePort(port: number, host?: string, timeoutMs?: 1000): Promise<boolean>;
+export interface ReadinessResult {
+    url?: string;
+    port?: number;
+    detectedBy: 'url' | 'probe';
+}
+export interface ReadinessWatcherOptions {
+    /** From `extractPortHint`, and only when the pre-flight probe found it FREE. */
+    portHint?: number;
+    readyTimeoutMs: number;
+    onReady: (result: ReadinessResult) => void;
+    /** Alive past `readyTimeoutMs` with nothing detected (`tsc --watch` et al). */
+    onTimeout: () => void;
+    /** Injected for the tests; production passes nothing. */
+    probe?: (port: number) => Promise<boolean>;
+}
+/**
+ * Races the URL detector against the port probe and stops at the first hit.
+ *
+ * ONE SHOT. `stop()` is idempotent and is called from every terminal path, so a
+ * service that exits during the window leaves nothing behind.
+ */
+export declare class ReadinessWatcher {
+    private readonly opts;
+    private timer;
+    private deadline;
+    private finished;
+    private probing;
+    private readonly probeFn;
+    constructor(opts: ReadinessWatcherOptions);
+    start(): void;
+    /**
+     * Offer the rows emitted since the last call.
+     *
+     * A MATCH WITH A PORT IS CONFIRMED BY ONE CONNECT before the status flips; a
+     * refused connect leaves the service `starting` and the row is simply not
+     * re-considered on the next call, because the caller passes only NEW rows.
+     */
+    offerRows(rows: readonly string[]): void;
+    stop(): void;
+    private settle;
+}