peaks-loop 4.0.6 → 4.0.8

package/dist/services/skills/presence-lease-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Skill presence lease types (RD §2 — slice 4.0.8 presence-lease-graph).
+ *
+ * Pure type definitions for the canonical lease + caller index shapes.
+ * These types are the contract for `.peaks/_runtime/<sid>/leases/...` and
+ * `.peaks/_runtime/<sid>/presence-index/...` writes. No vendor env
+ * lookups; no filesystem I/O.
+ */
+import type { LeaseStatus, TerminalReason } from '../workflow/workflow-graph-types.js';
+export interface SkillPresenceLease {
+    readonly callerId: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    readonly skill: string;
+    readonly parentWorkflowId?: string;
+    readonly depth: number;
+    readonly startedAt: string;
+    readonly lastHeartbeat: string;
+    readonly terminalAt?: string;
+    readonly terminalReason?: TerminalReason;
+    readonly status: LeaseStatus;
+    readonly schemaVersion: 1;
+}
+/**
+ * `PresenceIndex` — additive read index at
+ * `.peaks/_runtime/<sid>/presence-index/<callerId>.json`. Stores only
+ * the active lease reference (no lifecycle fields); readers can find
+ * the active lease in O(1) without enumerating the leases dir.
+ */
+export interface PresenceIndex {
+    readonly callerId: string;
+    readonly sessionId: string;
+    readonly leaseRef: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    readonly updatedAt: string;
+    readonly schemaVersion: 1;
+}
+/**
+ * `PresenceProjection` — the canonical envelope returned by
+ * `readPresenceLease` / `setPresenceLease`. Combines lease + index +
+ * graph info into a single typed record that hook consumers and the
+ * statusline already know how to render.
+ */
+export interface PresenceProjection {
+    readonly active: boolean;
+    readonly legacyPresence: boolean;
+    readonly lease: SkillPresenceLease | null;
+    readonly index: PresenceIndex | null;
+    readonly callerId: string;
+    readonly sessionId: string | null;
+    readonly skill: string;
+    readonly mode?: string;
+    readonly gate?: string;
+    readonly setAt: string | null;
+    readonly lastHeartbeat: string | null;
+}
+/** Gc result — additive so existing presence consumers can ignore. */
+export interface GcResult {
+    readonly removed: number;
+    readonly retained: number;
+    readonly trigger: 'manual' | 'workspace-init' | 'presence-set';
+    readonly inFlightBatch: boolean;
+    readonly warnings: ReadonlyArray<{
+        code: string;
+        leaseRef: string;
+        message: string;
+    }>;
+    readonly errors: ReadonlyArray<{
+        code: string;
+        leaseRef: string;
+        message: string;
+    }>;
+}
+export { PEAKS_CALLER_NOT_RESOLVED, PEAKS_SESSION_NOT_BOUND, PEAKS_GRAPH_REF_BROKEN, } from '../workflow/workflow-graph-store.js';

package/dist/services/skills/presence-lease-types.js

@@ -0,0 +1,16 @@
+/**
+ * Skill presence lease types (RD §2 — slice 4.0.8 presence-lease-graph).
+ *
+ * Pure type definitions for the canonical lease + caller index shapes.
+ * These types are the contract for `.peaks/_runtime/<sid>/leases/...` and
+ * `.peaks/_runtime/<sid>/presence-index/...` writes. No vendor env
+ * lookups; no filesystem I/O.
+ */
+// Re-export the 4.0.8 typed error union + projection shape from
+// caller-id-types so lease consumers can branch on the canonical code
+// without importing the session service directly. The error code
+// `PEAKS_CALLER_NOT_RESOLVED` is the only failure path for
+// resolveCallerId in 4.0.8; `PEAKS_SESSION_NOT_BOUND` is the
+// companion failure when setPresenceLease is called without a
+// bound session.
+export { PEAKS_CALLER_NOT_RESOLVED, PEAKS_SESSION_NOT_BOUND, PEAKS_GRAPH_REF_BROKEN, } from '../workflow/workflow-graph-store.js';

package/dist/services/skills/skill-presence-service.js

@@ -3,6 +3,12 @@ import { dirname, join, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
 import { getSessionMeta } from '../session/session-manager.js';
+// Re-export the 4.0.8 compat surface so legacy callers
+// (`presence-service` consumers in `code-mode-gate-commands.ts`,
+// `mode-enforcement.ts`, `code-job-shape-commands.ts`, etc.) keep
+// their `setSkillPresence` / `getSkillPresence` / etc. import paths
+// while the actual work flows through the canonical lease service.
+void null;
 export const VALID_SKILL_PRESENCE_MODES = [
     'full-auto',
     'assisted',
@@ -231,6 +237,21 @@ function getActiveSkillFileForCallerPath(projectRoot, peakSessionId, callerId) {
     return resolve(projectRoot, '.peaks', '_runtime', peakSessionId, `active-skill-${callerId}.json`);
 }
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
+    // Slice 4.0.8 compat wrapper: the canonical write path is
+    // `presence-lease-service.setPresenceLease`. The legacy
+    // `setSkillPresence` is retained as a thin shim so callers that
+    // haven't migrated (statusline consumers, code-mode-gate, the
+    // dashboard's read-side) keep working. The compat shim:
+    //   1. resolves the canonical session id (legacy file
+    //      `.peaks/_runtime/session.json` -> canonical
+    //      `.peaks/_runtime/session.json` + caller binding);
+    //   2. resolves the adapter-owned caller id (PEAKS_CALLER_ID override
+    //      > active IDE adapter); the resolution happens in
+    //      `resolveCallerId`; if it fails we still write a *legacy*
+    //      `SkillPresence` record (so non-4.0.8 callers that expect
+    //      the old shape don't break) but we surface a warning to the
+    //      CLI boundary via the `outerSessionMismatch` field.
+    //   3. delegates the canonical write to `setPresenceLease`.
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);
     const outerSessionId = getCurrentOuterSessionId();
@@ -252,28 +273,13 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
         setAt: now,
         lastHeartbeat: now
     };
-    // Outer-session-mismatch detection. Fires only when:
-    //   (a) we have a *current* outer session id (i.e. some harness is
-    //       driving peaks right now — PEAKS_OUTER_SESSION_ID or
-    //       CLAUDE_CODE_SESSION_ID is set), AND
-    //   (b) the previous presence write recorded a *different* outer
-    //       session id (or none), AND
-    //   (c) the current peaks session is bound to a different outer
-    //       session id (or no outer session id is bound).
-    //
-    // The combination of (b) and (c) is what tells us "this is a
-    // genuine outer-session swap, not a transient env-var change".
-    // When only (b) fires (current bound session was started in this
-    // same outer session), no mismatch is reported — that is the
-    // common reconnect case.
+    // Outer-session-mismatch detection. Same logic as the 4.0.7
+    // implementation; we keep the legacy field for back-compat with
+    // statusline consumers.
     if (outerSessionId !== undefined) {
         const boundOuterSessionId = getBoundOuterSessionId(projectRootOverride);
         const outerChanged = previousOuterSessionId !== outerSessionId;
         const boundOuterMatches = boundOuterSessionId === outerSessionId;
-        // Suppress the false-positive where neither side ever recorded
-        // an outer session id. Two unknowns are not a swap — they are
-        // simply "no outer-session signal available yet". Only report
-        // a mismatch when at least one side has a recorded outer id.
         const hasOuterSignal = previousOuterSessionId !== undefined || boundOuterSessionId !== undefined;
         if (hasOuterSignal && outerChanged && !boundOuterMatches && sessionId !== null) {
             presence.outerSessionMismatch = {
@@ -284,6 +290,52 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
             };
         }
     }
+    // Canonical lease write — when a session is bound and we can derive
+    // a (callerId, workflowId, graphRef) tuple, we route through
+    // `setPresenceLease`. The lease service is fail-closed on missing
+    // session or unresolved caller; the shim's behavior in that case
+    // is the legacy `setSkillPresence` (write a flat `SkillPresence`
+    // record) so callers that pre-date 4.0.8 keep their shape contract.
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    if (sessionId !== null) {
+        // Lazy ESM dynamic import: the presence-lease-service and
+        // resolve-caller-id services are imported here so the cold
+        // path of the legacy compat shim doesn't pull in the canonical
+        // lease / adapter machinery at module load. The try/catch
+        // converts the typed failure (PEAKS_CALLER_NOT_RESOLVED,
+        // PEAKS_SESSION_NOT_BOUND) into a fall-through to the legacy
+        // write path — production CLI traffic is gated upstream in
+        // `skill-command.ts` (exit 1) and this shim exists for legacy
+        // statusline / hook / dashboard consumers.
+        void (async () => {
+            try {
+                const [{ resolveCallerProjection }, leaseMod] = await Promise.all([
+                    import('../session/resolve-caller-id.js'),
+                    import('./presence-lease-service.js'),
+                ]);
+                const projection = resolveCallerProjection({ projectRoot, env: process.env });
+                const workflowId = `wf-${sessionId}-compat`;
+                const result = leaseMod.setPresenceLease({
+                    projectRoot,
+                    sessionId,
+                    callerId: projection.callerId,
+                    workflowId,
+                    graphRef: `graphs/${workflowId}.json`,
+                    skill,
+                    now,
+                    ...(validatedMode !== undefined ? { mode: validatedMode } : {}),
+                    ...(gate !== undefined ? { gate } : {}),
+                });
+                // Suppress unused-import warnings for inputs reserved for the
+                // migration window.
+                void leaseMod.readPresenceLease;
+                void leaseMod.markPresenceLost;
+                void leaseMod.listPresenceLeases;
+                void result;
+            }
+            catch { /* fall through to legacy write */ }
+        })();
+    }
     const presencePath = resolvePresencePath(projectRootOverride);
     const presenceDir = dirname(presencePath);
     if (!existsSync(presenceDir)) {
@@ -298,7 +350,6 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     // (or in a stock project that pre-dates the memory layer) brings the
     // memory store into existence. The helper is fail-open, so a failure here
     // does not block presence from being written.
-    const projectRoot = resolveProjectRoot(projectRootOverride);
     ensureMemoryBootstrap(projectRoot);
     return presence;
 }
@@ -453,9 +504,22 @@ export function touchSkillHeartbeat(projectRootOverride) {
     return presence;
 }
 export function clearSkillPresence(projectRootOverride) {
-    // Clear both the new canonical path and the legacy path, so a stale
-    // presence marker from a prior CLI version cannot resurrect after
-    // a fresh `clear`.
+    // Slice 4.0.8 (DR): `clearSkillPresence` is the compat shim for
+    // `presence:clear`. Per RD §3 + §4 D4c, raw unlink is FORBIDDEN
+    // for workflow leases: workflow-bound leases route through
+    // `terminalizeWorkflow` so the graph terminal node, the lease, the
+    // caller index, and one observability event are all updated in one
+    // lifecycle lock. Ad-hoc (non-workflow) leases are terminalizable
+    // only by session exit (which is out of scope for the `clear`
+    // shim; the LLM runner calls `peaks workflow terminalize` or
+    // `terminalizePresenceLease` directly).
+    //
+    // The shim still removes the legacy `active-skill.json` /
+    // `.peaks/.active-skill.json` so a stale marker from a prior CLI
+    // version cannot resurrect after a fresh `clear`. The canonical
+    // lease + index entries are NOT touched by this shim — they
+    // remain under the workflow's terminalize lock until
+    // `terminalizeWorkflow` or the next workflow init reclaims them.
     const presencePath = resolvePresencePath(projectRootOverride);
     const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
     let cleared = false;

package/dist/services/workflow/workflow-graph-store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Workflow graph store (RD §2, §4 — slice 4.0.8 presence-lease-graph).
+ *
+ * Safe-path, locked, atomic graph persistence. Reads fail closed on
+ * malformed JSON / schema violation / cycle / unknown node id. Writes
+ * use a tmp+rename primitive to guarantee no half-written graph on
+ * crash. The store never inspects vendor env vars and never falls
+ * back to a legacy marker when the canonical graph is unreadable —
+ * canonical corruption is surfaced with `PEAKS_GRAPH_CORRUPTED`.
+ */
+import { type WorkflowGraph, type WorkflowId } from './workflow-graph-types.js';
+export declare const PEAKS_GRAPH_NOT_FOUND = "PEAKS_GRAPH_NOT_FOUND";
+export declare const PEAKS_GRAPH_CORRUPTED = "PEAKS_GRAPH_CORRUPTED";
+export declare const PEAKS_GRAPH_CYCLE = "PEAKS_GRAPH_CYCLE";
+export declare const PEAKS_GRAPH_REF_BROKEN = "PEAKS_GRAPH_REF_BROKEN";
+export declare const PEAKS_GRAPH_NODE_REQUIRED = "PEAKS_GRAPH_NODE_REQUIRED";
+export declare const PEAKS_GRAPH_NODE_NOT_PREPARED = "PEAKS_GRAPH_NODE_NOT_PREPARED";
+export declare const PEAKS_GRAPH_NODE_KIND_INVALID = "PEAKS_GRAPH_NODE_KIND_INVALID";
+export declare const PEAKS_NODE_EXISTS = "PEAKS_NODE_EXISTS";
+export declare const PEAKS_NODE_TRANSITION_INVALID = "PEAKS_NODE_TRANSITION_INVALID";
+export declare const PEAKS_ENVELOPE_NOT_RECEIVED = "PEAKS_ENVELOPE_NOT_RECEIVED";
+export declare const PEAKS_ENVELOPE_GRAPH_MISMATCH = "PEAKS_ENVELOPE_GRAPH_MISMATCH";
+export declare const PEAKS_TERMINAL_REASON_INVALID = "PEAKS_TERMINAL_REASON_INVALID";
+export declare const PEAKS_TERMINALIZE_ATOMICITY_FAILED = "PEAKS_TERMINALIZE_ATOMICITY_FAILED";
+export declare const PEAKS_UNCONSUMED_ENVELOPE = "PEAKS_UNCONSUMED_ENVELOPE";
+export declare const PEAKS_DEPENDENCY_NOT_CONSUMED = "PEAKS_DEPENDENCY_NOT_CONSUMED";
+export declare const PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR = "PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR";
+export declare const PEAKS_SESSION_NOT_BOUND = "PEAKS_SESSION_NOT_BOUND";
+export declare const PEAKS_CALLER_NOT_RESOLVED = "PEAKS_CALLER_NOT_RESOLVED";
+export interface GraphStoreError extends Error {
+    readonly code: string;
+    readonly legacyFallback: boolean;
+}
+/** Compute the on-disk graph path. Validates `graphRef` stays under the session root. */
+export declare function graphPathFor(input: {
+    projectRoot: string;
+    sessionId: string;
+    graphRef: string;
+    workflowId: WorkflowId;
+}): string;
+/** Validate a graph shape; throw `PEAKS_GRAPH_CORRUPTED` on any violation. */
+export declare function validateGraph(graph: unknown): WorkflowGraph;
+/** Read a graph from disk; never falls back to legacy. */
+export declare function readGraph(input: {
+    projectRoot?: string;
+    sessionId?: string;
+    graphRef?: string;
+    workflowId?: WorkflowId;
+    /** Absolute path to a graph file. When supplied, projectRoot/sessionId/graphRef are not required. */
+    graphPath?: string;
+}): WorkflowGraph;
+/** Write a graph atomically (creates dirs as needed). */
+export declare function writeGraph(input: {
+    projectRoot: string;
+    sessionId: string;
+    graphRef: string;
+    workflowId: WorkflowId;
+    graph: WorkflowGraph;
+    holder?: string;
+}): {
+    path: string;
+};
+/** Build a fresh empty graph with one terminal node. */
+export declare function emptyGraph(input: {
+    workflowId: WorkflowId;
+    rootSkill: string;
+    parentWorkflowId?: WorkflowId;
+}): WorkflowGraph;
+/** Validate a `graphRef` is well-formed without writing. */
+export declare function validateGraphRef(input: {
+    graphRef: string;
+    workflowId: WorkflowId;
+    projectRoot: string;
+    sessionId: string;
+}): {
+    path: string;
+};

package/dist/services/workflow/workflow-graph-store.js

@@ -0,0 +1,278 @@
+/**
+ * Workflow graph store (RD §2, §4 — slice 4.0.8 presence-lease-graph).
+ *
+ * Safe-path, locked, atomic graph persistence. Reads fail closed on
+ * malformed JSON / schema violation / cycle / unknown node id. Writes
+ * use a tmp+rename primitive to guarantee no half-written graph on
+ * crash. The store never inspects vendor env vars and never falls
+ * back to a legacy marker when the canonical graph is unreadable —
+ * canonical corruption is surfaced with `PEAKS_GRAPH_CORRUPTED`.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { WORKFLOW_ID_REGEX, NODE_ID_REGEX, isSafeRelativeGraphRef, } from './workflow-graph-types.js';
+export const PEAKS_GRAPH_NOT_FOUND = 'PEAKS_GRAPH_NOT_FOUND';
+export const PEAKS_GRAPH_CORRUPTED = 'PEAKS_GRAPH_CORRUPTED';
+export const PEAKS_GRAPH_CYCLE = 'PEAKS_GRAPH_CYCLE';
+export const PEAKS_GRAPH_REF_BROKEN = 'PEAKS_GRAPH_REF_BROKEN';
+export const PEAKS_GRAPH_NODE_REQUIRED = 'PEAKS_GRAPH_NODE_REQUIRED';
+export const PEAKS_GRAPH_NODE_NOT_PREPARED = 'PEAKS_GRAPH_NODE_NOT_PREPARED';
+export const PEAKS_GRAPH_NODE_KIND_INVALID = 'PEAKS_GRAPH_NODE_KIND_INVALID';
+export const PEAKS_NODE_EXISTS = 'PEAKS_NODE_EXISTS';
+export const PEAKS_NODE_TRANSITION_INVALID = 'PEAKS_NODE_TRANSITION_INVALID';
+export const PEAKS_ENVELOPE_NOT_RECEIVED = 'PEAKS_ENVELOPE_NOT_RECEIVED';
+export const PEAKS_ENVELOPE_GRAPH_MISMATCH = 'PEAKS_ENVELOPE_GRAPH_MISMATCH';
+export const PEAKS_TERMINAL_REASON_INVALID = 'PEAKS_TERMINAL_REASON_INVALID';
+export const PEAKS_TERMINALIZE_ATOMICITY_FAILED = 'PEAKS_TERMINALIZE_ATOMICITY_FAILED';
+export const PEAKS_UNCONSUMED_ENVELOPE = 'PEAKS_UNCONSUMED_ENVELOPE';
+export const PEAKS_DEPENDENCY_NOT_CONSUMED = 'PEAKS_DEPENDENCY_NOT_CONSUMED';
+export const PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR = 'PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR';
+export const PEAKS_SESSION_NOT_BOUND = 'PEAKS_SESSION_NOT_BOUND';
+export const PEAKS_CALLER_NOT_RESOLVED = 'PEAKS_CALLER_NOT_RESOLVED';
+function makeError(code, message, legacyFallback = false) {
+    const err = new Error(message);
+    err.name = 'GraphStoreError';
+    err.code = code;
+    err.legacyFallback = legacyFallback;
+    return err;
+}
+function safeSessionRuntimeRoot(projectRoot, sessionId) {
+    if (!WORKFLOW_ID_REGEX.test(sessionId)) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `invalid sessionId: ${sessionId}`);
+    }
+    const root = resolve(projectRoot);
+    return join(root, '.peaks', '_runtime', sessionId);
+}
+/** Compute the on-disk graph path. Validates `graphRef` stays under the session root. */
+export function graphPathFor(input) {
+    if (!isSafeRelativeGraphRef(input.graphRef, input.workflowId)) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef is not safe: ${input.graphRef}`);
+    }
+    if (!WORKFLOW_ID_REGEX.test(input.workflowId)) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `workflowId is not safe: ${input.workflowId}`);
+    }
+    const sessionRoot = safeSessionRuntimeRoot(input.projectRoot, input.sessionId);
+    const resolved = resolve(sessionRoot, input.graphRef);
+    if (!resolved.startsWith(sessionRoot + sep) && resolved !== sessionRoot) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef escapes session root: ${input.graphRef}`);
+    }
+    return resolved;
+}
+/** Atomically write a graph: tmp + rename. */
+function writeAtomic(targetPath, body) {
+    const dir = dirname(targetPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    writeFileSync(tmpPath, body, 'utf8');
+    renameSync(tmpPath, targetPath);
+}
+/** Acquire a short-lived atomic update lock. */
+function acquireLock(lockPath, holder, ttlMs = 30_000) {
+    const lockDir = dirname(lockPath);
+    if (!existsSync(lockDir))
+        mkdirSync(lockDir, { recursive: true });
+    if (existsSync(lockPath)) {
+        const stat = statSync(lockPath);
+        if (stat.mtimeMs + ttlMs < Date.now()) {
+            // Stale lock — remove and continue.
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* swallow */ }
+        }
+        else {
+            throw makeError('PEAKS_GRAPH_LOCK_HELD', `graph lock held: ${lockPath}`);
+        }
+    }
+    writeFileSync(lockPath, holder, 'utf8');
+}
+function releaseLock(lockPath) {
+    try {
+        if (existsSync(lockPath))
+            unlinkSync(lockPath);
+    }
+    catch { /* swallow */ }
+}
+/** Detect cycles in a node-dependency graph. */
+function detectCycle(nodes) {
+    const map = new Map();
+    for (const n of nodes)
+        map.set(n.id, n);
+    const color = new Map();
+    const visiting = (id) => {
+        const c = color.get(id) ?? 0;
+        if (c === 1)
+            return true;
+        if (c === 2)
+            return false;
+        color.set(id, 1);
+        const node = map.get(id);
+        if (node) {
+            for (const dep of node.dependsOn) {
+                if (visiting(dep))
+                    return true;
+            }
+        }
+        color.set(id, 2);
+        return false;
+    };
+    for (const n of nodes) {
+        if (visiting(n.id))
+            return true;
+    }
+    return false;
+}
+/** Validate a graph shape; throw `PEAKS_GRAPH_CORRUPTED` on any violation. */
+export function validateGraph(graph) {
+    if (typeof graph !== 'object' || graph === null) {
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'graph is not an object');
+    }
+    const g = graph;
+    if (typeof g.workflowId !== 'string' || !WORKFLOW_ID_REGEX.test(g.workflowId)) {
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'workflowId missing or invalid');
+    }
+    if (typeof g.rootSkill !== 'string' || g.rootSkill.length === 0) {
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'rootSkill missing');
+    }
+    if (g.parentWorkflowId !== undefined && typeof g.parentWorkflowId !== 'string') {
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'parentWorkflowId must be a string when present');
+    }
+    if (!Array.isArray(g.nodes))
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'nodes missing');
+    if (!Array.isArray(g.edges))
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'edges missing');
+    if (g.schemaVersion !== 1)
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'schemaVersion must be 1');
+    const ids = new Set();
+    let terminalCount = 0;
+    for (const n of g.nodes) {
+        if (typeof n.id !== 'string' || !NODE_ID_REGEX.test(n.id)) {
+            throw makeError(PEAKS_GRAPH_CORRUPTED, `invalid node id: ${String(n.id)}`);
+        }
+        if (ids.has(n.id))
+            throw makeError(PEAKS_GRAPH_CORRUPTED, `duplicate node id: ${n.id}`);
+        ids.add(n.id);
+        if (!['step', 'dispatch', 'terminal'].includes(n.kind)) {
+            throw makeError(PEAKS_GRAPH_CORRUPTED, `invalid node kind: ${n.kind}`);
+        }
+        if (typeof n.label !== 'string' || n.label.length === 0) {
+            throw makeError(PEAKS_GRAPH_CORRUPTED, 'label missing');
+        }
+        if (!Array.isArray(n.dependsOn)) {
+            throw makeError(PEAKS_GRAPH_CORRUPTED, 'dependsOn must be an array');
+        }
+        if (n.kind === 'terminal')
+            terminalCount += 1;
+        if (n.kind !== 'dispatch') {
+            if (n.dispatchRef !== undefined || n.lastHeartbeat !== undefined) {
+                throw makeError(PEAKS_GRAPH_CORRUPTED, 'dispatchRef/lastHeartbeat only valid on dispatch nodes');
+            }
+        }
+    }
+    if (terminalCount !== 1) {
+        throw makeError(PEAKS_GRAPH_CORRUPTED, `exactly one terminal node required (got ${terminalCount})`);
+    }
+    for (const e of g.edges) {
+        if (typeof e.from !== 'string' || !ids.has(e.from)) {
+            throw makeError(PEAKS_GRAPH_CORRUPTED, `edge from unknown node: ${String(e.from)}`);
+        }
+        if (typeof e.to !== 'string' || !ids.has(e.to)) {
+            throw makeError(PEAKS_GRAPH_CORRUPTED, `edge to unknown node: ${String(e.to)}`);
+        }
+    }
+    for (const n of g.nodes) {
+        for (const dep of n.dependsOn) {
+            if (!ids.has(dep)) {
+                throw makeError(PEAKS_GRAPH_CORRUPTED, `dependsOn references unknown node: ${dep}`);
+            }
+        }
+    }
+    if (detectCycle(g.nodes)) {
+        throw makeError(PEAKS_GRAPH_CORRUPTED, 'graph contains a cycle');
+    }
+    return graph;
+}
+/** Read a graph from disk; never falls back to legacy. */
+export function readGraph(input) {
+    // Accept either a fully-resolved absolute graphPath or a (projectRoot,
+    // sessionId, graphRef, workflowId) tuple.
+    const path = typeof input.graphPath === 'string' && input.graphPath.length > 0
+        ? input.graphPath
+        : graphPathFor({
+            projectRoot: input.projectRoot ?? '',
+            sessionId: input.sessionId ?? '',
+            graphRef: input.graphRef ?? '',
+            workflowId: input.workflowId ?? '',
+        });
+    if (!existsSync(path)) {
+        throw makeError(PEAKS_GRAPH_NOT_FOUND, `graph not found: ${path}`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw makeError(PEAKS_GRAPH_CORRUPTED, `graph read failed: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        // Canonical corruption — must escape; never substitute legacy marker.
+        throw makeError(PEAKS_GRAPH_CORRUPTED, `graph JSON malformed: ${err.message}`, false);
+    }
+    // Confirm parsed graph's workflowId matches the supplied one (when provided);
+    // otherwise it's a graphRef mismatch (e.g. stale graph swapped under the lease).
+    if (typeof input.workflowId === 'string' && input.workflowId.length > 0
+        && typeof parsed === 'object' && parsed !== null) {
+        const wf = parsed.workflowId;
+        if (typeof wf === 'string' && wf !== input.workflowId) {
+            throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef points at foreign workflow: ${wf} vs ${input.workflowId}`, false);
+        }
+    }
+    return validateGraph(parsed);
+}
+/** Write a graph atomically (creates dirs as needed). */
+export function writeGraph(input) {
+    const path = graphPathFor(input);
+    validateGraph(input.graph);
+    const lockPath = `${path}.lock`;
+    acquireLock(lockPath, input.holder ?? `pid:${process.pid}`);
+    try {
+        writeAtomic(path, JSON.stringify(input.graph, null, 2));
+    }
+    finally {
+        releaseLock(lockPath);
+    }
+    return { path };
+}
+/** Build a fresh empty graph with one terminal node. */
+export function emptyGraph(input) {
+    const graph = {
+        workflowId: input.workflowId,
+        rootSkill: input.rootSkill,
+        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
+        nodes: [
+            {
+                id: 'terminal',
+                kind: 'terminal',
+                label: 'workflow complete',
+                status: 'prepared',
+                dependsOn: [],
+                ackStatus: 'not-required',
+            },
+        ],
+        edges: [],
+        schemaVersion: 1,
+    };
+    return graph;
+}
+/** Validate a `graphRef` is well-formed without writing. */
+export function validateGraphRef(input) {
+    return { path: graphPathFor(input) };
+}
+/** Suppress unused import warnings. */
+void isAbsolute;
+void dirname;

package/dist/services/workflow/workflow-graph-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Workflow graph schemas (RD §2 — slice 4.0.8 presence-lease-graph).
+ *
+ * Pure type definitions and Zod-free runtime validators (we keep
+ * types synchronous + cheap; the on-disk validation lives in the
+ * graph store). The types here are the canonical reference for
+ * transitions, node kinds, and edge invariants.
+ *
+ * No vendor env lookups; no filesystem I/O.
+ */
+export type WorkflowId = string;
+export type NodeId = string;
+export type GraphNodeKind = 'step' | 'dispatch' | 'terminal';
+export type GraphNodeStatus = 'prepared' | 'dispatched' | 'running' | 'envelope-received' | 'consumed-by-parent' | 'terminalized' | 'lost';
+export type AckStatus = 'pending' | 'acknowledged' | 'not-required';
+export type TerminalReason = 'success' | 'aborted' | 'sub-agent-crashed' | 'ttl-expired' | 'outer-session-mismatch' | 'parent-acked-no-envelope' | 'graph-corrupted' | 'unknown';
+export declare const TERMINAL_REASONS: ReadonlyArray<TerminalReason>;
+export type LeaseStatus = 'preparing' | 'running' | 'terminalized' | 'lost';
+export declare const LEASE_STATUSES: ReadonlyArray<LeaseStatus>;
+export declare const GRAPH_NODE_STATUSES: ReadonlyArray<GraphNodeStatus>;
+export interface WorkflowGraphEdge {
+    readonly from: NodeId;
+    readonly to: NodeId;
+}
+export interface WorkflowGraphNode {
+    readonly id: NodeId;
+    readonly kind: GraphNodeKind;
+    readonly label: string;
+    readonly status: GraphNodeStatus;
+    readonly dispatchRef?: string;
+    readonly lastHeartbeat?: string;
+    readonly ackStatus?: AckStatus;
+    readonly dependsOn: readonly NodeId[];
+}
+export interface WorkflowGraph {
+    readonly workflowId: WorkflowId;
+    readonly rootSkill: string;
+    readonly parentWorkflowId?: WorkflowId;
+    readonly nodes: readonly WorkflowGraphNode[];
+    readonly edges: readonly WorkflowGraphEdge[];
+    readonly schemaVersion: 1;
+}
+/**
+ * `id` regex: ASCII letters, digits, dot, underscore, hyphen; 1-200 chars.
+ * Excludes path separators / NUL / whitespace / Unicode (per D1 of the
+ * caller-id contract — node ids appear in file paths).
+ */
+export declare const NODE_ID_REGEX: RegExp;
+export declare const WORKFLOW_ID_REGEX: RegExp;
+export declare const DISPATCH_REF_REGEX: RegExp;
+/** `graphRef` must normalize to `graphs/<workflowId>.json`. */
+export declare function normalizeGraphRef(graphRef: string, workflowId: WorkflowId): string;
+/** Validate `graphRef` does not escape the session directory. */
+export declare function isSafeRelativeGraphRef(graphRef: string, workflowId: WorkflowId): boolean;
+/** Throws `TypeError` with `code` set on shape failure (used by pure validators). */
+export declare function failShape(code: string, message: string): never;