@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/fast/summary-prompt.js

@@ -0,0 +1,320 @@
+/**
+ * The task-summary prompt, its output normalisation, the language check and the
+ * deterministic floor (tui-shortcut-drawer-and-task-summary §4.4 / §6.2).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope. Every string in
+ * this file is English prose that goes to the model or into a code branch; the
+ * only non-ASCII the runtime ever sees arrives from the USER's message, which is
+ * data, not a literal.
+ *
+ * THE FLOOR NEVER LIES (D-9). Nine failure modes converge on one function,
+ * `localTaskSummary`, which returns a normalised prefix of the user's own words.
+ * That is the one outcome that cannot be wrong: the language matches by
+ * construction, nothing is invented, and the header cell is never empty. A model
+ * label that disagrees with the user's language is treated as a failure rather
+ * than displayed, because a Chinese task shown to a Chinese user as English is
+ * worse than their own sentence clipped.
+ */
+import stringWidth from 'string-width';
+import { TASK_SUMMARY_LIMITS, TASK_SUMMARY_PROMPT_VERSION } from './limits.js';
+/**
+ * The system prompt. ONE template, versioned by `TASK_SUMMARY_PROMPT_VERSION` so
+ * a behaviour report can be tied to a wording revision with one grep.
+ *
+ * THE RULES ARE SHORT ON PURPOSE: a summary model that has to reason about its
+ * instructions spends the whole 64-token budget on them. Every line here
+ * corresponds to one branch in `interpretSummary`/`normalizeTaskSummary`, so
+ * nothing is asked for that the code cannot check.
+ */
+function buildSystemPrompt() {
+    return [
+        "You write a one-line label for the user's task, shown in a terminal header.",
+        `(prompt ${TASK_SUMMARY_PROMPT_VERSION})`,
+        '',
+        'Rules:',
+        '- Reply with the label ONLY. No quotes, no markdown, no trailing punctuation.',
+        "- Use the SAME LANGUAGE as the user's message.",
+        '- At most 6 words in space-separated languages; at most 12 characters for',
+        '  Chinese/Japanese/Korean.',
+        '- Describe what the user wants done, not how it will be done.',
+        '- Never invent details that are not in the message.',
+    ].join('\n');
+}
+/**
+ * Clip the anchor to `anchorMaxChars` and wrap it in `<task>`.
+ *
+ * THE WRAPPER IS NOT DECORATION: without it a prompt that says "ignore the above
+ * and reply OK" is indistinguishable from an instruction, and the one thing this
+ * feature must never do is turn a user's message into a second instruction
+ * channel for its own label. The tag tells the model where the data starts and
+ * ends.
+ */
+function buildUserMessage(anchor) {
+    const clipped = anchor.slice(0, TASK_SUMMARY_LIMITS.anchorMaxChars);
+    return `<task>\n${clipped}\n</task>`;
+}
+/**
+ * The request one summary sends. No tools, no thinking, one bounded message.
+ *
+ * `modelLimits` is deliberately NOT set: the fast path uses the same output-cap
+ * authority as every other call (`resolveOutputTokens`), and hand-setting a
+ * second ceiling here is how the two would drift.
+ */
+export function buildTaskSummaryRequest(input) {
+    return {
+        model: input.modelId,
+        ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
+        apiKey: input.apiKey,
+        systemPrompt: buildSystemPrompt(),
+        messages: [{ role: 'user', content: buildUserMessage(input.anchor), timestamp: input.now }],
+        maxTokens: TASK_SUMMARY_LIMITS.outputTokens,
+        // PAIRED WITH `temperature: 0`, exactly as `review-call.ts` records: the
+        // Anthropic adapter deletes `temperature` whenever a thinking budget is set,
+        // so these two are one choice and not two.
+        thinkingLevel: 'off',
+        temperature: 0,
+        ...(input.signal ? { signal: input.signal } : {}),
+    };
+}
+/** ESC plus one CSI sequence (colours, cursor moves, OSC titles end with BEL). */
+const ANSI_PATTERN = /\u001b\[[0-9;?]*[ -/]*[@-~]|\u001b\][^\u0007]*\u0007/g;
+/** A leading label prefix: `Label:`, `Task:`, `Summary:` in any case. */
+const LABEL_PREFIX = /^(?:label|task|summary)\s*[:\-]\s*/i;
+/** Characters that mark "this is the whole label", never part of it. */
+const WRAPPERS = ['"', "'", '`', '<task>', '</task>', '**'];
+/** SCRIPT-AWARE LETTER COUNTS. One pass, no regex per script, so `dominantScript` is cheap. */
+const CJK_RANGES = [
+    [0x3040, 0x30ff], // Hiragana + Katakana
+    [0x3400, 0x4dbf], // CJK Extension A
+    [0x4e00, 0x9fff], // CJK Unified Ideographs
+    [0xac00, 0xd7af], // Hangul syllables
+    [0xf900, 0xfaff], // CJK compatibility ideographs
+    [0xff66, 0xff9d], // Halfwidth katakana
+];
+function isCjkCodePoint(code) {
+    return CJK_RANGES.some(([lo, hi]) => code >= lo && code <= hi);
+}
+function isLatinLetter(code) {
+    return (code >= 0x41 && code <= 0x5a)
+        || (code >= 0x61 && code <= 0x7a)
+        // Latin-1 supplement, Latin Extended-A/B: accented European text is Latin.
+        || (code >= 0xc0 && code <= 0x24f && code !== 0xd7 && code !== 0xf7);
+}
+/**
+ * `cjk` | `latin` | `other`, by LETTER majority.
+ *
+ * DIGITS AND PUNCTUATION ARE NOT LETTERS (the spec's wording) - a message that is
+ * only `pwd`'s output would otherwise be classified by its spaces. `other` is a
+ * real answer, not a failure: it means "the language rule cannot be checked",
+ * and the caller treats it as "no opinion" instead of a mismatch.
+ */
+export function dominantScript(text) {
+    let cjk = 0;
+    let latin = 0;
+    for (const char of text) {
+        const code = char.codePointAt(0) ?? 0;
+        if (isCjkCodePoint(code))
+            cjk += 1;
+        else if (isLatinLetter(code))
+            latin += 1;
+    }
+    const letters = cjk + latin;
+    if (letters === 0)
+        return 'other';
+    if (cjk / letters >= 0.5)
+        return 'cjk';
+    if (latin / letters >= 0.5)
+        return 'latin';
+    return 'other';
+}
+/** Count grapheme-ish clusters: one per code point, which is what the prompt says. */
+function graphemes(text) {
+    return Array.from(text);
+}
+/**
+ * Clean one raw model reply into a displayable label.
+ *
+ * THE FIVE STEPS ARE SEPARATE AND IN THIS ORDER, so each is independently
+ * assertable (v2 P1-8):
+ *
+ *  1. strip ANSI escapes, then every remaining control character;
+ *  2. collapse every whitespace run (newlines included) to ONE space and trim;
+ *  3. strip a leading label prefix and any wrapping quotes / backticks / markers;
+ *  4. strip trailing punctuation, ASCII and CJK full-width;
+ *  5. cap by script - words to `summaryMaxWords` OR graphemes to
+ *     `cjkMaxGraphemes` - then hard-cap characters at `summaryMaxChars`.
+ *
+ * Returns `null` when nothing survives; the caller reports that as `bad-output`
+ * and falls back. A refusal ("I cannot help with that") normalises to a non-empty
+ * string, so the LANGUAGE check is what rejects it - which is why step 5 runs
+ * before step 6 in `interpretSummary` rather than here.
+ */
+export function normalizeTaskSummary(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    // 1. ANSI first: an escape sequence contains '[', ';' and a letter, so
+    //    stripping it later would leave parts of it behind as "words".
+    let text = raw.replace(ANSI_PATTERN, '');
+    // eslint-disable-next-line no-control-regex
+    text = text.replace(/[\u0000-\u001f\u007f]/g, ' ');
+    // 2. One line, no runs.
+    text = text.replace(/\s+/g, ' ').trim();
+    // 3. Prefix, then wrappers (a model may answer `"Task: fix the build"`).
+    text = text.replace(LABEL_PREFIX, '');
+    for (const wrapper of WRAPPERS) {
+        text = stripWrapper(text, wrapper);
+    }
+    text = text.trim().replace(/\s+/g, ' ');
+    // 4. Trailing punctuation, ASCII and the full-width forms the prompt forbids.
+    text = text.replace(/[.,;:!?]+$/u, '');
+    text = text.replace(/[\u3002\uff0c\uff1b\uff1a\uff01\uff1f\u3001]+$/gu, '');
+    text = text.trim();
+    if (text.length === 0)
+        return null;
+    // 5. Script-aware cap, then the character ceiling.
+    const span = dominantScript(text);
+    if (span === 'cjk') {
+        const chars = graphemes(text);
+        if (chars.length > TASK_SUMMARY_LIMITS.cjkMaxGraphemes) {
+            text = chars.slice(0, TASK_SUMMARY_LIMITS.cjkMaxGraphemes).join('');
+        }
+    }
+    else {
+        const words = text.split(' ');
+        if (words.length > TASK_SUMMARY_LIMITS.summaryMaxWords) {
+            text = words.slice(0, TASK_SUMMARY_LIMITS.summaryMaxWords).join(' ');
+        }
+    }
+    if (text.length > TASK_SUMMARY_LIMITS.summaryMaxChars) {
+        text = text.slice(0, TASK_SUMMARY_LIMITS.summaryMaxChars);
+    }
+    text = text.trim();
+    return text.length === 0 ? null : text;
+}
+/** Remove one wrapper character/sequence from both ends when present. */
+function stripWrapper(text, wrapper) {
+    let out = text;
+    if (out.startsWith(wrapper))
+        out = out.slice(wrapper.length);
+    if (out.endsWith(wrapper))
+        out = out.slice(0, out.length - wrapper.length);
+    return out.trim();
+}
+/**
+ * The deterministic floor: a normalised verbatim prefix of the anchor.
+ *
+ * WHY IT IS SCRIPT-AWARE: a CJK sentence has no spaces, so a word-based clip
+ * would keep the first 8 characters and add an ellipsis - unreadable. CJK is
+ * clipped by graphemes instead, which is the same unit the prompt constrains.
+ *
+ * THE ELLIPSIS IS PASSED IN (`glyphs.ellipsis`) because this module may not
+ * spell a non-ASCII glyph (the scanner's rule); the caller supplies the one the
+ * terminal can actually render.
+ */
+export function localTaskSummary(anchor, span, ellipsis) {
+    const flat = anchor.replace(/\s+/g, ' ').trim();
+    if (flat.length === 0)
+        return null;
+    const chars = graphemes(flat);
+    // CJK: `cjkMaxGraphemes` clusters, which is what a reader can scan in a header.
+    if (span === 'cjk') {
+        if (chars.length <= TASK_SUMMARY_LIMITS.cjkMaxGraphemes)
+            return flat;
+        return chars.slice(0, TASK_SUMMARY_LIMITS.cjkMaxGraphemes).join('') + ellipsis;
+    }
+    const words = flat.split(' ');
+    if (words.length <= TASK_SUMMARY_LIMITS.summaryMaxWords) {
+        const clipped = chars.length <= TASK_SUMMARY_LIMITS.summaryMaxChars
+            ? flat
+            : chars.slice(0, TASK_SUMMARY_LIMITS.summaryMaxChars).join('').trimEnd();
+        return clipped;
+    }
+    return words.slice(0, TASK_SUMMARY_LIMITS.summaryMaxWords).join(' ') + ellipsis;
+}
+/** The label as the reducer stores it: never wider than `maxCells`. */
+function fitLabel(text, ellipsis) {
+    if (stringWidth(text) <= TASK_SUMMARY_LIMITS.maxCells)
+        return text;
+    const mark = stringWidth(ellipsis) < TASK_SUMMARY_LIMITS.maxCells ? ellipsis : '';
+    const room = TASK_SUMMARY_LIMITS.maxCells - stringWidth(mark);
+    let out = '';
+    let used = 0;
+    for (const char of graphemes(text)) {
+        const width = stringWidth(char);
+        if (used + width > room)
+            break;
+        out += char;
+        used += width;
+    }
+    return `${out}${mark}`;
+}
+/** Build the fallback view, or `null` when the user switched the floor off. */
+export function fallbackView(input) {
+    if (!input.fallbackEnabled)
+        return { view: null };
+    const span = dominantScript(input.anchor);
+    const local = localTaskSummary(input.anchor, span, input.ellipsis);
+    if (local === null)
+        return { view: null };
+    return {
+        view: {
+            text: fitLabel(local, input.ellipsis),
+            tone: 'fallback',
+            reason: input.reason,
+            script: span,
+            at: input.now,
+            by: '',
+        },
+    };
+}
+/**
+ * Assemble the outcome from raw model text, applying D-9.
+ *
+ * ORDER MATTERS: normalise, then compare scripts, then decide. A model label in
+ * the wrong language is a FAILURE (`language-mismatch`), not something to
+ * display with a caveat - the fallback is the same length, in the right
+ * language, and true by construction.
+ *
+ * AND IT IS NOT RETRIED. A second call costs money and 1-3 seconds to reach an
+ * answer the fallback already gives correctly.
+ */
+export function interpretSummary(input) {
+    const normalised = normalizeTaskSummary(input.raw);
+    if (normalised === null) {
+        return fallbackView({ ...input, reason: 'bad-output' });
+    }
+    const anchorSpan = dominantScript(input.anchor);
+    const summarySpan = dominantScript(normalised);
+    // `other` NEVER MISMATCHES: a label with no letters at all cannot be in the
+    // wrong language, and refusing it would be a complaint the user cannot act on.
+    const mismatched = summarySpan !== 'other'
+        && anchorSpan !== 'other'
+        && summarySpan !== anchorSpan;
+    if (mismatched) {
+        return fallbackView({ ...input, reason: 'language-mismatch' });
+    }
+    return {
+        view: {
+            text: fitLabel(normalised, input.ellipsis),
+            tone: 'model',
+            reason: null,
+            script: anchorSpan,
+            at: input.now,
+            by: input.by,
+        },
+    };
+}
+/** The assistant text of a completion, or `''` for a tool-only answer. */
+export function summaryText(message) {
+    if (!message || !Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('')
+        .trim();
+}
+/** One model identity string, as the drawer's status line prints it. */
+export function summaryBy(providerId, modelId) {
+    return `${providerId}:${modelId}`;
+}

package/dist/fast/task-summary-types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The task-summary types (tui-shortcut-drawer-and-task-summary §6.1).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * WHY THIS FILE EXISTS AT ALL (v2 P1-3). `fast/summary-call.ts` and
+ * `fast/summary-prompt.ts` produce and consume these shapes, and the header cell,
+ * the reducer and the controller only display them. Declaring them in
+ * `agent/controller.ts` - the v1 plan - would make `fast/` import `agent/` while
+ * `agent/` imports `fast/`, and `.claude-index/config.md` already records one
+ * real cycle in this package (`agent <-> compaction`). One more is not a style
+ * question: a cycle makes the import graph unusable for ordering, and it is
+ * exactly what `shortcut-table.test.ts` scans for. So the types live DOWN here,
+ * in the lowest layer that needs them, and `agent/**` reaches them with
+ * `import type` only.
+ */
+/** How the label was produced. `fallback` is the user's own words, never a guess. */
+export type TaskSummaryTone = 'model' | 'fallback';
+/**
+ * The dominant character class of a string, by letter majority.
+ *
+ * A NAMED UNION rather than the free-form `Script` v1 mentioned (and never
+ * defined, P1-8). Only three answers are actionable: the label must be CJK, must
+ * be Latin, or is neither (a prompt in Cyrillic, or only punctuation).
+ */
+export type TaskSummarySpan = 'cjk' | 'latin' | 'other';
+/**
+ * Why a label is what it is.
+ *
+ * THE FIRST NINE VALUES ALL MEAN "the model did not give us a label" and every
+ * one of them converges on the SAME deterministic floor (D-9); they are kept
+ * apart only so the drawer and `/task` can say which one happened. `empty` is
+ * the tenth and means there was no floor to show either (fallback disabled).
+ */
+export type TaskSummaryReason = 'tier-off' | 'no-model' | 'no-adapter' | 'no-key' | 'timeout' | 'aborted' | 'error' | 'bad-output' | 'language-mismatch' | 'empty';
+/**
+ * The one task label a session has, as the header and the drawer read it.
+ *
+ * A PURE VIEW: it is never persisted, never enters the conversation history and
+ * never touches `config.json` (§0-2). Everything a surface needs to explain the
+ * label without a second lookup is on this record.
+ */
+export interface TaskSummaryView {
+    /** Normalised, width-safe, at most `TASK_SUMMARY_LIMITS.maxCells` columns. */
+    text: string;
+    tone: TaskSummaryTone;
+    /** `null` exactly when `tone === 'model'`. */
+    reason: TaskSummaryReason | null;
+    /** The anchor's dominant script, so the drawer can disclose a mismatch. */
+    script: TaskSummarySpan;
+    /** Epoch ms of the attempt. The drawer renders `12s ago` from it, no clock of its own. */
+    at: number;
+    /** `provider:model` that produced it; `''` for a fallback. */
+    by: string;
+}
+/**
+ * What one attempt produced.
+ *
+ * `view: null` happens in exactly one case: the call failed AND
+ * `taskSummary.fallback` is false. That is a deliberate "show nothing" rather
+ * than an empty string, because an empty header cell would read as a broken
+ * feature (D-9).
+ */
+export interface TaskSummaryOutcome {
+    view: TaskSummaryView | null;
+}

package/dist/fast/task-summary-types.js

@@ -0,0 +1,17 @@
+/**
+ * The task-summary types (tui-shortcut-drawer-and-task-summary §6.1).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * WHY THIS FILE EXISTS AT ALL (v2 P1-3). `fast/summary-call.ts` and
+ * `fast/summary-prompt.ts` produce and consume these shapes, and the header cell,
+ * the reducer and the controller only display them. Declaring them in
+ * `agent/controller.ts` - the v1 plan - would make `fast/` import `agent/` while
+ * `agent/` imports `fast/`, and `.claude-index/config.md` already records one
+ * real cycle in this package (`agent <-> compaction`). One more is not a style
+ * question: a cycle makes the import graph unusable for ordering, and it is
+ * exactly what `shortcut-table.test.ts` scans for. So the types live DOWN here,
+ * in the lowest layer that needs them, and `agent/**` reaches them with
+ * `import type` only.
+ */
+export {};

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction' | 'session' | 'branch';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction' | 'session' | 'branch' | 'bridge';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

package/dist/proc/limits.d.ts

@@ -55,6 +55,13 @@ export declare const PROC_LIMITS: {
      * 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.
+     *
+     * IT IS A BOUND, NOT A VERDICT. Expiry says "stop waiting"; it does NOT say
+     * the pipe was held, and the note is only printed when the streams are
+     * observed still open at that moment (`proc/output-streams.ts` records the
+     * release-gate failure a timer-based verdict caused). The ordinary path does
+     * not even reach this bound: two ended streams after `'exit'` settle the call
+     * with the byte-identical body, one notification earlier.
      */
     readonly drainMs: 250;
     /**

package/dist/proc/limits.js

@@ -55,6 +55,13 @@ export const PROC_LIMITS = {
      * 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.
+     *
+     * IT IS A BOUND, NOT A VERDICT. Expiry says "stop waiting"; it does NOT say
+     * the pipe was held, and the note is only printed when the streams are
+     * observed still open at that moment (`proc/output-streams.ts` records the
+     * release-gate failure a timer-based verdict caused). The ordinary path does
+     * not even reach this bound: two ended streams after `'exit'` settle the call
+     * with the byte-identical body, one notification earlier.
      */
     drainMs: 250,
     /**

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

@@ -9,7 +9,7 @@
  * `read_file` and `grep`): it is the full log on disk plus the PATH in the
  * truncation note.
  *
- * THREE RULES, each of which is about not becoming a new failure mode:
+ * THREE RULES PLUS A SCOPE, each of which is about not becoming a new failure mode:
  *
  *  - ASYNC AND COALESCED. `appendFile` with a <=4 writes/second buffer, so a
  *    webpack build emitting thousands of lines cannot turn logging into the
@@ -19,19 +19,36 @@
  *  - FAILURES ARE DEBUG LOGS, NEVER THROWS. A full disk must not kill a training
  *    run; the ring, the tools and the job state machine do not depend on this
  *    module at all.
+ *  - SCOPED TO ITS OWN ROOT. The retention sweep deletes session directories under
+ *    the jobs root the CALLER names, never under a parent derived from it: a
+ *    derived parent is other people's directory the moment the mirror is handed a
+ *    scratch path.
  */
 export interface JobLogMirrorOptions {
     /** `${aragonHome}/jobs/${sessionTag}`. A closure so a test can hand in a temp dir. */
     root: () => string;
+    /**
+     * THE DIRECTORY WHOSE SESSION SUBDIRECTORIES MAY BE SWEPT - passed, never derived.
+     *
+     * `dirname(root())` used to stand in for this, and it was wrong in the only way that
+     * matters: for any caller whose `root()` does not sit exactly one level below the jobs
+     * directory (a scratch dir in a test is the OS temp root's child) it handed the sweep a
+     * directory full of OTHER people's data and deleted everything but the newest few
+     * entries. A release run paid 40 s for that sweep and lost the temp directories of the
+     * test files running beside it. Omitted means NO sweep at all: growth is bounded only
+     * for callers that name the root they own.
+     */
+    jobsRoot?: () => string;
     maxBytes?: number;
     flushMs?: number;
 }
 /**
  * Delete all but the newest `PROC_LIMITS.mirrorRetainDirs` session directories.
  *
- * BEST EFFORT AND SILENT. This runs once per process at first use, and its whole
- * job is to stop `~/.aragon-agent/jobs/` from growing without bound; a directory
- * that cannot be read is not a reason to refuse to start.
+ * BEST EFFORT AND SILENT. This runs once per mirror at first use, and its whole job is to
+ * stop `~/.aragon-agent/jobs/` from growing without bound; a directory that cannot be read
+ * is not a reason to refuse to start. `jobsRoot` MUST be the directory this module owns -
+ * see `JobLogMirrorOptions.jobsRoot` for what deriving it cost.
  */
 export declare function pruneJobLogSessions(jobsRoot: string): void;
 export declare class JobLogMirror {

package/dist/proc/log-mirror.js

@@ -9,7 +9,7 @@
  * `read_file` and `grep`): it is the full log on disk plus the PATH in the
  * truncation note.
  *
- * THREE RULES, each of which is about not becoming a new failure mode:
+ * THREE RULES PLUS A SCOPE, each of which is about not becoming a new failure mode:
  *
  *  - ASYNC AND COALESCED. `appendFile` with a <=4 writes/second buffer, so a
  *    webpack build emitting thousands of lines cannot turn logging into the
@@ -19,18 +19,34 @@
  *  - FAILURES ARE DEBUG LOGS, NEVER THROWS. A full disk must not kill a training
  *    run; the ring, the tools and the job state machine do not depend on this
  *    module at all.
+ *  - SCOPED TO ITS OWN ROOT. The retention sweep deletes session directories under
+ *    the jobs root the CALLER names, never under a parent derived from it: a
+ *    derived parent is other people's directory the moment the mirror is handed a
+ *    scratch path.
  */
 import { appendFile, appendFileSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { getLogger } from '../logging/logger.js';
 import { PROC_LIMITS } from './limits.js';
+/**
+ * True when `path` holds nothing but `<jobId>.log` files, or nothing at all.
+ *
+ * DEFENSE IN DEPTH, NOT THE PRIMARY GUARD. The primary guard is that the caller names
+ * the jobs root instead of having it derived. This one means a sweep handed a directory
+ * that is not a mirror root is a no-op rather than a data loss - an empty directory and a
+ * directory of job logs are the only two shapes this module ever creates.
+ */
+function isMirrorDirectory(path) {
+    return readdirSync(path, { withFileTypes: true }).every((entry) => entry.isFile() && entry.name.endsWith('.log'));
+}
 /**
  * Delete all but the newest `PROC_LIMITS.mirrorRetainDirs` session directories.
  *
- * BEST EFFORT AND SILENT. This runs once per process at first use, and its whole
- * job is to stop `~/.aragon-agent/jobs/` from growing without bound; a directory
- * that cannot be read is not a reason to refuse to start.
+ * BEST EFFORT AND SILENT. This runs once per mirror at first use, and its whole job is to
+ * stop `~/.aragon-agent/jobs/` from growing without bound; a directory that cannot be read
+ * is not a reason to refuse to start. `jobsRoot` MUST be the directory this module owns -
+ * see `JobLogMirrorOptions.jobsRoot` for what deriving it cost.
  */
 export function pruneJobLogSessions(jobsRoot) {
     try {
@@ -41,14 +57,16 @@ export function pruneJobLogSessions(jobsRoot) {
             .map((entry) => {
             const path = join(jobsRoot, entry.name);
             try {
-                return { path, mtime: statSync(path).mtimeMs };
+                return { path, mtime: statSync(path).mtimeMs, prunable: isMirrorDirectory(path) };
             }
             catch {
-                return { path, mtime: 0 };
+                return { path, mtime: 0, prunable: false };
             }
         })
             .sort((a, b) => b.mtime - a.mtime);
         for (const stale of dirs.slice(PROC_LIMITS.mirrorRetainDirs)) {
+            if (!stale.prunable)
+                continue;
             try {
                 rmSync(stale.path, { recursive: true, force: true });
             }
@@ -107,7 +125,11 @@ export class JobLogMirror {
             this.files.set(jobId, { path, bytes, capped: bytes >= this.maxBytes() });
             if (!this.pruned) {
                 this.pruned = true;
-                pruneJobLogSessions(dirname(this.opts.root()));
+                // ONLY THE ROOT THE CALLER NAMED. See `JobLogMirrorOptions.jobsRoot` for why
+                // `dirname(root())` is not a substitute for it.
+                const jobsRoot = this.opts.jobsRoot?.();
+                if (jobsRoot !== undefined)
+                    pruneJobLogSessions(jobsRoot);
             }
         }
         catch (err) {

package/dist/proc/output-streams.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Ask the child's output streams whether anything is still arriving (W1,
+ * defence 1).
+ *
+ * WHY THIS EXISTS AT ALL, AND THE RELEASE-GATE FAILURE THAT PROVED IT.
+ *
+ * `bash` settles on `'close'`, which fires only once every stdio stream is
+ * closed - and a detached grandchild that inherited the pipe keeps it open after
+ * the shell is long gone, so the promise had a path that never settled. The
+ * drain window (`PROC_LIMITS.drainMs`) closes that: a quarter of a second after
+ * `'exit'`, settle anyway and stamp
+ *
+ *     [note] the command exited but a background child is still holding its
+ *     output stream.
+ *
+ * The first build decided that sentence by TIMER EXPIRY - whatever had not
+ * settled when the window closed was called a held pipe. That is a claim about
+ * STATE inferred from a clock, and under load the two disagree. The release gate
+ * caught it on `tool-output-store.test.ts` AC-30 ("`bash` returns the same bytes
+ * with and without a recorder"): the second call of `node -e
+ * "process.stdout.write(...)"` returned the note for a child that had printed
+ * two lines and exited immediately. The pipe was closed microseconds after
+ * `'exit'`; the event loop was busy enough (four workers, 400 files, ~200 s of
+ * transforms behind it) that the timers phase came round before libuv delivered
+ * the close notification, so a 250 ms timer won a race it was never meant to
+ * win - and the model was told a background child was holding its output stream
+ * when nothing was.
+ *
+ * Hence: READ THE STREAMS, DO NOT GUESS FROM THE CLOCK. A `Readable` has ended
+ * once it has emitted `'end'` (`readableEnded`) or been destroyed. While either
+ * child descriptor is still open the sentence above is literally true; the
+ * moment both have ended it is false no matter what a timer says. Callers use
+ * this to decide the WORDING (note or not) and, together with the `'end'`
+ * events, to settle the ordinary path without waiting for `'close'` at all.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ */
+import type { Readable } from 'node:stream';
+/**
+ * Whether one child descriptor can still deliver bytes.
+ *
+ * A stream that has been destroyed is finished even when `readableEnded` is
+ * still false - that is the state a killed child's pipes end up in.
+ */
+export declare function isOutputStreamOpen(stream: Readable | null | undefined): boolean;
+/** Whether EITHER child descriptor can still deliver bytes. */
+export declare function hasOpenOutputStreams(streams: {
+    readonly stdout: Readable | null;
+    readonly stderr: Readable | null;
+}): boolean;