@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/config/schema.d.ts

@@ -39,6 +39,17 @@ export declare function isThemeName(v: unknown): v is ThemeName;
  * and would not match `clampThinkingLevel` / `clampTranscriptWindow`.
  */
 export declare function clampTheme(v: unknown, fallback: ThemeName): ThemeName;
+export declare const SCROLL_MODES: readonly ["native", "app"];
+/**
+ * How the interactive TUI scrolls (tui-native-terminal-scroll D1).
+ *
+ * `native` prints settled conversation into the host terminal's own scrollback and
+ * keeps only a bounded live region on screen; `app` is the original full-screen
+ * alternate-screen layout with application-owned scrolling.
+ */
+export type ScrollMode = (typeof SCROLL_MODES)[number];
+export declare const DEFAULT_SCROLL_MODE: ScrollMode;
+export declare function clampScrollMode(v: unknown, fallback: ScrollMode): ScrollMode;
 export declare const DENSITY_MODES: readonly ["comfortable", "compact"];
 export type DensityMode = (typeof DENSITY_MODES)[number];
 export declare function clampDensity(v: unknown, fallback: DensityMode): DensityMode;
@@ -784,6 +795,62 @@ export declare const DEFAULT_BASH_CONFIG: BashConfig;
  * A garbage `startupSettleMs` resolves to 4000 and throws nothing.
  */
 export declare function clampBashConfig(raw: unknown): BashConfig;
+export interface JobsConfig {
+    /**
+     * Register `job_wait` / `job_list`, splice the `<background_jobs>` block,
+     * mirror job logs. Default TRUE.
+     *
+     * READ ONCE AT CONSTRUCTION, the `bash.background` / `team.enabled` rule. Its
+     * job is to be the single switch under which the tool array, the tool
+     * descriptions and the system prompt are BYTE-IDENTICAL to the pre-feature
+     * build (I-3) - which is why it is a registration switch and not a behaviour
+     * flag.
+     */
+    enabled: boolean;
+    /**
+     * Seconds one `job_wait` blocks by default. Default 30, range 5..60.
+     *
+     * ALSO CONVERGED AGAINST THE TOOL CEILING at load time and again at call time
+     * (I-4): a wait that outlives the tool call hosting it would turn every long
+     * job into `Command timed out`, which is the defect this feature removes.
+     */
+    waitSeconds: number;
+    /**
+     * Seconds without output before a job is reported `[stalled]`. Default 300,
+     * range 30..3600.
+     *
+     * A REPORT, NEVER AN ACTION: nothing kills or retries on this (R-13). The
+     * default is deliberately generous, because a training epoch that prints every
+     * five minutes is healthy.
+     */
+    stallSeconds: number;
+    /**
+     * Mirror each job's full output to `<home>/jobs/<session>/<id>.log`. Default
+     * TRUE; `false` creates no directory at all, for privacy- or IO-sensitive
+     * environments (D-6).
+     */
+    persistLog: boolean;
+    /**
+     * Whether a completion notice may STEER the running turn. Default TRUE.
+     *
+     * NOT A NOTICE SWITCH (§6.5). With this off, notices still arrive at the end of
+     * the next tool result and before the next user turn; only the active
+     * interruption stops. Turning notifications off entirely would require running
+     * no jobs.
+     */
+    noticeSteer: boolean;
+}
+export declare const DEFAULT_JOBS_CONFIG: JobsConfig;
+/**
+ * THE single gate for every `jobs` read AND write, mirroring `clampBashConfig`
+ * and the four sections before it.
+ *
+ * THE ELEVENTH SECTION, AND THE FIRST ONE THAT `config set` CAN REACH BY
+ * NESTED KEY (§6.5). Every key is a SCALAR and the section is ONE level deep,
+ * because `runConfigGet` splits on a single dot - a `jobs.mirror.enabled` would
+ * resolve to `undefined` and the setting would silently never apply.
+ */
+export declare function clampJobsConfig(raw: unknown): JobsConfig;
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -864,6 +931,8 @@ export interface PersistedConfig {
     maxRenderIntervalMs: number;
     /** Repaint only the frame rows that changed (tui-input-flicker-fix §5.1). */
     diffRender: boolean;
+    /** Native terminal scrolling vs the full-screen app layout (tui-native-terminal-scroll D1). */
+    scrollMode: ScrollMode;
     /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
     syncOutput: boolean;
     confirmTools: boolean;
@@ -942,6 +1011,8 @@ export interface PersistedConfig {
     compaction: CompactionConfig;
     /** Background services. The TENTH nested object; scalars only (see BashConfig). */
     bash: BashConfig;
+    /** Background jobs and bounded waiting. The ELEVENTH; scalars only (see JobsConfig). */
+    jobs: JobsConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -1068,6 +1139,20 @@ export interface CliConfig {
      * with no compile error and no runtime error.
      */
     diffRender: boolean;
+    /**
+     * Native terminal scrolling vs the full-screen app layout
+     * (tui-native-terminal-scroll D1).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `diffRender` above records: `runInteractive` reads `config.scrollMode`, where
+     * `config` is a `CliConfig`, so a key added to the persisted shape alone would
+     * round-trip through `config set` and never reach the screen plan.
+     *
+     * OPTIONAL ON THIS SHAPE ONLY so the many hand-built `CliConfig` fixtures in the
+     * test suite stay valid without edits (I-S9); `loadConfig` always sets it and
+     * the one reader (`runInteractive`) falls back to `DEFAULT_SCROLL_MODE`.
+     */
+    scrollMode?: ScrollMode;
     /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
     syncOutput: boolean;
     confirmTools: boolean;
@@ -1235,6 +1320,21 @@ export interface CliConfig {
      * either of them.
      */
     bash: BashConfig;
+    /**
+     * Background jobs and bounded waiting (long-task-jobs §6.5). The ELEVENTH
+     * nested object; five scalar keys, one level deep.
+     *
+     * ON `CliConfig` AS WELL AS `PersistedConfig`, for the reason every section
+     * above records: `AgentController` reads `config.jobs.waitSeconds` through a
+     * closure and `job_wait` reads it again at call time, so a key persisted and
+     * never projected would round-trip through `config set`, show up in
+     * `config list`, and change nothing.
+     *
+     * ONE LEVEL DEEP IS A HARD REQUIREMENT, NOT A PREFERENCE: `runConfigGet` splits
+     * `jobs.waitSeconds` on a single dot, so a nested sub-object would resolve to
+     * `undefined` and report an empty value for a setting that IS on disk.
+     */
+    jobs: JobsConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -69,6 +69,14 @@ export function clampTheme(v, fallback) {
 // ---------------------------------------------------------------------------
 // Density / hints (v0.4.0)
 // ---------------------------------------------------------------------------
+export const SCROLL_MODES = ['native', 'app'];
+export const DEFAULT_SCROLL_MODE = 'native';
+export function clampScrollMode(v, fallback) {
+    if (typeof v !== 'string')
+        return fallback;
+    const normalized = v.trim().toLowerCase();
+    return normalized === 'native' || normalized === 'app' ? normalized : fallback;
+}
 export const DENSITY_MODES = ['comfortable', 'compact'];
 export function clampDensity(v, fallback) {
     return v === 'comfortable' || v === 'compact' ? v : fallback;
@@ -922,6 +930,34 @@ export function clampBashConfig(raw) {
         readyTimeoutMs: clampInt(src.readyTimeoutMs, DEFAULT_BASH_CONFIG.readyTimeoutMs, READY_TIMEOUT_RANGE),
     };
 }
+export const DEFAULT_JOBS_CONFIG = {
+    enabled: true,
+    waitSeconds: 30,
+    stallSeconds: 300,
+    persistLog: true,
+    noticeSteer: true,
+};
+const WAIT_SECONDS_RANGE = { min: 5, max: 60 };
+const STALL_SECONDS_RANGE = { min: 30, max: 3600 };
+/**
+ * THE single gate for every `jobs` read AND write, mirroring `clampBashConfig`
+ * and the four sections before it.
+ *
+ * THE ELEVENTH SECTION, AND THE FIRST ONE THAT `config set` CAN REACH BY
+ * NESTED KEY (§6.5). Every key is a SCALAR and the section is ONE level deep,
+ * because `runConfigGet` splits on a single dot - a `jobs.mirror.enabled` would
+ * resolve to `undefined` and the setting would silently never apply.
+ */
+export function clampJobsConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        enabled: bool(src.enabled, DEFAULT_JOBS_CONFIG.enabled),
+        waitSeconds: clampInt(src.waitSeconds, DEFAULT_JOBS_CONFIG.waitSeconds, WAIT_SECONDS_RANGE),
+        stallSeconds: clampInt(src.stallSeconds, DEFAULT_JOBS_CONFIG.stallSeconds, STALL_SECONDS_RANGE),
+        persistLog: bool(src.persistLog, DEFAULT_JOBS_CONFIG.persistLog),
+        noticeSteer: bool(src.noticeSteer, DEFAULT_JOBS_CONFIG.noticeSteer),
+    };
+}
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -970,6 +1006,7 @@ export const DEFAULT_CONFIG = {
     renderGovernor: DEFAULT_RENDER_GOVERNOR,
     maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
     diffRender: DEFAULT_DIFF_RENDER,
+    scrollMode: DEFAULT_SCROLL_MODE,
     syncOutput: DEFAULT_SYNC_OUTPUT,
     confirmTools: false,
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
@@ -1019,6 +1056,12 @@ export const DEFAULT_CONFIG = {
     // `undefined` would arrive with background services OFF for every existing
     // user — the same direction the compaction line above must never fail in.
     bash: DEFAULT_BASH_CONFIG,
+    // And one section later again, for the sixth time, and this one would fail
+    // in the WORSE direction: every key in `jobs` is `true` or positive by
+    // default, so a `config.json` predating this feature resolving `config.jobs`
+    // to `undefined` would throw on `config.jobs.waitSeconds` at construction
+    // rather than quietly disabling something.
+    jobs: DEFAULT_JOBS_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -17,7 +17,7 @@ import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerProfileSecrets, registerSecretsFrom } from '../logging/secret-registry.js';
 import { adaptLegacyConnectionPatch, ModelProfileConfigError, readModelSettingsDisk } from './model-profile-store.js';
 import { normalizeModelProfiles } from './model-profiles.js';
-import { clampBashConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { clampBashConfig, clampJobsConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -189,6 +189,12 @@ export function normalizePersistedConfig(input) {
         // and NOT merged over the defaults, which is verbatim the failure the
         // paragraph above says this line prevents.
         bash: clampBashConfig({ ...DEFAULT_CONFIG.bash, ...(partial.bash ?? {}) }),
+        // And the eleventh, on the same line and for the same reason. `jobs.enabled`
+        // is `true` by default, so a user whose `config.json` predates this feature
+        // must not resolve it to `undefined` — and `waitSeconds` would be `undefined`
+        // outright, which is a crash on the first `job_wait` rather than a silently
+        // wrong setting.
+        jobs: clampJobsConfig({ ...DEFAULT_CONFIG.jobs, ...(partial.jobs ?? {}) }),
     };
 }
 /**
@@ -289,6 +295,13 @@ export function mergePersistedConfig(current, patch) {
         // top level and write `background` absent, silently unregistering
         // `bash_output` / `bash_kill` from the next launch onward.
         bash: clampBashConfig({ ...current.bash, ...(patch.bash ?? {}) }),
+        // The eleventh section, and the sixth time this file records the same trap.
+        // `aragon config set jobs.waitSeconds 45` sends `{ jobs: { waitSeconds: 45 } }`;
+        // without this line the shallow top-level spread REPLACES the section and
+        // `persistLog` / `noticeSteer` / `enabled` / `stallSeconds` are written
+        // absent — with `noticeSteer`'s default masking it on the next load, so the
+        // user would never learn that their privacy switch had been turned back on.
+        jobs: clampJobsConfig({ ...current.jobs, ...(patch.jobs ?? {}) }),
     };
     return merged;
 }

package/dist/config/ui-state.d.ts

@@ -84,6 +84,12 @@ export interface UiState {
      * older file, which is the behaviour wanted here anyway.
      */
     vtInputNoticeVersion: number;
+    /**
+     * Which revision of the "scrolling now uses your terminal" notice this user has
+     * been shown (`0` = none; tui-native-terminal-scroll D12). A scalar beside the
+     * others for the same reasons the two above record, and NOT a schema bump.
+     */
+    scrollModeNoticeVersion: number;
 }
 /** Read the state, caching it for the life of the process. Never throws. */
 export declare function loadUiState(): UiState;
@@ -98,6 +104,9 @@ export declare function setMouseNoticeVersion(version: number): void;
 /** `0` on a file written before the field existed — see the field's comment. */
 export declare function getVtInputNoticeVersion(): number;
 export declare function setVtInputNoticeVersion(version: number): void;
+/** `0` on a file written before the field existed. */
+export declare function getScrollModeNoticeVersion(): number;
+export declare function setScrollModeNoticeVersion(version: number): void;
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/config/ui-state.js

@@ -37,6 +37,7 @@ const DEFAULT_UI_STATE = {
     mouseNoticeSeen: false,
     mouseNoticeVersion: 0,
     vtInputNoticeVersion: 0,
+    scrollModeNoticeVersion: 0,
 };
 let memory = null;
 /** Non-negative integer or `fallback`; shared by both numeric fields. */
@@ -69,6 +70,7 @@ function readFromDisk() {
                 : DEFAULT_UI_STATE.mouseNoticeSeen,
             mouseNoticeVersion: coerceCount(parsed.mouseNoticeVersion, DEFAULT_UI_STATE.mouseNoticeVersion),
             vtInputNoticeVersion: coerceCount(parsed.vtInputNoticeVersion, DEFAULT_UI_STATE.vtInputNoticeVersion),
+            scrollModeNoticeVersion: coerceCount(parsed.scrollModeNoticeVersion, DEFAULT_UI_STATE.scrollModeNoticeVersion),
         };
     }
     catch {
@@ -142,6 +144,13 @@ export function getVtInputNoticeVersion() {
 export function setVtInputNoticeVersion(version) {
     update({ vtInputNoticeVersion: version });
 }
+/** `0` on a file written before the field existed. */
+export function getScrollModeNoticeVersion() {
+    return loadUiState().scrollModeNoticeVersion;
+}
+export function setScrollModeNoticeVersion(version) {
+    update({ scrollModeNoticeVersion: version });
+}
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/exec/events.d.ts

@@ -9,8 +9,11 @@
  *
  * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
  * `node:`-free type space, so a consumer of this module cannot accidentally
- * evaluate the runner.
- *
+ * evaluate the runner. The one import below is a TYPE from `proc/types.ts` for
+ * the same reason: a shape, erased at compile time.
+ */
+import type { ServiceStatus } from '../proc/types.js';
+/**
  * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
  * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
  * That rule only holds if consumers keep their side of it, so the README states
@@ -370,7 +373,30 @@ export interface ExecResultEvent {
     todos: ExecTodoCounts | null;
     error: ExecErrorInfo | null;
 }
-export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTurnStateEvent | ExecProgressEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecFastTierEvent | ExecCompactionEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
+/**
+ * A background job's lifecycle (long-task-jobs §4.10).
+ *
+ * A PURE ADDITION to schema v1: a consumer that does not know this `type`
+ * ignores it, which is the forward-compatibility contract this file's header
+ * states. `progress` is emitted only when the extracted text CHANGES and at most
+ * once a second - a 40-minute training run would otherwise write thousands of
+ * lines to a machine consumer's stdout.
+ */
+export interface ExecJobEvent {
+    type: 'job';
+    schemaVersion: number;
+    sessionId: string;
+    subtype: 'started' | 'progress' | 'exited' | 'stalled';
+    /** `t3` / `s1`. */
+    jobId: string;
+    kind: 'service' | 'task';
+    status: ServiceStatus;
+    elapsedMs: number;
+    /** Only on `subtype === 'progress'`, and only when the text changed. */
+    progress?: string;
+    exitCode?: number | null;
+}
+export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTurnStateEvent | ExecProgressEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecFastTierEvent | ExecCompactionEvent | ExecRetryEvent | ExecJobEvent | ExecErrorEvent | ExecResultEvent;
 /** Everything `system/init` needs that the runner cannot derive for itself. */
 export interface ExecInitParams {
     sessionId: string;

package/dist/exec/events.js

@@ -1,16 +1,4 @@
 /**
- * THE CONTRACT (cli-integration-surface section 5.1).
- *
- * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope
- * (`glyphs.test.ts::inScope`, R-3 / AC-25). Every string here can reach a
- * consumer's terminal through `--output-format text` fallbacks or a stderr
- * warning, and the whole point of the scanner is that a legacy `cmd.exe` shows
- * mojibake for anything else.
- *
- * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
- * `node:`-free type space, so a consumer of this module cannot accidentally
- * evaluate the runner.
- *
  * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
  * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
  * That rule only holds if consumers keep their side of it, so the README states
@@ -53,6 +41,9 @@ export const EXEC_CAPABILITIES = [
     'session-file',
     'turn-lifecycle',
     'execution-progress',
+    // Background job lifecycle events (long-task-jobs §4.10). A consumer that does
+    // not know the `job` type ignores it; this string is how it asks first.
+    'background-jobs',
 ];
 export function buildInitEvent(params) {
     return {

package/dist/exec/runner.d.ts

@@ -20,6 +20,7 @@ import { type FollowThroughMode } from '../todo/follow-through.js';
 import type { ExecEmitter } from './emitter.js';
 import type { FastSnapshot } from '../fast/types.js';
 import type { ExecStopReason } from './events.js';
+import type { ProcEvent } from '../proc/types.js';
 /**
  * The controller surface the runner needs.
  *
@@ -45,6 +46,14 @@ export interface ExecRunnerController extends HeadlessController {
      * it simply emits no `fast_tier` events.
      */
     fastSnapshot?(): FastSnapshot | null;
+    /**
+     * The CLI-local process stream, when this session supervises processes.
+     *
+     * OPTIONAL AND CALLED WITH `?.()`, exactly like the three optional streams
+     * above: this interface is minimal so a test can satisfy it with an object
+     * literal, and a host with no supervisor has nothing to report.
+     */
+    subscribeProc?(listener: (event: ProcEvent) => void): () => void;
 }
 /** Where the caller's messages come from. One turn, or an NDJSON stdin stream. */
 export interface ExecPromptSource {
@@ -97,6 +106,10 @@ export declare class ExecRunner {
     private readonly progress;
     private controller;
     private unsubscribers;
+    /** Per-job progress throttle state: the last text emitted, and when. */
+    private readonly jobProgressAt;
+    /** Per-job `lastOutputAt` at which `stalled` was last reported. */
+    private readonly jobStalledAt;
     private turns;
     private readonly usage;
     private compactionBilling;
@@ -123,6 +136,17 @@ export declare class ExecRunner {
      * multiple subscribers.
      */
     attach(controller: ExecRunnerController): void;
+    /**
+     * Map a supervisor event onto the `job` channel.
+     *
+     * THROTTLING IS THE WHOLE DISCIPLINE HERE. `output` is already coalesced to
+     * <=10 Hz inside the supervisor, which is still far too fast for a machine
+     * consumer reading a 40-minute training run; `progress` is therefore emitted
+     * only when the extracted TEXT CHANGES and never more than once a second. The
+     * other three subtypes are one-shot per job, so they pass straight through.
+     */
+    private onProcEvent;
+    private emitJob;
     /**
      * Drop the subscriptions and the timer.
      *

package/dist/exec/runner.js

@@ -17,6 +17,7 @@
 import { formatStreamError } from '../agent/reducer.js';
 import { setSignalTerminator } from '../logging/install.js';
 import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
+import { EXEC_SCHEMA_VERSION } from './events.js';
 import { ExecProgressReporter } from './progress-reporter.js';
 export function singlePrompt(text) {
     let served = false;
@@ -44,6 +45,10 @@ export class ExecRunner {
     progress;
     controller = null;
     unsubscribers = [];
+    /** Per-job progress throttle state: the last text emitted, and when. */
+    jobProgressAt = new Map();
+    /** Per-job `lastOutputAt` at which `stalled` was last reported. */
+    jobStalledAt = new Map();
     turns = 0;
     usage = { inputTokens: 0, outputTokens: 0 };
     compactionBilling;
@@ -218,8 +223,82 @@ export class ExecRunner {
         });
         if (compaction)
             this.unsubscribers.push(compaction);
+        // Background jobs (long-task-jobs §4.10). SUBSCRIBED HERE, IN `attach()`, NOT
+        // IN `start()`: the follow-through chain enters `run()` more than once, and a
+        // subscription made there would be re-made every time and never released —
+        // one leaked listener per turn for the life of the process.
+        //
+        // The four-stream shape is deliberate: `?:` optional call, `unsubscribers`
+        // push, `detach()` releases. Identical to `subscribeTeam` / `subscribeTodos` /
+        // `subscribeFast` / `subscribeCompaction`, so a host without a supervisor
+        // simply emits nothing.
+        const proc = controller.subscribeProc?.((event) => this.onProcEvent(event));
+        if (proc)
+            this.unsubscribers.push(proc);
         this.installTerminator();
     }
+    /**
+     * Map a supervisor event onto the `job` channel.
+     *
+     * THROTTLING IS THE WHOLE DISCIPLINE HERE. `output` is already coalesced to
+     * <=10 Hz inside the supervisor, which is still far too fast for a machine
+     * consumer reading a 40-minute training run; `progress` is therefore emitted
+     * only when the extracted TEXT CHANGES and never more than once a second. The
+     * other three subtypes are one-shot per job, so they pass straight through.
+     */
+    onProcEvent(event) {
+        const job = event.service;
+        if (event.type === 'started') {
+            this.emitJob(job, 'started');
+            return;
+        }
+        if (event.type === 'exited' || event.type === 'stopped') {
+            this.jobProgressAt.delete(job.id);
+            this.jobStalledAt.delete(job.id);
+            this.emitJob(job, 'exited');
+            return;
+        }
+        // `ready` is deliberately NOT mapped onto a second `started`: a service emits
+        // both, and a consumer that counted `started` events would see two. The
+        // readiness fact is already carried by `status` on any later event, and the
+        // four subtypes this channel publishes are one-shot per job.
+        if (event.type !== 'output')
+            return;
+        if (job.stalled === true) {
+            if (this.jobStalledAt.get(job.id) === job.lastOutputAt)
+                return;
+            this.jobStalledAt.set(job.id, job.lastOutputAt);
+            this.emitJob(job, 'stalled');
+            return;
+        }
+        const text = job.progress?.text;
+        if (text === undefined)
+            return;
+        if (this.jobProgressAt.get(job.id)?.text === text)
+            return;
+        const now = Date.now();
+        const last = this.jobProgressAt.get(job.id)?.at ?? 0;
+        // ONE SECOND IS THE FLOOR, and the first change of a job is always emitted
+        // (no previous entry), so a consumer sees the initial figure immediately.
+        if (last !== 0 && now - last < 1000)
+            return;
+        this.jobProgressAt.set(job.id, { text, at: now });
+        this.emitJob(job, 'progress', text);
+    }
+    emitJob(job, subtype, progress) {
+        this.emit({
+            type: 'job',
+            schemaVersion: EXEC_SCHEMA_VERSION,
+            sessionId: this.sessionId,
+            subtype,
+            jobId: job.id,
+            kind: job.kind,
+            status: job.status,
+            elapsedMs: Math.max(0, (job.endedAt ?? Date.now()) - job.startedAt),
+            ...(progress !== undefined ? { progress } : {}),
+            ...(subtype === 'exited' ? { exitCode: job.exitCode } : {}),
+        });
+    }
     /**
      * Drop the subscriptions and the timer.
      *

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;