peaks-loop 4.0.47 → 4.0.48

package/dist/services/config/config-rollback.js

@@ -15,7 +15,12 @@ export function planRollback() {
 export function executeRollback(opts) {
     const plan = planRollback();
     if (!plan.available) {
-        throw new Error('NO_BACKUP: ~/.peaks/config.json.1.x.bak not found');
+        // rid 2026-09-13-two-decisions ①: a machine that never migrated has no
+        // `.bak`, and that is its normal state — `--apply` on such a machine is
+        // "nothing to roll back", not a failure. Returned instead of thrown so the
+        // exit status and the `available` key agree on every path; see
+        // `config-restore.ts` for the full rationale and the accepted cost.
+        return { ...plan, applied: false };
     }
     if (!opts.apply) {
         return { ...plan, applied: false };

package/dist/services/context/harness-context-witness.d.ts

@@ -0,0 +1,310 @@
+import type { StatusLineStdin } from '../skills/skill-statusline-service.js';
+export declare const HARNESS_CONTEXT_WITNESS_FILE = "harness-context-witness.json";
+export declare const WITNESS_SCHEMA_VERSION = 2;
+/**
+ * Contributor 1 of the budget: the harness reports a rounded percentage.
+ * "Pre-calculated percentage of context window used" is not documented as
+ * fractional, so the conservative reading is an integer percent, i.e. up to
+ * ±0.5 percentage points = ±0.005 of the window. If the real payload turns out
+ * to carry decimals this term shrinks tenfold and the guard gets sharper; the
+ * assumption is visible in the first witness file, where
+ * `usageTokens / modelWindowTokens` and `usedPercentage` must agree.
+ */
+export declare const WITNESS_PERCENT_ROUNDING_FRACTION = 0.005;
+/**
+ * Contributor 2: the two sides do not sum exactly the same token quantities.
+ * MEASURED, not guessed — on 2026-09-13 the harness's own pre-compact count
+ * (963,306 tokens) exceeded peaks-loop's transcript estimate (961,658) by
+ * 1,648 tokens = 0.171%. Used as a fraction of the tokens, not of the window.
+ */
+export declare const WITNESS_NUMERATOR_FRACTION = 0.0017;
+/**
+ * The smallest window difference this guard claims to detect, and therefore
+ * the yardstick for "is this sample sharp enough to answer at all".
+ *
+ * 3% is not arbitrary: the harness compacts a native-1M model at ~967,000 by
+ * default while peaks-loop writes the model ceiling, so 1,000,000 vs 967,000 —
+ * a 3.3% difference — is the smallest real-world disagreement between the two
+ * denominators today. Anything the guard reports as "agree" while its own
+ * budget is wider than that difference is a claim it cannot support.
+ *
+ * NOTE (repair cycle 2): the constant is a floor on the SAMPLE, and the sample
+ * it floors is the WITNESS's, not peaks-loop's — a gap of this size leaves a
+ * residual proportional to the witness's ratio, so a stale (or low) witness
+ * shrinks the signal while the budget's rounding term does not shrink with it.
+ * See `sampleSupportsAgreement`, which is where this constant is applied. At
+ * zero skew it was already correctly calibrated (measured onset 0.176 of the
+ * window against a predicted 0.177); the fault was that only zero skew was
+ * correctly calibrated.
+ */
+export declare const MIN_DETECTABLE_WINDOW_DIFFERENCE = 0.03;
+/**
+ * Which of the two in-range readings of a raw percentage was taken, or that
+ * neither could be taken. `unestablished` is not a reading: the payload said a
+ * percentage and carried nothing that could settle which scale it is on.
+ */
+export type PercentageUnit = 'fraction' | 'percent' | 'unestablished';
+/**
+ * A harness context snapshot, as written to
+ * `<projectRoot>/.peaks/_runtime/<sessionId>/harness-context-witness.json`.
+ *
+ * The path is peaks-loop's own session runtime directory — deliberately NOT
+ * the harness's settings file or any other harness-owned location.
+ */
+export interface HarnessContextWitness {
+    readonly schemaVersion: number;
+    /** When peaks-loop received the render payload. */
+    readonly capturedAt: string;
+    /**
+     * `context_window.used_percentage`, normalised to 0..1. `null` when this
+     * render's payload had no percentage this module could read — the record is
+     * still written, because "a render happened and carried nothing usable" is
+     * a different fact from "nothing rendered", and the two are told apart by
+     * exactly this file existing or not.
+     */
+    readonly usedPercentage: number | null;
+    /**
+     * The payload's `used_percentage` VERBATIM, before any normalisation. Kept
+     * so a human can tell a unit misread from a real disagreement: the number
+     * above is a 0..1 fraction and this one is not, and only this one shows what
+     * the harness actually said.
+     */
+    readonly usedPercentageRaw: number | null;
+    /** Which reading `usedPercentage` was normalised from, or why none was taken. */
+    readonly usedPercentageUnit: PercentageUnit | null;
+    /** `context_window.context_window_size`. Recorded, never the comparison's denominator. */
+    readonly modelWindowTokens: number | null;
+    /**
+     * Sum of the prompt-side `context_window.current_usage` components. This is
+     * the ALIGNMENT KEY: comparing it with a probe's `rawTokens` is how the
+     * guard learns whether the two numbers describe the same API response, and
+     * therefore how much of any difference is sampling skew rather than a real
+     * disagreement. `output_tokens` is excluded so the sum is the same quantity
+     * peaks-loop's transcript estimate sums.
+     */
+    readonly usageTokens: number | null;
+    /** The harness session id from the payload, for the foreign-session check. */
+    readonly outerSessionId: string | null;
+}
+export type WitnessVerdict = 'absent' | 'foreign-session' | 'unverifiable' | 'agree' | 'disagree';
+/**
+ * Why there is no witness to compare. The first two leave the same file system
+ * state — no file — so the caller, which knows the session directory, resolves
+ * which applies and this module turns it into a sentence.
+ *
+ * The third (`unreadable`, repair cycle 3) is decided by the READ, not by the
+ * directory, and it is the reason `readHarnessWitness` returns a tagged union
+ * rather than `null`: a file that exists but cannot be used is evidence that a
+ * render DID happen, so calling it `not-rendered` names the wrong cause — the
+ * exact mis-attribution §17-B was written to remove.
+ */
+export type WitnessAbsentCause = 'session-dir-missing' | 'not-rendered' | 'unreadable';
+export interface HarnessWitnessComparison {
+    readonly verdict: WitnessVerdict;
+    /** Why the verdict is what it is, when it is not `agree` / `disagree`. */
+    readonly reason: string | null;
+    readonly harnessPct: number | null;
+    readonly peaksRatio: number;
+    /** `peaksRatio - harnessPct`; `null` when the harness side is unknown. */
+    readonly deviation: number | null;
+    /**
+     * The quantity the verdict is actually decided on: `deviation` minus the
+     * sampling skew the two token snapshots measure. Equal denominators put this
+     * at zero no matter how stale the witness is, so a non-zero residual is the
+     * window difference itself rather than the sample's age.
+     */
+    readonly residual: number | null;
+    /** The budget `residual` was tested against, as a fraction of the window. */
+    readonly tolerance: number | null;
+    readonly witnessedAt: string | null;
+    readonly witnessTokens: number | null;
+    readonly peaksTokens: number | null;
+    /** The harness's raw `used_percentage`, verbatim — see `usedPercentageRaw`. */
+    readonly witnessRawPercentage: number | null;
+    /** Which reading produced `harnessPct`, so a unit misread is visible. */
+    readonly witnessPercentageUnit: PercentageUnit | null;
+}
+/**
+ * Read the harness's context block out of a parsed statusline stdin payload.
+ * Returns `null` only when there was no payload at all (a render on a TTY, or
+ * a manual `peaks statusline`) — in which case there is nothing to record and
+ * nothing to say. A payload that arrived but carried no usable percentage is
+ * recorded, not dropped.
+ */
+export declare function parseHarnessWitness(input: {
+    readonly stdin: StatusLineStdin | null;
+    readonly nowMs: number;
+}): HarnessContextWitness | null;
+export declare function harnessWitnessPath(projectRoot: string, sessionId: string): string;
+/**
+ * Write this render's record. Returns whether a file was written.
+ *
+ * This is the ONLY side effect on the statusline render path. It is bounded
+ * (one small file, inside peaks-loop's own session directory), it cannot
+ * influence any decision peaks-loop makes (nothing except the diagnostic in
+ * `peaks code context-now` reads it), and it never throws — a statusline that
+ * fails to render because an observability file could not be written would be
+ * a worse failure than a missing observation. A failed write is not swallowed:
+ * the next probe reports `absent`, which is the visible symptom.
+ *
+ * No `mkdir`: the session directory is created by the session layer, and a
+ * statusline render is the wrong place to be creating directories. Its absence
+ * is one of the honest reasons the witness can be missing.
+ *
+ * Written via temp + rename, not in place. A reader runs in ANOTHER process
+ * (the probe) and treats unreadable JSON as "no witness" — so a torn read
+ * would not be an error, it would be a SILENT loss of the comparison, which is
+ * the failure mode this whole slice exists to remove. The rename makes the
+ * partial state unobservable. Same shape as `atomicWriteJson` in
+ * statusline-settings-service.ts.
+ *
+ * The rename is not always available: on Windows it throws EPERM while another
+ * process holds the target open, which is exactly the reader this guard is
+ * written for. Dropping the sample then would be the silent loss the temp
+ * rename was introduced to remove, so the write falls back to in-place. The
+ * fallback gives up atomicity for that one write — the reader may see a
+ * half-written file and call it "no witness" — which is a narrower failure
+ * than never recording the sample at all, and the temp path stays the normal
+ * one.
+ *
+ * A LOWER-INFORMATION RECORD DOES NOT REPLACE A HIGHER-INFORMATION ONE (repair
+ * cycle 3). The render that carries no readable percentage is still recorded
+ * when there is nothing better on disk — that is what tells "rendered, nothing
+ * usable" apart from "never rendered" (§17-B) — but it does NOT overwrite a
+ * record whose percentage IS readable. Overwriting silences a real comparison:
+ * measured 2026-09-14, a witness giving a real 3.3% window gap reported
+ * `disagree` with its sentence, and one render whose payload lacked
+ * `context_window` turned the same comparison into `unverifiable` with the
+ * sentence suppressed. A render that says less must not delete a sample that
+ * says more.
+ *
+ * AND THE PARSE IS INSIDE A TRY (repair cycle 3). The module's contract at the
+ * top of this comment — "it never throws" — was true only by inspection: the
+ * `parseHarnessWitness` call sat above the only `try`, and a payload shape the
+ * guards did not anticipate escaped the function and killed the render (see
+ * `parseHarnessWitness` for the measured case). A nested `try` rather than a
+ * wider one, because the outer catch says something different: it is the
+ * temp+rename FALLBACK, and a parse failure has no JSON to fall back TO.
+ * A payload this module cannot read is a missing observation, which is the
+ * outcome the contract already prefers.
+ */
+export declare function writeHarnessWitness(input: {
+    readonly projectRoot: string | null;
+    readonly sessionId: string | null;
+    readonly stdin: StatusLineStdin | null;
+    readonly nowMs: number;
+}): boolean;
+/**
+ * What a read found.
+ *
+ * This used to be `HarnessContextWitness | null`, which collapsed FOUR file
+ * states — absent, unreadable, not JSON, not the shape this module writes —
+ * into one `null`. The caller then had to guess the cause from the directory
+ * alone and picked `not-rendered` whenever the directory existed, so a render
+ * whose record was merely unreadable was reported as "the statusline has not
+ * rendered here": the wrong-cause sentence §17-B was written to remove. The
+ * three states are named here instead of re-derived by a second look at the
+ * disk. Same shape, and deliberately the same words (`missing` / `valid` /
+ * `invalid`), as `CompactLifecycleRead` in
+ * `src/services/compact-statusline/compact-lifecycle-store.ts`, which reads a
+ * sibling file in the same directory for the same purpose.
+ */
+export type HarnessWitnessRead = {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'valid';
+    readonly witness: HarnessContextWitness;
+} | {
+    readonly kind: 'invalid';
+};
+/**
+ * Read the record for a session. Anything that exists but cannot be used as a
+ * record reads as `invalid` — never as `missing`, which would erase the one
+ * fact the file's existence carries: a render happened here.
+ */
+export declare function readHarnessWitness(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+}): HarnessWitnessRead;
+/**
+ * The budget, in tokens: what a difference between the two ratios can be
+ * explained by WITHOUT the two denominators being different, once the
+ * sampling skew has been taken out (see `compareHarnessWitness`).
+ *
+ *   rounding     0.005 x window        — the harness's percentage is rounded
+ *   numerator    0.0017 x usedTokens   — measured disagreement of the two sums
+ *
+ * Sample skew is deliberately NOT a term here. It is not a budget at all: it
+ * is MEASURED per sample from the two token counts and SUBTRACTED from the
+ * deviation, because under equal denominators the token difference and the
+ * ratio difference are the same number — see `compareHarnessWitness`.
+ */
+export declare function witnessToleranceTokens(input: {
+    readonly windowTokens: number;
+    readonly usedTokens: number;
+}): number;
+/**
+ * Compare peaks-loop's ratio with the harness's own percentage.
+ *
+ * Two identifiers must match before any comparison is allowed:
+ *   1. the SESSION — a witness written by another harness session on the same
+ *      project is not evidence about this one. Lenient in the same direction as
+ *      the compact-event attribution: refused only when BOTH ids resolve and
+ *      differ, because a guard that turns a missing field into a permanent
+ *      "cannot tell" is the failure this whole slice exists to remove.
+ *   2. the MOMENT — a witness is a snapshot, and the harness documents that its
+ *      percentage depends on when it was calculated. The token counts are what
+ *      says whether the two numbers came from the same API response.
+ *
+ * THE MOMENT IS REMOVED, NOT BUDGETED (repair cycle 1). If the two ratios
+ * share a denominator W, the harness's count and peaks-loop's count differ by
+ * exactly the sampling skew, so
+ *
+ *     peaksRatio - harnessPct == (peaksTokens - witnessTokens) / W
+ *
+ * holds identically — it is not a tolerance to be granted, it is an equality
+ * to be tested. Budgeting the skew instead (`tolerance += |skew|`) made the
+ * budget grow by `x` while the deviation grew by `x(1+g)`, so a real window
+ * difference `g` was cancelled for every skew large enough to absorb it: a
+ * measured 3.3% denominator gap read `agree` for skew in [12,400, 22,100]
+ * tokens, and gaps up to 5.3% never surfaced at all. Subtracting the skew from
+ * the deviation and testing the remainder against a budget that contains only
+ * rounding and numerator disagreement makes the test invariant to skew by
+ * construction, and leaves `-g x harnessPct/(1+g)` — the window difference
+ * itself — as the only thing the residual can be.
+ *
+ * AND THE RESIDUAL'S SIZE IS THE WITNESS'S, NOT PEAKS-LOOP'S (repair cycle 2).
+ * `-g x harnessPct/(1+g)` carries the witness's ratio, so a witness captured
+ * while the session was small cannot show a window difference that a bigger
+ * witness would. The three answers therefore do not share one gate: a residual
+ * past the budget is a `disagree` at any witness size, while `agree` needs the
+ * sample to be sharp enough to support it (`sampleSupportsAgreement`).
+ */
+export declare function compareHarnessWitness(input: {
+    readonly witness: HarnessContextWitness | null;
+    readonly peaksRatio: number;
+    readonly peaksTokens: number | null;
+    readonly peaksWindowTokens: number | null;
+    readonly outerSessionId: string | null;
+    readonly absentCause?: WitnessAbsentCause;
+}): HarnessWitnessComparison;
+/**
+ * One-way sentence for a disagreeing witness. Advising, never asking: an
+ * auto-compact observation must never become an `AskUserQuestion` (see
+ * `.peaks/memory/auto-compact-threshold-policy.md`).
+ *
+ * The sentence states the quantity that decided it (the residual, after the
+ * measured skew was removed) and the raw harness value with the reading that
+ * was taken from it. Both are there so a reader can tell a real denominator
+ * difference from a unit misread without going back to the file.
+ */
+export declare function describeHarnessWitness(comparison: HarnessWitnessComparison): string | null;
+/** Convenience for the CLI: read + compare in one call. */
+export declare function readAndCompareHarnessWitness(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly peaksRatio: number;
+    readonly peaksTokens: number | null;
+    readonly peaksWindowTokens: number | null;
+    readonly outerSessionId: string | null;
+}): HarnessWitnessComparison;