@aragon-agent/cli 0.6.23 → 0.6.25

package/dist/config/load.js

@@ -411,33 +411,44 @@ function resolveMaxTokens(flags, env, file) {
  * `null`, and `null` is exactly the value being looked for. NO CLI FLAG feeds
  * this - it is a per-installation correction for a model table entry, not a
  * per-invocation choice, so `config set` and the environment variable are the
- * two surfaces the design names.
+ * two surfaces the design names. The model profile bound as Main is the third
+ * (profile-context-window): its window arrives already merged into the `file`
+ * layer by `projectModelProfiles`, and `profileOwned` names it.
+ *
+ * THE ORIGIN CONTRACT (profile-context-window §6.1, shared verbatim with the
+ * save transaction): `origin !== undefined` IF AND ONLY IF `value !== null`.
+ * An explicit AUTO - profile set to auto, `config set contextWindow auto`,
+ * `ARAGON_CONTEXT_WINDOW=auto` - returns `{ value: null }` and NO origin,
+ * because "the user asserted this denominator" and "the user declared AUTO"
+ * are different facts and the meter's override branch only sees the first.
  */
-function resolveContextWindow(env, file) {
+function resolveContextWindow(env, file, profileOwned) {
     const layers = [
         {
             name: 'ARAGON_CONTEXT_WINDOW',
             value: hasOwn(env, 'contextWindow') ? env.contextWindow : undefined,
+            origin: 'env',
         },
         {
             name: 'config.json contextWindow',
             value: hasOwn(file, 'contextWindow') ? file.contextWindow : undefined,
+            origin: profileOwned ? 'profile' : 'config',
         },
     ];
     for (const layer of layers) {
         if (layer.value === undefined)
             continue; // this layer said nothing
         if (layer.value === null || isAutoToken(layer.value))
-            return null; // AUTO
+            return { value: null }; // AUTO
         const n = clampContextWindow(layer.value, null);
         if (n !== null)
-            return n;
+            return { value: n, origin: layer.origin };
         getLogger().warn('config', 'context_window_unusable', {
             source: layer.name,
             value: String(layer.value),
         });
     }
-    return DEFAULT_CONFIG.contextWindow;
+    return { value: DEFAULT_CONFIG.contextWindow };
 }
 /**
  * Rewrite the cli<=0.6.16 persisted team ceiling defaults to 0 and persist the
@@ -513,7 +524,8 @@ export function loadConfig(flags = {}, options = {}) {
     const liveToolOutput = pick(flags.liveToolOutput, env.partial.liveToolOutput, file.liveToolOutput) ??
         DEFAULT_CONFIG.liveToolOutput;
     const maxTokens = resolveMaxTokens(flags, env.partial, file);
-    const contextWindow = resolveContextWindow(env.partial, file);
+    const resolvedWindow = resolveContextWindow(env.partial, file, projection.mainOwnsContextWindow);
+    const contextWindow = resolvedWindow.value;
     // `clampTheme` is also where the v0.3.0 `dark` name is migrated to `cool`,
     // so reading a legacy config file needs no extra step here (§4.5 / R-4).
     const theme = clampTheme(pick(flags.theme, env.partial.theme, file.theme), DEFAULT_CONFIG.theme);
@@ -609,6 +621,12 @@ export function loadConfig(flags = {}, options = {}) {
         liveToolOutput,
         maxTokens,
         contextWindow,
+        // CONDITIONAL SPREAD so a feature-off config object stays byte-identical
+        // (invariant 6): with no override there is no origin KEY, not an undefined
+        // one, and every `toEqual` on a default config keeps passing untouched.
+        ...(resolvedWindow.origin !== undefined
+            ? { contextWindowOrigin: resolvedWindow.origin }
+            : {}),
         theme,
         reducedMotion,
         exitTranscript: flags.exitTranscript !== undefined

package/dist/config/model-profile-resolution.d.ts

@@ -4,6 +4,14 @@ export interface ProfileProjection {
     file: Partial<PersistedConfig>;
     state: ModelProfilesRuntime;
     issues: ProfileValidationIssue[];
+    /**
+     * True when a valid library has Main bound, so the bound profile OWNS the
+     * context-window denominator (profile-context-window tradeoff B). THE ONE
+     * AUTHORITY for "does the profile decide the window" - load.ts and the save
+     * transaction both read it rather than comparing numbers, which would lie on
+     * a coincidental match.
+     */
+    mainOwnsContextWindow: boolean;
 }
 export interface RoleKeyInput {
     config: CliConfig;

package/dist/config/model-profile-resolution.js

@@ -9,8 +9,9 @@ export function projectModelProfiles(file) {
     const issues = validateModelProfiles(file.modelProfiles);
     const state = emptyModelProfileState(issues.length > 0);
     const projected = { ...file };
-    if (issues.length || !file.modelProfiles)
-        return { file: projected, state, issues };
+    if (issues.length || !file.modelProfiles) {
+        return { file: projected, state, issues, mainOwnsContextWindow: false };
+    }
     const library = normalizeModelProfiles(file.modelProfiles);
     projected.modelProfiles = library;
     for (const role of ['main', 'fast']) {
@@ -20,13 +21,19 @@ export function projectModelProfiles(file) {
         state[role] = { selectedId: entry.id, appliedId: entry.id,
             overriddenFields: [], invalid: false };
         const connection = { provider: entry.provider, model: entry.model, baseUrl: entry.baseUrl };
-        if (role === 'main')
-            Object.assign(projected, connection);
-        else
+        if (role === 'main') {
+            // The profile owns the denominator: project BOTH a number and null
+            // (null = AUTO), so "profile set auto" stays distinguishable from
+            // "no profile bound" (profile-context-window tradeoff B).
+            Object.assign(projected, connection, { contextWindow: entry.contextWindow });
+        }
+        else {
             projected.fast = { ...DEFAULT_CONFIG.fast, ...file.fast, ...connection,
                 baseUrl: entry.baseUrl ?? '' };
+        }
     }
-    return { file: projected, state, issues };
+    return { file: projected, state, issues,
+        mainOwnsContextWindow: state.main.appliedId !== null };
 }
 /** Derive binding status from current connections, including session/model overrides. */
 export function resolveModelProfileState(config, profiles = config.modelProfiles, invalid = false) {

package/dist/config/model-profile-store.d.ts

@@ -1,9 +1,11 @@
 import { type ModelProfilesConfig, type ModelRole, type ProfileValidationIssue } from './model-profiles.js';
-import type { CliConfig, CompactionConfig, FastConfig, LogConfig, PersistedConfig } from './schema.js';
-export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log'>> {
+import type { CliConfig, CompactionConfig, FastConfig, LogConfig, PersistedConfig, TeamConfig } from './schema.js';
+export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log' | 'team'>> {
     fast?: Partial<FastConfig>;
     compaction?: Partial<CompactionConfig>;
     log?: Partial<LogConfig>;
+    /** The subagent-model picker writes here (subagent-model D-5/I-5): draft-only until Save. */
+    team?: Partial<TeamConfig>;
 }
 export interface ModelSettingsDraft {
     profiles?: ModelProfilesConfig;

package/dist/config/model-profiles.d.ts

@@ -6,6 +6,8 @@ export interface ModelProfile {
     model: string;
     baseUrl: string | null;
     apiKey: string | null;
+    /** The context window of this model+endpoint; null = AUTO (profile-context-window 5.1). */
+    contextWindow: number | null;
 }
 export interface ModelProfilesConfig {
     version: 1;
@@ -32,8 +34,27 @@ export interface ProfileValidationIssue {
 export declare function emptyModelProfiles(): ModelProfilesConfig;
 /** Return independently mutable role state. */
 export declare function emptyModelProfileState(invalid?: boolean): ModelProfilesRuntime;
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * copy of these four clauses is one edit away from disagreeing with the config layer.
+ */
+export declare function isValidEndpointUrl(value: string | null | undefined): boolean;
 /** Validate untrusted input; diagnostics never include supplied values. */
 export declare function validateModelProfiles(value: unknown): ProfileValidationIssue[];
+/**
+ * Disk-tolerance gate for a profile-level context window (profile-context-window 5.3).
+ *
+ * THE SAME TRI-STATE DISCIPLINE as store.ts normalizeContextWindow, kept out of
+ * store.ts on purpose: this file already imports schema.js and store's sibling
+ * model-profile-store.ts already imports this one, so placing it here avoids
+ * widening the existing store <-> model-profile-store cycle. A garbage value on
+ * a hand-edited file degrades to AUTO; it NEVER invalidates the whole library
+ * (invariant 4 - one bad number must not drop the user's credentials).
+ */
+export declare function normalizeProfileContextWindow(value: unknown): number | null;
 /** Normalize a valid library into a safe field whitelist; throws a fixed error if invalid. */
 export declare function normalizeModelProfiles(value: unknown): ModelProfilesConfig;
 /** Create an entry with a stable UUID and a frozen default name. */

package/dist/config/model-profiles.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { ADAPTER_PROVIDERS } from './schema.js';
+import { ADAPTER_PROVIDERS, clampContextWindow, isAutoToken } from './schema.js';
 const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
 /** Return a fresh empty library without initiating a disk migration. */
 export function emptyModelProfiles() {
@@ -32,6 +32,16 @@ function validUrl(value) {
         return false;
     }
 }
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * copy of these four clauses is one edit away from disagreeing with the config layer.
+ */
+export function isValidEndpointUrl(value) {
+    return validUrl(value);
+}
 function validateEntry(value, index) {
     const path = `modelProfiles.entries[${index}]`;
     const invalid = (field, message) => ({
@@ -91,6 +101,21 @@ export function validateModelProfiles(value) {
     }
     return issues;
 }
+/**
+ * Disk-tolerance gate for a profile-level context window (profile-context-window 5.3).
+ *
+ * THE SAME TRI-STATE DISCIPLINE as store.ts normalizeContextWindow, kept out of
+ * store.ts on purpose: this file already imports schema.js and store's sibling
+ * model-profile-store.ts already imports this one, so placing it here avoids
+ * widening the existing store <-> model-profile-store cycle. A garbage value on
+ * a hand-edited file degrades to AUTO; it NEVER invalidates the whole library
+ * (invariant 4 - one bad number must not drop the user's credentials).
+ */
+export function normalizeProfileContextWindow(value) {
+    if (value === undefined || value === null || isAutoToken(value))
+        return null;
+    return clampContextWindow(value, null);
+}
 /** Normalize a valid library into a safe field whitelist; throws a fixed error if invalid. */
 export function normalizeModelProfiles(value) {
     if (validateModelProfiles(value).length)
@@ -102,7 +127,8 @@ export function normalizeModelProfiles(value) {
         entries: library.entries.map((entry) => ({ id: entry.id, name: entry.name.trim()
                 || [...entry.model.trim()].slice(0, 80).join(''), provider: entry.provider,
             model: entry.model.trim(), baseUrl: entry.baseUrl?.trim() || null,
-            apiKey: entry.apiKey?.trim() || null })) };
+            apiKey: entry.apiKey?.trim() || null,
+            contextWindow: normalizeProfileContextWindow(entry.contextWindow) })) };
 }
 /** Create an entry with a stable UUID and a frozen default name. */
 export function createModelProfile(input) {

package/dist/config/schema.d.ts

@@ -99,6 +99,35 @@ export declare const MAX_CONTEXT_WINDOW = 5000000;
  * this deliberately copies its shape rather than inventing a second convention.
  */
 export declare function clampContextWindow(v: unknown, fallback: number | null): number | null;
+/**
+ * Where the effective `contextWindow` override came from
+ * (profile-context-window §5.2).
+ *
+ * A CLI-LOCAL RUNTIME FACT: never persisted, never promoted into Core's event
+ * shapes. It exists so `/context` can name WHICH surface supplied a
+ * denominator the user asserted - the environment, the legacy top-level key,
+ * or the model profile bound as Main.
+ */
+export type ContextWindowOrigin = 'env' | 'config' | 'profile';
+/**
+ * Parse text typed into the settings screen or the profile editor for a
+ * context window (profile-context-window §5.3).
+ *
+ * THE MIRROR OF `parseMaxTokensInput` BELOW, down to the tri-state shape: it
+ * distinguishes AUTO from "the user typed nonsense", which `clampContextWindow`
+ * cannot - a typo must change NOTHING rather than silently discard the number
+ * the user meant to set. `''` / `'auto'` / `'0'` are AUTO (`isAutoToken`);
+ * a digit run is clamped through THE single gate; anything else is invalid.
+ */
+export declare function parseContextWindowInput(raw: string): {
+    kind: 'auto';
+} | {
+    kind: 'value';
+    value: number;
+    clamped: boolean;
+} | {
+    kind: 'invalid';
+};
 /**
  * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
  *
@@ -356,6 +385,26 @@ export interface TeamConfig {
      * meaningful while `team.overseer` is true.
      */
     overseerIntervalMs: number;
+    /**
+     * Which model a team child runs on (subagent-model-and-question-controls
+     * D-2). `'main'` = the lead's own connection - the default and the
+     * historical parity behavior; `'fast'` = the fast tier, resolved per
+     * dispatch through `resolveFastTier`; `'profile'` = the entry named by
+     * `team.modelProfileId`.
+     *
+     * A USER-OWNED SETTING, NEVER A TOOL PARAMETER (D-1): `normalizeSubagentSpecs`
+     * keeps silently dropping a stale `model` key, so the MODEL cannot downgrade
+     * its own delegation. This key is the one explicit, visible, reversible
+     * switch the human owns.
+     */
+    model: 'main' | 'fast' | 'profile';
+    /**
+     * The profile entry a `model: 'profile'` dispatch binds to; `null` = not
+     * bound. IGNORED by the other modes. Existence is NOT validated here - a
+     * dangling id degrades to the main model with a disclosed reason at
+     * resolution time (D-4), so deleting a profile can never break a dispatch.
+     */
+    modelProfileId: string | null;
 }
 /**
  * The requirement's ceiling on the fan-out (R-g).
@@ -967,6 +1016,18 @@ export interface CliConfig {
      * would parse and be discarded, with nothing failing.
      */
     contextWindow: number | null;
+    /**
+     * WHERE the override above came from, or `undefined` when there is none
+     * (profile-context-window §5.2). RUNTIME-ONLY, never persisted.
+     *
+     * THE CONTRACT IS AN IFF: `contextWindowOrigin !== undefined` exactly when
+     * `contextWindow !== null`. An explicit AUTO (profile set to auto,
+     * `config set contextWindow auto`, `ARAGON_CONTEXT_WINDOW=auto`) has value
+     * null, so its origin is undefined - "the user asserted this denominator"
+     * and "the user declared AUTO" are different facts, and the meter's
+     * override branch only ever sees the first.
+     */
+    contextWindowOrigin?: ContextWindowOrigin;
     theme: ThemeName;
     reducedMotion: boolean;
     /** Replay a plain-text summary on exit (full-screen only — see §4.4). */

package/dist/config/schema.js

@@ -148,6 +148,27 @@ export function clampContextWindow(v, fallback) {
         return fallback;
     return Math.min(MAX_CONTEXT_WINDOW, Math.max(MIN_CONTEXT_WINDOW, Math.floor(n)));
 }
+/**
+ * Parse text typed into the settings screen or the profile editor for a
+ * context window (profile-context-window §5.3).
+ *
+ * THE MIRROR OF `parseMaxTokensInput` BELOW, down to the tri-state shape: it
+ * distinguishes AUTO from "the user typed nonsense", which `clampContextWindow`
+ * cannot - a typo must change NOTHING rather than silently discard the number
+ * the user meant to set. `''` / `'auto'` / `'0'` are AUTO (`isAutoToken`);
+ * a digit run is clamped through THE single gate; anything else is invalid.
+ */
+export function parseContextWindowInput(raw) {
+    const trimmed = String(raw ?? '').trim();
+    if (isAutoToken(trimmed))
+        return { kind: 'auto' };
+    if (!/^\d+$/.test(trimmed))
+        return { kind: 'invalid' };
+    const value = clampContextWindow(trimmed, null);
+    if (value === null)
+        return { kind: 'invalid' };
+    return { kind: 'value', value, clamped: value !== Number.parseInt(trimmed, 10) };
+}
 /**
  * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
  *
@@ -457,6 +478,10 @@ export const DEFAULT_TEAM_CONFIG = {
     overseer: true,
     // 0 = the structural cadence default (300 s). See the field docstring.
     overseerIntervalMs: 0,
+    // The parity default: children run the lead's own model until the user
+    // says otherwise (AC-1 - an upgraded config behaves exactly as before).
+    model: 'main',
+    modelProfileId: null,
 };
 const SUBAGENTS_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
 const CONCURRENT_RANGE = { min: 1, max: HARD_MAX_SUBAGENTS };
@@ -490,6 +515,17 @@ export function clampTeamConfig(raw) {
         maxTurnsPerSubagent: clampIntAllowingZero(src.maxTurnsPerSubagent, DEFAULT_TEAM_CONFIG.maxTurnsPerSubagent, TURNS_RANGE),
         overseer: bool(src.overseer, DEFAULT_TEAM_CONFIG.overseer),
         overseerIntervalMs: clampIntAllowingZero(src.overseerIntervalMs, DEFAULT_TEAM_CONFIG.overseerIntervalMs, OVERSEER_INTERVAL_RANGE),
+        // typo-changes-nothing, the discipline every enum clamp here follows: a
+        // hand-edited `model: 'fats'` resolves to 'main' (the parity default)
+        // rather than invalidating the file or refusing to launch. A bad
+        // `modelProfileId` (wrong type, or over the 128-codepoint budget
+        // `model-profiles.ts::validText` defines) is nulled the same way;
+        // reference EXISTENCE stays a resolution-time concern (D-4).
+        model: src.model === 'fast' || src.model === 'profile' ? src.model : 'main',
+        modelProfileId: typeof src.modelProfileId === 'string' && src.modelProfileId.length > 0
+            && [...src.modelProfileId].length <= 128
+            ? src.modelProfileId
+            : null,
     };
 }
 /**

package/dist/session/clear-archive.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Archive the conversation a `/clear` is about to destroy
+ * (clear-command-context-reset §3.8 / D-5 / I-5).
+ *
+ * ASCII ONLY: `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS EXISTS AT ALL: a command whose whole job is to destroy context is a
+ * command a user will eventually fire by accident, one keystroke from `/cwd`. The
+ * difference between "I lost an hour of work" and "I resumed it" is one file, and
+ * `saveSession()` already knows how to write it.
+ *
+ * WHY THIS IS NOT `session/store.ts::writeSession()`: that function MOVES THE
+ * `--continue` POINTER and writes `meta`. An archive is not a session you continue;
+ * it is a record you resume BY PATH. Writing `meta` would also make the file look
+ * `aragon exec`-managed to `sessions list` / `prune`, which is the scoping rule
+ * `persist.ts` records at the top of `SessionMeta` - so a maintenance command would
+ * start deleting the user's cleared conversations.
+ *
+ * ISOLATION IS TWO DEEP (I-6 / P2-4). The directory is the first fence:
+ * `listSessions` / `pruneSessions` / `latestSessionForCwd` read `sessionsDir()`
+ * non-recursively and skip anything not ending in `.json` (`store.ts`), so a
+ * SUBDIRECTORY name is invisible to all three by construction. Omitting `meta` is
+ * the second fence, for the day someone makes that listing recursive or gives
+ * `--all` a wider meaning.
+ */
+import type { Message, ModelRef } from '@aragon-agent/core';
+import type { Entry } from '../agent/reducer.js';
+import type { TodoItem } from '../todo/types.js';
+import type { CompactionIdentity } from '../compaction/memory-identity.js';
+/** Everything the archive writes. `entries` is supplied by the command layer. */
+export interface ClearedArchiveInput {
+    model: ModelRef;
+    messages: Message[];
+    compactionIdentity?: CompactionIdentity;
+    /** The screen transcript, which lives only in `ViewState` (P0-1). */
+    entries: Entry[];
+    todos: TodoItem[];
+}
+/** Bounded retention: the newest N cleared conversations survive. */
+export declare const CLEAR_ARCHIVE_LIMITS: {
+    readonly maxArchives: 20;
+};
+/**
+ * Best-effort archive of the conversation being cleared.
+ *
+ * @returns the absolute path of the written file, or `null` when there was
+ * nothing to save (an empty conversation) or the write failed. NEVER THROWS:
+ * a full disk must not be able to stop a user from starting a new conversation
+ * (I-5), and a caller that had to wrap this in `try` would eventually forget.
+ */
+export declare function archiveClearedConversation(input: ClearedArchiveInput): string | null;

package/dist/session/clear-archive.js

@@ -0,0 +1,160 @@
+/**
+ * Archive the conversation a `/clear` is about to destroy
+ * (clear-command-context-reset §3.8 / D-5 / I-5).
+ *
+ * ASCII ONLY: `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS EXISTS AT ALL: a command whose whole job is to destroy context is a
+ * command a user will eventually fire by accident, one keystroke from `/cwd`. The
+ * difference between "I lost an hour of work" and "I resumed it" is one file, and
+ * `saveSession()` already knows how to write it.
+ *
+ * WHY THIS IS NOT `session/store.ts::writeSession()`: that function MOVES THE
+ * `--continue` POINTER and writes `meta`. An archive is not a session you continue;
+ * it is a record you resume BY PATH. Writing `meta` would also make the file look
+ * `aragon exec`-managed to `sessions list` / `prune`, which is the scoping rule
+ * `persist.ts` records at the top of `SessionMeta` - so a maintenance command would
+ * start deleting the user's cleared conversations.
+ *
+ * ISOLATION IS TWO DEEP (I-6 / P2-4). The directory is the first fence:
+ * `listSessions` / `pruneSessions` / `latestSessionForCwd` read `sessionsDir()`
+ * non-recursively and skip anything not ending in `.json` (`store.ts`), so a
+ * SUBDIRECTORY name is invisible to all three by construction. Omitting `meta` is
+ * the second fence, for the day someone makes that listing recursive or gives
+ * `--all` a wider meaning.
+ */
+import { mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { getLogger } from '../logging/logger.js';
+import { saveSession } from './persist.js';
+import { sessionsDir } from './store.js';
+/** Bounded retention: the newest N cleared conversations survive. */
+export const CLEAR_ARCHIVE_LIMITS = { maxArchives: 20 };
+/** `<sessions>/cleared` - a subdirectory, which is the first isolation fence. */
+const CLEARED_DIR_NAME = 'cleared';
+/** Every archive's filename starts with this, which is what `prune` selects on. */
+const ARCHIVE_PREFIX = 'cleared-';
+/**
+ * Best-effort archive of the conversation being cleared.
+ *
+ * @returns the absolute path of the written file, or `null` when there was
+ * nothing to save (an empty conversation) or the write failed. NEVER THROWS:
+ * a full disk must not be able to stop a user from starting a new conversation
+ * (I-5), and a caller that had to wrap this in `try` would eventually forget.
+ */
+export function archiveClearedConversation(input) {
+    // Clearing an empty conversation produces no file. Without this, every
+    // `/clear` on a fresh session would litter the directory with empty archives
+    // and push a real one out of the retention window.
+    if (input.messages.length === 0)
+        return null;
+    const dir = join(sessionsDir(), CLEARED_DIR_NAME);
+    const path = join(dir, `${archiveId(new Date())}.json`);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        getLogger().debug('agent', 'clear_archive_failed', { reason: reasonOf(err) });
+        return null;
+    }
+    // DEGRADE AND RETRY (P1-6 / C-8). `saveSession` VALIDATES the compaction
+    // identity and THROWS on a damaged or stale one, and an interrupted
+    // conversation - the one a user most wants back - is exactly the one most
+    // likely to carry a stale identity. Losing a whole conversation to an
+    // accessory field would break the only promise this module makes, so the
+    // second attempt drops it: `messages` is what makes the archive recoverable,
+    // the identity only lets the NEXT compaction reuse a prefix.
+    //
+    // The retry runs ONLY when there is an identity to drop. A disk that refused
+    // the first write will refuse an identical second one, so retrying without one
+    // would just double the log line and the wait without changing the outcome.
+    const wrote = writeArchive(path, input, true)
+        || (input.compactionIdentity !== undefined && writeArchive(path, input, false));
+    if (!wrote)
+        return null;
+    pruneArchives(dir);
+    return path;
+}
+/**
+ * One write attempt. `withIdentity` is the only difference between the first and
+ * the degraded second attempt, which is why it is a parameter rather than a
+ * duplicated body.
+ */
+function writeArchive(path, input, withIdentity) {
+    const identity = withIdentity ? input.compactionIdentity : undefined;
+    try {
+        saveSession(path, {
+            model: input.model,
+            messages: input.messages,
+            ...(identity ? { compactionIdentity: identity } : {}),
+            entries: input.entries,
+            todos: input.todos,
+        });
+        return true;
+    }
+    catch (err) {
+        getLogger().debug('agent', 'clear_archive_write_failed', {
+            withIdentity, reason: reasonOf(err),
+        });
+        return false;
+    }
+}
+/**
+ * Deterministic, collision-free id (P2-3).
+ *
+ * `cleared-<yyyyMMdd>-<HHmmss>-<pid>` is ASCII, matches `isValidSessionId`
+ * (`[A-Za-z0-9][A-Za-z0-9._-]*`), and is legible enough to type after
+ * `/resume `. The pid removes cross-process collisions; within one process a
+ * second `cleared-` file in the same second is unreachable because the FIRST
+ * clear leaves an empty conversation and `archiveClearedConversation` returns
+ * early on that. So no `-2`/`-3` suffix ladder is needed, and none is here.
+ */
+function archiveId(at) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const day = `${at.getFullYear()}${pad(at.getMonth() + 1)}${pad(at.getDate())}`;
+    const clock = `${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}`;
+    return `${ARCHIVE_PREFIX}${day}-${clock}-${process.pid}`;
+}
+/**
+ * Keep the newest `maxArchives` files; delete the rest.
+ *
+ * A sweep, not a scheduled job: retention that runs on the write path cannot be
+ * forgotten, and the failure mode of a missed sweep is bounded disk usage rather
+ * than unbounded. Every error here is swallowed on purpose - pruning is
+ * housekeeping and must never be able to fail a clear that already succeeded.
+ */
+function pruneArchives(dir) {
+    const survivors = [];
+    for (const name of safeReaddir(dir)) {
+        if (!name.startsWith(ARCHIVE_PREFIX) || !name.endsWith('.json'))
+            continue;
+        const path = join(dir, name);
+        try {
+            survivors.push({ path, modified: statSync(path).mtimeMs });
+        }
+        catch {
+            // A file that vanished between listing and stat is already deleted.
+        }
+    }
+    survivors.sort((a, b) => b.modified - a.modified);
+    for (const doomed of survivors.slice(CLEAR_ARCHIVE_LIMITS.maxArchives)) {
+        try {
+            unlinkSync(doomed.path);
+        }
+        catch (err) {
+            getLogger().debug('agent', 'clear_archive_prune_failed', { reason: reasonOf(err) });
+        }
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function reasonOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}