peaks-loop 4.0.48 → 4.0.50

package/dist/services/feedback/promotion-artifact-evidence.d.ts

@@ -0,0 +1,69 @@
+/**
+ * rid 2026-09-14-gate-h-promotion (R2; repaired by R8) — what a promotion's
+ * artifact has to PROVE.
+ *
+ * The three layers used to be checked with `text.includes(<rule name>)` over the
+ * whole file. A substring test cannot tell "the rule is registered" from "a
+ * comment saying the rule is absent", so a refusal tree passed every layer:
+ *
+ *   - layer A: a `.peaks/sops/registry.json` that is not valid JSON, with the id
+ *     still somewhere in its bytes;
+ *   - layer B: a settings template whose only mention of the rule reads
+ *     "do NOT add a matcher for <rule>";
+ *   - layer C: a `mode-gate.ts` whose only mention reads
+ *     "// TODO: <rule> is DELIBERATELY NOT a hard-floor category".
+ *
+ * All three are the same defect facing the other way: an unreadable artifact is
+ * treated as a permitted one. Each check below therefore parses its evidence and
+ * asserts the SHAPE, and every failure is a finding — never a warning that
+ * permits. Nothing here throws: an unparseable file is reported, not swallowed.
+ *
+ * R8 (same rid) — the same defect survived inside R2's repair, in two places:
+ *
+ *   - layer C matched a member's `doc` by name MENTION, so an adverse line
+ *     sitting between two vocabulary members became the following member's doc
+ *     and the verdict flipped on where the comment sat. The predicate is now this
+ *     repo's own citation form — the memory cited by PATH,
+ *     `.peaks/memory/<id>.md`, exactly as `mode-gate.ts:41` does — rather than
+ *     the memory merely named. That citation requirement is what closes the
+ *     placement dependence; the doc is also read from the comment SPANS attached
+ *     to the member rather than from the raw slice, which states "code is not a
+ *     doc" as an invariant rather than relying on the raw slice to honour it;
+ *   - layer B kept `matcher.includes(id)` / `command.includes(id)` over free
+ *     text, so `command: "echo 'do NOT add a matcher for rule-x'"` registered a
+ *     rule by writing a sentence about it. Both fields are now parsed: a matcher
+ *     is a tool selector, a command is argv.
+ *
+ * R10 (same rid) — layer C read the `HardFloorCategory` union and the
+ * `HARD_FLOOR_CATEGORIES` array as ONE flattened member list, so a member of the
+ * union alone satisfied the check. Measured on the R8 bytes: a union-only literal
+ * — and a union-only member whose doc cited `.peaks/memory/<id>.md` — were both
+ * reported BACKED, while `isHardFloorCategory` (which reads the array) returned
+ * false and `shouldPauseAtGate` returned `shouldPause: false`. The gate certified
+ * a hard floor that paused nothing, contradicting its own message. Only the array
+ * enforces, so only the array is now evidence — for the name and for the citation
+ * alike. The union is still READ, for one reason only: a category's doc belongs
+ * to the category, and this repo documents `commit-boundary-side-effect` beside
+ * the union member while the array enforces it.
+ */
+export type PromotionEvidence = 
+/** A SOP manifest: a JSON object whose `id` is the SOP's and whose `gates` is an array. */
+'sop-manifest'
+/** An entry with the SOP's `id` inside `<registry>.sops[]` — what `readRegistry()` enumerates. */
+ | 'sop-registry-entry'
+/** A hook registration (hook command) inside `hooks` that runs something named after the rule. */
+ | 'hook-registration'
+/** A member of `HARD_FLOOR_CATEGORIES` — the array `isHardFloorCategory` reads — that names the rule. */
+ | 'hard-floor-category';
+export type PromotionArtifactCheck = {
+    /** Project-relative POSIX path whose CONTENT must carry the evidence. */
+    path: string;
+    evidence: PromotionEvidence;
+    /** The rule id the evidence must name (a SOP id for layer A, a memory name for B and C). */
+    id: string;
+};
+/**
+ * The reason `check` is unsatisfied by `text`, or `null` when it is satisfied.
+ * Never throws: a file that cannot be parsed yields the reason it could not be.
+ */
+export declare function artifactEvidenceFailure(check: PromotionArtifactCheck, text: string): string | null;

package/dist/services/feedback/promotion-artifact-evidence.js

@@ -0,0 +1,332 @@
+/**
+ * rid 2026-09-14-gate-h-promotion (R2; repaired by R8) — what a promotion's
+ * artifact has to PROVE.
+ *
+ * The three layers used to be checked with `text.includes(<rule name>)` over the
+ * whole file. A substring test cannot tell "the rule is registered" from "a
+ * comment saying the rule is absent", so a refusal tree passed every layer:
+ *
+ *   - layer A: a `.peaks/sops/registry.json` that is not valid JSON, with the id
+ *     still somewhere in its bytes;
+ *   - layer B: a settings template whose only mention of the rule reads
+ *     "do NOT add a matcher for <rule>";
+ *   - layer C: a `mode-gate.ts` whose only mention reads
+ *     "// TODO: <rule> is DELIBERATELY NOT a hard-floor category".
+ *
+ * All three are the same defect facing the other way: an unreadable artifact is
+ * treated as a permitted one. Each check below therefore parses its evidence and
+ * asserts the SHAPE, and every failure is a finding — never a warning that
+ * permits. Nothing here throws: an unparseable file is reported, not swallowed.
+ *
+ * R8 (same rid) — the same defect survived inside R2's repair, in two places:
+ *
+ *   - layer C matched a member's `doc` by name MENTION, so an adverse line
+ *     sitting between two vocabulary members became the following member's doc
+ *     and the verdict flipped on where the comment sat. The predicate is now this
+ *     repo's own citation form — the memory cited by PATH,
+ *     `.peaks/memory/<id>.md`, exactly as `mode-gate.ts:41` does — rather than
+ *     the memory merely named. That citation requirement is what closes the
+ *     placement dependence; the doc is also read from the comment SPANS attached
+ *     to the member rather than from the raw slice, which states "code is not a
+ *     doc" as an invariant rather than relying on the raw slice to honour it;
+ *   - layer B kept `matcher.includes(id)` / `command.includes(id)` over free
+ *     text, so `command: "echo 'do NOT add a matcher for rule-x'"` registered a
+ *     rule by writing a sentence about it. Both fields are now parsed: a matcher
+ *     is a tool selector, a command is argv.
+ *
+ * R10 (same rid) — layer C read the `HardFloorCategory` union and the
+ * `HARD_FLOOR_CATEGORIES` array as ONE flattened member list, so a member of the
+ * union alone satisfied the check. Measured on the R8 bytes: a union-only literal
+ * — and a union-only member whose doc cited `.peaks/memory/<id>.md` — were both
+ * reported BACKED, while `isHardFloorCategory` (which reads the array) returned
+ * false and `shouldPauseAtGate` returned `shouldPause: false`. The gate certified
+ * a hard floor that paused nothing, contradicting its own message. Only the array
+ * enforces, so only the array is now evidence — for the name and for the citation
+ * alike. The union is still READ, for one reason only: a category's doc belongs
+ * to the category, and this repo documents `commit-boundary-side-effect` beside
+ * the union member while the array enforces it.
+ */
+/** Is `value` a JSON object (not null, not an array)? */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function manifestFailure(parsed, id) {
+    if (!isRecord(parsed))
+        return 'not a JSON object';
+    if (parsed.id !== id)
+        return `does not declare id "${id}"`;
+    if (!Array.isArray(parsed.gates))
+        return 'has no "gates" array';
+    return null;
+}
+function registryFailure(parsed, id) {
+    if (!isRecord(parsed))
+        return 'not a JSON object';
+    if (!Array.isArray(parsed.sops))
+        return 'has no "sops" array';
+    const registered = parsed.sops.some((entry) => isRecord(entry) && entry.id === id);
+    return registered ? null : `registry has no SOP entry with id "${id}"`;
+}
+/**
+ * A tool selector: `Name` or `Name(pattern)`, one or more separated by `|` —
+ * `Bash`, `Write|Edit|MultiEdit`, `Bash(git push:*)`. A segment that is not a
+ * tool-name token (a hyphenated rule name, say) makes the selector malformed.
+ */
+const MATCHER_SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*\s*(\(.*\))?$/;
+function isToolMatcher(matcher) {
+    const segments = matcher.split('|');
+    return segments.every((segment) => MATCHER_SEGMENT_RE.test(segment.trim()));
+}
+/**
+ * Split a hook command the way a shell does: whitespace separates words, and
+ * quotes group whitespace INTO a word rather than ending it. So a phrase inside
+ * a string literal arrives as one long word, while a path arrives short.
+ */
+function commandWords(command) {
+    const words = [];
+    let current = '';
+    let started = false;
+    let quote = null;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        if (char === '\\' && quote !== "'" && i + 1 < command.length) {
+            current += command[i + 1];
+            started = true;
+            i += 1;
+            continue;
+        }
+        if (quote !== null) {
+            if (char === quote)
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (started)
+                words.push(current);
+            current = '';
+            started = false;
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (started)
+        words.push(current);
+    return words;
+}
+const SCRIPT_EXTENSION_RE = /\.(?:c|m)?[jt]s$|\.(?:sh|bash|ps1|py|rb)$/i;
+/**
+ * Does this hook `command` RUN something named after the rule?
+ *
+ * A command is argv, not prose. The rule counts only when its name sits inside a
+ * single word that (a) is not a phrase — no embedded whitespace, so a sentence
+ * inside a string literal is out — and (b) designates a file the hook executes:
+ * a path, or a script by extension.
+ *
+ * `echo 'do NOT add a matcher for rule-x'` parses to two words, the second of
+ * which holds the rule's name and four spaces: a sentence ABOUT the rule, not an
+ * invocation of it. `node scripts/enforce-rule-x.js` parses to two words, the
+ * second a path. That difference is the check.
+ */
+function commandRegistersRule(command, id) {
+    return commandWords(command).some((word) => {
+        if (/\s/.test(word))
+            return false;
+        if (!word.includes(id))
+            return false;
+        return word.includes('/') || word.includes('\\') || SCRIPT_EXTENSION_RE.test(word);
+    });
+}
+/**
+ * Layer B. A hook group is `{ matcher?, hooks: [...] }`. The matcher SELECTS
+ * TOOLS, so it can never name a rule: a group whose selector is not a tool
+ * matcher fires nothing and registers nothing. The registration itself is a hook
+ * command that runs something named after the rule — prose elsewhere in the file
+ * (an `env` note saying "do NOT add a matcher") is not a registration, and
+ * neither is a sentence in a command.
+ */
+function hookFailure(parsed, id) {
+    if (!isRecord(parsed))
+        return 'not a JSON object';
+    if (!isRecord(parsed.hooks))
+        return 'has no "hooks" object';
+    for (const groups of Object.values(parsed.hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isRecord(group))
+                continue;
+            if (typeof group.matcher === 'string' && !isToolMatcher(group.matcher))
+                continue;
+            const hooks = group.hooks;
+            if (!Array.isArray(hooks))
+                continue;
+            const registers = hooks.some((h) => isRecord(h) && typeof h.command === 'string' && commandRegistersRule(h.command, id));
+            if (registers)
+                return null;
+        }
+    }
+    return `no hook registration runs anything named "${id}" (a hook command must invoke a file named after the rule)`;
+}
+/**
+ * One pattern, used by BOTH the masker and the doc reader, so a comment can
+ * never be blanked by one and read as a doc by the other.
+ */
+const COMMENT_RE = /\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
+/** Comments are blanked to spaces, which keeps every offset in the file valid. */
+function maskComments(text) {
+    return text.replace(COMMENT_RE, (comment) => ' '.repeat(comment.length));
+}
+function commentSpans(source) {
+    const spans = [];
+    COMMENT_RE.lastIndex = 0;
+    let match;
+    while ((match = COMMENT_RE.exec(source)) !== null) {
+        spans.push({ start: match.index, end: match.index + match[0].length, text: match[0] });
+    }
+    return spans;
+}
+/**
+ * Collect the members of the hard-floor vocabulary, each with the comment text
+ * that governs it. `masked` decides where a member STARTS (so a quoted string
+ * inside a comment is not a member, and no comment can inject the `;` / `]` that
+ * bounds a declaration); the doc is read from the comment SPANS inside the
+ * member's slot. Taking it from the raw slice instead — as R2 did — let CODE
+ * between two members become a doc, which is what made the verdict depend on
+ * where an adverse line sat.
+ */
+function collectMembers(masked, comments, start, end, enforcing, out) {
+    const body = masked.slice(start, end);
+    const literalRe = /'([^']*)'/g;
+    let match;
+    let previousEnd = 0;
+    while ((match = literalRe.exec(body)) !== null) {
+        // A member literal is preceded by nothing but whitespace, a `|` (union) or a
+        // `,` (array). Anything else — a `'` inside prose, say — is not a member.
+        if (/^[\s|,]*$/.test(body.slice(previousEnd, match.index))) {
+            const from = start + previousEnd;
+            const to = start + match.index;
+            out.push({
+                literal: match[1],
+                doc: comments
+                    .filter((comment) => comment.start >= from && comment.end <= to)
+                    .map((comment) => comment.text)
+                    .join('\n'),
+                enforcing
+            });
+        }
+        previousEnd = match.index + match[0].length;
+    }
+}
+/**
+ * The two declarations that spell the vocabulary: the `HardFloorCategory` union
+ * (a type) and `HARD_FLOOR_CATEGORIES` (the array `isHardFloorCategory` reads).
+ * They are the same vocabulary, but only the ARRAY enforces — see
+ * `mergeByLiteral` for why the union is still read.
+ */
+function vocabularyMembers(source) {
+    const masked = maskComments(source);
+    const comments = commentSpans(source);
+    const raw = [];
+    const union = /export\s+type\s+HardFloorCategory\s*=/.exec(masked);
+    if (union) {
+        const start = union.index + union[0].length;
+        const end = masked.indexOf(';', start);
+        if (end > start)
+            collectMembers(masked, comments, start, end, false, raw);
+    }
+    const array = /HARD_FLOOR_CATEGORIES\s*:/.exec(masked);
+    if (array) {
+        const equals = masked.indexOf('=', array.index);
+        const open = masked.indexOf('[', equals);
+        const close = masked.indexOf(']', open + 1);
+        if (equals > array.index && open > equals && close > open) {
+            collectMembers(masked, comments, open + 1, close, true, raw);
+        }
+    }
+    return mergeByLiteral(raw);
+}
+/**
+ * R10 — one entry per literal, and `enforcing` is only ever set by the array.
+ *
+ * Reading the two declarations as one flat member list let a member of the
+ * `HardFloorCategory` union ALONE satisfy this check while
+ * `isHardFloorCategory` — and therefore `shouldPauseAtGate` — did not recognise
+ * it. The gate reported BACKED for a hard floor that paused nothing. Splitting
+ * the provenance of `enforcing` out of the member list is what makes the two
+ * agree: what the predicate accepts is exactly what the array contains.
+ *
+ * The docs are joined across occurrences rather than kept per-declaration,
+ * because a category's doc belongs to the CATEGORY. This repo's own layer-C
+ * promotion cites `.peaks/memory/2026-06-28-full-auto-boundary.md` from the
+ * comment beside the UNION member of `commit-boundary-side-effect`, while the
+ * ARRAY is what enforces it; reading the doc from one declaration only would
+ * make that citation unreadable — a false negative on a file already known good.
+ */
+function mergeByLiteral(members) {
+    const merged = new Map();
+    for (const member of members) {
+        const previous = merged.get(member.literal);
+        merged.set(member.literal, {
+            literal: member.literal,
+            doc: [previous?.doc, member.doc].filter((doc) => doc !== undefined && doc !== '').join('\n'),
+            enforcing: (previous?.enforcing ?? false) || member.enforcing
+        });
+    }
+    return [...merged.values()];
+}
+/** A memory cited by path, the way this repo cites one (`mode-gate.ts:41`). */
+const MEMORY_CITATION_RE = /\.peaks\/memory\/([A-Za-z0-9._-]+)\.md/g;
+function citedMemories(doc) {
+    return Array.from(doc.matchAll(MEMORY_CITATION_RE), (match) => match[1]);
+}
+/**
+ * Layer C. The rule counts when it IS a member of `HARD_FLOOR_CATEGORIES`, or
+ * when one of THAT ARRAY's members has a doc block that CITES it the way this
+ * repo cites a memory — by path: `commit-boundary-side-effect` cites
+ * `.peaks/memory/2026-06-28-full-auto-boundary.md`.
+ *
+ * R10 — both clauses are gated on `enforcing`. Certifying membership in the
+ * `HardFloorCategory` union alone is what let the check report BACKED for a
+ * category that `isHardFloorCategory` rejects and `shouldPauseAtGate` ignores.
+ *
+ * A citation is a deliberate act with a shape; a name is a word that any
+ * sentence can carry. `// TODO: <rule> is DELIBERATELY NOT a hard-floor
+ * category` names the rule while saying the opposite, and is rejected in every
+ * placement — the predicate never reads the sentence the citation sits in, so
+ * prose that negates a citation is a residual this cannot see. What it does see
+ * is the difference between being cited and being mentioned.
+ */
+function hardFloorFailure(source, id) {
+    const registered = vocabularyMembers(source).some((member) => member.enforcing && (member.literal === id || citedMemories(member.doc).includes(id)));
+    return registered
+        ? null
+        : `no hard-floor category names "${id}" (it must be a member of HARD_FLOOR_CATEGORIES, or cited by one as ".peaks/memory/${id}.md")`;
+}
+/**
+ * The reason `check` is unsatisfied by `text`, or `null` when it is satisfied.
+ * Never throws: a file that cannot be parsed yields the reason it could not be.
+ */
+export function artifactEvidenceFailure(check, text) {
+    if (check.evidence === 'hard-floor-category')
+        return hardFloorFailure(text, check.id);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return `not valid JSON: ${err.message}`;
+    }
+    if (check.evidence === 'sop-manifest')
+        return manifestFailure(parsed, check.id);
+    if (check.evidence === 'sop-registry-entry')
+        return registryFailure(parsed, check.id);
+    return hookFailure(parsed, check.id);
+}

package/dist/services/final-review/pre-post-diff.js

@@ -123,13 +123,21 @@ function isSourcePath(path) {
  * read as two deleted cases; a class that is half-counted is worse than a class
  * that is not counted at all.
  *
+ * Word-boundary simulation, not `\b`. The JS regex could spell this as `\b`
+ * directly, but the POSIX ERE side of the count has to run on macOS too —
+ * where `git grep -E` is BSD grep, and BSD grep's POSIX ERE has no `\b`
+ * (it is a literal `b`). The two expressions therefore both spell the boundary
+ * as `(^|[^A-Za-z0-9_])`: start of line OR a non-word character. The two
+ * sides MUST agree, and `git grep -c` counts matched lines (not occurrences)
+ * so the extra prefix group does not shift the count.
+ *
  * What is deliberately NOT modelled: an occurrence inside a comment or a string
  * literal still matches. That is symmetric — the same expression is evaluated on
  * both sides — so it cancels out of the DELTA, which is the only thing a removal
  * is ever derived from.
  */
-const TEST_CASE_LINE_RE = /\b(it|test)(\.[A-Za-z]+)*\(/;
-const TEST_CASE_ERE = '\\b(it|test)(\\.[A-Za-z]+)*\\(';
+const TEST_CASE_LINE_RE = /(?:^|[^A-Za-z0-9_])(it|test)(\.[A-Za-z]+)*\(/;
+const TEST_CASE_ERE = '(^|[^A-Za-z0-9_])(it|test)(\\.[A-Za-z]+)*\\(';
 /**
  * Column-0 `export` — an export STATEMENT, not a type-checked symbol.
  *

package/dist/services/job/job-progress-store.js

@@ -22,6 +22,21 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
+import { guardRuntimeSegment, runtimeRoot } from '../../shared/runtime-root.js';
+/**
+ * The single place a job-progress directory is built, and therefore the single
+ * place the two ids that reach it are guarded.
+ *
+ * Slice 2026-09-15 (runtime-path-unrepresentable): this join used to be written
+ * at three sites, none of them guarded, and the shipped text rule could not see
+ * them — they sit in the service layer, outside the command layer it scans.
+ * Both ids are caller-supplied (`peaks job checkpoint` takes them from flags).
+ * The seam now requires `GuardedSegment`, so dropping either guard is a compile
+ * error rather than a finding someone has to notice.
+ */
+function jobProgressDir(projectRoot, sessionId, jobId) {
+    return runtimeRoot(projectRoot).join(guardRuntimeSegment(sessionId, 'session id'), guardRuntimeSegment('job', 'role'), guardRuntimeSegment(jobId, 'job id'));
+}
 export const JOB_PROGRESS_SCHEMA_VERSION = 1;
 export const JobProgressSchema = z.object({
     schemaVersion: z.literal(JOB_PROGRESS_SCHEMA_VERSION),
@@ -33,7 +48,7 @@ export const JobProgressSchema = z.object({
     updatedAt: z.string().datetime()
 });
 export function writeJobProgress(projectRoot, sessionId, input) {
-    const dir = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', input.jobId);
+    const dir = jobProgressDir(projectRoot, sessionId, input.jobId);
     mkdirSync(dir, { recursive: true });
     const record = {
         schemaVersion: JOB_PROGRESS_SCHEMA_VERSION,
@@ -49,7 +64,7 @@ export function writeJobProgress(projectRoot, sessionId, input) {
     return record;
 }
 export function readJobProgress(projectRoot, sessionId, jobId) {
-    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    const path = join(jobProgressDir(projectRoot, sessionId, jobId), 'progress.json');
     if (!existsSync(path)) {
         throw new Error(`JobProgressStore: no progress for ${jobId} at ${path}`);
     }
@@ -57,7 +72,7 @@ export function readJobProgress(projectRoot, sessionId, jobId) {
     return JobProgressSchema.parse(JSON.parse(raw));
 }
 export function tryReadJobProgress(projectRoot, sessionId, jobId) {
-    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    const path = join(jobProgressDir(projectRoot, sessionId, jobId), 'progress.json');
     if (!existsSync(path))
         return null;
     try {

package/dist/services/observability/jsonl-store.d.ts

@@ -21,6 +21,19 @@ export declare const MAX_METRICS_FILES = 10;
 export declare function metricsFilePath(projectRoot: string, sessionId: string): string;
 /** Absolute path to a session's metrics directory. */
 export declare function metricsDirPath(projectRoot: string, sessionId: string): string;
+/**
+ * Absolute path to a session's metrics JSONL file, or `null` when the
+ * session id names no session directory.
+ *
+ * Total sibling of `metricsFilePath`, built on the axis's own total
+ * entry (`tryGetSessionDir`) so the two agree on the predicate. It
+ * exists because this module has frames whose contract is never-throws
+ * (`readMetricLines`, and through it `readObservabilityEvents`) and
+ * `metricsFilePath` was the one call in them that could still throw.
+ * `null` here means exactly one thing — the id could not be resolved —
+ * and every caller below handles it in the same statement that reads it.
+ */
+export declare function tryMetricsFilePath(projectRoot: string, sessionId: string): string | null;
 /**
  * Append one line to the session's metrics JSONL file. Creates the
  * directory tree on demand. Returns true on success, false on any
@@ -32,6 +45,12 @@ export declare function appendMetricLine(projectRoot: string, sessionId: string,
  * Returns [] when the file does not exist. Does NOT parse — callers
  * decide what counts as valid (see `observability-service.ts`
  * `readObservabilityEvents` for the schema-aware reader).
+ *
+ * Returns [] for an unresolvable session id too: this is the read half
+ * of a fire-and-forget store, and `readObservabilityEvents` documents
+ * that a session with no readable metrics file has no events. Throwing
+ * here used to escape as a raw guard error out of a documented
+ * never-throws reader (repair R6).
  */
 export declare function readMetricLines(projectRoot: string, sessionId: string): string[];
 export type SessionMetricsEntry = {

package/dist/services/observability/jsonl-store.js

@@ -16,7 +16,7 @@
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { getSessionDir } from '../session/getSessionDir.js';
+import { getSessionDir, tryGetSessionDir } from '../session/getSessionDir.js';
 export const METRICS_DIR = 'metrics';
 export const METRICS_FILENAME = 'slices.jsonl';
 export const MAX_METRICS_FILES = 10;
@@ -28,6 +28,22 @@ export function metricsFilePath(projectRoot, sessionId) {
 export function metricsDirPath(projectRoot, sessionId) {
     return join(getSessionDir(projectRoot, sessionId), METRICS_DIR);
 }
+/**
+ * Absolute path to a session's metrics JSONL file, or `null` when the
+ * session id names no session directory.
+ *
+ * Total sibling of `metricsFilePath`, built on the axis's own total
+ * entry (`tryGetSessionDir`) so the two agree on the predicate. It
+ * exists because this module has frames whose contract is never-throws
+ * (`readMetricLines`, and through it `readObservabilityEvents`) and
+ * `metricsFilePath` was the one call in them that could still throw.
+ * `null` here means exactly one thing — the id could not be resolved —
+ * and every caller below handles it in the same statement that reads it.
+ */
+export function tryMetricsFilePath(projectRoot, sessionId) {
+    const resolved = tryGetSessionDir(projectRoot, sessionId);
+    return resolved.ok ? join(resolved.dir, METRICS_DIR, METRICS_FILENAME) : null;
+}
 /**
  * Append one line to the session's metrics JSONL file. Creates the
  * directory tree on demand. Returns true on success, false on any
@@ -51,9 +67,18 @@ export function appendMetricLine(projectRoot, sessionId, line) {
  * Returns [] when the file does not exist. Does NOT parse — callers
  * decide what counts as valid (see `observability-service.ts`
  * `readObservabilityEvents` for the schema-aware reader).
+ *
+ * Returns [] for an unresolvable session id too: this is the read half
+ * of a fire-and-forget store, and `readObservabilityEvents` documents
+ * that a session with no readable metrics file has no events. Throwing
+ * here used to escape as a raw guard error out of a documented
+ * never-throws reader (repair R6).
  */
 export function readMetricLines(projectRoot, sessionId) {
-    const path = metricsFilePath(projectRoot, sessionId);
+    const path = tryMetricsFilePath(projectRoot, sessionId);
+    if (path === null) {
+        return [];
+    }
     if (!existsSync(path)) {
         return [];
     }

package/dist/services/observability/observability-service.d.ts

@@ -29,8 +29,8 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
     ts: z.ZodString;
     sessionId: z.ZodString;
     category: z.ZodEnum<{
-        dispatch: "dispatch";
         "slice-transition": "slice-transition";
+        dispatch: "dispatch";
         checkpoint: "checkpoint";
         "mode-gate": "mode-gate";
         "context-trigger": "context-trigger";
@@ -56,11 +56,15 @@ export type EmitOptions = {
     /** Absolute path to the project root (where `.peaks/_runtime/` lives). */
     projectRoot: string;
 };
-export type EmitFailureReason = 'invalid-schema' | 'write-failed';
+export type EmitFailureReason = 'invalid-schema' | 'write-failed' | 'invalid-session-id';
 export type EmitResult = {
     /** True when the JSONL line was appended; false on any error path. */
     written: boolean;
-    /** Absolute path to the metrics file the event was written to (or would be). */
+    /**
+     * Absolute path to the metrics file the event was written to (or would
+     * be). Empty string when the session id named no session directory —
+     * there is no path to report, and `reason` says so.
+     */
     path: string;
     /** Set only when `written` is false. */
     reason?: EmitFailureReason;
@@ -81,7 +85,10 @@ export declare function emitObservabilityEvent(event: ObservabilityEvent, option
  * lines and any record whose `schemaVersion` does not match the
  * current `OBSERVABILITY_SCHEMA_VERSION` (forward-compat per Q3).
  *
- * Returns [] when the session has no metrics file yet.
+ * Returns [] when the session has no metrics file yet, and [] when the
+ * session id names no session directory — both are "no events are
+ * readable here", and this reader does not throw (repair R6: it used to,
+ * via `readMetricLines` → `metricsFilePath`).
  */
 export declare function readObservabilityEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];
 /**

package/dist/services/observability/observability-service.js

@@ -19,7 +19,7 @@
  * result (fire-and-forget by convention).
  */
 import { z } from 'zod';
-import { appendMetricLine, metricsFilePath, pruneMetricsFiles, readMetricLines } from './jsonl-store.js';
+import { appendMetricLine, pruneMetricsFiles, readMetricLines, tryMetricsFilePath } from './jsonl-store.js';
 export const OBSERVABILITY_SCHEMA_VERSION = 1;
 export const OBSERVABILITY_CATEGORIES = [
     'slice-transition',
@@ -74,7 +74,17 @@ export const ObservabilityEventSchema = z.object({
  * session count is below `MAX_METRICS_FILES`.
  */
 export function emitObservabilityEvent(event, options) {
-    const path = metricsFilePath(options.projectRoot, event.sessionId);
+    // The session id is resolved through the axis's TOTAL entry, before anything
+    // else. The contract two doc comments above is that this function never
+    // throws; the previous first line called the axis's THROWING entry, so an
+    // unsafe session id made it throw — measured (repair R4) as
+    // `Invalid session id: ../../../../RD-R4-PWNED`, against a legal control
+    // that returned `written: true`. A guard refusal is a failure like any
+    // other here: it becomes a reason, not an exception.
+    const path = tryMetricsFilePath(options.projectRoot, event.sessionId);
+    if (path === null) {
+        return { written: false, path: '', reason: 'invalid-session-id' };
+    }
     const validation = ObservabilityEventSchema.safeParse(event);
     if (!validation.success) {
         return { written: false, path, reason: 'invalid-schema' };
@@ -93,7 +103,10 @@ export function emitObservabilityEvent(event, options) {
  * lines and any record whose `schemaVersion` does not match the
  * current `OBSERVABILITY_SCHEMA_VERSION` (forward-compat per Q3).
  *
- * Returns [] when the session has no metrics file yet.
+ * Returns [] when the session has no metrics file yet, and [] when the
+ * session id names no session directory — both are "no events are
+ * readable here", and this reader does not throw (repair R6: it used to,
+ * via `readMetricLines` → `metricsFilePath`).
  */
 export function readObservabilityEvents(projectRoot, sessionId) {
     const lines = readMetricLines(projectRoot, sessionId);