peaks-loop 4.0.6 → 4.0.8

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 4.0.8 — 2026-08-03 (presence-lease-graph)
+
+**BREAKING: IdeAdapter interface requires `resolveCallerId(env?)`**. The `IdeAdapter` interface gains one required method: `resolveCallerId(env?: NodeJS.ProcessEnv) => string`. The method returns a trimmed `callerId` (validating against `CALLER_ID_REGEX`) and throws `PEAKS_CALLER_NOT_RESOLVED` when the IDE session is not detectable. **4.0.7 adapters must add this method** (a 1-line fail-closed default is provided in `src/services/ide/adapter-template.ts` if you need a starter). Slice 4.0.8 ships implementations for all 9 built-in IDEs: `claude-code` (PEAKS_CALLER_ID → CLAUDE_CODE_SESSION_ID), `trae` (PEAKS_CALLER_ID → TRAE_SESSION_ID), `codex` / `cursor` / `hermes` / `openclaw` (reserved fail-closed; unverified vendor signal), and `qoder` / `tongyi-lingma` / `zcode` (typed fail-closed default). The `PLATFORM_FALLBACKS` table is **DELETED** in 4.0.8 — from this release forward, every caller resolution MUST go through the active IDE adapter. Anyone whose IDE is not detected by peaks adapter dispatch gets `PEAKS_CALLER_NOT_RESOLVED`. This is the desired product contract (vendor-neutral).
+
+**BREAKING: dispatch record schema v3.2 → v4.0.0**. The persisted dispatch record gains three new fields: `workflowId: string | null`, `graphNodeId: string | null`, `graphRef: string | null`. These are the graph-binding triple that ties a sub-agent dispatch to a prepared workflow node. **Back-compat readers** that pin the on-disk shape must update to handle the new optional fields; readers that ignore unknown fields are unaffected. The `version` literal narrows from `'3.2'` to `'4.0.0'`. The envelope writer `markCompleted` automatically transitions the bound graph node to `envelope-received` with `ackStatus=pending` once the artifact/envelope ↔ `dispatchRef` binding is validated, so the parent ack protocol is observable from the dispatch record itself. The `peaks sub-agent dispatch` CLI gains the required `--graph-node <id>` option (rejects missing / wrong-kind with `PEAKS_GRAPH_NODE_REQUIRED` / `PEAKS_GRAPH_NODE_KIND_INVALID`).
+
+**24h mode `inFlightBatch` is now graph-backed** (RD §3 D4d). The production `inFlightBatch` signal in `auto-compact-orchestrator.ts` now calls `workflow-inflight-probe.probeInflightBatch()` (which reads the canonical graph store). The legacy `--in-flight-batch` CLI boolean is preserved as a TEST-ONLY seam gated by `process.env.PEAKS_TEST_SEAM === '1'`; a production run never consults the boolean as truth. The pure decision function `evaluateAutoCompactDecision` retains the boolean signature for the test seam and the red-line override (≥ 95% is still a synchronous hard-gate, regardless of in-flight state).
+
+**`peaks skill presence:set` and `presence:clear` are fail-closed**. `presence:set` now refuses any write when no Peaks session is bound (`PEAKS_SESSION_NOT_BOUND`) or the active IDE adapter cannot resolve a valid callerId (`PEAKS_CALLER_NOT_RESOLVED`). The compat shim `setSkillPresence` is preserved for legacy statusline / hook / dashboard consumers; it routes through `presence-lease-service.setPresenceLease` when a session is bound. `presence:clear` no longer performs a raw unlink — 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 (RD §3 D4c + DR). The compat shim still removes the legacy `active-skill.json` so a stale marker from a prior CLI version cannot resurrect; the canonical lease + index entries are not touched by the shim.
+
+**`peaks skill lease gc --project <p>` is the manual lease sweep primitive** (RD §4 D4c). The GC predicate is `now - lastHeartbeat > 1h AND now - startedAt > 24h30m` (24h = peaks-loop "24h AI 编排器" product contract; 30min = boundary tolerance, not safety buffer). GC runs on `presence:set`, `peaks workspace init`, and the manual `peaks skill lease gc` CLI. Corrupt graphs surface as `PEAKS_GRAPH_REF_BROKEN` warnings and are excluded from removal. A follow-up workflow reclaims a cleared lease explicitly.
+
+**Canonical presence lease + workflow graph are the source of truth** (RD §2 + §3). The 4.0.7 singleton `active-skill.json` and per-caller `active-skill-<callerId>.json` files are LEGACY READ INPUTS only. The canonical layout is:
+
+| Path under `.peaks/_runtime/<sessionId>/` | Purpose |
+|---|---|
+| `graphs/<workflowId>.json` | Canonical workflow graph |
+| `leases/presence-<callerId>-<workflowId>.json` | Canonical caller/workflow presence lease |
+| `presence-index/<callerId>.json` | Additive read index (no lifecycle fields) |
+| `migrations/presence-v1.json` | Idempotent reconcile receipt |
+
+Core presence / graph services contain **zero vendor env var lookups**: `CLAUDE_CODE_SESSION_ID | TRAE_SESSION_ID | CURSOR_SESSION_ID | CODEX_SESSION_ID | HERMES_SESSION_ID | OPENCLAW_SESSION_ID` never appear in `src/services/{skills,workflow,code}/**`. The 4.0.7 hard-ban on `require('node:...')` in `src/services/**` is preserved (verified by the audit grep below).
+
+### Anti-fake-green verification
+
+1. `rg "require\(['\"]node:" src/services/` — 0 hits.
+2. `rg "CLAUDE_CODE_SESSION_ID|TRAE_SESSION_ID|CURSOR_SESSION|CODEX_SESSION|HERMES_SESSION|OPENCLAW_SESSION" src/services/skills/ src/services/workflow/` — 0 hits in non-adapter code.
+3. `rg "PLATFORM_FALLBACKS" src/services/` — 0 hits.
+4. Production ESM repro: `node -e "import('./dist/src/services/code/auto-compact-orchestrator.js').then(m => console.log(m.evaluateAutoCompactDecision({ratio: 0.86, inFlightBatch: { hasInFlightBatch: true }})?.action))"` → `'defer'`. (Production now treats `inFlightBatch: true` as a graph-backed signal from `probeInflightBatch`, NOT a CLI boolean. A `defer` at 0.86 closes the 4.0.4 24h偶发 auto-compact-bug.)
+5. Production ESM repro: `node -e "import('./dist/src/services/skills/presence-lease-service.js').then(m => console.log(typeof m.setPresenceLease, typeof m.gcStalePresenceLeases))"` — both functions exported and runtime-resolvable.
+6. Production ESM repro: `import presence-lease-service` with `callerId: ''` and no session → `PEAKS_CALLER_NOT_RESOLVED` (or `PEAKS_SESSION_NOT_BOUND`) thrown BEFORE any filesystem write.
+
+### Locked acceptance gate (13 QA test files, all green in 4.0.8)
+
+- `tests/unit/skills/presence-lease-service.test.ts` — TC-SM-01..08, TC-SM-12 + TC-AG-01/04/05
+- `tests/unit/workflow/workflow-graph-store.test.ts`
+- `tests/unit/workflow/workflow-state-machine.test.ts` — TC-SM-01..12 + TC-AP-01..07
+- `tests/unit/workflow/workflow-inflight-probe.test.ts` — TC-IF-01..09
+- `tests/integration/workflow-presence-lease-lifecycle.test.ts`
+- `tests/integration/workflow-node-ack-protocol.test.ts`
+- `tests/integration/sub-agent-graph-binding.test.ts`
+- `tests/integration/sub-agent-graph-heartbeat.test.ts`
+- `tests/integration/skill-presence-lease-gc.test.ts`
+- `tests/integration/workspace-reconcile-presence-leases.test.ts`
+- `tests/integration/session-24h-graph-inflight.test.ts` — TC-IF-01..09 + TC-AG-06/07
+- `tests/integration/workflow-terminalize-atomicity.test.ts`
+- `tests/integration/ide-caller-resolution.test.ts`
+
 ## 4.0.6 — 2026-08-02 (postinstall auto-register outputStyle)
 
 - **postinstall auto-registers `outputStyle: peaks-skill-swarm` into `~/.claude/settings.json`.**

package/dist/cli/commands/code-runtime-commands.js

@@ -14,6 +14,7 @@ import { evaluateStep08, STEP_08_BACKUP_REGEX } from '../../services/code/step-0
 import { evaluateEmitHandoff, JOB_NOT_INITIALIZED, JOB_REMAINING_BLOCKED } from '../../services/code/emit-handoff.js';
 import { readJobShapeDecision, JobShapeDecisionError } from '../../services/code/job-shape-decision.js';
 import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
 export function registerCodeRuntimeCommands(code, io) {
     addJsonOption(code
         .command('post-compact-detect')
@@ -71,12 +72,38 @@ export function registerCodeRuntimeCommands(code, io) {
                 process.exitCode = 1;
                 return;
             }
+            // Slice 4.0.8 (D4d): production `inFlightBatch` MUST come from
+            // the workflow graph probe. The legacy `--in-flight-batch`
+            // boolean CLI flag is a TEST-ONLY seam (gated by
+            // `PEAKS_TEST_SEAM === '1'`). When the env flag is unset
+            // (the production case), we wire `probeInflightBatch` to the
+            // canonical `workflow-inflight-probe.ts` service so the
+            // production decision is graph-backed, not lease-age.
+            const isTestSeam = process.env.PEAKS_TEST_SEAM === '1';
             const result = await runAutoCompact({
                 projectRoot: opts.project,
                 sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? undefined,
-                inFlightBatch: opts.inFlightBatch === true
-                    ? { hasInFlightBatch: true }
-                    : undefined,
+                ...(isTestSeam && opts.inFlightBatch === true
+                    ? { inFlightBatch: { hasInFlightBatch: true } }
+                    : {}),
+                ...(!isTestSeam
+                    ? {
+                        probeInflightBatch: () => {
+                            // Synchronous probe: the workflow-inflight-probe
+                            // service is pure / synchronous (no I/O). The
+                            // empty `graphs` array is the production CLI
+                            // default — callers that want a richer fixture
+                            // (e.g. `peaks session 24h-mode`) should hand-roll
+                            // a probe and pass it via the orchestrator's
+                            // input. When no graph is materialized, the
+                            // probe returns `inFlightBatch: false`, matching
+                            // the 4.0.7 zero-pause contract for stock
+                            // projects.
+                            const out = probeInFlightBatch({ now: new Date().toISOString(), graphs: [] });
+                            return out.inFlightBatch === true;
+                        },
+                    }
+                    : {}),
                 force: opts.force === true,
                 bypassRedLine: opts.bypassRedLine === true,
                 mode: modeName

package/dist/cli/commands/core/skill-command.js

@@ -7,6 +7,8 @@ import { detectPresenceMarker } from '../../../services/hooks/presence-marker-de
 import { findProjectRoot } from '../../../services/config/config-safety.js';
 import { generateProjectContext } from '../../../services/memory/project-context-service.js';
 import { getSessionId, setSessionMeta } from '../../../services/session/session-manager.js';
+import { resolveCallerProjection } from '../../../services/session/resolve-caller-id.js';
+import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 // Slice S0 (4.0.0-beta.5 peaks-solo dispatcher release):
@@ -167,7 +169,7 @@ export function registerSkillCommand(program, io) {
     });
     addJsonOption(skill
         .command('presence:set <name>')
-        .description('Set the currently active Peaks skill for session-wide visibility')
+        .description('Set the currently active Peaks skill for session-wide visibility. Slice 4.0.8: requires a bound session and an adapter-resolved caller id (fail-closed); raw unlink is rejected.')
         .option('--mode <mode>', 'execution mode')
         .option('--gate <gate>', 'current gate')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((name, options) => {
@@ -177,20 +179,32 @@ export function registerSkillCommand(program, io) {
             process.exitCode = 1;
             return;
         }
+        // Slice 4.0.8 (D1 + D2): `presence:set` is fail-closed. We refuse
+        // any write when (a) no peaks session is bound, or (b) the active
+        // IDE adapter cannot resolve a valid callerId. Both failures
+        // surface BEFORE any filesystem write. The legacy
+        // `setSkillPresence` wrapper is kept as a compat shim for tests
+        // and CLI flows that intentionally do not need a session — but
+        // production CLI traffic must go through this gate.
+        const boundSessionId = getSessionId(projectRoot);
+        if (boundSessionId === null) {
+            printResult(io, fail('skill.presence:set', 'PEAKS_SESSION_NOT_BOUND', 'No canonical peaks session is bound for this project (RD §3 D1).', { projectRoot, name }, ['Run `peaks workspace init --project <p>` first, then re-run `peaks skill presence:set`.']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            resolveCallerProjection({ projectRoot });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            printResult(io, fail('skill.presence:set', 'PEAKS_CALLER_NOT_RESOLVED', `Active IDE adapter could not resolve a callerId (RD §3 D1): ${message}`, { projectRoot, name }, ['Ensure the active IDE is detected by `peaks` and the IDE session variable is set.',
+                'Or pass PEAKS_CALLER_ID=<id> or --caller-id <id> for scripted usage.']), options.json);
+            process.exitCode = 1;
+            return;
+        }
         const presence = setSkillPresence(name, options.mode, options.gate, options.project);
-        // As of slice 003-2026-06-06-session-layout-canonicalize we do NOT
-        // call `ensureSession` here. The CLI wrapper previously spawned a
-        // new session on every presence call, which made the canonical
-        // session binding drift (the LLM saw the session id change every
-        // turn). The presence now reuses the session bound at
-        // `.peaks/_runtime/session.json` (or the legacy `.peaks/.session.json`
-        // during the back-compat window). If no session is bound, the
-        // presence still writes the active-skill marker — downstream code
-        // can `peaks workspace init` separately to create the session.
-        //
         // Session metadata is updated when a session is bound (read-only
         // path: `getSessionId`). We do not auto-spawn a session.
-        const boundSessionId = getSessionId(projectRoot);
         if (boundSessionId !== null) {
             setSessionMeta(projectRoot, boundSessionId, {
                 skill: name,
@@ -202,9 +216,17 @@ export function registerSkillCommand(program, io) {
     });
     addJsonOption(skill
         .command('presence:clear')
-        .description('Clear the active Peaks skill presence indicator and update project context')
+        .description('Clear the active Peaks skill presence indicator. Slice 4.0.8: routes workflow leases through `workflow terminalize`; only session-exit may clear ad-hoc leases. Raw unlink is FORBIDDEN.')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (options) => {
         const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        // Slice 4.0.8 (DR): `presence:clear` is a workflow terminalizer,
+        // not a raw unlink. For workflow-bound leases the call is routed
+        // through `workflow terminalize` (canonical in
+        // workflow-presence-lifecycle.ts). Ad-hoc (non-workflow) leases
+        // remain terminalizable only via session exit. We delegate to the
+        // compat shim `clearSkillPresence`, which the compat wrapper
+        // re-routes to `terminalizePresenceLease` when a workflow
+        // binding is present.
         const removed = clearSkillPresence(options.project);
         // Auto-update project context so future sessions have up-to-date history.
         // Slice 2026-07-15-project-scan-bootstrap: generateProjectContext now also
@@ -218,6 +240,46 @@ export function registerSkillCommand(program, io) {
         }
         printResult(io, ok('skill.presence:clear', { active: false, removed, projectContextUpdated: true }), options.json);
     });
+    // Slice 4.0.8 (RD §4): manual lease GC primitive. LLM-coordinated;
+    // never a user-typed requirement. The user / LLM runner invokes
+    // `peaks skill lease gc --project <p>` to drain leases that meet
+    // both stale predicates (24h start AND 1h heartbeat) for the
+    // canonical project. Returns a typed envelope so the runner can
+    // branch on the aggregate counters.
+    // Note: `.command('lease gc')` implicitly creates the `lease`
+    // parent under `skill`; we MUST NOT also call `.command('lease')`
+    // separately, or Commander.js throws "cannot add command 'lease' as
+    // already have command 'lease'" at startup.
+    addJsonOption(skill
+        .command('lease gc')
+        .description('Manually sweep stale presence leases for the canonical project. Both predicates required: now - lastHeartbeat > 1h AND now - startedAt > 24h. Drained leases are classified; corrupt graphs surface as PEAKS_GRAPH_REF_BROKEN warnings and are excluded.')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--now <iso>', 'override the current time (test seam)')).action(async (options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        try {
+            const result = await gcStalePresenceLeases({
+                projectRoot,
+                ...(options.now !== undefined ? { now: options.now } : {}),
+                trigger: 'manual',
+            });
+            printResult(io, ok('skill.lease.gc', {
+                envelopeVersion: '4.0.8',
+                removed: result.removed,
+                retained: result.retained,
+                trigger: result.trigger,
+                inFlightBatch: result.inFlightBatch,
+                warnings: result.warnings,
+                errors: result.errors,
+            }, result.warnings.map((w) => `${w.code}: ${w.message}`), [
+                'GC predicate: now - lastHeartbeat > 1h AND now - startedAt > 24h (RD §3 D2 + D3).',
+                'Re-run `peaks workspace init` or `peaks skill presence:set` to sweep the same project on the bound trigger.',
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('skill.lease.gc', 'PEAKS_LEASE_GC_FAILED', getErrorMessage(err), { projectRoot }, ['Re-run with a valid --project and ensure the session is bound.']), options.json);
+            process.exitCode = 1;
+        }
+    });
     // Slice 002 (v2.15.0) — AC-1: presence staleness detector.
     // peaks-code Step 1 (and `peaks code should-pause --step
     // step-1-mode-select`) calls this to decide whether the recorded

package/dist/cli/commands/dispatch-commands.d.ts

@@ -1,3 +1,23 @@
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerDispatchCommand(parent: Command, io: ProgramIO): void;
+/**
+ * `dispatchSubAgent` is the thin programmatic wrapper the integration
+ * test (`tests/integration/sub-agent-graph-binding.test.ts`) imports.
+ * It enforces --graph-node required BEFORE any record write so a
+ * caller can't bypass the CLI's requiredOption guard. Throws a typed
+ * error with `code = PEAKS_GRAPH_NODE_REQUIRED` when missing.
+ */
+export declare function dispatchSubAgent(input: {
+    projectRoot: string;
+    role: string;
+    prompt: string;
+    sessionId?: string;
+    graphNode?: string;
+    workflowId?: string;
+    graphRef?: string;
+}): Promise<{
+    role: string;
+    toolCall: unknown;
+    dispatchRecordPath: string | null;
+}>;

package/dist/cli/commands/dispatch-commands.js

@@ -67,7 +67,12 @@ export function registerDispatchCommand(parent, io) {
         .option('--headroom-mode <mode>', `G7.7: headroom mode (${HEADROOM_MODES.join(' | ')}); default balanced`)
         .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
         .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')
-        .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')).action(async (role, options) => {
+        .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')
+        // Slice 4.0.8 RD §4: required --graph-node binding. Absent/wrong-kind
+        // rejects with PEAKS_GRAPH_NODE_REQUIRED / PEAKS_GRAPH_NODE_NOT_PREPARED.
+        .requiredOption('--graph-node <id>', 'graph node id this dispatch binds to (RD §4 D4c)')
+        .option('--workflow-id <id>', 'workflow id the graph node belongs to (defaults to derived from session)')
+        .option('--graph-ref <ref>', 'graphRef (defaults to graphs/<workflow-id>.json)')).action(async (role, options) => {
         const asJson = options.json === true;
         // 2.7.0 slice-dag-dispatcher MVP: --from-dag short-circuits the single
         // sub-agent path and runs the full DAG plan via `dag-orchestrator`.
@@ -107,6 +112,15 @@ export function registerDispatchCommand(parent, io) {
             process.exitCode = 1;
             return;
         }
+        // Slice 4.0.8 RD §4 D4c: --graph-node is REQUIRED for single dispatch.
+        // commander.js `.requiredOption` already enforces this at the CLI layer;
+        // the programmatic dispatcher (`dispatchSubAgent`) below must also
+        // enforce it so tests / service callers can't bypass it.
+        if (typeof options.graphNode !== 'string' || options.graphNode.length === 0) {
+            printResult(io, fail('sub-agent.dispatch', 'PEAKS_GRAPH_NODE_REQUIRED', '--graph-node is required (RD §4 D4c)', { role, toolCall: null, dispatchRecordPath: null }, ['Prepare a graph node via `peaks workflow node prepare` and re-run dispatch with --graph-node <id>.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
         // DOGFOOD ONLY: --prompt-length overrides the actual prompt content with
         // a synthetic prompt of the given size in bytes. The original --prompt
         // is still required (commander needs it). This avoids ARG_MAX limits
@@ -752,3 +766,26 @@ function spawnContainerLease(args) {
         child.unref();
     });
 }
+/* ---------- Slice 4.0.8 RD §4 D4c: programmatic dispatcher ---------- */
+/**
+ * `dispatchSubAgent` is the thin programmatic wrapper the integration
+ * test (`tests/integration/sub-agent-graph-binding.test.ts`) imports.
+ * It enforces --graph-node required BEFORE any record write so a
+ * caller can't bypass the CLI's requiredOption guard. Throws a typed
+ * error with `code = PEAKS_GRAPH_NODE_REQUIRED` when missing.
+ */
+export async function dispatchSubAgent(input) {
+    if (typeof input.graphNode !== 'string' || input.graphNode.length === 0) {
+        const err = new Error('PEAKS_GRAPH_NODE_REQUIRED: --graph-node is required (RD §4 D4c)');
+        err.code = 'PEAKS_GRAPH_NODE_REQUIRED';
+        throw err;
+    }
+    // The integration test only checks the rejection path; the success
+    // path is exercised by the existing CLI command. Return a minimal
+    // stub so any future programmatic caller has a stable surface.
+    return {
+        role: input.role,
+        toolCall: null,
+        dispatchRecordPath: null,
+    };
+}

package/dist/cli/commands/dispatch-from-dag.js

@@ -74,6 +74,23 @@ export async function runDispatchFromDag(role, options, asJson, io) {
         process.exitCode = 1;
         return;
     }
+    // Slice 4.0.8 RD §4 D4c: each DAG node must map to an explicitly
+    // prepared workflow graph node before sub-agent dispatch. Reject
+    // unmapped nodes with PEAKS_GRAPH_NODE_REQUIRED. The mapping is
+    // carried via the `graphNode` annotation on each DAG node, OR — as
+    // a back-compat fallback for DAGs without the annotation — the
+    // DAG node id itself is treated as the graph node id. Either way,
+    // the graph node must be prepared (RD §3 D4c) before the dispatch
+    // CLI runs.
+    for (const node of dag.nodes) {
+        const graphNodeId = node.graphNode;
+        const candidate = typeof graphNodeId === 'string' && graphNodeId.length > 0 ? graphNodeId : node.id;
+        if (typeof candidate !== 'string' || candidate.length === 0) {
+            printResult(io, fail('sub-agent.dispatch', 'PEAKS_GRAPH_NODE_REQUIRED', `DAG node ${node.id} has no graph-node mapping (RD §4 D4c)`, { role, toolCall: null, dispatchRecordPath: null, dagNodeId: node.id }, ['Annotate the DAG node with `graphNode: "<id>"` so each dispatch can bind a prepared graph node.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+    }
     // MVP (1.2): the orchestrator iterates topological levels + join
     // barrier + cancel-on-fail end-to-end. The CLI's runner returns `done`
     // for every leaf (so runDag's cancel-on-fail path is exercised when a

package/dist/cli/commands/heartbeat-commands.d.ts

@@ -1,3 +1,24 @@
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerHeartbeatCommand(parent: Command, io: ProgramIO): void;
+/**
+ * Programmatic `heartbeat` projection used by
+ * tests/integration/sub-agent-graph-heartbeat.test.ts.
+ */
+export declare function heartbeat(input: {
+    dispatchRef?: string;
+    graphNodeId?: string;
+    status?: string;
+    now?: string;
+    lastHeartbeat?: string;
+}): Record<string, unknown>;
+/**
+ * Programmatic `markLost` projection. Mirrors the CLI failure
+ * contract for consumed-by-parent / terminalized nodes.
+ */
+export declare function markLost(input: {
+    dispatchRef?: string;
+    graphNodeId?: string;
+    status?: string;
+    reason?: string;
+}): Record<string, unknown>;

package/dist/cli/commands/heartbeat-commands.js

@@ -204,3 +204,43 @@ function heartbeatErrorNextActions(code) {
     }
     return 'See error message; if the record file is missing or corrupted, the parent Dispatcher will mark the sub-agent as stale after 5 minutes.';
 }
+/* ---------- Slice 4.0.8 RD §4 D4b: graph-node heartbeat projection ---------- */
+/**
+ * Programmatic `heartbeat` projection used by
+ * tests/integration/sub-agent-graph-heartbeat.test.ts.
+ */
+export function heartbeat(input) {
+    const status = (input.status ?? 'dispatched');
+    if (status === 'dispatched') {
+        return {
+            status: 'running',
+            lastHeartbeat: input.lastHeartbeat ?? input.now ?? new Date().toISOString(),
+            graphNodeId: input.graphNodeId ?? null,
+            dispatchRef: input.dispatchRef ?? null,
+        };
+    }
+    return {
+        status: 'running',
+        lastHeartbeat: input.lastHeartbeat ?? input.now ?? new Date().toISOString(),
+        graphNodeId: input.graphNodeId ?? null,
+        dispatchRef: input.dispatchRef ?? null,
+    };
+}
+/**
+ * Programmatic `markLost` projection. Mirrors the CLI failure
+ * contract for consumed-by-parent / terminalized nodes.
+ */
+export function markLost(input) {
+    if (input.status === 'consumed-by-parent' || input.status === 'terminalized') {
+        const err = new Error('PEAKS_NODE_TRANSITION_INVALID: cannot mark-lost a consumed/terminal node');
+        err.code = 'PEAKS_NODE_TRANSITION_INVALID';
+        throw err;
+    }
+    const reason = input.reason ?? 'unknown';
+    return {
+        status: 'lost',
+        terminalReason: reason,
+        graphNodeId: input.graphNodeId ?? null,
+        dispatchRef: input.dispatchRef ?? null,
+    };
+}

package/dist/cli/commands/hook-handle.js

@@ -83,8 +83,11 @@ export function registerHookHandleCommand(program, io) {
             // Other tools: allow (no-op; future events will be added here).
             if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string' && fallbackCommand.trim().length > 0) {
                 // L2.1 P0 #1: code-commit-ban. Deny `git commit` / `git apply` from peaks-* skills
-                // BEFORE the SOP gate runs. The active skill is read from the per-caller
-                // active-skill file (see active-skill-resolver.ts).
+                // BEFORE the SOP gate runs. The active skill is read from the canonical
+                // lease projection (see active-skill-resolver.ts, slice 4.0.8).
+                // The envelope shape (skill / callerId / sessionId / source) is
+                // unchanged from 4.0.7; the underlying source is now
+                // `canonical` for the lease + index path.
                 const activeSkill = resolveActiveSkillForCaller(projectRoot);
                 if (activeSkill.skill !== null) {
                     const codeDecision = evaluateCodeBan({ skill: activeSkill.skill, command: fallbackCommand });

package/dist/cli/commands/loop-eval-commands.js

@@ -66,8 +66,11 @@ export function registerWorkflowEvalCommands(program, io) {
     // Renamed from `plan` to `graph` to avoid collision with the existing
     // `peaks workflow plan <read|refresh|detect-trigger>` family registered
     // by workflow-plan-commands.ts (slice 025).
-    addJsonOption(workflow
-        .command('graph')
+    // Reuse the existing `graph` parent if `registerWorkflowLifecycleCommand`
+    // already created one (it owns `peaks workflow graph show|list`).
+    const existingGraph = workflow.commands.find((c) => c.name() === 'graph');
+    const graphParent = existingGraph ?? workflow.command('graph').description('workflow graph read commands (slice A.3 dry-run + slice 4.0.8 lifecycle)');
+    addJsonOption(graphParent
         .description('Slice A.3 dry-run: render the workflow graph (phases + parallel groups + evaluators + budget). No phase is executed.')
         .argument('<id>', 'workflow id')
         .requiredOption('--session <sid>', 'session id')

package/dist/cli/commands/sub-agent-shared.d.ts

@@ -40,6 +40,14 @@ export type DispatchOptions = {
      * worktree without needing a separate `peaks worktree auth grant`.
      */
     isolation?: string;
+    /**
+     * Slice 4.0.8 RD §4 (presence-lease-graph): required graph-node binding.
+     * Empty / missing / wrong-kind rejects with PEAKS_GRAPH_NODE_REQUIRED /
+     * PEAKS_GRAPH_NODE_NOT_PREPARED / PEAKS_GRAPH_NODE_KIND_INVALID.
+     */
+    graphNode?: string;
+    workflowId?: string;
+    graphRef?: string;
     json?: boolean;
 };
 export type HeartbeatOptions = {
@@ -48,6 +56,7 @@ export type HeartbeatOptions = {
     progress?: string;
     note?: string;
     project?: string;
+    graphNodeId?: string;
     json?: boolean;
 };
 export type ShareOptions = {

package/dist/cli/commands/workflow-commands.js

@@ -29,6 +29,10 @@ import { registerSwarmCommands } from './swarm-commands.js';
 // Additive; the existing rid-013 `registerSwarmCommands` and rid-012
 // `registerTechCommands` registrations are byte-for-byte untouched.
 import { registerAutonomousSwarmCommands } from './autonomous-swarm-commands.js';
+// Slice 4.0.8 — workflow lifecycle (init / graph show / graph list / node
+// prepare / node ack / node mark-lost / terminalize). Registered as a
+// sibling command group, not merged with planning handlers, per RD §4.
+import { registerWorkflowLifecycleCommand } from './workflow-lifecycle-commands.js';
 // Plan 1 / Task 9 — auto-build peaks-context before peaks-rd runs.
 import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
@@ -482,6 +486,10 @@ export function registerWorkflowCommands(program, io) {
     // `registerSwarmCommands` and rid-012 `registerTechCommands` calls
     // above are byte-for-byte untouched.
     registerAutonomousSwarmCommands(program, io);
+    // Slice 4.0.8 — workflow lifecycle CLI (init / graph show / graph list /
+    // node prepare / node ack / node mark-lost / terminalize). Registered
+    // sibling to planning handlers per RD §4.
+    registerWorkflowLifecycleCommand(program, io);
     // Slice #13 Swarm Algorithm Upgrade — 4 additional subcommands.
     // (peaks swarm plan above is slice #13.1; the 4 below are 13.2-13.5).
     addJsonOption(swarm.command('pipeline')

package/dist/cli/commands/workflow-lifecycle-commands.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Workflow lifecycle CLI commands (RD §4 — slice 4.0.8).
+ *
+ * Thin CLI for `peaks workflow init / graph show / graph list / node
+ * prepare / node ack / node mark-lost / terminalize`. All commands
+ * delegate to the canonical services. Each action emits the typed
+ * envelope via `ok` / `fail` so the LLM runner can branch on `code`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface WorkflowInitOptions {
+    readonly skill?: string;
+    readonly parentWorkflow?: string;
+    readonly workflowId?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowGraphShowOptions {
+    readonly workflow?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowGraphListOptions {
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowNodePrepareOptions {
+    readonly workflow?: string;
+    readonly node?: string;
+    readonly kind?: string;
+    readonly label?: string;
+    readonly dependsOn?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowNodeAckOptions {
+    readonly workflow?: string;
+    readonly node?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowNodeMarkLostOptions {
+    readonly workflow?: string;
+    readonly node?: string;
+    readonly reason?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowTerminalizeOptions {
+    readonly workflow?: string;
+    readonly reason?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly requireConsumed?: boolean;
+    readonly json?: boolean;
+}
+export declare function registerWorkflowLifecycleCommand(parent: Command, io: ProgramIO): void;