peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/baseline-rollback-commands.js

@@ -0,0 +1,88 @@
+// src/cli/commands/baseline-rollback-commands.ts
+//
+// `peaks baseline rollback` and `peaks baseline reset` — the two destructive
+// baseline operations, both gated behind `--confirm`. Split out of
+// `baseline-commands.ts`; every refusal code, message and data field is
+// unchanged.
+import { copyFileSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { readBaselineFile } from '../../services/capability-baseline/store.js';
+import { CURRENT_DIR, fail, HISTORY_DIR, ok } from './baseline-command-shared.js';
+function runRollback(io, opts) {
+    const projectRoot = opts.project ?? '.';
+    if (opts.confirm !== true) {
+        fail(io, 'HUMAN_NL_DECISION_REQUIRED', 'rollback requires the user to approve via AskUserQuestion. The LLM must surface a multi-choice prompt, then re-run with --confirm.');
+        return;
+    }
+    if (!opts.to) {
+        fail(io, 'MISSING_ARG', '--to is required');
+        return;
+    }
+    const source = HISTORY_DIR(projectRoot, opts.to);
+    const from = join(source, 'capability-baseline.json');
+    const fromLock = join(source, 'capability-baseline.lock');
+    if (!existsSync(from) || !existsSync(fromLock)) {
+        fail(io, 'BASELINE_HISTORY_GAP', `no frozen baseline recorded for version ${opts.to}`);
+        return;
+    }
+    const r = readBaselineFile(projectRoot);
+    if (!r.ok) {
+        fail(io, r.error.code, r.error.message);
+        return;
+    }
+    mkdirSync(CURRENT_DIR(projectRoot), { recursive: true });
+    copyFileSync(from, join(CURRENT_DIR(projectRoot), 'capability-baseline.json'));
+    copyFileSync(fromLock, join(CURRENT_DIR(projectRoot), 'capability-baseline.lock'));
+    // Re-read through the locked store so a tampered history entry cannot be
+    // installed: the copy is only reported successful if it verifies.
+    const after = readBaselineFile(projectRoot);
+    if (!after.ok) {
+        fail(io, after.error.code, after.error.message);
+        return;
+    }
+    ok(io, 'baseline.rollback', {
+        fromVersion: r.file.version,
+        toVersion: after.file.version,
+        historyPath: source
+    });
+}
+function runReset(io, opts) {
+    const projectRoot = opts.project ?? '.';
+    if (opts.confirm !== true) {
+        fail(io, 'HUMAN_NL_DECISION_REQUIRED', 'reset requires the user to approve via AskUserQuestion. The LLM must surface a multi-choice prompt, then re-run with --confirm.');
+        return;
+    }
+    const r = readBaselineFile(projectRoot);
+    // A missing baseline is already "wiped" — but an unreadable one (hash
+    // mismatch / unsigned lock) must not be silently discarded.
+    if (!r.ok && r.error.code !== 'BASELINE_NOT_FOUND') {
+        fail(io, r.error.code, r.error.message);
+        return;
+    }
+    const wipedVersion = r.ok ? r.file.version : null;
+    rmSync(join(CURRENT_DIR(projectRoot), 'capability-baseline.json'), { force: true });
+    rmSync(join(CURRENT_DIR(projectRoot), 'capability-baseline.lock'), { force: true });
+    ok(io, 'baseline.reset', {
+        wipedVersion,
+        nextAction: 're-freeze with `baseline freeze --from <path>`'
+    });
+}
+export function registerBaselineRollbackCommand(baseline, io) {
+    baseline
+        .command('rollback')
+        .description("Roll the baseline back to a historical version. --confirm records the user's approval.")
+        .option('--to <version>', 'Historical version to roll back to')
+        .option('--confirm', "Record the user's approval (collected via AskUserQuestion) for this rollback")
+        .option('--project <path>', 'Project root', '.')
+        .option('--json', 'Emit JSON envelope')
+        .action((opts) => runRollback(io, opts));
+}
+export function registerBaselineResetCommand(baseline, io) {
+    baseline
+        .command('reset')
+        .description("Wipe the current baseline and require a re-freeze. --confirm records the user's approval.")
+        .option('--confirm', "Record the user's approval (collected via AskUserQuestion) for the wipe")
+        .option('--project <path>', 'Project root', '.')
+        .option('--json', 'Emit JSON envelope')
+        .action((opts) => runReset(io, opts));
+}

package/dist/cli/commands/classify-downgrade-command.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ClassifyDowngradeOptions = {
+    project: string;
+    level: string;
+    reason: string;
+    json?: boolean;
+};
+export declare function registerClassifyDowngradeCommand(classify: Command, io: ProgramIO): void;

package/dist/cli/commands/classify-downgrade-command.js

@@ -0,0 +1,21 @@
+// src/cli/commands/classify-downgrade-command.ts
+//
+// `peaks classify downgrade` — REFUSED per spec §4: the CLI never downgrades a
+// classification unilaterally. Extracted from
+// `governance-classify-contract-commands.ts`; the registered name, description,
+// options, refusal code and exit code (2) are unchanged.
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+export function registerClassifyDowngradeCommand(classify, io) {
+    classify
+        .command('downgrade')
+        .description('REFUSED per spec §4 — peaks-loop never downgrades a classification; ask the user to override explicitly')
+        .requiredOption('--level <level>', 'attempted level')
+        .requiredOption('--reason <text>', 'reason for the attempt (always rejected)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--json', 'print machine-readable JSON envelope')
+        .action((options) => {
+        printResult(io, fail('classify.downgrade', 'DOWNGRADE_REFUSED', 'peaks classify downgrade is refused per spec §4. Use --override (with reason) on `classify run` to force a level; the CLI never downgrades a classification unilaterally.', { attemptedLevel: options.level, reason: options.reason }, ['Use `peaks classify run --override <level> --reason "<text>"` instead']), options.json);
+        process.exitCode = 2;
+    });
+}

package/dist/cli/commands/classify-run-command.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ClassifyRunOptions = {
+    project: string;
+    override?: string;
+    reason?: string;
+    json?: boolean;
+};
+export declare function registerClassifyRunCommand(classify: Command, io: ProgramIO): void;

package/dist/cli/commands/classify-run-command.js

@@ -0,0 +1,73 @@
+// src/cli/commands/classify-run-command.ts
+//
+// `peaks classify run` — classify the current diff (git diff HEAD) into one of
+// the 5 task levels, with an optional `--override` + `--reason`. Extracted from
+// `governance-classify-contract-commands.ts`; the registered name, description,
+// options, refusal codes, audit write and envelope are unchanged.
+//
+// `loadPreferences` is synchronous, so the action is too — the merged file said
+// `await loadPreferences(...)`, which `@typescript-eslint/await-thenable`
+// flagged as an await of a non-Promise. Dropping the keyword pair changes no
+// byte of the envelope (the equivalence harness re-measured it).
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { classifyTask } from '../../services/classify/classify-service.js';
+import { TASK_LEVELS } from '../../services/classify/classify-types.js';
+import { loadPreferences } from '../../services/preferences/preferences-service.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { appendAuditEntry, CLASSIFY_AUDIT_FILE, getSignalsFromGitDiff, isTaskLevel } from './classify-signals.js';
+export function registerClassifyRunCommand(classify, io) {
+    addJsonOption(classify
+        .command('run')
+        .description('Classify the current diff (git diff HEAD) into one of 5 task levels')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--override <level>', 'force a level (one of typo|bug|feature|refactor|migration); requires --reason')
+        .option('--reason <text>', 'reason for the override (mandatory when --override is set)')).action((options) => {
+        const envelope = classifyRunEnvelope(options);
+        printResult(io, envelope, options.json);
+        if (!envelope.ok)
+            process.exitCode = 1;
+    });
+}
+function classifyRunEnvelope(options) {
+    try {
+        const prefs = loadPreferences(options.project);
+        const signals = getSignalsFromGitDiff(options.project);
+        const override = readOverride(options);
+        if (override.envelope !== null)
+            return override.envelope;
+        const result = classifyTask(override.level === undefined
+            ? { signals, conservatism: prefs.classifyConservatism }
+            : {
+                signals,
+                conservatism: prefs.classifyConservatism,
+                override: { level: override.level, reason: override.reason }
+            }, prefs.classifyRules.feature_threshold_files, prefs.classifyRules.feature_threshold_lines);
+        appendAuditEntry(options.project, result.audit);
+        return ok('classify.run', result, [], [
+            `gate set for level "${result.level}": ${result.gateSet.stages.join(', ')}`,
+            `audit log: .peaks/_runtime/${CLASSIFY_AUDIT_FILE}`
+        ]);
+    }
+    catch (error) {
+        return fail('classify.run', 'CLASSIFY_RUN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Run peaks classify --help for usage']);
+    }
+}
+/** The two refusals `--override` / `--reason` can earn, in the order they fire. */
+function readOverride(options) {
+    const empty = { level: undefined, reason: '', envelope: null };
+    if (options.override === undefined)
+        return empty;
+    if (!isTaskLevel(options.override)) {
+        return {
+            ...empty,
+            envelope: fail('classify.run', 'INVALID_LEVEL', `level must be one of: ${TASK_LEVELS.join(', ')}`, { provided: options.override }, ['Pass one of typo, bug, feature, refactor, migration'])
+        };
+    }
+    if (options.reason === undefined || options.reason.length === 0) {
+        return {
+            ...empty,
+            envelope: fail('classify.run', 'REASON_REQUIRED', '--reason is required when --override is set', {}, ['Provide a non-empty reason for the override'])
+        };
+    }
+    return { level: options.override, reason: options.reason, envelope: null };
+}

package/dist/cli/commands/classify-signals.d.ts

@@ -0,0 +1,5 @@
+import { type ClassifySignals, type TaskLevel } from '../../services/classify/classify-types.js';
+export declare const CLASSIFY_AUDIT_FILE = "classify-audit.jsonl";
+export declare function getSignalsFromGitDiff(projectRoot: string): ClassifySignals;
+export declare function appendAuditEntry(projectRoot: string, entry: unknown): void;
+export declare function isTaskLevel(value: string): value is TaskLevel;

package/dist/cli/commands/classify-signals.js

@@ -0,0 +1,104 @@
+// src/cli/commands/classify-signals.ts
+//
+// What `peaks classify` reads and writes outside its own envelope: the diff
+// signals the heuristic classifies, the audit-log append, and the task-level
+// guard. Extracted from `governance-classify-contract-commands.ts` (which had
+// merged `classify-classify-commands.ts` verbatim); the parsing, the audit file
+// name and the level guard are unchanged.
+//
+// `child_process` is a static import here rather than the CJS `require` the
+// merged file used inside `getSignalsFromGitDiff`: the module specifier is a
+// Node builtin, so a top-level import cannot fail where the `require` could, and
+// the call itself — arguments, `windowsHide`, and the zeros fallback when git is
+// unavailable — is byte-for-byte the same.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { TASK_LEVELS } from '../../services/classify/classify-types.js';
+export const CLASSIFY_AUDIT_FILE = 'classify-audit.jsonl';
+export function getSignalsFromGitDiff(projectRoot) {
+    // Use git diff --stat to extract file count + line count. Fall back to
+    // zeros if git is unavailable (e.g. fresh repo with no commits).
+    let stdout;
+    try {
+        stdout = execFileSync('git', ['diff', '--shortstat', 'HEAD'], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 32 * 1024 * 1024,
+            windowsHide: true
+        }).toString('utf8');
+    }
+    catch {
+        return {
+            filesChanged: 0,
+            linesChanged: 0,
+            touchesDependencies: false,
+            touchesMigrationScripts: false,
+            isPureRefactor: true,
+            keywords: []
+        };
+    }
+    const lines = stdout.split('\n').filter((l) => l.trim().length > 0);
+    const filesChanged = lines.length;
+    let added = 0;
+    let removed = 0;
+    let touchesDependencies = false;
+    let touchesMigrationScripts = false;
+    for (const line of lines) {
+        const match = /(\d+)\s+insertion.*?(\d+)\s+deletion/.exec(line);
+        if (match) {
+            added += Number(match[1]);
+            removed += Number(match[2]);
+        }
+        if (/(package\.json|pnpm-lock\.yaml|yarn\.lock|requirements\.txt|go\.mod)/.test(line)) {
+            touchesDependencies = true;
+        }
+        if (/(migrate|codemod|backfill|schema)/.test(line)) {
+            touchesMigrationScripts = true;
+        }
+    }
+    // isPureRefactor: heuristic — if added lines / removed lines < 0.1 OR
+    // no new exports were added, treat as refactor. For L2.2 the signal is
+    // binary (true/false). Default: true (no behavior change is the safe
+    // assumption; flip to false when keyword 'add' / 'new' / 'feature' present).
+    const isPureRefactor = true;
+    return {
+        filesChanged,
+        linesChanged: added + removed,
+        touchesDependencies,
+        touchesMigrationScripts,
+        isPureRefactor,
+        keywords: []
+    };
+}
+export function appendAuditEntry(projectRoot, entry) {
+    const auditDir = join(projectRoot, '.peaks/_runtime');
+    if (!existsSync(auditDir)) {
+        try {
+            mkdirSync(auditDir, { recursive: true });
+        }
+        catch {
+            /* ignore */
+        } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    }
+    const auditPath = join(auditDir, CLASSIFY_AUDIT_FILE);
+    let body = '';
+    try {
+        if (existsSync(auditPath)) {
+            body = readFileSync(auditPath, 'utf8');
+        }
+    }
+    catch {
+        /* ignore */
+    } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    body += JSON.stringify(entry) + '\n';
+    try {
+        writeFileSync(auditPath, body);
+    }
+    catch {
+        /* best-effort */
+    } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+}
+export function isTaskLevel(value) {
+    return TASK_LEVELS.includes(value);
+}

package/dist/cli/commands/code-auto-compact-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeAutoCompactCommand(code: Command, io: ProgramIO): void;

package/dist/cli/commands/code-auto-compact-command.js

@@ -0,0 +1,124 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+import { runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
+import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
+import { readActiveSid } from './code-runtime-session.js';
+import { buildAutoCompactEnvelope } from './code-auto-compact-envelope.js';
+const AUTO_COMPACT_DESCRIPTION = 'v2.13.0 AC-4: zero-human-intervention auto-compact. Probes current ' +
+    'context-fill % via the active IDE adapter; ≥ 0.85 writes a pre-compact ' +
+    'checkpoint + convergence plan + auto-decisions log; ≥ 0.95 ASKS the ' +
+    'harness to compact and reports that it is waiting for it — no ratio ' +
+    'blocks sub-agent dispatch, because peaks-loop has no way to compact a ' +
+    'running session and a gate nobody can satisfy gates nothing. The LLM / ' +
+    'runner keeps working at any ratio without human intervention. Pair with `peaks code ' +
+    'context-now` (AC-1), the read-only probe that reports the ratio this ' +
+    'command acts on. This command is also fired by the installed ' +
+    'PreToolUse hook, which passes `--project .` — without that argument ' +
+    'the hook could never run at all. rid-027 ' +
+    'adds `--mode <mode>`: `standard` (0.85/0.95) or `partial` (0.70/0.85 ' +
+    'for 24h long-run mode).';
+/** The invalid-`--mode` branch, lifted verbatim out of the action body. */
+function reportInvalidAutoCompactMode(io, modeName, json) {
+    printResult(io, fail('code.auto-compact', 'AUTO_COMPACT_INVALID_MODE', `Invalid --mode '${modeName}'. Valid values: standard | partial.`, null, ['Re-run with --mode standard or --mode partial.']), json);
+    process.exitCode = 1;
+}
+/**
+ * The `runAutoCompact` input object, lifted verbatim: it reads only its two
+ * parameters, so it has no ordering dependency on the call site.
+ */
+function buildAutoCompactInput(opts, modeName) {
+    // Slice 4.0.8 (D4d): production `inFlightBatch` MUST come from
+    // the workflow graph probe. The legacy `--in-flight-batch`
+    // boolean CLI flag is a TEST-ONLY seam (gated by
+    // `PEAKS_TEST_SEAM === '1'`). When the env flag is unset
+    // (the production case), we wire `probeInflightBatch` to the
+    // canonical `workflow-inflight-probe.ts` service so the
+    // production decision is graph-backed, not lease-age.
+    const isTestSeam = process.env.PEAKS_TEST_SEAM === '1';
+    return {
+        projectRoot: opts.project,
+        sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? undefined,
+        ...(isTestSeam && opts.inFlightBatch === true
+            ? { inFlightBatch: { hasInFlightBatch: true } }
+            : {}),
+        ...(!isTestSeam
+            ? {
+                probeInflightBatch: () => {
+                    // Synchronous probe: the workflow-inflight-probe
+                    // service is pure / synchronous (no I/O). The
+                    // empty `graphs` array is the production CLI
+                    // default — callers that want a richer fixture
+                    // (e.g. `peaks session 24h-mode`) should hand-roll
+                    // a probe and pass it via the orchestrator's
+                    // input. When no graph is materialized, the
+                    // probe returns `inFlightBatch: false`, matching
+                    // the 4.0.7 zero-pause contract for stock
+                    // projects.
+                    const out = probeInFlightBatch({ now: new Date().toISOString(), graphs: [] });
+                    return out.inFlightBatch === true;
+                }
+            }
+            : {}),
+        force: opts.force === true,
+        bypassRedLine: opts.bypassRedLine === true,
+        // Forward the FLAG verbatim — `undefined` when the user named no
+        // mode — so the orchestrator's fallback to the presence-derived
+        // mode can actually run. Forwarding the validated `modeName` is
+        // what disabled 24h → partial.
+        mode: opts.mode === undefined ? undefined : modeName
+    };
+}
+/** The catch branch, lifted verbatim out of the action body. */
+function reportAutoCompactFailure(io, err, json) {
+    printResult(io, fail('code.auto-compact', 'AUTO_COMPACT_FAILED', getErrorMessage(err), null, [
+        'Verify the project path + session id and try again'
+    ]), json);
+    process.exitCode = 1;
+}
+/** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
+async function runAutoCompactAction(opts, io) {
+    try {
+        const { isValidMode } = await import('../../services/code/auto-compact-modes.js');
+        const modeName = opts.mode ?? 'standard';
+        if (!isValidMode(modeName)) {
+            reportInvalidAutoCompactMode(io, modeName, opts.json);
+            return;
+        }
+        const result = await runAutoCompact(buildAutoCompactInput(opts, modeName));
+        const code = result.code;
+        const exitOk = result.ok || code === 'AUTO_COMPACT_SKIP' || code === 'AUTO_COMPACT_WAIT';
+        // Adapt AutoCompactResult → ResultEnvelope so printResult's
+        // generic accepts it. The orchestrator envelope carries
+        // `data` on success-path and `nextActions` on the error
+        // path; surface both directly to the user.
+        printResult(io, buildAutoCompactEnvelope(result), opts.json);
+        if (!exitOk)
+            process.exitCode = 1;
+    }
+    catch (err) {
+        reportAutoCompactFailure(io, err, opts.json);
+    }
+}
+export function registerCodeAutoCompactCommand(code, io) {
+    addJsonOption(code
+        .command('auto-compact')
+        .description(AUTO_COMPACT_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--in-flight-batch', 'defer if a sub-agent batch is in flight (D6.e)')
+        .option('--force', 'force compact at any ratio (test seam)')
+        // Accepted and inert. There is no longer a 95% gate to skip: peaks-loop
+        // cannot compact a running session, so the red line never blocked
+        // dispatch and `bypassRedLine` is read by nothing (slice
+        // rather than deleted because it is a published CLI surface — deleting it
+        // would make an existing caller fail on an unknown option, which is a
+        // harder break than a no-op — and because the honest fix here is to stop
+        // advertising it, not to change its meaning.
+        .option('--bypass-red-line', 'no-op: the 95% red line no longer gates dispatch, so there is nothing to bypass (accepted for backward compatibility)')
+        // No commander default here, deliberately. A declared default makes
+        // `opts.mode` permanently defined, which defeats the orchestrator's
+        // `input.mode ?? resolveAutoCompactMode(projectRoot)` fallback and
+        // silently disables "24h mode auto-selects partial" — the help text
+        // below promises it. Absence must stay absent.
+        .option('--mode <mode>', 'auto-compact mode (standard | partial). Default: standard. 24h mode auto-selects partial.')).action((opts) => runAutoCompactAction(opts, io));
+}

package/dist/cli/commands/code-auto-compact-envelope.d.ts

@@ -0,0 +1,22 @@
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+import { type AutoCompactResult } from '../../services/code/auto-compact-orchestrator.js';
+/**
+ * Adapt `runAutoCompact`'s domain result to a `ResultEnvelope`.
+ *
+ * Extracted and exported so the CHANNEL each fact chooses can be asserted
+ * directly, without a real red-line probe.
+ *
+ * The harness-window CONFLICT ("peaks-loop divided this ratio by N but the
+ * settings file pins M") is a fact about the STATE, not an instruction, so it
+ * rides `warnings` — the very channel `peaks code context-now` already puts it
+ * on, via the same `harnessWindowSyncWarning`. Before this, the shim hard-coded
+ * `warnings: []`, so the identical fact reached a consumer as a sentence inside
+ * `nextActions` on this command and as a `warnings` entry on the other one. One
+ * fact, two shapes, depending on which of the two syncing commands a consumer
+ * happened to read: two parsers for one mechanism.
+ *
+ * The prose description (`describeHarnessWindowSync`) stays in `nextActions` on
+ * BOTH commands — that half is advice ("what to do about it") and both already
+ * agree on it.
+ */
+export declare function buildAutoCompactEnvelope(result: AutoCompactResult): ResultEnvelope<unknown>;

package/dist/cli/commands/code-auto-compact-envelope.js

@@ -0,0 +1,39 @@
+// The `peaks code auto-compact` result adapter, on its own so the CHANNEL each
+// fact chooses can be asserted directly, without a real red-line probe.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { harnessWindowSyncWarning } from '../../services/context/harness-window-config.js';
+/**
+ * Adapt `runAutoCompact`'s domain result to a `ResultEnvelope`.
+ *
+ * Extracted and exported so the CHANNEL each fact chooses can be asserted
+ * directly, without a real red-line probe.
+ *
+ * The harness-window CONFLICT ("peaks-loop divided this ratio by N but the
+ * settings file pins M") is a fact about the STATE, not an instruction, so it
+ * rides `warnings` — the very channel `peaks code context-now` already puts it
+ * on, via the same `harnessWindowSyncWarning`. Before this, the shim hard-coded
+ * `warnings: []`, so the identical fact reached a consumer as a sentence inside
+ * `nextActions` on this command and as a `warnings` entry on the other one. One
+ * fact, two shapes, depending on which of the two syncing commands a consumer
+ * happened to read: two parsers for one mechanism.
+ *
+ * The prose description (`describeHarnessWindowSync`) stays in `nextActions` on
+ * BOTH commands — that half is advice ("what to do about it") and both already
+ * agree on it.
+ */
+export function buildAutoCompactEnvelope(result) {
+    const data = 'data' in result ? result.data : null;
+    const nextActions = 'nextActions' in result ? result.nextActions : [];
+    const warning = harnessWindowSyncWarning(data?.harnessWindow ?? null);
+    const warnings = warning === null ? [] : [warning];
+    if (result.ok) {
+        return ok('code.auto-compact', data ?? {}, warnings, [result.message, ...nextActions]);
+    }
+    // `fail()` hard-codes `warnings: []`, so the warning is spread back over it —
+    // a refused write can disagree with the ratio just as easily on the failure
+    // path, and the state does not become less true because the dispatch failed.
+    return {
+        ...fail('code.auto-compact', result.code, result.message, data, [...nextActions]),
+        warnings
+    };
+}

package/dist/cli/commands/code-context-audit-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeContextAuditCommand(code: Command, io: ProgramIO): void;

package/dist/cli/commands/code-context-audit-command.js

@@ -0,0 +1,68 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { ok } from 'peaks-loop-shared/result';
+import { auditContext } from '../../services/context/context-audit.js';
+import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
+import { readActiveSid } from './code-runtime-session.js';
+const CONTEXT_AUDIT_DESCRIPTION = "Slice 2026-09-10 Slice A: report what fills the current session's " +
+    'context window, grouped by tool + short input key (command line / ' +
+    "path tail / pattern), sorted by bytes. Locates the CURRENT session's " +
+    "IDE transcript through the active adapter's " +
+    '`compact.resolveTranscriptPath` (vendor-neutral); emits total bytes, ' +
+    'entry count, and the top-N groups ' +
+    '(`{tool, key, bytes, pctOfTotal, count}`). Read-only and fail-soft — ' +
+    'a missing/oversized/corrupt transcript returns `available:false` ' +
+    'with a reason and never blocks. Never dumps tool result content.';
+/** The catch branch, lifted verbatim out of the action body (fail-soft, exit code untouched). */
+function reportContextAuditFailure(io, err, json) {
+    printResult(io, ok('code.context-audit', {
+        available: false,
+        reason: `audit-failed: ${getErrorMessage(err)}`,
+        transcriptPath: null,
+        totalBytes: 0,
+        entryCount: 0,
+        groupCount: 0,
+        topN: 0,
+        entries: []
+    }, [], ['context-audit is a read-only probe; continue without it.']), json);
+}
+/** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
+function runCodeContextAudit(opts, io) {
+    try {
+        // `resolveOuterSessionId` checks the env signal FIRST, so the peaks
+        // session id is only a fallback lookup key — mirror context-now's
+        // 'unknown' default so an unbound presence still resolves via env.
+        const sessionId = opts.sessionId ?? readActiveSid(opts.project) ?? 'unknown';
+        const outerSessionId = resolveOuterSessionId(opts.project, sessionId);
+        const result = auditContext({
+            outerSessionId: outerSessionId ?? null,
+            ...(opts.top !== undefined ? { topN: opts.top } : {}),
+            ...(opts.transcript !== undefined ? { transcriptPath: opts.transcript } : {})
+        });
+        // Fail-soft contract: unavailability is DATA, not an error. The exit
+        // code stays 0 so a `context-audit` call can never block a workflow.
+        const nextActions = result.available
+            ? [
+                `${result.entryCount} tool result(s) across ${result.groupCount} group(s); showing top ${result.entries.length}.`
+            ]
+            : [
+                `context-audit unavailable: ${result.reason ?? 'unknown'} — continue without it (read-only probe).`
+            ];
+        printResult(io, ok('code.context-audit', { ...result }, [], nextActions), opts.json);
+    }
+    catch (err) {
+        reportContextAuditFailure(io, err, opts.json);
+    }
+}
+export function registerCodeContextAuditCommand(code, io) {
+    // WHAT fills the orchestrator window. `context-now` returns a ratio; this
+    // returns the grouped byte breakdown of tool results from the live
+    // transcript. Read-only + fail-soft: an unavailable transcript reports
+    // `available:false` with a reason and NEVER sets a non-zero exit code.
+    addJsonOption(code
+        .command('context-audit')
+        .description(CONTEXT_AUDIT_DESCRIPTION)
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--top <n>', 'number of top entries to emit (default 15, max 100)', (value) => Number(value))
+        .option('--transcript <path>', 'override the transcript jsonl path (test seam)')).action((opts) => runCodeContextAudit(opts, io));
+}

package/dist/cli/commands/code-context-now-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeContextNowCommand(code: Command, io: ProgramIO): void;