peaks-loop 4.0.47 → 4.0.49

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/final-review-service.d.ts

@@ -252,6 +252,15 @@ interface EvidenceSource {
     readonly label: string;
     /** Path segments under `.peaks/_runtime/<sessionId>/`. */
     readonly segments: readonly string[];
+    /**
+     * An older location of the SAME artifact, tried only when `segments` is not
+     * on disk. Slice `2026-09-14-prd-capsule-rid-scoping` moved the PRD handoff
+     * capsule to `prd/handoff-<rid>.md`; sessions written before it hold only
+     * the bare `prd/handoff.md`, and this module's delivery gate keys on that
+     * source — so a source that goes missing does not fail the gate, it stops
+     * it (`enforceScopeContractDelivery` returns early on `missing`).
+     */
+    readonly legacySegments?: readonly string[];
     /** Dimensions this source can supply evidence for. */
     readonly supports: readonly DimensionKind[];
     /** What DELIVERED means for this source. See `isDelivered()` — every source

package/dist/services/final-review/final-review-service.js

@@ -474,7 +474,10 @@ function evidenceSourcesFor(rid, prePostDiffAvailable) {
         {
             key: SCOPE_CONTRACT_SOURCE_KEY,
             label: 'PRD handoff (approved scope + non-goals)',
-            segments: ['prd', 'handoff.md'],
+            // One capsule per slice since `2026-09-14-prd-capsule-rid-scoping`; the
+            // bare name is the pre-scoping tier and still lives on 3 sessions.
+            segments: ['prd', `handoff-${rid}.md`],
+            legacySegments: ['prd', 'handoff.md'],
             supports: ['functional-completeness', 'existing-functionality-intact'],
             delivery: { kind: 'whole' }
         }
@@ -508,22 +511,43 @@ function classifyReadFailure(error) {
 function readEvidence(projectRoot, sessionId, rid, prePostDiffAvailable) {
     const runtimeRoot = join(projectRoot, '.peaks', '_runtime', sessionId);
     return evidenceSourcesFor(rid, prePostDiffAvailable).map(source => {
-        const relativePath = ['.peaks', '_runtime', sessionId, ...source.segments].join('/');
-        const absolutePath = join(runtimeRoot, ...source.segments);
+        // The canonical location first; an older one is tried only when the
+        // canonical file is genuinely ABSENT (see `legacySegments`). A file that
+        // is present but unreadable stops the walk — falling through to an older
+        // copy would silently swap the evidence this run reports.
+        const attempts = [
+            source.segments,
+            ...(source.legacySegments !== undefined ? [source.legacySegments] : [])
+        ];
+        // The path reported when nothing resolved stays the CANONICAL one, so the
+        // operator is sent to where the artifact belongs, not to its old home.
+        let resolved = source.segments;
         let raw = null;
         let error = '';
-        let read = 'ok';
-        try {
-            raw = readFileSync(absolutePath);
-        }
-        catch (err) {
-            read = classifyReadFailure(err);
-            error = err instanceof Error ? err.message : String(err);
+        let read = 'missing';
+        for (const segments of attempts) {
+            try {
+                raw = readFileSync(join(runtimeRoot, ...segments));
+                read = 'ok';
+                resolved = segments;
+                break;
+            }
+            catch (err) {
+                read = classifyReadFailure(err);
+                error = err instanceof Error ? err.message : String(err);
+                // A file that exists but cannot be read IS this source's file, so it
+                // is also the path the report must name — walking on to an older copy
+                // would silently swap the evidence this run reports.
+                if (read === 'unreadable') {
+                    resolved = segments;
+                    break;
+                }
+            }
         }
         return {
             source,
-            relativePath,
-            absolutePath,
+            relativePath: ['.peaks', '_runtime', sessionId, ...resolved].join('/'),
+            absolutePath: join(runtimeRoot, ...resolved),
             raw,
             read,
             error,

package/dist/services/ide/ide-registry.d.ts

@@ -15,6 +15,25 @@ export declare function getAdapter(ide: IdeId): IdeAdapter;
 export declare function tryGetAdapter(ide: string): IdeAdapter | undefined;
 /** All registered adapter ids (insertion order). */
 export declare function listAdapterIds(): readonly IdeId[];
+/**
+ * Help text for every `--ide <id>` option, derived from the registry.
+ *
+ * It used to be a hand-written literal — `"target adapter id (claude-code |
+ * trae); default: auto-detect from env/cwd"` — copy-pasted into six option
+ * declarations across `hooks-commands.ts` and `statusline-commands.ts`. By the
+ * time anyone read it the registry had nine adapters, so the help named two of
+ * the nine values the option accepts and stayed silent about the other seven.
+ * A help string that enumerates a set it does not own cannot be kept true by
+ * discipline; deriving it here is the only form that cannot drift.
+ *
+ * Note for whoever is tempted to point the help at `peaks adapter list`
+ * instead: that command lists USER-REGISTERED vendor adapters from
+ * `.peaks/runtime/adapters.json` (a different registry, empty on a fresh
+ * project). It is not this set. The nine ids below have no CLI surface of
+ * their own; `peaks ide model --current` is the closest read-only viewer and
+ * it reports one adapter, not the list.
+ */
+export declare function resolveIdeOptionHelp(): string;
 /** All registered adapters (insertion order). */
 export declare function listAdapters(): readonly IdeAdapter[];
 /**

package/dist/services/ide/ide-registry.js

@@ -57,6 +57,27 @@ export function tryGetAdapter(ide) {
 export function listAdapterIds() {
     return Array.from(ADAPTERS.keys());
 }
+/**
+ * Help text for every `--ide <id>` option, derived from the registry.
+ *
+ * It used to be a hand-written literal — `"target adapter id (claude-code |
+ * trae); default: auto-detect from env/cwd"` — copy-pasted into six option
+ * declarations across `hooks-commands.ts` and `statusline-commands.ts`. By the
+ * time anyone read it the registry had nine adapters, so the help named two of
+ * the nine values the option accepts and stayed silent about the other seven.
+ * A help string that enumerates a set it does not own cannot be kept true by
+ * discipline; deriving it here is the only form that cannot drift.
+ *
+ * Note for whoever is tempted to point the help at `peaks adapter list`
+ * instead: that command lists USER-REGISTERED vendor adapters from
+ * `.peaks/runtime/adapters.json` (a different registry, empty on a fresh
+ * project). It is not this set. The nine ids below have no CLI surface of
+ * their own; `peaks ide model --current` is the closest read-only viewer and
+ * it reports one adapter, not the list.
+ */
+export function resolveIdeOptionHelp() {
+    return `target adapter id (${listAdapterIds().join(' | ')}); default: auto-detect from env/cwd`;
+}
 /** All registered adapters (insertion order). */
 export function listAdapters() {
     return Array.from(ADAPTERS.values());

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/job/job-state-store.js

@@ -1,12 +1,19 @@
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { JobStateSchema } from './job-types.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 export class JobStateStore {
     rootDir;
     constructor(rootDir) {
         this.rootDir = rootDir;
     }
     jobDir(jobId) {
+        // JobId axis. This is the only join the store performs, so one guard here
+        // covers every `peaks job *` subcommand — ten CLI call sites hand the
+        // store a caller-supplied `--job-id` and none of them checked it.
+        if (isUnsafePathInput(jobId)) {
+            throw new Error(`Invalid job id: ${jobId} (must be a single path segment)`);
+        }
         return join(this.rootDir, jobId);
     }
     init(input) {

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

@@ -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[];
 /**