peaks-loop 4.1.3 → 4.1.4

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');
+}

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

@@ -1,243 +1,14 @@
-import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe, type AutoCompactResult } from '../context/auto-compact-types.js';
-import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
-import { type AutoCompactMode } from './auto-compact-modes.js';
-import type { CompactLifecycleRecord, CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
-export interface AutoCompactInput {
-    /** Project root for context (default cwd). */
-    readonly projectRoot: string;
-    /**
-     * Caller-provided in-flight batch probe (default false). Slice
-     * 4.0.8 (D4d): production callers should pass a `probeInflightBatch`
-     * function (see below). The legacy `inFlightBatch` boolean
-     * remains as a TEST-ONLY seam — the CLI gates it behind
-     * `process.env.PEAKS_TEST_SEAM === '1'` so a production run
-     * never consults the boolean as truth.
-     */
-    readonly inFlightBatch?: InFlightBatchProbe | undefined;
-    /**
-     * Slice 4.0.8 (D4d): graph-only in-flight probe. When supplied,
-     * the orchestrator calls this function and uses the boolean
-     * result as the production `inFlightBatch` signal. The legacy
-     * boolean parameter is suppressed in production callers — the
-     * CLI's `--in-flight-batch` flag is gated behind
-     * `PEAKS_TEST_SEAM === '1'`. The pure decision function
-     * `evaluateAutoCompactDecision` retains the boolean signature
-     * for the test seam + the red-line override.
-     */
-    readonly probeInflightBatch?: (() => boolean) | undefined;
-    /**
-     * Force execute even when ratio < threshold (test seam). In
-     * production this is always `false` — peaks-loop drives compact
-     * autonomously at 0.85+ with zero human / zero LLM intervention.
-     */
-    readonly force?: boolean | undefined;
-    /**
-     * INERT — nothing reads this. It is threaded from the CLI's
-     * `--bypass-red-line` (a published flag, kept for backward compatibility;
-     * see the option's own note) down to `evaluateAutoCompactDecision`, where the
-     * red-line branch ignores it.
-     *
-     * Why nothing reads it any more: it used to skip a gate that refused to
-     * dispatch below 0.85. That gate was removed (slice
-     * compact a running session, so the refusal could not shorten the wait it
-     * was waiting for, and it deadlocked the runner at the worst moment. With the
-     * gate gone, the red line still ASKS the harness to compact (when it always
-     * did) and no longer needs a bypass. Kept as a field so the published
-     * signature does not change under callers that pass it.
-     */
-    readonly bypassRedLine?: boolean | undefined;
-    /** Current session id (default = resolve via session-id-service). */
-    readonly sessionId?: string | undefined;
-    /** Injectable env for IDE detection (test seam). */
-    readonly env?: NodeJS.ProcessEnv | undefined;
-    /** Injectable clock for mtime checks (test seam). */
-    readonly now?: Date | undefined;
-    /**
-     * the compact should target. Default `'main'` — the orchestrator
-     * (peaks-code body) runs in the main-session Claude Code window and
-     * wants to compress *its* context. Sub-agent shells pass
-     * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
-     */
-    readonly target?: CompactTarget | undefined;
-    /**
-     * `'standard'` (v2.13.0 zero-pause contract, 0.85/0.95). `'partial'`
-     * fires earlier (0.70/0.85) for 24h long-run scenarios. CLI flag
-     * `--mode <mode>` overrides the 24h-mode auto-detection.
-     */
-    readonly mode?: AutoCompactMode | undefined;
-    /**
-     * every lifecycle stage this process actually proved. Telemetry
-     * only — it can neither change the threshold decision nor the
-     * dispatch outcome, and a throwing observer is swallowed.
-     */
-    readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
-    /**
-     * Test-only injection seams for lifecycle failure paths. NEVER set in
-     * production — these exist so the unit suite can drive the `failed`
-     * transition and the store-outage branch without mocking the SUT.
-     * Each flag toggles a single, well-scoped throw at a documented point:
-     *   - `failPreparing`: throw inside the checkpoint/plan/recovery phase
-     *     (so the record rests at `failedAt: 'preparing'`)
-     *   - `failCompacting`: throw inside the IDE-dispatch phase
-     *     (so the record rests at `failedAt: 'compacting'`)
-     *   - `failLifecycleWrite`: make every lifecycle-store write throw
-     *     (so the compact envelope is proven independent of telemetry)
-     */
-    readonly testHooks?: AutoCompactTestHooks | undefined;
-}
-/**
- * Test-only injection seams. The `boolean` shape (vs. an injected error)
- * is deliberate: tests assert the *transition*, not the thrown value —
- * the value would just be a brittle fingerprint. The real error path
- * is still exercised by `summarizeLifecycleError`'s tests.
- */
-export interface AutoCompactTestHooks {
-    readonly failPreparing?: boolean | undefined;
-    readonly failCompacting?: boolean | undefined;
-    readonly failLifecycleWrite?: boolean | undefined;
-}
-/**
- * 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.
- */
-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;
-/**
- * Execute the auto-compact flow.
- *
- * Steps (orchestration):
- *   1. Resolve session id.
- *   3. Evaluate trigger via `evaluateCompactTrigger`.
- *   4. If trigger.kind === 'none' / 'soft-warn' → return skip.
- *   5. If trigger.kind === 'pre-compact' AND in-flight batch → wait.
- *   6. If trigger.kind === 'pre-compact' → async dispatch (write
- *      checkpoint + IDE compact; orchestrator returns immediately).
- *   7. If trigger.kind === 'red-line' → dispatch the IDE compact, report
- *      that the harness has been asked and that dispatch continues.
- *
- * The caller (CLI or skill body) handles the actual return — D7's
- * post-compact-detect will pick up the checkpoint on the next turn. For
- * red-line, the caller keeps working; it re-probes and, if the ratio is
- * still rising with no compact from the harness, reports that instead of
- * stalling.
- */
-export declare function runAutoCompact(input: AutoCompactInput): Promise<AutoCompactResult>;
-/** Re-export for callers that need to surface the trigger shape. */
+import type { AutoCompactResult, CompactTrigger, ConvergencePlan, InFlightBatchProbe } from '../context/auto-compact-types.js';
+import type { AutoCompactInput } from './auto-compact-run-types.js';
+export type { AutoCompactInput, AutoCompactTestHooks } from './auto-compact-run-types.js';
+export { evaluateCompactTrigger, evaluateAutoCompactDecision, buildConvergencePlan } from './auto-compact-decision.js';
+export type { CompactHistoryEvent } from './auto-compact-history.js';
+export { appendCompactHistoryEvent } from './auto-compact-history.js';
 export type { CompactTrigger, ConvergencePlan, InFlightBatchProbe, AutoCompactResult };
 /**
- * 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>/`).
+ * Execute the auto-compact flow. The caller handles the return — the post-compact
+ * detector picks the checkpoint up on the next turn. For the red line the caller keeps
+ * working: it re-probes and, if the ratio is still rising with no compact from the
+ * harness, reports that instead of stalling.
  */
-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;
+export declare function runAutoCompact(input: AutoCompactInput): Promise<AutoCompactResult>;