@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/input/mouse-events.js

@@ -15,8 +15,10 @@
  * module exists so `stdin-mouse-filter.ts` can remove every byte of every
  * report before Ink ever sees the chunk (invariant I-1).
  *
- * Non-wheel reports (press / release / drag) are recognized and DISCARDED
- * rather than passed through, for the same reason.
+ * Every mouse report is CONSUMED here whatever it turns out to be; what changed
+ * with tui-selection-and-scroll-follow is that press / drag / release are now
+ * EMITTED as well as consumed, so `SelectionController` can build a selection
+ * out of them (§4.4.2). They were previously recognized and thrown away.
  */
 /**
  * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
@@ -38,34 +40,80 @@ const SGR_PREFIX = /^\x1b\[<[\d;]*$/;
 export function isMousePrefix(s) {
     return /^\x1B(\[(<[\d;]*|M[\s\S]{0,2})?)?$/.test(s);
 }
+function modifiers(b) {
+    return { shift: (b & 4) !== 0, alt: (b & 8) !== 0, ctrl: (b & 16) !== 0 };
+}
 /**
- * Decode an SGR button byte into a wheel event, or `null` when the report is
- * not a wheel notch we act on.
+ * Decode one report, or `null` when it is a report we consume without acting on.
  *
  * THE ORDER OF THESE TESTS IS THE SPECIFICATION, not a presentation choice.
  * Button 66 (wheel-left) has `b & 1 === 0` and would decode as `'up'`, so the
- * horizontal test has to precede the direction decode.
+ * horizontal test has to precede the direction decode; and `b & 32` (motion) has
+ * to precede the `final` test, because a drag is reported with `M` exactly as a
+ * press is.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * I-11 — BUTTON EVENTS COME FROM THE SGR PATH ONLY. X10 stays wheel-only, which
+ * is exactly the contract it has today.
+ *
+ * `matchX10` reconstructs a legacy report and hard-codes `final = 'M'`, because
+ * X10 HAS NO SEPARATE RELEASE FORM AT ALL — it encodes a release as button 3 of
+ * a press. Fed through the table below, an X10 release would become a `press`
+ * that is never followed by a `release`, whose `button` is 3 while the type says
+ * `0 | 1 | 2`, and whose consequence is a `hold` that is set and never cleared:
+ * content anchoring never lets go, the resume timer's third condition never
+ * passes, and the transcript is frozen for the rest of the session with nothing
+ * raised anywhere.
+ *
+ * This costs nothing real (D-16): we never REQUEST X10 — `?1006h` is over a
+ * decade old and every terminal that implements `?1000` implements it — and a
+ * terminal that ignored the SGR request also has no usable drag coordinates past
+ * column 223 (R-2). X10 exists in this parser only so a stray report cannot
+ * reach the user's draft.
+ * ═══════════════════════════════════════════════════════════════════════════
  */
-function decodeWheel(b, x, y, final) {
-    // 1. Not a wheel report at all (press / release / drag) — consume, emit nothing.
-    if ((b & 64) === 0)
-        return null;
-    // 2. Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
-    if ((b & 3) >= 2)
-        return null;
-    // 3. Wheel buttons are press-only; a terminal that ever sent a release for one
-    //    must not produce a second step for the same physical notch.
-    if (final !== 'M')
+function decodeReport(b, x, y, final, encoding) {
+    // 1. Wheel. Buttons 64-67 in both encodings.
+    if ((b & 64) !== 0) {
+        // Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
+        if ((b & 3) >= 2)
+            return null;
+        // Wheel buttons are press-only; a terminal that ever sent a release for one
+        // must not produce a second step for the same physical notch.
+        if (final !== 'M')
+            return null;
+        return { kind: 'wheel', dir: (b & 1) === 1 ? 'down' : 'up', x, y, ...modifiers(b) };
+    }
+    if (encoding !== 'sgr')
+        return null; // I-11
+    // 2. Motion while a button is held (`?1002h`). `3` is "no button", which
+    //    `?1002` should never send and `?1003` sends constantly — dropping it is
+    //    what keeps an any-event terminal from painting a selection with no button
+    //    down at all.
+    if ((b & 32) !== 0) {
+        const button = b & 3;
+        if (button === 3)
+            return null;
+        return { kind: 'drag', button: button, x, y, ...modifiers(b) };
+    }
+    // 3. Release. In SGR the final byte carries the transition, so this is
+    //    unambiguous — unlike X10, which is why step 1's guard exists.
+    //
+    //    A release whose button field reads `3` is a terminal saying "some button
+    //    came up" without naming it. It is mapped to button 0 rather than dropped:
+    //    the ONE thing a release must always do is let go of `hold`, and dropping
+    //    it would leave the viewport frozen — the exact failure I-11 is about. A
+    //    spurious button-0 release is harmless, because a selection can only exist
+    //    if button 0 was pressed in the first place.
+    if (final === 'm') {
+        const button = b & 3;
+        return { kind: 'release', button: (button === 3 ? 0 : button), x, y, ...modifiers(b) };
+    }
+    // 4. Press.
+    const button = b & 3;
+    if (button === 3)
         return null;
-    return {
-        kind: 'wheel',
-        dir: (b & 1) === 1 ? 'down' : 'up',
-        x,
-        y,
-        shift: (b & 4) !== 0,
-        alt: (b & 8) !== 0,
-        ctrl: (b & 16) !== 0,
-    };
+    return { kind: 'press', button: button, x, y, ...modifiers(b) };
 }
 /**
  * X10 legacy reports (`\x1b[M` + three chars, each `code - 32`).
@@ -84,7 +132,13 @@ function matchX10(s) {
     if (codes.some((c) => c < 32 || c > 255))
         return { kind: 'complete', length: 6, event: null };
     const [b, x, y] = codes;
-    return { kind: 'complete', length: 6, event: decodeWheel(b - 32, x - 32, y - 32, 'M') };
+    return {
+        kind: 'complete',
+        length: 6,
+        // `'x10'` is what makes I-11 a property of the code rather than of somebody's
+        // memory: this encoding yields wheel events or nothing, ever.
+        event: decodeReport(b - 32, x - 32, y - 32, 'M', 'x10'),
+    };
 }
 /** Classify the escape sequence starting at `s[0] === ESC`. */
 function matchReport(s) {
@@ -100,7 +154,7 @@ function matchReport(s) {
             const b = Number(m[1]);
             const x = Number(m[2]);
             const y = Number(m[3]);
-            return { kind: 'complete', length: m[0].length, event: decodeWheel(b, x, y, m[4]) };
+            return { kind: 'complete', length: m[0].length, event: decodeReport(b, x, y, m[4], 'sgr') };
         }
         return SGR_PREFIX.test(s) ? { kind: 'partial' } : { kind: 'none' };
     }
@@ -109,12 +163,17 @@ function matchReport(s) {
     return { kind: 'none' };
 }
 /**
- * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * Split a decoded stdin chunk into mouse events, passthrough text, and a
  * trailing prefix to carry into the next chunk.
  *
  * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
  * split writes mid-sequence, and a report torn across two chunks would
  * otherwise leak its tail into the composer (R-6).
+ *
+ * ONE CHANNEL, NOT TWO (§4.4.2). Widening this list to carry buttons alongside
+ * wheel notches is what keeps ARRIVAL ORDER intact between them; a second
+ * channel would let a press overtake the notch that preceded it, and the
+ * selection would then be anchored against rows that had already scrolled.
  */
 export function splitMouseEvents(buffer) {
     const events = [];

package/dist/input/stdin-mouse-filter.d.ts

@@ -18,10 +18,15 @@
  * than the bug this feature fixes. `cli.tsx::runInteractive` is the only caller
  * and passes `filter !== null` to `enterAltScreen`.
  */
-import { type WheelEvent } from './mouse-events.js';
+import { type MouseEvent } from './mouse-events.js';
 export interface MouseSource {
-    /** Returns an unsubscribe function. Multiple subscribers are allowed. */
-    subscribe(listener: (event: WheelEvent) => void): () => void;
+    /**
+     * Returns an unsubscribe function. Multiple subscribers are allowed — the
+     * wheel router and (since tui-selection-and-scroll-follow) the selection
+     * controller both take this one channel, and each ignores the kinds it does
+     * not own.
+     */
+    subscribe(listener: (event: MouseEvent) => void): () => void;
 }
 export interface MouseFilter {
     /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */

package/dist/logging/install.d.ts

@@ -129,7 +129,17 @@ export interface AgentEventSource {
         thinkingLevel: string;
     };
 }
-/** The nine members of the core `AgentEvent` union, as this module reads them. */
+/**
+ * The ELEVEN members of the core `AgentEvent` union, as this module reads them.
+ *
+ * THIS UNION MUST STAY A SUPERSET OF CORE'S, and the failure when it does not is
+ * a COMPILE error rather than a silent one (implementation finding IF-3): the
+ * `AgentEventSource` interface above takes a listener of THIS type, so a core
+ * union member missing here makes `AgentController` structurally incompatible
+ * with `attachAgentEvents` and every call site fails to type-check. That is the
+ * right failure mode, but it means adding an event to core is also a change
+ * here — the two `compaction_*` members below arrived that way.
+ */
 export type AgentLogEvent = {
     type: 'agent_start';
 } | {
@@ -183,6 +193,46 @@ export type AgentLogEvent = {
     duration?: number;
     error?: string;
     output?: string;
+}
+/**
+ * Context compaction (context-auto-compaction §5.1).
+ *
+ * RECORDED UNDER THE `agent` SCOPE HERE, not `compaction`. This module logs the
+ * LEAD'S LIFECYCLE, and "the run paused to compact" is part of that story — a
+ * support reader following a run's `agent` records must not find an unexplained
+ * gap where a 40-second summarization was. The `compaction` scope carries the
+ * subsystem's own detail (`compaction/compactor.ts`), which is a different
+ * question.
+ *
+ * NO `summary` FIELD IS READ, ever: it can be tens of thousands of characters,
+ * and this file's `message_update` case already records why a log larger than
+ * the conversation is not a log.
+ */
+ | {
+    type: 'compaction_start';
+    trigger?: string;
+    messageCount?: number;
+} | {
+    type: 'compaction_end';
+    applied?: boolean;
+    mode?: string;
+    reason?: string;
+    messagesBefore?: number;
+    messagesAfter?: number;
+    droppedMessages?: number;
+    /**
+     * The tail-relief report (context-auto-compaction-hardening W2).
+     *
+     * THIS UNION MUST STAY A SUPERSET OF CORE'S (IF-3). A field added to
+     * `CompactionEndEvent` and not mirrored here does not fail the build — the
+     * structural type simply ignores it — so the only trace of a degradation
+     * the user is entitled to know about would be missing from the log.
+     */
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    durationMs?: number;
 };
 /**
  * Subscribe to the agent's events and record them.

package/dist/logging/install.js

@@ -273,6 +273,34 @@ export function attachAgentEvents(logger, controller) {
                     ms: turnStartedAt > 0 ? Date.now() - turnStartedAt : 0,
                 });
                 break;
+            // Context compaction (context-auto-compaction §5.1). At `info`, like
+            // `turn_end`, so a run's `agent` records have no unexplained 40-second gap
+            // where a summarization was.
+            case 'compaction_start':
+                logger.info('agent', 'compaction_start', {
+                    trigger: event.trigger,
+                    messages: event.messageCount,
+                });
+                break;
+            case 'compaction_end':
+                // `applied: false` is a WARN, not an info: it means the run is still at
+                // the occupancy that triggered this and is about to send anyway.
+                logger[event.applied ? 'info' : 'warn']('agent', 'compaction_end', {
+                    applied: event.applied,
+                    mode: event.mode,
+                    reason: event.reason,
+                    before: event.messagesBefore,
+                    after: event.messagesAfter,
+                    dropped: event.droppedMessages,
+                    ...(event.tailRelief
+                        ? {
+                            clipped: event.tailRelief.messages,
+                            clippedChars: event.tailRelief.charsRemoved,
+                        }
+                        : {}),
+                    ms: event.durationMs,
+                });
+                break;
             case 'message_update': {
                 // API retry (llm-api-retry-backoff §6.8), ABOVE the `trace` line so a
                 // three-minute pause is in the log at the DEFAULT level. Redaction is

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

package/dist/session/cli-commands.js

@@ -16,7 +16,17 @@
  * should make on its own.
  */
 import process from 'node:process';
-import { listSessions, pruneSessions, readSessionFile, removeSession, sessionPathFor, sessionsDir, } from './store.js';
+import { isValidSessionId, listSessions, pruneSessions, readSessionFile, removeSession, sessionPathFor, sessionsDir, } from './store.js';
+/**
+ * One wording for one rule, shared by `show` and `rm`.
+ *
+ * It is deliberately the same sentence `--session-id` produces: a caller who
+ * meets the rule once should recognise it everywhere, and two spellings of the
+ * same refusal read as two different rules.
+ */
+const INVALID_ID_MESSAGE = (id) => `Invalid session id "${id}". Use 1-64 characters matching ` +
+    '[A-Za-z0-9][A-Za-z0-9._-]* (no "/", "\\", ".." or a leading dot). ' +
+    'Pass a path to `aragon exec --resume` if you mean a file elsewhere.';
 const SUBCOMMANDS = ['list', 'show', 'rm', 'prune', 'path'];
 export function registerSessionsCommand(program) {
     program
@@ -74,6 +84,10 @@ function runShow(argument, opts) {
         process.stderr.write('Usage: aragon sessions show <id> [--json]\n');
         return 2;
     }
+    if (!isValidSessionId(argument)) {
+        process.stderr.write(`${INVALID_ID_MESSAGE(argument)}\n`);
+        return 2;
+    }
     const path = sessionPathFor(argument);
     const session = readSessionFile(path);
     if (!session) {
@@ -112,6 +126,14 @@ function runRemove(argument, opts) {
         process.stderr.write('Refusing to delete without --yes.\n');
         return 2;
     }
+    // BEFORE `--yes` IS HONOURED AS PERMISSION TO DELETE. `sessions rm` is
+    // documented to accept any file IN THE SESSIONS DIRECTORY, because the user
+    // named it - not any file anywhere, which is what an unvalidated id joined to
+    // that directory would reach (R-7).
+    if (!isValidSessionId(argument)) {
+        process.stderr.write(`${INVALID_ID_MESSAGE(argument)}\n`);
+        return 2;
+    }
     if (!removeSession(argument)) {
         process.stderr.write(`session_not_found: no session "${argument}".\n`);
         return 2;

package/dist/session/persist.js

@@ -139,6 +139,25 @@ export function normalizeLoadedEntries(entries) {
                 detail: 'interrupted (session resumed)',
             };
         }
+        // THE FIFTH CLAUSE (context-auto-compaction §5.5 / C-8 / AC-19). A compaction
+        // card saved while its summarization was open resumes claiming to be running
+        // while nothing is, and — the part that actually costs — it never settles, so
+        // `Transcript`'s MONOTONIC boundary never advances past it and every frame for
+        // the rest of the session re-renders the whole tail.
+        //
+        // `applied: false` is also simply TRUE: whatever the call was going to
+        // return died with the process, and the history on disk is the PRE-compaction
+        // one. A card that claimed otherwise would tell the user their session had
+        // been compacted when it had not.
+        if (entry.kind === 'compaction' && entry.live) {
+            return {
+                ...entry,
+                live: false,
+                applied: false,
+                mode: 'none',
+                reason: 'interrupted (session resumed)',
+            };
+        }
         return entry;
     });
 }

package/dist/session/store.d.ts

@@ -54,6 +54,24 @@ export interface SessionListEntry {
 }
 export declare function sessionsDir(): string;
 export declare function sessionPathFor(id: string): string;
+/**
+ * The id a RESUMED session writes back under.
+ *
+ * `--resume` accepts `<id|path>`, so the value the caller typed is NOT usable as
+ * an id: `--resume ./sessions/hand-saved.json` would otherwise make the path
+ * itself the id, and every later `sessionPathFor` / lock call would build a
+ * filename out of it - outside the sessions directory whenever the path was
+ * relative. That is the same write primitive `--session-id` is validated to
+ * prevent, arriving through the flag next to it. `meta.id` is no safer: it comes
+ * out of a file, and files are inputs.
+ *
+ * The order is the one that keeps every legitimate resume landing where the user
+ * expects: an exec-written session names itself, a TUI `/save` is named by its
+ * file, and anything else gets a fresh id rather than a guess - reported back in
+ * `system.init.sessionId` and `result.sessionId`, so the caller is never left
+ * wondering which session it just wrote.
+ */
+export declare function resumedSessionId(path: string, saved: SavedSession): string;
 /** Read one file, or `null` for anything unreadable. NEVER THROWS. */
 export declare function readSessionFile(path: string): SavedSession | null;
 /**

package/dist/session/store.js

@@ -53,8 +53,58 @@ const POINTER_FILE = '.last.json';
 export function sessionsDir() {
     return getSessionsDir();
 }
+/**
+ * THE CHOKE POINT. Every string that becomes a session filename passes here.
+ *
+ * `isValidSessionId` is applied HERE rather than only at `--session-id`, because
+ * that flag is not the only way a caller-supplied string reaches this function:
+ * `--resume <id|path>` derives an id from the resumed FILE, `sessions rm` /
+ * `sessions show` take one straight from argv, and a session file can carry any
+ * `meta.id` at all. Guarding each caller instead would mean the boundary holds
+ * only for the callers someone remembered - and `join()` silently normalises
+ * `../..` away, so an escape leaves no trace to notice later. Validating at the
+ * single point that builds the path is what makes R-7 a property of the module
+ * rather than a habit of its callers.
+ *
+ * THROWS rather than coercing to a "safe" name: a caller who asked for one file
+ * and silently got another is a worse failure than a loud one, and every caller
+ * that can be handed untrusted input validates first and reports exit 2 itself.
+ */
+function assertSessionId(id) {
+    if (!isValidSessionId(id)) {
+        throw new Error(`Invalid session id "${id}": expected 1-64 characters matching ` +
+            '[A-Za-z0-9][A-Za-z0-9._-]* (no "/", "\\", ".." or a leading dot).');
+    }
+    return id;
+}
 export function sessionPathFor(id) {
-    return join(getSessionsDir(), `${id}.json`);
+    return join(getSessionsDir(), `${assertSessionId(id)}.json`);
+}
+/**
+ * The id a RESUMED session writes back under.
+ *
+ * `--resume` accepts `<id|path>`, so the value the caller typed is NOT usable as
+ * an id: `--resume ./sessions/hand-saved.json` would otherwise make the path
+ * itself the id, and every later `sessionPathFor` / lock call would build a
+ * filename out of it - outside the sessions directory whenever the path was
+ * relative. That is the same write primitive `--session-id` is validated to
+ * prevent, arriving through the flag next to it. `meta.id` is no safer: it comes
+ * out of a file, and files are inputs.
+ *
+ * The order is the one that keeps every legitimate resume landing where the user
+ * expects: an exec-written session names itself, a TUI `/save` is named by its
+ * file, and anything else gets a fresh id rather than a guess - reported back in
+ * `system.init.sessionId` and `result.sessionId`, so the caller is never left
+ * wondering which session it just wrote.
+ */
+export function resumedSessionId(path, saved) {
+    const declared = saved.meta?.id;
+    if (typeof declared === 'string' && isValidSessionId(declared))
+        return declared;
+    const base = basenameId(path);
+    if (isValidSessionId(base))
+        return base;
+    return randomUUID();
 }
 function ensureDir() {
     const dir = getSessionsDir();
@@ -117,6 +167,11 @@ export function writeSession(input) {
     return path;
 }
 export function removeSession(id) {
+    // An id that cannot name a session in this directory has not "failed to be
+    // deleted" - there was never a file of that name to delete. `sessions rm`
+    // validates first and reports the reason, so this stays a boolean.
+    if (!isValidSessionId(id))
+        return false;
     const path = sessionPathFor(id);
     try {
         unlinkSync(path);
@@ -329,7 +384,9 @@ export function tryAcquireSessionLock(id, opts = {}) {
     const now = opts.now ?? Date.now;
     const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
     ensureDir();
-    const path = join(getSessionsDir(), `${id}.lock`);
+    // Same boundary as `sessionPathFor` - a lock is a file in this directory too,
+    // and an id that may not name a session may not name its lock either.
+    const path = join(getSessionsDir(), `${assertSessionId(id)}.lock`);
     const payload = {
         pid: process.pid,
         host: hostname(),

package/dist/team/report.js

@@ -143,9 +143,15 @@ function buildSection(run) {
     // bytes, and it is the only place the lead learns which of its children were
     // cheap — the fact the whole second cost line is about.
     const tier = run.tier === 'fast' ? ' [fast]' : '';
+    // `compacted N` in the same position `retried Nx` uses, and for the same
+    // reason (context-auto-compaction-hardening §3.4.4 / W3): this is the ONLY
+    // place the lead learns that a child's own history was summarized mid-task, so
+    // a summary that reads thinner than the turn count suggests has a stated cause
+    // rather than an unexplained one. Absent when it never happened.
+    const compacted = run.compactions ? `, compacted ${run.compactions}` : '';
     const head = [
         `### ${run.label}${tier} "${run.description}"  ${statusBadge(run)}  ${elapsed(run)}, ` +
-            `${run.turns} turns, ${run.toolCalls} tools${retried}`,
+            `${run.turns} turns, ${run.toolCalls} tools${retried}${compacted}`,
     ];
     if (run.filesTouched.length > 0)
         head.push(`files: ${run.filesTouched.join(', ')}`);

package/dist/team/runtime.d.ts

@@ -60,6 +60,16 @@ export interface TeamRuntimeDeps {
      * is the pre-feature behaviour.
      */
     resolveTier?: SubagentDeps['resolveTier'];
+    /**
+     * Per-child context compaction (context-auto-compaction-hardening §3.4 / W3).
+     *
+     * Passed straight through to `SubagentDeps`; absent means children get none,
+     * which is the pre-hardening behaviour exactly. `AgentController` supplies it
+     * from `CompactionWiring.childFactory()`, and the closure returns `undefined`
+     * when compaction is unregistered or `compaction.subagents` is false - which is
+     * what lets `subagent.ts` spread nothing at all.
+     */
+    contextManagerFor?: SubagentDeps['contextManagerFor'];
 }
 export declare class TeamRuntime {
     private readonly deps;

package/dist/team/runtime.js

@@ -132,6 +132,13 @@ export class TeamRuntime {
             ...(this.deps.humanQueue ? { humanQueue: this.deps.humanQueue } : {}),
             agentFactory: this.deps.agentFactory ?? defaultSubagentFactory,
             ...(this.deps.resolveTier ? { resolveTier: this.deps.resolveTier } : {}),
+            // Site two of two, and the omission is silent in the same way the policy
+            // one above is: declaring it on `TeamRuntimeDeps` and forgetting this line
+            // type-checks and forwards nothing, so every child would quietly run with
+            // no compaction while the config key says it has one.
+            ...(this.deps.contextManagerFor
+                ? { contextManagerFor: this.deps.contextManagerFor }
+                : {}),
         };
         // Hoisted into a factory so a retry can build a fresh child with IDENTICAL
         // wiring (F-4). Replacing the child rather than re-prompting it is the only

package/dist/team/subagent.d.ts

@@ -10,8 +10,9 @@
  * them (§3.11 / R-6). What a child does NOT get is spelled out below, and each
  * omission has a reason that is a correctness boundary rather than caution.
  */
-import { type AgentConfig, type AgentEvent, type AgentTool, type ModelRef, type ProviderRegistry, type SkillRegistry, type ThinkingLevel, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
+import { type AgentConfig, type AgentEvent, type AgentTool, type Message, type ModelRef, type ProviderRegistry, type SkillRegistry, type ThinkingLevel, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
+import type { ChildContextManagerProvider } from '../compaction/child.js';
 import type { CliConfig } from '../config/schema.js';
 import type { ToolPermission } from '../exec/permission.js';
 import type { FastTierName } from '../fast/types.js';
@@ -29,6 +30,24 @@ export interface SubagentAgentLike extends WatchdogPausable {
     prompt(text: string): Promise<void>;
     abort(): void;
     subscribe(listener: (event: AgentEvent) => void): () => void;
+    /**
+     * The child's live history, for its own context manager
+     * (context-auto-compaction-hardening §3.4.3 / W3).
+     *
+     * NARROWED ON PURPOSE. `Agent` satisfies this with its full `AgentState`
+     * getter and a stub satisfies it with `{ messages: [] }`. Widening it to
+     * `AgentState` would make every test stub fabricate a systemPrompt, a model and
+     * a phase to compile, for fields none of them use.
+     *
+     * A PROPERTY READ, NOT A METHOD CALL, AND THAT IS NOT A STYLE CHOICE: core's
+     * `Agent` has NO `getMessages()`. It exposes `get state(): AgentState`;
+     * `AgentController.getMessages()` is the CONTROLLER's own one-line forwarder
+     * over `this.agent.state.messages`. Adding a method to the engine to serve a
+     * host-side convenience would move the core export surface for nothing.
+     */
+    readonly state: {
+        readonly messages: readonly Message[];
+    };
 }
 export type SubagentAgentFactory = (config: AgentConfig) => SubagentAgentLike;
 /** The default factory: a real `Agent` from `@aragon-agent/core`. */
@@ -91,6 +110,17 @@ export interface SubagentDeps {
         ref: ModelRef;
         thinkingLevel: ThinkingLevel;
     };
+    /**
+     * Build this child its own context manager
+     * (context-auto-compaction-hardening §3.4.3 / W3).
+     *
+     * ABSENT means children get none, and `subagent.ts` then spreads NO
+     * `contextManager` key at all - so the child's loop gate tests a genuinely
+     * undefined field and a `compaction.subagents: false` session is byte-identical
+     * to round 1 (AC-H10). `AgentController` supplies it from
+     * `CompactionWiring.childFactory()`, which returns `null` when the key is off.
+     */
+    contextManagerFor?: ChildContextManagerProvider;
 }
 export interface SubagentHooks {
     /** Coalesced at the source (§5.2); phase transitions always pass. */

package/dist/team/subagent.js

@@ -183,22 +183,40 @@ export function createSubagent(spec, deps, hooks) {
             thinkingLevel: deps.config.thinkingLevel,
         };
     const model = resolved.ref;
-    const agent = deps.agentFactory({
-        systemPrompt: buildSystemPrompt({
-            cwd: deps.getCwd(),
-            tools,
-            skillsBlock: deps.alwaysBlock ?? '',
-            agentMode: spec.readOnly ? 'plan' : deps.getMode(),
-            // A child has no overlay, so the plan block must describe the headless
-            // shape: write the plan as the final message rather than calling tools it
-            // does not have.
-            planInteractive: false,
-            subagentBlock: buildSubagentBlock({
-                label: spec.label,
-                description: spec.description,
-                peers: deps.bus.peersOf(spec.label),
-            }),
+    // HOISTED TO A LOCAL, AND THAT IS WHAT MAKES W3 POSSIBLE AT ALL. This was built
+    // INLINE inside the `agentFactory({...})` argument, so there was nothing for the
+    // child manager's `getSystemPrompt` accessor to close over - and the accessor
+    // cannot read it back off the agent, because `SubagentAgentLike` is narrowed to
+    // `state.messages` on purpose.
+    const systemPrompt = buildSystemPrompt({
+        cwd: deps.getCwd(),
+        tools,
+        skillsBlock: deps.alwaysBlock ?? '',
+        agentMode: spec.readOnly ? 'plan' : deps.getMode(),
+        // A child has no overlay, so the plan block must describe the headless
+        // shape: write the plan as the final message rather than calling tools it
+        // does not have.
+        planInteractive: false,
+        subagentBlock: buildSubagentBlock({
+            label: spec.label,
+            description: spec.description,
+            peers: deps.bus.peersOf(spec.label),
         }),
+    });
+    // LAZY ACCESSORS OVER `agentRef`, WHICH IS ASSIGNED AFTER THIS RETURNS. A
+    // non-lazy read here is `undefined` at construction and the child's estimate
+    // branch would silently measure an empty history - CR-1 one module over.
+    const contextManager = deps.contextManagerFor?.({
+        label: spec.label,
+        model,
+        getMessages: () => agentRef?.state.messages ?? [],
+        getSystemPrompt: () => systemPrompt,
+        onCompacted: () => {
+            run.compactions = (run.compactions ?? 0) + 1;
+        },
+    });
+    const agent = deps.agentFactory({
+        systemPrompt,
         model,
         tools,
         thinkingLevel: resolved.thinkingLevel,
@@ -217,6 +235,11 @@ export function createSubagent(spec, deps, hooks) {
             // explicitly.
             idleTimeout: deps.config.idleTimeoutMs,
         },
+        // SPREAD CONDITIONALLY, never `contextManager: deps.contextManagerFor?.(...)`.
+        // With the feature off the options bag has no such key, so the loop's gate
+        // tests a field that is genuinely `undefined` rather than a property holding
+        // one - the identical argument `AgentController` makes for the lead (AC-H10).
+        ...(contextManager ? { contextManager } : {}),
     });
     agentRef = agent;
     let lastEmit = 0;
@@ -289,6 +312,10 @@ export function createSubagent(spec, deps, hooks) {
                     outputTokens: run.usage.outputTokens + event.usage.outputTokens,
                 };
                 hooks.onUsage(spec.label, event.usage);
+                // W1's delta needs the history LENGTH the measurement covered, and the
+                // port carries no turn hook. `turn_end` is emitted BEFORE the assistant
+                // push, so this is exactly the history the reported `usage` describes.
+                contextManager?.onTurnEnd(event.usage, agentRef?.state.messages ?? [], systemPrompt);
                 const text = assistantText(event.message);
                 // The LAST non-empty assistant text wins, which is exactly the child's
                 // final message once the loop stops calling tools. Capturing it here