@aragon-agent/cli 0.6.31 → 0.6.32

package/dist/proc/log-mirror.js

@@ -0,0 +1,203 @@
+/**
+ * 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.
+ */
+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';
+/**
+ * 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 function pruneJobLogSessions(jobsRoot) {
+    try {
+        if (!existsSync(jobsRoot))
+            return;
+        const dirs = readdirSync(jobsRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => {
+            const path = join(jobsRoot, entry.name);
+            try {
+                return { path, mtime: statSync(path).mtimeMs };
+            }
+            catch {
+                return { path, mtime: 0 };
+            }
+        })
+            .sort((a, b) => b.mtime - a.mtime);
+        for (const stale of dirs.slice(PROC_LIMITS.mirrorRetainDirs)) {
+            try {
+                rmSync(stale.path, { recursive: true, force: true });
+            }
+            catch (err) {
+                getLogger().debug('tool', 'job_mirror_prune_failed', {
+                    path: stale.path,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    catch (err) {
+        getLogger().debug('tool', 'job_mirror_prune_failed', {
+            root: jobsRoot,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * The longest prefix of `text` whose UTF-8 encoding fits in `maxBytes`.
+ *
+ * THE CAP IS IN BYTES AND THE BUFFER IS IN CHARACTERS, so slicing by character
+ * count silently overshoots for any non-ASCII output - a log that writes more than
+ * its documented ceiling while claiming to enforce it. A partial trailing sequence
+ * is dropped rather than written as a replacement character, so `grep` sees a short
+ * final line instead of a corrupted one. The ASCII fast path costs one length check.
+ */
+function truncateToBytes(text, maxBytes) {
+    if (Buffer.byteLength(text, 'utf8') <= maxBytes)
+        return text;
+    const decoded = Buffer.from(text, 'utf8').subarray(0, maxBytes).toString('utf8');
+    // A cut inside a multi-byte sequence decodes to U+FFFD, which must not be
+    // written: strip the tail of replacement characters the cut produced.
+    return decoded.replace(/\uFFFD+$/u, '');
+}
+export class JobLogMirror {
+    opts;
+    files = new Map();
+    buffers = new Map();
+    flushTimer;
+    pruned = false;
+    disposed = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Lazy creation: the directory appears only when a job actually prints. */
+    open(jobId) {
+        if (this.disposed || this.files.has(jobId))
+            return;
+        const path = join(this.opts.root(), `${jobId}.log`);
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            // SEEDED FROM DISK, because a resumed session reuses nothing but the
+            // directory name: without this the byte cap restarts at zero every launch.
+            const bytes = existsSync(path) ? statSync(path).size : 0;
+            this.files.set(jobId, { path, bytes, capped: bytes >= this.maxBytes() });
+            if (!this.pruned) {
+                this.pruned = true;
+                pruneJobLogSessions(dirname(this.opts.root()));
+            }
+        }
+        catch (err) {
+            getLogger().debug('tool', 'job_mirror_open_failed', {
+                job: jobId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /** Buffer one chunk. Never throws, never awaits, never blocks the child. */
+    write(jobId, chunk) {
+        if (this.disposed)
+            return;
+        if (!this.files.has(jobId))
+            this.open(jobId);
+        const file = this.files.get(jobId);
+        if (!file || file.capped)
+            return;
+        this.buffers.set(jobId, (this.buffers.get(jobId) ?? '') + chunk);
+        this.scheduleFlush();
+    }
+    pathOf(jobId) {
+        return this.files.get(jobId)?.path;
+    }
+    /** Flush what is buffered and release the timer. Idempotent. */
+    dispose() {
+        this.disposed = true;
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        // SYNCHRONOUS AT TEARDOWN. The async path is right during a run (it must never
+        // block the child's stdout callback), but a dispose that returns before the
+        // last chunk has landed is a log with a hole in the one place it matters -
+        // the end of the job.
+        this.flushAll(true);
+    }
+    maxBytes() {
+        return this.opts.maxBytes ?? PROC_LIMITS.logMirrorMaxBytes;
+    }
+    flushMs() {
+        return this.opts.flushMs ?? PROC_LIMITS.mirrorFlushMs;
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            this.flushAll();
+        }, this.flushMs());
+        this.flushTimer.unref?.();
+    }
+    flushAll(sync = false) {
+        for (const [jobId, chunk] of [...this.buffers]) {
+            this.buffers.delete(jobId);
+            this.flushOne(jobId, chunk, sync);
+        }
+    }
+    flushOne(jobId, chunk, sync) {
+        const file = this.files.get(jobId);
+        if (!file || chunk.length === 0)
+            return;
+        const room = this.maxBytes() - file.bytes;
+        const accepted = room <= 0 ? '' : truncateToBytes(chunk, room);
+        if (accepted.length > 0) {
+            file.bytes += Buffer.byteLength(accepted, 'utf8');
+            this.writeOut(file.path, accepted, jobId, sync);
+        }
+        if (file.bytes >= this.maxBytes() && !file.capped) {
+            file.capped = true;
+            this.writeOut(file.path, '\n[mirror truncated]\n', jobId, sync);
+        }
+    }
+    /** One place that writes, so the sync and async paths cannot drift. */
+    writeOut(path, text, jobId, sync) {
+        if (sync) {
+            try {
+                appendFileSync(path, text, 'utf8');
+            }
+            catch (err) {
+                getLogger().debug('tool', 'job_mirror_write_failed', {
+                    job: jobId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return;
+        }
+        appendFile(path, text, 'utf8', (err) => {
+            if (err) {
+                getLogger().debug('tool', 'job_mirror_write_failed', { job: jobId, error: err.message });
+            }
+        });
+    }
+}

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

@@ -24,6 +24,17 @@ export interface LogRingPage {
     cursor: number;
     /** Rows between `since` and the first row returned were evicted. */
     truncated: boolean;
+    /**
+     * The not-yet-terminated line, or an empty string when the last chunk ended
+     * with a newline.
+     *
+     * THE ROWS ARRAY ENDS WITH THE CARRY LINE when one exists, so from the array
+     * alone a consumer cannot tell "the newest completed row" from "the progress bar
+     * being redrawn right now" - and that difference is the whole content of
+     * `JobProgress.source`. It is also what lets `job_wait` decline to reprint an
+     * unchanged, carriage-return-rewritten bar on every single wait (RV-P1-5).
+     */
+    carryRow: string;
 }
 /**
  * A per-service ring.
@@ -51,6 +62,17 @@ export declare class LogRing {
     append(chunk: string): readonly string[];
     /** The last `n` display rows, in-progress line included when non-empty. */
     tail(n: number): readonly string[];
+    /**
+     * The not-yet-terminated line, exactly as the display would show it.
+     *
+     * THE PROGRESS EXTRACTOR NEEDS THIS SEPARATELY FROM `tail()`, and that is the
+     * only reason it is public: `tail()` appends the carry line as its last
+     * element, so a consumer that is handed the array cannot tell whether that last
+     * element is a completed row or the bar currently being redrawn. A tqdm run and
+     * a silent job would look identical, and the difference is precisely the
+     * information `JobProgress.source` carries.
+     */
+    get carryRow(): string;
     /** Every completed row plus the in-progress line. */
     all(): readonly string[];
     /** Completed rows ever appended — the paging cursor and the revision term. */

package/dist/proc/log-ring.js

@@ -65,6 +65,19 @@ export class LogRing {
         const all = live.length > 0 ? [...this.rows, live] : this.rows;
         return Object.freeze(all.length > n ? all.slice(-n) : [...all]);
     }
+    /**
+     * The not-yet-terminated line, exactly as the display would show it.
+     *
+     * THE PROGRESS EXTRACTOR NEEDS THIS SEPARATELY FROM `tail()`, and that is the
+     * only reason it is public: `tail()` appends the carry line as its last
+     * element, so a consumer that is handed the array cannot tell whether that last
+     * element is a completed row or the bar currently being redrawn. A tqdm run and
+     * a silent job would look identical, and the difference is precisely the
+     * information `JobProgress.source` carries.
+     */
+    get carryRow() {
+        return toDisplayRow(this.carry);
+    }
     /** Every completed row plus the in-progress line. */
     all() {
         return this.tail(this.capacity + 1);
@@ -87,7 +100,12 @@ export class LogRing {
     page(since) {
         const oldest = this.seen - this.rows.length;
         if (since === undefined || since < 0) {
-            return { rows: this.all(), cursor: this.seen, truncated: this.truncated };
+            return {
+                rows: this.all(),
+                cursor: this.seen,
+                truncated: this.truncated,
+                carryRow: toDisplayRow(this.carry),
+            };
         }
         const from = Math.max(since, oldest);
         const rows = this.rows.slice(from - oldest);
@@ -97,6 +115,7 @@ export class LogRing {
             rows: Object.freeze(withLive),
             cursor: this.seen,
             truncated: since < oldest,
+            carryRow: live,
         };
     }
 }

package/dist/proc/notices.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The completion-notice queue and its one renderer (long-task-jobs §4.6).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A NOTICE IS NOT A MESSAGE. It is a bounded, factual sentence about a job that
+ * ended while the model was busy, and it reaches the model through three
+ * mutually exclusive paths that all take from THIS queue - the tail of the next
+ * tool result (pull), a `steer()` at the one safe point (push), and a
+ * `steer()` before the next user turn (fill). One `drain()` behind all three is
+ * what makes "at most once" a property of the data structure rather than a
+ * promise in three call sites (I-6).
+ *
+ * THE QUEUE IS BOUNDED AND DEDUPLICATED BY ID. A job can only end once, so a
+ * second notice for the same id is always the same fact restated - which is what
+ * makes the relay's re-queueing after a queue wipe idempotent (I-11).
+ */
+import type { JobKind, ServiceStatus } from './types.js';
+export interface JobNotice {
+    /** The job: `t3` / `s1`. */
+    id: string;
+    kind: JobKind;
+    /** Always terminal - a notice is never queued for a running job. */
+    status: Extract<ServiceStatus, 'exited' | 'failed' | 'stopped'>;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    elapsedMs: number;
+    /** The last extracted progress line, when there was one. */
+    progressText?: string;
+    /** At most `PROC_LIMITS.noticeTailRows`, and only for a failure. */
+    tailRows: readonly string[];
+    at: number;
+}
+/**
+ * Insertion-ordered, deduplicated by id, bounded by `PROC_LIMITS.maxNotices`.
+ *
+ * INSERTION ORDER IS KEPT because "the oldest thing I have not told you about"
+ * is the one that has been waiting longest; the RENDERER then puts failures
+ * first, which is a display decision rather than a queue decision.
+ */
+export declare class JobNoticeQueue {
+    private readonly entries;
+    /** Same id twice keeps ONE entry: a job's terminal fact does not change. */
+    push(notice: JobNotice): void;
+    /** Take everything and reset. The one way a notice leaves this object. */
+    drain(): JobNotice[];
+    pending(): number;
+    clear(): void;
+}
+/**
+ * Render the `<job_notices>` block, or `''` when there is nothing to say.
+ *
+ * EMPTY IN, EMPTY OUT, and the wrapper that appends this to a tool result relies
+ * on it: an unconditional block would add two lines to every tool call in every
+ * session, which is the context growth this feature exists to avoid.
+ */
+export declare function renderJobNotices(notices: readonly JobNotice[]): string;

package/dist/proc/notices.js

@@ -0,0 +1,101 @@
+/**
+ * The completion-notice queue and its one renderer (long-task-jobs §4.6).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A NOTICE IS NOT A MESSAGE. It is a bounded, factual sentence about a job that
+ * ended while the model was busy, and it reaches the model through three
+ * mutually exclusive paths that all take from THIS queue - the tail of the next
+ * tool result (pull), a `steer()` at the one safe point (push), and a
+ * `steer()` before the next user turn (fill). One `drain()` behind all three is
+ * what makes "at most once" a property of the data structure rather than a
+ * promise in three call sites (I-6).
+ *
+ * THE QUEUE IS BOUNDED AND DEDUPLICATED BY ID. A job can only end once, so a
+ * second notice for the same id is always the same fact restated - which is what
+ * makes the relay's re-queueing after a queue wipe idempotent (I-11).
+ */
+import { formatDuration } from '../agent/usage.js';
+import { PROC_LIMITS } from './limits.js';
+/**
+ * Insertion-ordered, deduplicated by id, bounded by `PROC_LIMITS.maxNotices`.
+ *
+ * INSERTION ORDER IS KEPT because "the oldest thing I have not told you about"
+ * is the one that has been waiting longest; the RENDERER then puts failures
+ * first, which is a display decision rather than a queue decision.
+ */
+export class JobNoticeQueue {
+    entries = new Map();
+    /** Same id twice keeps ONE entry: a job's terminal fact does not change. */
+    push(notice) {
+        if (this.entries.has(notice.id))
+            return;
+        this.entries.set(notice.id, notice);
+        // Oldest first out when the bound is exceeded. Dropping the newest instead
+        // would bias the block towards facts the model already knows.
+        while (this.entries.size > PROC_LIMITS.maxNotices) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done === true)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+    /** Take everything and reset. The one way a notice leaves this object. */
+    drain() {
+        if (this.entries.size === 0)
+            return [];
+        const out = [...this.entries.values()];
+        this.entries.clear();
+        return out;
+    }
+    pending() {
+        return this.entries.size;
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+/** `exited code 0` / `exited signal SIGKILL` / `stopped` - the same grammar as a card. */
+function outcomeOf(notice) {
+    if (notice.status === 'stopped')
+        return 'stopped';
+    if (notice.exitCode === null) {
+        return notice.signal === null ? notice.status : `${notice.status} on ${notice.signal}`;
+    }
+    return `${notice.status} code ${notice.exitCode}`;
+}
+/** Failures first, then non-zero exits, then the rest - in queue order within a group. */
+function rank(notice) {
+    if (notice.status === 'failed')
+        return 0;
+    if (notice.status === 'exited' && notice.exitCode !== 0)
+        return 1;
+    return 2;
+}
+/**
+ * Render the `<job_notices>` block, or `''` when there is nothing to say.
+ *
+ * EMPTY IN, EMPTY OUT, and the wrapper that appends this to a tool result relies
+ * on it: an unconditional block would add two lines to every tool call in every
+ * session, which is the context growth this feature exists to avoid.
+ */
+export function renderJobNotices(notices) {
+    if (notices.length === 0)
+        return '';
+    const sorted = [...notices].sort((a, b) => rank(a) - rank(b));
+    const lines = ['<job_notices>'];
+    for (const notice of sorted.slice(0, PROC_LIMITS.maxNotices)) {
+        const progress = notice.progressText ? ` (${notice.progressText} at last check)` : '';
+        lines.push(`${notice.kind} ${notice.id} ${outcomeOf(notice)} after ` +
+            `${formatDuration(notice.elapsedMs)}${progress}`);
+        // ONLY A FAILURE EARNS A TAIL: a successful job's last rows are noise, and
+        // two lines per success is the difference between a bounded block and a log.
+        if (rank(notice) < 2) {
+            for (const row of notice.tailRows.slice(0, PROC_LIMITS.noticeTailRows)) {
+                lines.push(`  last: ${row}`);
+            }
+        }
+    }
+    lines.push('</job_notices>');
+    return lines.join('\n');
+}

package/dist/proc/progress.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Progress extraction for a long-running job (long-task-jobs §4.5).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * PURE: no IO, no clock, no process. That is what lets `progress.test.ts`
+ * enumerate the whole table, and it is why the cost of a progress line is one
+ * function call inside an already-coalesced output tick rather than a second
+ * subscription to the child's stdio.
+ *
+ * THE POINT IS EXTRACTION, NOT TRANSPORT. The alternative - handing the model
+ * the last 200 rows so it can notice the `47%` itself - costs 4k-8k tokens per
+ * check and buries the one number that matters. Here the ring keeps the rows and
+ * the model gets `47%`.
+ *
+ * NOTHING DECIDES ANYTHING FROM THIS (R-4). Progress is a REPORT. `status`,
+ * `exitCode` and `signal` are the only things a job's outcome is ever read from,
+ * so a false `100%` in `[100%] built target foo` costs one confusing word rather
+ * than a wrong conclusion.
+ */
+export type ProgressKind = 'percent' | 'ratio' | 'epoch' | 'bytes' | 'text';
+export interface JobProgress {
+    /** Already clipped to `PROC_LIMITS.waitProgressChars`. */
+    text: string;
+    kind: ProgressKind;
+    /** `carry` = the not-yet-newline-terminated line, where every progress bar lives. */
+    source: 'row' | 'carry';
+    /** Index into the scanned window; `-1` for the carry line. Diagnostics and tests only. */
+    rowIndex: number;
+}
+/**
+ * Extract one line of progress from the tail of a job's output.
+ *
+ * `rows` is the scan window (the caller passes at most
+ * `PROC_LIMITS.progressScanRows`); `carry` is the not-yet-terminated line, which
+ * is where a `\r`-rewritten bar keeps its whole life. Returns `undefined` when
+ * nothing but decoration has been printed - an honest "there is no progress to
+ * show", which the callers render as absence rather than as a fake `0%`.
+ */
+export declare function extractProgress(rows: readonly string[], carry: string): JobProgress | undefined;

package/dist/proc/progress.js

@@ -0,0 +1,135 @@
+/**
+ * Progress extraction for a long-running job (long-task-jobs §4.5).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * PURE: no IO, no clock, no process. That is what lets `progress.test.ts`
+ * enumerate the whole table, and it is why the cost of a progress line is one
+ * function call inside an already-coalesced output tick rather than a second
+ * subscription to the child's stdio.
+ *
+ * THE POINT IS EXTRACTION, NOT TRANSPORT. The alternative - handing the model
+ * the last 200 rows so it can notice the `47%` itself - costs 4k-8k tokens per
+ * check and buries the one number that matters. Here the ring keeps the rows and
+ * the model gets `47%`.
+ *
+ * NOTHING DECIDES ANYTHING FROM THIS (R-4). Progress is a REPORT. `status`,
+ * `exitCode` and `signal` are the only things a job's outcome is ever read from,
+ * so a false `100%` in `[100%] built target foo` costs one confusing word rather
+ * than a wrong conclusion.
+ */
+import { PROC_LIMITS } from './limits.js';
+/**
+ * The ordered table (first match wins PER ROW, newest row scanned first).
+ *
+ * BYTES SITS ABOVE THE GENERIC RATIO, and that rewrites the order the design
+ * document lists. `1.2/3.4 GiB` satisfies the generic ratio pattern as `2/3`
+ * (the digits either side of the slash, with `.` a word boundary), so a table
+ * that tried `\d+/\d+` first would report every download as `2/3`. The document's
+ * constraint - ordered, anchored, single-line, no backtracking blowup - is kept;
+ * only the relative order of those two rows changed. Recorded in
+ * `docs/plans/long-task-jobs/spec.md` under `## 实施过程发现的方案缺陷` (I-1).
+ */
+const PERCENT = /(\d{1,3}(?:\.\d+)?)\s*%/;
+const EPOCH_STEP = /\b(epoch|step)\s+(\d{1,7})\s*\/\s*(\d{1,7})/i;
+const BYTES = /(\d+(?:\.\d+)?)\s*(GiB|MiB|KiB|GB|MB|KB|gb|mb|kb|gib|mib)?\s*\/\s*(\d+(?:\.\d+)?)\s*(GiB|MiB|KiB|GB|MB|KB|gb|mb|kb|gib|mib)/;
+const RATIO = /[\[(]?\b(\d{1,7})\s*\/\s*(\d{1,7})\b[\])]?/;
+const ETA = /ETA[^0-9]{0,4}([0-9:]+[a-z]*)/i;
+/** A row that is decoration, not information: `...`, `|`, `-`, `===`, a bare path separator. */
+const NOISE = /^[\s.\-_=|\\/+*#>~]+$/;
+/** Clip to the one-line budget, ASCII ellipsis, never mid-surrogate. */
+function clip(text, limit = PROC_LIMITS.waitProgressChars) {
+    // VERTICAL whitespace only is collapsed: a stray `\r` or `\n` would break the
+    // one-row contract, while the DOUBLE SPACE before `ETA` is how the row is meant
+    // to read (`47%  ETA 13m`) and collapsing it would make the table's rendering
+    // depend on which function ran last.
+    const flat = text.replace(/[\r\n\t]+/g, ' ').trim();
+    if (flat.length <= limit)
+        return flat;
+    return `${flat.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
+}
+/**
+ * The structured signals for one line, in table order.
+ *
+ * ORDER WITHIN A LINE IS THE TABLE'S ORDER; the caller decides which LINE wins
+ * (newest first), because a live `47%` must beat a stale `100%` from the phase
+ * above it.
+ */
+function signalsOf(line) {
+    const percent = PERCENT.exec(line);
+    if (percent?.[1])
+        return { text: `${percent[1]}%`, kind: 'percent' };
+    const epoch = EPOCH_STEP.exec(line);
+    if (epoch?.[1] && epoch[2] !== undefined && epoch[3] !== undefined) {
+        return { text: `${epoch[1].toLowerCase()} ${epoch[2]}/${epoch[3]}`, kind: 'epoch' };
+    }
+    const bytes = BYTES.exec(line);
+    if (bytes?.[1] && bytes[3]) {
+        // Normalised to the TOTAL's unit, which is the one the user's own command
+        // printed: `1.2/3.4 GiB` reads, `1.2 GiB/3.4 GiB` is noise. The numerator's
+        // unit is optional because the common form writes it once, at the end.
+        return { text: `${bytes[1]}/${bytes[3]} ${bytes[4]}`, kind: 'bytes' };
+    }
+    const ratio = RATIO.exec(line);
+    if (ratio?.[1] && ratio[2] !== undefined) {
+        return { text: `${ratio[1]}/${ratio[2]}`, kind: 'ratio' };
+    }
+    return undefined;
+}
+/** Append the ETA once, when the window names one. */
+function withEta(signal, window) {
+    if (signal.text.includes('ETA'))
+        return signal;
+    for (const line of window) {
+        const eta = ETA.exec(line);
+        if (eta?.[1])
+            return { text: `${signal.text}  ETA ${eta[1]}`, kind: signal.kind };
+    }
+    return signal;
+}
+/**
+ * Extract one line of progress from the tail of a job's output.
+ *
+ * `rows` is the scan window (the caller passes at most
+ * `PROC_LIMITS.progressScanRows`); `carry` is the not-yet-terminated line, which
+ * is where a `\r`-rewritten bar keeps its whole life. Returns `undefined` when
+ * nothing but decoration has been printed - an honest "there is no progress to
+ * show", which the callers render as absence rather than as a fake `0%`.
+ */
+export function extractProgress(rows, carry) {
+    const displayCarry = carry.trim();
+    // NEWEST FIRST, INSIDE ONE WINDOW. The carry line is the newest of all by
+    // definition, so it is tested before every completed row.
+    const candidates = [];
+    if (displayCarry.length > 0 && !NOISE.test(displayCarry)) {
+        candidates.push({ line: displayCarry, source: 'carry', rowIndex: -1 });
+    }
+    for (let i = rows.length - 1; i >= 0; i -= 1) {
+        const line = rows[i] ?? '';
+        if (line.trim().length === 0 || NOISE.test(line))
+            continue;
+        candidates.push({ line, source: 'row', rowIndex: i });
+    }
+    const window = candidates.map((c) => c.line);
+    for (const candidate of candidates) {
+        const signal = signalsOf(candidate.line);
+        if (!signal)
+            continue;
+        return {
+            text: clip(withEta(signal, window).text),
+            kind: signal.kind,
+            source: candidate.source,
+            rowIndex: candidate.rowIndex,
+        };
+    }
+    // Fallback: the newest line that at least says something.
+    const last = candidates[0];
+    if (!last)
+        return undefined;
+    return {
+        text: clip(last.line),
+        kind: 'text',
+        source: last.source,
+        rowIndex: last.rowIndex,
+    };
+}

package/dist/proc/prompt.d.ts

@@ -19,6 +19,28 @@
  * `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 };
+/**
+ * The `<background_jobs>` system-prompt block (long-task-jobs §12).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope, and this string
+ * also reaches a model running in a `cmd.exe` terminal.
+ *
+ * SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what preserves I-3: with
+ * `jobs.enabled: false` the prompt is BYTE-IDENTICAL to the pre-feature output.
+ *
+ * EVERY SENTENCE HERE ANSWERS A DECISION THE MODEL ACTUALLY HAS TO MAKE:
+ *  - "do not poll" is the behaviour this feature exists to replace (six
+ *    `bash_output` calls per 30 seconds, six LLM turns, six 200-row tails);
+ *  - "a bounded wait is the only thing that tells you it finished" prevents the
+ *    opposite failure, a model that starts a job and then guesses;
+ *  - "`<job_notices>` is the notification, not an error" stops it apologising for
+ *    a block that is good news;
+ *  - "`[stalled]` is not a failure" stops it killing a job that is merely quiet.
+ *
+ * `JOBS_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { JOBS_BLOCK_VERSION } from './limits.js';
+export { JOBS_BLOCK_VERSION };
+export declare function buildBackgroundJobsBlock(): string;
 export declare function buildBackgroundServicesBlock(): string;