@aragon-agent/cli 0.6.31 → 0.6.32

package/dist/input/cursor-report.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cursor Position Report parsing (tui-bottom-anchored-live-region §4.5).
+ *
+ * The bottom anchor needs one number the writer cannot compute: how many rows are
+ * left below the cursor. `ESC[6n` is the only way to ask, and the terminal answers
+ * with `ESC[<row>;<col>R` (DECXCPR adds a `?`: `ESC[?<row>;<col>R`) on STDIN —
+ * the same stream the user types on. Two things follow, and both live here:
+ *
+ *  1. THE ANSWER MUST BE STRIPPED BEFORE INK SEES IT. A report that reaches Ink
+ *     travels the keystroke path: `[` is 0x5B, so `PromptInput`'s control-sequence
+ *     guard passes it through and the user's draft gets `[12;1R` typed into it (the
+ *     same class of accident the mouse filter exists to prevent).
+ *  2. THE ANSWER CAN ARRIVE IN TWO CHUNKS. ConPTY, tmux and a loaded SSH session
+ *     all split reads at arbitrary points, and a half report (`ESC[12`) is worse
+ *     than a whole one: `parse-keypress` has no branch for it.
+ *
+ * Pure functions only, mirroring `mouse-events.ts`: the filter owns the buffering
+ * and the timers, this module owns the shapes.
+ */
+/** The query for a Cursor Position Report (DSR 6). ASCII by construction. */
+export declare const CURSOR_REPORT_QUERY = "\u001B[6n";
+/** One parsed report. `row`/`col` are 1-based, exactly as the terminal sent them. */
+export interface CursorReport {
+    row: number;
+    col: number;
+}
+export interface CursorReportSplit {
+    /** Text that survives stripping — everything that is not a report. */
+    text: string;
+    /** Reports found in this chunk, in order. */
+    reports: CursorReport[];
+    /** Trailing bytes that could still become a report; hand them to the next chunk. */
+    pending: string;
+}
+/** True when `s` is a non-empty proper prefix of a possible report. */
+export declare function isCursorReportPrefix(s: string): boolean;
+/**
+ * Split the reports out of one chunk.
+ *
+ * `pending` carries the tail that might still complete into a report. It is only
+ * ever the LAST fragment: the scan is left to right, so anything before a complete
+ * report is settled text.
+ */
+export declare function splitCursorReports(text: string): CursorReportSplit;
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a report, or 0.
+ *
+ * LONGEST MATCH WINS, unlike the mouse family's shortest-wins rule. The families are
+ * combined with `max()`, so only the longest answer ever survives, and a longer hold
+ * is never wrong here: `ESC[1` can still become `ESC[12;1R`, while the shorter
+ * answer `ESC` could not describe it. The bound is the longest report the terminals
+ * we target emit (DECXCPR with a `?` and three-digit coordinates).
+ */
+export declare function trailingCprPrefixLength(text: string): number;
+/** The query bytes, as a function so call sites read as an action rather than a literal. */
+export declare function formatCursorReportQuery(): string;
+/**
+ * Rows left below a reported cursor row on a terminal of `rows` rows.
+ * `0` means the cursor is already on the last row; `null` when the height is unknown.
+ */
+export declare function spaceBelowFromReport(report: CursorReport, rows: number | undefined): number | null;

package/dist/input/cursor-report.js

@@ -0,0 +1,97 @@
+/**
+ * Cursor Position Report parsing (tui-bottom-anchored-live-region §4.5).
+ *
+ * The bottom anchor needs one number the writer cannot compute: how many rows are
+ * left below the cursor. `ESC[6n` is the only way to ask, and the terminal answers
+ * with `ESC[<row>;<col>R` (DECXCPR adds a `?`: `ESC[?<row>;<col>R`) on STDIN —
+ * the same stream the user types on. Two things follow, and both live here:
+ *
+ *  1. THE ANSWER MUST BE STRIPPED BEFORE INK SEES IT. A report that reaches Ink
+ *     travels the keystroke path: `[` is 0x5B, so `PromptInput`'s control-sequence
+ *     guard passes it through and the user's draft gets `[12;1R` typed into it (the
+ *     same class of accident the mouse filter exists to prevent).
+ *  2. THE ANSWER CAN ARRIVE IN TWO CHUNKS. ConPTY, tmux and a loaded SSH session
+ *     all split reads at arbitrary points, and a half report (`ESC[12`) is worse
+ *     than a whole one: `parse-keypress` has no branch for it.
+ *
+ * Pure functions only, mirroring `mouse-events.ts`: the filter owns the buffering
+ * and the timers, this module owns the shapes.
+ */
+/** The query for a Cursor Position Report (DSR 6). ASCII by construction. */
+export const CURSOR_REPORT_QUERY = '\x1b[6n';
+/**
+ * `ESC[<row>;<col>R`, with the DECXCPR `?` accepted. Anchored on `ESC[` plus digits
+ * and one `;`, which is what keeps it from matching a private-mode write such as
+ * `ESC[?25l` (that one ends in a letter this pattern cannot accept).
+ *
+ * Built per call rather than shared: a module-level `/g` regex carries `lastIndex`
+ * between calls, which turns a pure function into a stateful one.
+ */
+const reportPattern = () => /\x1b\[\??(\d+);(\d+)R/g;
+/**
+ * A PROPER prefix of a report: `ESC`, `ESC[`, then an optional `?`, then digits, at
+ * most one `;`, then more digits. Nothing a keyboard produces matches past `ESC[`
+ * (arrow keys end in a letter), so the filter's 12 ms hold stays a rare path.
+ */
+const PREFIX = /^\x1b(\[(\?(\d*(;\d*)?)?|\d*(;\d*)?)?)?$/;
+/** True when `s` is a non-empty proper prefix of a possible report. */
+export function isCursorReportPrefix(s) {
+    return s.length > 0 && s.length < 24 && PREFIX.test(s);
+}
+/**
+ * Split the reports out of one chunk.
+ *
+ * `pending` carries the tail that might still complete into a report. It is only
+ * ever the LAST fragment: the scan is left to right, so anything before a complete
+ * report is settled text.
+ */
+export function splitCursorReports(text) {
+    const reports = [];
+    const pattern = reportPattern();
+    let out = '';
+    let index = 0;
+    for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+        out += text.slice(index, match.index);
+        reports.push({ row: Number(match[1]), col: Number(match[2]) });
+        index = match.index + match[0].length;
+    }
+    out += text.slice(index);
+    const pendingLength = trailingCprPrefixLength(out);
+    if (pendingLength === 0)
+        return { text: out, reports, pending: '' };
+    return {
+        text: out.slice(0, out.length - pendingLength),
+        reports,
+        pending: out.slice(out.length - pendingLength),
+    };
+}
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a report, or 0.
+ *
+ * LONGEST MATCH WINS, unlike the mouse family's shortest-wins rule. The families are
+ * combined with `max()`, so only the longest answer ever survives, and a longer hold
+ * is never wrong here: `ESC[1` can still become `ESC[12;1R`, while the shorter
+ * answer `ESC` could not describe it. The bound is the longest report the terminals
+ * we target emit (DECXCPR with a `?` and three-digit coordinates).
+ */
+export function trailingCprPrefixLength(text) {
+    const max = Math.min(text.length, 24);
+    for (let k = max; k >= 1; k -= 1) {
+        if (isCursorReportPrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}
+/** The query bytes, as a function so call sites read as an action rather than a literal. */
+export function formatCursorReportQuery() {
+    return CURSOR_REPORT_QUERY;
+}
+/**
+ * Rows left below a reported cursor row on a terminal of `rows` rows.
+ * `0` means the cursor is already on the last row; `null` when the height is unknown.
+ */
+export function spaceBelowFromReport(report, rows) {
+    if (rows === undefined || !Number.isFinite(rows) || rows < 1)
+        return null;
+    return Math.max(0, Math.floor(rows) - 1 - (report.row - 1));
+}

package/dist/input/stdin-filter.d.ts

@@ -69,11 +69,33 @@ export interface StdinFilterFeatures {
      * translates for a session whose mode push actually happened.
      */
     readonly enhancedKeys?: boolean;
+    /**
+     * Strip the Cursor Position Report a terminal sends back for `ESC[6n`
+     * (tui-bottom-anchored-live-region §4.5).
+     *
+     * TOLD, never derived, like the three above: `cli.tsx` passes
+     * `plan.differ === 'scrollback'`, so an `app`-mode session stays byte-identical to
+     * the build without this feature (I-A8). The report MUST NOT reach Ink -- `[` is
+     * 0x5B, so `PromptInput`'s control-sequence guard passes it and the reply gets
+     * typed into the draft -- and a report split across two reads is worse than a
+     * whole one, because `parse-keypress` has no branch for a half sequence.
+     */
+    readonly cursorReport?: boolean;
 }
 export interface StdinFilter {
     /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */
     readonly stdin: NodeJS.ReadStream;
     readonly source: MouseSource;
+    /**
+     * The probe is waiting for an answer: hold a possible report prefix until it
+     * settles instead of flushing it after `PENDING_FLUSH_MS`.
+     *
+     * ConPTY can split `ESC[12;1R` across two reads further apart than 12 ms, and a
+     * half report that reaches Ink lands on an undefined branch of its key parser.
+     * Turning this off flushes whatever is still held as ordinary text -- the
+     * correct degradation for a terminal that answered with something else (R3).
+     */
+    setExpectingCursorReport(on: boolean): void;
     /** Idempotent. Detaches from the real stdin and clears every timer (I-7). */
     dispose(): void;
 }

package/dist/input/stdin-filter.js

@@ -36,6 +36,7 @@ import { MAX_PENDING_MOUSE_CHARS, splitMouseEvents, isMousePrefix, } from './mou
 import { ENTER_NEWLINE_FRAME, INDEX_KEY_FRAME, PASTE_ASSEMBLY_MAX_MS, PASTE_BURST_MS, PASTE_CLOSE, PASTE_MARKER_RESCAN_TTL_MS, PASTE_MAX_BYTES, PASTE_OPEN, formatPasteSize, } from './limits.js';
 import { PASTE_BEGIN_MARK, PASTE_END_MARK, classifyChunk, isPastePrefix, sanitisePaste, trailingPastePrefixLength, } from './paste-parse.js';
 import { hasPasteOnlySequence } from './control-sequences.js';
+import { splitCursorReports, trailingCprPrefixLength } from './cursor-report.js';
 import { splitEnterSequences, trailingEnterPrefixLength } from './enter-sequences.js';
 import { splitCsiUKeys, trailingCsiUPrefixLength, translateCsiUKey } from './csiu-keys.js';
 import { splitWin32KeySequences, trailingWin32PrefixLength, translateWin32Key, } from './win32-input-mode.js';
@@ -95,6 +96,12 @@ export function createStdinFilter(real, features, bridge, onWarn) {
     let disposed = false;
     let finished = false;
     let paste = { kind: 'idle' };
+    /**
+     * The probe window (R3). While true a possible report prefix is held until the
+     * probe settles instead of being flushed after `PENDING_FLUSH_MS`, because a
+     * half `ESC[12` reaching Ink hits an undefined branch of its key parser.
+     */
+    let expectingCursorReport = false;
     let discardBracketed = false;
     let outputBatch = null;
     /**
@@ -266,6 +273,26 @@ export function createStdinFilter(real, features, bridge, onWarn) {
             burstTimer = arm(flushBurst, PASTE_BURST_MS);
             return;
         }
+        // FOURTH PREFIX FAMILY: the terminal's answer to `ESC[6n`
+        // (tui-bottom-anchored-live-region §4.5). AFTER the paste tests, and that order
+        // is the specification: a user who pastes a terminal log containing `ESC[12;1R`
+        // is pasting DATA, and a paste body is the one place such a sequence is kept
+        // verbatim (I-3, the same rule that suspends mouse parsing inside a body).
+        if (features.cursorReport) {
+            const report = splitCursorReports(text);
+            text = report.text;
+            if (report.pending.length > 0) {
+                // Not text yet: it joins the cross-chunk buffer the mouse family uses.
+                // `holdTail` false means a paste marker follows in this very chunk, so no
+                // later byte can complete the prefix and holding it would reorder it (I-5).
+                if (holdTail)
+                    pending += report.pending;
+                else
+                    writeInput(report.pending);
+            }
+            if (text.length === 0)
+                return;
+        }
         // Ink conflates DEL Backspace with CSI Delete. Normalize only keyboard
         // text, after burst classification, preserving ESC for Alt+Backspace.
         text = text.replace(/\x7f/g, '\x08');
@@ -414,7 +441,7 @@ export function createStdinFilter(real, features, bridge, onWarn) {
                 // the ESC / ESC-[ head bytes, which the max keeps for whoever needs
                 // them. The existing 12 ms flush and the 32-char ceiling bound the
                 // hold, so no new timer is needed.
-                const keep = Math.max(trailingPastePrefixLength(rest), features.mouse ? trailingMousePrefixLength(rest) : 0, trailingEnterPrefixLength(rest), enhancedKeys ? trailingWin32PrefixLength(rest) : 0, enhancedKeys ? trailingCsiUPrefixLength(rest) : 0);
+                const keep = Math.max(trailingPastePrefixLength(rest), features.mouse ? trailingMousePrefixLength(rest) : 0, features.cursorReport ? trailingCprPrefixLength(rest) : 0, trailingEnterPrefixLength(rest), enhancedKeys ? trailingWin32PrefixLength(rest) : 0, enhancedKeys ? trailingCsiUPrefixLength(rest) : 0);
                 const tail = rest.slice(rest.length - keep);
                 handleOutsidePaste(rest.slice(0, rest.length - keep), true);
                 pending += tail;
@@ -450,6 +477,10 @@ export function createStdinFilter(real, features, bridge, onWarn) {
         flushTimer = clearTimer(flushTimer);
         if (pending.length === 0 || disposed)
             return;
+        // The probe owes us an answer: releasing a half report now would type it into
+        // the draft. `setExpectingCursorReport(false)` flushes whatever is left.
+        if (expectingCursorReport)
+            return;
         const text = pending;
         pending = '';
         // A tail that never completed is ordinary text; it goes through the same
@@ -526,9 +557,12 @@ export function createStdinFilter(real, features, bridge, onWarn) {
             wrapper.write(text);
         if (paste.kind === 'bracketed' || pending.length === 0)
             return;
-        if (pending.length > MAX_PENDING_CHARS) {
+        if (pending.length > MAX_PENDING_CHARS && !expectingCursorReport) {
             // A malformed sequence that looks like a prefix forever must never wedge
-            // input: past the ceiling the tail becomes ordinary text.
+            // input: past the ceiling the tail becomes ordinary text. NOT DURING THE
+            // PROBE WINDOW THOUGH (L8): there the ceiling could push half a report into
+            // Ink, which is the failure this whole family exists to prevent. The window
+            // is bounded by the probe timeout, after which the ceiling applies again.
             const text = pending;
             pending = '';
             flushTailAsText(text);
@@ -574,6 +608,17 @@ export function createStdinFilter(real, features, bridge, onWarn) {
                 return () => listeners.delete(listener);
             },
         },
+        setExpectingCursorReport(on) {
+            if (expectingCursorReport === on)
+                return;
+            expectingCursorReport = on;
+            if (on || disposed)
+                return;
+            // Settled: nothing that is still held was a report. Release it as text, so a
+            // probe that never got an answer costs its own timeout and not a dead keyboard.
+            flushTimer = clearTimer(flushTimer);
+            flushPending();
+        },
         dispose() {
             if (disposed)
                 return;

package/dist/proc/limits.d.ts

@@ -34,14 +34,19 @@ export declare const PROC_LIMITS: {
     /** Rows a snapshot (and therefore a card) carries. */
     readonly cardTailRows: 8;
     /**
-     * Service RECORDS one session may hold.
+     * JOB RECORDS one session may hold — services AND tasks share the number.
+     *
+     * NAMED `maxJobs`, NOT `maxServices` (long-task-jobs D-7). A constant that
+     * counts two kinds of job while being called `maxServices` is the next edit's
+     * bug: the limit and its refusal message would go on saying "service" while
+     * the model is holding a training run.
      *
      * 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;
+    readonly maxJobs: 16;
     /**
      * How long `bash` waits after `'exit'` for the stdio streams to close before
      * settling anyway.
@@ -76,9 +81,78 @@ export declare const PROC_LIMITS: {
     readonly stopGraceMs: 3000;
     /** Below this many terminal columns the status chip degrades to `[N]`. */
     readonly statusCompactCols: 92;
+    /**
+     * Rows of new output one `job_wait` result carries, in addition to its status,
+     * progress, cursor, `[note]`/`[stalled]` and `[next]` lines.
+     *
+     * THE NUMBER IS THE FEATURE. One wait must cost ~150 tokens, not the ~6k a
+     * 200-row tail costs - that economy is the whole reason `job_wait` exists
+     * instead of a seventh `bash_output` poll.
+     */
+    readonly waitTailRows: 6;
+    /** Seconds a single wait may block, as a STRUCTURAL floor and ceiling (`jobs.waitSeconds` is clamped into this range). */
+    readonly waitMinSeconds: 5;
+    readonly waitMaxSeconds: 60;
+    /**
+     * Characters one extracted progress line may occupy.
+     *
+     * Also the width the card's progress row is assumed to take, which is why
+     * `ui/layout/virtual-window.ts` can count it as exactly one row.
+     */
+    readonly waitProgressChars: 80;
+    /**
+     * Rows `extractProgress` scans, from the tail, before giving up.
+     *
+     * Eight because a tqdm bar plus its ETA plus the loss line above it is the
+     * realistic worst case, and because a wider window is how a stale `100%` from
+     * an earlier phase wins over the live one.
+     */
+    readonly progressScanRows: 8;
+    /** Notices one `<job_notices>` block may render. Bounded so the block stays ~8 lines. */
+    readonly maxNotices: 8;
+    /** Log rows a failed job's notice carries. Two: the message and the frame above it. */
+    readonly noticeTailRows: 2;
+    /** Rows `job_list` prints before it collapses the rest into `+N more`. */
+    readonly listRows: 8;
+    /**
+     * Consecutive waits with no new row and no progress change before the
+     * `[guard]` line is prepended (R-3).
+     *
+     * A HINT, NEVER A REFUSAL: the seventh wait still waits. Refusing would take
+     * the decision away from the model at exactly the point where it has the most
+     * context.
+     */
+    readonly maxConsecutiveWaits: 6;
+    /** Bytes one mirrored job log may occupy before it stops appending. */
+    readonly logMirrorMaxBytes: 2000000;
+    /** Coalescing window for the log mirror's appends (<=4 writes/second). */
+    readonly mirrorFlushMs: 250;
+    /** Session directories the mirror keeps, newest by mtime. */
+    readonly mirrorRetainDirs: 5;
 };
 /**
  * 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";
+/**
+ * The same discipline for the `<background_jobs>` block. A SEPARATE CONSTANT,
+ * not a bump of the one above: the two blocks are spliced by different flags
+ * (`bash.background` and `jobs.enabled`), so one version number covering both
+ * would make "which block changed" unanswerable from a report.
+ */
+export declare const JOBS_BLOCK_VERSION = "v1-2026-10";
+/**
+ * Head-room a single wait leaves below the tool ceiling (I-4).
+ *
+ * `jobs.waitSeconds * 1000 + JOB_WAIT_MARGIN_MS <= toolTimeoutMs` is the whole
+ * reason a wait never needs to pause the idle watchdog (D-3): a 60 s wait inside
+ * a 180 s tool call in a 210 s idle window cannot be mistaken for a hang.
+ *
+ * IT LIVES HERE RATHER THAN IN `config/schema.ts`, where the design document put
+ * it, because the TOOL layer needs the same number for its call-time convergence
+ * (AC-14) and nothing in `tools/` may import `config/` - a tool takes its policy
+ * through closures. One constant, two readers, no second copy to drift. Recorded
+ * in `docs/plans/long-task-jobs/spec.md` under `## 实施过程发现的方案缺陷` (I-2).
+ */
+export declare const JOB_WAIT_MARGIN_MS = 30000;

package/dist/proc/limits.js

@@ -34,14 +34,19 @@ export const PROC_LIMITS = {
     /** Rows a snapshot (and therefore a card) carries. */
     cardTailRows: 8,
     /**
-     * Service RECORDS one session may hold.
+     * JOB RECORDS one session may hold — services AND tasks share the number.
+     *
+     * NAMED `maxJobs`, NOT `maxServices` (long-task-jobs D-7). A constant that
+     * counts two kinds of job while being called `maxServices` is the next edit's
+     * bug: the limit and its refusal message would go on saying "service" while
+     * the model is holding a training run.
      *
      * 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,
+    maxJobs: 16,
     /**
      * How long `bash` waits after `'exit'` for the stdio streams to close before
      * settling anyway.
@@ -76,9 +81,85 @@ export const PROC_LIMITS = {
     stopGraceMs: 3000,
     /** Below this many terminal columns the status chip degrades to `[N]`. */
     statusCompactCols: 92,
+    // --- long-task-jobs: bounded waiting, progress, notices, log mirror --------
+    //
+    // EVERY ONE OF THESE IS STRUCTURAL, not policy. The user-tunable knobs are the
+    // five `jobs.*` keys in `config/schema.ts` (how many seconds to wait, when
+    // silence becomes `[stalled]`, whether to mirror the log, whether notices may
+    // steer). What a result can PHYSICALLY carry lives here, for the reason this
+    // file's header records at length.
+    /**
+     * Rows of new output one `job_wait` result carries, in addition to its status,
+     * progress, cursor, `[note]`/`[stalled]` and `[next]` lines.
+     *
+     * THE NUMBER IS THE FEATURE. One wait must cost ~150 tokens, not the ~6k a
+     * 200-row tail costs - that economy is the whole reason `job_wait` exists
+     * instead of a seventh `bash_output` poll.
+     */
+    waitTailRows: 6,
+    /** Seconds a single wait may block, as a STRUCTURAL floor and ceiling (`jobs.waitSeconds` is clamped into this range). */
+    waitMinSeconds: 5,
+    waitMaxSeconds: 60,
+    /**
+     * Characters one extracted progress line may occupy.
+     *
+     * Also the width the card's progress row is assumed to take, which is why
+     * `ui/layout/virtual-window.ts` can count it as exactly one row.
+     */
+    waitProgressChars: 80,
+    /**
+     * Rows `extractProgress` scans, from the tail, before giving up.
+     *
+     * Eight because a tqdm bar plus its ETA plus the loss line above it is the
+     * realistic worst case, and because a wider window is how a stale `100%` from
+     * an earlier phase wins over the live one.
+     */
+    progressScanRows: 8,
+    /** Notices one `<job_notices>` block may render. Bounded so the block stays ~8 lines. */
+    maxNotices: 8,
+    /** Log rows a failed job's notice carries. Two: the message and the frame above it. */
+    noticeTailRows: 2,
+    /** Rows `job_list` prints before it collapses the rest into `+N more`. */
+    listRows: 8,
+    /**
+     * Consecutive waits with no new row and no progress change before the
+     * `[guard]` line is prepended (R-3).
+     *
+     * A HINT, NEVER A REFUSAL: the seventh wait still waits. Refusing would take
+     * the decision away from the model at exactly the point where it has the most
+     * context.
+     */
+    maxConsecutiveWaits: 6,
+    /** Bytes one mirrored job log may occupy before it stops appending. */
+    logMirrorMaxBytes: 2_000_000,
+    /** Coalescing window for the log mirror's appends (<=4 writes/second). */
+    mirrorFlushMs: 250,
+    /** Session directories the mirror keeps, newest by mtime. */
+    mirrorRetainDirs: 5,
 };
 /**
  * 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';
+/**
+ * The same discipline for the `<background_jobs>` block. A SEPARATE CONSTANT,
+ * not a bump of the one above: the two blocks are spliced by different flags
+ * (`bash.background` and `jobs.enabled`), so one version number covering both
+ * would make "which block changed" unanswerable from a report.
+ */
+export const JOBS_BLOCK_VERSION = 'v1-2026-10';
+/**
+ * Head-room a single wait leaves below the tool ceiling (I-4).
+ *
+ * `jobs.waitSeconds * 1000 + JOB_WAIT_MARGIN_MS <= toolTimeoutMs` is the whole
+ * reason a wait never needs to pause the idle watchdog (D-3): a 60 s wait inside
+ * a 180 s tool call in a 210 s idle window cannot be mistaken for a hang.
+ *
+ * IT LIVES HERE RATHER THAN IN `config/schema.ts`, where the design document put
+ * it, because the TOOL layer needs the same number for its call-time convergence
+ * (AC-14) and nothing in `tools/` may import `config/` - a tool takes its policy
+ * through closures. One constant, two readers, no second copy to drift. Recorded
+ * in `docs/plans/long-task-jobs/spec.md` under `## 实施过程发现的方案缺陷` (I-2).
+ */
+export const JOB_WAIT_MARGIN_MS = 30_000;

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

@@ -0,0 +1,59 @@
+/**
+ * The optional on-disk log mirror — the escape hatch (long-task-jobs §4.8).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * WHY IT EXISTS: the ring holds 200 rows, so the `ModuleNotFoundError` from eight
+ * minutes ago is gone exactly when the model needs it. The answer is not a bigger
+ * ring (that is a bigger context) and not a new tool (the model already has
+ * `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:
+ *
+ *  - ASYNC AND COALESCED. `appendFile` with a <=4 writes/second buffer, so a
+ *    webpack build emitting thousands of lines cannot turn logging into the
+ *    bottleneck of the build it is logging.
+ *  - BOUNDED. `PROC_LIMITS.logMirrorMaxBytes` (2 MB) per job, then one
+ *    `[mirror truncated]` line and silence.
+ *  - 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.
+ */
+export interface JobLogMirrorOptions {
+    /** `${aragonHome}/jobs/${sessionTag}`. A closure so a test can hand in a temp dir. */
+    root: () => 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.
+ */
+export declare function pruneJobLogSessions(jobsRoot: string): void;
+export declare class JobLogMirror {
+    private readonly opts;
+    private readonly files;
+    private readonly buffers;
+    private flushTimer;
+    private pruned;
+    private disposed;
+    constructor(opts: JobLogMirrorOptions);
+    /** Lazy creation: the directory appears only when a job actually prints. */
+    open(jobId: string): void;
+    /** Buffer one chunk. Never throws, never awaits, never blocks the child. */
+    write(jobId: string, chunk: string): void;
+    pathOf(jobId: string): string | undefined;
+    /** Flush what is buffered and release the timer. Idempotent. */
+    dispose(): void;
+    private maxBytes;
+    private flushMs;
+    private scheduleFlush;
+    private flushAll;
+    private flushOne;
+    /** One place that writes, so the sync and async paths cannot drift. */
+    private writeOut;
+}