@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/proc/classify.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Is this command one that does not exit on its own?
+ * (background-service-supervision §3.5.)
+ *
+ * PURE. No process, no filesystem, no clock — so the whole table below is
+ * enumerable by a test and readable by a reviewer in one screen.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A CONSERVATIVE ALLOWLIST OVER THE LEADING TOKEN AND SCRIPT NAME, NEVER A VERB
+ * HEURISTIC (R-1). The cost of a false positive is real: a build that is
+ * backgrounded returns before it finished, and the model reads a half-empty log
+ * as success. So `npm run build` and `npm test` must not match, and a chained
+ * command must not match at all — a chain's TAIL is what the model actually
+ * wants the result of.
+ */
+/**
+ * The classifier's table, exported so `classify.test.ts` can enumerate it and a
+ * reviewer can read it whole.
+ *
+ * Each pattern is anchored at the start of the (trimmed, env-prefix-stripped)
+ * command. `\b`-style boundaries are spelled explicitly because a bare `vite`
+ * must not match `vitest`.
+ */
+export declare const LONG_RUNNING_PATTERNS: readonly RegExp[];
+/**
+ * Does the command contain a TOP-LEVEL `&&`, `||`, `;` or `|`?
+ *
+ * "Top level" means outside quotes: `echo "a && b"` is one command. Anything
+ * quoted is skipped, which is enough for the judgement being made here — this
+ * decides whether to REFUSE to background, so an over-eager reading is the safe
+ * direction.
+ */
+export declare function hasTopLevelChain(command: string): boolean;
+/**
+ * Would this command sit there rather than exiting?
+ *
+ * FALSE FOR ANYTHING CHAINED, unconditionally and before the table is consulted.
+ */
+export declare function looksLongRunning(command: string): boolean;
+/**
+ * The port the command asks for, when it names one.
+ *
+ * Used ONLY to enable the probe detector, so a miss is free (the URL detector
+ * still runs) and a wrong hit is bounded by the pre-flight probe: a port that
+ * already answers before we spawn disables the detector entirely rather than
+ * declaring every launch instantly ready.
+ *
+ * `--port N`, `--port=N`, `-p N`, `PORT=N`, and a `:N` suffix on a host in the
+ * command text (`php -S 127.0.0.1:8080`).
+ */
+export declare function extractPortHint(command: string): number | undefined;

package/dist/proc/classify.js

@@ -0,0 +1,143 @@
+/**
+ * Is this command one that does not exit on its own?
+ * (background-service-supervision §3.5.)
+ *
+ * PURE. No process, no filesystem, no clock — so the whole table below is
+ * enumerable by a test and readable by a reviewer in one screen.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A CONSERVATIVE ALLOWLIST OVER THE LEADING TOKEN AND SCRIPT NAME, NEVER A VERB
+ * HEURISTIC (R-1). The cost of a false positive is real: a build that is
+ * backgrounded returns before it finished, and the model reads a half-empty log
+ * as success. So `npm run build` and `npm test` must not match, and a chained
+ * command must not match at all — a chain's TAIL is what the model actually
+ * wants the result of.
+ */
+/**
+ * The classifier's table, exported so `classify.test.ts` can enumerate it and a
+ * reviewer can read it whole.
+ *
+ * Each pattern is anchored at the start of the (trimmed, env-prefix-stripped)
+ * command. `\b`-style boundaries are spelled explicitly because a bare `vite`
+ * must not match `vitest`.
+ */
+export const LONG_RUNNING_PATTERNS = Object.freeze([
+    // Package-manager scripts whose NAME says "does not exit".
+    /^(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|watch|preview)(?:\s|$)/i,
+    // Node/JS dev servers and bundlers in watch mode.
+    /^next\s+(?:dev|start)(?:\s|$)/i,
+    /^vite(?:\s|$)/i,
+    /^nuxt\s+dev(?:\s|$)/i,
+    /^astro\s+dev(?:\s|$)/i,
+    /^remix\s+dev(?:\s|$)/i,
+    /^ng\s+serve(?:\s|$)/i,
+    /^webpack\s+serve(?:\s|$)/i,
+    /^nodemon(?:\s|$)/i,
+    /^tsc\s+(?:--watch|-w)(?:\s|$)/i,
+    /^(?:serve|http-server)(?:\s|$)/i,
+    // Python.
+    /^uvicorn(?:\s|$)/i,
+    /^gunicorn(?:\s|$)/i,
+    /^hypercorn(?:\s|$)/i,
+    /^flask\s+run(?:\s|$)/i,
+    /^python[0-9.]*\s+(?:\S*[\\/])?manage\.py\s+runserver(?:\s|$)/i,
+    /^python[0-9.]*\s+-m\s+http\.server(?:\s|$)/i,
+    // Ruby / PHP / Rust.
+    /^rails\s+(?:server|s)(?:\s|$)/i,
+    /^php\s+-S(?:\s|$)/i,
+    /^cargo\s+watch(?:\s|$)/i,
+    // Containers. `up` WITHOUT `-d` only; the `-d` form is checked below.
+    /^docker(?:\s+compose|-compose)\s+up(?:\s|$)/i,
+    // Plain watchers.
+    /^tail\s+-f(?:\s|$)/i,
+    /^watch\s+/i,
+]);
+/** `docker compose up -d` returns on its own, so it is a foreground command. */
+const DOCKER_DETACHED = /(?:^|\s)(?:-d|--detach)(?:\s|$)/i;
+/**
+ * A leading `KEY=value ` run of assignments, which POSIX shells accept and which
+ * would otherwise hide the real leading token (`PORT=5173 vite`).
+ */
+const ENV_PREFIX = /^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)+/;
+/** Strip a leading env-assignment run, so the table can anchor on the command. */
+function stripEnvPrefix(command) {
+    return command.replace(ENV_PREFIX, '');
+}
+/**
+ * Does the command contain a TOP-LEVEL `&&`, `||`, `;` or `|`?
+ *
+ * "Top level" means outside quotes: `echo "a && b"` is one command. Anything
+ * quoted is skipped, which is enough for the judgement being made here — this
+ * decides whether to REFUSE to background, so an over-eager reading is the safe
+ * direction.
+ */
+export function hasTopLevelChain(command) {
+    let quote = null;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === ';')
+            return true;
+        // A lone `|` is a pipe and `||` is an or; both disqualify. So does `&`, in
+        // BOTH of its readings: `&&` is a chain, and a trailing single `&` is the
+        // manual-detach the prompt block bans - whatever it backgrounds, we cannot
+        // supervise. One branch each, because the two `&` cases have one answer.
+        if (ch === '|' || ch === '&')
+            return true;
+    }
+    return false;
+}
+/**
+ * Would this command sit there rather than exiting?
+ *
+ * FALSE FOR ANYTHING CHAINED, unconditionally and before the table is consulted.
+ */
+export function looksLongRunning(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (hasTopLevelChain(trimmed))
+        return false;
+    const bare = stripEnvPrefix(trimmed);
+    if (/^docker(?:\s+compose|-compose)\s+up(?:\s|$)/i.test(bare) && DOCKER_DETACHED.test(bare)) {
+        return false;
+    }
+    return LONG_RUNNING_PATTERNS.some((re) => re.test(bare));
+}
+/**
+ * The port the command asks for, when it names one.
+ *
+ * Used ONLY to enable the probe detector, so a miss is free (the URL detector
+ * still runs) and a wrong hit is bounded by the pre-flight probe: a port that
+ * already answers before we spawn disables the detector entirely rather than
+ * declaring every launch instantly ready.
+ *
+ * `--port N`, `--port=N`, `-p N`, `PORT=N`, and a `:N` suffix on a host in the
+ * command text (`php -S 127.0.0.1:8080`).
+ */
+export function extractPortHint(command) {
+    const candidates = [
+        /(?:^|\s)--port[=\s]+(\d{1,5})(?:\s|$)/i,
+        /(?:^|\s)-p[=\s]+(\d{1,5})(?:\s|$)/,
+        /(?:^|\s)PORT=(\d{1,5})(?:\s|$)/,
+        /(?:^|\s)\S*?:(\d{2,5})(?:\s|$)/,
+    ];
+    for (const re of candidates) {
+        const m = re.exec(command);
+        if (!m || !m[1])
+            continue;
+        const port = Number.parseInt(m[1], 10);
+        if (Number.isFinite(port) && port > 0 && port <= 65535)
+            return port;
+    }
+    return undefined;
+}

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