peaks-loop 4.0.54 → 4.1.1

package/dist/services/sediment/pool-read.js

@@ -1,30 +1,46 @@
-import { readdirSync, readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { resolveUserBeesDir, resolveSegmentsDir } from "./pool-paths.js";
-import { lintManifest } from "./manifest-lint.js";
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveUserBeesDir, resolveSegmentsDir } from './pool-paths.js';
+import { BeeManifestSchema } from './json-schema.js';
 export class POOL_READ_ERROR extends Error {
 }
-function readJsonIfExists(p) {
-    if (!existsSync(p))
-        return null;
-    return JSON.parse(readFileSync(p, "utf-8"));
-}
 function readBeeDir(home, name) {
     const dir = join(resolveUserBeesDir({ home }), name);
-    const manifestPath = join(dir, "manifest.json");
-    const m = readJsonIfExists(manifestPath);
-    if (!m)
+    const manifestPath = join(dir, 'manifest.json');
+    if (!existsSync(manifestPath))
         return null;
-    const r = lintManifest(m);
-    if (!r.ok)
+    // The two failures must stay DISTINCT here, so the two steps are written out
+    // rather than delegated.
+    //
+    //   not JSON        -> `JSON.parse` throws -> `peaks sediment list` fails loudly
+    //   wrong shape     -> `safeParse` fails   -> this bee is skipped
+    //
+    // This used to be FORCED: neither shipped primitive could keep the pair apart
+    // (`tryParseJson` mapped both failures to `null`; `parseJson` throws on both,
+    // `schema.parse(JSON.parse(raw))`). As of 2026-09-23 `tryParseJson` returns a
+    // discriminated `TryParse<S>`, so a `reason`-aware call CAN express this pair.
+    // The steps stay written out anyway, because the loud failure must remain
+    // `JSON.parse`'s OWN throw: substituting a hand-made error would change what
+    // `peaks sediment list` reports, and this pair is pinned by
+    // `tests/unit/services/sediment/pool-read-semantics.test.ts`.
+    //
+    // `: unknown` is not decoration: `JSON.parse` is typed `any`, so an
+    // un-annotated binding would be an `any` entering the file
+    // (`no-unsafe-assignment`). Annotating it is the shape the repo's other 20
+    // bare `JSON.parse` reads already use, and `safeParse` accepts `unknown`,
+    // so handing it on is not a `no-unsafe-argument` either.
+    const decoded = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    const parsed = BeeManifestSchema.safeParse(decoded);
+    if (!parsed.success)
         return null;
+    const m = parsed.data;
     return {
         name: m.name,
-        kind: "bee",
+        kind: 'bee',
         path: `bees/${name}`,
         source: m.source,
         promotion_status: m.promotion_status,
-        segments: m.segments.map((s) => s.name),
+        segments: m.segments.map((s) => s.name)
     };
 }
 function readSegmentDir(home, name) {
@@ -32,7 +48,11 @@ function readSegmentDir(home, name) {
     if (!existsSync(dir))
         return null;
     return {
-        name, kind: "segment", path: `segments/${name}`, source: "user", promotion_status: "stable",
+        name,
+        kind: 'segment',
+        path: `segments/${name}`,
+        source: 'user',
+        promotion_status: 'stable'
     };
 }
 /** Pure read of the in-memory pool index (Critical #2 fix).
@@ -67,7 +87,11 @@ export function readPool({ home }) {
             entries.push(...[readSegmentDir(home, ent.name)].filter((e) => e !== null));
         }
     }
-    const idx = { schemaVersion: "peaks.pool/1", generatedAt: new Date().toISOString(), entries };
+    const idx = {
+        schemaVersion: 'peaks.pool/1',
+        generatedAt: new Date().toISOString(),
+        entries
+    };
     // Note: NO writeFileSync here. See Critical #2 fix.
     return idx;
 }

package/dist/services/sediment/pool-rebuild-index.d.ts

@@ -1,4 +1,4 @@
-import type { IndexFile } from "./types.js";
+import type { IndexFile } from './types.js';
 /**
  * Rebuilds index.json from on-disk manifests/segments and writes the result.
  *

package/dist/services/sediment/pool-rebuild-index.js

@@ -1,7 +1,7 @@
-import { writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { resolvePoolRoot } from "./pool-paths.js";
-import { readPool } from "./pool-read.js";
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolvePoolRoot } from './pool-paths.js';
+import { readPool } from './pool-read.js';
 /**
  * Rebuilds index.json from on-disk manifests/segments and writes the result.
  *
@@ -23,6 +23,6 @@ export function rebuildIndexFromFs({ home }) {
     // behavior rather than drop it — both are JSON-valid but the trailing
     // newline matches the convention used by every other peaks-*.json file
     // in the project (manifest.json, segment.json, etc.).
-    writeFileSync(join(root, "index.json"), JSON.stringify(idx, null, 2) + "\n");
+    writeFileSync(join(root, 'index.json'), JSON.stringify(idx, null, 2) + '\n');
     return idx;
 }

package/dist/services/sediment/pool-write.d.ts

@@ -1,4 +1,4 @@
-import type { BeeManifest } from "./types.js";
+import type { BeeManifest } from './types.js';
 /**
  * Atomically writes a BeeManifest to <home>/.peaks/skills/bees/<name>/manifest.json.
  *

package/dist/services/sediment/pool-write.js

@@ -1,7 +1,7 @@
-import { writeFileSync, mkdirSync, renameSync } from "node:fs";
-import { join } from "node:path";
-import { assertNotSystemPath, resolveUserBeeDir } from "./pool-paths.js";
-import { lintManifestStrict } from "./manifest-lint.js";
+import { writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertNotSystemPath, resolveUserBeeDir } from './pool-paths.js';
+import { lintManifestStrict } from './manifest-lint.js';
 /**
  * Atomically writes a BeeManifest to <home>/.peaks/skills/bees/<name>/manifest.json.
  *
@@ -17,9 +17,9 @@ export function writeBeeManifest({ home }, m) {
     const dir = resolveUserBeeDir({ home }, validated.name);
     assertNotSystemPath(dir);
     mkdirSync(dir, { recursive: true });
-    const file = join(dir, "manifest.json");
+    const file = join(dir, 'manifest.json');
     assertNotSystemPath(file);
-    const tmp = file + ".tmp";
-    writeFileSync(tmp, JSON.stringify(validated, null, 2) + "\n");
+    const tmp = file + '.tmp';
+    writeFileSync(tmp, JSON.stringify(validated, null, 2) + '\n');
     renameSync(tmp, file);
 }

package/dist/services/sediment/promotion-gate.d.ts

@@ -1,4 +1,4 @@
-import type { BeeManifest } from "./types.js";
+import type { BeeManifest } from './types.js';
 export interface GateInputs {
     humanApproved: boolean;
     smokeTestPresent: boolean;

package/dist/services/sediment/promotion-gate.js

@@ -1,20 +1,20 @@
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { resolveUserBeeDir } from "./pool-paths.js";
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveUserBeeDir } from './pool-paths.js';
 export function evaluateGate({ home }, m, inputs) {
-    if (m.source === "system") {
+    if (m.source === 'system') {
         return { ok: true, failedSubconditions: [] };
     }
     const failed = [];
-    const rsPath = join(resolveUserBeeDir({ home }, m.name), "run-state.json");
+    const rsPath = join(resolveUserBeeDir({ home }, m.name), 'run-state.json');
     const cycles = existsSync(rsPath)
-        ? JSON.parse(readFileSync(rsPath, "utf-8")).cycles
+        ? JSON.parse(readFileSync(rsPath, 'utf-8')).cycles
         : 0;
     if (cycles < m.promotion.minCycles)
-        failed.push("minCycles");
+        failed.push('minCycles');
     if (inputs.smokeTestPresent !== m.promotion.requiresSmokeTest)
-        failed.push("smokeTest");
+        failed.push('smokeTest');
     if (m.promotion.requiresHumanApproval && !inputs.humanApproved)
-        failed.push("humanApproval");
+        failed.push('humanApproval');
     return { ok: failed.length === 0, failedSubconditions: failed };
 }

package/dist/services/sediment/types.d.ts

@@ -1,8 +1,8 @@
-export type Source = "system" | "user";
-export type PromotionStatus = "candidate" | "stable" | "retired" | "system-stable";
+export type Source = 'system' | 'user';
+export type PromotionStatus = 'candidate' | 'stable' | 'retired' | 'system-stable';
 export interface Param {
     name: string;
-    type: "string" | "number" | "boolean" | "json";
+    type: 'string' | 'number' | 'boolean' | 'json';
     required: boolean;
 }
 export interface SegmentRef {
@@ -13,7 +13,7 @@ export interface SegmentRef {
 }
 export interface SkillEnvelopeRef {
     path: string;
-    kind: "file" | "dir" | "script";
+    kind: 'file' | 'dir' | 'script';
 }
 export interface SkillEnvelope {
     preamble: string;
@@ -26,7 +26,7 @@ export interface PromotionGate {
     retireOnMissesInRow?: number;
 }
 export interface BeeManifest {
-    schemaVersion: "peaks.bee/1";
+    schemaVersion: 'peaks.bee/1';
     name: string;
     source: Source;
     promotion_status: PromotionStatus;
@@ -34,19 +34,19 @@ export interface BeeManifest {
     segments: SegmentRef[];
     entrypoint: SkillEnvelope;
     promotion: PromotionGate;
-    createdBy: "human" | "llm";
+    createdBy: 'human' | 'llm';
     lastTouchedAt: string;
 }
 export interface IndexEntry {
     name: string;
-    kind: "bee" | "segment";
+    kind: 'bee' | 'segment';
     path: string;
     source: Source;
     promotion_status: PromotionStatus;
     segments?: string[];
 }
 export interface IndexFile {
-    schemaVersion: "peaks.pool/1";
+    schemaVersion: 'peaks.pool/1';
     generatedAt: string;
     entries: IndexEntry[];
 }

package/dist/services/session/binding-status-service.js

@@ -31,7 +31,11 @@ export function loadBindingStatus(projectRoot) {
     const binding = readBinding(projectRoot);
     const canonicalExists = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'));
     const legacyExists = existsSync(join(projectRoot, '.peaks', '.session.json'));
-    const source = canonicalExists ? 'canonical' : legacyExists ? 'legacy' : 'none';
+    const source = canonicalExists
+        ? 'canonical'
+        : legacyExists
+            ? 'legacy'
+            : 'none';
     const outerSessionId = readOuterSessionId();
     const stale = binding === null
         ? false
@@ -79,7 +83,13 @@ export function formatTable(view) {
         return '';
     const rows = [];
     for (const [sid, inst] of Object.entries(view.binding.instances)) {
-        rows.push([sid, inst.callerId, String(view.binding.pid), inst.roles.join(','), inst.lastHeartbeat]);
+        rows.push([
+            sid,
+            inst.callerId,
+            String(view.binding.pid),
+            inst.roles.join(','),
+            inst.lastHeartbeat
+        ]);
     }
     if (rows.length === 0)
         return '';
@@ -120,8 +130,8 @@ export function isInstanceRecord(value) {
     if (value === null || typeof value !== 'object')
         return false;
     const v = value;
-    return typeof v.startedAt === 'string' &&
+    return (typeof v.startedAt === 'string' &&
         Array.isArray(v.roles) &&
         typeof v.callerId === 'string' &&
-        typeof v.lastHeartbeat === 'string';
+        typeof v.lastHeartbeat === 'string');
 }

package/dist/services/session/caller-binding-service.js

@@ -92,7 +92,8 @@ export function getCallerBinding(projectRoot, callerId) {
         }
         return parsed;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
 }

package/dist/services/session/getSessionDir.js

@@ -86,7 +86,10 @@ export function tryGetSessionDir(projectRoot, sessionId) {
     // That would re-introduce the swallow this function exists to remove, and it
     // would also catch a throw from `join` for reasons that are not a bad id.
     if (isUnsafePathInput(sessionId)) {
-        return { ok: false, reason: `Invalid session id: ${sessionId} (must be a single path segment)` };
+        return {
+            ok: false,
+            reason: `Invalid session id: ${sessionId} (must be a single path segment)`
+        };
     }
     return { ok: true, dir: join(projectRoot, '.peaks', '_runtime', sessionId) };
 }

package/dist/services/session/index.d.ts

@@ -1,6 +1,6 @@
 export { ensureSession, getSessionId, resolveCallerBoundSession, type CallerBoundSession, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding, type SessionInfo, type SessionMeta } from './session-manager.js';
 export { getSessionDir } from './getSessionDir.js';
-export { resolveCallerId, } from './resolve-caller-id.js';
+export { resolveCallerId } from './resolve-caller-id.js';
 export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, resolveCallerBinding, type CallerBindingResolution, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
 export { PLATFORM_FALLBACKS, type PlatformFallback } from './platform-fallbacks.js';
 export { resolveCallerProjection, type ResolveCallerIdOptions } from './resolve-caller-id.js';

package/dist/services/session/index.js

@@ -1,7 +1,7 @@
 export { ensureSession, getSessionId, resolveCallerBoundSession, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding } from './session-manager.js';
 export { getSessionDir } from './getSessionDir.js';
 // Slice 020 — caller-keyed session binding. The new canonical path.
-export { resolveCallerId, } from './resolve-caller-id.js';
+export { resolveCallerId } from './resolve-caller-id.js';
 export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, resolveCallerBinding, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
 // Slice 4.0.8 (C1): PLATFORM_FALLBACKS is deleted. Re-export kept as
 // a deprecated alias for one minor release so legacy consumers keep

package/dist/services/session/resolve-caller-id.js

@@ -33,7 +33,7 @@
  * See `.peaks/_runtime/2026-08-03-session-bee258/rd/requests/001-2026-08-03-presence-lease-graph-design.md`
  * for the slice 4.0.8 contract.
  */
-import { CALLER_ID_REGEX, CallerIdError, } from './caller-id-types.js';
+import { CALLER_ID_REGEX, CallerIdError } from './caller-id-types.js';
 import { getAdapter } from '../ide/ide-registry.js';
 import { detectInstalledIde } from '../ide/ide-detector.js';
 // Re-export for CLI consumers (avoids a second import line).
@@ -76,7 +76,9 @@ export function resolveCallerId(opts = {}) {
         return validateCallerId(opts.flagValue, 'flag');
     }
     // Priority level 2: env var (vendor-neutral override).
-    const envValue = isNonEmpty(opts.envOverride) ? opts.envOverride : opts.env?.PEAKS_CALLER_ID ?? process.env.PEAKS_CALLER_ID;
+    const envValue = isNonEmpty(opts.envOverride)
+        ? opts.envOverride
+        : (opts.env?.PEAKS_CALLER_ID ?? process.env.PEAKS_CALLER_ID);
     if (isNonEmpty(envValue)) {
         return validateCallerId(envValue, 'env');
     }
@@ -122,7 +124,7 @@ export function resolveCallerProjection(opts = {}) {
             callerId: validated,
             workflowId: null,
             graphRef: null,
-            source: 'env-flag',
+            source: 'env-flag'
         };
     }
     // 2. Env-flag — PEAKS_CALLER_ID override.
@@ -134,7 +136,7 @@ export function resolveCallerProjection(opts = {}) {
             callerId: validated,
             workflowId: null,
             graphRef: null,
-            source: 'env-flag',
+            source: 'env-flag'
         };
     }
     // 3. Adapter — the active IDE owns its priority rules.
@@ -146,7 +148,7 @@ export function resolveCallerProjection(opts = {}) {
             callerId,
             workflowId: null,
             graphRef: null,
-            source: 'adapter',
+            source: 'adapter'
         };
     }
     catch (err) {

package/dist/services/session/session-binding-bridge.js

@@ -23,7 +23,9 @@ import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
 import { projectRootsMatch, stableRealPath } from '../../shared/path-utils.js';
-import { resolveCallerBinding, setCallerBinding, } from './caller-binding-service.js';
+import { tryParseJson } from '../../shared/json-parse.js';
+import { SessionBindingSchema, SessionFileSchema } from './session-file-schema.js';
+import { resolveCallerBinding, setCallerBinding } from './caller-binding-service.js';
 import { resolveCallerProjection } from './resolve-caller-id.js';
 import { getSessionId, getSessionIdCanonical, getSessionMeta, rotateSessionBinding, setSessionMeta } from './session-manager.js';
 // --- Lower-level helpers the bridge needs (moved verbatim) ---
@@ -59,15 +61,14 @@ function readSessionFile(projectRoot) {
     if (!existsSync(pathToRead))
         return null;
     try {
-        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
-        if (data.sessionId &&
-            typeof data.projectRoot === 'string' &&
-            projectRootsMatch(data.projectRoot, projectRoot)) {
-            return data;
+        const parsed = tryParseJson(readFileSync(pathToRead, 'utf8'), SessionBindingSchema);
+        if (parsed.ok && projectRootsMatch(parsed.value.projectRoot, projectRoot)) {
+            return parsed.value;
         }
         return null;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
 }
@@ -78,15 +79,14 @@ function readSessionFileCanonical(projectRoot) {
     if (!existsSync(pathToRead))
         return null;
     try {
-        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
-        if (data.sessionId &&
-            typeof data.projectRoot === 'string' &&
-            projectRootsMatch(data.projectRoot, projectRoot)) {
-            return data;
+        const parsed = tryParseJson(readFileSync(pathToRead, 'utf8'), SessionBindingSchema);
+        if (parsed.ok && projectRootsMatch(parsed.value.projectRoot, projectRoot)) {
+            return parsed.value;
         }
         return null;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
 }
@@ -114,14 +114,11 @@ function readSessionMeta(projectRoot, sessionId) {
     if (!existsSync(metaPath))
         return null;
     try {
-        const raw = readFileSync(metaPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed?.sessionId !== 'string' || parsed.sessionId.length === 0) {
-            return null;
-        }
-        return parsed;
+        const parsed = tryParseJson(readFileSync(metaPath, 'utf8'), SessionFileSchema);
+        return parsed.ok ? parsed.value : null;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
 }
@@ -171,11 +168,12 @@ function getCurrentOuterSessionId(projectRoot) {
                         if (parsed !== null &&
                             typeof parsed === 'object' &&
                             typeof parsed.outerSessionId === 'string' &&
-                            (parsed.outerSessionId).length > 0) {
+                            parsed.outerSessionId.length > 0) {
                             resolved = parsed.outerSessionId;
                         }
                     }
-                    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    catch {
+                        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
                         // fall through — file missing / malformed JSON / IO error → undefined
                     }
                 }
@@ -217,7 +215,8 @@ function resolveCallerBindingForEnsure(projectRoot) {
     try {
         projection = resolveCallerProjection({ projectRoot, env: process.env });
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
     try {
@@ -230,7 +229,8 @@ function resolveCallerBindingForEnsure(projectRoot) {
             callerId: projection.callerId
         };
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
 }
@@ -337,7 +337,8 @@ export async function ensureSession(projectRoot) {
         try {
             setCallerBinding(projectRoot, newCallerId, payload);
         }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        catch {
+            // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
             // best effort; session.json write below is the legacy fallback
         }
     }

package/dist/services/session/session-checkpoint-service.js

@@ -142,7 +142,7 @@ export function listCheckpointPaths(projectRoot, sessionId) {
 }
 export function latestCheckpointPath(projectRoot, sessionId) {
     const paths = listCheckpointPaths(projectRoot, sessionId);
-    return paths.length > 0 ? paths[0] ?? null : null;
+    return paths.length > 0 ? (paths[0] ?? null) : null;
 }
 export const CHECKPOINT_CONSTANTS = {
     CHECKPOINTS_DIR,

package/dist/services/session/session-file-schema.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Runtime schemas for the on-disk session files.
+ *
+ * WHY THIS EXISTS (S12, 2026-09-20). Six readers across `session-manager.ts`
+ * and `session-binding-bridge.ts` did `JSON.parse(readFileSync(path, 'utf8'))`
+ * and then hand-rolled `typeof data.sessionId === 'string'` checks before
+ * asserting the result with `as SessionInfo` / `as SessionMeta`. Because
+ * `JSON.parse` returns `any`, the hand-rolled check could only ever cover the
+ * one or two fields it happened to name, and the assertion claimed the rest —
+ * an unchecked cast sitting on top of a partial check. Those sites are part of
+ * the R1 root at the S12 census.
+ *
+ * The schemas below are the same checks, made total: every field the return
+ * type promises is now checked, so the callers return the parsed value
+ * directly and the `as` casts are gone. The check is STRICTER than it was —
+ * that is the point, and it is stated here rather than discovered later. A
+ * file that lacks `createdAt` or `projectRoot` used to be handed back typed as
+ * `SessionInfo`; it now reads as `null`, which is what the readers do with
+ * every other unusable file.
+ *
+ * THREE schemas, layered, because three different readers check three
+ * different things. Each one validates EXACTLY the fields its reader relies
+ * on and nothing more — a schema that demanded more than the code checks
+ * would be a new requirement smuggled in under a type, and it would show up
+ * as passing tests having to be rewritten. It did, during S12: requiring
+ * `createdAt` in the project-level binding schema broke five statusline tests
+ * that seed `{ sessionId, projectRoot }`, and no consumer reads `createdAt`
+ * from that reader. That finding is why this file has three schemas.
+ */
+import { z } from 'zod';
+/**
+ * The minimum a reader needs to LOCATE a session: a non-empty id. Equivalent
+ * to the `typeof data.sessionId === 'string' && data.sessionId.length > 0`
+ * check it replaces.
+ */
+export declare const SessionIdentitySchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$loose>;
+/**
+ * What the project-level binding readers (`readSessionFile` /
+ * `readSessionFileCanonical`, in both `session-manager.ts` and
+ * `session-binding-bridge.ts`) actually use: the id, and the `projectRoot`
+ * they compare against the caller. Equivalent to the
+ * `data.sessionId && typeof data.projectRoot === 'string'` check it replaces.
+ */
+export declare const SessionBindingSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    projectRoot: z.ZodString;
+}, z.core.$loose>;
+/**
+ * The full session record, as written by `writeSessionFile` (`.peaks/_runtime/
+ * session.json`) and `setSessionMeta` (`.peaks/_runtime/<sid>/session.json`).
+ * This is the shape the META readers promise a caller (`SessionMeta` requires
+ * `createdAt` and `projectRoot`); the optional fields are `SessionMeta`'s own.
+ * `looseObject` preserves any further key the file carries, so a reader still
+ * sees everything on disk.
+ */
+export declare const SessionFileSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    createdAt: z.ZodString;
+    projectRoot: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    skill: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodString>;
+    gate: z.ZodOptional<z.ZodString>;
+    lastActivity: z.ZodOptional<z.ZodString>;
+    outerSessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** What the project-level binding readers hand back: validated, and nothing more. */
+export type SessionBinding = z.infer<typeof SessionBindingSchema>;

package/dist/services/session/session-file-schema.js

@@ -0,0 +1,68 @@
+/**
+ * Runtime schemas for the on-disk session files.
+ *
+ * WHY THIS EXISTS (S12, 2026-09-20). Six readers across `session-manager.ts`
+ * and `session-binding-bridge.ts` did `JSON.parse(readFileSync(path, 'utf8'))`
+ * and then hand-rolled `typeof data.sessionId === 'string'` checks before
+ * asserting the result with `as SessionInfo` / `as SessionMeta`. Because
+ * `JSON.parse` returns `any`, the hand-rolled check could only ever cover the
+ * one or two fields it happened to name, and the assertion claimed the rest —
+ * an unchecked cast sitting on top of a partial check. Those sites are part of
+ * the R1 root at the S12 census.
+ *
+ * The schemas below are the same checks, made total: every field the return
+ * type promises is now checked, so the callers return the parsed value
+ * directly and the `as` casts are gone. The check is STRICTER than it was —
+ * that is the point, and it is stated here rather than discovered later. A
+ * file that lacks `createdAt` or `projectRoot` used to be handed back typed as
+ * `SessionInfo`; it now reads as `null`, which is what the readers do with
+ * every other unusable file.
+ *
+ * THREE schemas, layered, because three different readers check three
+ * different things. Each one validates EXACTLY the fields its reader relies
+ * on and nothing more — a schema that demanded more than the code checks
+ * would be a new requirement smuggled in under a type, and it would show up
+ * as passing tests having to be rewritten. It did, during S12: requiring
+ * `createdAt` in the project-level binding schema broke five statusline tests
+ * that seed `{ sessionId, projectRoot }`, and no consumer reads `createdAt`
+ * from that reader. That finding is why this file has three schemas.
+ */
+import { z } from 'zod';
+/**
+ * The minimum a reader needs to LOCATE a session: a non-empty id. Equivalent
+ * to the `typeof data.sessionId === 'string' && data.sessionId.length > 0`
+ * check it replaces.
+ */
+export const SessionIdentitySchema = z.looseObject({
+    sessionId: z.string().min(1)
+});
+/**
+ * What the project-level binding readers (`readSessionFile` /
+ * `readSessionFileCanonical`, in both `session-manager.ts` and
+ * `session-binding-bridge.ts`) actually use: the id, and the `projectRoot`
+ * they compare against the caller. Equivalent to the
+ * `data.sessionId && typeof data.projectRoot === 'string'` check it replaces.
+ */
+export const SessionBindingSchema = z.looseObject({
+    sessionId: z.string().min(1),
+    projectRoot: z.string()
+});
+/**
+ * The full session record, as written by `writeSessionFile` (`.peaks/_runtime/
+ * session.json`) and `setSessionMeta` (`.peaks/_runtime/<sid>/session.json`).
+ * This is the shape the META readers promise a caller (`SessionMeta` requires
+ * `createdAt` and `projectRoot`); the optional fields are `SessionMeta`'s own.
+ * `looseObject` preserves any further key the file carries, so a reader still
+ * sees everything on disk.
+ */
+export const SessionFileSchema = z.looseObject({
+    sessionId: z.string().min(1),
+    createdAt: z.string(),
+    projectRoot: z.string(),
+    title: z.string().optional(),
+    skill: z.string().optional(),
+    mode: z.string().optional(),
+    gate: z.string().optional(),
+    lastActivity: z.string().optional(),
+    outerSessionId: z.string().optional()
+});