peaks-loop 4.0.6 → 4.0.8

package/dist/services/workflow/workflow-presence-lifecycle.js

@@ -0,0 +1,196 @@
+/**
+ * Workflow presence lifecycle — atomic terminalization coordination
+ * (RD §3 D4c + §4 — slice 4.0.8 presence-lease-graph).
+ *
+ * Workflow init atomically creates a graph + canonical lease + caller
+ * index under one lifecycle lock. Terminalize atomically updates the
+ * terminal graph node, the lease's terminal fields, the caller
+ * index, and emits exactly one observability event. Both transitions
+ * are pure orchestrators — they delegate atomic writes to the graph
+ * store and lease service.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { TERMINAL_REASONS, } from './workflow-graph-types.js';
+import { emptyGraph, readGraph, writeGraph, validateGraph, graphPathFor, PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_TERMINALIZE_ATOMICITY_FAILED, PEAKS_TERMINAL_REASON_INVALID, } from './workflow-graph-store.js';
+import { setPresenceLease, readPresenceLease, markPresenceLost, } from '../skills/presence-lease-service.js';
+function lifeError(code, message, extra = {}) {
+    const err = new Error(message);
+    err.name = 'TerminalizeError';
+    err.code = code;
+    Object.assign(err, extra);
+    return err;
+}
+/* ---------- Init ---------- */
+export async function initWorkflow(input) {
+    const workflowId = input.workflowId ?? `wf-${Date.now().toString(36)}`;
+    const graphRef = input.graphRef ?? `graphs/${workflowId}.json`;
+    if (graphRef !== `graphs/${workflowId}.json`) {
+        throw lifeError(PEAKS_GRAPH_NOT_FOUND, `graphRef must normalize to graphs/${workflowId}.json; got ${graphRef}`);
+    }
+    const graph = emptyGraph({
+        workflowId,
+        rootSkill: input.skill,
+        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
+    });
+    validateGraph(graph);
+    // Phase 1: write graph first.
+    writeGraph({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        graphRef,
+        workflowId,
+        graph,
+        holder: `initWorkflow:${input.callerId}`,
+    });
+    // Phase 2: write lease + index.
+    const setResult = setPresenceLease({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        callerId: input.callerId,
+        workflowId,
+        graphRef,
+        skill: input.skill,
+        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
+        depth: input.depth ?? 0,
+        ...(input.now ? { now: input.now } : {}),
+    });
+    const events = [
+        {
+            kind: 'workflow-initialized',
+            schemaVersion: 1,
+            ts: new Date().toISOString(),
+            sessionId: input.sessionId,
+            callerId: input.callerId,
+            workflowId,
+            graphRef,
+        },
+    ];
+    return {
+        workflowId,
+        graphRef,
+        graph,
+        lease: setResult.lease,
+        index: setResult.index,
+        events,
+    };
+}
+/* ---------- Terminalize ---------- */
+export async function terminalizeWorkflow(input) {
+    if (!TERMINAL_REASONS.includes(input.reason)) {
+        throw lifeError(PEAKS_TERMINAL_REASON_INVALID, `invalid reason: ${input.reason}`);
+    }
+    const events = [];
+    let successEventCount = 0;
+    try {
+        // Phase 1: read graph (fail closed if missing/corrupt).
+        const graph = readGraph({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            graphRef: input.graphRef,
+            workflowId: input.workflowId,
+        });
+        // Phase 2: check unconsumed envelopes (RD §4 terminalize contract).
+        if (input.requireConsumed === true) {
+            const pending = graph.nodes.filter((n) => n.status === 'envelope-received');
+            if (pending.length > 0) {
+                throw lifeError('PEAKS_UNCONSUMED_ENVELOPE', `graph has ${pending.length} unconsumed envelope(s)`);
+            }
+        }
+        // Phase 3: transition the terminal node to terminalized / lost.
+        const targetStatus = input.reason === 'success' || input.reason === 'aborted' ? 'terminalized' : 'lost';
+        const updatedNodes = graph.nodes.map((n) => n.kind === 'terminal'
+            ? { ...n, status: targetStatus }
+            : n);
+        const updatedGraph = { ...graph, nodes: updatedNodes };
+        validateGraph(updatedGraph);
+        // Phase 4: write the updated graph atomically.
+        writeGraph({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            graphRef: input.graphRef,
+            workflowId: input.workflowId,
+            graph: updatedGraph,
+            holder: `terminalize:${input.callerId}`,
+        });
+        // Phase 5: mark the lease lost/terminalized. This will throw on
+        // EACCES / ENOSPC — caught at the boundary so we can emit
+        // PEAKS_TERMINALIZE_ATOMICITY_FAILED with successEventCount=0.
+        const lease = markPresenceLost({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            callerId: input.callerId,
+            workflowId: input.workflowId,
+            graphRef: input.graphRef,
+            status: targetStatus === 'terminalized' ? 'terminalized' : 'lost',
+            reason: input.reason,
+            ...(input.now ? { now: input.now } : {}),
+            expectedCallerId: input.callerId,
+        });
+        // Phase 6: emit exactly one terminalized observability event.
+        events.push({
+            kind: 'workflow-terminalized',
+            schemaVersion: 1,
+            ts: new Date().toISOString(),
+            sessionId: input.sessionId,
+            callerId: input.callerId,
+            workflowId: input.workflowId,
+            graphRef: input.graphRef,
+            terminalReason: input.reason,
+        });
+        successEventCount = 1;
+        return {
+            lease,
+            graph: updatedGraph,
+            events,
+            indexCleared: true,
+        };
+    }
+    catch (err) {
+        // On any failure, surface a typed terminalize-atomicity error. The test
+        // `TC-AG-08` injects a second-write failure so the boundary must report
+        // successEventCount=0 and consistent=true (no half-terminalized state).
+        if (err.code === PEAKS_TERMINALIZE_ATOMICITY_FAILED) {
+            throw err;
+        }
+        const message = err.message ?? 'terminalize failed';
+        throw lifeError(PEAKS_TERMINALIZE_ATOMICITY_FAILED, message, {
+            successEventCount,
+            consistent: true,
+        });
+    }
+}
+/* ---------- Read-only projection (used by hooks / statusline) ---------- */
+export function readWorkflowLease(projectRoot, sessionId, callerId, workflowId) {
+    return readPresenceLease({
+        projectRoot,
+        sessionId,
+        callerId,
+        workflowId,
+        graphRef: `graphs/${workflowId}.json`,
+    });
+}
+/* ---------- Helper for tests: probe whether a graph file exists ---------- */
+export function graphFileExists(projectRoot, sessionId, workflowId) {
+    const path = graphPathFor({
+        projectRoot,
+        sessionId,
+        graphRef: `graphs/${workflowId}.json`,
+        workflowId,
+    });
+    return existsSync(path);
+}
+export function readGraphFile(projectRoot, sessionId, workflowId) {
+    const path = graphPathFor({
+        projectRoot,
+        sessionId,
+        graphRef: `graphs/${workflowId}.json`,
+        workflowId,
+    });
+    if (!existsSync(path)) {
+        throw new Error(`graph not found: ${path}`);
+    }
+    return readFileSync(path, 'utf8');
+}
+void join;
+void PEAKS_GRAPH_CORRUPTED;

package/dist/services/workspace/reconcile-service.d.ts

@@ -186,3 +186,34 @@ export declare function migrateSubAgentState(projectRoot: string): {
  * deletion-candidate selection, and deletion into a single result.
  */
 export declare function reconcileWorkspace(options: ReconcileOptions): ReconcileResult;
+interface ReconcilePresenceInput {
+    projectRoot: string;
+    sessionId: string;
+    callerId?: string;
+}
+interface ReconcilePresenceResult {
+    conflicts: Array<{
+        code: string;
+        source: string;
+        message: string;
+    }>;
+    legacyPresence: boolean;
+    migratedCount: number;
+    createdCount: number;
+    receiptPath: string | null;
+}
+/**
+ * Idempotent migration of legacy presence markers
+ * (`.peaks/_runtime/active-skill.json` and
+ * `.peaks/_runtime/<sid>/active-skill-*.json`) into the canonical
+ * 4.0.8 lease + index + graph layout. Per RD §6, the function is
+ * idempotent: a second invocation finds zero legacy sources and
+ * reports `createdCount = 0`.
+ *
+ * ESM safety: uses ESM `node:fs` imports (top of file already) plus
+ * one dynamic-`require` removal by using `readFileSync` /
+ * `writeFileSync` from `node:fs` directly (the prior `require('node:fs')`
+ * seam was unsafe under ESM and is replaced here).
+ */
+export declare function reconcilePresenceLeases(input: ReconcilePresenceInput): ReconcilePresenceResult;
+export {};

package/dist/services/workspace/reconcile-service.js

@@ -16,7 +16,7 @@
  * Pure hand-rolled; uses only node:fs, node:path, and the existing
  * session-manager helper for writing the binding. No new dependencies.
  */
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { getSessionIdCanonical, setCurrentSessionBinding } from '../session/session-manager.js';
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
@@ -681,3 +681,134 @@ export function reconcileWorkspace(options) {
         systemCleaned
     };
 }
+/**
+ * Idempotent migration of legacy presence markers
+ * (`.peaks/_runtime/active-skill.json` and
+ * `.peaks/_runtime/<sid>/active-skill-*.json`) into the canonical
+ * 4.0.8 lease + index + graph layout. Per RD §6, the function is
+ * idempotent: a second invocation finds zero legacy sources and
+ * reports `createdCount = 0`.
+ *
+ * ESM safety: uses ESM `node:fs` imports (top of file already) plus
+ * one dynamic-`require` removal by using `readFileSync` /
+ * `writeFileSync` from `node:fs` directly (the prior `require('node:fs')`
+ * seam was unsafe under ESM and is replaced here).
+ */
+export function reconcilePresenceLeases(input) {
+    const { projectRoot, sessionId, callerId } = input;
+    const conflicts = [];
+    const legacyPaths = [];
+    // Canonical target tree (RD §6).
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
+    const sessionRoot = join(runtimeRoot, sessionId);
+    const leasesDir = join(sessionRoot, 'leases');
+    const presenceIndexDir = join(sessionRoot, 'presence-index');
+    const migrationsDir = join(sessionRoot, 'migrations');
+    // Detect canonical corruption first (RD §3 D3 + §6): a malformed
+    // active-skill.json is a typed conflict, not a silent fallback.
+    const newPath = join(runtimeRoot, 'active-skill.json');
+    if (existsSync(newPath)) {
+        try {
+            const raw = readFileSync(newPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed?.skill !== 'string') {
+                conflicts.push({ code: 'PEAKS_GRAPH_CORRUPTED', source: newPath, message: 'canonical active-skill.json malformed' });
+            }
+        }
+        catch (err) {
+            conflicts.push({ code: 'PEAKS_GRAPH_CORRUPTED', source: newPath, message: `JSON malformed: ${err.message}` });
+        }
+    }
+    // Legacy sources (per-caller markers + the singleton).
+    const legacyPath2 = join(runtimeRoot, 'legacy-active-skill.json');
+    if (existsSync(legacyPath2)) {
+        legacyPaths.push(legacyPath2);
+    }
+    // Receipt path: idempotency contract.
+    const receiptPath = join(migrationsDir, 'presence-v1.json');
+    let migratedCount = 0;
+    if (existsSync(receiptPath)) {
+        try {
+            const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+            migratedCount = typeof receipt.migratedCount === 'number' ? receipt.migratedCount : 0;
+        }
+        catch { /* swallow; treat as empty receipt */ }
+    }
+    // Migration itself: copy each legacy source into the canonical tree.
+    if (!existsSync(sessionRoot))
+        mkdirSync(sessionRoot, { recursive: true });
+    if (!existsSync(leasesDir))
+        mkdirSync(leasesDir, { recursive: true });
+    if (!existsSync(presenceIndexDir))
+        mkdirSync(presenceIndexDir, { recursive: true });
+    if (!existsSync(migrationsDir))
+        mkdirSync(migrationsDir, { recursive: true });
+    let createdCount = 0;
+    if (legacyPaths.length === 0 && conflicts.length === 0) {
+        // Idempotent path: nothing to do.
+        return { conflicts, legacyPresence: false, migratedCount, createdCount: 0, receiptPath: null };
+    }
+    // Slice 4.0.8 (RD §3 D3): when the canonical target is malformed
+    // and the legacy file is valid, the migration refuses to surface
+    // the legacy as the active presence (canonical-wins-with-error).
+    // The `legacyPresence` flag is `false` whenever a typed conflict
+    // exists, regardless of whether legacy sources are present.
+    const hasCanonicalConflict = conflicts.some((c) => c.code === 'PEAKS_GRAPH_CORRUPTED');
+    if (hasCanonicalConflict) {
+        return {
+            conflicts,
+            legacyPresence: false,
+            migratedCount,
+            createdCount: 0,
+            receiptPath: null,
+        };
+    }
+    for (const legacy of legacyPaths) {
+        try {
+            const raw = readFileSync(legacy, 'utf8');
+            const parsed = JSON.parse(raw);
+            const skill = typeof parsed.skill === 'string' ? parsed.skill : 'peaks-code';
+            const workflowId = `wf-migrated-${Date.now().toString(36)}`;
+            const caller = callerId ?? 'migrated-caller';
+            const leaseBody = {
+                callerId: caller,
+                workflowId,
+                graphRef: `graphs/${workflowId}.json`,
+                skill,
+                depth: 0,
+                startedAt: new Date().toISOString(),
+                lastHeartbeat: new Date().toISOString(),
+                status: 'preparing',
+                schemaVersion: 1,
+            };
+            const leasePath = join(leasesDir, `presence-${caller}-${workflowId}.json`);
+            const tmpPath = `${leasePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            writeFileSync(tmpPath, JSON.stringify(leaseBody, null, 2), 'utf8');
+            renameSync(tmpPath, leasePath);
+            createdCount += 1;
+            migratedCount += 1;
+        }
+        catch (err) {
+            conflicts.push({ code: 'PEAKS_LEASE_IO_FAILED', source: legacy, message: err.message });
+        }
+    }
+    if (createdCount > 0) {
+        const receipt = {
+            schemaVersion: 1,
+            migratedCount,
+            sources: legacyPaths,
+            ts: new Date().toISOString(),
+        };
+        try {
+            writeFileSync(receiptPath, JSON.stringify(receipt, null, 2), 'utf8');
+        }
+        catch { /* best-effort */ }
+    }
+    return {
+        conflicts,
+        legacyPresence: legacyPaths.length > 0,
+        migratedCount,
+        createdCount,
+        receiptPath: createdCount > 0 ? receiptPath : null,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.6",
+  "version": "4.0.8",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -98,9 +98,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-mut": "0.1.11",
-    "peaks-loop-shared-channel": "0.0.15",
-    "peaks-loop-shared": "0.0.36"
+    "peaks-loop-mut": "0.1.14",
+    "peaks-loop-shared-channel": "0.0.18",
+    "peaks-loop-shared": "0.0.39"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"

package/skills/peaks-code/references/completion-handoff.md

@@ -8,7 +8,7 @@ Use Peaks-Loop TXT for the compact handoff capsule: mode, validated decisions, a
 
 ## Workflow completion (no auto-exit)
 
-peaks-code does NOT itself call `peaks skill presence:clear --project <repo>` at workflow end. Presence management is delegated to the last downstream skill in the workflow (peaks-rd, peaks-qa, peaks-txt); each of those skills owns its own presence:clear step per its SKILL.md. peaks-code only sets presence: it does not unset it.
+peaks-code does NOT itself call `peaks skill presence:clear --project <repo>` at workflow end. Presence clear is owned by `peaks workflow terminalize`; for non-workflow ad-hoc skill usage, presence is cleared on session exit. Direct early workflow clear is rejected with `PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR`.
 
 The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-code` to do so. The header continues to display whatever skill is active; the user can `/peaks-code` again to re-anchor.
 

package/skills/peaks-code/references/skill-presence-and-title.md

@@ -18,7 +18,7 @@ peaks statusline install --project <repo>   # idempotent; skips if already insta
 
 Then display the compact status header: `Peaks-Loop Skill: peaks-code | Peaks-Loop Gate: startup | Next: <one short action>`. Display this header on EVERY turn while the skill is active.
 
-Update with `peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.
+Update with `peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — clear is owned by workflow terminalize; follow-up workflows re-claim via new workflow init.
 
 ## Step 2.5 — Set session title