@aragon-agent/cli 0.6.31 → 0.6.32

package/dist/agent/reducer.d.ts

@@ -17,7 +17,7 @@ import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '.
 import type { FastReview, FastSnapshot } from '../fast/types.js';
 import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger, ContextUsageSnapshot } from '../compaction/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
-import type { ServiceSnapshot, ServiceStatus } from '../proc/types.js';
+import type { JobKind, ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
@@ -247,6 +247,26 @@ export type Entry = {
     terminal?: boolean;
     /** The stop reported the pid still alive afterwards (R-2 / P2-6). */
     killIncomplete?: boolean;
+    /**
+     * WHICH KIND OF JOB THIS CARD DRAWS (long-task-jobs §4.9 / I-2).
+     *
+     * It changes the NOUN and the status wording only. Renaming the entry kind
+     * from `service` to `job` would be a pure regression: ordinary assertions pin
+     * `[background] service s1 started` word for word, `bg-command.test.ts` pins
+     * `/bg stop`'s `Stopped N services` toast, and there are no snapshot files in
+     * this package to absorb the churn. The few strings that DID move to "job"
+     * are the model-facing unknown-id messages in `proc-tools.ts`, which name an
+     * id space that now holds both kinds.
+     */
+    jobKind: JobKind;
+    /** Latest extracted progress line; one extra row when present. */
+    progress?: string;
+    /** When output last arrived, so `stalled` can be evaluated at render time. */
+    lastOutputAt: number;
+    /** Derived at snapshot time by the supervisor, carried here so it survives a save. */
+    stalled?: boolean;
+    /** Where the on-disk mirror wrote this job's full log. */
+    logPath?: string;
 };
 export interface UsageTotal {
     inputTokens: number;

package/dist/agent/reducer.js

@@ -1479,6 +1479,7 @@ function serviceFields(service) {
     return {
         kind: 'service',
         serviceId: service.id,
+        jobKind: service.kind,
         command: service.command,
         status: service.status,
         ...(service.url !== undefined ? { url: service.url } : {}),
@@ -1490,6 +1491,12 @@ function serviceFields(service) {
         rows: service.rows,
         rowsSeen: service.rowsSeen,
         ...(service.killIncomplete ? { killIncomplete: true } : {}),
+        // The four fields long-task-jobs adds, in the SAME projection for all three
+        // actions - which is the property this function exists to guarantee.
+        lastOutputAt: service.lastOutputAt,
+        ...(service.progress ? { progress: service.progress.text } : {}),
+        ...(service.stalled ? { stalled: true } : {}),
+        ...(service.logPath !== undefined ? { logPath: service.logPath } : {}),
     };
 }
 /** The LIVE card for a service id, newest first; terminal records are skipped. */

package/dist/agent/system-prompt.d.ts

@@ -102,6 +102,18 @@ export interface SystemPromptParams {
      * `bash_kill` would describe tools it does not have.
      */
     backgroundBlock?: string;
+    /**
+     * The rendered `<background_jobs>` block, or `''` (long-task-jobs §12 step 13).
+     *
+     * Spliced conditionally exactly as every block above is, which is what keeps
+     * I-3 true: `jobs.enabled: false` produces the pre-feature prompt BYTE FOR BYTE
+     * for a fixed tool array.
+     *
+     * A CHILD'S PROMPT NEVER CARRIES IT: subagents are built with no supervisor and
+     * no `job_*` tools, so the block's first sentence would describe a capability
+     * the child does not have.
+     */
+    jobsBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -43,6 +43,7 @@ export function buildSystemPrompt(params) {
     const todoBlock = params.todoBlock ?? '';
     const fastBlock = params.fastBlock ?? '';
     const backgroundBlock = params.backgroundBlock ?? '';
+    const jobsBlock = params.jobsBlock ?? '';
     const appended = (params.appendSystemPrompt ?? '').trim();
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
@@ -65,6 +66,7 @@ export function buildSystemPrompt(params) {
         ...(todoBlock ? ['', todoBlock] : []),
         ...(fastBlock ? ['', fastBlock] : []),
         ...(backgroundBlock ? ['', backgroundBlock] : []),
+        ...(jobsBlock ? ['', jobsBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

package/dist/cli.js

@@ -25,7 +25,7 @@ import { formatMigrationNotice, migrateLegacyState } from './config/migrate-lega
 import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
 import { migrateStateOutOfConfig } from './config/migrate-state-out-of-config.js';
 import { runHistoryCommand } from './config/history-commands.js';
-import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyCompactionConfigSet, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, JOBS_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyCompactionConfigSet, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyJobsConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
@@ -58,7 +58,9 @@ import { createFrameObserver } from './ui/frame-observer.js';
 import { enterAltScreen, enterNativeScreen, writeExitTranscript, } from './ui/screen.js';
 import { resolveTerminalPlan } from './ui/terminal-plan.js';
 import { createScrollbackDrain } from './ui/scrollback/drain.js';
+import { SCROLLBACK_LIMITS } from './ui/scrollback/limits.js';
 import { createScrollbackWriter } from './ui/scrollback/scrollback-writer.js';
+import { probeAnchorSpaceBelow, setAnchorProbeDisabled } from './ui/scrollback/cursor-probe.js';
 import { createScrollbackBridge, } from './ui/scrollback/use-scrollback-view.js';
 import { supportsWindowsVtInput } from './ui/win-vt-input.js';
 import { forceWindowsVtInput } from './ui/win-vt-force.js';
@@ -412,8 +414,16 @@ function forceVtInputForThisConsole() {
  * "…" > out.txt`, `aragon config set`, and `aragon --version`, because the
  * interactive and headless paths are disjoint branches: `runInteractive()`
  * renders Ink, `runOneShot()` goes to `runHeadless()`, which never does.
+ *
+ * `async` FOR EXACTLY ONE `await` (tui-bottom-anchored-live-region P1-3): the
+ * cursor-position probe before the first frame. Both call sites are inside async
+ * Commander actions and use `void runInteractive(...)` — the session's lifetime is
+ * owned by `waitUntilExit()` and the four idempotent restore paths, never by the
+ * caller, so nothing awaits it. The `await` sits before the FIRST `stdout.write`
+ * and between it and `render()` there is no other suspension point, so making the
+ * function async introduces no new interleaving.
  */
-function runInteractive(flags, extras = {}) {
+async function runInteractive(flags, extras = {}) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         process.stderr.write('Interactive UI requires a TTY. Use -p "<prompt>", exec, or config list / config set.\n');
         process.exitCode = 2;
@@ -546,6 +556,10 @@ function runInteractive(flags, extras = {}) {
      * asynchronous wait for it.
      */
     const finalizeNativeScreen = () => {
+        // FIRST, before any bytes: the anchor probe must go quiet here (P1-6). A settle
+        // timer that survived this point would write `ESC[6n` at a terminal already handed
+        // back to the shell and nobody would strip the reply.
+        killAnchorProbe();
         const bridge = scrollbackBridge;
         if (!bridge)
             return;
@@ -651,7 +665,14 @@ function runInteractive(flags, extras = {}) {
     // conhost), so no capability gate is possible or needed there.
     const wantEnhancedKeys = plan.enhancedKeys;
     const filter = process.stdin.isTTY
-        ? tryCreateStdinFilter(process.stdin, { mouse: wantMouse, paste: wantPaste, enhancedKeys: wantEnhancedKeys }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
+        ? tryCreateStdinFilter(process.stdin, {
+            mouse: wantMouse,
+            paste: wantPaste,
+            enhancedKeys: wantEnhancedKeys,
+            // TOLD, never derived (I-A8): a native session strips the terminal's
+            // answer to `ESC[6n`, an `app` session is byte-identical to before.
+            cursorReport: plan.differ === 'scrollback',
+        }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
         : null;
     /**
      * THE ONE EXPRESSION EVERY MOUSE SITE READS (I-11 / D-17).
@@ -665,7 +686,135 @@ function runInteractive(flags, extras = {}) {
     const pasteOn = wantPaste && filter !== null;
     /** Same discipline: the translation runs only when a filter fronts Ink. */
     const enhancedKeysOn = wantEnhancedKeys && filter !== null;
-    const disposeStdinFilter = () => filter?.dispose();
+    // --- The bottom anchor's measurement pipeline (tui-bottom-anchored-live-region).
+    //
+    // Three pieces of host state, and every one of them exists to close a specific
+    // failure mode the writer cannot close by itself:
+    //
+    //  `anchorProbeDead` — I-A9 / P1-6. After `finalizeNativeScreen()`,
+    //    `disposeFrameWriter()`, `filter.dispose()` and the process `exit` hook, a
+    //    query must never be written again: it would hit a terminal already handed
+    //    back to the shell, where nothing strips the reply and the user's prompt gains
+    //    a literal `^[[12;1R`.
+    //  `anchorReprobeQueued` — P0-3. `invalidate()` is called from inside the writer's
+    //    `transform`, i.e. inside Ink's own `stdout.write`, so the request is pushed out
+    //    with `setImmediate` and everything inside that window is coalesced into one
+    //    query instead of becoming a probe storm on every foreign write.
+    //  `anchorReprobeTimer` — the 200 ms settle window (§4.6). A drag fires dozens of
+    //    resize events; one CPR each would fight the input channel for bandwidth and
+    //    make the region jitter.
+    let anchorProbeDead = false;
+    let anchorReprobeQueued = false;
+    let anchorReprobeTimer = null;
+    /** Stop measuring for the rest of the process. Idempotent; safe from any exit path. */
+    function killAnchorProbe() {
+        anchorProbeDead = true;
+        anchorReprobeQueued = false;
+        if (anchorReprobeTimer) {
+            clearTimeout(anchorReprobeTimer);
+            anchorReprobeTimer = null;
+        }
+        // The module-level switch is what makes a probe that is already in flight, or one
+        // whose timer fires during teardown, write zero bytes.
+        setAnchorProbeDisabled(true);
+    }
+    /** Ask for one measurement soon; coalesced, deferred out of Ink's write, and dead-safe. */
+    function requestAnchorProbe() {
+        if (anchorProbeDead || anchorReprobeQueued)
+            return;
+        anchorReprobeQueued = true;
+        setImmediate(() => {
+            anchorReprobeQueued = false;
+            if (anchorProbeDead)
+                return;
+            if (anchorReprobeTimer)
+                clearTimeout(anchorReprobeTimer);
+            anchorReprobeTimer = setTimeout(() => {
+                anchorReprobeTimer = null;
+                void runAnchorProbe();
+            }, SCROLLBACK_LIMITS.anchorReprobeDelayMs);
+            anchorReprobeTimer.unref?.();
+        });
+    }
+    /**
+     * One query, then consume the answer. Never throws and never fails the session: a
+     * terminal that does not answer simply keeps whatever anchor it had.
+     */
+    async function runAnchorProbe() {
+        const bridge = scrollbackBridge;
+        if (anchorProbeDead || !bridge || !filter)
+            return;
+        filter.setExpectingCursorReport(true);
+        let spaceBelow = null;
+        try {
+            spaceBelow = await probeAnchorSpaceBelow({
+                stdin: process.stdin,
+                stdout: process.stdout,
+                rows: () => process.stdout.rows,
+            });
+        }
+        catch (error) {
+            logger.warn('cli', 'scroll_anchor_probe_failed', {
+                rows: process.stdout.rows ?? null, reason: String(error),
+            });
+        }
+        finally {
+            filter.setExpectingCursorReport(false);
+        }
+        if (anchorProbeDead || spaceBelow === null)
+            return;
+        // `setAnchorSpaceBelow` records the re-probe count; the repaint is deferred for
+        // the same reason `requestRepaint` is (this can run while Ink is writing).
+        bridge.writer.setAnchorSpaceBelow(spaceBelow, 'probe');
+        logger.info('cli', 'scroll_anchor', {
+            source: 'probe', spaceBelow, rows: process.stdout.rows ?? null,
+        });
+        setImmediate(() => {
+            if (!anchorProbeDead)
+                frameWriter?.repaint();
+        });
+    }
+    /**
+     * THE ORDER HERE IS THE MECHANISM (P0-1 / I-A10). In canonical mode a terminal's
+     * reply to `ESC[6n` is line-buffered until a newline AND echoed, so the probe would
+     * time out on every Linux/macOS session while printing `^[[12;1R` on the screen.
+     * Raising raw first is also the direction `forceVtInputForThisConsole()` already
+     * goes (it raises the mode before Ink's own `setRawMode(true)` so libuv does not
+     * rewrite the console mode); a second raise is a no-op on both platforms.
+     *
+     * `false` means "no probe", never "no session": the caller falls back to the fill.
+     */
+    function raiseRawModeForProbe() {
+        if (typeof process.stdin.setRawMode !== 'function')
+            return false;
+        try {
+            process.stdin.setRawMode(true);
+        }
+        catch (error) {
+            logger.warn('cli', 'scroll_anchor_probe_failed', {
+                rows: process.stdout.rows ?? null, reason: `raw mode: ${String(error)}`,
+            });
+            return false;
+        }
+        // Ink lowers raw mode on unmount, which is the normal restore. A kill, a closed
+        // window or a crash never unmounts, so the same restore `forceVtInputForThisConsole`
+        // registers is registered here too; it is idempotent and cheap.
+        process.on('exit', () => {
+            try {
+                process.stdin.setRawMode(false);
+            }
+            catch {
+                /* Stream already torn down - nothing left to restore. */
+            }
+        });
+        return true;
+    }
+    const disposeStdinFilter = () => {
+        // Before the filter goes away: a probe settle timer must not fire into a stream
+        // nobody is stripping any more.
+        killAnchorProbe();
+        filter?.dispose();
+    };
     // --- Drag-select (tui-selection-and-scroll-follow §4.4). ------------------
     //
     // Selection owns its controller, decoration and notice. Button motion follows
@@ -698,6 +847,10 @@ function runInteractive(flags, extras = {}) {
             // Deferred: static rows can be queued from inside a React commit, and the
             // repaint writes to the stream Ink is in the middle of writing to.
             requestRepaint: () => { setImmediate(() => frameWriter?.repaint()); },
+            // `invalidate()` calls this from inside `transform` (geometry lost), so the
+            // deferral is not optional here either (P0-3). The host coalesces it into one
+            // query per settle window and stops it for good once the screen is handed back.
+            requestAnchorProbe,
         });
         scrollbackBridge = createScrollbackBridge({
             writer, drain, requestFlush: () => { setImmediate(() => frameWriter?.repaint()); },
@@ -757,6 +910,8 @@ function runInteractive(flags, extras = {}) {
             stdout: frameWriter?.stdout ?? process.stdout, terminal: process.stdout, scrollbar,
         });
     const disposeFrameWriter = () => {
+        // Same switch as `finalizeNativeScreen`: this is one of the four teardown paths.
+        killAnchorProbe();
         frameObserver?.dispose();
         pointerRouter?.dispose();
         scrollbar.controller?.dispose();
@@ -798,6 +953,49 @@ function runInteractive(flags, extras = {}) {
             vtInputSupported,
         })
         : NOOP_KEYBOARD_ENHANCEMENT;
+    // --- Measure the bottom of the screen, THEN build the first frame (§4.4 / §8.1).
+    //
+    // ORDER, ALL OF IT LOAD-BEARING:
+    //  1. the filter exists (it is the only thing that strips the reply — D5);
+    //  2. raw mode is raised BEFORE the query (P0-1 / I-A10);
+    //  3. the probe is awaited, and any failure is `null`;
+    //  4. `enterNativeScreen` writes the one-off fill only when the probe failed;
+    //  5. the measurement is handed to the writer before the first batch.
+    //
+    // This is the only `await` in the whole startup path and it is bounded by
+    // `anchorProbeTimeoutMs` (150 ms), which only a terminal that cannot answer pays.
+    let anchorSpaceBelow = null;
+    if (native && filter && scrollbackBridge) {
+        if (raiseRawModeForProbe()) {
+            filter.setExpectingCursorReport(true);
+            try {
+                anchorSpaceBelow = await probeAnchorSpaceBelow({
+                    stdin: process.stdin,
+                    stdout: process.stdout,
+                    rows: () => process.stdout.rows,
+                    // The first frame is waiting on this: hold the event loop, or a session with
+                    // nothing else referenced yet can exit before it draws anything.
+                    holdProcess: true,
+                });
+            }
+            catch (error) {
+                // The probe never throws by contract; this is the belt to that braces, and it
+                // must not be able to fail the launch.
+                logger.warn('cli', 'scroll_anchor_probe_failed', {
+                    rows: process.stdout.rows ?? null, reason: String(error),
+                });
+                anchorSpaceBelow = null;
+            }
+            finally {
+                filter.setExpectingCursorReport(false);
+            }
+        }
+        logger.info('cli', anchorSpaceBelow === null ? 'scroll_anchor_probe_failed' : 'scroll_anchor', {
+            source: anchorSpaceBelow === null ? 'fill' : 'probe',
+            spaceBelow: anchorSpaceBelow,
+            rows: process.stdout.rows ?? null,
+        });
+    }
     {
         // `mouse` here means "a mouse-parsing filter is installed", NOT "the user
         // wants mouse support" — see `AltScreenOptions`. `screen.ts` must never
@@ -815,8 +1013,18 @@ function runInteractive(flags, extras = {}) {
                 motion: mouseOn,
                 bracketedPaste: pasteOn,
             })
-            // Native scroll: no alternate screen, no mouse (D6). Only DEC 2004.
-            : enterNativeScreen(process.stdout, { bracketedPaste: pasteOn });
+            // Native scroll: no alternate screen, no mouse (D6). DEC 2004, plus the
+            // one-off fill when the cursor could not be measured — before anything else,
+            // so the rows it scrolls away are the shell's, never this session's.
+            : enterNativeScreen(process.stdout, {
+                bracketedPaste: pasteOn,
+                anchorFillRows: anchorSpaceBelow === null && scrollbackBridge
+                    ? Math.max(0, (process.stdout.rows ?? 24) - 1)
+                    : 0,
+            });
+        // The measurement reaches the writer BEFORE the first batch, so frame one is
+        // already pinned. `fill` says "we know where the bottom is because we went there".
+        scrollbackBridge?.writer.setAnchorSpaceBelow(anchorSpaceBelow ?? 0, anchorSpaceBelow === null ? 'fill' : 'probe');
         // Input-encoding modes unwind FIRST, for the same reason the mouse
         // reporting does inside `screen.restore()`: the terminal must stop
         // sending enhanced encodings before anything else tears the reader
@@ -1327,6 +1535,11 @@ const CONFIG_SET_KEYS = new Set([
     // a script at all: `config list` enumerates the section dynamically and so
     // shows these keys whether they are here or not, while `config set` does not.
     ...COMPACTION_CONFIG_SET_KEYS,
+    // `jobs.*` keys are handled by `applyJobsConfigSet`, same reasoning again — and
+    // this spread is exactly why `JOBS_CONFIG_SET_KEYS ⊆ CONFIG_SET_KEYS` needs its
+    // own assertion: the static guard in `config.test.ts` matches LITERAL keys in
+    // this file, so a spread set is invisible to it (RV-P2-8).
+    ...JOBS_CONFIG_SET_KEYS,
 ]);
 /**
  * `aragon config set maxTokens <n|auto|default>`.
@@ -1466,6 +1679,17 @@ function runConfigSetValue(key, value) {
         process.stdout.write(`Set ${key} = ${String(merged.compaction[field])}\n`);
         return;
     }
+    const jobsPatch = applyJobsConfigSet(key, value);
+    if (jobsPatch) {
+        // Echoed from the STORED value, so `config set jobs.waitSeconds 1` prints 5
+        // and `jobs.waitSeconds 9999` prints 60 — the rule every section above
+        // states. It matters here too: `waitSeconds` is ALSO converged against the
+        // tool ceiling by I-4, so the stored value is the only honest answer.
+        const merged = updatePersistedConfig(jobsPatch);
+        const field = key.slice('jobs.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.jobs[field])}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -1935,14 +2159,14 @@ function buildProgram() {
             }
             return;
         }
-        runInteractive(flags, { initialPrompt: prompt });
+        void runInteractive(flags, { initialPrompt: prompt });
     });
     // aragon config [set <key> <value> | path]
     const configCmd = program
         .command('config')
         .description('Open the settings screen')
         .action(() => {
-        runInteractive(toFlags(program.opts()), { initialOverlay: 'settings' });
+        void runInteractive(toFlags(program.opts()), { initialOverlay: 'settings' });
     });
     configCmd
         .command('set <key> <value>')

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';
@@ -1256,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).
          *
@@ -1277,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') {
@@ -1289,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);
@@ -1335,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. */
@@ -40,6 +41,32 @@ export interface PerfSnapshot {
     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
@@ -83,6 +110,7 @@ export declare function readFrameStats(): FrameWriterStats | null;
  * 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;
@@ -95,9 +123,34 @@ export interface ScrollbackPerf {
     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 six-line block documented in §5.4 (plus the scrollbar line). */
+/**
+ * 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

@@ -78,10 +78,14 @@ function formatScrollbackLine() {
     if (!stats)
         return [];
     return [
-        `scrollback region ${stats.regionRows} rows  -  batches seed ${stats.framesSeed}, ` +
+        `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})  -  ` +
+            `static rows ${stats.staticRowsWritten}  -  elided ${stats.elidedEntries}  -  ` +
+            `guardHits ${stats.guardHits} (outside resize ${stats.guardHitsOutsideResize})  -  ` +
             `clippedRows ${stats.clippedRows}  -  fallbacks ${stats.fallbacks}  -  ` +
             `resizes ${stats.resizes}`,
     ];
@@ -120,7 +124,26 @@ 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' : '';
@@ -142,6 +165,7 @@ export function formatPerfReport(snap) {
         native
             ? `mode       native  -  live region ${snap.viewportRows} rows`
             : `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
+        formatBandLine(snap.band),
         formatWriterLine(),
         ...formatScrollbackLine(),
         ...scrollbar,