@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/cli.js

@@ -27,7 +27,7 @@ import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS,
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampContextWindow, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, isAutoToken, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -44,7 +44,7 @@ import { decideRenderMode } from './ui/layout/frame.js';
 import { createFrameDiffer } from './ui/frame-differ.js';
 import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
 import { setFrameStatsProvider } from './commands/perf.js';
-import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
+import { tryCreateStdinFilter } from './input/stdin-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { supportsWindowsVtInput } from './ui/win-vt-input.js';
 import { forceWindowsVtInput } from './ui/win-vt-force.js';
@@ -113,6 +113,11 @@ function toFlags(opts) {
         // on `CliFlags`, AND a line here; `config.test.ts` is the regression pin that
         // exists because `--no-mouse` shipped inert once already.
         mouseSelect: opts.mouseSelect,
+        // Site three of three for `--paste` / `--no-paste` -- TEN features, one
+        // trap. A flag needs the `.option()` declaration below, a field on
+        // `CliFlags`, AND a line here; `config.test.ts` is the regression pin that
+        // exists because `--no-mouse` shipped inert once already.
+        paste: opts.paste,
         skills: opts.skills,
         skill: opts.skill,
         skillsYes: opts.skillsYes,
@@ -148,6 +153,11 @@ function toFlags(opts) {
         fastModel: opts.fastModel,
         fastProvider: opts.fastProvider,
         fastReview: opts.fastReview,
+        // …and again for `--fast-delegate` / `--no-fast-delegate`, one feature
+        // later — NINE features, one trap. It is `fast.delegate`'s only channel:
+        // there is no `ARAGON_FAST_DELEGATE`, so missing this line leaves a wrapper
+        // with no way at all to say "do not delegate on this run".
+        fastDelegate: opts.fastDelegate,
         // `--verbose` is just a shorthand for `--log-level debug`; an explicit
         // `--log-level` still wins, so the two can be combined without surprise.
         logLevel: opts.logLevel ?? (opts.verbose ? 'debug' : undefined),
@@ -416,7 +426,7 @@ function runInteractive(flags, extras = {}) {
     // before it reaches this process, so `\x1b[?1000h` is a pure no-op and the
     // filter has nothing to filter. Gating `wantMouse` — rather than the three
     // things downstream of it — is what keeps the three in agreement: the
-    // `?1000h` write (`enterAltScreen(..., { mouse: filter !== null })`), the
+    // `?1000h` write (`enterAltScreen(..., { mouse: mouseOn })`), the
     // filter itself, and the `mouseSource` prop that decides whether the user is
     // advised about a mode that is not running. Wiring any of them separately
     // re-opens the gap where the app claims a capability it does not have.
@@ -434,10 +444,36 @@ function runInteractive(flags, extras = {}) {
         !!process.stdout.isTTY &&
         !!process.stdin.isTTY &&
         vtInputSupported;
-    const mouseFilter = wantMouse
-        ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
+    // --- Paste handling (tui-paste-handling section 5.1.1 / D-13 / D-17). ----
+    //
+    // THE GATE IS WIDER THAN THE MOUSE'S, AND `paste` DEFAULTS TO TRUE. Paste
+    // needs no `vtInputSupported` and no full-screen: Tier 2 is a heuristic on
+    // chunk shape and needs no terminal cooperation at all, which is exactly why
+    // it exists for the consoles that never deliver `\x1b[200~` (R-11).
+    //
+    // WHAT THIS WIDENING BREAKS IF IT IS NOT PAIRED WITH `mouseOn` BELOW (P0-1).
+    // `filter !== null` used to be the answer to FIVE questions, only one of which
+    // is really about the stream. With paste able to build a filter on its own,
+    // `aragon --no-mouse` would get a non-null handle and every one of those five
+    // would flip true: `?1000h`/`?1006h`/`?1002h` written, terminal selection taken
+    // away (the ONLY reason anyone passes `--no-mouse`), and a startup notice
+    // advising the user about a mode they just disabled.
+    const wantPaste = config.paste && !!process.stdin.isTTY;
+    const pasteBridge = { notify: null };
+    const filter = wantMouse || wantPaste
+        ? tryCreateStdinFilter(process.stdin, { mouse: wantMouse, paste: wantPaste }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
         : null;
-    const disposeMouse = () => mouseFilter?.dispose();
+    /**
+     * THE ONE EXPRESSION EVERY MOUSE SITE READS (I-11 / D-17).
+     *
+     * `filter !== null` now answers exactly one question -- "is a stream wrapped?"
+     * -- and the only site allowed to keep reading it is the `stdin` handed to
+     * `render()`.
+     */
+    const mouseOn = wantMouse && filter !== null;
+    /** Same discipline for DEC 2004: already decided here, never re-derived. */
+    const pasteOn = wantPaste && filter !== null;
+    const disposeStdinFilter = () => filter?.dispose();
     // --- Drag-select (tui-selection-and-scroll-follow §4.4). ------------------
     //
     // ONE EXPRESSION, READ BY FOUR THINGS, and that is the same discipline
@@ -446,7 +482,7 @@ function runInteractive(flags, extras = {}) {
     // disagree about whether drag-select is running. With it false the session is
     // byte-identical to a pre-feature build — no extra escape on the wire (AC-8),
     // no controller, no `decorate`, no mirror.
-    const wantSelect = mouseFilter !== null && config.mouseSelect;
+    const wantSelect = mouseOn && config.mouseSelect;
     const selectionBridge = {
         controller: null,
         onCopied: null,
@@ -526,11 +562,21 @@ function runInteractive(flags, extras = {}) {
         }));
     };
     if (mode === 'fullscreen') {
-        // `mouse` here means "a filter is installed", NOT "the user wants mouse
-        // support" — see `AltScreenOptions`. `screen.ts` must never derive it for
-        // itself, or a later refactor re-opens the gap I-8 closes. `motion` carries
-        // the same discipline for `?1002h`: already decided, never re-derived.
-        screen = enterAltScreen(process.stdout, { mouse: mouseFilter !== null, motion: wantSelect });
+        // `mouse` here means "a mouse-parsing filter is installed", NOT "the user
+        // wants mouse support" — see `AltScreenOptions`. `screen.ts` must never
+        // derive it for itself, or a later refactor re-opens the gap I-8 closes.
+        // `motion` carries the same discipline for `?1002h`, and `bracketedPaste`
+        // for `?2004h`: all three are already decided, none is re-derived.
+        //
+        // IT IS `mouseOn`, NOT `filter !== null` (P0-1). A `--no-mouse` session with
+        // paste at its default `true` still builds a filter, and passing the handle
+        // here would write `?1000h` at a user who disabled the mouse precisely to
+        // keep their terminal's own selection.
+        screen = enterAltScreen(process.stdout, {
+            mouse: mouseOn,
+            motion: wantSelect,
+            bracketedPaste: pasteOn && mode === 'fullscreen',
+        });
         const restore = () => screen?.restore();
         // Four idempotent restore paths (§4.4). The signal hook is NOT redundant:
         //   - `waitUntilExit().then()` is a microtask and may never be reached when
@@ -613,10 +659,10 @@ function runInteractive(flags, extras = {}) {
     // than inside `screen.ts`'s closure because `App` needs to READ it and the
     // handle's own flag is private (it has to be — `restore()` reads it, and
     // exposing a setter would be a second way to get the two out of step).
-    let mouseCaptured = mouseFilter !== null;
-    if (wantSelect && mouseFilter) {
+    let mouseCaptured = mouseOn;
+    if (wantSelect && filter) {
         selectionBridge.controller = createSelectionController({
-            source: mouseFilter.source,
+            source: filter.source,
             // The frame writer is absent under `--no-diff-render`, where there is no
             // cache to repaint from at all; the controller then falls back to asking
             // `App` for a React redraw on every drag flush, which is slower and
@@ -656,7 +702,7 @@ function runInteractive(flags, extras = {}) {
     const terminalBridge = mode === 'fullscreen' || writeForeign
         ? {
             mouseSelect: wantSelect,
-            ...(mouseFilter
+            ...(mouseOn
                 ? {
                     setMouseCapture: (on) => {
                         screen?.setMouseCapture(on);
@@ -682,13 +728,21 @@ function runInteractive(flags, extras = {}) {
         !!process.stdin.isTTY &&
         !process.env.CI &&
         config.update.mode !== 'off';
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source, 
+    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, 
+        // `mouseOn`, NOT the handle (I-11). `App.tsx:186-188` documents this
+        // prop's contract as "absent under `--no-mouse`, inline, or non-TTY", and
+        // it feeds `enabled: !!mouseSource` on a wheel subscription that would
+        // otherwise be a channel no event can ever arrive on.
+        mouseSource: mouseOn && filter ? filter.source : undefined, 
         // Present ONLY when this console swallows `CSI Z` and mouse reports.
         // Passed in rather than probed inside `App` so that every test renders
         // the same tree on every machine — reading `process.versions.node` from
         // a component would make the notice appear or vanish according to which
         // Node the developer happened to have installed.
-        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, terminal: terminalBridge }), 
+        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, 
+        // Absent when nothing can refuse a paste, so a `--no-paste` tree is
+        // byte-identical to a build without this feature.
+        pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
     {
@@ -696,7 +750,7 @@ function runInteractive(flags, extras = {}) {
         patchConsole: mode === 'inline',
         // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
         // every existing path is provably unchanged.
-        stdin: mouseFilter?.stdin ?? process.stdin,
+        stdin: filter?.stdin ?? process.stdin,
         // SPREAD, not `frameWriter?.stdout ?? process.stdout`. This call passed no
         // `stdout` at all before, and Ink defaults it to `process.stdout`; omitting
         // the key entirely when the writer is off keeps the options object the same
@@ -757,12 +811,12 @@ function runInteractive(flags, extras = {}) {
         .waitUntilExit()
         .then(() => {
         screen?.restore();
-        // BEFORE `disposeMouse()`, which clears the listener set it subscribed to,
+        // BEFORE `disposeStdinFilter()`, which clears the listener set it subscribed to,
         // and after `restore()` for the reason that call records: the terminal must
         // stop reporting first, and anything already in flight is still consumed by
         // a live filter.
         disposeSelection();
-        disposeMouse();
+        disposeStdinFilter();
         // BOTH BRANCHES, the same discipline `controller.dispose()` and
         // `updateService?.dispose()` already follow. It drops the `'resize'`
         // listener of I-8 and detaches the `/perf` provider so a later `/perf` in a
@@ -786,12 +840,12 @@ function runInteractive(flags, extras = {}) {
     })
         .catch(() => {
         screen?.restore();
-        // BEFORE `disposeMouse()`, which clears the listener set it subscribed to,
+        // BEFORE `disposeStdinFilter()`, which clears the listener set it subscribed to,
         // and after `restore()` for the reason that call records: the terminal must
         // stop reporting first, and anything already in flight is still consumed by
         // a live filter.
         disposeSelection();
-        disposeMouse();
+        disposeStdinFilter();
         disposeFrameWriter();
         controller.dispose();
         updateService?.dispose();
@@ -875,6 +929,11 @@ const CONFIG_SET_KEYS = new Set([
     'baseUrl',
     'thinkingLevel',
     'maxTokens',
+    // context-usage-gauge-accuracy §3.6. Listed here AND given its own branch in
+    // `runConfigSet` below - a key present here but absent there falls through
+    // every case, writes nothing, and still prints `Set contextWindow = 1000000`
+    // (P1-2).
+    'contextWindow',
     'theme',
     'confirmTools',
     'toolTimeoutMs',
@@ -911,6 +970,10 @@ const CONFIG_SET_KEYS = new Set([
     // records: a key listed here but absent there writes nothing and still prints
     // `Set mouseSelect = false`.
     'mouseSelect',
+    // Listed here AND cased in the switch below, for the reason the note above
+    // `mouse` records: a key present here but absent there falls through every
+    // case, writes nothing, and still prints `Set paste = false`.
+    'paste',
     'scrollResumeMs',
     'historyEnabled',
     'planModeDefault',
@@ -967,6 +1030,30 @@ function runConfigSetMaxTokens(value) {
     const merged = updatePersistedConfig({ maxTokens: stored });
     process.stdout.write(`Set maxTokens = ${merged.maxTokens ?? 'auto'}\n`);
 }
+/**
+ * `aragon config set contextWindow <n|auto>`.
+ *
+ * ITS OWN BRANCH, AHEAD OF THE SWITCH, for the reason `maxTokens` has one: it
+ * must echo the STORED value rather than the typed one, so
+ * `config set contextWindow 99999999` reports the clamped 5000000 instead of a
+ * number that was never written. It also REJECTS nonsense rather than clamping
+ * it - a non-numeric argument here is almost always a typo for a number, and
+ * storing AUTO for `20O000` would quietly discard the user's intent.
+ */
+function runConfigSetContextWindow(value) {
+    const trimmed = value.trim();
+    const auto = isAutoToken(trimmed);
+    if (!auto && !/^\d+$/.test(trimmed)) {
+        process.stderr.write(`Invalid contextWindow "${value}". Use a number of tokens or "auto".\n`);
+        process.exitCode = 2;
+        return;
+    }
+    // `null` GOES IN UNCLAMPED (RV-12). Running AUTO through the clamp yields
+    // 8000 and removes "auto" from the config permanently.
+    const stored = auto ? null : clampContextWindow(trimmed, null);
+    const merged = updatePersistedConfig({ contextWindow: stored });
+    process.stdout.write(`Set contextWindow = ${merged.contextWindow ?? 'auto'}\n`);
+}
 function runConfigSet(key, value) {
     if (!CONFIG_SET_KEYS.has(key)) {
         process.stderr.write(`Unknown config key "${key}". Known keys: ${[...CONFIG_SET_KEYS].join(', ')}.\n`);
@@ -987,6 +1074,11 @@ function runConfigSet(key, value) {
         runConfigSetMaxTokens(value);
         return;
     }
+    // The second tri-state key, and it needs its own branch for the same reason.
+    if (key === 'contextWindow') {
+        runConfigSetContextWindow(value);
+        return;
+    }
     const teamPatch = applyTeamConfigSet(key, value);
     if (teamPatch) {
         // The written value is echoed from the CLAMPED result rather than from the
@@ -1109,6 +1201,9 @@ function runConfigSet(key, value) {
         case 'mouseSelect':
             patch.mouseSelect = value === 'true' || value === '1';
             break;
+        case 'paste':
+            patch.paste = value === 'true' || value === '1';
+            break;
         // Clamped rather than rejected, for the same reason `planModeDefault` below
         // records: hardening only the READ path leaves a bad value on disk that
         // reverts to the default on every launch, which presents as "my setting
@@ -1381,6 +1476,12 @@ function buildProgram() {
         // `false` on every run that passes no flag at all.
         .option('--mouse-select', 'Drag with the mouse to select text; releasing copies it')
         .option('--no-mouse-select', 'Keep wheel scrolling, but leave drag-select off')
+        // Positive form FIRST, same tri-state reason as `--mouse-select` above:
+        // `paste` is persisted and defaults to `true`, so a lone `--no-paste` would
+        // make commander default `opts.paste` to `true` -- indistinguishable from
+        // silence, and silently overriding a stored `false` on every run.
+        .option('--paste', 'Collapse large pastes into a placeholder (the default)')
+        .option('--no-paste', 'Treat pasted bytes as keystrokes (pre-0.6.3 behavior)')
         // Declaring `--fullscreen` BEFORE `--no-fullscreen` keeps the default
         // `undefined` instead of `true`, which is what makes the tri-state work:
         // "no opinion" must stay distinguishable from "force it".
@@ -1429,6 +1530,14 @@ function buildProgram() {
         .option('--fast-model <id>', 'The fast model id (implies nothing about --fast)')
         .option('--fast-provider <id>', 'Provider for the fast model (default: the main provider)')
         .option('--fast-review <n|off>', 'Turns between automatic fast reviews, or "off"')
+        // BOTH FORMS, POSITIVE FIRST, and here it matters more than anywhere above:
+        // `fast.delegate` is PERSISTED and defaults to TRUE, so declaring only
+        // `--no-fast-delegate` would make commander default `opts.fastDelegate` to
+        // `true` and force `delegate: true` on EVERY run that passed no flag at all
+        // — silently overwriting a user's stored `false`. Same polarity, same trap
+        // and same fix as `--update` / `--compaction`.
+        .option('--fast-delegate', 'Let the fast tier take mechanical sub-steps (the default)')
+        .option('--no-fast-delegate', 'Run every sub-step on the main model')
         // BOTH FORMS, positive first, for the reason recorded seven times above —
         // and this is the pair whose omission would be worst. `update.mode` is
         // PERSISTED and defaults to `'auto'`, so a lone `--no-update` would make

package/dist/commands/builtins.js

@@ -7,7 +7,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 { computeCost, formatCost, formatTokens } from '../agent/usage.js';
+import { computeCost, formatCost, formatDuration, formatTokens } from '../agent/usage.js';
 import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
 import { buildContinuationMessage } from '../todo/follow-through.js';
 import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
@@ -17,6 +17,7 @@ import { getLogger } from '../logging/logger.js';
 import { copyText } from '../ui/clipboard.js';
 import { perfCommand } from './perf.js';
 import { runCompactCommand } from '../compaction/command.js';
+import { runContextCommand } from '../compaction/context-command.js';
 /**
  * `/fast status` — THE GUARANTEED REPORTING SURFACE for the tier (§4.4 / R-8).
  *
@@ -809,6 +810,14 @@ const COMMANDS = [
         description: 'Context compaction: status | on | off | threshold <n> | keep <n> | <instructions>',
         run: (ctx) => runCompactCommand(ctx),
     },
+    {
+        // REGISTRATION ONLY, for the reason `/compact` records one entry up: this
+        // file is past the 1000-line guideline and the report has five sections.
+        // The body is in `compaction/context-command.ts`.
+        name: 'context',
+        description: 'Show context occupancy, the window it is measured against, and session spend',
+        run: (ctx) => runContextCommand(ctx),
+    },
     {
         name: 'expand',
         // DELIBERATELY LEFT TOOL-ONLY, and the asymmetry with Ctrl+O is a decision
@@ -1048,6 +1057,95 @@ const COMMANDS = [
     // render layer, and threading `ui/render-cache.js` into this file would make
     // every other command's import graph pull the renderer in with it.
     perfCommand,
+    {
+        name: 'bg',
+        description: 'Background services: list | logs <id> [n] | stop <id|all> | status',
+        /**
+         * THE USER'S HANDLE ON WHAT THE AGENT LEFT RUNNING (§5.3).
+         *
+         * It is the LIVE view, and that is why it exists at all: the transcript
+         * records EVENTS about a service (D-11) — a card printed into `<Static>`
+         * cannot be rewritten — so "what is running right now" lives here, in the
+         * status chip, and in `bash_output`. Without this command a user whose
+         * server card scrolled away an hour ago has no way to name it.
+         */
+        run: async (ctx) => {
+            const arg = ctx.args.trim();
+            const [verb = 'list', value, count] = arg.split(/\s+/);
+            const controller = ctx.controller;
+            if (!controller.isBackgroundRegistered()) {
+                ctx.notify('info', 'Background services are off for this session (bash.background).');
+                return;
+            }
+            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.`);
+                return;
+            }
+            if (verb === 'logs') {
+                if (!value) {
+                    ctx.notify('warn', 'Usage: /bg logs <id> [n]');
+                    return;
+                }
+                const service = controller.getServiceSnapshot(value);
+                if (!service) {
+                    ctx.notify('warn', `No service "${value}".`);
+                    return;
+                }
+                const page = controller.readServiceLog(value);
+                const n = count ? Number.parseInt(count, 10) : DEFAULT_BG_LOG_ROWS;
+                const rows = page?.rows ?? [];
+                const take = Number.isFinite(n) && n > 0 ? n : DEFAULT_BG_LOG_ROWS;
+                const shown = rows.slice(-take);
+                ctx.notify('info', shown.length === 0
+                    ? `service ${service.id}: no output yet.`
+                    : `service ${service.id} (last ${shown.length} rows)\n${shown.join('\n')}`);
+                return;
+            }
+            if (verb === 'stop') {
+                if (!value) {
+                    ctx.notify('warn', 'Usage: /bg stop <id|all>');
+                    return;
+                }
+                // AWAITED, unlike `doExit`'s force path: a slash command runs on a live
+                // event loop, so the graceful SIGTERM -> SIGKILL ladder can run and a
+                // dev server gets its chance to release its port cleanly.
+                const stopped = await controller.stopService(value);
+                if (stopped.length === 0) {
+                    ctx.notify('info', 'Nothing to stop.');
+                    return;
+                }
+                const leaked = stopped.filter((svc) => svc.killIncomplete);
+                ctx.toast('success', `Stopped ${stopped.length} service${stopped.length === 1 ? '' : 's'}.`);
+                if (leaked.length > 0) {
+                    // AN HONEST WARNING BEATS A SILENT LEAK (R-2 / P2-6). `taskkill /t`
+                    // cannot reach a grandchild that re-parented itself, and saying so is
+                    // the difference between a puzzle and a `netstat` the user knows to run.
+                    ctx.notify('warn', `${leaked.map((svc) => svc.id).join(', ')} may have left a detached child - ` +
+                        'check with netstat/lsof if a port is still held.');
+                }
+                return;
+            }
+            if (verb !== 'list' && verb !== '') {
+                ctx.notify('warn', `Unknown argument "${verb}" - use /bg [list|logs|stop|status].`);
+                return;
+            }
+            if (services.length === 0) {
+                ctx.notify('info', 'No background services this session.');
+                return;
+            }
+            const now = Date.now();
+            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}`;
+            });
+            ctx.notify('info', `Background services:\n${lines.join('\n')}`);
+        },
+    },
     {
         name: 'exit',
         aliases: ['quit'],
@@ -1055,6 +1153,8 @@ const COMMANDS = [
         run: (ctx) => ctx.exit(),
     },
 ];
+/** Rows `/bg logs <id>` shows when the user names no count. */
+const DEFAULT_BG_LOG_ROWS = 40;
 export function registerBuiltinCommands(registry) {
     for (const command of COMMANDS)
         registry.register(command);

package/dist/compaction/child.js

@@ -85,6 +85,11 @@ export function createChildContextManager(req, deps) {
             }
             if (event.type !== 'compaction_end')
                 return;
+            // DEFENCE IN DEPTH SINCE quiet-noop D-8: a child compaction that declines
+            // before committing to work no longer emits this event at all, so this
+            // filter is now unreachable on that path. It is retained deliberately -
+            // it is this tree's own record that a no-op compaction is a non-event, and
+            // deleting it would make the child depend on that rule holding forever.
             if (!event.record.applied && event.record.mode === 'none')
                 return;
             req.onCompacted();

package/dist/compaction/command.js

@@ -66,9 +66,22 @@ export function formatCompactionStatus(ctx) {
     lines.push(`  Summarizer: ${snapshot.model || '(none)'}` +
         (config.useFastTier ? ' (fast tier preferred)' : ' (fast tier not used)'));
     lines.push(`  On summarize failure: ${config.onFailure}`);
+    // THE PARENTHETICAL IS BUILT FROM WHATEVER APPLIES, AND OMITTED WHEN NOTHING
+    // DOES (quiet-noop D-9). `declined` counts checkpoints that fired and chose to
+    // do nothing - the only human-readable trace of a decline once the transcript
+    // stopped carrying a card for one. It renders ONLY when non-zero: a counter
+    // that says `(0 checkpoints declined)` in every healthy session would have
+    // replaced one piece of noise with another.
+    const sessionNotes = [];
+    if (snapshot.generation > 0)
+        sessionNotes.push(`generation ${snapshot.generation}`);
+    const declined = snapshot.declined ?? 0;
+    if (declined > 0) {
+        sessionNotes.push(`${declined} ${declined === 1 ? 'checkpoint' : 'checkpoints'} declined`);
+    }
     lines.push(`  This session: ${snapshot.compactions} ` +
         `${snapshot.compactions === 1 ? 'compaction' : 'compactions'}` +
-        (snapshot.generation > 0 ? ` (generation ${snapshot.generation})` : '') +
+        (sessionNotes.length > 0 ? ` (${sessionNotes.join(', ')})` : '') +
         `, ${formatTokens(snapshot.tokensReclaimed)} tokens reclaimed`);
     const cost = snapshot.pricingUnknown
         ? `unknown (no price table for ${snapshot.model || 'the summarizer'})`