peaks-loop 4.0.47 → 4.0.48

package/dist/services/artifacts/request-artifact-service.js

@@ -11,6 +11,7 @@ import { ensureSession, getSessionIdCanonical } from '../session/session-manager
 // live at `shared/path-safety.ts` if this module ever needs them.
 import { getNextNumber, buildNumberedFilename, slugifyDescription } from '../../shared/incrementing-number.js';
 import { lintRequestArtifact } from './artifact-lint-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { checkTypeSanity } from '../scan/type-sanity-service.js';
 import { requireUserConfirmation } from '../mode/mode-enforcement.js';
 import { scanFileSize } from '../scan/file-size-scan.js';
@@ -27,7 +28,14 @@ export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType };
 // the local namespace under `isolatedModules`).
 import { renderTemplate } from './artifact-templates.js';
 export { formatHandoffPath, formatCommitBoundaryPath, formatSkillUsageLessonsPath } from './artifact-templates.js';
-const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * F-1 (slice 025 security): reject rids that contain path separators, null
+ * bytes, or traversal sequences. A request id is a single path segment, so
+ * anything that builds a filename from one must test it against this first —
+ * it is exported so those call sites reuse it instead of re-declaring a copy
+ * that can drift.
+ */
+export const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const VALID_ROLES = new Set(['prd', 'ui', 'rd', 'qa', 'sc']);
 function defaultClock() {
     return new Date().toISOString();
@@ -60,6 +68,13 @@ export async function createRequestArtifact(options) {
     // in the artifact body's frontmatter (under `- change-id:`) for
     // human navigation; it is no longer a filesystem path key.
     const sessionId = options.sessionId ?? await ensureSession(options.projectRoot);
+    // Sid axis. The rid axis is guarded three times above (`REQUEST_ID_PATTERN`
+    // at :110, and again in the numbered-filename path); the session id was
+    // never checked, so `--session-id ../../x` wrote the artifact outside the
+    // project root under an `ok: true` envelope.
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     // Slice 2026-06-29-change-id-root-removal: the `current-change`
     // binding file is gone. Resolution order for the change-id (file
     // body metadata) is now:
@@ -154,17 +169,12 @@ export async function createRequestArtifact(options) {
     };
 }
 function extractMetadata(markdown) {
-    let state = 'unknown';
+    const state = readArtifactState(markdown) ?? 'unknown';
     let createdAt;
     let requestType = DEFAULT_REQUEST_TYPE;
     let sessionId;
     for (const rawLine of markdown.split(/\r?\n/)) {
         const line = rawLine.trim();
-        const stateMatch = /^-\s*state:\s*(.+?)\s*$/.exec(line);
-        if (stateMatch !== null && stateMatch[1] !== undefined) {
-            state = stateMatch[1];
-            continue;
-        }
         const createdMatch = /^-\s*created:\s*(.+?)\s*$/.exec(line);
         if (createdMatch !== null && createdMatch[1] !== undefined) {
             createdAt = createdMatch[1];
@@ -343,7 +353,7 @@ async function readRequestArtifact(projectRoot, scope, role, found) {
 // the sibling `request-artifact-state-helpers.ts` module — see
 // v2.18.3 file-split for the rationale. Function signatures and
 // behaviour are unchanged (verbatim move).
-import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock, } from './request-artifact-state-helpers.js';
+import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, readArtifactState, TypeSanityViolationError, updateStatusBlock, } from './request-artifact-state-helpers.js';
 export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
 export async function transitionRequestArtifact(options) {
     if (!VALID_ROLES.has(options.role)) {

package/dist/services/artifacts/request-artifact-state-helpers.d.ts

@@ -45,6 +45,63 @@ export declare class FileSizeViolationError extends Error {
         lines: number;
     }>, threshold: number);
 }
+export interface ArtifactStateLocation {
+    /** Index of the authoritative `- state:` line, or -1 when the document has none. */
+    stateLineIndex: number;
+    /** The authoritative state, or null when `stateLineIndex` is -1. */
+    state: string | null;
+}
+/**
+ * The ONE rule for "which `state:` line is this artifact's state": the LAST
+ * one. A request artifact is an append-only log — each QA round appends a
+ * section ending in its own `## Status`, and `request transition` rewrites the
+ * newest state line in place — so the last line is the current round and the
+ * earlier ones are history.
+ *
+ * Every reader (`verify-pipeline`, `request show`, the resume detector) and the
+ * writer (`updateStatusBlock`) MUST go through this. The 2026-09-14 defect was
+ * three readers disagreeing about one file: `verify-pipeline` and the resume
+ * detector took the first match, `request show` took the last, so an artifact
+ * appended to more than once read as its first round to the checker and the
+ * resume detector while reading as its last round to the viewer and the writer.
+ *
+ * Scoping the search to the last `## Status` block was evaluated as an
+ * alternative and rejected — as a SECOND locator, not as a broken rule. It is
+ * well defined on the specimen that motivated this slice (four blocks) and
+ * returns `verdict-issued`, the right answer; and a trailing appended
+ * `- state:` line does not defeat it the way it defeats this rule — on that
+ * input the two rules disagree, and the one the block rule then disagrees with
+ * is the writer. `updateStatusBlock` rewrites the last `- state:` line wherever
+ * it sits and never moves it into the newest block, so a block-scoped reader
+ * parts company with the writer as soon as those two positions differ: the
+ * writer writes the appended line while the block reader keeps reporting the
+ * block's own line. That is this slice's reader-vs-writer divergence on a new
+ * axis. Sharing the writer's locator makes the agreement structural, not
+ * accidental.
+ *
+ * Known boundary of this rule, pinned in
+ * `request-artifact-state-authority.test.ts` rather than hidden: a process that
+ * appends a bare `- state:` line takes over the field — consistent with the
+ * writer being its only sanctioned producer.
+ *
+ * Two narrowings keep that boundary to lines the writer could have produced.
+ * A line inside a fenced code region is skipped, and the line must start at
+ * column 0. Neither is defensive decoration: a document that *describes* the
+ * state machine quotes `- state: qa-block` inside a fence, and this job's own
+ * `qa/requests/*.md` artifacts do exactly that — under the unfenced rule the
+ * quoted example was an input to the transition checker, and it survived only
+ * because the quoted copies happened not to be last. Both narrowings were
+ * measured against every `*.md` under `.peaks/` (833 files) and change no
+ * artifact's answer, and the writer already satisfies both by construction
+ * (`updateStatusBlock` writes `- state: <state>` at column 0), so reader and
+ * writer stay the same locator.
+ *
+ * Fuller record: the slice-3 section of this session's `rd/tech-doc.md` and
+ * the repair-round section of `rd/repair2-meta-integrity-fixes.md`.
+ */
+export declare function locateArtifactState(lines: ReadonlyArray<string>): ArtifactStateLocation;
+/** `locateArtifactState` over a whole document. Null when there is no `- state:` line. */
+export declare function readArtifactState(markdown: string): string | null;
 export declare function updateStatusBlock(markdown: string, newState: RequestArtifactState, timestamp: string, reason?: string): {
     updated: string;
     previousState: string;

package/dist/services/artifacts/request-artifact-state-helpers.js

@@ -75,20 +75,101 @@ export class FileSizeViolationError extends Error {
         this.threshold = threshold;
     }
 }
-export function updateStatusBlock(markdown, newState, timestamp, reason) {
-    const lines = markdown.split(/\r?\n/);
-    let previousState = 'unknown';
+/**
+ * The `- state:` line the artifact templates and `request transition` write.
+ * Anchored on both ends so a prose mention (`state: qa-block`, without the
+ * leading dash) is not read as the field, and anchored at column 0 because
+ * every writer of this field (`updateStatusBlock`, `request init`) emits it
+ * as a top-level line — an indented match is a nested list item, not the
+ * field. `locateArtifactState` applies it only outside fenced code regions.
+ */
+const STATE_LINE_RE = /^-\s*state:\s*(.+?)\s*$/;
+/** A fenced-code delimiter line: three or more backticks or tildes. */
+const FENCE_LINE_RE = /^(`{3,}|~{3,})/;
+/**
+ * The ONE rule for "which `state:` line is this artifact's state": the LAST
+ * one. A request artifact is an append-only log — each QA round appends a
+ * section ending in its own `## Status`, and `request transition` rewrites the
+ * newest state line in place — so the last line is the current round and the
+ * earlier ones are history.
+ *
+ * Every reader (`verify-pipeline`, `request show`, the resume detector) and the
+ * writer (`updateStatusBlock`) MUST go through this. The 2026-09-14 defect was
+ * three readers disagreeing about one file: `verify-pipeline` and the resume
+ * detector took the first match, `request show` took the last, so an artifact
+ * appended to more than once read as its first round to the checker and the
+ * resume detector while reading as its last round to the viewer and the writer.
+ *
+ * Scoping the search to the last `## Status` block was evaluated as an
+ * alternative and rejected — as a SECOND locator, not as a broken rule. It is
+ * well defined on the specimen that motivated this slice (four blocks) and
+ * returns `verdict-issued`, the right answer; and a trailing appended
+ * `- state:` line does not defeat it the way it defeats this rule — on that
+ * input the two rules disagree, and the one the block rule then disagrees with
+ * is the writer. `updateStatusBlock` rewrites the last `- state:` line wherever
+ * it sits and never moves it into the newest block, so a block-scoped reader
+ * parts company with the writer as soon as those two positions differ: the
+ * writer writes the appended line while the block reader keeps reporting the
+ * block's own line. That is this slice's reader-vs-writer divergence on a new
+ * axis. Sharing the writer's locator makes the agreement structural, not
+ * accidental.
+ *
+ * Known boundary of this rule, pinned in
+ * `request-artifact-state-authority.test.ts` rather than hidden: a process that
+ * appends a bare `- state:` line takes over the field — consistent with the
+ * writer being its only sanctioned producer.
+ *
+ * Two narrowings keep that boundary to lines the writer could have produced.
+ * A line inside a fenced code region is skipped, and the line must start at
+ * column 0. Neither is defensive decoration: a document that *describes* the
+ * state machine quotes `- state: qa-block` inside a fence, and this job's own
+ * `qa/requests/*.md` artifacts do exactly that — under the unfenced rule the
+ * quoted example was an input to the transition checker, and it survived only
+ * because the quoted copies happened not to be last. Both narrowings were
+ * measured against every `*.md` under `.peaks/` (833 files) and change no
+ * artifact's answer, and the writer already satisfies both by construction
+ * (`updateStatusBlock` writes `- state: <state>` at column 0), so reader and
+ * writer stay the same locator.
+ *
+ * Fuller record: the slice-3 section of this session's `rd/tech-doc.md` and
+ * the repair-round section of `rd/repair2-meta-integrity-fixes.md`.
+ */
+export function locateArtifactState(lines) {
     let stateLineIndex = -1;
-    let lastUpdateLineIndex = -1;
+    let state = null;
+    let fence = null;
     for (const [index, raw] of lines.entries()) {
-        const trimmed = raw.trim();
-        const stateMatch = /^-\s*state:\s*(.+?)\s*$/.exec(trimmed);
-        if (stateMatch !== null && stateMatch[1] !== undefined) {
-            previousState = stateMatch[1];
-            stateLineIndex = index;
+        const fenceMatch = FENCE_LINE_RE.exec(raw.trim());
+        if (fence === null) {
+            if (fenceMatch !== null) {
+                fence = fenceMatch[1][0];
+                continue;
+            }
+        }
+        else {
+            if (fenceMatch !== null && fenceMatch[1][0] === fence)
+                fence = null;
             continue;
         }
-        if (/^-\s*last update:\s*/.test(trimmed)) {
+        const match = STATE_LINE_RE.exec(raw);
+        if (match?.[1] !== undefined) {
+            stateLineIndex = index;
+            state = match[1];
+        }
+    }
+    return { stateLineIndex, state };
+}
+/** `locateArtifactState` over a whole document. Null when there is no `- state:` line. */
+export function readArtifactState(markdown) {
+    return locateArtifactState(markdown.split(/\r?\n/)).state;
+}
+export function updateStatusBlock(markdown, newState, timestamp, reason) {
+    const lines = markdown.split(/\r?\n/);
+    const { stateLineIndex, state } = locateArtifactState(lines);
+    const previousState = state ?? 'unknown';
+    let lastUpdateLineIndex = -1;
+    for (const [index, raw] of lines.entries()) {
+        if (/^-\s*last update:\s*/.test(raw.trim())) {
             lastUpdateLineIndex = index;
         }
     }

package/dist/services/audit-independent/perf-audit-service.d.ts

@@ -101,6 +101,15 @@ export declare function readPerfTemplate(projectRoot: string): string | null;
 export declare function detectPerfAudit(input: {
     readonly projectRoot: string;
     readonly sessionId: string;
+    /**
+     * The slice whose capsule this run audits. Slice
+     * `2026-09-14-prd-capsule-rid-scoping` put the rid in the capsule's
+     * filename, so a caller that knows it must pass it or the probe resolves
+     * only the pre-rid-scoping bare name. Both callers pass it:
+     * `runPerfAudit` always did, and `peaks perf-audit detect` forwards its
+     * long-standing `--rid` flag as of the post-verification repair round.
+     */
+    readonly requestId?: string;
     readonly dispatchError?: unknown;
     readonly envelope?: unknown;
 }): PerfAuditDetectResult;

package/dist/services/audit-independent/perf-audit-service.js

@@ -23,6 +23,8 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
+import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
+import { resolveHandoffPath } from '../prd/handoff-service.js';
 /**
  * Validate a raw value as a PerfAuditEnvelope. Mirrors the
  * `isSecurityAuditEnvelope` strict-shape pattern.
@@ -134,8 +136,12 @@ export function readPerfTemplate(projectRoot) {
 export function detectPerfAudit(input) {
     const warnings = [];
     const nextActions = [];
-    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
-    const handoffPresent = existsSync(handoffPath);
+    const handoffPath = resolveHandoffPath({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {})
+    });
+    const handoffPresent = handoffPath !== null;
     const templatePath = join(input.projectRoot, '.peaks', 'project-scan', 'perf-template.md');
     const templatePresent = existsSync(templatePath);
     if (!handoffPresent) {
@@ -143,7 +149,12 @@ export function detectPerfAudit(input) {
             state: 'handoff-missing',
             handoffPresent: false,
             templatePresent,
-            warnings: [`peaks-prd handoff not found at ${handoffPath}`],
+            warnings: [
+                `peaks-prd handoff not found under ${join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd')}`,
+                ...(input.requestId === undefined
+                    ? ['No --rid was supplied, so only the pre-rid-scoping `prd/handoff.md` could be probed. Pass --rid to resolve this slice\'s `prd/handoff-<rid>.md`.']
+                    : [])
+            ],
             nextActions: [
                 'Run peaks-prd handoff init to produce a sha256-locked handoff before running peaks perf-audit.',
                 'Until the handoff exists, peaks-perf-audit cannot start (gate fail).'
@@ -268,6 +279,12 @@ export function renderPerfAuditArtifact(env, opts) {
  * Returns the absolute path on success.
  */
 export function writePerfAuditArtifact(projectRoot, sessionId, rid, body) {
+    // The rid is a filename below, and the write is tmp+rename, so an
+    // unvalidated rid can OVERWRITE an arbitrary `.md` rather than merely create
+    // one. Guarded here (not only at the CLI boundary) so no caller can skip it.
+    if (!REQUEST_ID_PATTERN.test(rid)) {
+        throw new Error(`Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`);
+    }
     const targetDir = join(projectRoot, '.peaks', '_runtime', sessionId, 'audit');
     mkdirSync(targetDir, { recursive: true });
     const targetPath = join(targetDir, `perf-${rid}.md`);
@@ -290,6 +307,7 @@ export function runPerfAudit(input) {
     const detect = detectPerfAudit({
         projectRoot: input.projectRoot,
         sessionId: input.sessionId,
+        requestId: input.rid,
         ...(input.dispatchError !== undefined ? { dispatchError: input.dispatchError } : {}),
         ...(input.envelope !== undefined ? { envelope: input.envelope } : {})
     });
@@ -298,8 +316,12 @@ export function runPerfAudit(input) {
     }
     // detect.state === 'ready' implies input.envelope passed isPerfAuditEnvelope.
     const env = input.envelope;
-    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
-    const verified = readAndVerifyHandoff(handoffPath, input.projectRoot);
+    const handoffPath = resolveHandoffPath({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        requestId: input.rid
+    });
+    const verified = handoffPath === null ? null : readAndVerifyHandoff(handoffPath, input.projectRoot);
     const handoffHash = verified?.frontmatter.sha256 ?? 'unknown';
     const rendered = renderPerfAuditArtifact(env, {
         rid: input.rid,

package/dist/services/audit-independent/security-audit-service.d.ts

@@ -8,7 +8,7 @@
  * The service owns:
  *   - 5-state detection of the security-audit runtime
  *     (handoff-missing / template-missing / dispatch-failed / template-malformed / ready)
- *   - Loading + sha256 verification of the prd/handoff.md
+ *   - Loading + sha256 verification of the slice's prd/handoff-<rid>.md
  *   - Loading the project-level security-template.md
  *   - Producing the audit envelope (verdict + violations) to write
  *     to `.peaks/_runtime/<sid>/audit/security-<rid>.md`
@@ -36,7 +36,8 @@
  * 5-state detection result. Mirrors `detectEcc` in `services/code-review/ecc-bridge.ts`.
  *
  *   - `ready`              — handoff + template + project all present
- *   - `handoff-missing`    — `.peaks/_runtime/<sid>/prd/handoff.md` absent
+ *   - `handoff-missing`    — this slice's `.peaks/_runtime/<sid>/prd/handoff-<rid>.md`
+ *                        (or the pre-rid-scoping `prd/handoff.md`) absent
  *   - `template-missing`   — `.peaks/project-scan/security-template.md` absent
  *   - `dispatch-failed`    — parent LLM threw before returning the audit envelope
  *   - `envelope-malformed` — parent LLM returned a value that fails `isSecurityAuditEnvelope`
@@ -107,6 +108,15 @@ export declare function readSecurityTemplate(projectRoot: string): string | null
 export declare function detectSecurityAudit(input: {
     readonly projectRoot: string;
     readonly sessionId: string;
+    /**
+     * The slice whose capsule this run audits. Slice
+     * `2026-09-14-prd-capsule-rid-scoping` put the rid in the capsule's
+     * filename, so a caller that knows it must pass it or the probe resolves
+     * only the pre-rid-scoping bare name. Both callers pass it:
+     * `runSecurityAudit` always did, and `peaks security-audit detect` forwards
+     * its long-standing `--rid` flag as of the post-verification repair round.
+     */
+    readonly requestId?: string;
     readonly dispatchError?: unknown;
     readonly envelope?: unknown;
 }): SecurityAuditDetectResult;

package/dist/services/audit-independent/security-audit-service.js

@@ -8,7 +8,7 @@
  * The service owns:
  *   - 5-state detection of the security-audit runtime
  *     (handoff-missing / template-missing / dispatch-failed / template-malformed / ready)
- *   - Loading + sha256 verification of the prd/handoff.md
+ *   - Loading + sha256 verification of the slice's prd/handoff-<rid>.md
  *   - Loading the project-level security-template.md
  *   - Producing the audit envelope (verdict + violations) to write
  *     to `.peaks/_runtime/<sid>/audit/security-<rid>.md`
@@ -35,6 +35,8 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
+import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
+import { resolveHandoffPath } from '../prd/handoff-service.js';
 /**
  * Validate a raw value as a SecurityAuditEnvelope. Mirrors the
  * `isEccEnvelope` strict-shape pattern.
@@ -145,8 +147,12 @@ export function readSecurityTemplate(projectRoot) {
 export function detectSecurityAudit(input) {
     const warnings = [];
     const nextActions = [];
-    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
-    const handoffPresent = existsSync(handoffPath);
+    const handoffPath = resolveHandoffPath({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {})
+    });
+    const handoffPresent = handoffPath !== null;
     const templatePath = join(input.projectRoot, '.peaks', 'project-scan', 'security-template.md');
     const templatePresent = existsSync(templatePath);
     if (!handoffPresent) {
@@ -154,7 +160,12 @@ export function detectSecurityAudit(input) {
             state: 'handoff-missing',
             handoffPresent: false,
             templatePresent,
-            warnings: [`peaks-prd handoff not found at ${handoffPath}`],
+            warnings: [
+                `peaks-prd handoff not found under ${join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd')}`,
+                ...(input.requestId === undefined
+                    ? ['No --rid was supplied, so only the pre-rid-scoping `prd/handoff.md` could be probed. Pass --rid to resolve this slice\'s `prd/handoff-<rid>.md`.']
+                    : [])
+            ],
             nextActions: [
                 'Run peaks-prd handoff init to produce a sha256-locked handoff before running peaks security-audit.',
                 'Until the handoff exists, peaks-security-audit cannot start (gate fail).'
@@ -268,6 +279,12 @@ export function renderSecurityAuditArtifact(env, opts) {
  * Returns the absolute path on success.
  */
 export function writeSecurityAuditArtifact(projectRoot, sessionId, rid, body) {
+    // The rid is a filename below, and the write is tmp+rename, so an
+    // unvalidated rid can OVERWRITE an arbitrary `.md` rather than merely create
+    // one. Guarded here (not only at the CLI boundary) so no caller can skip it.
+    if (!REQUEST_ID_PATTERN.test(rid)) {
+        throw new Error(`Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`);
+    }
     const targetDir = join(projectRoot, '.peaks', '_runtime', sessionId, 'audit');
     mkdirSync(targetDir, { recursive: true });
     const targetPath = join(targetDir, `security-${rid}.md`);
@@ -290,6 +307,7 @@ export function runSecurityAudit(input) {
     const detect = detectSecurityAudit({
         projectRoot: input.projectRoot,
         sessionId: input.sessionId,
+        requestId: input.rid,
         ...(input.dispatchError !== undefined ? { dispatchError: input.dispatchError } : {}),
         ...(input.envelope !== undefined ? { envelope: input.envelope } : {})
     });
@@ -298,8 +316,12 @@ export function runSecurityAudit(input) {
     }
     // detect.state === 'ready' implies input.envelope passed isSecurityAuditEnvelope.
     const env = input.envelope;
-    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
-    const verified = readAndVerifyHandoff(handoffPath, input.projectRoot);
+    const handoffPath = resolveHandoffPath({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        requestId: input.rid
+    });
+    const verified = handoffPath === null ? null : readAndVerifyHandoff(handoffPath, input.projectRoot);
     const handoffHash = verified?.frontmatter.sha256 ?? 'unknown';
     const rendered = renderSecurityAuditArtifact(env, {
         rid: input.rid,

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

@@ -145,4 +145,123 @@ export declare function settleOpenLifecycleRun(input: {
     readonly triggerRatio: number;
     readonly afterRatio: number;
 } | null;
+/**
+ * rid `2026-09-13-compact-event-settle`: close out an open compact run because
+ * the HARNESS said one completed — `PostCompact` — rather than because a later
+ * probe noticed the ratio had fallen.
+ *
+ * WHY THIS IS A SECOND FUNCTION AND NOT A FLAG ON THE ONE ABOVE. The function
+ * above is defined by two MEASUREMENT gates: it refuses when nothing could be
+ * measured, and refuses when the number it got has not dropped far enough. Both
+ * are correct for a probe, whose ratio is an INFERENCE about whether something
+ * happened. Handed a harness event, both are wrong in the same direction —
+ * the harness has already stated that the compaction happened, so a probe that
+ * could not measure, or measured something larger, contradicts nothing. The
+ * event is the evidence; the ratio is a consequence.
+ *
+ * What survives from the probe path is the ATTRIBUTION gate, and only that:
+ * there must be an open run (`compacting` / `armed`) for this event to be
+ * about. A `PostCompact` on a session where peaks-loop never dispatched has
+ * nothing to settle — objectively, the run the event would complete does not
+ * exist. (`queued` / `preparing` are excluded for the probe path's reason: a
+ * run that died before dispatch never had a compaction to complete.)
+ *
+ * `afterRatio` is recorded ONLY when it is a genuine DROP below the ratio the
+ * dispatch was made at. Immediately after a compaction, `readContextPercent`
+ * prefers the statusline file, which may still hold the PRE-compact value; the
+ * one thing this row must not do is launder that stale reading into an
+ * `afterRatio` and publish "the context did not shrink" as a measurement. A
+ * `null` here means "no honest post-compact number was available at the moment
+ * the event fired" — and that is NOT self-healing: the record is left at
+ * `completed` with no number, `computeWindowCalibration` skips `observed` rows
+ * that carry none, and the probe path refuses a run that is no longer open. The
+ * pair is then closed by `fillEventSettledMeasurement` below — but only on the
+ * probes that reach it, which is not all of them: that call sits in the
+ * BELOW-THRESHOLD branch of `runAutoCompact` (`auto-compact-orchestrator.ts:567`
+ * guards it, `:589` calls it). A probe that instead commits to compacting does
+ * not merely defer the measurement: `advance('queued')` writes a fresh run to
+ * the same one-record-per-session store (`auto-compact-orchestrator.ts:668`), so
+ * the `completed`-without-`afterRatio` record this pair was owed is gone and the
+ * pair stays unmeasured. That loss is inherent rather than an oversight — once a
+ * second compaction has happened, no later ratio can be attributed to the first,
+ * so there is nothing honest left to fill — and it is visible as `unmeasured` in
+ * `peaks compact history` (QA residual R9). A fabricated number is not
+ * recoverable at all, which is why the stale reading is dropped rather than
+ * corrected.
+ *
+ * `verifying` is deliberately NOT emitted: its documented meaning is "we hold a
+ * measurement and are checking it", and on this path there may be no
+ * measurement at all. Emitting it would move the same untruth from the history
+ * row into the lifecycle record.
+ *
+ * Returns the settled facts, or `null` when there was nothing to settle. `null`
+ * means exactly ONE thing here — there was no OPEN run for this event to be
+ * about. A run that was open but whose record could not be written is not
+ * `null`: it returns the facts read off that run with `lifecycleWritten: false`,
+ * because a failed write is not an absent run, and a caller that cannot tell the
+ * two apart ends up telling the user a falsehood (see `compact-event-settle.ts`).
+ */
+export declare function settleOpenLifecycleRunOnCompactEvent(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly measuredRatio: number | null;
+    readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
+    /** Failure injection for the write below — the seam `CompactLifecyclePublisher` already takes. */
+    readonly failLifecycleWrite?: boolean | undefined;
+}): {
+    readonly runId: string;
+    readonly triggerRatio: number;
+    readonly afterRatio: number | null;
+    /**
+     * `false` when the run could not be marked settled — `writeCompactLifecycle`
+     * threw. The three facts above were read off the OPEN run, so they stay true
+     * and a caller may still record the observation; what it must not do is report
+     * the run as settled. `settleOpenLifecycleRun` above does not suppress its
+     * returned record on a failed write either, so the two now agree that a write
+     * failure is not "nothing happened". This field exists because this function's
+     * caller, unlike the sibling's, renders a sentence about the outcome.
+     */
+    readonly lifecycleWritten: boolean;
+} | null;
+/**
+ * rid `2026-09-13-compact-event-settle` (repair R1): supply the measurement a
+ * harness-settled run was left owing.
+ *
+ * The function above deliberately refuses to launder a post-compact reading
+ * that has not dropped — and right after a compaction that refusal is the
+ * NORMAL case, because the statusline still holds the pre-compact value. The
+ * run is then closed at `completed` with no `afterRatio`, so the dispatch's
+ * calibration pair never closes and "intent vs observed" stays blank for
+ * exactly the compactions this slice exists to witness. This function is what
+ * makes the function above's promise payable.
+ *
+ * WHY NOT WIDEN `settleOpenLifecycleRun`. That one re-emits `verifying` before
+ * `completed`, which on an already-`completed` record is a backwards stage
+ * transition with no observer to serve. This is not a settlement — the run IS
+ * settled; only the number is owed. So no stage is rewritten here.
+ *
+ * WRITING `afterRatio` ONTO THE RECORD IS THE IDEMPOTENCE TOKEN: every later
+ * probe finds it present and returns `null`, so however many probes follow, one
+ * compaction yields exactly one late measurement.
+ *
+ * THE DROP GATE IS THE EVENT PATH'S OWN (`measuredRatio < triggerRatio`), not
+ * the probe path's `autoFireThreshold`. `afterRatio` has to mean "below the
+ * ratio this run was dispatched at" — the rule the event path already enforces
+ * — or a run dispatched under the threshold (a forced or banded dispatch) would
+ * let a NON-drop through the one path that can still write a `completed` record.
+ * `conservative-fallback` is refused for the probe path's reason: its `0` is
+ * the absence of a measurement, not an empty context.
+ *
+ * Returns the filled record, or `null` when no run is owed a measurement.
+ */
+export declare function fillEventSettledMeasurement(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly measuredRatio: number;
+    readonly source: string;
+}): {
+    readonly runId: string;
+    readonly triggerRatio: number;
+    readonly afterRatio: number;
+} | null;
 export {};