@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/agent/headless.js

@@ -167,6 +167,52 @@ export async function runHeadless(controller, prompt, options = {}) {
         total.inputTokens += event.usage.inputTokens;
         total.outputTokens += event.usage.outputTokens;
     });
+    // Context compaction (context-auto-compaction §4.7).
+    //
+    // TWO STDERR LINES, AND UNLIKE THE FAST TIER THEY ARE WRITTEN (D-12's
+    // reasoning does not carry over). A review is an unrequested second opinion
+    // that changes nothing; a compaction PERMANENTLY DROPS MESSAGES from the
+    // conversation, and a `-p` run whose middle third vanished with no line
+    // anywhere saying so is not a compact run, it is an unexplained one — the same
+    // argument the retry lines above make for a three-minute pause.
+    //
+    // stderr, never stdout: stdout is the machine-readable answer and has to stay
+    // parseable by `aragon -p | jq`. Not `--quiet`-gated, for the reason the retry
+    // line is not.
+    //
+    // The summary text is NOT written (D-18): it can be tens of thousands of
+    // characters, and no consumer of `-p` asked for it.
+    const unsubscribeCompaction = controller.subscribeCompaction?.((event) => {
+        if (event.type === 'usage') {
+            total.inputTokens += event.usage.inputTokens;
+            total.outputTokens += event.usage.outputTokens;
+            return;
+        }
+        if (event.type !== 'compaction_end')
+            return;
+        const r = event.record;
+        if (!r.applied) {
+            err.write(`\n[compaction] skipped: ${r.reason ?? 'unknown'}\n`);
+            return;
+        }
+        const secs = (r.durationMs / 1000).toFixed(1);
+        const how = r.mode === 'truncated'
+            ? ' WITHOUT a summary (summarize failed)'
+            : r.mode === 'relieved'
+                ? ' by clipping the retained turns (nothing could be dropped)'
+                : '';
+        err.write(`\n[compaction] ${formatTokens(r.tokensBefore)} -> ${formatTokens(r.tokensAfter)} tokens, ` +
+            `${r.messagesBefore} -> ${r.messagesAfter} messages${how} (${secs}s)\n`);
+        // ONE MORE LINE, AND ONLY WHEN RELIEF FIRED (§4.5). A clip inside the turns
+        // the run is about to continue from is a real data loss, and a `-p` run whose
+        // recent tool output was silently shortened is an unexplained run - the same
+        // argument the compaction lines above make for a vanished middle third.
+        if (r.tailRelief) {
+            err.write(`[compaction] clipped ${r.tailRelief.messages} tool ` +
+                `${r.tailRelief.messages === 1 ? 'result' : 'results'} in the retained turns ` +
+                `(${formatTokens(r.tailRelief.charsRemoved)} chars)\n`);
+        }
+    });
     // --- The bounded continuation loop (todo-plan-followthrough §3.6). --------
     //
     // THE THREE `unsubscribe` CALLS STAY OUTSIDE IT (rule 4). The loop wraps the
@@ -227,6 +273,7 @@ export async function runHeadless(controller, prompt, options = {}) {
         unsubscribeTeam?.();
         unsubscribeTodos?.();
         unsubscribeFast?.();
+        unsubscribeCompaction?.();
     }
     // Ensure a trailing newline so piped output is well-formed.
     if (wroteText)

package/dist/agent/reducer.d.ts

@@ -14,7 +14,9 @@ import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agen
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
 import type { FastReview, FastSnapshot } from '../fast/types.js';
+import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger } from '../compaction/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
+import type { 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';
@@ -222,6 +224,107 @@ export type Entry = {
     turn: number;
     durationMs?: number;
     live: boolean;
+}
+/**
+ * One context compaction (context-auto-compaction §5.5). ONE CARD PER
+ * COMPACTION, rewritten once when the call returns — like the fast card, and
+ * unlike the todo card's per-turn checklist.
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` and `/resume` need no format
+ * change.
+ *
+ * `live: true` is normalized away ON LOAD, in `session/persist.ts`, next to
+ * `team.active`, `todo.live`, the retry card's phase and `fast.live`, and for
+ * the identical reason (C-8): `Transcript`'s settled boundary is MONOTONIC, so
+ * an entry that never settles never reaches `<Static>` and is re-rendered on
+ * every frame for the rest of the session.
+ *
+ * EVERY STRING ON THIS CARD DESCRIBES THE HISTORY, NEVER THE SCREEN (P2-9).
+ * `/clear` empties the transcript view but not `messages`, so a compaction can
+ * legitimately fire against a visually empty transcript and report
+ * "112 -> 9 messages" with nine visible rows.
+ */
+ | {
+    id: string;
+    kind: 'compaction';
+    /** 1-based within the session, so the card can name itself. */
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    applied: boolean;
+    reason?: string;
+    messagesBefore: number;
+    messagesAfter: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    summary?: string;
+    model: string;
+    durationMs?: number;
+    /**
+     * When the live card opened, so the elapsed counter has an origin
+     * (context-auto-compaction-hardening §3.6 / W5).
+     *
+     * JSON-SERIALIZABLE like every other field here, and harmless on reload:
+     * `session/persist.ts` normalizes `live` to false, and a settled card
+     * renders `durationMs` rather than an elapsed figure.
+     */
+    startedAt?: number;
+    /** Set when tail relief clipped the retained turns (W2). */
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    live: boolean;
+}
+/**
+ * One supervised background service (background-service-supervision §3.10).
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
+ *
+ * IT IS THE ONE LIVE CARD THAT DOES **NOT** BLOCK THE SETTLED BOUNDARY ONCE IT
+ * IS UP (D-11 / P0-4). Every other live clause in
+ * `Transcript.tsx::computeSettledCount` is bounded by an OPERATION — a
+ * dispatch, a turn, one LLM call, one countdown — and each carries a comment
+ * saying that an entry which never settles is re-rendered on every frame for
+ * the rest of the session. A service is bounded by the USER'S INTENT: a dev
+ * server left up for an hour is the normal case. So only `starting` blocks
+ * (bounded by `readyTimeoutMs`), a `ready`/`running` card commits its body to
+ * `<Static>`, and a later terminal transition appends a NEW one-row entry
+ * rather than trying to rewrite a card `<Static>` has already printed.
+ *
+ * `terminal: true` marks that second entry. `session/persist.ts` rewrites any
+ * restored non-terminal card to `stopped`, next to `team.active`, `todo.live`,
+ * the retry phase, `fast.live` and `compaction.live`, and for the identical
+ * reason.
+ */
+ | {
+    id: string;
+    kind: 'service';
+    /** `s1`, `s2`, ... — the id the model quotes back. */
+    serviceId: string;
+    command: string;
+    status: ServiceStatus;
+    url?: string;
+    port?: number;
+    exitCode: number | null;
+    startedAt: number;
+    readyAt?: number;
+    endedAt?: number;
+    rows: readonly string[];
+    /**
+     * MONOTONIC row cursor — the revision term, NEVER `rows.length` (P0-3).
+     *
+     * The tail is a FIXED-SIZE RING: it evicts its oldest row while appending
+     * a new one, so the joined length is unchanged while the content is not.
+     * That is verbatim the non-append mutation the `tool` branch's `liveSeq`
+     * comment was written for, and a length term would go on matching while
+     * the card changed underneath it.
+     */
+    rowsSeen: number;
+    /** The one-row entry a terminal transition appends (D-11). */
+    terminal?: boolean;
+    /** The stop reported the pid still alive afterwards (R-2 / P2-6). */
+    killIncomplete?: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
@@ -296,6 +399,25 @@ export interface ViewState {
      * what leaves an ordinary session's status bar byte-identical (AC-4).
      */
     fast: FastSnapshot | null;
+    /**
+     * The live compaction projection, or `null` when the feature is off for this
+     * session (context-auto-compaction §5.5).
+     *
+     * NEVER PERSISTED — `entries` is the history and the settled cards are the
+     * record. It drives the status chip, the gauge's marks and `/compact status`'s
+     * totals. `null` is what leaves an ordinary session's status bar unchanged.
+     */
+    compaction: CompactionSnapshot | null;
+    /**
+     * Whether `contextTokens` is currently a DERIVED figure rather than a measured
+     * one (§6.2 / P1-11).
+     *
+     * Set by `compactionEnd`, cleared by the next `turnEnd`. The status bar widens
+     * its leading `~` to cover it: today `~` means "the window is a guess", and
+     * this makes it also mean "the occupancy is a guess". Honesty about a guess is
+     * cheaper than a support thread about a wrong percentage.
+     */
+    contextTokensEstimated: boolean;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
@@ -305,6 +427,8 @@ export interface ViewState {
     retryEntryId?: string;
     /** The `kind: 'fast'` entry the in-flight review is writing into. */
     fastEntryId?: string;
+    /** The `kind: 'compaction'` entry the in-flight compaction is writing into. */
+    compactionEntryId?: string;
     streamingId?: string;
     turnProduced: boolean;
     errorNoticed: boolean;
@@ -497,6 +621,60 @@ export type ViewAction = {
 } | {
     type: 'fastTier';
     snapshot: FastSnapshot;
+} | {
+    type: 'compactionStart';
+    index: number;
+    trigger: CompactionUiTrigger;
+    model: string;
+} | {
+    type: 'compactionEnd';
+    record: CompactionRecord;
+}
+/**
+ * Compaction spend.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as `teamUsage`'s and
+ * `fastUsage`'s are: the reducer stays pure and cost-table-free. It matters
+ * MORE here than for either of those, because the summarizer may be a
+ * different model from the lead AND from the fast tier, so a reducer that
+ * computed its own would have to know about three price tables.
+ */
+ | {
+    type: 'compactionUsage';
+    usage: TokenUsage;
+    costDelta: number;
+} | {
+    type: 'compactionSnapshot';
+    snapshot: CompactionSnapshot;
+}
+/**
+ * Overwrite the gauge with a DERIVED occupancy (§6.2).
+ *
+ * Separate from `compactionEnd` because the value is not always available at
+ * the same instant, and because the flag it sets — `contextTokensEstimated` —
+ * has to be clearable by the next `turnEnd` independently.
+ */
+ | {
+    type: 'contextTokensEstimated';
+    tokens: number;
+} | {
+    type: 'serviceStart';
+    service: ServiceSnapshot;
+} | {
+    type: 'serviceUpdate';
+    service: ServiceSnapshot;
+}
+/**
+ * A service reached a terminal state.
+ *
+ * IT APPENDS A NEW ONE-ROW ENTRY rather than rewriting the card (D-11). The
+ * card may already have been printed into `<Static>`, and `<Static>` cannot
+ * un-print — so any design that rewrites a printed card is wrong whatever it
+ * claims. A second event at a second time is also simply more honest.
+ */
+ | {
+    type: 'serviceEnd';
+    service: ServiceSnapshot;
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;
@@ -532,6 +710,17 @@ export interface PatchSource {
  * it — every existing test, and headless mode — produces byte-identical actions.
  */
 export declare function reduceEvent(event: AgentEvent, cost?: ModelCost, patches?: PatchSource): ViewAction[];
+/**
+ * The opening words of the `context_overflow` banner.
+ *
+ * A SHARED CONSTANT RATHER THAN TWO LITERALS, because `compactionStart` matches
+ * on it to rewrite the notice a successful reactive recovery would otherwise
+ * leave behind (P1-4). Two spellings that must agree, with nothing checking that
+ * they do, is how that rewrite silently stops matching — at which point the red
+ * "start over" banner comes back and only on the recovery path, which is the one
+ * place nobody re-tests.
+ */
+export declare const CONTEXT_OVERFLOW_NOTICE_PREFIX = "Context length exceeded";
 /** Turn a provider error into a friendly banner, mapping LLMError.errorType. */
 export declare function formatStreamError(error: Error): string;
 export declare function viewReducer(state: ViewState, action: ViewAction): ViewState;

package/dist/agent/reducer.js

@@ -11,6 +11,7 @@
  *     synthesizes a generic error notice (a swallowed throw is never a no-op).
  */
 import process from 'node:process';
+import { occupiedTokens } from '../compaction/pressure.js';
 import { computeCost } from './usage.js';
 import { ENTRY_LIMITS, appendBounded, entryRetain, trimEntries } from './entry-limits.js';
 /** Default auto-dismiss window for a toast. */
@@ -46,11 +47,14 @@ export function initialViewState(seed = {}) {
         todos: null,
         retry: null,
         fast: null,
+        compaction: null,
+        contextTokensEstimated: false,
         seq: 0,
         teamEntryId: undefined,
         todoEntryId: undefined,
         retryEntryId: undefined,
         fastEntryId: undefined,
+        compactionEntryId: undefined,
         streamingId: undefined,
         turnProduced: false,
         errorNoticed: false,
@@ -223,6 +227,17 @@ function reduceStreamEvent(se) {
             return [];
     }
 }
+/**
+ * The opening words of the `context_overflow` banner.
+ *
+ * A SHARED CONSTANT RATHER THAN TWO LITERALS, because `compactionStart` matches
+ * on it to rewrite the notice a successful reactive recovery would otherwise
+ * leave behind (P1-4). Two spellings that must agree, with nothing checking that
+ * they do, is how that rewrite silently stops matching — at which point the red
+ * "start over" banner comes back and only on the recovery path, which is the one
+ * place nobody re-tests.
+ */
+export const CONTEXT_OVERFLOW_NOTICE_PREFIX = 'Context length exceeded';
 /** Turn a provider error into a friendly banner, mapping LLMError.errorType. */
 export function formatStreamError(error) {
     const errorType = error.errorType;
@@ -235,7 +250,13 @@ export function formatStreamError(error) {
         case 'overloaded':
             return `Provider overloaded - please retry shortly. (${base})`;
         case 'context_overflow':
-            return `Context length exceeded - start a new conversation with /reset. (${base})`;
+            // `/compact` IS NAMED FIRST, and adding it is the second half of P1-4's
+            // fix. This remedy list predates context compaction and was, until it
+            // existed, complete: throwing the conversation away really was the only
+            // exit. It is not any more, and a banner that offers only `/reset` now
+            // tells the user to discard a session the very next line of code may be
+            // about to save.
+            return `${CONTEXT_OVERFLOW_NOTICE_PREFIX} - try /compact, or start over with /reset. (${base})`;
         case 'network_error':
             return `Network error reaching the provider. (${base})`;
         case 'timeout':
@@ -295,6 +316,11 @@ function appendEntry(state, entries, entry) {
             // `fastEntryId` IS PART OF THIS LIST for the reason the note above gives:
             // a fifth live card left out of it is a card I-L1-1 does not cover.
             state.fastEntryId,
+            // And `compactionEntryId` is the sixth. Same reason, and it is the one
+            // whose absence would be hardest to notice: a compaction card is rare, so
+            // a `mapEntry` that silently stopped matching would be found by a user
+            // rather than by a test.
+            state.compactionEntryId,
         ].filter((id) => typeof id === 'string');
         for (const id of live) {
             if (!trimmed.entries.some((e) => e.id === id)) {
@@ -584,7 +610,17 @@ export function viewReducer(state, action) {
                 ...state,
                 streamingId: undefined,
                 turnProduced: true,
-                contextTokens: action.usage.inputTokens + action.usage.outputTokens,
+                // ONE FUNCTION, SHARED WITH THE COMPACTION TRIGGER (§3.4.1 / R-11 /
+                // AC-3). The old expression — `inputTokens + outputTokens` — silently
+                // UNDER-reports for anyone behind a caching gateway, because Anthropic
+                // reports `input_tokens` EXCLUDING cached tokens and puts them in two
+                // separate fields. That was a live defect in the number this gauge shows;
+                // it becomes a much worse one the moment a trigger fires on a different
+                // number from the one the user is watching.
+                contextTokens: occupiedTokens(action.usage),
+                // A MEASUREMENT SUPERSEDES A DERIVATION (§6.2). `compactionEnd` writes an
+                // estimate so the bar falls immediately; this is where it stops being one.
+                contextTokensEstimated: false,
                 usageTotal: {
                     inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
                     outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
@@ -713,6 +749,12 @@ export function viewReducer(state, action) {
                 // holds, it is a projection of an entry that has just been erased.
                 retryEntryId: undefined,
                 retry: null,
+                // Same reasoning again for the compaction card: the entry is gone, so the
+                // id must go with it or `compactionEnd` would `mapEntry` an id that no
+                // longer exists. `compaction` STAYS — unlike `retry` it is not a
+                // projection of an entry, it is the live state of a subsystem that is
+                // still running, and `/clear` clears the screen rather than the session.
+                compactionEntryId: undefined,
             };
         case 'resetConversation':
             return {
@@ -731,6 +773,11 @@ export function viewReducer(state, action) {
                 todoEntryId: undefined,
                 retryEntryId: undefined,
                 retry: null,
+                compactionEntryId: undefined,
+                // `contextTokens` is zeroed above, so the flag that says it is a
+                // DERIVATION has to go with it — otherwise a fresh conversation renders
+                // `~0%` and the tilde is a lie about a number that is simply zero.
+                contextTokensEstimated: false,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
@@ -957,6 +1004,164 @@ export function viewReducer(state, action) {
             };
         case 'fastTier':
             return { ...state, fast: action.snapshot };
+        // --- Context compaction (context-auto-compaction §5.5) ----------------
+        // NOT A TOTAL FUNCTION OVER COMPACTION ATTEMPTS (quiet-noop §3.1). A
+        // `pressure` compaction that declines before calling a model or changing the
+        // history dispatches NOTHING - no `compactionStart`, no `compactionEnd`, no
+        // entry - exactly as a checkpoint below the threshold dispatches nothing.
+        // Counting cards here counts compactions that RAN, never checkpoints that
+        // fired; `/compact status` and the diagnostic log are where the attempts are.
+        case 'compactionStart': {
+            const { id, seq } = nextId(state);
+            let entries = state.entries;
+            // RESPONSIBILITY 1 — SEAL ANY LIVE `streamingId` ENTRY, defensively.
+            // C-8's failure mode, and reachable here: `provider.ts` records that
+            // Anthropic can deliver an error IN-STREAM, after the connection is open
+            // and therefore after text deltas have already been emitted. An entry that
+            // never settles pins `Transcript`'s monotonic boundary and re-renders the
+            // tail forever.
+            if (state.streamingId) {
+                entries = mapEntry(entries, state.streamingId, (e) => e.kind === 'assistant' ? { ...e, streaming: false, ...sealThinkingMs(e) } : e);
+            }
+            // RESPONSIBILITY 2 — REWRITE A TRAILING `context_overflow` ERROR NOTICE
+            // (P1-4). `agent-loop.ts` emits `message_update` for EVERY stream event
+            // before the `error` branch throws, and `reduceStreamEvent`'s `case 'error'`
+            // turns that into a `level: 'error'` notice reading "Context length
+            // exceeded". So the HAPPY PATH of the reactive recovery would otherwise end
+            // with a red banner telling the user to throw away the session we are one
+            // frame from saving.
+            //
+            // IT REWRITES RATHER THAN REMOVES, because `<Static>` cannot un-print an
+            // entry it has already drawn — and it matches ONLY when that notice is the
+            // TAIL entry, so it can never touch an older, genuine error. If the
+            // recovery then fails, the ladder's own notice or the re-thrown 400 is what
+            // the user is left with, so neither direction lies.
+            if (action.trigger === 'overflow') {
+                const tail = entries[entries.length - 1];
+                if (tail &&
+                    tail.kind === 'notice' &&
+                    tail.level === 'error' &&
+                    tail.text.startsWith(CONTEXT_OVERFLOW_NOTICE_PREFIX)) {
+                    entries = mapEntry(entries, tail.id, (e) => e.kind === 'notice'
+                        ? { ...e, level: 'info', text: 'Context window exceeded - compacting and retrying.' }
+                        : e);
+                }
+            }
+            const entry = {
+                id,
+                kind: 'compaction',
+                index: action.index,
+                trigger: action.trigger,
+                mode: 'none',
+                applied: false,
+                messagesBefore: 0,
+                messagesAfter: 0,
+                tokensBefore: 0,
+                tokensAfter: 0,
+                model: action.model,
+                startedAt: Date.now(),
+                live: true,
+            };
+            return {
+                ...state,
+                seq,
+                ...appendEntry(state, entries, entry),
+                compactionEntryId: id,
+                streamingId: undefined,
+            };
+        }
+        case 'compactionEnd': {
+            const { record } = action;
+            const settle = (e) => e.kind === 'compaction'
+                ? {
+                    ...e,
+                    index: record.index,
+                    trigger: record.trigger,
+                    mode: record.mode,
+                    applied: record.applied,
+                    ...(record.reason !== undefined ? { reason: record.reason } : {}),
+                    messagesBefore: record.messagesBefore,
+                    messagesAfter: record.messagesAfter,
+                    tokensBefore: record.tokensBefore,
+                    tokensAfter: record.tokensAfter,
+                    ...(record.summary !== undefined ? { summary: record.summary } : {}),
+                    ...(record.tailRelief ? { tailRelief: record.tailRelief } : {}),
+                    model: record.model,
+                    durationMs: record.durationMs,
+                    // SETTLED. `Transcript`'s boundary is monotonic, so a card that
+                    // never settles is re-rendered on every frame for the rest of the
+                    // session (C-8).
+                    live: false,
+                }
+                : e;
+            // THE SECOND BRANCH IS NOT DEFENSIVE PADDING, exactly as `fastEnd`'s is
+            // not: the IDLE `/compact` path settles a record for a card this session
+            // may never have opened, and "it did nothing" must never be the observable
+            // outcome (R-8 / §6.4).
+            if (state.compactionEntryId) {
+                return {
+                    ...state,
+                    entries: mapEntry(state.entries, state.compactionEntryId, settle),
+                    compactionEntryId: undefined,
+                };
+            }
+            const { id, seq } = nextId(state);
+            const entry = {
+                id,
+                kind: 'compaction',
+                index: record.index,
+                trigger: record.trigger,
+                mode: record.mode,
+                applied: record.applied,
+                ...(record.reason !== undefined ? { reason: record.reason } : {}),
+                messagesBefore: record.messagesBefore,
+                messagesAfter: record.messagesAfter,
+                tokensBefore: record.tokensBefore,
+                tokensAfter: record.tokensAfter,
+                ...(record.summary !== undefined ? { summary: record.summary } : {}),
+                ...(record.tailRelief ? { tailRelief: record.tailRelief } : {}),
+                model: record.model,
+                durationMs: record.durationMs,
+                live: false,
+            };
+            return { ...state, seq, ...appendEntry(state, state.entries, entry) };
+        }
+        case 'compactionUsage':
+            // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` and `fastUsage`. In
+            // particular NOT `contextTokens`: that gauge shows the LEAD's context
+            // occupancy against the lead model's window, and a summarization is a
+            // separate conversation with a possibly different model entirely.
+            return {
+                ...state,
+                usageTotal: {
+                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
+                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
+                    costUsd: state.usageTotal.costUsd + action.costDelta,
+                },
+            };
+        case 'compactionSnapshot':
+            return { ...state, compaction: action.snapshot };
+        /**
+         * THE GAUGE MUST FALL IMMEDIATELY (§6.2 / AC-5).
+         *
+         * `contextTokens` is otherwise only written at `turnEnd`, so a compaction
+         * that took the session from 92 % to 24 % would leave the bar at 92 % until
+         * the next turn completes — and the user would reasonably conclude that
+         * nothing happened. This is a small change and it is the difference between
+         * the feature feeling real and feeling broken.
+         *
+         * The value arrives ALREADY CALIBRATED from `App` (§6.2 / P1-11): it replaces
+         * a MEASUREMENT that included the tool schemas, and core's raw estimator
+         * never counts them, so writing the raw figure would make the bar fall too
+         * far and then visibly climb again on the next `turn_end` for no reason the
+         * user can see.
+         */
+        case 'contextTokensEstimated':
+            return {
+                ...state,
+                contextTokens: Math.max(0, Math.round(action.tokens)),
+                contextTokensEstimated: true,
+            };
         // --- API retry (llm-api-retry-backoff §6.4) ---------------------------
         case 'retryScheduled': {
             const snapshot = {
@@ -1118,10 +1323,104 @@ export function viewReducer(state, action) {
                 fastEntryId: undefined,
             };
         }
+        // --- Background services (§3.10 / D-11) -----------------------------
+        case 'serviceStart': {
+            const { id, seq } = nextId(state);
+            const entry = { id, ...serviceFields(action.service) };
+            const appended = appendEntry(state, state.entries, entry);
+            return {
+                ...state,
+                seq,
+                entries: appended.entries,
+                droppedEntries: appended.droppedEntries,
+            };
+        }
+        /**
+         * Rewrite the LIVE card in place.
+         *
+         * SAFE ONLY BECAUSE OF D-11'S OTHER HALF: a `ready` / `running` card has
+         * reached `<Static>` and cannot be re-printed, so `serviceEnd` appends a new
+         * entry instead of routing through here. What this handles is the window in
+         * which the card is still in the live region — `starting`, and the one
+         * transition out of it — plus the output tail while it is there.
+         *
+         * The lookup is by `serviceId` and SKIPS terminal entries, so a stray update
+         * cannot rewrite the one-row record `serviceEnd` appended.
+         */
+        case 'serviceUpdate': {
+            const target = findServiceEntryId(state, action.service.id);
+            if (!target)
+                return state;
+            return {
+                ...state,
+                entries: mapEntry(state.entries, target, (e) => e.kind === 'service' ? { ...e, ...serviceFields(action.service) } : e),
+            };
+        }
+        /**
+         * A service reached a terminal state.
+         *
+         * TWO WRITES, AND BOTH ARE REQUIRED. The live card is settled in place so
+         * `computeSettledCount` can move past it and `estimateEntryRows` stops
+         * charging for a tail nothing will add to; the NEW one-row entry is what the
+         * user actually reads, because the card may already be printed into
+         * `<Static>` and `<Static>` cannot un-print (D-11 / R-13).
+         */
+        case 'serviceEnd': {
+            const target = findServiceEntryId(state, action.service.id);
+            const settled = target
+                ? mapEntry(state.entries, target, (e) => e.kind === 'service' ? { ...e, ...serviceFields(action.service) } : e)
+                : state.entries;
+            const { id, seq } = nextId(state);
+            const appended = appendEntry(state, settled, {
+                id,
+                ...serviceFields(action.service),
+                terminal: true,
+            });
+            return {
+                ...state,
+                seq,
+                entries: appended.entries,
+                droppedEntries: appended.droppedEntries,
+            };
+        }
         default:
             return state;
     }
 }
+/**
+ * Project a supervisor snapshot onto the entry's own fields.
+ *
+ * ONE PROJECTION FOR ALL THREE ACTIONS, so a field that reaches the card through
+ * `serviceStart` can never fail to reach it through `serviceUpdate` — the kind of
+ * asymmetry that produces a card frozen at its first values with nothing
+ * reporting it.
+ */
+function serviceFields(service) {
+    return {
+        kind: 'service',
+        serviceId: service.id,
+        command: service.command,
+        status: service.status,
+        ...(service.url !== undefined ? { url: service.url } : {}),
+        ...(service.port !== undefined ? { port: service.port } : {}),
+        exitCode: service.exitCode,
+        startedAt: service.startedAt,
+        ...(service.readyAt !== undefined ? { readyAt: service.readyAt } : {}),
+        ...(service.endedAt !== undefined ? { endedAt: service.endedAt } : {}),
+        rows: service.rows,
+        rowsSeen: service.rowsSeen,
+        ...(service.killIncomplete ? { killIncomplete: true } : {}),
+    };
+}
+/** The LIVE card for a service id, newest first; terminal records are skipped. */
+function findServiceEntryId(state, serviceId) {
+    for (let i = state.entries.length - 1; i >= 0; i -= 1) {
+        const e = state.entries[i];
+        if (e && e.kind === 'service' && e.serviceId === serviceId && !e.terminal)
+            return e.id;
+    }
+    return undefined;
+}
 function safeStringify(value) {
     try {
         return JSON.stringify(value);