@aragon-agent/cli 0.6.39 → 0.6.42

package/dist/commands/skills.js

@@ -12,6 +12,7 @@ import { checkManifest } from '../skills/manifest.js';
 import { updateAllSkills, updateSkill, isHardFailure } from '../skills/updater.js';
 import { currentPlatform } from '../skills/node-host.js';
 import { listUsage, resetUsage, getUsagePath } from '../skills/usage.js';
+import { SKILL_TRIAGE_LIMITS } from '../skills/triage.js';
 import { HOST_TOOL_NAMES, SKILL_TOOL_FLOOR } from '../tools/index.js';
 import { SKILLS_TOOL_POLICY_MODES, isSkillsToolPolicyMode } from '../config/schema.js';
 import { pickGlyphs } from '../ui/glyphs.js';
@@ -92,12 +93,96 @@ async function runSkills(ctx, service, version) {
             return unloadFrames(ctx, service);
         case 'usage':
             return usageFromCommand(ctx, service, argument);
+        case 'triage':
+            return triageFromCommand(ctx, service, argument);
+        case 'route':
+            return routeFromCommand(ctx, service, argument);
         default:
             ctx.notify('warn', `Unknown subcommand "/skills ${sub}". Try: list, info, install, update, remove, enable, ` +
-                'disable, reload, create, trust, untrust, policy, unload, usage.');
+                'disable, reload, create, trust, untrust, policy, unload, usage, triage, route.');
     }
 }
 // ---------------------------------------------------------------------------
+// /skills triage · route  (skill-triage-and-unbounded-ask §4.2.8)
+// ---------------------------------------------------------------------------
+/**
+ * `/skills triage [on|off]`.
+ *
+ * The report names the switch AND the last turn's result, because "on" alone does
+ * not answer the question a user actually has, which is "is it finding anything?".
+ * `lastSkillRouting` comes from the controller — it is per-turn session state, not
+ * skill-service state, and the service must not start owning a copy of it.
+ */
+function triageFromCommand(ctx, service, argument) {
+    const requested = argument.trim().toLowerCase();
+    if (requested.length === 0) {
+        const on = service.getConfig().triage === true;
+        const last = ctx.controller.getSkillRouting();
+        const summary = last === null
+            ? 'No turn has been triaged yet.'
+            : last.candidates.length === 0
+                ? `Last turn: no candidate (${last.eligible} eligible skill(s) scored).`
+                : `Last turn: ${last.candidates.length} candidate(s), best ${last.candidates[0].name} (${last.candidates[0].score}).`;
+        ctx.notify('info', `Skill triage: ${on ? 'on' : 'off'}. ${summary}`);
+        return;
+    }
+    if (requested !== 'on' && requested !== 'off') {
+        ctx.notify('warn', `Unknown argument "${argument}" - use /skills triage [on|off].`);
+        return;
+    }
+    const enabled = requested === 'on';
+    // `setTriageEnabled` persists AND fires `onChange`, which rebuilds the prompt in
+    // this session. Without that second half the switch would look applied and take
+    // effect only after a restart (AC-T23).
+    service.setTriageEnabled(enabled);
+    // A toast, not a transcript notice: flipping a switch is an acknowledgement, and
+    // `toast` is this package's channel for exactly that (see `toggleSkill`). The
+    // level still differs by direction, so "off" does not read as a win.
+    ctx.toast(enabled ? 'success' : 'info', `Skill triage: ${enabled ? 'on' : 'off'}. ` +
+        (enabled
+            ? 'Each new task gets a short candidate list.'
+            : 'The system prompt no longer carries the triage block.'));
+}
+/**
+ * `/skills route [text]`.
+ *
+ * Two modes, one output shape. With text it routes that text; without text it
+ * replays the previous turn's real routing, which is the case a user is most often
+ * in — they just watched the model ignore a suggestion. The "never triaged" text
+ * names the form that works instead of leaving them to guess.
+ */
+function routeFromCommand(ctx, service, argument) {
+    const task = argument.trim();
+    if (task.length === 0) {
+        const last = ctx.controller.getSkillRouting();
+        if (last === null) {
+            ctx.notify('info', 'No turn has been triaged yet. Run /skills route <text> to try one.');
+            return;
+        }
+        ctx.notify('info', renderRoutingReport(last));
+        return;
+    }
+    // A fresh computation, NOT the cached one: `/skills route <text>` is how a user
+    // tests whether a phrasing would have matched.
+    ctx.notify('info', renderRoutingReport(service.route(task)));
+}
+/** One `info` notification, one line per candidate, ASCII only (`commands/`). */
+function renderRoutingReport(report) {
+    if (report.candidates.length === 0) {
+        const close = report.topUnqualified === null
+            ? ''
+            : ` Closest was ${report.topUnqualified.name} (${report.topUnqualified.score}); ` +
+                `the threshold is ${SKILL_TRIAGE_LIMITS.minScore}.`;
+        return (`No skill matched "${report.task}". The catalog has ${report.eligible} eligible skills.` +
+            close);
+    }
+    const lines = report.candidates.map((candidate) => {
+        const reasons = candidate.reasons.length > 0 ? candidate.reasons.join('+') : 'none';
+        return `${candidate.name} (${candidate.scope}) score ${candidate.score} [${reasons}]`;
+    });
+    return [`Routed "${report.task}" (${report.tokenCount} token(s)):`, ...lines].join('\n');
+}
+// ---------------------------------------------------------------------------
 // /skills policy · unload · usage  (§5.5 / §9)
 // ---------------------------------------------------------------------------
 /**

package/dist/commands/subagent-command.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `/subagent`: a DEPRECATED ALIAS of `/team` (team-command-forced-dispatch
+ * §3.10 / D-12 / I-8).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY IT STILL EXISTS. It shipped, it is in five places in the README, and it is
+ * in the muscle memory of everyone who used the forced fan-out before `/team`
+ * grew its meaning. Removing the name would be a breaking change that buys
+ * nothing the alias does not buy for one `toast`.
+ *
+ * WHY IT HAS NO BODY. `subagent-fanout-and-forced-dispatch` implemented the
+ * whole grammar - control words, two ceilings, four parse errors, plan-mode
+ * disclosure - and every one of those bytes is now `/team`'s. A second copy here
+ * would drift on the first refinement, and the drift would be invisible: both
+ * commands would keep working, one of them would quietly be the old one. The
+ * file therefore holds ONE delegation and one line of deprecation text, and
+ * `subagent-command.test.ts` asserts both (I-8).
+ */
+import type { CommandContext, CommandRegistry } from './registry.js';
+/**
+ * Run `/team`, having first said out loud that this is the same thing.
+ *
+ * THE TOAST COMES FIRST ON PURPOSE: it is one ephemeral line above whatever
+ * `/team` prints, so the sequence reads "you used the old name; here is the
+ * answer" rather than a full answer followed by a correction nobody notices.
+ */
+export declare function runSubagentCommand(ctx: CommandContext): void;
+/** Registered from `builtins.ts`: the name, and nothing else, lives here. */
+export declare function registerSubagentCommand(registry: CommandRegistry): void;

package/dist/commands/subagent-command.js

@@ -0,0 +1,39 @@
+/**
+ * `/subagent`: a DEPRECATED ALIAS of `/team` (team-command-forced-dispatch
+ * §3.10 / D-12 / I-8).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY IT STILL EXISTS. It shipped, it is in five places in the README, and it is
+ * in the muscle memory of everyone who used the forced fan-out before `/team`
+ * grew its meaning. Removing the name would be a breaking change that buys
+ * nothing the alias does not buy for one `toast`.
+ *
+ * WHY IT HAS NO BODY. `subagent-fanout-and-forced-dispatch` implemented the
+ * whole grammar - control words, two ceilings, four parse errors, plan-mode
+ * disclosure - and every one of those bytes is now `/team`'s. A second copy here
+ * would drift on the first refinement, and the drift would be invisible: both
+ * commands would keep working, one of them would quietly be the old one. The
+ * file therefore holds ONE delegation and one line of deprecation text, and
+ * `subagent-command.test.ts` asserts both (I-8).
+ */
+import { runTeamCommand } from './team-command.js';
+/**
+ * Run `/team`, having first said out loud that this is the same thing.
+ *
+ * THE TOAST COMES FIRST ON PURPOSE: it is one ephemeral line above whatever
+ * `/team` prints, so the sequence reads "you used the old name; here is the
+ * answer" rather than a full answer followed by a correction nobody notices.
+ */
+export function runSubagentCommand(ctx) {
+    ctx.toast('info', '/subagent is now /team - same arguments.');
+    runTeamCommand(ctx);
+}
+/** Registered from `builtins.ts`: the name, and nothing else, lives here. */
+export function registerSubagentCommand(registry) {
+    registry.register({
+        name: 'subagent',
+        description: 'Deprecated alias of /team - same arguments',
+        run: (ctx) => { runSubagentCommand(ctx); },
+    });
+}

package/dist/commands/team-command.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `/team`: force the session into team mode and start work, or leave it
+ * (team-command-forced-dispatch §3.3 / §3.4 / §5.1).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHAT THIS COMMAND IS. `/team <brief>` parses the user's intent, ARMS a
+ * session-level forced mode and submits ONE normal user turn. The lead analyses
+ * and plans that turn and then has to call `task` - three layers say so: the
+ * directive it is handed, the `<forced_team_mode>` block in every later system
+ * prompt, and the mechanical gate in `ui/App.tsx` that nudges once if a whole
+ * turn went by without a dispatch. This command never dispatches itself (I-1):
+ * Esc, the watchdog, the report, spend accounting and the concurrency lock all
+ * stay on the one path that already has them.
+ *
+ * WHAT IT IS NOT ANY MORE. It used to be the CONFIG command - `status | on | off
+ * | max <n> | overseer on|off | model <name>`. All five verbs now live in the
+ * settings screen (`Settings > Team`, plus the root `Subagent model` row), and
+ * this command writes not one byte of `config.json` (I-4). The reason is the one
+ * the requirement names: a command that both changes configuration and starts
+ * work leaves the user unable to predict what it did. `on` and `off` survive as
+ * SESSION CONTROL words - a mode needs enter, leave and report - and they never
+ * persist; the settings screen is the only persistent writer (I-4 / D-11).
+ *
+ * THE GUARD ORDER IS A CONTRACT (§3.4, R-P1-10 / R-P1-11) and it is not
+ * alphabetical:
+ *
+ *   status (no guard)   - "what is on?" is a question, answerable even in a
+ *                         `--no-team` session, which is where users ask it.
+ *   off   (no guard)    - leaving is always possible, even mid-dispatch.
+ *   registered?         - a `--no-team` session cannot grow the tool (I-7).
+ *   enabled?            - NOT a refusal: it is turned on for this session
+ *                         (D-5), because "start now" must not detour through a
+ *                         settings screen. Nothing is persisted.
+ *   not busy / idle     - two separate sentences, because both would otherwise
+ *                         surface as `task`'s own refusal card.
+ *   key present?        - names the missing provider.
+ *   on                  - arm only; the next message dispatches.
+ *
+ * EVERY `armForcedTeam()` / `disarmForcedTeam()` CALL SITE BELOW IS FOLLOWED BY A
+ * `ctx.notify` / `ctx.toast` IN THE SAME BRANCH (P1-6 / AC-28), because arming
+ * itself produces no `AgentEvent` and therefore no render: without the notice the
+ * `Team 4` chip would wait for an unrelated state change before appearing.
+ */
+import type { CommandContext, CommandRegistry } from './registry.js';
+/** The command body; `registerTeamCommand` is the only registration site. */
+export declare function runTeamCommand(ctx: CommandContext): void;
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export declare function registerTeamCommand(registry: CommandRegistry): void;

package/dist/commands/team-command.js

@@ -0,0 +1,259 @@
+/**
+ * `/team`: force the session into team mode and start work, or leave it
+ * (team-command-forced-dispatch §3.3 / §3.4 / §5.1).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHAT THIS COMMAND IS. `/team <brief>` parses the user's intent, ARMS a
+ * session-level forced mode and submits ONE normal user turn. The lead analyses
+ * and plans that turn and then has to call `task` - three layers say so: the
+ * directive it is handed, the `<forced_team_mode>` block in every later system
+ * prompt, and the mechanical gate in `ui/App.tsx` that nudges once if a whole
+ * turn went by without a dispatch. This command never dispatches itself (I-1):
+ * Esc, the watchdog, the report, spend accounting and the concurrency lock all
+ * stay on the one path that already has them.
+ *
+ * WHAT IT IS NOT ANY MORE. It used to be the CONFIG command - `status | on | off
+ * | max <n> | overseer on|off | model <name>`. All five verbs now live in the
+ * settings screen (`Settings > Team`, plus the root `Subagent model` row), and
+ * this command writes not one byte of `config.json` (I-4). The reason is the one
+ * the requirement names: a command that both changes configuration and starts
+ * work leaves the user unable to predict what it did. `on` and `off` survive as
+ * SESSION CONTROL words - a mode needs enter, leave and report - and they never
+ * persist; the settings screen is the only persistent writer (I-4 / D-11).
+ *
+ * THE GUARD ORDER IS A CONTRACT (§3.4, R-P1-10 / R-P1-11) and it is not
+ * alphabetical:
+ *
+ *   status (no guard)   - "what is on?" is a question, answerable even in a
+ *                         `--no-team` session, which is where users ask it.
+ *   off   (no guard)    - leaving is always possible, even mid-dispatch.
+ *   registered?         - a `--no-team` session cannot grow the tool (I-7).
+ *   enabled?            - NOT a refusal: it is turned on for this session
+ *                         (D-5), because "start now" must not detour through a
+ *                         settings screen. Nothing is persisted.
+ *   not busy / idle     - two separate sentences, because both would otherwise
+ *                         surface as `task`'s own refusal card.
+ *   key present?        - names the missing provider.
+ *   on                  - arm only; the next message dispatches.
+ *
+ * EVERY `armForcedTeam()` / `disarmForcedTeam()` CALL SITE BELOW IS FOLLOWED BY A
+ * `ctx.notify` / `ctx.toast` IN THE SAME BRANCH (P1-6 / AC-28), because arming
+ * itself produces no `AgentEvent` and therefore no render: without the notice the
+ * `Team 4` chip would wait for an unrelated state change before appearing.
+ */
+import { buildForcedDirective } from '../team/forced-dispatch.js';
+import { DEFAULT_FORCED_COUNT, planForced, planNotice, readTeamIntent, } from '../team/forced-mode.js';
+import { subagentModelSummary } from '../ui/overlays/model-profile-state.js';
+/**
+ * The subagent model line, phrased by the same authority the settings root row
+ * uses (`subagentModelSummary`), fed the six inputs only this layer can gather.
+ *
+ * IT IS A FUNCTION AND NOT AN INLINE CALL because the six inputs are exactly
+ * what a second copy gets wrong, and the settings root row feeds the same
+ * authority (`subagentModelSummary`) the same six - which is what keeps the two
+ * surfaces from describing one setting differently.
+ */
+function modelLine(ctx) {
+    const config = ctx.controller.getConfig();
+    const team = ctx.controller.getTeamConfig();
+    const fast = config.fast;
+    return subagentModelSummary({
+        mode: team.model,
+        modelProfileId: team.modelProfileId,
+        mainConnection: `${config.provider}:${config.model}`,
+        fastConnection: fast.enabled && fast.model
+            ? `${fast.provider || config.provider}:${fast.model}` : null,
+        profiles: config.modelProfiles,
+        hasKey: (id) => ctx.controller.hasApiKey(id),
+    });
+}
+/**
+ * The no-argument answer: five lines, honest in every session state (§5.1).
+ *
+ * IT RUNS BEFORE EVERY GUARD. "How do I use this?" is a question, not a request,
+ * and it is answerable in a `--no-team` session - which is exactly where the user
+ * most needs the answer.
+ */
+function reportStatus(ctx) {
+    const team = ctx.controller.getTeamConfig();
+    const forced = ctx.controller.getForcedTeam();
+    const registered = ctx.controller.isTeamRegistered();
+    const lines = [
+        forced
+            ? `Forced team mode: on, ${forced.count} subagents per turn.`
+            : 'Forced team mode: off.',
+        registered
+            ? `Team: ${ctx.controller.isTeamEnabled() ? 'on' : 'off'}; `
+                + `${team.maxSubagents} per dispatch, ${team.maxConcurrent} at once; `
+                + `supervisor ${team.overseer ? 'on' : 'off'}.`
+            : 'Team: off for this session (started with --no-team); /team cannot dispatch.',
+        `Subagent model: ${modelLine(ctx)}`,
+        'Usage: /team <brief> arms it and starts now; /team off leaves it.',
+        'Settings > Team has the persistent switches (mode, width, supervisor).',
+    ];
+    // DISCLOSED, NEVER REFUSED (§5.1 third degraded form): plan mode narrows what a
+    // child may do, and a user who is told so will not read the restraint as a bug.
+    if (forced && ctx.controller.getAgentMode() === 'plan') {
+        lines.push('Plan mode is on: dispatch read-only research, then submit_plan.');
+    }
+    ctx.notify('info', lines.join('\n'));
+}
+/**
+ * Guard 5's sentence. The provider is named because "no API key" alone leaves the
+ * user guessing which of their configured providers is the empty one.
+ */
+function reportMissingKey(ctx, team) {
+    const config = ctx.controller.getConfig();
+    const resolution = ctx.controller.subagentModelResolution();
+    const provider = resolution.effective === 'main'
+        ? config.provider : resolution.ref.providerId;
+    const note = team.model === 'fast' && !ctx.controller.hasApiKey(undefined, 'fast')
+        ? ' Fast tier has no key either; children will fail and the report will say so.'
+        : '';
+    ctx.notify('warn', `No API key for ${provider}. Set one with /settings or an environment variable.${note}`);
+}
+/**
+ * The capability guards, in §3.4's exact order: registered -> enabled -> busy ->
+ * running -> key.
+ *
+ * RETURNS `true` WHEN THE CALLER MAY CONTINUE. Step 5 is the one place a guard
+ * becomes an ACTION (D-5) and it sits at its documented position rather than at
+ * the end for a behavioural reason: the user's own sentence is "start now", so
+ * the switch is turned on before any sentence about *why we cannot* is composed.
+ * The action is still followed by a notice in the same branch (P1-6 / AC-28),
+ * because `setTeamEnabled()` rebuilds the prompt and produces no `AgentEvent`, so
+ * without it the `Team N` chip would wait for an unrelated render.
+ */
+function passGuards(ctx, team) {
+    if (!ctx.controller.isTeamRegistered()) {
+        ctx.notify('warn', 'Team mode is off for this session (started with --no-team). '
+            + 'Restart without --no-team to use /team.');
+        return false;
+    }
+    // STEP 5, THE ONE GUARD THAT IS NOT A REFUSAL: "start now" must not detour
+    // through a settings screen. Nothing is persisted here (I-4) - `Settings >
+    // Team` stays the only persistent writer.
+    if (!ctx.controller.isTeamEnabled()) {
+        ctx.controller.setTeamEnabled(true);
+        ctx.notify('info', 'Team mode was off; turned on for this session (Settings > Team saves it).');
+    }
+    // The team lock and the lead's turn are separate refusals for one reason: both
+    // would collide with `task`'s own BUSY_REFUSAL, and the user would see a failed
+    // tool card instead of a sentence explaining why nothing ran.
+    if (ctx.controller.isTeamBusy()) {
+        ctx.notify('warn', 'A team dispatch is already running. '
+            + 'Wait for its report, or press Esc to stop it.');
+        return false;
+    }
+    if (ctx.controller.isRunning()) {
+        ctx.notify('warn', 'A turn is in progress. Press Esc to stop it, then run /team again.');
+        return false;
+    }
+    if (!ctx.controller.hasApiKey()) {
+        reportMissingKey(ctx, team);
+        return false;
+    }
+    return true;
+}
+/** The four parse failures, each with the one sentence that fixes it. */
+function reportParseError(ctx, intent) {
+    if (intent.error === 'count') {
+        ctx.notify('warn', '/team: -n needs a number of 1 or more, e.g. -n 4.');
+        return;
+    }
+    if (intent.error === 'conflict') {
+        ctx.notify('warn', '/team: use -n or --parts, not both.');
+        return;
+    }
+    if (intent.error === 'flag') {
+        ctx.notify('warn', `/team: unknown option "${intent.token ?? ''}". Try /team for usage.`);
+        return;
+    }
+    ctx.notify('warn', '/team <brief> - describe the work; add -n <count> to fix the fan-out.');
+}
+/**
+ * `/team off`: disarm the session, and say plainly that the CAPABILITY was not
+ * touched.
+ *
+ * THE SECOND HALF OF THE SENTENCE IS THE POINT (D-2 / D-11): with the switch
+ * moved to settings, "off" can only ever mean "this conversation stops being
+ * forced". A user who reads it as "team mode is now disabled everywhere" would
+ * next find `/team` still working tomorrow, and no test would describe that as a
+ * defect because no single surface would be wrong.
+ */
+function leaveForcedMode(ctx) {
+    if (!ctx.controller.getForcedTeam()) {
+        // IDEMPOTENT, and it says so rather than reporting a change it did not make.
+        ctx.notify('info', 'Forced team mode was not on.');
+        return;
+    }
+    ctx.controller.disarmForcedTeam();
+    ctx.notify('info', 'Forced team mode off. Team capability unchanged (Settings > Team).');
+}
+/** `/team on`: arm with the default count and stop there - no turn is submitted. */
+function enterForcedMode(ctx) {
+    if (!passGuards(ctx, ctx.controller.getTeamConfig()))
+        return;
+    const adopted = ctx.controller.armForcedTeam(DEFAULT_FORCED_COUNT);
+    ctx.notify('info', `Forced team mode on: ${adopted} subagents per turn. `
+        + 'Your next message dispatches.');
+}
+/** `/team [-n n|--parts a,b] [--read-only] <brief>`: arm and submit in one act. */
+function armAndSubmit(ctx, intent) {
+    const team = ctx.controller.getTeamConfig();
+    if (!passGuards(ctx, team))
+        return;
+    const planned = planForced(intent.args, team);
+    // ARMED BEFORE THE TURN IS SUBMITTED, and with the SAME narrowed number the
+    // directive names: the later turns reuse this count, so the first turn and the
+    // rest of the session cannot disagree about how wide the fan-out is (D-7).
+    ctx.controller.armForcedTeam(planned.count);
+    ctx.notify('info', planNotice(planned, team));
+    const directive = buildForcedDirective({
+        brief: planned.brief,
+        count: planned.count,
+        readOnly: planned.readOnly,
+        parts: planned.parts,
+        maxSubagents: team.maxSubagents,
+        clamped: planned.requested > planned.count,
+        requested: planned.requested,
+        planMode: ctx.controller.getAgentMode() === 'plan',
+    });
+    // `userInitiated: false`: a directive the user did not type belongs in neither
+    // the prompt history nor the hint-fade counter (todo-plan-followthrough C-12).
+    ctx.submit(directive, { userInitiated: false });
+}
+/** The command body; `registerTeamCommand` is the only registration site. */
+export function runTeamCommand(ctx) {
+    const intent = readTeamIntent(ctx.args);
+    if (intent.kind === 'status') {
+        reportStatus(ctx);
+        return;
+    }
+    if (intent.kind === 'off') {
+        leaveForcedMode(ctx);
+        return;
+    }
+    if (intent.kind === 'on') {
+        enterForcedMode(ctx);
+        return;
+    }
+    if (intent.kind === 'error') {
+        // PARSED BEFORE THE CAPABILITY GUARDS, unlike `on` / `<brief>`. A syntax hint
+        // is the answer to a syntax mistake in ANY session: sending a `--no-team` user
+        // to fix their flags first would send them to repair the one thing that is
+        // not broken.
+        reportParseError(ctx, intent);
+        return;
+    }
+    armAndSubmit(ctx, intent);
+}
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export function registerTeamCommand(registry) {
+    registry.register({
+        name: 'team',
+        description: 'Force team mode and start now: /team <brief>; /team [on|off|status]',
+        run: (ctx) => { runTeamCommand(ctx); },
+    });
+}

package/dist/compaction/command.js

@@ -16,6 +16,7 @@ import { parseThresholdInput } from '../config/schema.js';
 import { formatCost, formatTokens } from '../agent/usage.js';
 import { computeCost } from '../agent/usage.js';
 import { COMPACTION_LIMITS } from './limits.js';
+import { compactionReasonLine } from './reason-text.js';
 import { findArchive, listArchives } from './archive.js';
 /**
  * `/compact status` — THE GUARANTEED REPORTING SURFACE (§6.5 / AC-17).
@@ -46,7 +47,7 @@ export function formatCompactionStatus(ctx) {
         return lines.join('\n');
     }
     const state = snapshot.selfDisabled
-        ? `self-disabled (${snapshot.selfDisabledReason ?? 'no progress'})`
+        ? `self-disabled (${compactionReasonLine(snapshot.selfDisabledReason ?? 'no progress')})`
         : controller.isCompactionEnabled()
             ? snapshot.live
                 ? 'on'
@@ -61,7 +62,13 @@ export function formatCompactionStatus(ctx) {
         `[${p.source === 'usage' ? 'measured' : 'estimated'}]`);
     lines.push(`  Automatic trigger: occupancy >= ${(config.threshold * 100).toFixed(2)}%; ` +
         `manual: /compact (${Math.ceil(p.contextWindow * config.threshold)} tokens)`);
+    // TWO LINES, BECAUSE THE TAIL GUARANTEE IS NOW CONDITIONAL (never-fires B).
+    // `keepRecentTurns` stays the promise; the second line is what happens when a run
+    // has too few user turns for that promise to be satisfiable, and saying it here
+    // is what makes the card's `kept M of N` readable rather than surprising.
     lines.push(`  Keeps: the original task + ${config.keepRecentTurns} recent turns, verbatim`);
+    lines.push(`  Relaxes to: the last ${COMPACTION_LIMITS.minRetainedMessages} messages ` +
+        'when a run has too few user turns for that');
     lines.push(`  Summarizer: ${snapshot.model || '(none)'}` +
         (config.useFastTier ? ' (fast tier preferred)' : ' (fast tier not used)'));
     lines.push('  On summarize failure: ' + (config.onFailure === 'truncate'
@@ -79,8 +86,14 @@ export function formatCompactionStatus(ctx) {
     if (declined > 0) {
         sessionNotes.push(`${declined} ${declined === 1 ? 'checkpoint' : 'checkpoints'} declined`);
     }
-    lines.push(`  This session: ${snapshot.compactions} ` +
-        `${snapshot.compactions === 1 ? 'compaction' : 'compactions'}` +
+    // ATTEMPTS, THEN APPLIED (never-fires C). `compactions` counts every card the
+    // user saw, which now includes the ones that declined, so reporting it alone
+    // would overstate how much the feature actually achieved.
+    const attempts = snapshot.applied === undefined
+        ? `${snapshot.compactions} ${snapshot.compactions === 1 ? 'compaction' : 'compactions'}`
+        : `${snapshot.compactions} ${snapshot.compactions === 1 ? 'attempt' : 'attempts'}` +
+            ` (${snapshot.applied} applied)`;
+    lines.push(`  This session: ${attempts}` +
         (sessionNotes.length > 0 ? ` (${sessionNotes.join(', ')})` : '') +
         `, ${formatTokens(snapshot.tokensReclaimed)} tokens reclaimed`);
     const cost = snapshot.pricingUnknown

package/dist/compaction/compactor.d.ts

@@ -93,6 +93,7 @@ export declare class Compactor implements ContextManager {
     private compactionsThisRun;
     private lastCompactionTurn;
     private compactions;
+    private appliedCompactions;
     private declined;
     private tokensReclaimed;
     private sessionUsage;
@@ -132,8 +133,31 @@ export declare class Compactor implements ContextManager {
     private callOnce;
     private checkCandidate;
     private isCurrent;
+    /**
+     * Open the card for THIS attempt (C).
+     *
+     * CALLED FROM `compact()`'S ENTRY, so the two pre-model rejections are visible
+     * too. The old position - inside `callOnce` - made an attempt that never called
+     * a model indistinguishable from a checkpoint that never fired, which is exactly
+     * how this feature spent 96 attempts without a single user-visible symptom.
+     *
+     * `state.index !== undefined` keeps it idempotent: `callOnce` no longer calls it,
+     * but the guard stays so a future re-announce cannot open a second card for one
+     * attempt.
+     */
     private announce;
+    /** Publish the current phase, for the live card only. */
+    private phase;
     private keep;
+    /**
+     * The relaxation disclosure, as record fields.
+     *
+     * ONE PLACE BUILDS IT, so the card, the reducer and the diagnostic log cannot
+     * describe one relaxed cut three different ways. Absent entirely when the first
+     * planning pass found a cut, which is what keeps a normal compaction's record
+     * byte-identical to the round before this change.
+     */
+    private relaxedFields;
     private finishRecord;
     /** Commit only the engine/host verdict; candidates have no authority before this point. */
     settleOperation(verdict: {
@@ -152,6 +176,7 @@ export declare class Compactor implements ContextManager {
     sessionTotals(): {
         selfDisabledReason?: string | undefined;
         compactions: number;
+        applied: number;
         declined: number;
         tokensReclaimed: number;
         usage: TokenUsage;