peaks-loop 4.1.2 → 4.1.4

package/dist/services/code/auto-compact-decision.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The pure auto-compact decision surface: trigger, decision and plan.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe } from '../context/auto-compact-types.js';
+import { type AutoCompactMode } from './auto-compact-modes.js';
+export declare function evaluateCompactTrigger(ratio: number, mode?: AutoCompactMode): CompactTrigger;
+/**
+ * Decide whether to run the auto-compact flow. Pure function for the
+ * decision; side effects (checkpoint + IDE dispatch) live in
+ * `runAutoCompact` below. Zero human / zero LLM intervention:
+ *
+ *   - ratio < 0.85           → skip (LLM keeps working; no action)
+ *   - 0.85 ≤ ratio < 0.95    → pre-compact; if in-flight batch
+ *                                present, defer (D6.e); else dispatch
+ *                                IDE compact asynchronously.
+ *   - ratio ≥ 0.95           → red-line; ask the harness to compact
+ *                                regardless of in-flight batch. Nothing is
+ *                                gated — dispatch is NOT blocked (slice
+ *                                peaks-loop cannot compact a running session,
+ *                                so a "block" gated nothing and deadlocked the
+ *                                runner).
+ */
+export declare function evaluateAutoCompactDecision(input: {
+    ratio: number;
+    /**
+     * Caller-provided in-flight batch signal. Accepts either a plain
+     * boolean (convenience / repro seam) or the full `InFlightBatchProbe`
+     * shape (production callers — graph-probe-backed). When the boolean
+     * form is `true`, the normalized probe carries
+     * `hasInFlightBatch: true`. Slice 4.0.8 hotfix.
+     */
+    inFlightBatch?: boolean | InFlightBatchProbe | undefined;
+    /**
+     * Legacy camelCase alias for `inFlightBatch`. Production repro
+     * inputs use `inflightBatch: true|false`; the orchestrator
+     * normalizes it to the same internal shape. Slice 4.0.8 hotfix.
+     */
+    inflightBatch?: boolean | InFlightBatchProbe | undefined;
+    force?: boolean | undefined;
+    /** Accepted and ignored — see `AutoCompactInput.bypassRedLine`. */
+    bypassRedLine?: boolean | undefined;
+    mode?: AutoCompactMode | undefined;
+    /**
+     * Source tag from `readContextPercent.source`. Optional — when absent, the
+     * function behaves exactly as pre-rid (ratio-only). Slice 2026-07-31-rid-
+     * mac-transcript-estimate-trigger uses this to carry forward an explicit
+     * carve-out for the Mac-only `transcript-estimate` signal.
+     */
+    source?: string | undefined;
+}): {
+    shouldCompact: boolean;
+    reason: 'below-threshold' | 'in-flight-batch' | 'pre-compact' | 'red-line';
+    trigger: CompactTrigger;
+    /** Typed verdict enum (RD §4 24h-mode contract). Slice 4.0.8 hotfix. */
+    action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' | 'defer';
+};
+/**
+ * Build the convergence plan that D7's post-compact-detect will read
+ * back. Includes the current plan, open questions, recent decisions,
+ * todo state, and recent artifact paths — strictly more than what a
+ * raw `/compact` would preserve.
+ */
+export declare function buildConvergencePlan(input: {
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly ratio: number;
+    readonly checkpointPath: string;
+    readonly nextActions: readonly string[];
+    readonly redLine?: boolean;
+}): ConvergencePlan;

package/dist/services/code/auto-compact-decision.js

@@ -0,0 +1,149 @@
+/**
+ * The pure auto-compact decision surface: trigger, decision and plan.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { AUTO_COMPACT_PRE_COMPACT_RATIO } from '../context/auto-compact-types.js';
+import { thresholdFor } from './auto-compact-modes.js';
+/**
+ * Map a context ratio to a `CompactTrigger` action. Pure; the side
+ * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
+ * tiers (standard mode; partial mode shifts both thresholds):
+ *
+ *   - ratio < preCompact → 'none' or 'soft-warn'
+ *   - ratio ≥ preCompact → 'pre-compact' (async-friendly path)
+ *   - ratio ≥ redLine    → 'red-line' (ask the harness; dispatch continues)
+ *
+ * Default `'standard'` (0.85/0.95). `'partial'` (0.70/0.85) is used
+ * when 24h long-run mode is active or `--mode partial` is passed.
+ */
+/** Below this ratio the probe is not even worth a soft warning. */
+const SOFT_WARN_RATIO_FLOOR = 0.5;
+export function evaluateCompactTrigger(ratio, mode = 'standard') {
+    const autoFire = thresholdFor(mode, 'autoFire');
+    const preCompact = thresholdFor(mode, 'preCompact');
+    const redLine = thresholdFor(mode, 'redLine');
+    if (ratio < autoFire) {
+        return ratio < SOFT_WARN_RATIO_FLOOR
+            ? { kind: 'none' }
+            : {
+                kind: 'soft-warn',
+                ratio,
+                message: `Context at ${(ratio * 100).toFixed(1)}%; below the ${(autoFire * 100).toFixed(0)}% auto-fire threshold (mode=${mode}).`
+            };
+    }
+    if (ratio >= redLine) {
+        // longer claims it blocks anything. It cannot: peaks-loop has no
+        // executor for a running session (no `/compact` the model may invoke, no
+        // hook-initiated compact, no `--compact` flag), so "refuse dispatch until
+        // ratio < 0.85" was a gate with no key — a constructive deadlock at the
+        // exact moment the runner most needed to keep working. What peaks-loop
+        // CAN do is ask the harness (whose own trigger is armed) and say so.
+        return {
+            kind: 'red-line',
+            ratio,
+            message: `Context at ${(ratio * 100).toFixed(1)}% ≥ ${(redLine * 100).toFixed(0)}% red line (mode=${mode}). peaks-loop has asked the harness to compact and is WAITING for it — sub-agent dispatch is NOT blocked; carry on and re-probe with \`peaks code context-now\`.`
+        };
+    }
+    if (ratio < preCompact) {
+        // Part 22: auto-fire zone (0.80 ≤ ratio < 0.85). peaks-loop
+        // preempts and runs `peaks code auto-compact` itself
+        // without LLM involvement. The LLM is not asked to "decide";
+        // the toolkit is applied synchronously. Closes the
+        // LLM-misjudges-context window that previously let the
+        // ratio drift to 0.95 before the auto-fire kicked in.
+        return {
+            kind: 'auto-fire',
+            ratio,
+            message: `Context at ${(ratio * 100).toFixed(1)}% in auto-fire zone (≥${(autoFire * 100).toFixed(0)}% / <${(preCompact * 100).toFixed(0)}%, mode=${mode}). peaks-loop will fire compact without LLM confirmation.`
+        };
+    }
+    // pre-compact zone (0.85 ≤ ratio < 0.95): kept for backward
+    // compat with operators who configured the higher threshold.
+    // In practice peaks-loop already auto-fired at the lower
+    // threshold; the pre-compact zone today is the "already fired"
+    // zone.
+    return {
+        kind: 'pre-compact',
+        ratio,
+        toolkitReady: true,
+        message: `Context at ${(ratio * 100).toFixed(1)}% in pre-compact zone (≥${(preCompact * 100).toFixed(0)}% / <${(redLine * 100).toFixed(0)}%, mode=${mode}). peaks-loop already fired the auto-compact pathway at the auto-fire threshold; the LLM does not need to act.`
+    };
+}
+/**
+ * Decide whether to run the auto-compact flow. Pure function for the
+ * decision; side effects (checkpoint + IDE dispatch) live in
+ * `runAutoCompact` below. Zero human / zero LLM intervention:
+ *
+ *   - ratio < 0.85           → skip (LLM keeps working; no action)
+ *   - 0.85 ≤ ratio < 0.95    → pre-compact; if in-flight batch
+ *                                present, defer (D6.e); else dispatch
+ *                                IDE compact asynchronously.
+ *   - ratio ≥ 0.95           → red-line; ask the harness to compact
+ *                                regardless of in-flight batch. Nothing is
+ *                                gated — dispatch is NOT blocked (slice
+ *                                peaks-loop cannot compact a running session,
+ *                                so a "block" gated nothing and deadlocked the
+ *                                runner).
+ */
+export function evaluateAutoCompactDecision(input) {
+    const trigger = evaluateCompactTrigger(input.ratio, input.mode ?? 'standard');
+    // Normalize both `inFlightBatch` and `inflightBatch` (boolean | probe)
+    // into a single `InFlightBatchProbe` shape. The probe reads
+    // `hasInFlightBatch`; the boolean reads truthiness.
+    const rawProbe = input.inFlightBatch ?? input.inflightBatch;
+    const probe = typeof rawProbe === 'boolean' ? { hasInFlightBatch: rawProbe } : rawProbe;
+    if (trigger.kind === 'none') {
+        return { shouldCompact: false, reason: 'below-threshold', trigger, action: 'ok' };
+    }
+    if (trigger.kind === 'soft-warn') {
+        return { shouldCompact: false, reason: 'below-threshold', trigger, action: 'soft-warn' };
+    }
+    if (trigger.kind === 'red-line') {
+        // Red line: ignore in-flight batch — the harness is asked NOW rather than
+        // waiting for the batch to drain. Not "synchronous dispatch": peaks-loop
+        // has no synchronous compact to run, it can only request one and report
+        // that it is waiting.
+        return { shouldCompact: true, reason: 'red-line', trigger, action: 'red-line' };
+    }
+    // pre-compact zone (0.85 ≤ ratio < 0.95): honor D6.e in-flight deferral.
+    if (probe?.hasInFlightBatch === true) {
+        return { shouldCompact: false, reason: 'in-flight-batch', trigger, action: 'defer' };
+    }
+    if (input.force) {
+        return { shouldCompact: true, reason: 'pre-compact', trigger, action: 'auto-compact-now' };
+    }
+    // is the ONLY signal available on Mac Claude Code (no env-var, no statusline
+    // poll). The gate above already returns shouldCompact: true at ratio ≥ 0.85,
+    // but this forward-compat carve-out makes the source-aware rule explicit so
+    // any future source-aware downgrading cannot silently re-introduce the
+    // Mac auto-compact silent-failure mode without an audit. No higher-priority
+    // source is present (`claude-code-env` would have been P1, `statusline-poll`
+    // P2, `user-overridden` P4) — Mac's only signal is `transcript-estimate`.
+    if (input.source === 'transcript-estimate' && input.ratio >= AUTO_COMPACT_PRE_COMPACT_RATIO)
+        return { shouldCompact: true, reason: 'pre-compact', trigger, action: 'auto-compact-now' };
+    // Default: peaks-loop drives pre-compact autonomously.
+    return { shouldCompact: true, reason: 'pre-compact', trigger, action: 'auto-compact-now' };
+}
+/**
+ * Build the convergence plan that D7's post-compact-detect will read
+ * back. Includes the current plan, open questions, recent decisions,
+ * todo state, and recent artifact paths — strictly more than what a
+ * raw `/compact` would preserve.
+ */
+export function buildConvergencePlan(input) {
+    return {
+        schemaVersion: 1,
+        sessionId: input.sessionId,
+        projectRoot: input.projectRoot,
+        createdAt: new Date().toISOString(),
+        ratio: input.ratio,
+        checkpointPath: input.checkpointPath,
+        nextActions: [...input.nextActions],
+        resumeHint: input.redLine === true
+            ? 'RED-LINE compact requested from the harness; work CONTINUES (nothing is blocked). Re-probe with `peaks code context-now`; if the ratio is still ≥ 0.95 and the harness has not compacted, report it and hand control back to the user.'
+            : 'post-compact-detect shouldAutoResume → resume pre-compact plan from checkpoint'
+    };
+}

package/dist/services/code/auto-compact-dispatch-gate.d.ts

@@ -0,0 +1,36 @@
+import type { AutoCompactResult } from '../context/auto-compact-types.js';
+import type { CompactRun } from './auto-compact-run-types.js';
+/**
+ * The decision fires whenever the ratio is at or over the auto-fire threshold, and
+ * the ratio does not come back down on its own — nothing in peaks-loop can compact a
+ * running session, and the harness fires only at its own red line. So "shouldCompact"
+ * was true on every probe, forever: one real session's `compact-history.jsonl` holds
+ * 1075 dispatch rows, 444 checkpoints and ZERO compactions over 15.5 h. Re-dispatching
+ * bought nothing, because the `ide-native` dispatch only installs a PreToolUse hook
+ * and installing it again is a documented no-op: 1074 of those 1075 rows say `already
+ * installed` in their own `dispatchMessage`. It produced rows, not compactions.
+ *
+ * The lifecycle store already knows whether an attempt is outstanding (`readOpenDispatchRun`
+ * — `armed`/`compacting` = dispatched, `completed`/`failed` = over), so the gate needs no
+ * new state and no threshold: it is keyed on the STAGE of the open run, never on a ratio,
+ * which is why it survives any future realignment of the 0.65/0.70/0.85/0.95 table.
+ *
+ * What is NOT suppressed: the probe still measures and still reports. The envelope carries
+ * the LIVE ratio plus the ratio the open ask was made at, so "it crossed and it is still
+ * high, unanswered" stays legible on every turn — the difference between a quiet signal
+ * and a silenced one.
+ *
+ * `force` (the `--force` test seam, "force compact at any ratio") outranks the inference:
+ * an explicit instruction must not be silently reduced to a no-op, which would make the
+ * published flag a lie.
+ *
+ * `readOpenDispatchRun` answers in THREE states, not two. `none` admits the dispatch;
+ * `unresolvable` means the backoff's question could not be asked — the session id names
+ * no session directory, so no lifecycle record can answer it. Measured on ONE directory
+ * before this: a legal sid found the open `armed` run and suppressed the dispatch, while
+ * `./<legal sid>`, which joins to the identical path, returned `null` and dispatched. A
+ * gate that reads a string instead of the artifact the string names is the defect the
+ * whole id axis exists to close, so an unanswerable question is NOT an admit: the
+ * conservative direction is to leave the dispatch undone and say why.
+ */
+export declare function readOpenRunGate(ctx: CompactRun): AutoCompactResult | null;

package/dist/services/code/auto-compact-dispatch-gate.js

@@ -0,0 +1,86 @@
+/**
+ * The dispatch back-off: whether a compact was already asked for this crossing.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { readOpenDispatchRun } from './auto-compact-lifecycle.js';
+import { thresholdFor } from './auto-compact-modes.js';
+/**
+ * The decision fires whenever the ratio is at or over the auto-fire threshold, and
+ * the ratio does not come back down on its own — nothing in peaks-loop can compact a
+ * running session, and the harness fires only at its own red line. So "shouldCompact"
+ * was true on every probe, forever: one real session's `compact-history.jsonl` holds
+ * 1075 dispatch rows, 444 checkpoints and ZERO compactions over 15.5 h. Re-dispatching
+ * bought nothing, because the `ide-native` dispatch only installs a PreToolUse hook
+ * and installing it again is a documented no-op: 1074 of those 1075 rows say `already
+ * installed` in their own `dispatchMessage`. It produced rows, not compactions.
+ *
+ * The lifecycle store already knows whether an attempt is outstanding (`readOpenDispatchRun`
+ * — `armed`/`compacting` = dispatched, `completed`/`failed` = over), so the gate needs no
+ * new state and no threshold: it is keyed on the STAGE of the open run, never on a ratio,
+ * which is why it survives any future realignment of the 0.65/0.70/0.85/0.95 table.
+ *
+ * What is NOT suppressed: the probe still measures and still reports. The envelope carries
+ * the LIVE ratio plus the ratio the open ask was made at, so "it crossed and it is still
+ * high, unanswered" stays legible on every turn — the difference between a quiet signal
+ * and a silenced one.
+ *
+ * `force` (the `--force` test seam, "force compact at any ratio") outranks the inference:
+ * an explicit instruction must not be silently reduced to a no-op, which would make the
+ * published flag a lie.
+ *
+ * `readOpenDispatchRun` answers in THREE states, not two. `none` admits the dispatch;
+ * `unresolvable` means the backoff's question could not be asked — the session id names
+ * no session directory, so no lifecycle record can answer it. Measured on ONE directory
+ * before this: a legal sid found the open `armed` run and suppressed the dispatch, while
+ * `./<legal sid>`, which joins to the identical path, returned `null` and dispatched. A
+ * gate that reads a string instead of the artifact the string names is the defect the
+ * whole id axis exists to close, so an unanswerable question is NOT an admit: the
+ * conservative direction is to leave the dispatch undone and say why.
+ */
+export function readOpenRunGate(ctx) {
+    const { input, sessionId, probe, mode, harnessWindow } = ctx;
+    const openRun = readOpenDispatchRun({ projectRoot: input.projectRoot, sessionId });
+    if (openRun.kind === 'unresolvable' && input.force !== true) {
+        return {
+            ok: true,
+            code: 'AUTO_COMPACT_UNRESOLVED_SESSION',
+            message: `Context at ${(probe.ratio * 100).toFixed(1)}%; a compact may be warranted, but this session's ` +
+                `directory could not be resolved (${openRun.reason}), so whether a compact was already dispatched ` +
+                `for this crossing cannot be answered. Not dispatching: an unanswered question is not a 'no'. ` +
+                `The session id comes from the active binding or from the caller.`,
+            data: {
+                sessionId,
+                ratio: probe.ratio,
+                source: probe.source,
+                decision: 'unresolved-session',
+                harnessWindow
+            }
+        };
+    }
+    if (openRun.kind === 'open' && input.force !== true) {
+        return {
+            ok: true,
+            code: 'AUTO_COMPACT_ALREADY_ARMED',
+            message: `Context at ${(probe.ratio * 100).toFixed(1)}% — still above the ` +
+                `${(thresholdFor(mode, 'autoFire') * 100).toFixed(0)}% auto-fire threshold (mode=${mode}); ` +
+                `a compact was already dispatched for this crossing at ${(openRun.triggerRatio * 100).toFixed(1)}% ` +
+                `(run ${openRun.runId}, resting at '${openRun.stage}') and nothing has compacted since. ` +
+                `Not dispatching again: the trigger is already registered, so a second dispatch would install the ` +
+                `same hook and add a checkpoint and a history row without adding a capability. ` +
+                `Re-probe with \`peaks code context-now\`.`,
+            data: {
+                sessionId,
+                ratio: probe.ratio,
+                source: probe.source,
+                decision: 'already-armed',
+                armedAtRatio: openRun.triggerRatio,
+                armedRunId: openRun.runId,
+                harnessWindow
+            }
+        };
+    }
+    return null;
+}

package/dist/services/code/auto-compact-envelopes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The result envelopes `runAutoCompact` can return.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { type AutoCompactResult, type CompactDispatchResult, type ConvergencePlan } from '../context/auto-compact-types.js';
+import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
+import type { CompactRun } from './auto-compact-run-types.js';
+/** No session is bound, so there is nothing to probe. */
+export declare function noSessionResult(): AutoCompactResult;
+/** The envelope for a probe that did not cross the auto-fire threshold. */
+export declare function skipResult(ctx: CompactRun): AutoCompactResult;
+/**
+ * The envelope for a throw during preparation. It preserves the original error
+ * contract: the caller gets the `AUTO_COMPACT_DISPATCH_FAILED` shape it already
+ * handles, not a thrown exception and not a widened type.
+ */
+export declare function prepareFailureResult(ctx: CompactRun, error: unknown): AutoCompactResult;
+/** The envelope for a throw or a refusal during the IDE dispatch. */
+export declare function dispatchFailureResult(ctx: CompactRun, attempt: {
+    readonly checkpointPath: string;
+    readonly plan: ConvergencePlan;
+    readonly target: CompactTarget;
+}, error: unknown): AutoCompactResult;
+/** The envelope for a run that reached the dispatch phase. */
+export declare function compactResult(ctx: CompactRun, attempt: {
+    readonly checkpointPath: string;
+    readonly plan: ConvergencePlan;
+    readonly target: CompactTarget;
+    readonly dispatch: CompactDispatchResult;
+}): AutoCompactResult;

package/dist/services/code/auto-compact-envelopes.js

@@ -0,0 +1,134 @@
+/**
+ * The result envelopes `runAutoCompact` can return.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { DEPRECATED_ENVELOPE_FIELDS } from '../context/auto-compact-types.js';
+import { describeHarnessWindowSync, harnessWindowSyncWarning } from '../context/harness-window-config.js';
+import { describeMode, thresholdFor } from './auto-compact-modes.js';
+import { summarizeLifecycleError } from './auto-compact-lifecycle.js';
+/** No session is bound, so there is nothing to probe. */
+export function noSessionResult() {
+    return {
+        ok: false,
+        code: 'AUTO_COMPACT_NO_SESSION',
+        message: 'No active session; cannot run auto-compact. Run `peaks workspace init` first.',
+        nextActions: ['Run `peaks workspace init --change-id <id>` to bind a session']
+    };
+}
+/** The envelope for a probe that did not cross the auto-fire threshold. */
+export function skipResult(ctx) {
+    const { decision, probe, mode, harnessWindow, sessionId } = ctx;
+    return {
+        ok: true,
+        code: decision.reason === 'in-flight-batch' ? 'AUTO_COMPACT_WAIT' : 'AUTO_COMPACT_SKIP',
+        message: `${decision.trigger.kind === 'soft-warn'
+            ? decision.trigger.message
+            : decision.reason === 'in-flight-batch'
+                ? `In-flight batch detected; deferring pre-compact (ratio=${(probe.ratio * 100).toFixed(1)}%); next probe will re-evaluate.`
+                : `Context at ${(probe.ratio * 100).toFixed(1)}%; below the ${(thresholdFor(mode, 'autoFire') * 100).toFixed(0)}% auto-fire threshold (mode=${mode}).`}${
+        // No compact was needed, but the sync may still have rewritten the harness's
+        // settings (the first probe of a project always does). The notice is appended
+        // ONLY for an actual write — the other actions' sentences would be noise on
+        // every quiet probe — PLUS the one refusal that is not quiet: a refused write
+        // that leaves peaks-loop's number and the harness's pinned window disagreeing.
+        // That is the moment the ratio stops describing the harness's trigger, so
+        // staying silent is exactly the failure 要告知 exists to prevent.
+        harnessWindow !== null &&
+            harnessWindow !== undefined &&
+            (harnessWindow.action === 'written' || harnessWindowSyncWarning(harnessWindow) !== null)
+            ? ` ${describeHarnessWindowSync(harnessWindow)}`
+            : ''}`,
+        data: {
+            sessionId,
+            ratio: probe.ratio,
+            source: probe.source,
+            decision: decision.reason === 'in-flight-batch' ? 'in-flight-batch' : 'below-threshold',
+            harnessWindow
+        }
+    };
+}
+/**
+ * The envelope for a throw during preparation. It preserves the original error
+ * contract: the caller gets the `AUTO_COMPACT_DISPATCH_FAILED` shape it already
+ * handles, not a thrown exception and not a widened type.
+ */
+export function prepareFailureResult(ctx, error) {
+    const { input, sessionId, probe, mode, isRedLine, harnessWindow } = ctx;
+    return {
+        ok: false,
+        code: 'AUTO_COMPACT_DISPATCH_FAILED',
+        message: `Auto-compact preparation failed before IDE dispatch: ${summarizeLifecycleError(error)}`,
+        data: {
+            sessionId,
+            ratio: probe.ratio,
+            source: probe.source,
+            target: input.target ?? 'main',
+            mode,
+            redLineRequested: isRedLine,
+            // Compatibility alias + its record. `redLineGated` shipped from 2.13.0 to
+            // 4.0.46, so a consumer outside this repo reads it and must not start
+            // receiving `undefined`; the record is what makes the deprecation visible
+            // to that consumer. See the type.
+            redLineGated: isRedLine,
+            deprecatedFields: DEPRECATED_ENVELOPE_FIELDS,
+            harnessWindow
+        }
+    };
+}
+/** The envelope for a throw or a refusal during the IDE dispatch. */
+export function dispatchFailureResult(ctx, attempt, error) {
+    const { sessionId, probe, mode, isRedLine, harnessWindow } = ctx;
+    return {
+        ok: false,
+        code: 'AUTO_COMPACT_DISPATCH_FAILED',
+        message: `Auto-compact checkpoint written but IDE dispatch threw: ${summarizeLifecycleError(error)}`,
+        data: {
+            sessionId,
+            ratio: probe.ratio,
+            source: probe.source,
+            checkpointPath: attempt.checkpointPath,
+            convergencePlan: attempt.plan,
+            target: attempt.target,
+            mode,
+            redLineRequested: isRedLine,
+            redLineGated: isRedLine,
+            deprecatedFields: DEPRECATED_ENVELOPE_FIELDS,
+            harnessWindow
+        }
+    };
+}
+/** The envelope for a run that reached the dispatch phase. */
+export function compactResult(ctx, attempt) {
+    const { checkpointPath, plan, target, dispatch } = attempt;
+    const { probe, mode, isRedLine, harnessWindow, sessionId } = ctx;
+    return {
+        ok: dispatch.ok,
+        code: dispatch.ok
+            ? isRedLine
+                ? 'AUTO_COMPACT_RED_LINE'
+                : 'AUTO_COMPACT_DISPATCHED'
+            : 'AUTO_COMPACT_DISPATCH_FAILED',
+        message: dispatch.ok
+            ? isRedLine
+                ? `RED-LINE: harness compact REQUESTED (${dispatch.ide} / ${dispatch.pathway} / target=${target} / mode=${mode} — ${describeMode(mode)}); checkpoint at ${checkpointPath}. Sub-agent dispatch is NOT blocked — keep working and re-probe with \`peaks code context-now\`.`
+                : `Auto-compact dispatched (${dispatch.ide} / ${dispatch.pathway} / target=${target} / mode=${mode} — ${describeMode(mode)}); checkpoint at ${checkpointPath}.`
+            : `Auto-compact checkpoint written but IDE dispatch failed: ${dispatch.message}`,
+        data: {
+            sessionId,
+            ratio: probe.ratio,
+            source: probe.source,
+            checkpointPath,
+            convergencePlan: plan,
+            dispatch,
+            target,
+            mode,
+            redLineRequested: isRedLine,
+            redLineGated: isRedLine,
+            deprecatedFields: DEPRECATED_ENVELOPE_FIELDS,
+            harnessWindow
+        }
+    };
+}

package/dist/services/code/auto-compact-history.d.ts

@@ -0,0 +1,46 @@
+/**
+ * auto-compact dispatch. Appended at the end of `executeAutoCompact`
+ * so the new 'peaks compact history' CLI + the
+ * 'peaks statusline compact' indicator have a record. One file
+ * per session (gitignored under `.peaks/_runtime/<sessionId>/`).
+ */
+export interface CompactHistoryEvent {
+    readonly schemaVersion: 1;
+    readonly ts: string;
+    readonly target: 'main' | 'sub-agent' | 'worker';
+    readonly mode: 'standard' | 'partial' | 'aggressive';
+    readonly ide: string;
+    readonly pathway: string;
+    readonly beforeRatio: number;
+    readonly redLine: boolean;
+    readonly ok: boolean;
+    readonly checkpointPath: string;
+    readonly dispatchMessage: string;
+    /**
+     * instrument. `windowTokens` is the denominator peaks-loop divided by
+     * (`probe.capacityTokens`), so `beforeRatio * windowTokens` is the exact
+     * TOKEN POINT peaks-loop asked the harness to compact at. That number is
+     * the deliverable — NOT a hand-picked threshold: this slice could not run a
+     * real Claude Code session, so the real trigger point of
+     * `CLAUDE_CODE_AUTO_COMPACT_WINDOW` (documented as a window, observed to
+     * fire near the window's end) has no measured answer yet. Recording the
+     * intent lets the first real session produce one.
+     */
+    readonly windowTokens?: number | null;
+    /** Which layer produced `windowTokens` (see `ContextWindowSource`). */
+    readonly windowSource?: string | null;
+    /**
+     * `dispatch` (default, and the only kind earlier releases wrote) or
+     * `observed` — a row appended when a later probe MEASURED the ratio after
+     * a dispatched compact, proving one landed. The pair is what yields the
+     * intent-vs-observed delta.
+     */
+    readonly kind?: 'dispatch' | 'observed';
+    /** `observed` rows only: the measured post-compact ratio. */
+    readonly afterRatio?: number;
+}
+export declare function appendCompactHistoryEvent(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly event: CompactHistoryEvent;
+}): void;

package/dist/services/code/auto-compact-history.js

@@ -0,0 +1,17 @@
+/**
+ * The per-session compact-history log one run appends to.
+ *
+ * Split out of `auto-compact-orchestrator.ts` (file-size cap campaign). The
+ * orchestrator re-exports every name declared here, so existing importers keep
+ * using `./auto-compact-orchestrator.js` unchanged.
+ */
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+export function appendCompactHistoryEvent(input) {
+    const dir = getSessionDir(input.projectRoot, input.sessionId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'compact-history.jsonl');
+    appendFileSync(path, JSON.stringify(input.event) + '\n', 'utf8');
+}