@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/compaction/archive.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The compaction archive - a compaction stops being irreversible
+ * (context-auto-compaction-hardening §3.5 / W4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), and that INCLUDES the field names below and every
+ * string `/compact history` and `/compact show` print.
+ *
+ * WHAT THIS IS FOR. Round 1's non-goal was stated plainly: "the dropped messages
+ * are gone". Combined with R-1 - "the summary is wrong or lossy, and the agent
+ * proceeds confidently on a false record... this is the feature's defining risk
+ * and it cannot be eliminated" - the product was asking the user to accept an
+ * unverifiable, unrecoverable transformation of their session. That is the wrong
+ * default for a tool that runs unattended. This does not add undo (§12: restoring
+ * an over-full history re-creates the condition that triggered compaction). It
+ * adds FIDELITY ON DISK, so R-1 becomes something a human can check.
+ *
+ * NO IMPORTS FROM `ui/`. This module writes files and formats two report blocks;
+ * it has no terminal, no theme and no glyphs.
+ */
+import type { Message } from '@aragon-agent/core';
+import type { CompactionMode, CompactionUiTrigger } from './types.js';
+/** Bumped only when the SHAPE changes; the reader rejects anything else. */
+export declare const ARCHIVE_FORMAT_VERSION = 1;
+export interface CompactionArchive {
+    version: number;
+    /** `COMPACTION_BLOCK_VERSION` at write time, so a bad summary ties to a revision. */
+    blockVersion: string;
+    createdAt: number;
+    /**
+     * Which process wrote this.
+     *
+     * STORED INSIDE THE DOCUMENT as well as in the name, so a file renamed or
+     * copied by hand is still self-describing and the reader never has to parse a
+     * filename for meaning it cannot verify.
+     */
+    runId: string;
+    /** 1-based within this run. */
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    generation: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    /**
+     * THE NUMBER. Deliberately not called `droppedMessages`: that name already
+     * means a COUNT in three typed places (`CompactionPlan`, `finish`'s `applied`
+     * argument, and `AgentEvent.compaction_end`), and this is the document someone
+     * reads while diagnosing a bad summary (RV-3).
+     */
+    droppedCount: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    /** True when `dropped` was shortened to fit `archiveMaxBytes`. */
+    clipped: boolean;
+    /** THE ARRAY. Verbatim, oldest first. */
+    dropped: Message[];
+}
+/** One row of `/compact history`, already resolved from disk. */
+export interface ArchiveListing {
+    entries: ArchiveEntry[];
+    /** Archives in the directory belonging to OTHER runs. Counted, never listed. */
+    otherRuns: number;
+    dir: string;
+}
+export interface ArchiveEntry {
+    path: string;
+    fileName: string;
+    index: number;
+    createdAt: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedCount: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    clipped: boolean;
+}
+export interface ArchiveWriteInput {
+    runId: string;
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    generation: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    dropped: Message[];
+    /** Injected by the tests; production passes nothing. */
+    dir?: string;
+    now?: number;
+}
+/**
+ * `compaction-<YYYY-MM-DD>-<hhmmss>-<runId>-<index>.json`.
+ *
+ * THE RUN ID IS IN THE NAME BECAUSE THE DIRECTORY IS SHARED (RV-6).
+ * `file-sink.ts` makes log retention best-effort precisely because "on Windows
+ * another `aragon` process may hold a handle on a file we would like to remove",
+ * so concurrent CLI processes are an acknowledged in-tree condition rather than
+ * an edge case. Without this segment `/compact history` presents another
+ * session's compactions as this one's and `/compact show 2` is ambiguous the
+ * moment two runs both reach their second compaction.
+ */
+export declare function archiveFileName(runId: string, index: number, at: Date): string;
+/**
+ * Mint this process's archive key.
+ *
+ * NOT `SessionMeta.id`: that exists only once a session has been SAVED, and the
+ * unattended long run this feature serves is exactly the one nobody saved. Short,
+ * filename-safe, and only ever compared for equality - a grouping key, not an
+ * identity.
+ */
+export declare function mintRunId(pid?: number, now?: number): string;
+/**
+ * Serialize, clipping the dropped bodies from the OLDEST end if the document
+ * exceeds `archiveMaxBytes`.
+ *
+ * THE METADATA AND THE SUMMARY ARE NEVER CLIPPED. A truncated archive that still
+ * says what happened, when, and with which model beats no archive at all - and
+ * the oldest dropped messages are the least likely to be the ones a human came
+ * looking for.
+ */
+export declare function serializeArchive(doc: CompactionArchive, maxBytes: number): string;
+/**
+ * Write one archive, then prune. Returns the path written, or `null`.
+ *
+ * NEVER THROWS. The caller runs inside an event handler on the compaction path;
+ * a filesystem is not allowed to affect whether a session survives its context
+ * window. Every failure is a `warn` with the path and nothing else - a toast for
+ * a best-effort audit file trains users to ignore toasts.
+ */
+export declare function writeArchive(input: ArchiveWriteInput): string | null;
+/**
+ * Two-tier retention, and the ORDER MATTERS (§3.5.2 / RV-6).
+ *
+ *  1. WITHIN THIS RUN: keep the newest `archiveMaxFiles` files carrying THIS
+ *     `runId`. This is the bound that protects the user from their own long
+ *     session, and it can never touch another run.
+ *  2. ACROSS RUNS: delete files older than `archiveMaxAgeMs`, regardless of
+ *     `runId`, so an abandoned run's archives do not accumulate forever. AGE, not
+ *     count - a count-based global prune is exactly the rule that deletes a live
+ *     session's work while it is still running.
+ *
+ * Best-effort throughout, in the `enforceRetention` shape: every `rmSync` in its
+ * own `try`, a locked file skipped rather than fatal.
+ */
+export declare function pruneArchives(runId: string, dir: string, now: number): void;
+/**
+ * This run's archives, newest first, plus a COUNT of everyone else's.
+ *
+ * THE COUNT IS REPORTED RATHER THAN THE FILES, because the alternative is a user
+ * concluding their own compactions went missing when the directory holds a
+ * neighbour's.
+ */
+export declare function listArchives(runId: string, dirOverride?: string): ArchiveListing;
+/** One archive by its `#n`, or `null`. `n` is the index within THIS run. */
+export declare function findArchive(runId: string, index: number, dirOverride?: string): ArchiveEntry | null;

package/dist/compaction/archive.js

@@ -0,0 +1,267 @@
+/**
+ * The compaction archive - a compaction stops being irreversible
+ * (context-auto-compaction-hardening §3.5 / W4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), and that INCLUDES the field names below and every
+ * string `/compact history` and `/compact show` print.
+ *
+ * WHAT THIS IS FOR. Round 1's non-goal was stated plainly: "the dropped messages
+ * are gone". Combined with R-1 - "the summary is wrong or lossy, and the agent
+ * proceeds confidently on a false record... this is the feature's defining risk
+ * and it cannot be eliminated" - the product was asking the user to accept an
+ * unverifiable, unrecoverable transformation of their session. That is the wrong
+ * default for a tool that runs unattended. This does not add undo (§12: restoring
+ * an over-full history re-creates the condition that triggered compaction). It
+ * adds FIDELITY ON DISK, so R-1 becomes something a human can check.
+ *
+ * NO IMPORTS FROM `ui/`. This module writes files and formats two report blocks;
+ * it has no terminal, no theme and no glyphs.
+ */
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCompactionArchiveDir } from '../config/app-paths.js';
+import { getLogger } from '../logging/logger.js';
+import { COMPACTION_BLOCK_VERSION, COMPACTION_LIMITS } from './limits.js';
+const FILE_PREFIX = 'compaction-';
+const FILE_SUFFIX = '.json';
+/** Bumped only when the SHAPE changes; the reader rejects anything else. */
+export const ARCHIVE_FORMAT_VERSION = 1;
+/**
+ * `compaction-<YYYY-MM-DD>-<hhmmss>-<runId>-<index>.json`.
+ *
+ * THE RUN ID IS IN THE NAME BECAUSE THE DIRECTORY IS SHARED (RV-6).
+ * `file-sink.ts` makes log retention best-effort precisely because "on Windows
+ * another `aragon` process may hold a handle on a file we would like to remove",
+ * so concurrent CLI processes are an acknowledged in-tree condition rather than
+ * an edge case. Without this segment `/compact history` presents another
+ * session's compactions as this one's and `/compact show 2` is ambiguous the
+ * moment two runs both reach their second compaction.
+ */
+export function archiveFileName(runId, index, at) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const date = `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`;
+    const time = `${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}`;
+    return `${FILE_PREFIX}${date}-${time}-${runId}-${index}${FILE_SUFFIX}`;
+}
+/**
+ * The inverse of `archiveFileName`, or `null` when the name is not one of ours.
+ *
+ * AN EXACT PARSE RATHER THAN `name.includes('-' + runId + '-')`, because that
+ * substring test is not the question either caller is asking. A run id is a pid
+ * in base 36 followed by four base-36 characters of the clock, so a six-character
+ * all-digit one matches the `hhmmss` segment of EVERY other run's file written at
+ * that second - and the two places this attribution is used are precisely the two
+ * RV-6 exists to protect: retention deleting a neighbour's archive, and
+ * `/compact history` presenting one as this run's.
+ *
+ * KEEP IT IN STEP WITH `archiveFileName` ABOVE. The two are one format, written
+ * adjacently so a change to either is visible against the other.
+ */
+function parseArchiveName(name) {
+    const match = /^compaction-\d{4}-\d{2}-\d{2}-\d{6}-(.+)-(\d+)\.json$/.exec(name);
+    if (!match)
+        return null;
+    return { runId: match[1], index: Number(match[2]) };
+}
+/**
+ * Mint this process's archive key.
+ *
+ * NOT `SessionMeta.id`: that exists only once a session has been SAVED, and the
+ * unattended long run this feature serves is exactly the one nobody saved. Short,
+ * filename-safe, and only ever compared for equality - a grouping key, not an
+ * identity.
+ */
+export function mintRunId(pid = process.pid, now = Date.now()) {
+    return `${pid.toString(36)}${now.toString(36).slice(-4)}`;
+}
+/**
+ * Serialize, clipping the dropped bodies from the OLDEST end if the document
+ * exceeds `archiveMaxBytes`.
+ *
+ * THE METADATA AND THE SUMMARY ARE NEVER CLIPPED. A truncated archive that still
+ * says what happened, when, and with which model beats no archive at all - and
+ * the oldest dropped messages are the least likely to be the ones a human came
+ * looking for.
+ */
+export function serializeArchive(doc, maxBytes) {
+    let dropped = doc.dropped;
+    let clipped = doc.clipped;
+    let text = JSON.stringify({ ...doc, dropped, clipped }, null, 2);
+    while (Buffer.byteLength(text, 'utf8') > maxBytes && dropped.length > 0) {
+        // HALVED RATHER THAN SHIFTED ONE AT A TIME: a 100 MB archive of 4 000
+        // messages would otherwise re-serialize 4 000 times, inside a write that is
+        // supposed to be invisible to the run.
+        dropped = dropped.slice(Math.max(1, Math.ceil(dropped.length / 2)));
+        clipped = true;
+        text = JSON.stringify({ ...doc, dropped, clipped }, null, 2);
+    }
+    return text;
+}
+/**
+ * Write one archive, then prune. Returns the path written, or `null`.
+ *
+ * NEVER THROWS. The caller runs inside an event handler on the compaction path;
+ * a filesystem is not allowed to affect whether a session survives its context
+ * window. Every failure is a `warn` with the path and nothing else - a toast for
+ * a best-effort audit file trains users to ignore toasts.
+ */
+export function writeArchive(input) {
+    const dir = input.dir ?? getCompactionArchiveDir();
+    const now = input.now ?? Date.now();
+    const path = join(dir, archiveFileName(input.runId, input.index, new Date(now)));
+    try {
+        mkdirSync(dir, { recursive: true });
+        const doc = {
+            version: ARCHIVE_FORMAT_VERSION,
+            blockVersion: COMPACTION_BLOCK_VERSION,
+            createdAt: now,
+            runId: input.runId,
+            index: input.index,
+            trigger: input.trigger,
+            mode: input.mode,
+            model: input.model,
+            generation: input.generation,
+            tokensBefore: input.tokensBefore,
+            tokensAfter: input.tokensAfter,
+            messagesBefore: input.messagesBefore,
+            messagesAfter: input.messagesAfter,
+            droppedCount: input.dropped.length,
+            ...(input.summary !== undefined ? { summary: input.summary } : {}),
+            ...(input.tailRelief ? { tailRelief: input.tailRelief } : {}),
+            clipped: false,
+            dropped: input.dropped,
+        };
+        writeFileSync(path, serializeArchive(doc, COMPACTION_LIMITS.archiveMaxBytes), 'utf8');
+    }
+    catch (err) {
+        getLogger()
+            .child('compaction')
+            .warn('compaction_archive_failed', { path, error: errorText(err) });
+        return null;
+    }
+    pruneArchives(input.runId, dir, now);
+    return path;
+}
+/**
+ * Two-tier retention, and the ORDER MATTERS (§3.5.2 / RV-6).
+ *
+ *  1. WITHIN THIS RUN: keep the newest `archiveMaxFiles` files carrying THIS
+ *     `runId`. This is the bound that protects the user from their own long
+ *     session, and it can never touch another run.
+ *  2. ACROSS RUNS: delete files older than `archiveMaxAgeMs`, regardless of
+ *     `runId`, so an abandoned run's archives do not accumulate forever. AGE, not
+ *     count - a count-based global prune is exactly the rule that deletes a live
+ *     session's work while it is still running.
+ *
+ * Best-effort throughout, in the `enforceRetention` shape: every `rmSync` in its
+ * own `try`, a locked file skipped rather than fatal.
+ */
+export function pruneArchives(runId, dir, now) {
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX))
+            .map((name) => {
+            const path = join(dir, name);
+            try {
+                return { path, name, mtime: statSync(path).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => e !== null);
+    }
+    catch {
+        return; // The directory does not exist yet, or is unreadable.
+    }
+    const mine = files
+        .filter((f) => parseArchiveName(f.name)?.runId === runId)
+        .sort((a, b) => a.mtime - b.mtime);
+    for (const f of mine.slice(0, Math.max(0, mine.length - COMPACTION_LIMITS.archiveMaxFiles))) {
+        remove(f.path);
+    }
+    for (const f of files) {
+        if (now - f.mtime > COMPACTION_LIMITS.archiveMaxAgeMs)
+            remove(f.path);
+    }
+}
+function remove(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Held by another instance. Retention is best-effort by design.
+    }
+}
+/**
+ * This run's archives, newest first, plus a COUNT of everyone else's.
+ *
+ * THE COUNT IS REPORTED RATHER THAN THE FILES, because the alternative is a user
+ * concluding their own compactions went missing when the directory holds a
+ * neighbour's.
+ */
+export function listArchives(runId, dirOverride) {
+    const dir = dirOverride ?? getCompactionArchiveDir();
+    const entries = [];
+    let otherRuns = 0;
+    let names;
+    try {
+        names = readdirSync(dir).filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX));
+    }
+    catch {
+        return { entries: [], otherRuns: 0, dir };
+    }
+    for (const name of names) {
+        if (parseArchiveName(name)?.runId !== runId) {
+            otherRuns += 1;
+            continue;
+        }
+        const entry = readArchiveEntry(join(dir, name), name);
+        if (entry)
+            entries.push(entry);
+    }
+    entries.sort((a, b) => b.index - a.index);
+    return { entries, otherRuns, dir };
+}
+/** One archive by its `#n`, or `null`. `n` is the index within THIS run. */
+export function findArchive(runId, index, dirOverride) {
+    return listArchives(runId, dirOverride).entries.find((e) => e.index === index) ?? null;
+}
+/**
+ * Read one document's METADATA. The `dropped` array is never returned.
+ *
+ * `/compact show` prints no message bodies (DH-9): a single archive can be
+ * megabytes and the transcript is not a pager. The path is the useful output.
+ */
+function readArchiveEntry(path, fileName) {
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if (raw.version !== ARCHIVE_FORMAT_VERSION)
+            return null;
+        return {
+            path,
+            fileName,
+            index: Number(raw.index ?? 0),
+            createdAt: Number(raw.createdAt ?? 0),
+            trigger: (raw.trigger ?? 'pressure'),
+            mode: (raw.mode ?? 'none'),
+            model: String(raw.model ?? ''),
+            tokensBefore: Number(raw.tokensBefore ?? 0),
+            tokensAfter: Number(raw.tokensAfter ?? 0),
+            droppedCount: Number(raw.droppedCount ?? 0),
+            ...(typeof raw.summary === 'string' ? { summary: raw.summary } : {}),
+            ...(raw.tailRelief ? { tailRelief: raw.tailRelief } : {}),
+            clipped: raw.clipped === true,
+        };
+    }
+    catch {
+        // A half-written file from a process that was killed mid-write, or a format
+        // from a future version. Skipping it is the only sensible reading.
+        return null;
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/compaction/child.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Per-child context compaction (context-auto-compaction-hardening §3.4 / W3).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * WHY THIS REVERSES D-15. That decision said children are bounded by their
+ * dispatch timeout and turn cap, so giving them a manager only makes a dispatch's
+ * cost unpredictable. The premise is measurable and false at the configured
+ * bounds: `team.maxTurnsPerSubagent` is 24 and `team.dispatchTimeoutMs` is
+ * 900 000, which is 24 turns over fifteen minutes - the same profile as the lead
+ * run this feature exists for. The cost argument also inverts once the
+ * alternative is priced: an overflow ENDS the dispatch, the lead pays for every
+ * turn the child already ran, and receives one partial sentence for all of it.
+ * Two fast-model summarizations is the cheap side of that trade.
+ *
+ * A CHILD MANAGER IS THE SAME `Compactor` UNDER A DIFFERENT POLICY, and the
+ * overlay needs TWO mechanisms rather than one (RV-2):
+ *
+ *   A. A CONFIG VIEW, for `keepRecentTurns` / `onFailure` / `useFastTier`, which
+ *      `Compactor` reads through `deps.getConfig()`.
+ *   B. AN INSTANCE BOUND, for `maxPerRun`, which is STRUCTURAL and has no config
+ *      path by design (`limits.ts` header). Without it the child silently
+ *      inherits the lead's 5 - two and a half times the bound the reversal above
+ *      rests on.
+ *
+ * NO UI. A child's compaction produces no transcript card (DH-7): the lead's
+ * transcript describes the LEAD's context, and a card there would claim the
+ * lead's own history had been compacted. The team panel row and the dispatch
+ * report are where a child's internals belong.
+ */
+import type { AssistantMessage, ContextManager, LLMRequest, Message, ModelInfo, ModelRef, TokenUsage } from '@aragon-agent/core';
+import type { CliConfig } from '../config/schema.js';
+export interface ChildCompactionDeps {
+    /** Read LIVE on every call - see `childConfig` below. */
+    getConfig: () => CliConfig;
+    hasKey: (providerId: string) => boolean;
+    getApiKey: (providerId: string) => string | undefined;
+    getModelInfoFor: (ref: Pick<ModelRef, 'providerId' | 'modelId'>) => ModelInfo;
+    isPricedModel: (ref: Pick<ModelRef, 'providerId' | 'modelId'>) => boolean;
+    /** The lead wiring's own transport, reused (D-10 stays true). */
+    complete: (providerId: string, request: LLMRequest) => Promise<AssistantMessage>;
+    /** Child compaction spend joins the session totals through the lead's sink. */
+    onUsage: (usage: TokenUsage) => void;
+}
+/**
+ * Everything one child manager needs about its child.
+ *
+ * AN OPTIONS OBJECT RATHER THAN FIVE POSITIONAL PARAMETERS - the rule
+ * `TeamRuntime.RunOneCtx` states one package over, and this signature would sit
+ * exactly on the cap.
+ */
+export interface ChildContextManagerRequest {
+    label: string;
+    /**
+     * The model the child actually runs on.
+     *
+     * CARRIED RATHER THAN READ FROM CONFIG, because a `tier: 'fast'` child runs on
+     * a model whose context window is usually SMALLER than the lead's. Measuring a
+     * child against the lead's window would put the trigger in the wrong place in
+     * the one direction that matters - late.
+     */
+    model: ModelRef;
+    /**
+     * LAZY, AND IT MUST BE. `agentRef` is assigned AFTER the factory call returns,
+     * so a non-lazy read here is `undefined` at construction and the child's
+     * estimate branch would silently measure an empty history - CR-1 reproduced one
+     * module over.
+     */
+    getMessages: () => readonly Message[];
+    getSystemPrompt: () => string;
+    onCompacted: () => void;
+}
+/**
+ * A child manager, plus the one hook the port does not carry.
+ *
+ * `onTurnEnd` IS NOT PART OF `ContextManager` and is called by `subagent.ts` from
+ * its existing `turn_end` case. Without it the child never records the history
+ * length its last measurement covered, so W1's delta is permanently `undefined`
+ * and the child reads the same systematically-short number the lead used to.
+ */
+export interface ChildContextManager extends ContextManager {
+    onTurnEnd(usage: TokenUsage, messages: readonly Message[], systemPrompt: string): void;
+}
+export type ChildContextManagerFactory = (req: ChildContextManagerRequest) => ChildContextManager;
+/**
+ * The shape `subagent.ts` is handed, which may DECLINE.
+ *
+ * `undefined` RATHER THAN A THROW OR A NO-OP MANAGER, and the difference is
+ * AC-H10: the caller spreads the result conditionally, so a session with
+ * `compaction.subagents: false` builds a child whose options bag has no
+ * `contextManager` KEY AT ALL - the loop's gate then tests a genuinely absent
+ * field. The decision is re-taken per child rather than per dispatch, so a
+ * settings-screen edit mid-dispatch reaches the next one.
+ */
+export type ChildContextManagerProvider = (req: ChildContextManagerRequest) => ChildContextManager | undefined;
+/** One manager per child. State is per-history and must not be shared. */
+export declare function createChildContextManager(req: ChildContextManagerRequest, deps: ChildCompactionDeps): ChildContextManager;

package/dist/compaction/child.js

@@ -0,0 +1,113 @@
+/**
+ * Per-child context compaction (context-auto-compaction-hardening §3.4 / W3).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * WHY THIS REVERSES D-15. That decision said children are bounded by their
+ * dispatch timeout and turn cap, so giving them a manager only makes a dispatch's
+ * cost unpredictable. The premise is measurable and false at the configured
+ * bounds: `team.maxTurnsPerSubagent` is 24 and `team.dispatchTimeoutMs` is
+ * 900 000, which is 24 turns over fifteen minutes - the same profile as the lead
+ * run this feature exists for. The cost argument also inverts once the
+ * alternative is priced: an overflow ENDS the dispatch, the lead pays for every
+ * turn the child already ran, and receives one partial sentence for all of it.
+ * Two fast-model summarizations is the cheap side of that trade.
+ *
+ * A CHILD MANAGER IS THE SAME `Compactor` UNDER A DIFFERENT POLICY, and the
+ * overlay needs TWO mechanisms rather than one (RV-2):
+ *
+ *   A. A CONFIG VIEW, for `keepRecentTurns` / `onFailure` / `useFastTier`, which
+ *      `Compactor` reads through `deps.getConfig()`.
+ *   B. AN INSTANCE BOUND, for `maxPerRun`, which is STRUCTURAL and has no config
+ *      path by design (`limits.ts` header). Without it the child silently
+ *      inherits the lead's 5 - two and a half times the bound the reversal above
+ *      rests on.
+ *
+ * NO UI. A child's compaction produces no transcript card (DH-7): the lead's
+ * transcript describes the LEAD's context, and a card there would claim the
+ * lead's own history had been compacted. The team panel row and the dispatch
+ * report are where a child's internals belong.
+ */
+import { getLogger } from '../logging/logger.js';
+import { Compactor } from './compactor.js';
+import { COMPACTION_LIMITS } from './limits.js';
+/** One manager per child. State is per-history and must not be shared. */
+export function createChildContextManager(req, deps) {
+    const log = getLogger().child('compaction');
+    /**
+     * MECHANISM A - the config view.
+     *
+     * IT RE-READS `deps.getConfig()` ON EVERY CALL and never closes over one
+     * snapshot: a settings-screen edit mid-dispatch has to reach a running child,
+     * which is the same reason `subagent.ts` reuses the lead's `getApiKey` closure
+     * rather than the resolved key.
+     *
+     * `useFastTier: true` EXPRESSES A PREFERENCE, NOT AN OUTCOME. `resolveFastTier`
+     * still decides, and when nothing resolves the child falls back exactly as the
+     * lead does - to its OWN model, because `provider` / `model` are overlaid here
+     * too.
+     *
+     * `onFailure: 'truncate'` IS FORCED because a child that stops is a failed
+     * dispatch and the user is not there to intervene.
+     */
+    const childConfig = () => {
+        const base = deps.getConfig();
+        return {
+            ...base,
+            provider: req.model.providerId,
+            model: req.model.modelId,
+            ...(req.model.baseUrl !== undefined ? { baseUrl: req.model.baseUrl } : {}),
+            compaction: {
+                ...base.compaction,
+                keepRecentTurns: COMPACTION_LIMITS.childKeepRecentTurns,
+                onFailure: 'truncate',
+                useFastTier: true,
+                // ONE ARCHIVE PER LEAD COMPACTION IS AUDITABLE; TWENTY PER DISPATCH IS
+                // NOISE. The child's dropped slice is therefore never retained either -
+                // `runCompaction` reads this key before it stashes anything.
+                archive: false,
+            },
+        };
+    };
+    const compactor = new Compactor({
+        getConfig: childConfig,
+        hasKey: deps.hasKey,
+        getApiKey: deps.getApiKey,
+        getModelInfoFor: deps.getModelInfoFor,
+        isPricedModel: deps.isPricedModel,
+        getMessages: req.getMessages,
+        getSystemPrompt: req.getSystemPrompt,
+        complete: deps.complete,
+        emit: (event) => {
+            if (event.type === 'usage') {
+                deps.onUsage(event.usage);
+                return;
+            }
+            if (event.type !== 'compaction_end')
+                return;
+            if (!event.record.applied && event.record.mode === 'none')
+                return;
+            req.onCompacted();
+            // W3 HAS NO CARD, so this line is the whole record of a child compaction.
+            log.info('compaction_child', {
+                label: req.label,
+                index: event.record.index,
+                tokensBefore: event.record.tokensBefore,
+                tokensAfter: event.record.tokensAfter,
+            });
+        },
+        // A CHILD HAS NO TRANSCRIPT AND NOBODY WATCHING IT. `notify` on the lead's
+        // channel would put a warning about a background worker's context in the
+        // user's transcript with no card to explain which agent it is about.
+        notify: () => { },
+    }, 
+    // MECHANISM B - the instance bound (RV-2 / DH-16).
+    { maxPerRun: COMPACTION_LIMITS.childMaxPerRun });
+    return {
+        // THERE IS NO `/compact` FOR A CHILD, so nothing is ever queued and the
+        // manual branch of `shouldCompact` is unreachable by construction.
+        shouldCompact: (probe) => compactor.shouldCompact(probe),
+        compact: (ctx) => compactor.compact(ctx),
+        onTurnEnd: (usage, messages, systemPrompt) => compactor.onTurnEnd(usage, messages, systemPrompt),
+    };
+}