@aragon-agent/cli 0.6.2 → 0.6.4

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;
+}

package/dist/proc/readiness.js

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+import net from 'node:net';
+import { PROC_LIMITS } from './limits.js';
+/**
+ * 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 const READY_URL_RE = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|::1)(?::(\d{1,5}))?(\/\S*)?/i;
+/**
+ * Servers that announce a bare port instead of a URL.
+ *
+ * A SEPARATE, SMALLER LIST rather than more alternation in the URL pattern: what
+ * these produce is a PORT and no URL, which is a different result shape and a
+ * different confirmation path (the probe must succeed before anything flips).
+ */
+const PORT_PHRASES = Object.freeze([
+    /listening on (?:port )?(\d{2,5})\b/i,
+    /server running at .*?:(\d{2,5})\b/i,
+    /started server on .*?:(\d{2,5})\b/i,
+    /\bLocal:\s+\S*?:(\d{2,5})\b/i,
+]);
+/**
+ * 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 function normalizeHost(url) {
+    return url
+        .replace(/:\/\/0\.0\.0\.0/i, '://127.0.0.1')
+        .replace(/:\/\/\[::1\]/i, '://127.0.0.1')
+        .replace(/:\/\/::1/i, '://127.0.0.1');
+}
+/**
+ * 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 function detectReadyUrl(rows) {
+    for (const row of rows) {
+        const m = READY_URL_RE.exec(row);
+        if (m) {
+            const url = normalizeHost(m[0]);
+            const port = m[1] ? Number.parseInt(m[1], 10) : undefined;
+            return port === undefined ? { url } : { url, port };
+        }
+    }
+    for (const row of rows) {
+        for (const re of PORT_PHRASES) {
+            const m = re.exec(row);
+            if (!m || !m[1])
+                continue;
+            const port = Number.parseInt(m[1], 10);
+            if (Number.isFinite(port) && port > 0 && port <= 65535)
+                return { port };
+        }
+    }
+    return 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 function probePort(port, host = '127.0.0.1', timeoutMs = PROC_LIMITS.probeSocketTimeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (answered) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve(answered);
+        };
+        const socket = new net.Socket();
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+        try {
+            socket.connect(port, host);
+            socket.unref();
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+/**
+ * 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 class ReadinessWatcher {
+    opts;
+    timer;
+    deadline;
+    finished = false;
+    probing = false;
+    probeFn;
+    constructor(opts) {
+        this.opts = opts;
+        this.probeFn = opts.probe ?? ((port) => probePort(port));
+    }
+    start() {
+        if (this.finished)
+            return;
+        this.deadline = setTimeout(() => {
+            if (this.finished)
+                return;
+            this.stop();
+            this.opts.onTimeout();
+        }, this.opts.readyTimeoutMs);
+        this.deadline.unref?.();
+        const hint = this.opts.portHint;
+        if (hint === undefined)
+            return;
+        this.timer = setInterval(() => {
+            if (this.finished || this.probing)
+                return;
+            this.probing = true;
+            void this.probeFn(hint)
+                .then((answered) => {
+                this.probing = false;
+                if (!answered || this.finished)
+                    return;
+                this.settle({ port: hint, url: `http://127.0.0.1:${hint}`, detectedBy: 'probe' });
+            })
+                .catch(() => {
+                this.probing = false;
+            });
+        }, PROC_LIMITS.probeIntervalMs);
+        this.timer.unref?.();
+    }
+    /**
+     * 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) {
+        if (this.finished || rows.length === 0)
+            return;
+        const hit = detectReadyUrl(rows);
+        if (!hit)
+            return;
+        if (hit.port === undefined) {
+            this.settle({ ...(hit.url ? { url: hit.url } : {}), detectedBy: 'url' });
+            return;
+        }
+        const port = hit.port;
+        void this.probeFn(port)
+            .then((answered) => {
+            if (!answered || this.finished)
+                return;
+            this.settle({
+                port,
+                url: hit.url ?? `http://127.0.0.1:${port}`,
+                detectedBy: 'url',
+            });
+        })
+            .catch(() => {
+            /* a refused connect is not an error; it just is not ready yet */
+        });
+    }
+    stop() {
+        this.finished = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        if (this.deadline)
+            clearTimeout(this.deadline);
+        this.timer = undefined;
+        this.deadline = undefined;
+    }
+    settle(result) {
+        if (this.finished)
+            return;
+        this.stop();
+        this.opts.onReady(result);
+    }
+}

package/dist/proc/supervisor.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ProcSupervisor — the owner of every child process this session spawned
+ * (background-service-supervision §3.3 / §3.5 / §3.6).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * ONE REGISTRY, TWO LIFETIMES (I-4). Foreground `bash` children are tracked so
+ * `forceStop()` can reach them; background services are tracked so `Ctrl+C`,
+ * `bash_kill` and process exit can reach them. Splitting those into two
+ * registries is how a force-stop ends up killing the user's dev server, or how a
+ * quit leaves it running. They are two collections in ONE object, and the two
+ * kill entry points are named for which one they own.
+ *
+ * CONSTRUCTED UNCONDITIONALLY (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") are promised
+ * unconditionally. With the flag off this object holds foreground pids, nothing
+ * else, and allocates no timers.
+ */
+import { type ProcEventListener, type ProcSupervisorPort, type ServiceLogPage, type ServiceSnapshot, type ServiceStartRequest, type ServiceStartResult } from './types.js';
+export interface ProcSupervisorOptions {
+    /** `cfg.bash.readyTimeoutMs`, read once per service at spawn. */
+    readyTimeoutMs: () => number;
+    /** Injected by the tests; production uses a real TCP connect. */
+    probe?: (port: number) => Promise<boolean>;
+}
+export declare class ProcSupervisor implements ProcSupervisorPort {
+    private readonly opts;
+    private readonly services;
+    /**
+     * Live FOREGROUND `bash` children, by pid.
+     *
+     * A `Set` of pids rather than of `ChildProcess` objects: the only thing
+     * `killForeground` needs is the number, and holding the object would keep a
+     * reference to a settled child's stdio for the life of the session.
+     */
+    private readonly foreground;
+    private readonly listeners;
+    private nextId;
+    private disposed;
+    constructor(opts: ProcSupervisorOptions);
+    trackForeground(pid: number | undefined): () => void;
+    /**
+     * Hard-kill every tracked foreground child. Returns how many were signalled.
+     *
+     * THIS IS WHAT ACTUALLY UNBLOCKS A WEDGED `await tool.execute` on rung two of
+     * the Esc ladder. It NEVER touches services: `Esc` interrupts the AGENT,
+     * `Ctrl+C` stops the SERVICES, and that asymmetry is the user's own two
+     * sentences (I-4). A later reader will want to "fix" this by making it kill
+     * everything; that is the bug, not the fix.
+     */
+    killForeground(_reason: 'force'): number;
+    start(req: ServiceStartRequest): Promise<ServiceStartResult>;
+    get(id: string): ServiceSnapshot | undefined;
+    list(): ServiceSnapshot[];
+    read(id: string, since?: number): ServiceLogPage | undefined;
+    liveCount(): number;
+    /**
+     * Stop one service, or every service.
+     *
+     * `SIGTERM` FIRST, `SIGKILL` AFTER `stopGraceMs` — the graceful ladder, which
+     * belongs here rather than in `reapSync` because this path has a live event
+     * loop to run it on. It then CHECKS `process.kill(pid, 0)` and records
+     * `killIncomplete` when the pid is still there (P2-6): an honest warning beats
+     * a silent leak, and `killTree` cannot know on its own whether it worked.
+     */
+    stop(id: string): Promise<ServiceSnapshot[]>;
+    private stopOne;
+    /**
+     * SYNCHRONOUS, TOTAL, IDEMPOTENT. The only entry point a signal hook,
+     * `process.on('exit')` or `handleFatal` may call.
+     *
+     * No escalation ladder, no promises, no logging: a reaper that can block or
+     * throw is worse than one that misses a child. It reaps FOREGROUND children
+     * too, because a `bash` call in flight at quit time is a process nobody else
+     * will ever kill.
+     */
+    reapSync(): void;
+    dispose(): void;
+    subscribe(listener: ProcEventListener): () => void;
+    /**
+     * EVERY LISTENER IS WRAPPED, and that is not defensive noise (I-5). This runs
+     * inside `child.stdout.on('data')`, so a throw here would kill a ten-minute
+     * build because of a render bug. `debug` rather than `warn` because a listener
+     * that throws once throws on every chunk — the same rule, the same reason, as
+     * `AgentController.emitToolOutput`.
+     */
+    private emit;
+    /** Coalesce `output` at the SOURCE — `/bg` and `bash_output` read it too. */
+    private scheduleOutput;
+    /** Release every timer, wake every waiter, and announce the terminal state. */
+    private finish;
+    /**
+     * Evict TERMINAL records only, oldest first, to make room.
+     *
+     * IDS ARE NEVER REUSED (I-6): `nextId` only ever increases, so a stale
+     * `bash_kill({ service: 's1' })` can only be a no-op and never a kill of
+     * something else.
+     */
+    private evictTerminal;
+    private snapshot;
+}