peaks-loop 4.0.7 → 4.0.9

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;

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

@@ -0,0 +1,67 @@
+/**
+ * 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 const TERMINAL_REASONS = [
+    'success',
+    'aborted',
+    'sub-agent-crashed',
+    'ttl-expired',
+    'outer-session-mismatch',
+    'parent-acked-no-envelope',
+    'graph-corrupted',
+    'unknown',
+];
+export const LEASE_STATUSES = [
+    'preparing',
+    'running',
+    'terminalized',
+    'lost',
+];
+export const GRAPH_NODE_STATUSES = [
+    'prepared',
+    'dispatched',
+    'running',
+    'envelope-received',
+    'consumed-by-parent',
+    'terminalized',
+    'lost',
+];
+/**
+ * `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 const NODE_ID_REGEX = /^[a-zA-Z0-9._-]{1,200}$/;
+export const WORKFLOW_ID_REGEX = /^[a-zA-Z0-9._-]{1,200}$/;
+export const DISPATCH_REF_REGEX = /^dispatch\/[a-zA-Z0-9._/-]{1,400}\.json$/;
+/** `graphRef` must normalize to `graphs/<workflowId>.json`. */
+export function normalizeGraphRef(graphRef, workflowId) {
+    return `graphs/${workflowId}.json`;
+}
+/** Validate `graphRef` does not escape the session directory. */
+export function isSafeRelativeGraphRef(graphRef, workflowId) {
+    if (typeof graphRef !== 'string' || graphRef.length === 0)
+        return false;
+    if (graphRef !== normalizeGraphRef(graphRef, workflowId))
+        return false;
+    if (graphRef.includes('\\'))
+        return false;
+    if (graphRef.includes('..'))
+        return false;
+    if (graphRef.startsWith('/'))
+        return false;
+    return true;
+}
+/** Throws `TypeError` with `code` set on shape failure (used by pure validators). */
+export function failShape(code, message) {
+    const err = new TypeError(message);
+    err.code = code;
+    throw err;
+}

package/dist/services/workflow/workflow-inflight-probe.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Workflow in-flight probe (RD §4 D4d — slice 4.0.8).
+ *
+ * The single source of truth for `inFlightBatch` in 24h mode is the
+ * set of `status=running && age(lastHeartbeat)<30min` nodes across
+ * all valid graphs for the bound session. No CLI boolean or lease-age
+ * heuristic may override graph facts in production. This probe is the
+ * production replacement for the previous lease-age `inFlightBatch`
+ * computation in `auto-compact-orchestrator.ts`.
+ */
+import { type GraphNodeStatus, type WorkflowId } from './workflow-graph-types.js';
+export declare const FRESH_RUNNING_THRESHOLD_MS: number;
+export declare const PEAKS_HEARTBEAT_MISSING = "PEAKS_HEARTBEAT_MISSING";
+export declare const PEAKS_GRAPH_REF_BROKEN = "PEAKS_GRAPH_REF_BROKEN";
+export declare const PEAKS_GRAPH_CORRUPTED = "PEAKS_GRAPH_CORRUPTED";
+export interface ProbeGraph {
+    readonly workflowId?: WorkflowId;
+    readonly rootSkill?: string;
+    readonly nodes?: ReadonlyArray<{
+        readonly id?: string;
+        readonly kind?: string;
+        readonly status?: GraphNodeStatus;
+        readonly lastHeartbeat?: string;
+    }>;
+    readonly edges?: ReadonlyArray<unknown>;
+    readonly schemaVersion?: number;
+    /** Sentinel for corrupt graphs the test seam wants to surface as broken. */
+    readonly corrupt?: boolean;
+    readonly graphRef?: string;
+}
+export interface ProbeInput {
+    readonly now: string;
+    readonly graphs: ReadonlyArray<ProbeGraph>;
+    readonly leases?: ReadonlyArray<unknown>;
+    readonly redLine?: boolean;
+    readonly autoCompact?: boolean;
+}
+export interface ProbeWarning {
+    readonly code: string;
+    readonly message: string;
+    readonly graphRef?: string;
+    readonly nodeId?: string;
+}
+export interface ProbeResult {
+    readonly inFlightBatch: boolean;
+    readonly shouldCompact: boolean;
+    readonly deferPreCompact: boolean;
+    readonly warnings: ReadonlyArray<ProbeWarning>;
+    readonly errors: ReadonlyArray<ProbeWarning>;
+    readonly reason: string;
+}
+export declare function probeInFlightBatch(input: ProbeInput): ProbeResult;

package/dist/services/workflow/workflow-inflight-probe.js

@@ -0,0 +1,86 @@
+/**
+ * Workflow in-flight probe (RD §4 D4d — slice 4.0.8).
+ *
+ * The single source of truth for `inFlightBatch` in 24h mode is the
+ * set of `status=running && age(lastHeartbeat)<30min` nodes across
+ * all valid graphs for the bound session. No CLI boolean or lease-age
+ * heuristic may override graph facts in production. This probe is the
+ * production replacement for the previous lease-age `inFlightBatch`
+ * computation in `auto-compact-orchestrator.ts`.
+ */
+export const FRESH_RUNNING_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
+export const PEAKS_HEARTBEAT_MISSING = 'PEAKS_HEARTBEAT_MISSING';
+export const PEAKS_GRAPH_REF_BROKEN = 'PEAKS_GRAPH_REF_BROKEN';
+export const PEAKS_GRAPH_CORRUPTED = 'PEAKS_GRAPH_CORRUPTED';
+const NON_RUNNING = new Set([
+    'prepared',
+    'dispatched',
+    'envelope-received',
+    'consumed-by-parent',
+    'terminalized',
+    'lost',
+]);
+export function probeInFlightBatch(input) {
+    const nowMs = new Date(input.now).getTime();
+    const warnings = [];
+    const errors = [];
+    let inFlight = false;
+    for (const graph of input.graphs) {
+        if (graph.corrupt === true || graph.schemaVersion !== 1) {
+            errors.push({
+                code: PEAKS_GRAPH_REF_BROKEN,
+                message: 'corrupt or missing graph',
+                ...(graph.graphRef ? { graphRef: graph.graphRef } : {}),
+            });
+            continue;
+        }
+        if (!graph.nodes || !Array.isArray(graph.nodes)) {
+            errors.push({
+                code: PEAKS_GRAPH_CORRUPTED,
+                message: 'graph.nodes missing',
+                ...(graph.graphRef ? { graphRef: graph.graphRef } : {}),
+            });
+            continue;
+        }
+        for (const node of graph.nodes) {
+            if (node.status !== 'running')
+                continue;
+            if (!node.lastHeartbeat || typeof node.lastHeartbeat !== 'string') {
+                warnings.push({
+                    code: PEAKS_HEARTBEAT_MISSING,
+                    message: 'running node missing lastHeartbeat',
+                    ...(node.id ? { nodeId: node.id } : {}),
+                });
+                continue;
+            }
+            const hbMs = new Date(node.lastHeartbeat).getTime();
+            if (!Number.isFinite(hbMs)) {
+                warnings.push({
+                    code: PEAKS_HEARTBEAT_MISSING,
+                    message: 'heartbeat unparseable',
+                    ...(node.id ? { nodeId: node.id } : {}),
+                });
+                continue;
+            }
+            const age = nowMs - hbMs;
+            if (age < FRESH_RUNNING_THRESHOLD_MS) {
+                inFlight = true;
+            }
+        }
+    }
+    // Red-line compaction overrides in-flight deferral (RD §8 TC-IF-09).
+    const shouldCompact = input.redLine === true ? true : !inFlight;
+    const deferPreCompact = inFlight;
+    return {
+        inFlightBatch: inFlight,
+        shouldCompact,
+        deferPreCompact,
+        warnings,
+        errors,
+        reason: inFlight
+            ? 'fresh-running-node'
+            : (errors.length > 0 ? 'corrupt-graphs' : 'no-fresh-running-node'),
+    };
+}
+void NON_RUNNING;
+void {};

package/dist/services/workflow/workflow-node-lifecycle.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Workflow node lifecycle — pure transition tables (RD §3).
+ *
+ * Pure functions: no filesystem, no env access. The transition
+ * tables encode the allowed lease + node status transitions defined
+ * in RD §3. Forbidden transitions return a typed error code so the
+ * CLI / orchestrator can surface actionable hints.
+ *
+ * Anti-fake-green rule: this module never imports a vendor env var.
+ * The vendor signal lives entirely in the IDE adapters.
+ */
+import { type GraphNodeStatus, type LeaseStatus, type AckStatus, type WorkflowGraph, type WorkflowGraphNode, type NodeId, type WorkflowId } from './workflow-graph-types.js';
+export interface LifecycleError extends Error {
+    readonly code: string;
+}
+export declare function transitionLease(from: LeaseStatus, to: LeaseStatus, input?: Record<string, unknown>): Record<string, unknown>;
+export declare function transitionNode(from: GraphNodeStatus, to: GraphNodeStatus, input?: Record<string, unknown>): Record<string, unknown>;
+export declare function acknowledgeNode(node: WorkflowGraphNode): WorkflowGraphNode;
+export declare function markNodeLost(node: WorkflowGraphNode, reason: string): WorkflowGraphNode;
+declare function _purePrepareNode(graph: WorkflowGraph, node: WorkflowGraphNode): WorkflowGraph;
+export declare function isFirstHeartbeat(node: WorkflowGraphNode, inputFirstHeartbeat: unknown): boolean;
+export declare function buildGraphNode(input: {
+    id: NodeId;
+    kind: 'step' | 'dispatch' | 'terminal';
+    label: string;
+    status: GraphNodeStatus;
+    dispatchRef?: string;
+    lastHeartbeat?: string;
+    ackStatus?: AckStatus;
+    dependsOn?: readonly NodeId[];
+}): WorkflowGraphNode;
+export interface GraphDispatchBinding {
+    readonly workflowId: WorkflowId;
+    readonly graphNodeId: NodeId;
+    readonly graphRef: string;
+}
+export declare function resolveDispatchBinding(input: {
+    workflowId?: WorkflowId;
+    graphNodeId?: NodeId;
+    graphRef?: string;
+}): GraphDispatchBinding;
+export interface NodeLifecycleInput {
+    readonly projectRoot?: string;
+    readonly sessionId?: string;
+    readonly workflowId?: string;
+    readonly graphRef?: string;
+    readonly nodeId?: string;
+    readonly graphNode?: WorkflowGraphNode;
+    readonly dispatchRef?: string;
+    readonly envelopeDispatchRef?: string;
+    readonly status?: GraphNodeStatus;
+    readonly lastHeartbeat?: string;
+    readonly firstHeartbeat?: boolean;
+    readonly dependsOn?: readonly NodeId[];
+    readonly duplicate?: boolean;
+    readonly cycle?: boolean;
+}
+export declare function prepareNodeAction(input: NodeLifecycleInput): WorkflowGraphNode;
+export declare function dispatchNode(input: NodeLifecycleInput): Record<string, unknown>;
+export declare function heartbeatNode(input: NodeLifecycleInput): Record<string, unknown>;
+export declare function writeEnvelope(input: NodeLifecycleInput): Record<string, unknown>;
+export declare function ackNode(input: NodeLifecycleInput): Record<string, unknown>;
+export declare function markLost(input: NodeLifecycleInput): Record<string, unknown>;
+export declare function prepareNode(arg1: WorkflowGraph | NodeLifecycleInput, arg2?: WorkflowGraphNode): WorkflowGraph | WorkflowGraphNode;
+export declare const nodePrepare: typeof prepareNodeAction;
+export declare const nodePreparePure: typeof _purePrepareNode;
+export {};