@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/commands/builtins.js

@@ -9,6 +9,7 @@ import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { resolveOutputTokens } from '@aragon-agent/core';
 import { clampThinkingLevel, clampTheme, isAdapterProvider, isThemeName, parseMaxTokensInput, ADAPTER_PROVIDERS, DEFAULT_MAX_TOKENS, HARD_MAX_RETRIES, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
+import { isTerminalStatus } from '../proc/types.js';
 import { computeCost, formatCost, formatDuration, formatTokens } from '../agent/usage.js';
 import { mergePendingEntries } from '../agent/queued-messages.js';
 import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
@@ -1122,6 +1123,10 @@ const COMMANDS = [
         name: 'mouse',
         description: 'Release the mouse to the terminal, or take it back',
         run: (ctx) => {
+            if (ctx.nativeScroll) {
+                ctx.notify('info', 'Mouse capture is not used in native scroll mode; your terminal handles scrolling and selection.');
+                return;
+            }
             const port = ctx.mouse;
             if (!port) {
                 // Inline mode, `--no-mouse`, a non-TTY, or a console that cannot deliver
@@ -1252,7 +1257,7 @@ const COMMANDS = [
     perfCommand,
     {
         name: 'bg',
-        description: 'Background services: list | logs <id> [n] | stop <id|all> | status',
+        description: 'Background jobs: list | logs <id> [n] | stop <id|all> | status',
         /**
          * THE USER'S HANDLE ON WHAT THE AGENT LEFT RUNNING (§5.3).
          *
@@ -1273,9 +1278,18 @@ const COMMANDS = [
             const services = controller.listServices();
             if (verb === 'status') {
                 const live = controller.liveServiceCount();
-                ctx.notify('info', live === 0
-                    ? 'No background services running.'
-                    : `${live} background service${live === 1 ? '' : 's'} running.`);
+                if (live === 0) {
+                    ctx.notify('info', 'No background jobs running.');
+                    return;
+                }
+                // THE KIND SPLIT IS THE INFORMATION (long-task-jobs §4.9): "2 jobs
+                // running" is not the same as "1 task, 1 service". A task will end on its
+                // own; a service will not, and that difference decides whether the user
+                // has to do anything.
+                const running = services.filter((job) => !isTerminalStatus(job.status));
+                const tasks = running.filter((job) => job.kind === 'task').length;
+                ctx.notify('info', `${live} background job${live === 1 ? '' : 's'} running ` +
+                    `(${tasks} task, ${running.length - tasks} service).`);
                 return;
             }
             if (verb === 'logs') {
@@ -1285,7 +1299,7 @@ const COMMANDS = [
                 }
                 const service = controller.getServiceSnapshot(value);
                 if (!service) {
-                    ctx.notify('warn', `No service "${value}".`);
+                    ctx.notify('warn', `No job "${value}".`);
                     return;
                 }
                 const page = controller.readServiceLog(value);
@@ -1331,12 +1345,17 @@ const COMMANDS = [
                 return;
             }
             const now = Date.now();
+            // `id  kind  status  elapsed  progress|url  $ command` - the same column
+            // grammar `job_list` uses for the model, so a user reading `/bg list` and a
+            // model reading `job_list` see the same facts in the same order.
             const lines = services.map((svc) => {
                 const uptime = formatDuration((svc.endedAt ?? now) - svc.startedAt);
-                const where = svc.url ? `  ${svc.url}` : '';
-                return `${svc.id}  ${svc.status}  ${uptime}${where}  $ ${svc.command}`;
+                const aside = svc.progress?.text ?? svc.url;
+                const where = aside ? `  ${aside}` : '';
+                const stalled = svc.stalled === true ? '  [no output]' : '';
+                return `${svc.id}  ${svc.kind}  ${svc.status}  ${uptime}${where}${stalled}  $ ${svc.command}`;
             });
-            ctx.notify('info', `Background services:\n${lines.join('\n')}`);
+            ctx.notify('info', `Background jobs:\n${lines.join('\n')}`);
         },
     },
     {

package/dist/commands/perf.d.ts

@@ -17,6 +17,7 @@
  */
 import type { FrameWriterStats } from '../ui/frame-differ.js';
 import type { ScrollbarBridge } from '../ui/scrollbar-controller.js';
+import type { AnchorSource } from '../ui/scrollback/canvas.js';
 import type { SlashCommand } from './registry.js';
 export interface PerfSnapshot {
     /** Governor rung, its resolved interval, and the last measured commit cost. */
@@ -34,11 +35,38 @@ export interface PerfSnapshot {
     heightsEstimated: number;
     cols: number;
     /** Geometry. */
-    mode: 'fullscreen';
+    mode: 'fullscreen' | 'native';
+    /** Full-screen: the transcript viewport. Native: the live region height. */
     viewportRows: number;
     offset: number;
     /** Right-edge scrollbar diagnostics; read lazily so it reflects the live bridge. */
     scrollbar?: ScrollbarPerf;
+    /**
+     * The native panel band, or `null` outside native mode
+     * (release-gate-and-native-panels §6.10).
+     *
+     * REQUIRED, WITH AN EXPLICIT `null`. This feature has six ways to show nothing and
+     * four of them are invisible, so "the rail is gone" has to be answerable from one
+     * line. An optional field would let a future caller forget it and leave `/perf`
+     * silently unable to explain the case the user is reporting.
+     */
+    band: BandPerf | null;
+}
+/**
+ * The band's projection, as `/perf` reads it. Counts only - the allocation itself lives
+ * in `ui/scrollback/band.ts` (`LiveBand`), and this type exists so the command layer
+ * does not have to import a UI module to describe it.
+ */
+export interface BandPerf {
+    reason: 'visible' | 'empty' | 'disabled' | 'overlay' | 'narrow' | 'short';
+    railRows: number;
+    railCols: number;
+    teamRows: number;
+    previewRows: number;
+    contentCols: number;
+    previewCols: number;
+    heldRailRows: number;
+    heldTeamRows: number;
 }
 /**
  * Why the right-edge scrollbar is or is not usable, in one record
@@ -74,6 +102,55 @@ export declare function setPerfResetHook(fn: (() => void) | null): void;
 /** Called by `cli.tsx` after building the writer. Passing `null` detaches. */
 export declare function setFrameStatsProvider(fn: (() => FrameWriterStats) | null): void;
 export declare function readFrameStats(): FrameWriterStats | null;
-/** Format a snapshot as the six-line block documented in §5.4 (plus the scrollbar line). */
+/**
+ * Native-scroll writer counters (tui-native-terminal-scroll §5.1). A third
+ * module-level slot for the reason the one above records: the writer lives outside
+ * React. `guardHitsOutsideResize > 0` on a session with no resize is the defect
+ * signal (a live region reached the terminal height); `clippedRows > 0` means Ink
+ * and the terminal disagreed about a character's width (I-S13).
+ */
+export interface ScrollbackPerf {
+    /** LIVE REGION height (the Ink frame), NOT the canvas — see `anchorCanvasRows`. */
+    regionRows: number;
+    framesSeed: number;
+    framesDiff: number;
+    framesFull: number;
+    staticRowsWritten: number;
+    elidedEntries: number;
+    guardHits: number;
+    guardHitsOutsideResize: number;
+    clippedRows: number;
+    fallbacks: number;
+    resizes: number;
+    repaints: number;
+    /** `probe` = measured by CPR; `fill` = the one-off screen fill; `none` = unmeasured. */
+    anchorSource: AnchorSource;
+    /**
+     * Canvas height of the most recent batch, which is also the next erase distance.
+     *
+     * A SEPARATE FIELD RATHER THAN A RENAMED `regionRows` (P1-4): `/perf`'s
+     * "scrollback region N rows" is the first number anyone reads when the frame
+     * looks wrong, and quietly turning it into the canvas height would make a 6-row
+     * region report 24 during a short conversation.
+     */
+    anchorCanvasRows: number;
+    /** Content rows inside that canvas — how much of the conversation is on screen. */
+    anchorHeldRows: number;
+    /** Blank rows above the content. Non-zero is expected on a short conversation. */
+    anchorGapRows: number;
+    /** Rows this session pushed into the terminal's own scrollback. */
+    anchorScrollRows: number;
+    /** Times the geometry was dropped on purpose (column change, shrink, geometry lost). */
+    anchorResets: number;
+    /** Measurements accepted after the first: the re-probe count, not the resize count. */
+    anchorReprobes: number;
+}
+/** Called by `cli.tsx` in native mode. Passing `null` detaches. */
+export declare function setScrollbackStatsProvider(fn: (() => ScrollbackPerf) | null): void;
+/**
+ * Format a snapshot as the seven-line block documented in §5.4 (plus the scrollbar
+ * line). The `band:` line is the newest one and the only place that answers "why is
+ * that panel not on screen".
+ */
 export declare function formatPerfReport(snap: PerfSnapshot): string;
 export declare const perfCommand: SlashCommand;

package/dist/commands/perf.js

@@ -68,6 +68,28 @@ export function setFrameStatsProvider(fn) {
 export function readFrameStats() {
     return frameStats ? frameStats() : null;
 }
+let scrollbackStats = null;
+/** Called by `cli.tsx` in native mode. Passing `null` detaches. */
+export function setScrollbackStatsProvider(fn) {
+    scrollbackStats = fn;
+}
+function formatScrollbackLine() {
+    const stats = scrollbackStats?.();
+    if (!stats)
+        return [];
+    return [
+        `scrollback region ${stats.regionRows} rows  -  canvas ${stats.anchorCanvasRows} rows  -  ` +
+            `content ${stats.anchorHeldRows} rows  -  gap ${stats.anchorGapRows} rows  -  ` +
+            `anchor bottom via ${stats.anchorSource}  -  scrolled ${stats.anchorScrollRows} rows  -  ` +
+            `anchor resets ${stats.anchorResets}  -  reprobes ${stats.anchorReprobes}`,
+        `           batches seed ${stats.framesSeed}, ` +
+            `diff ${stats.framesDiff}, full ${stats.framesFull}, repaint ${stats.repaints}  -  ` +
+            `static rows ${stats.staticRowsWritten}  -  elided ${stats.elidedEntries}  -  ` +
+            `guardHits ${stats.guardHits} (outside resize ${stats.guardHitsOutsideResize})  -  ` +
+            `clippedRows ${stats.clippedRows}  -  fallbacks ${stats.fallbacks}  -  ` +
+            `resizes ${stats.resizes}`,
+    ];
+}
 function mb(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
@@ -102,12 +124,34 @@ function formatScrollbarLine(bar) {
         ? `${bar.trackCol}x${bar.trackRows + 4}` : 'the terminal size';
     return `${line}\n           waiting for a full frame matching ${size}`;
 }
-/** Format a snapshot as the six-line block documented in §5.4 (plus the scrollbar line). */
+/**
+ * `band:` - who got which rows, and why a panel is not on screen.
+ *
+ * `rail=<rows>x<cols>` reads `0x0` when the rail is not drawn, which is the only
+ * unambiguous "there is no rail" - a conservative width would look like a rail that
+ * merely has no height. One line, because `/perf` is a notice entry and a wrapping
+ * readout costs the repaint it exists to explain.
+ */
+function formatBandLine(band) {
+    if (!band)
+        return 'band       n/a (full-screen layout)';
+    return `band       rail=${band.railRows}x${band.railCols} team=${band.teamRows} ` +
+        `preview=${band.previewRows} cols=${band.contentCols}/${band.previewCols} ` +
+        `reason=${band.reason} held=${band.heldRailRows}/${band.heldTeamRows}`;
+}
+/**
+ * Format a snapshot as the seven-line block documented in §5.4 (plus the scrollbar
+ * line). The `band:` line is the newest one and the only place that answers "why is
+ * that panel not on screen".
+ */
 export function formatPerfReport(snap) {
     const caches = renderCacheStats();
     const eco = snap.rung > 0 ? '  -  eco' : '';
     const governor = snap.governorEnabled ? '' : '  -  governor off';
-    const scrollbar = snap.scrollbar ? [formatScrollbarLine(snap.scrollbar)] : [];
+    const native = snap.mode === 'native';
+    const scrollbar = native
+        ? ['scrollbar  n/a (native scroll)']
+        : snap.scrollbar ? [formatScrollbarLine(snap.scrollbar)] : [];
     return [
         `render     rung ${snap.rung}  -  interval ${snap.intervalMs}ms  -  last commit ` +
             `${Math.round(snap.lastCommitMs)}ms${eco}${governor}`,
@@ -118,8 +162,12 @@ export function formatPerfReport(snap) {
         `caches     md ${caches.markdownEntries} (${mb(caches.markdownBytes)})  -  ` +
             `hl ${caches.highlightEntries} (${mb(caches.highlightBytes)})  -  ` +
             `lines ${caches.lineEntries}`,
-        `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
+        native
+            ? `mode       native  -  live region ${snap.viewportRows} rows`
+            : `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
+        formatBandLine(snap.band),
         formatWriterLine(),
+        ...formatScrollbackLine(),
         ...scrollbar,
     ].join('\n');
 }

package/dist/commands/registry.d.ts

@@ -100,6 +100,12 @@ export interface CommandContext {
      * missing, which is the same reason `update` above it is optional.
      */
     mouse?: MouseCommandPort;
+    /**
+     * True in native-scroll mode (tui-native-terminal-scroll): the terminal owns
+     * scrolling and selection, so there is no capture to toggle. Lets `/mouse` say so
+     * instead of the generic "not captured" answer.
+     */
+    nativeScroll?: boolean;
     /**
      * The foreign-write door, for `/copy`'s OSC 52 half (§4.4.5).
      *

package/dist/config/cli-commands.d.ts

@@ -21,6 +21,19 @@ export declare const LOG_CONFIG_SET_KEYS: readonly ["log.level", "log.toFile", "
  * `Set team.enabled = false`.
  */
 export declare const TEAM_CONFIG_SET_KEYS: readonly ["team.enabled", "team.maxSubagents", "team.maxConcurrent", "team.subagentTimeoutMs", "team.dispatchTimeoutMs", "team.maxTurnsPerSubagent", "team.overseer", "team.overseerIntervalMs", "team.model", "team.modelProfileId"];
+/**
+ * Config keys under `jobs.` that `aragon config set` accepts
+ * (long-task-jobs §6.5).
+ *
+ * THE FIRST NESTED SECTION WHOSE KEYS ARE ALL WRITABLE, so it is also the first
+ * one where `JOBS_CONFIG_SET_KEYS ⊆ CONFIG_SET_KEYS` needs its own assertion:
+ * `__tests__/config.test.ts`'s static guard matches LITERAL keys in `cli.tsx`, so
+ * a set that is spread in is invisible to it (RV-P2-8).
+ *
+ * Every key is ONE level deep on purpose — `runConfigGet` splits on a single dot,
+ * so `jobs.waitSeconds` resolves and `jobs.mirror.enabled` would not.
+ */
+export declare const JOBS_CONFIG_SET_KEYS: readonly ["jobs.enabled", "jobs.waitSeconds", "jobs.stallSeconds", "jobs.persistLog", "jobs.noticeSteer"];
 /**
  * Config keys under `retry.` that `aragon config set` accepts
  * (llm-api-retry-backoff §8.2).
@@ -81,6 +94,20 @@ export declare const COMPACTION_CONFIG_SET_KEYS: readonly ["compaction.enabled",
  * included.
  */
 export declare function applyLogConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate a `jobs.*` dotted key into a patch, or `null` for anything else.
+ *
+ * THE TEMPLATE IS `applyTeamConfigSet`, NOT an `applyBashConfigSet` — no such
+ * function exists, and `bash.*` is not `config set`-able to this day (RV-P2-8).
+ * Every numeric key routes through `clampJobsConfig` rather than a local
+ * coercion, so the caller echoes the STORED value and an out-of-range input is
+ * visible: `config set jobs.waitSeconds 1` prints `5`.
+ *
+ * The patch is a PARTIAL section, which is only safe because
+ * `updatePersistedConfig` deep-merges `jobs` — the sixth time that trap is
+ * recorded in `store.ts`.
+ */
+export declare function applyJobsConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
 /**
  * Translate a `team.*` dotted key into a patch, or `null` for anything else.
  *

package/dist/config/cli-commands.js

@@ -14,7 +14,7 @@ import { getConfigBackupPath, getConfigPath, getHomeRoot, getLogsDir, getPromptH
 import { getHomeMigrationBreadcrumbPath } from './migrate-home.js';
 import { loadPersistedConfig, updatePersistedConfig } from './store.js';
 import { normalizeModelProfiles, validateModelProfiles } from './model-profiles.js';
-import { clampFastConfig, clampRetryConfig, clampCompactionConfig, clampTeamConfig, parseThresholdInput, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_COMPACTION_CONFIG, DEFAULT_UPDATE_CONFIG, } from './schema.js';
+import { clampFastConfig, clampRetryConfig, clampCompactionConfig, clampTeamConfig, parseThresholdInput, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_COMPACTION_CONFIG, DEFAULT_UPDATE_CONFIG, DEFAULT_JOBS_CONFIG, clampJobsConfig, } from './schema.js';
 import { clampLogLevel } from '../logging/levels.js';
 /** Config keys under `log.` that `aragon config set` accepts. */
 export const LOG_CONFIG_SET_KEYS = [
@@ -48,6 +48,25 @@ export const TEAM_CONFIG_SET_KEYS = [
     'team.model',
     'team.modelProfileId',
 ];
+/**
+ * Config keys under `jobs.` that `aragon config set` accepts
+ * (long-task-jobs §6.5).
+ *
+ * THE FIRST NESTED SECTION WHOSE KEYS ARE ALL WRITABLE, so it is also the first
+ * one where `JOBS_CONFIG_SET_KEYS ⊆ CONFIG_SET_KEYS` needs its own assertion:
+ * `__tests__/config.test.ts`'s static guard matches LITERAL keys in `cli.tsx`, so
+ * a set that is spread in is invisible to it (RV-P2-8).
+ *
+ * Every key is ONE level deep on purpose — `runConfigGet` splits on a single dot,
+ * so `jobs.waitSeconds` resolves and `jobs.mirror.enabled` would not.
+ */
+export const JOBS_CONFIG_SET_KEYS = [
+    'jobs.enabled',
+    'jobs.waitSeconds',
+    'jobs.stallSeconds',
+    'jobs.persistLog',
+    'jobs.noticeSteer',
+];
 /**
  * Config keys under `retry.` that `aragon config set` accepts
  * (llm-api-retry-backoff §8.2).
@@ -166,6 +185,40 @@ export function applyLogConfigSet(key, value) {
             return null;
     }
 }
+/**
+ * Translate a `jobs.*` dotted key into a patch, or `null` for anything else.
+ *
+ * THE TEMPLATE IS `applyTeamConfigSet`, NOT an `applyBashConfigSet` — no such
+ * function exists, and `bash.*` is not `config set`-able to this day (RV-P2-8).
+ * Every numeric key routes through `clampJobsConfig` rather than a local
+ * coercion, so the caller echoes the STORED value and an out-of-range input is
+ * visible: `config set jobs.waitSeconds 1` prints `5`.
+ *
+ * The patch is a PARTIAL section, which is only safe because
+ * `updatePersistedConfig` deep-merges `jobs` — the sixth time that trap is
+ * recorded in `store.ts`.
+ */
+export function applyJobsConfigSet(key, value) {
+    const patch = (jobs) => ({ jobs });
+    const clampOne = (field) => {
+        const merged = clampJobsConfig({ ...DEFAULT_JOBS_CONFIG, [field]: value });
+        return { [field]: merged[field] };
+    };
+    switch (key) {
+        case 'jobs.enabled':
+            return patch({ enabled: isTrue(value) });
+        case 'jobs.waitSeconds':
+            return patch(clampOne('waitSeconds'));
+        case 'jobs.stallSeconds':
+            return patch(clampOne('stallSeconds'));
+        case 'jobs.persistLog':
+            return patch({ persistLog: isTrue(value) });
+        case 'jobs.noticeSteer':
+            return patch({ noticeSteer: isTrue(value) });
+        default:
+            return null;
+    }
+}
 /**
  * Translate a `team.*` dotted key into a patch, or `null` for anything else.
  *

package/dist/config/env.js

@@ -254,6 +254,44 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.bash = section;
     }
+    const jobsEnabled = process.env.ARAGON_JOBS_ENABLED?.trim().toLowerCase();
+    const jobsWait = process.env.ARAGON_JOBS_WAIT_SECONDS?.trim();
+    const jobsStall = process.env.ARAGON_JOBS_STALL_SECONDS?.trim();
+    const jobsPersist = process.env.ARAGON_JOBS_PERSIST_LOG?.trim().toLowerCase();
+    const jobsSteer = process.env.ARAGON_JOBS_NOTICE_STEER?.trim().toLowerCase();
+    if ((jobsEnabled !== undefined && jobsEnabled.length > 0) ||
+        (jobsWait !== undefined && jobsWait.length > 0) ||
+        (jobsStall !== undefined && jobsStall.length > 0) ||
+        (jobsPersist !== undefined && jobsPersist.length > 0) ||
+        (jobsSteer !== undefined && jobsSteer.length > 0)) {
+        const section = {};
+        // ONE TRUTHINESS LADDER FOR ALL THREE BOOLEANS, because three slightly
+        // different spellings of "is this true" is how `ARAGON_JOBS_ENABLED=off`
+        // ends up enabling the feature.
+        const flag = (value) => value === '1' || value === 'true' || value === 'on' || value === 'yes';
+        if (jobsEnabled !== undefined && jobsEnabled.length > 0)
+            section.enabled = flag(jobsEnabled);
+        if (jobsPersist !== undefined && jobsPersist.length > 0)
+            section.persistLog = flag(jobsPersist);
+        if (jobsSteer !== undefined && jobsSteer.length > 0)
+            section.noticeSteer = flag(jobsSteer);
+        if (jobsWait !== undefined && jobsWait.length > 0) {
+            const parsed = Number.parseInt(jobsWait, 10);
+            // LEFT ABSENT WHEN UNPARSEABLE, so `clampJobsConfig` supplies the default
+            // rather than an env var that silently means 0.
+            if (Number.isFinite(parsed))
+                section.waitSeconds = parsed;
+        }
+        if (jobsStall !== undefined && jobsStall.length > 0) {
+            const parsed = Number.parseInt(jobsStall, 10);
+            if (Number.isFinite(parsed))
+                section.stallSeconds = parsed;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it - the
+        // same contract `partial.skills` / `partial.log` / `partial.team` rely on.
+        if (Object.keys(section).length > 0)
+            partial.jobs = section;
+    }
     const retry = process.env.ARAGON_RETRY?.trim().toLowerCase();
     const retryMax = process.env.ARAGON_RETRY_MAX?.trim();
     if ((retry !== undefined && retry.length > 0) || (retryMax !== undefined && retryMax.length > 0)) {
@@ -392,6 +430,10 @@ export function readEnvConfig() {
         partial.diffRender =
             diffRender === '1' || diffRender === 'true' || diffRender === 'on' || diffRender === 'yes';
     }
+    // Invalid values are ignored, like every other ARAGON_* key.
+    const scrollMode = process.env.ARAGON_SCROLL_MODE?.trim().toLowerCase();
+    if (scrollMode === 'native' || scrollMode === 'app')
+        partial.scrollMode = scrollMode;
     const syncOutput = process.env.ARAGON_SYNC_OUTPUT?.trim().toLowerCase();
     if (syncOutput !== undefined && syncOutput.length > 0) {
         partial.syncOutput =

package/dist/config/load.d.ts

@@ -5,7 +5,7 @@
  * layers, `idleTimeout` is re-derived to be strictly ≥ `toolTimeout` so a
  * legitimately long single tool run can never be watchdog-killed.
  */
-import { type CliConfig } from './schema.js';
+import { type CliConfig, type ScrollMode } from './schema.js';
 import type { ModelRole } from './model-profiles.js';
 export interface CliFlags {
     provider?: string;
@@ -149,6 +149,8 @@ export interface CliFlags {
      * all — i.e. the documented escape hatch would quietly un-set itself.
      */
     diffRender?: boolean;
+    /** `--scroll-mode <native|app>`; already validated by `cli.tsx` (exit 2 on junk). */
+    scrollMode?: ScrollMode;
     /** `--sync-output` ⇒ true, `--no-sync-output` ⇒ false, absent ⇒ undefined (§5.2). */
     syncOutput?: boolean;
     /**

package/dist/config/load.js

@@ -6,7 +6,8 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
+import { JOB_WAIT_MARGIN_MS } from '../proc/limits.js';
+import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampJobsConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile, updatePersistedConfig } from './store.js';
 import { projectModelProfiles, resolveModelProfileState, resolveModelRoleKey, } from './model-profile-resolution.js';
@@ -182,6 +183,23 @@ function resolveBashConfig(env, file) {
         ...(env.bash ?? {}),
     });
 }
+/**
+ * Merge the `jobs` section across the three layers that supply it
+ * (defaults > file > env), long-task-jobs §6.5.
+ *
+ * THREE LAYERS, NOT FOUR, and that is the same decision `resolveBashConfig`
+ * records: both switches this section carries are already reachable from
+ * `config.json` (a per-machine preference) and from the environment (the channel
+ * a container entrypoint has). A fourth spelling would be a fourth place for the
+ * answer to differ.
+ */
+function resolveJobsConfig(env, file) {
+    return clampJobsConfig({
+        ...DEFAULT_CONFIG.jobs,
+        ...(file.jobs ?? {}),
+        ...(env.jobs ?? {}),
+    });
+}
 /**
  * Merge the `retry` section across all four layers (defaults › file › env ›
  * flags), llm-api-retry-backoff §6.2.
@@ -334,6 +352,16 @@ function resolveDiffRender(flags, env, file) {
         return file.diffRender;
     return DEFAULT_CONFIG.diffRender;
 }
+/** flags > env > file > default, like `resolveDiffRender` (tui-native-terminal-scroll §6.1). */
+function resolveScrollMode(flags, env, file) {
+    if (flags.scrollMode !== undefined)
+        return flags.scrollMode;
+    if (env.scrollMode !== undefined)
+        return env.scrollMode;
+    if (file.scrollMode !== undefined)
+        return clampScrollMode(file.scrollMode, DEFAULT_SCROLL_MODE);
+    return DEFAULT_SCROLL_MODE;
+}
 /** Same ladder for the DEC 2026 envelope (§5.1). */
 function resolveSyncOutput(flags, env, file) {
     if (flags.syncOutput !== undefined)
@@ -544,10 +572,32 @@ export function loadConfig(flags = {}, options = {}) {
     const planModeMaxAskRounds = clampAskRounds(file.planModeMaxAskRounds, DEFAULT_CONFIG.planModeMaxAskRounds);
     const planModeHumanTimeoutMs = clampHumanTimeout(file.planModeHumanTimeoutMs, DEFAULT_CONFIG.planModeHumanTimeoutMs);
     const toolTimeoutMs = coercePositiveInt(pick(flags.toolTimeout, file.toolTimeoutMs), DEFAULT_CONFIG.toolTimeoutMs);
+    // THE `jobs` SECTION IS RESOLVED HERE, ABOVE THE TIMEOUT BLOCK, and the
+    // position is the whole of RV-P1-2. The design's first draft put the I-4 clamp
+    // next to the `idleTimeoutMs` invariant below, but `jobs` is parsed inside the
+    // big config literal a hundred lines further down — a reference to it here would
+    // be a use-before-declaration, and "resolve it later and patch the object" is
+    // how the invariant gets silently skipped. Resolving it first makes the clamp
+    // impossible to omit.
+    const jobs = resolveJobsConfig(env.partial, file);
     let idleTimeoutMs = coercePositiveInt(pick(flags.idleTimeout, file.idleTimeoutMs), DEFAULT_CONFIG.idleTimeoutMs);
     // Timeout invariant (R1): idle must be strictly greater than the tool ceiling
     // so a long single tool run is never aborted by the idle watchdog.
     idleTimeoutMs = Math.max(idleTimeoutMs, toolTimeoutMs + IDLE_TIMEOUT_MARGIN_MS);
+    // INVARIANT I-4 (long-task-jobs): a wait must fit inside the tool call that
+    // hosts it, `jobs.waitSeconds * 1000 + JOB_WAIT_MARGIN_MS <= toolTimeoutMs`.
+    //
+    // `Math.min`, AND THE DIRECTION IS THE POINT. The invariant above RAISES the
+    // idle window to accommodate the tool; this one LOWERS the wait to accommodate
+    // the tool. Copying `Math.max` here would produce a wait that outlives its own
+    // tool call — which is exactly the `Command timed out` failure the feature
+    // exists to remove, re-created by its own config check.
+    //
+    // With an operator-set ceiling below the margin the floor of 1s applies rather
+    // than a negative wait: the invariant wins over the minimum, because a wait
+    // longer than its host is worse than a short wait.
+    const waitCeilingSeconds = Math.floor((toolTimeoutMs - JOB_WAIT_MARGIN_MS) / 1000);
+    jobs.waitSeconds = Math.max(1, Math.min(jobs.waitSeconds, waitCeilingSeconds));
     // Resolve API keys: config-file key wins over the provider env var.
     const fileKeys = file.apiKeys ?? {};
     const apiKeys = {};
@@ -638,6 +688,7 @@ export function loadConfig(flags = {}, options = {}) {
         renderGovernor: resolveRenderGovernor(flags, env.partial, file),
         maxRenderIntervalMs: clampMaxRenderInterval(pick(flags.maxRenderInterval, env.partial.maxRenderIntervalMs, file.maxRenderIntervalMs), DEFAULT_CONFIG.maxRenderIntervalMs),
         diffRender: resolveDiffRender(flags, env.partial, file),
+        scrollMode: resolveScrollMode(flags, env.partial, file),
         syncOutput: resolveSyncOutput(flags, env.partial, file),
         confirmTools,
         toolTimeoutMs,
@@ -676,6 +727,10 @@ export function loadConfig(flags = {}, options = {}) {
         update: resolveUpdateConfig(flags, env.partial, file),
         compaction: resolveCompactionConfig(flags, env.partial, file),
         bash: resolveBashConfig(env.partial, file),
+        // The already-resolved-and-converged section from the timeout block above.
+        // NOT `resolveJobsConfig(...)` a second time: that would re-apply the
+        // un-converged `waitSeconds` and silently undo I-4.
+        jobs,
         cwd,
         color,
         colorLevel,
@@ -719,6 +774,11 @@ function recordResolvedConfig(config) {
         // trace — so "why did my failing call sit there for three minutes" (or
         // "why did it not retry at all") has an answer after the fact.
         retry: config.retry.enabled ? config.retry.maxRetries : 'off',
+        // The CONVERGED value, not the configured one: after I-4 they can differ, and
+        // "my 30s wait became 10s" is answerable only if the resolved number is
+        // recorded rather than the one on disk.
+        jobWaitSeconds: config.jobs.waitSeconds,
+        jobsEnabled: config.jobs.enabled,
         hasApiKey: Boolean(config.apiKeys[config.provider]),
         configPath: getConfigPath(),
     });