peaks-loop 4.1.3 → 4.1.4

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

@@ -5,84 +5,18 @@
  * 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 { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-import { resolveCallerId } from '../../services/session/resolve-caller-id.js';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
-import { initWorkflow, terminalizeWorkflow } from '../../services/workflow/workflow-presence-lifecycle.js';
-import { readGraph, emptyGraph } from '../../services/workflow/workflow-graph-store.js';
-import { WORKFLOW_ID_REGEX, TERMINAL_REASONS } from '../../services/workflow/workflow-graph-types.js';
-import { prepareNodeAction, transitionNode, transitionLease } from '../../services/workflow/workflow-node-lifecycle.js';
-function deriveCallerId() {
-    try {
-        return resolveCallerId({});
-    }
-    catch (err) {
-        throw fail('workflow.init', 'PEAKS_CALLER_NOT_RESOLVED', getErrorMessage(err), { callerId: null }, ['Resolve the IDE session identity before running workflow commands.']);
-    }
-}
-function deriveProjectRoot(options) {
-    return options.project ?? process.cwd();
-}
-/**
- * The literal that means "no session could be resolved". Kept as a named
- * constant because three call sites now have to ASK whether resolution
- * failed rather than consume the value as if it were an id.
- */
-export const UNKNOWN_SESSION_ID = 'unknown-sid';
-/**
- * Resolve the session id for every `workflow *` command.
- *
- * Tier order (matches the idiom every other command family in this CLI
- * already uses — see `job-commands.ts:85`, `container-commands.ts:138`):
  *
- *   1. `--session-id <sid>`             — explicit wins
- *   2. `PEAKS_SESSION_ID` env var       — scripted / sub-process callers
- *   3. `getCurrentSessionId(projectRoot)` — this caller's OWN binding
- *      (`callers/<callerId>.json`) falling back to the project-global
- *      `.peaks/_runtime/session.json`, the same resolver `peaks session
- *      info --active` and `peaks session checkpoint` use
- *   4. `unknown-sid`                    — nothing is bound
- *
- * Tier 3 was MISSING until 2026-09-15 (S6), and its absence is the whole
- * defect: `workflow init` resolved on tiers 1–2 only, so with no flag and no
- * env var it wrote the graph into `.peaks/_runtime/unknown-sid/graphs/`
- * regardless of what the binding file said. `peaks workflow node prepare`
- * then ran under the CORRECT session dir and reported `PEAKS_GRAPH_NOT_FOUND`
- * — the graph it was asking for had been written one bucket over. The bucket
- * accumulated artifacts from at least 4 distinct caller ids between 2026-09-01
- * and 2026-09-15, i.e. it had never worked for anyone.
- *
- * The same prior-art sweep (`.peaks/memory/archived/2026-06-26-unknown-sid-root-cause.md`)
- * converted six inline `?? 'unknown-sid'` sites to this 4-tier chain;
- * `workflow-lifecycle-commands.ts` was missed. This is that site.
- *
- * The project root passed to tier 3 goes through the same `findProjectRoot`
- * walk `session info` uses, so a command run from a SUBDIRECTORY of the
- * project resolves the project's binding instead of `cwd`'s (which has none).
+ * The verb implementations live beside this file, one module per verb group:
+ * `workflow-init-command.ts`, `workflow-graph-commands.ts`,
+ * `workflow-node-commands.ts`, `workflow-terminalize-command.ts`, with the
+ * option vocabulary and the caller / project / session derivation in
+ * `workflow-command-shared.ts`.
  */
-function deriveSessionId(options) {
-    if (typeof options.sessionId === 'string' && options.sessionId.length > 0)
-        return options.sessionId;
-    const fromEnv = process.env.PEAKS_SESSION_ID;
-    if (typeof fromEnv === 'string' && fromEnv.length > 0)
-        return fromEnv;
-    return (getCurrentSessionId(findProjectRoot(options.project ?? process.cwd()) ?? options.project ?? process.cwd()) ?? UNKNOWN_SESSION_ID);
-}
-/**
- * Tier 3 resolving to `unknown-sid` means NO session is bound at all. A
- * `workflow` subcommand that WRITES must fail loudly on that rather than
- * create a bucket named after a failure — `graph list` already does (see its
- * `PEAKS_SESSION_NOT_BOUND` guard below); `init` did not.
- */
-function buildSessionNotBoundEnvelope(sessionId, projectRoot) {
-    return fail('workflow.init', 'PEAKS_SESSION_NOT_BOUND', `No peaks session is bound for '${projectRoot}' (derived session id '${sessionId}'): --session-id, PEAKS_SESSION_ID and the project binding are all absent.`, { workflowId: null }, [
-        'Run `peaks workspace init --project <p>` to bind a session, then re-run.',
-        'Or pass `--session-id <sid>` explicitly.'
-    ]);
-}
+import { registerWorkflowGraphCommands } from './workflow-graph-commands.js';
+import { registerWorkflowInitCommand } from './workflow-init-command.js';
+import { registerWorkflowNodeCommands } from './workflow-node-commands.js';
+import { registerWorkflowTerminalizeCommand } from './workflow-terminalize-command.js';
+export { UNKNOWN_SESSION_ID } from './workflow-command-shared.js';
 export function registerWorkflowLifecycleCommand(parent, io) {
     // Reuse the existing `workflow` parent (created by `registerWorkflowCommands`)
     // to avoid Commander.js's "cannot add command 'workflow' as already have
@@ -90,276 +24,8 @@ export function registerWorkflowLifecycleCommand(parent, io) {
     const existingWorkflow = parent.commands.find((c) => c.name() === 'workflow');
     const workflow = existingWorkflow ??
         parent.command('workflow').description('workflow lifecycle commands (RD §4)');
-    addJsonOption(workflow
-        .command('init')
-        .description('Initialize a workflow graph + canonical lease + caller index.')
-        .requiredOption('--skill <name>', 'the skill owning this workflow (e.g. peaks-code)')
-        .option('--workflow-id <id>', 'optional explicit workflowId (auto-generated if omitted)')
-        .option('--parent-workflow <id>', 'parent workflowId for nested runs')
-        .option('--session-id <sid>', 'override session id (default: derived from session.json / env)')
-        .option('--project <path>', 'target project root (defaults to cwd)')).action(async (options) => {
-        const asJson = options.json === true;
-        try {
-            const callerId = deriveCallerId();
-            const projectRoot = deriveProjectRoot(options);
-            const sessionId = deriveSessionId(options);
-            if (sessionId === UNKNOWN_SESSION_ID) {
-                printResult(io, buildSessionNotBoundEnvelope(sessionId, projectRoot), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            const workflowId = options.workflowId ?? `wf-${Date.now().toString(36)}`;
-            if (!WORKFLOW_ID_REGEX.test(workflowId)) {
-                throw new Error(`workflowId shape invalid: ${workflowId}`);
-            }
-            const result = await initWorkflow({
-                projectRoot,
-                sessionId,
-                callerId,
-                skill: options.skill ?? 'peaks-code',
-                workflowId,
-                ...(options.parentWorkflow ? { parentWorkflowId: options.parentWorkflow } : {})
-            });
-            printResult(io, ok('workflow.init', {
-                envelopeVersion: '4.0.8',
-                workflowId: result.workflowId,
-                graphRef: result.graphRef,
-                events: result.events
-            }), asJson);
-        }
-        catch (err) {
-            const code = err.code ?? 'PEAKS_GRAPH_WRITE_FAILED';
-            printResult(io, fail('workflow.init', code, getErrorMessage(err), { workflowId: null }, []), asJson);
-            process.exitCode = 1;
-        }
-    });
-    // Note: `.command('graph show')` and `.command('graph list')` each
-    // implicitly create a NEW `graph` parent under `workflow` in
-    // Commander v12 (no auto-reuse), so calling them in sequence throws
-    // "cannot add command 'graph' as already have command 'graph'" at
-    // startup. Reuse the first created `graph` parent for the second
-    // registration.
-    const graphCmd = workflow.command('graph').description('workflow graph read commands');
-    graphCmd
-        .command('show')
-        .description('Read a workflow graph.')
-        .option('--workflow <id>', 'workflow id')
-        .option('--session-id <sid>', 'session id')
-        .option('--project <path>', 'project root')
-        .option('--json', 'json output')
-        .action((options) => {
-        const asJson = options.json === true;
-        try {
-            const sessionId = deriveSessionId(options);
-            const projectRoot = deriveProjectRoot(options);
-            const workflowId = options.workflow ?? '';
-            if (!workflowId || !WORKFLOW_ID_REGEX.test(workflowId)) {
-                throw new Error('workflowId is required');
-            }
-            const graph = readGraph({
-                projectRoot,
-                sessionId,
-                graphRef: `graphs/${workflowId}.json`,
-                workflowId
-            });
-            printResult(io, ok('workflow.graph.show', { envelopeVersion: '4.0.8', graph }), asJson);
-        }
-        catch (err) {
-            const code = err.code ?? 'PEAKS_GRAPH_NOT_FOUND';
-            printResult(io, fail('workflow.graph.show', code, getErrorMessage(err), { graph: null }, []), asJson);
-            process.exitCode = 1;
-        }
-    });
-    graphCmd
-        .command('list')
-        .description('List workflow graphs (metadata only).')
-        .option('--session-id <sid>', 'session id')
-        .option('--project <path>', 'project root')
-        .option('--json', 'json output')
-        .action((options) => {
-        const asJson = options.json === true;
-        try {
-            const sessionId = deriveSessionId(options);
-            if (sessionId === UNKNOWN_SESSION_ID) {
-                throw new Error('PEAKS_SESSION_NOT_BOUND: no session id');
-            }
-            const result = { envelopeVersion: '4.0.8', sessionId, graphs: [] };
-            printResult(io, ok('workflow.graph.list', result), asJson);
-        }
-        catch (err) {
-            const code = err.code ?? 'PEAKS_SESSION_NOT_BOUND';
-            printResult(io, fail('workflow.graph.list', code, getErrorMessage(err), { graphs: [] }, []), asJson);
-            process.exitCode = 1;
-        }
-    });
-    // Reuse one `node` parent for prepare / ack / mark-lost (Commander v12
-    // creates a NEW parent per `.command('node X')` call, so we must
-    // explicitly create the parent first to avoid duplicate-registration).
-    const nodeCmd = workflow.command('node').description('workflow node commands');
-    nodeCmd
-        .command('prepare')
-        .description('Prepare a node in a workflow graph.')
-        .option('--workflow <id>', 'workflow id')
-        .option('--node <id>', 'node id')
-        .option('--kind <k>', 'node kind: step | dispatch | terminal')
-        .option('--label <text>', 'human-readable label')
-        .option('--depends-on <ids>', 'comma-separated list of dependency node ids')
-        .option('--session-id <sid>', 'session id')
-        .option('--project <path>', 'project root')
-        .option('--json', 'json output')
-        .action((options) => {
-        const asJson = options.json === true;
-        try {
-            const sessionId = deriveSessionId(options);
-            const projectRoot = deriveProjectRoot(options);
-            const workflowId = options.workflow ?? '';
-            if (!workflowId || !WORKFLOW_ID_REGEX.test(workflowId)) {
-                throw new Error('workflowId is required');
-            }
-            const graphRef = `graphs/${workflowId}.json`;
-            const existing = readGraph({ projectRoot, sessionId, graphRef, workflowId });
-            const nodeId = options.node ?? `node-${Date.now().toString(36)}`;
-            const kind = (options.kind ?? 'step');
-            const dependsOn = (options.dependsOn ?? '')
-                .split(',')
-                .map((s) => s.trim())
-                .filter((s) => s.length > 0);
-            const updated = prepareNodeAction({
-                workflowId,
-                nodeId,
-                graphNode: existing.nodes.find((n) => n.id === nodeId) ?? {
-                    id: nodeId,
-                    kind,
-                    label: options.label ?? nodeId,
-                    status: 'prepared',
-                    dependsOn
-                },
-                dependsOn,
-                status: 'prepared'
-            });
-            // Persist via the graph store
-            // (not inlined so the CLI delegates everything to the service).
-            printResult(io, ok('workflow.node.prepare', { envelopeVersion: '4.0.8', graph: updated }), asJson);
-        }
-        catch (err) {
-            const code = err.code ?? 'PEAKS_GRAPH_CORRUPTED';
-            printResult(io, fail('workflow.node.prepare', code, getErrorMessage(err), { graph: null }, []), asJson);
-            process.exitCode = 1;
-        }
-    });
-    nodeCmd
-        .command('ack')
-        .description('Acknowledge a node that has an envelope-received status.')
-        .option('--workflow <id>', 'workflow id')
-        .option('--node <id>', 'node id')
-        .option('--session-id <sid>', 'session id')
-        .option('--project <path>', 'project root')
-        .option('--json', 'json output')
-        .action((options) => {
-        const asJson = options.json === true;
-        try {
-            const sessionId = deriveSessionId(options);
-            const projectRoot = deriveProjectRoot(options);
-            const workflowId = options.workflow ?? '';
-            if (!workflowId)
-                throw new Error('workflowId is required');
-            const graphRef = `graphs/${workflowId}.json`;
-            const graph = readGraph({ projectRoot, sessionId, graphRef, workflowId });
-            const nodeId = options.node ?? '';
-            const node = graph.nodes.find((n) => n.id === nodeId);
-            if (!node)
-                throw new Error(`node ${nodeId} not found`);
-            if (node.status !== 'envelope-received') {
-                throw new Error('PEAKS_ENVELOPE_NOT_RECEIVED: node is not envelope-received');
-            }
-            const updated = transitionNode(node.status, 'consumed-by-parent', { graphNode: node });
-            printResult(io, ok('workflow.node.ack', { envelopeVersion: '4.0.8', node: updated }), asJson);
-        }
-        catch (err) {
-            const code = err.code ?? 'PEAKS_ENVELOPE_NOT_RECEIVED';
-            printResult(io, fail('workflow.node.ack', code, getErrorMessage(err), { node: null }, []), asJson);
-            process.exitCode = 1;
-        }
-    });
-    nodeCmd
-        .command('mark-lost')
-        .description('Mark a node as lost.')
-        .option('--workflow <id>', 'workflow id')
-        .option('--node <id>', 'node id')
-        .option('--reason <reason>', `terminal reason: ${TERMINAL_REASONS.join(' | ')}`)
-        .option('--session-id <sid>', 'session id')
-        .option('--project <path>', 'project root')
-        .option('--json', 'json output')
-        .action((options) => {
-        const asJson = options.json === true;
-        try {
-            const workflowId = options.workflow ?? '';
-            if (!workflowId)
-                throw new Error('workflowId is required');
-            const nodeId = options.node ?? '';
-            if (!nodeId)
-                throw new Error('nodeId is required');
-            const reason = options.reason ?? 'unknown';
-            if (!TERMINAL_REASONS.includes(reason)) {
-                throw new Error(`PEAKS_TERMINAL_REASON_INVALID: ${reason}`);
-            }
-            printResult(io, ok('workflow.node.mark-lost', {
-                envelopeVersion: '4.0.8',
-                workflowId,
-                nodeId,
-                status: 'lost',
-                terminalReason: reason
-            }), asJson);
-        }
-        catch (err) {
-            const code = err.code ?? 'PEAKS_TERMINAL_REASON_INVALID';
-            printResult(io, fail('workflow.node.mark-lost', code, getErrorMessage(err), { node: null }, []), asJson);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(workflow
-        .command('terminalize')
-        .description('Atomically terminalize a workflow (lease + graph + index + observability event).')
-        .requiredOption('--workflow <id>', 'workflow id')
-        .requiredOption('--reason <reason>', `terminal reason: ${TERMINAL_REASONS.join(' | ')}`)
-        .option('--session-id <sid>', 'session id')
-        .option('--project <path>', 'project root')
-        .option('--require-consumed', 'fail if there are unconsumed envelopes')).action(async (options) => {
-        const asJson = options.json === true;
-        try {
-            const callerId = deriveCallerId();
-            const sessionId = deriveSessionId(options);
-            const projectRoot = deriveProjectRoot(options);
-            const workflowId = options.workflow ?? '';
-            if (!workflowId)
-                throw new Error('workflowId is required');
-            if (!TERMINAL_REASONS.includes(options.reason)) {
-                throw new Error(`PEAKS_TERMINAL_REASON_INVALID: ${options.reason}`);
-            }
-            const result = await terminalizeWorkflow({
-                projectRoot,
-                sessionId,
-                callerId,
-                workflowId,
-                graphRef: `graphs/${workflowId}.json`,
-                reason: options.reason,
-                ...(options.requireConsumed ? { requireConsumed: true } : {})
-            });
-            printResult(io, ok('workflow.terminalize', {
-                envelopeVersion: '4.0.8',
-                lease: result.lease,
-                graph: result.graph,
-                events: result.events,
-                indexCleared: result.indexCleared
-            }), asJson);
-        }
-        catch (err) {
-            const code = err.code ?? 'PEAKS_TERMINALIZE_ATOMICITY_FAILED';
-            printResult(io, fail('workflow.terminalize', code, getErrorMessage(err), { lease: null }, []), asJson);
-            process.exitCode = 1;
-        }
-    });
-    // Suppress unused-import warnings for symbols reserved for future slices.
-    void transitionLease;
-    void emptyGraph;
+    registerWorkflowInitCommand(workflow, io);
+    registerWorkflowGraphCommands(workflow, io);
+    registerWorkflowNodeCommands(workflow, io);
+    registerWorkflowTerminalizeCommand(workflow, io);
 }

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

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorkflowNodeCommands(workflow: Command, io: ProgramIO): void;

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

@@ -0,0 +1,154 @@
+// src/cli/commands/workflow-node-commands.ts
+//
+// `peaks workflow node prepare` / `node ack` / `node mark-lost` — the workflow
+// node lifecycle verbs. Split out of `workflow-lifecycle-commands.ts`; every
+// verb name, option and envelope shape is unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { readGraph } from '../../services/workflow/workflow-graph-store.js';
+import { prepareNodeAction, transitionNode } from '../../services/workflow/workflow-node-lifecycle.js';
+import { TERMINAL_REASONS, WORKFLOW_ID_REGEX } from '../../services/workflow/workflow-graph-types.js';
+import { deriveProjectRoot, deriveSessionId, GENERATED_ID_RADIX } from './workflow-command-shared.js';
+/** The comma-separated `--depends-on` list, trimmed, with empties removed. */
+function parseDependsOn(raw) {
+    return (raw ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** The node this `prepare` acts on: the one already in the graph, or the new default. */
+function prepareGraphNode(existing, request) {
+    return (existing.nodes.find((n) => n.id === request.nodeId) ?? {
+        id: request.nodeId,
+        kind: request.kind,
+        label: request.label ?? request.nodeId,
+        status: 'prepared',
+        dependsOn: request.dependsOn
+    });
+}
+function runWorkflowNodePrepare(io, options) {
+    const asJson = options.json === true;
+    try {
+        const sessionId = deriveSessionId(options);
+        const projectRoot = deriveProjectRoot(options);
+        const workflowId = options.workflow ?? '';
+        if (!workflowId || !WORKFLOW_ID_REGEX.test(workflowId)) {
+            throw new Error('workflowId is required');
+        }
+        const graphRef = `graphs/${workflowId}.json`;
+        const existing = readGraph({ projectRoot, sessionId, graphRef, workflowId });
+        const nodeId = options.node ?? `node-${Date.now().toString(GENERATED_ID_RADIX)}`;
+        const kind = (options.kind ?? 'step');
+        const dependsOn = parseDependsOn(options.dependsOn);
+        const updated = prepareNodeAction({
+            workflowId,
+            nodeId,
+            graphNode: prepareGraphNode(existing, {
+                nodeId,
+                kind,
+                label: options.label,
+                dependsOn
+            }),
+            dependsOn,
+            status: 'prepared'
+        });
+        // Persist via the graph store
+        // (not inlined so the CLI delegates everything to the service).
+        printResult(io, ok('workflow.node.prepare', { envelopeVersion: '4.0.8', graph: updated }), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_GRAPH_CORRUPTED';
+        printResult(io, fail('workflow.node.prepare', code, getErrorMessage(err), { graph: null }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+function runWorkflowNodeAck(io, options) {
+    const asJson = options.json === true;
+    try {
+        const sessionId = deriveSessionId(options);
+        const projectRoot = deriveProjectRoot(options);
+        const workflowId = options.workflow ?? '';
+        if (!workflowId)
+            throw new Error('workflowId is required');
+        const graphRef = `graphs/${workflowId}.json`;
+        const graph = readGraph({ projectRoot, sessionId, graphRef, workflowId });
+        const nodeId = options.node ?? '';
+        const node = graph.nodes.find((n) => n.id === nodeId);
+        if (!node)
+            throw new Error(`node ${nodeId} not found`);
+        if (node.status !== 'envelope-received') {
+            throw new Error('PEAKS_ENVELOPE_NOT_RECEIVED: node is not envelope-received');
+        }
+        const updated = transitionNode(node.status, 'consumed-by-parent', { graphNode: node });
+        printResult(io, ok('workflow.node.ack', { envelopeVersion: '4.0.8', node: updated }), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_ENVELOPE_NOT_RECEIVED';
+        printResult(io, fail('workflow.node.ack', code, getErrorMessage(err), { node: null }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+function runWorkflowNodeMarkLost(io, options) {
+    const asJson = options.json === true;
+    try {
+        const workflowId = options.workflow ?? '';
+        if (!workflowId)
+            throw new Error('workflowId is required');
+        const nodeId = options.node ?? '';
+        if (!nodeId)
+            throw new Error('nodeId is required');
+        const reason = options.reason ?? 'unknown';
+        if (!TERMINAL_REASONS.includes(reason)) {
+            throw new Error(`PEAKS_TERMINAL_REASON_INVALID: ${reason}`);
+        }
+        printResult(io, ok('workflow.node.mark-lost', {
+            envelopeVersion: '4.0.8',
+            workflowId,
+            nodeId,
+            status: 'lost',
+            terminalReason: reason
+        }), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_TERMINAL_REASON_INVALID';
+        printResult(io, fail('workflow.node.mark-lost', code, getErrorMessage(err), { node: null }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowNodeCommands(workflow, io) {
+    // Reuse one `node` parent for prepare / ack / mark-lost (Commander v12
+    // creates a NEW parent per `.command('node X')` call, so we must
+    // explicitly create the parent first to avoid duplicate-registration).
+    const nodeCmd = workflow.command('node').description('workflow node commands');
+    nodeCmd
+        .command('prepare')
+        .description('Prepare a node in a workflow graph.')
+        .option('--workflow <id>', 'workflow id')
+        .option('--node <id>', 'node id')
+        .option('--kind <k>', 'node kind: step | dispatch | terminal')
+        .option('--label <text>', 'human-readable label')
+        .option('--depends-on <ids>', 'comma-separated list of dependency node ids')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')
+        .option('--json', 'json output')
+        .action((options) => runWorkflowNodePrepare(io, options));
+    nodeCmd
+        .command('ack')
+        .description('Acknowledge a node that has an envelope-received status.')
+        .option('--workflow <id>', 'workflow id')
+        .option('--node <id>', 'node id')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')
+        .option('--json', 'json output')
+        .action((options) => runWorkflowNodeAck(io, options));
+    nodeCmd
+        .command('mark-lost')
+        .description('Mark a node as lost.')
+        .option('--workflow <id>', 'workflow id')
+        .option('--node <id>', 'node id')
+        .option('--reason <reason>', `terminal reason: ${TERMINAL_REASONS.join(' | ')}`)
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')
+        .option('--json', 'json output')
+        .action((options) => runWorkflowNodeMarkLost(io, options));
+}

package/dist/cli/commands/workflow-terminalize-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorkflowTerminalizeCommand(workflow: Command, io: ProgramIO): void;

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

@@ -0,0 +1,56 @@
+// src/cli/commands/workflow-terminalize-command.ts
+//
+// `peaks workflow terminalize` — atomically terminalize a workflow (lease +
+// graph + index + observability event). Split out of
+// `workflow-lifecycle-commands.ts`; the verb name, its options, the
+// `--require-consumed` passthrough and the envelope shape are unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { terminalizeWorkflow } from '../../services/workflow/workflow-presence-lifecycle.js';
+import { TERMINAL_REASONS } from '../../services/workflow/workflow-graph-types.js';
+import { deriveCallerId, deriveProjectRoot, deriveSessionId } from './workflow-command-shared.js';
+async function runWorkflowTerminalize(io, options) {
+    const asJson = options.json === true;
+    try {
+        const callerId = deriveCallerId();
+        const sessionId = deriveSessionId(options);
+        const projectRoot = deriveProjectRoot(options);
+        const workflowId = options.workflow ?? '';
+        if (!workflowId)
+            throw new Error('workflowId is required');
+        if (!TERMINAL_REASONS.includes(options.reason)) {
+            throw new Error(`PEAKS_TERMINAL_REASON_INVALID: ${options.reason}`);
+        }
+        const result = await terminalizeWorkflow({
+            projectRoot,
+            sessionId,
+            callerId,
+            workflowId,
+            graphRef: `graphs/${workflowId}.json`,
+            reason: options.reason,
+            ...(options.requireConsumed ? { requireConsumed: true } : {})
+        });
+        printResult(io, ok('workflow.terminalize', {
+            envelopeVersion: '4.0.8',
+            lease: result.lease,
+            graph: result.graph,
+            events: result.events,
+            indexCleared: result.indexCleared
+        }), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_TERMINALIZE_ATOMICITY_FAILED';
+        printResult(io, fail('workflow.terminalize', code, getErrorMessage(err), { lease: null }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowTerminalizeCommand(workflow, io) {
+    addJsonOption(workflow
+        .command('terminalize')
+        .description('Atomically terminalize a workflow (lease + graph + index + observability event).')
+        .requiredOption('--workflow <id>', 'workflow id')
+        .requiredOption('--reason <reason>', `terminal reason: ${TERMINAL_REASONS.join(' | ')}`)
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')
+        .option('--require-consumed', 'fail if there are unconsumed envelopes')).action((options) => runWorkflowTerminalize(io, options));
+}

package/dist/services/code/auto-compact-artifacts.d.ts

@@ -0,0 +1,54 @@
+import { type HarnessWindowSyncResult } from '../context/harness-window-config.js';
+import type { ConvergencePlan } from '../context/auto-compact-types.js';
+/**
+ * What the caller is told to do next. The harness-window notice rides along because
+ * the run also rewrites the harness's own settings, so it says so too: the user
+ * accepted that write on the condition 要告知, and a write only one of the two
+ * syncing commands reports is not a notice.
+ */
+export declare function compactNextActions(isRedLine: boolean, harnessWindow: HarnessWindowSyncResult | null): readonly string[];
+/**
+ * Append a one-row convergence decision to the LLM-readable log.
+ * The LLM reads this on the post-compact turn to pick up exactly
+ * where it left off (vs. blindly trusting the IDE's compressed
+ * transcript).
+ */
+export declare function appendAutoDecisionLog(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly plan: ConvergencePlan;
+}): void;
+/**
+ * main-session compact intent so the main-session LLM picks it up on
+ * its next turn and fires `/compact` in-band. Without this file the
+ * orchestrator's "main-session compact" request is invisible to the
+ * main Claude Code window (defeats the whole point of auto-compact
+ * for the main context).
+ *
+ * The file is gitignored under `.peaks/_runtime/<sessionId>/txt/` and
+ * is one-shot: the LLM should `mv` it to `.consumed` after firing
+ * `/compact`. A re-run will overwrite.
+ *
+ * write survives, but nothing consumes the file, and its `nextAction` asks
+ * for a `/compact` the model cannot invoke (the Skill tool exposes only
+ * `/init` and `/security-review`; hooks can observe or veto, never initiate).
+ * Retained deliberately for the sibling A2 slice, which owns harness-side
+ * state re-injection. Not a capability peaks-loop has today.
+ */
+export declare function writeMainSessionCompactIntent(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly ratio: number;
+    readonly redLine: boolean;
+    readonly now: Date;
+}): void;
+/**
+ * Write a pre-compact checkpoint. The shape mirrors `peaks session
+ * checkpoint` so D7's post-compact-detect picks it up unchanged.
+ */
+export declare function writePreCompactCheckpoint(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly now: Date;
+    readonly redLine?: boolean;
+}): string;