@aragon-agent/cli 0.6.39 → 0.6.42

package/dist/compaction/types.d.ts

@@ -55,6 +55,23 @@ export type CompactionMode = 'summarized' | 'truncated' | 'relieved' | 'none';
  * thing a CLI-local type is for.
  */
 export type CompactionUiTrigger = 'pressure' | 'overflow' | 'manual';
+/**
+ * Where one attempt currently is, so "compacting context" can also say WHAT it is
+ * doing for the forty-five seconds it is on screen.
+ *
+ * IT EXISTS BECAUSE THE GATES WERE INVISIBLE (context-compaction-never-fires
+ * RC-3). Planning and digesting both run BEFORE any model call, and both used to
+ * be able to reject while the only surface said `Context 95%` and nothing else.
+ * A phase is the CLI's answer to "is this stuck, or merely slow", and it is
+ * CLI-LOCAL for the reason the whole stream is: the engine has no phases, only a
+ * splice.
+ *
+ * THERE IS NO `settled` MEMBER, deliberately: the settle is already the
+ * `compaction_end` record. A phase restating it would give the card two ways to
+ * learn one fact, and the extra phase would race the record whenever the engine's
+ * verdict comes back first.
+ */
+export type CompactionPhase = 'planning' | 'digesting' | 'summarizing' | 'validating' | 'applying';
 /** Whether a figure was measured by the provider or estimated by us. */
 export type PressureSource = 'usage' | 'estimate';
 /** The exact occupancy evidence at the compaction checkpoint. */
@@ -183,6 +200,36 @@ export interface CompactionRecord {
     usage?: TokenUsage;
     /** Set when an overflow attempt halved `keepRecentTurns` for itself (D-24). */
     keepRecentTurnsUsed?: number;
+    /**
+     * Set when `planCompaction` had to relax `keepRecentTurns` to find a cut
+     * (context-compaction-never-fires B).
+     *
+     * DISCLOSED ON THE CARD, never silent: the relaxation trades "the last N turns
+     * are verbatim" for "compaction happens at all", and a user who is not told
+     * which side they got cannot tell a lossless compaction from a lossy one.
+     * `retainedTurns` and `retainedMessages` are what actually survived, so the card
+     * can state all three numbers instead of implying one.
+     */
+    keepRelaxed?: boolean;
+    retainedTurns?: number;
+    /**
+     * How many MESSAGES the relaxed cut left verbatim.
+     *
+     * `retainedTurns` COUNTS USER TURNS, and in the sessions this fix exists for - one
+     * prompt followed by a hundred tool calls - that number is zero even though forty
+     * messages survived word for word. A card reading "kept 0 recent turns" at that
+     * moment says the opposite of what happened, so both numbers are recorded.
+     */
+    retainedMessages?: number;
+    /**
+     * Messages left OUT of the digest text and therefore not quotable by the
+     * summarizer (context-compaction-never-fires A1).
+     *
+     * The elision is LOUD in three places: the digest text itself carries an
+     * `[elided ...]` marker, this field puts the count on the card, and the elided
+     * ids never enter the source map, so a delta citing one is rejected.
+     */
+    elidedMessages?: number;
     /**
      * Present ONLY when tail relief fired (hardening §3.3.4 / W2).
      *
@@ -221,14 +268,24 @@ export interface CompactionSnapshot {
     /** The summarizer's model id, or `''`. */
     model: string;
     /**
-     * How many compactions ANNOUNCED themselves (quiet-noop §6.2 / D-5).
+     * How many compactions ANNOUNCED themselves, i.e. how many cards the user saw.
      *
-     * COMPACTIONS THAT RAN, NOT CHECKPOINTS THAT FIRED. A `pressure` compaction
-     * that declines before calling a model or changing the history never advances
-     * this, which is what keeps the card's `#N` contiguous. `declined` below is
-     * the other half of the same total.
+     * IT COUNTS ATTEMPTS, NOT SPLICES (context-compaction-never-fires C). Before
+     * this change only attempts that committed to work announced, so this was
+     * "compactions that ran"; now every attempt opens a card - including the ones
+     * that decline at the planner or the digest - because a silent decline is
+     * indistinguishable from a dead feature, which is the bug this feature shipped
+     * with. `applied` below is the other half, and `/compact status` prints both.
      */
     compactions: number;
+    /**
+     * How many of those attempts actually replaced the history.
+     *
+     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE STAYS UNTOUCHED. Absent means
+     * "not reported", which `/compact status` renders exactly as the pre-change
+     * wording did.
+     */
+    applied?: number;
     /**
      * How many `pressure` checkpoints declined BEFORE committing to any work
      * (quiet-noop D-9 / P1-2).
@@ -260,19 +317,26 @@ export interface CompactionSnapshot {
 /**
  * THE COMPACTION EVENT STREAM.
  *
- * `compaction_start` and `compaction_end` are emitted ONLY for compactions that
- * COMMITTED TO WORK (quiet-noop §3.1): a `pressure` compaction that declines
- * before calling a model or changing the history emits NEITHER, and is
- * deliberately indistinguishable from a turn at which `shouldCompact` returned
- * false. `manual` and `overflow` always emit both.
+ * EVERY ATTEMPT ANNOUNCES ITSELF (context-compaction-never-fires C, which
+ * REVERSES quiet-noop §3.1). A `pressure` compaction used to reach
+ * `compaction_start` only after it committed to paid work, so an attempt that
+ * declined at the planner (`nothing_to_drop`) or at the digest budget produced
+ * no card at all - and a user sitting at 95 % with a dead auto-compaction had no
+ * way to learn that the feature was trying and failing 96 times. The card is now
+ * opened at the entry of `compact()` and ALWAYS settled, so `#N` counts attempts
+ * and the transcript carries one line per attempt, applied or not.
+ *
+ * WHY THE OLD DESIGN WAS DEFENSIBLE AND IS STILL WRONG. Its stated worry was a
+ * red `context not compacted` card every two turns flooding the transcript. The
+ * guards bound that to `stuckLimit` declines per run (`limits.ts`), and after
+ * them the auto path self-disables and says so once - so the flood never
+ * happens, while the silence happened every time.
  *
  * The pair is still BALANCED: every `compaction_start` is followed by exactly
  * one `compaction_end` (a `finally` in the engine guarantees the verdict, and
  * `settlePending` synthesizes a skeleton record when the compactor's own has not
- * arrived). Consumers that count PAIRS are unaffected; consumers that counted
- * ATTEMPTS must read `/compact status` or the JSONL diagnostic log instead -
- * CORE's own `compaction_start` / `compaction_end` pair still fires for every
- * attempt, declined or not, and that is the stream the log subscribes to.
+ * arrived). `phase` events land BETWEEN them, in order, and only for the live
+ * card.
  */
 export type CompactionEvent = {
     type: 'compaction_start';
@@ -282,6 +346,10 @@ export type CompactionEvent = {
 } | {
     type: 'compaction_end';
     record: CompactionRecord;
+} | {
+    type: 'phase';
+    index: number;
+    phase: CompactionPhase;
 } | ({
     type: 'usage';
     usage: TokenUsage;

package/dist/compaction/wiring.d.ts

@@ -27,14 +27,19 @@ import type { CompactionIdentity } from './memory-identity.js';
  * `/compact off`, `/compact threshold 0.8` and a settings-screen save take effect
  * mid-session without touching the `Agent`.
  *
- * DECLINED COMPACTIONS PRODUCE NO CLI EVENTS (quiet-noop §3.6). A `pressure`
- * compaction that changed nothing, called nothing and spent nothing never emits
- * `compaction_start`, so `onCompactorEvent` never opens a card and `settlePending`
- * finds neither a held record nor a skeleton to synthesize. CORE still emits its
- * own pair for every attempt, which is why `settlePending` still runs - it just
- * refreshes the snapshot and returns. `onCompactorEvent`'s `if (!this.open)`
- * guard is now unreachable for declines and stays for the abort race it was
- * written for.
+ * DECLINED COMPACTIONS ARE VISIBLE (context-compaction-never-fires C, which
+ * REVERSES quiet-noop §3.6). A `pressure` compaction that changes nothing used to
+ * emit no `compaction_start`, so `onCompactorEvent` never opened a card and the
+ * only trace of an attempt was a counter in `/compact status`. The compactor now
+ * announces at the entry of `compact()` and always settles, so this class holds a
+ * record for every attempt and `settlePending` emits it - declined attempts
+ * included, with the reason on the card.
+ *
+ * WHAT THE OLD RULE PROTECTED IS STILL PROTECTED, by a different mechanism: the
+ * transcript cannot flood, because `maxPerRun` (5) and `stuckLimit` (2) bound the
+ * attempts and the auto path self-disables and says so once. `onCompactorEvent`'s
+ * `if (!this.open)` guard is still load-bearing: it is what stops a late record
+ * from re-opening a card the engine's verdict already closed.
  */
 import type { ModelRole } from '../config/model-profiles.js';
 import { type AgentEvent, type ContextManager, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ProviderRegistryOptions, type TokenUsage } from '@aragon-agent/core';

package/dist/compaction/wiring.js

@@ -368,6 +368,7 @@ export class CompactionWiring {
             live: this.enabled && summarizer !== null,
             model: summarizer?.ref.modelId ?? '',
             compactions: totals.compactions,
+            applied: totals.applied,
             // OMITTED WHEN ZERO (quiet-noop D-9), so a healthy session's snapshot is
             // shaped exactly as it was before this feature and `/compact status` has
             // nothing extra to render.

package/dist/config/load.js

@@ -7,7 +7,7 @@
  */
 import process from 'node:process';
 import { JOB_WAIT_MARGIN_MS } from '../proc/limits.js';
-import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
+import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, legacyTeamFanoutPatch, LEGACY_TEAM_FANOUT_DEFAULTS, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile, updatePersistedConfig } from './store.js';
 import { projectModelProfiles, resolveModelProfileState, resolveModelRoleKey, } from './model-profile-resolution.js';
@@ -517,6 +517,49 @@ function migrateLegacyTeamCeilings(raw) {
         keys: Object.keys(patch).join(','),
     });
 }
+/**
+ * Rewrite the cli<=0.6.x persisted fan-out defaults (5 / 3) to the new ones
+ * (8 / 8) and persist the change (subagent-fanout D-3 / D-4).
+ *
+ * ONE-SHOT and IDEMPOTENT, and the FILE LAYER ONLY, for the reasons
+ * `migrateLegacyTeamCeilings` records one block above: env (`ARAGON_TEAM_MAX`)
+ * and `--team-max` are THIS launch's intent and are never rewritten, the raw
+ * file object is patched IN PLACE so the `file` layer resolved below already
+ * reads 8/8, and a failed write leaves the marker absent so the next launch
+ * retries the whole migration.
+ *
+ * WHY A MARKER AND NOT JUST THE NUMBERS: `fanoutMigrated` is what keeps a user
+ * who deliberately returns to 5/3 from being migrated again on every launch
+ * (`legacyTeamFanoutPatch` returns `null` once it is set). The price of
+ * exact-equality is that one deliberate 5/3 is widened once; the marker bounds
+ * that to at most once.
+ */
+function migrateLegacyTeamFanout(raw) {
+    const patch = legacyTeamFanoutPatch(raw?.team);
+    if (patch === null)
+        return;
+    // READ THE STARTING POINT BEFORE THE IN-PLACE PATCH, and never hardcode
+    // `5/3`: rule 4 of the matcher accepts an ABSENT `maxConcurrent`, in which
+    // case the honest starting point is "unset" - a log line the user cannot find
+    // on disk is worse than no log line.
+    const from = `${LEGACY_TEAM_FANOUT_DEFAULTS.maxSubagents}/${raw?.team?.maxConcurrent ?? 'unset'}`;
+    // THE FULL SECTION, not the bare patch: the write port types `team` as a
+    // whole `TeamConfig`, and the section the file already carries plus the three
+    // keys IS the section we want on disk.
+    const migratedTeam = { ...raw.team, ...patch };
+    Object.assign(raw.team, patch);
+    try {
+        updatePersistedConfig({ team: migratedTeam });
+    }
+    catch {
+        // Unwritable config dir: in-memory values are already migrated; retry next
+        // launch (idempotent, because the marker never made it to disk).
+    }
+    getLogger().warn('config', 'team_fanout_migrated', {
+        from,
+        to: `${patch.maxSubagents}/${patch.maxConcurrent}`,
+    });
+}
 /**
  * Resolve the effective config by merging all layers, then derive the runtime
  * (non-persisted) fields and enforce the timeout invariant.
@@ -527,6 +570,12 @@ export function loadConfig(flags = {}, options = {}) {
     loadDotenv(cwd);
     const read = readConfigFile();
     migrateLegacyTeamCeilings(read.config);
+    // THE NEXT LINE, not a shared pass: the two migrations are independent, and
+    // keeping them as two statements keeps each one's "returns null when nothing
+    // matches" contract visible. Both run BEFORE `projectModelProfiles` for the
+    // same reason - the `file` layer resolved below must already read the migrated
+    // numbers, and neither migration needs a second projection path.
+    migrateLegacyTeamFanout(read.config);
     const projection = projectModelProfiles(read.config ?? {});
     const file = projection.file;
     const env = readEnvConfig();
@@ -570,7 +619,6 @@ export function loadConfig(flags = {}, options = {}) {
     // a config file that turned plan mode on.
     const startInPlanMode = pick(flags.plan, env.partial.planModeDefault, file.planModeDefault) ??
         DEFAULT_CONFIG.planModeDefault;
-    const planModeMaxAskRounds = clampAskRounds(file.planModeMaxAskRounds, DEFAULT_CONFIG.planModeMaxAskRounds);
     const planModeHumanTimeoutMs = clampHumanTimeout(file.planModeHumanTimeoutMs, DEFAULT_CONFIG.planModeHumanTimeoutMs);
     const toolTimeoutMs = coercePositiveInt(pick(flags.toolTimeout, file.toolTimeoutMs), DEFAULT_CONFIG.toolTimeoutMs);
     // THE `jobs` SECTION IS RESOLVED HERE, ABOVE THE TIMEOUT BLOCK, and the
@@ -706,7 +754,6 @@ export function loadConfig(flags = {}, options = {}) {
         // From `<home>/state.json`, not the config file — see `ui-state.ts`.
         submitCount: readSubmitCount(),
         startInPlanMode,
-        planModeMaxAskRounds,
         planModeHumanTimeoutMs,
         skills,
         skillsRuntime: {

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

@@ -70,7 +70,8 @@ export declare const KIT_LIMITS: {
  * exactly as it is for `team.modelProfileId` (`schema.ts` clampTeamConfig):
  * `createModelProfileState` blanks the whole settings page when validation
  * fails, so promoting "a hand-edited file left one dangling id" into "the page
- * and `/team model` are both dead" is a wildly disproportionate blast radius.
+ * and the `Subagent model` row are both dead" is a wildly disproportionate blast
+ * radius.
  *
  * `duplicate_name` is deliberately NOT a code: two kits may share a name
  * (§6.6), and `/kit use` disambiguates with an `#id` prefix.

package/dist/config/schema.d.ts

@@ -206,15 +206,15 @@ export declare const DEFAULT_SCROLL_RESUME_MS = 5000;
  * Exactly the trap `retry.maxRetries` needed this helper for.
  */
 export declare function clampScrollResumeMs(v: unknown, fallback: number): number;
-/** `ask_user` calls allowed per user turn. */
-export declare const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
 /**
  * Ceiling on ONE human wait, in ms. Thirty minutes is far outside "the user
  * went to get coffee", but a ceiling has to exist: an unattended terminal must
  * not wedge a CI job or a stale ssh session forever.
+ *
+ * THIS IS NOT A ROUND LIMIT and the distinction matters. It bounds a single wait
+ * (liveness); it says nothing about how many times the model may ask.
  */
 export declare const DEFAULT_PLAN_HUMAN_TIMEOUT_MS = 1800000;
-export declare function clampAskRounds(v: unknown, fallback: number): number;
 export declare function clampHumanTimeout(v: unknown, fallback: number): number;
 export interface SkillsConfig {
     enabled: boolean;
@@ -259,6 +259,18 @@ export interface SkillsConfig {
      * just be a second decorative field.
      */
     toolPolicy: SkillsToolPolicyMode;
+    /**
+     * Automatic skill triage (skill-triage-and-unbounded-ask §4.2.9): compute a
+     * short candidate list for each new task and put it in the system prompt, so
+     * "is a skill applicable?" becomes a question the protocol forces the model to
+     * answer rather than one it has to remember to ask.
+     *
+     * DEFAULT ON, and OFF must be byte-identical to the pre-feature prompt. That is
+     * what the block's conditional splice in `buildSystemPrompt` guarantees
+     * (invariant I-T1) — a permanently-on block would be a prompt change nobody
+     * could turn off.
+     */
+    triage: boolean;
 }
 export declare const SKILLS_INTEGRITY_MODES: readonly ["off", "warn", "strict"];
 export type SkillsIntegrityMode = (typeof SKILLS_INTEGRITY_MODES)[number];
@@ -343,6 +355,16 @@ export interface TeamConfig {
      * failed subagent.
      */
     maxConcurrent: number;
+    /**
+     * The one-shot marker `migrateLegacyTeamFanout` writes (subagent-fanout
+     * D-3), and NOTHING else may ever write it.
+     *
+     * It exists because the fan-out default moved 5/3 -> 8/8 while every save
+     * materializes the whole section: without a marker, a user who deliberately
+     * returns to 5/3 is migrated back to 8/8 on the next launch, for ever. Absent
+     * means "not yet migrated"; it is never written as `false`.
+     */
+    fanoutMigrated?: boolean;
     /**
      * One child's wall clock before its own abort. `0` (the default) means NO
      * ceiling: a subagent runs until it finishes or is aborted, exactly like
@@ -465,6 +487,40 @@ export declare const LEGACY_TEAM_CEILING_DEFAULTS: Readonly<{
  * equality test lives beside the constants it reads.
  */
 export declare function legacyTeamCeilingPatch(raw: unknown): Partial<TeamConfig> | null;
+/**
+ * The fan-out defaults cli <= 0.6.x persisted as its OWN defaults
+ * (subagent-fanout F-2 / R-1).
+ *
+ * THE SAME TRAP AS THE CEILINGS ABOVE, ONE SECTION OVER. `mergePersistedConfig`
+ * writes the WHOLE `team` section on every save, so a user who has ever touched
+ * any setting carries this exact pair in `config.json` - changing
+ * `DEFAULT_TEAM_CONFIG` alone would never reach them, and they would keep
+ * seeing "only 3 subagents at once" for ever.
+ */
+export declare const LEGACY_TEAM_FANOUT_DEFAULTS: {
+    readonly maxSubagents: 5;
+    readonly maxConcurrent: 3;
+};
+/**
+ * The `{ maxSubagents, maxConcurrent, fanoutMigrated }` patch for the legacy
+ * default pair, or `null` when nothing matches (subagent-fanout D-3).
+ *
+ * EXACT-EQUALITY ONLY, the rule `legacyTeamCeilingPatch` records: a value that
+ * differs was a deliberate user choice and survives untouched. Two differences
+ * from that function, both deliberate:
+ *
+ *  - `fanoutMigrated: true` short-circuits to `null`. That is what makes "the
+ *    user changed their mind and went back to 5/3" stick: without it the next
+ *    launch would migrate them again, every launch, for ever.
+ *  - `maxConcurrent` is allowed to be ABSENT as well as 3, because a
+ *    hand-written section may name only one key and a half-written pair is
+ *    still the legacy intent, not a user decision.
+ *
+ * Pure on purpose: `loadConfig` decides WHERE the patch is applied and
+ * persisted; this function only answers WHICH keys match, so the equality test
+ * lives beside the constants it reads.
+ */
+export declare function legacyTeamFanoutPatch(raw: unknown): Partial<TeamConfig> | null;
 export interface TodoConfig {
     /** Register `todo_write` at all. Default TRUE. */
     enabled: boolean;
@@ -1064,8 +1120,6 @@ export interface PersistedConfig {
     scrollResumeMs: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
     planModeDefault: boolean;
-    /** `ask_user` rounds allowed per user turn; clamped to [1, 10]. */
-    planModeMaxAskRounds: number;
     /** Ceiling on a single human wait in ms; clamped to [60_000, 7_200_000]. */
     planModeHumanTimeoutMs: number;
     /** Skill system settings. The SECOND nested object in this file after apiKeys. */
@@ -1118,6 +1172,29 @@ export declare const LEGACY_STATE_KEYS: readonly ["promptHistory", "submitCount"
  * one door for both directions.
  */
 export declare function stripLegacyStateKeys<T extends object>(raw: T): T;
+/**
+ * Config keys whose MEANING was removed, mapped to the explanation a user gets if
+ * they still try to set one.
+ *
+ * SEPARATE FROM `LEGACY_STATE_KEYS`, because the disposition differs: those keys'
+ * values were MOVED somewhere else, while these have nowhere to go — the feature
+ * they configured no longer exists. Merging the two lists would erase that
+ * difference at exactly the moment someone is reading the file to find out what
+ * happened to their setting.
+ *
+ * Stripped on the READ side for the same reason `stripLegacyStateKeys` is:
+ * `loadPersistedConfig()` merges `{ ...DEFAULT_CONFIG, ...partial }`, so a key
+ * left on disk rides that spread into memory and `updatePersistedConfig` writes it
+ * straight back. The user deletes the line, launches once, and watches it return.
+ */
+export declare const RETIRED_CONFIG_KEYS: Readonly<Record<string, string>>;
+/**
+ * THE single gate that keeps retired keys out of `config.json`. Applied on the
+ * read side, so it is self-healing: every write is read-strip-merge-write, and a
+ * hand-edited file, a downgrade to an older CLI and back, or a half-finished
+ * migration all converge on a clean file at the next write.
+ */
+export declare function stripRetiredConfigKeys<T extends object>(raw: T): T;
 export interface CliConfig {
     /** A committed model snapshot failed to apply; no further requests may start. */
     modelSettingsRestartRequired?: boolean;
@@ -1312,7 +1389,6 @@ export interface CliConfig {
      * live mode from here on belongs to the controller.
      */
     startInPlanMode: boolean;
-    planModeMaxAskRounds: number;
     planModeHumanTimeoutMs: number;
     skills: SkillsConfig;
     /** Flag/env-only skill switches for this run (§7.5). Never persisted. */

package/dist/config/schema.js

@@ -273,20 +273,23 @@ export function clampScrollResumeMs(v, fallback) {
 // nested-object merge is hand-written and capped at one level; three scalars do
 // not justify a second `clampXConfig` gate plus two more merge sites, and flat
 // keys mean `store.ts` needs ZERO changes.
+//
+// ONE OF THOSE KEYS IS GONE: `planModeMaxAskRounds` capped `ask_user` at four
+// rounds per turn. There is no cap any more, so there is no number to store, no
+// range to clamp and nothing to configure. It is retired through
+// `RETIRED_CONFIG_KEYS` below rather than defaulted to a large number — a
+// ninety-nine in the config file is the same second source of truth as a four.
 // ---------------------------------------------------------------------------
-/** `ask_user` calls allowed per user turn. */
-export const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
-const ASK_ROUNDS_RANGE = { min: 1, max: 10 };
 /**
  * Ceiling on ONE human wait, in ms. Thirty minutes is far outside "the user
  * went to get coffee", but a ceiling has to exist: an unattended terminal must
  * not wedge a CI job or a stale ssh session forever.
+ *
+ * THIS IS NOT A ROUND LIMIT and the distinction matters. It bounds a single wait
+ * (liveness); it says nothing about how many times the model may ask.
  */
 export const DEFAULT_PLAN_HUMAN_TIMEOUT_MS = 1_800_000;
 const HUMAN_TIMEOUT_RANGE = { min: 60_000, max: 7_200_000 };
-export function clampAskRounds(v, fallback) {
-    return clampInt(v, fallback, ASK_ROUNDS_RANGE);
-}
 export function clampHumanTimeout(v, fallback) {
     return clampInt(v, fallback, HUMAN_TIMEOUT_RANGE);
 }
@@ -322,6 +325,9 @@ export const DEFAULT_SKILLS_CONFIG = {
     integrity: 'warn',
     usageTracking: true,
     toolPolicy: 'enforce',
+    // ON by default: the capability this key controls is the feature's whole point,
+    // and it costs zero model calls (local matching over in-memory records).
+    triage: true,
 };
 const CATALOG_BYTES_RANGE = { min: 500, max: 40_000 };
 /**
@@ -406,6 +412,7 @@ export function clampSkillsConfig(raw) {
         integrity: clampSkillsIntegrity(src.integrity, DEFAULT_SKILLS_CONFIG.integrity),
         usageTracking: bool(src.usageTracking, DEFAULT_SKILLS_CONFIG.usageTracking),
         toolPolicy: clampSkillsToolPolicy(src.toolPolicy, DEFAULT_SKILLS_CONFIG.toolPolicy),
+        triage: bool(src.triage, DEFAULT_SKILLS_CONFIG.triage),
     };
 }
 export const DEFAULT_SKILLS_RUNTIME = { forcedSkills: [], approveAll: false };
@@ -474,8 +481,12 @@ export function clampLogConfig(raw) {
 export const HARD_MAX_SUBAGENTS = TEAM_LIMITS.hardMaxSubagents;
 export const DEFAULT_TEAM_CONFIG = {
     enabled: true,
-    maxSubagents: 5,
-    maxConcurrent: 3,
+    // 8 IS THE DEFAULT, 10 IS THE CEILING, and they are not the same number
+    // (subagent-fanout D-1 / D-2). `maxConcurrent` moves WITH `maxSubagents`
+    // because a wider population behind a 3-wide pool shows the user nothing:
+    // children 4..8 simply queue (`team-bus.test.ts` records the queued phase).
+    maxSubagents: 8,
+    maxConcurrent: 8,
     // 0 = NO LIMIT. Subagents run under the same regime as the lead: no
     // wall clock, no turn cap; only the idle watchdog and the user's Esc.
     subagentTimeoutMs: 0,
@@ -534,6 +545,13 @@ export function clampTeamConfig(raw) {
             && [...src.modelProfileId].length <= 128
             ? src.modelProfileId
             : null,
+        // TRANSPARENT, and only ever `true` (subagent-fanout D-3 / R-6). The flag is
+        // not a setting: it is the one-shot marker the migration leaves behind, so a
+        // clamp that dropped it would re-migrate the user on every launch. Written
+        // as a spread rather than `=== true ? true : undefined` so the key stays
+        // ABSENT (not `undefined`) in the clamped result - `toEqual(DEFAULT_TEAM_CONFIG)`
+        // and the on-disk shape both depend on that.
+        ...(src.fanoutMigrated === true ? { fanoutMigrated: true } : {}),
     };
 }
 /**
@@ -574,6 +592,56 @@ export function legacyTeamCeilingPatch(raw) {
     }
     return matched ? patch : null;
 }
+/**
+ * The fan-out defaults cli <= 0.6.x persisted as its OWN defaults
+ * (subagent-fanout F-2 / R-1).
+ *
+ * THE SAME TRAP AS THE CEILINGS ABOVE, ONE SECTION OVER. `mergePersistedConfig`
+ * writes the WHOLE `team` section on every save, so a user who has ever touched
+ * any setting carries this exact pair in `config.json` - changing
+ * `DEFAULT_TEAM_CONFIG` alone would never reach them, and they would keep
+ * seeing "only 3 subagents at once" for ever.
+ */
+export const LEGACY_TEAM_FANOUT_DEFAULTS = {
+    maxSubagents: 5,
+    maxConcurrent: 3,
+};
+/**
+ * The `{ maxSubagents, maxConcurrent, fanoutMigrated }` patch for the legacy
+ * default pair, or `null` when nothing matches (subagent-fanout D-3).
+ *
+ * EXACT-EQUALITY ONLY, the rule `legacyTeamCeilingPatch` records: a value that
+ * differs was a deliberate user choice and survives untouched. Two differences
+ * from that function, both deliberate:
+ *
+ *  - `fanoutMigrated: true` short-circuits to `null`. That is what makes "the
+ *    user changed their mind and went back to 5/3" stick: without it the next
+ *    launch would migrate them again, every launch, for ever.
+ *  - `maxConcurrent` is allowed to be ABSENT as well as 3, because a
+ *    hand-written section may name only one key and a half-written pair is
+ *    still the legacy intent, not a user decision.
+ *
+ * Pure on purpose: `loadConfig` decides WHERE the patch is applied and
+ * persisted; this function only answers WHICH keys match, so the equality test
+ * lives beside the constants it reads.
+ */
+export function legacyTeamFanoutPatch(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const src = raw;
+    if (src.fanoutMigrated === true)
+        return null;
+    if (src.maxSubagents !== LEGACY_TEAM_FANOUT_DEFAULTS.maxSubagents)
+        return null;
+    if (src.maxConcurrent !== undefined
+        && src.maxConcurrent !== LEGACY_TEAM_FANOUT_DEFAULTS.maxConcurrent)
+        return null;
+    return {
+        maxSubagents: DEFAULT_TEAM_CONFIG.maxSubagents,
+        maxConcurrent: DEFAULT_TEAM_CONFIG.maxConcurrent,
+        fanoutMigrated: true,
+    };
+}
 export const DEFAULT_TODO_CONFIG = {
     enabled: true,
     panel: true,
@@ -1069,7 +1137,6 @@ export const DEFAULT_CONFIG = {
     keyboardEnhancement: true,
     scrollResumeMs: DEFAULT_SCROLL_RESUME_MS,
     planModeDefault: false,
-    planModeMaxAskRounds: DEFAULT_PLAN_MAX_ASK_ROUNDS,
     planModeHumanTimeoutMs: DEFAULT_PLAN_HUMAN_TIMEOUT_MS,
     skills: DEFAULT_SKILLS_CONFIG,
     log: DEFAULT_LOG_CONFIG,
@@ -1162,6 +1229,37 @@ export function stripLegacyStateKeys(raw) {
         delete out[key];
     return out;
 }
+/**
+ * Config keys whose MEANING was removed, mapped to the explanation a user gets if
+ * they still try to set one.
+ *
+ * SEPARATE FROM `LEGACY_STATE_KEYS`, because the disposition differs: those keys'
+ * values were MOVED somewhere else, while these have nowhere to go — the feature
+ * they configured no longer exists. Merging the two lists would erase that
+ * difference at exactly the moment someone is reading the file to find out what
+ * happened to their setting.
+ *
+ * Stripped on the READ side for the same reason `stripLegacyStateKeys` is:
+ * `loadPersistedConfig()` merges `{ ...DEFAULT_CONFIG, ...partial }`, so a key
+ * left on disk rides that spread into memory and `updatePersistedConfig` writes it
+ * straight back. The user deletes the line, launches once, and watches it return.
+ */
+export const RETIRED_CONFIG_KEYS = {
+    planModeMaxAskRounds: 'ask_user has no round limit any more, so this key is gone. Nothing to set; ' +
+        'the next config write removes it from config.json.',
+};
+/**
+ * THE single gate that keeps retired keys out of `config.json`. Applied on the
+ * read side, so it is self-healing: every write is read-strip-merge-write, and a
+ * hand-edited file, a downgrade to an older CLI and back, or a half-finished
+ * migration all converge on a clean file at the next write.
+ */
+export function stripRetiredConfigKeys(raw) {
+    const out = { ...raw };
+    for (const key of Object.keys(RETIRED_CONFIG_KEYS))
+        delete out[key];
+    return out;
+}
 // ---------------------------------------------------------------------------
 // Coercion / validation helpers
 // ---------------------------------------------------------------------------

package/dist/config/store.js

@@ -17,7 +17,7 @@ import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerProfileSecrets, registerSecretsFrom } from '../logging/secret-registry.js';
 import { adaptLegacyConnectionPatch, ModelProfileConfigError, readModelSettingsDisk } from './model-profile-store.js';
 import { normalizeModelProfiles } from './model-profiles.js';
-import { clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, stripRetiredConfigKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -124,7 +124,12 @@ export function normalizePersistedConfig(input) {
     // on disk would otherwise ride the spread into `merged` and be written back
     // out by `updatePersistedConfig` — the "I deleted it and it grew back" bug
     // that `stripLegacyStateKeys` exists to make impossible (§4.5).
-    const partial = stripLegacyStateKeys(input);
+    //
+    // TWO PASSES, DELIBERATELY: `stripLegacyStateKeys` handles keys whose value
+    // MOVED, `stripRetiredConfigKeys` handles keys whose FEATURE was removed
+    // (`planModeMaxAskRounds`). Same door, different reasons, and each list keeps
+    // growing on its own schedule.
+    const partial = stripRetiredConfigKeys(stripLegacyStateKeys(input));
     delete partial.fullscreen;
     return {
         ...DEFAULT_CONFIG,
@@ -268,8 +273,9 @@ export function mergePersistedConfig(current, patch) {
         // replace the whole section and quietly revert `maxFiles`, `previewChars`
         // and — worst of all — `redactSecrets`.
         log: clampLogConfig({ ...current.log, ...(patch.log ?? {}) }),
-        // The fourth section, and it needs the merge for the same reason: `/team max
-        // 4` sends `{ team: { maxSubagents: 4 } }`, which a shallow spread would
+        // The fourth section, and it needs the merge for the same reason: the settings
+        // `Max subagents` row sends `{ team: { maxSubagents: 4 } }`, which a shallow
+        // spread would
         // turn into "changing the fan-out width silently reverted every timeout".
         team: clampTeamConfig({ ...current.team, ...(patch.team ?? {}) }),
         // The fifth section, and its omission is the worst of the five (P0-1):