@planu/cli 4.11.7 → 4.11.8

package/dist/storage/approval-operation-lock.d.ts

@@ -0,0 +1,10 @@
+export declare class ApprovalOperationBusyError extends Error {
+    constructor(specId: string);
+}
+/**
+ * Serialize approval and lifecycle operations for one spec across local calls and
+ * processes. Reentrancy lets request_changes invoke update_status while retaining
+ * the same outer exclusion boundary.
+ */
+export declare function withApprovalSpecLock<T>(projectPath: string, specId: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=approval-operation-lock.d.ts.map

package/dist/storage/approval-operation-lock.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { resolve } from 'node:path';
+import { withFileLock } from './file-mutex.js';
+import { LockBusyError, withSpecLock } from '../engine/safety/cross-process-lock.js';
+const heldApprovalLocks = new AsyncLocalStorage();
+function approvalLockId(specId) {
+    const digest = createHash('sha256').update(specId).digest('hex').slice(0, 24);
+    return `__approval-operation-${digest}`;
+}
+export class ApprovalOperationBusyError extends Error {
+    constructor(specId) {
+        super(`Approval operation for ${specId} is busy in another process. Retry shortly.`);
+        this.name = 'ApprovalOperationBusyError';
+    }
+}
+/**
+ * Serialize approval and lifecycle operations for one spec across local calls and
+ * processes. Reentrancy lets request_changes invoke update_status while retaining
+ * the same outer exclusion boundary.
+ */
+export async function withApprovalSpecLock(projectPath, specId, fn) {
+    const normalizedProjectPath = resolve(projectPath);
+    const lockId = approvalLockId(specId);
+    const localLockKey = `${normalizedProjectPath}\0${lockId}`;
+    const heldLocks = heldApprovalLocks.getStore();
+    if (heldLocks?.has(localLockKey)) {
+        return fn();
+    }
+    return withFileLock(localLockKey, async () => {
+        try {
+            return await withSpecLock(normalizedProjectPath, lockId, async () => heldApprovalLocks.run(new Set([...(heldLocks ?? []), localLockKey]), async () => fn()), {
+                reason: `approval/lifecycle operation for ${specId}`,
+            });
+        }
+        catch (error) {
+            if (error instanceof LockBusyError) {
+                throw new ApprovalOperationBusyError(specId);
+            }
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=approval-operation-lock.js.map

package/dist/storage/approval-store.d.ts

@@ -7,6 +7,8 @@ export declare function savePolicy(projectId: string, policy: ApprovalPolicy): P
 export declare function getRecords(projectId: string, specId: string): Promise<ApprovalRecord[]>;
 /** Append a new approval record. Returns the full updated list. */
 export declare function appendRecord(projectId: string, specId: string, record: ApprovalRecord): Promise<ApprovalRecord[]>;
+/** Atomically replace all approval records for a spec. */
+export declare function replaceRecords(projectId: string, specId: string, records: ApprovalRecord[]): Promise<ApprovalRecord[]>;
 /** Delete all approval records for a spec (e.g. when changes are requested). */
 export declare function clearRecords(projectId: string, specId: string): Promise<void>;
 //# sourceMappingURL=approval-store.d.ts.map

package/dist/storage/approval-store.js

@@ -43,8 +43,16 @@ export async function appendRecord(projectId, specId, record) {
         return updated;
     });
 }
+/** Atomically replace all approval records for a spec. */
+export async function replaceRecords(projectId, specId, records) {
+    const filePath = approvalRecordsPath(projectId, specId);
+    return withFileLock(filePath, async () => {
+        await writeJson(filePath, records);
+        return records;
+    });
+}
 /** Delete all approval records for a spec (e.g. when changes are requested). */
 export async function clearRecords(projectId, specId) {
-    await writeJson(approvalRecordsPath(projectId, specId), []);
+    await replaceRecords(projectId, specId, []);
 }
 //# sourceMappingURL=approval-store.js.map

package/dist/storage/spec-store.d.ts

@@ -1,4 +1,4 @@
-import type { Spec, SpecStatus, SpecVersion, SpecSummary, DefinitionOfReady, DefinitionOfDone } from '../types/index.js';
+import type { Spec, SpecStatus, SpecVersion, SpecSummary, DefinitionOfReady, DefinitionOfDone, PostCommitTaskClaim } from '../types/index.js';
 /**
  * Thrown when code tries to write `status` via `updateSpec` directly.
  * All status transitions must go through `handleUpdateStatus` → `transitionSpec`.
@@ -16,6 +16,8 @@ export declare function listSpecs(projectId: string): Promise<Spec[]>;
  * Get a single spec by ID. Returns `null` when not found.
  */
 export declare function getSpec(projectId: string, specId: string): Promise<Spec | null>;
+/** Reload a spec from disk after the caller acquires its cross-process lock. */
+export declare function getSpecFresh(projectId: string, specId: string): Promise<Spec | null>;
 /** SPEC-601: Lookup a spec by its globally unique UUID. */
 export declare function getSpecByUuid(projectId: string, uuid: string): Promise<Spec | null>;
 /**
@@ -27,7 +29,32 @@ export declare function createSpec(projectId: string, spec: Spec): Promise<Spec>
  * Importable exclusively from `src/engine/spec-state-machine/transition-spec.ts`.
  * All status transitions must flow through `transitionSpec` → `__internalSetStatus`.
  */
-export declare function __internalSetStatus(projectId: string, specId: string, status: SpecStatus): Promise<Spec>;
+export declare function __internalSetStatus(projectId: string, specId: string, status: SpecStatus, updates?: Omit<Partial<Spec>, 'status'>, pendingBackgroundActions?: readonly string[], expectedSnapshot?: Pick<Spec, 'status' | 'updatedAt'>): Promise<Spec>;
+/**
+ * Restore the exact snapshot captured before a lifecycle transition.
+ * This is only used by transitionSpec compensation while the caller still
+ * holds the per-spec cross-process lock.
+ */
+export declare function __internalRestoreSpecSnapshot(projectId: string, specId: string, snapshot: Spec, expectedCurrentSnapshot: Spec): Promise<Spec>;
+/**
+ * Atomically claim one durable post-commit task.
+ * Legacy transition receipts are materialized only when the task was explicitly planned.
+ */
+export declare function claimPostCommitTask(projectId: string, specId: string, transitionId: string, taskName: string, options?: {
+    now?: string;
+    leaseMs?: number;
+}): Promise<PostCommitTaskClaim>;
+/** Extend a running task lease while the owning execution is still alive. */
+export declare function renewPostCommitTaskLease(projectId: string, specId: string, transitionId: string, taskName: string, executionId: string, options?: {
+    now?: string;
+    leaseMs?: number;
+}): Promise<boolean>;
+/** Finalize a claimed task if the execution lease still belongs to the caller. */
+export declare function settlePostCommitTask(projectId: string, specId: string, transitionId: string, taskName: string, executionId: string, outcome: {
+    status: 'done' | 'failed';
+    error?: string;
+    now?: string;
+}): Promise<boolean>;
 /**
  * Replace an existing spec entirely (non-status fields only).
  * Throws `DirectStatusWriteForbiddenError` if `updates` contains a `status` field.

package/dist/storage/spec-store.js

@@ -4,6 +4,8 @@ import { withFileLock } from './file-mutex.js';
 import { discoverProjectDataFile } from './data-dir-discovery.js';
 import { computeHealthScore } from '../engine/spec-health-scorer.js';
 import { loadSpecContent } from '../engine/validation-loop.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { acquireLock, releaseLock } from '../engine/safety/cross-process-lock.js';
 // ---------------------------------------------------------------------------
 // SPEC-720: Guard error — direct status write forbidden
 // ---------------------------------------------------------------------------
@@ -44,6 +46,43 @@ function normalizeSpec(raw) {
 // Populated on first read; invalidated (updated) on every mutation.
 // Eliminates repeated disk I/O for a local single-user MCP server.
 const specsCache = new Map();
+const STORE_LOCK_RETRY_MS = 25;
+const STORE_LOCK_TIMEOUT_MS = 2_000;
+const STORE_LOCK_ID = '__project-spec-store__';
+const DEFAULT_POST_COMMIT_LEASE_MS = 30_000;
+const MAX_POST_COMMIT_ATTEMPTS = 3;
+const COMPLETED_OUTBOX_RETENTION = 20;
+async function withSpecMutationLock(projectId, fn) {
+    return withFileLock(specsFile(projectId), async () => {
+        const lockRoot = projectDataDir(projectId);
+        const deadline = Date.now() + STORE_LOCK_TIMEOUT_MS;
+        let handle = await acquireLock(lockRoot, STORE_LOCK_ID, {
+            reason: `spec-store mutation for ${projectId}`,
+        });
+        while (handle === null && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, STORE_LOCK_RETRY_MS));
+            handle = await acquireLock(lockRoot, STORE_LOCK_ID, {
+                reason: `spec-store mutation for ${projectId}`,
+            });
+        }
+        if (handle === null) {
+            throw new Error(`[Planu] Spec store is busy for project ${projectId}; retry the operation.`);
+        }
+        try {
+            // Another process may have written since this process populated its cache.
+            specsCache.delete(projectId);
+            return await fn();
+        }
+        finally {
+            await releaseLock(handle).catch((error) => {
+                console.warn('[planu:spec-store] failed to release mutation lock', {
+                    projectId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }
+    });
+}
 /**
  * Load all specs — from cache on subsequent calls, disk only on first access.
  *
@@ -99,6 +138,11 @@ export async function getSpec(projectId, specId) {
     const specs = await loadAll(projectId);
     return specs.find((s) => s.id === specId) ?? null;
 }
+/** Reload a spec from disk after the caller acquires its cross-process lock. */
+export async function getSpecFresh(projectId, specId) {
+    specsCache.delete(projectId);
+    return getSpec(projectId, specId);
+}
 /** SPEC-601: Lookup a spec by its globally unique UUID. */
 export async function getSpecByUuid(projectId, uuid) {
     const specs = await loadAll(projectId);
@@ -108,7 +152,7 @@ export async function getSpecByUuid(projectId, uuid) {
  * Create a new spec. Throws if a spec with the same ID already exists.
  */
 export async function createSpec(projectId, spec) {
-    return withFileLock(specsFile(projectId), async () => {
+    return withSpecMutationLock(projectId, async () => {
         const specs = await loadAll(projectId);
         if (specs.some((s) => s.id === spec.id)) {
             throw new Error(`Spec "${spec.id}" already exists in project "${projectId}"`);
@@ -128,8 +172,8 @@ export async function createSpec(projectId, spec) {
  * NOT exported from the barrel. Called only by `__internalSetStatus` and itself.
  * All external callers must use `updateSpec` (non-status) or `transitionSpec` (status).
  */
-async function __internalUpdateSpec(projectId, specId, updates) {
-    return withFileLock(specsFile(projectId), async () => {
+async function __internalUpdateSpec(projectId, specId, updates, pendingBackgroundActions = [], expectedSnapshot) {
+    return withSpecMutationLock(projectId, async () => {
         const specs = await loadAll(projectId);
         const idx = specs.findIndex((s) => s.id === specId);
         if (idx === -1) {
@@ -139,11 +183,42 @@ async function __internalUpdateSpec(projectId, specId, updates) {
         if (!existing) {
             throw new Error(`Spec "${specId}" not found in project "${projectId}"`);
         }
+        if (expectedSnapshot &&
+            (existing.status !== expectedSnapshot.status ||
+                existing.updatedAt !== expectedSnapshot.updatedAt)) {
+            throw new Error(`Spec "${specId}" changed after lifecycle gates ran; retry update_status with the fresh state.`);
+        }
         const now = new Date().toISOString();
         const incomingStatus = updates.status;
         let updatedStatusHistory = existing.statusHistory;
         if (incomingStatus !== undefined && incomingStatus !== existing.status) {
-            const entry = { status: incomingStatus, changedAt: now };
+            const transitionId = createHash('sha256')
+                .update([
+                'update_status:v1',
+                projectId,
+                specId,
+                existing.status,
+                incomingStatus,
+                now,
+                randomUUID(),
+            ].join('\0'))
+                .digest('hex')
+                .slice(0, 24);
+            const entry = {
+                status: incomingStatus,
+                changedAt: now,
+                fromStatus: existing.status,
+                transitionId,
+                ...(pendingBackgroundActions.length > 0 && { pendingBackgroundActions }),
+                ...(pendingBackgroundActions.length > 0 && {
+                    postCommitTasks: pendingBackgroundActions.map((name) => ({
+                        name,
+                        status: 'pending',
+                        attempts: 0,
+                        updatedAt: now,
+                    })),
+                }),
+            };
             updatedStatusHistory = [...(existing.statusHistory ?? []), entry];
         }
         const merged = {
@@ -168,8 +243,233 @@ async function __internalUpdateSpec(projectId, specId, updates) {
  * Importable exclusively from `src/engine/spec-state-machine/transition-spec.ts`.
  * All status transitions must flow through `transitionSpec` → `__internalSetStatus`.
  */
-export async function __internalSetStatus(projectId, specId, status) {
-    return __internalUpdateSpec(projectId, specId, { status });
+export async function __internalSetStatus(projectId, specId, status, updates = {}, pendingBackgroundActions = [], expectedSnapshot) {
+    return __internalUpdateSpec(projectId, specId, { ...updates, status }, pendingBackgroundActions, expectedSnapshot);
+}
+/**
+ * Restore the exact snapshot captured before a lifecycle transition.
+ * This is only used by transitionSpec compensation while the caller still
+ * holds the per-spec cross-process lock.
+ */
+export async function __internalRestoreSpecSnapshot(projectId, specId, snapshot, expectedCurrentSnapshot) {
+    return withSpecMutationLock(projectId, async () => {
+        const specs = await loadAll(projectId);
+        const idx = specs.findIndex((candidate) => candidate.id === specId);
+        if (idx === -1) {
+            throw new Error(`Spec "${specId}" not found in project "${projectId}"`);
+        }
+        if (snapshot.id !== specId) {
+            throw new Error(`Cannot restore snapshot "${snapshot.id}" over "${specId}" in project "${projectId}"`);
+        }
+        const existing = specs[idx];
+        if (!existing) {
+            throw new Error(`Spec "${specId}" not found in project "${projectId}"`);
+        }
+        if (JSON.stringify(existing) !== JSON.stringify(expectedCurrentSnapshot)) {
+            throw new Error(`Spec "${specId}" changed after the transition commit; refusing unsafe compensation.`);
+        }
+        const restored = { ...snapshot };
+        const nextSpecs = specs.map((current, currentIdx) => (currentIdx === idx ? restored : current));
+        await saveAll(projectId, nextSpecs);
+        return restored;
+    });
+}
+function updateOutboxReceipt(history, transitionId, update) {
+    if (!history) {
+        return null;
+    }
+    const index = history.findIndex((entry) => entry.transitionId === transitionId);
+    if (index === -1) {
+        return null;
+    }
+    return history.map((entry, currentIndex) => (currentIndex === index ? update(entry) : entry));
+}
+function materializePostCommitTasks(entry) {
+    if (entry.postCommitTasks) {
+        return entry.postCommitTasks;
+    }
+    return (entry.pendingBackgroundActions ?? []).map((name) => ({
+        name,
+        status: 'pending',
+        attempts: 0,
+        updatedAt: entry.changedAt,
+    }));
+}
+function isPendingPostCommitTask(task) {
+    return (task.status !== 'done' &&
+        !(task.status === 'failed' && task.attempts >= MAX_POST_COMMIT_ATTEMPTS));
+}
+function pruneCompletedOutbox(history) {
+    let completedOutboxesKept = 0;
+    return [...history]
+        .reverse()
+        .map((entry) => {
+        const tasks = entry.postCommitTasks;
+        const isCompletedOutbox = tasks !== undefined && tasks.length > 0 && tasks.every((task) => task.status === 'done');
+        if (!isCompletedOutbox) {
+            return entry;
+        }
+        completedOutboxesKept += 1;
+        if (completedOutboxesKept <= COMPLETED_OUTBOX_RETENTION) {
+            return entry;
+        }
+        const { postCommitTasks: _postCommitTasks, pendingBackgroundActions: _pending, ...receipt } = entry;
+        return receipt;
+    })
+        .reverse();
+}
+/**
+ * Atomically claim one durable post-commit task.
+ * Legacy transition receipts are materialized only when the task was explicitly planned.
+ */
+export async function claimPostCommitTask(projectId, specId, transitionId, taskName, options = {}) {
+    return withSpecMutationLock(projectId, async () => {
+        const specs = await loadAll(projectId);
+        const specIndex = specs.findIndex((candidate) => candidate.id === specId);
+        const existing = specs[specIndex];
+        if (!existing) {
+            return { claimed: false, reason: 'missing' };
+        }
+        const now = options.now ?? new Date().toISOString();
+        const nowMs = Date.parse(now);
+        const claimResult = {
+            value: { claimed: false, reason: 'missing' },
+        };
+        const nextHistory = updateOutboxReceipt(existing.statusHistory, transitionId, (entry) => {
+            const tasks = materializePostCommitTasks(entry);
+            const taskIndex = tasks.findIndex((task) => task.name === taskName);
+            const current = tasks[taskIndex];
+            if (!current) {
+                return entry;
+            }
+            if (current.status === 'done') {
+                claimResult.value = { claimed: false, reason: 'done' };
+                return entry;
+            }
+            if (current.attempts >= MAX_POST_COMMIT_ATTEMPTS) {
+                claimResult.value = { claimed: false, reason: 'done' };
+                return entry;
+            }
+            if (current.status === 'running' &&
+                current.leaseExpiresAt &&
+                Date.parse(current.leaseExpiresAt) > nowMs) {
+                claimResult.value = {
+                    claimed: false,
+                    reason: 'running',
+                    retryAt: current.leaseExpiresAt,
+                };
+                return entry;
+            }
+            const executionId = randomUUID();
+            const attempts = current.attempts + 1;
+            const claimedTask = {
+                name: current.name,
+                status: 'running',
+                attempts,
+                updatedAt: now,
+                executionId,
+                leaseExpiresAt: new Date(nowMs + (options.leaseMs ?? DEFAULT_POST_COMMIT_LEASE_MS)).toISOString(),
+            };
+            claimResult.value = { claimed: true, executionId, attempts };
+            const nextTasks = tasks.map((task, index) => (index === taskIndex ? claimedTask : task));
+            return {
+                ...entry,
+                postCommitTasks: nextTasks,
+                pendingBackgroundActions: nextTasks
+                    .filter(isPendingPostCommitTask)
+                    .map((task) => task.name),
+            };
+        });
+        if (!nextHistory || !claimResult.value.claimed) {
+            return claimResult.value;
+        }
+        const updated = { ...existing, statusHistory: nextHistory };
+        await saveAll(projectId, specs.map((spec, index) => (index === specIndex ? updated : spec)));
+        return claimResult.value;
+    });
+}
+/** Extend a running task lease while the owning execution is still alive. */
+export async function renewPostCommitTaskLease(projectId, specId, transitionId, taskName, executionId, options = {}) {
+    return withSpecMutationLock(projectId, async () => {
+        const specs = await loadAll(projectId);
+        const specIndex = specs.findIndex((candidate) => candidate.id === specId);
+        const existing = specs[specIndex];
+        if (!existing) {
+            return false;
+        }
+        const now = options.now ?? new Date().toISOString();
+        const nowMs = Date.parse(now);
+        const renewed = { value: false };
+        const nextHistory = updateOutboxReceipt(existing.statusHistory, transitionId, (entry) => {
+            const tasks = materializePostCommitTasks(entry);
+            const taskIndex = tasks.findIndex((task) => task.name === taskName);
+            const current = tasks[taskIndex];
+            if (current?.status !== 'running' || current.executionId !== executionId) {
+                return entry;
+            }
+            renewed.value = true;
+            const renewedTask = {
+                ...current,
+                updatedAt: now,
+                leaseExpiresAt: new Date(nowMs + (options.leaseMs ?? DEFAULT_POST_COMMIT_LEASE_MS)).toISOString(),
+            };
+            return {
+                ...entry,
+                postCommitTasks: tasks.map((task, index) => (index === taskIndex ? renewedTask : task)),
+            };
+        });
+        if (!nextHistory || !renewed.value) {
+            return false;
+        }
+        await saveAll(projectId, specs.map((spec, index) => index === specIndex ? { ...existing, statusHistory: nextHistory } : spec));
+        return true;
+    });
+}
+/** Finalize a claimed task if the execution lease still belongs to the caller. */
+export async function settlePostCommitTask(projectId, specId, transitionId, taskName, executionId, outcome) {
+    return withSpecMutationLock(projectId, async () => {
+        const specs = await loadAll(projectId);
+        const specIndex = specs.findIndex((candidate) => candidate.id === specId);
+        const existing = specs[specIndex];
+        if (!existing) {
+            return false;
+        }
+        const now = outcome.now ?? new Date().toISOString();
+        const settlement = { completed: false };
+        const nextHistory = updateOutboxReceipt(existing.statusHistory, transitionId, (entry) => {
+            const tasks = materializePostCommitTasks(entry);
+            const taskIndex = tasks.findIndex((task) => task.name === taskName);
+            const current = tasks[taskIndex];
+            if (current?.status !== 'running' || current.executionId !== executionId) {
+                return entry;
+            }
+            settlement.completed = true;
+            const settledTask = {
+                name: current.name,
+                status: outcome.status,
+                attempts: current.attempts,
+                updatedAt: now,
+                ...(outcome.status === 'failed' && outcome.error ? { lastError: outcome.error } : {}),
+            };
+            const nextTasks = tasks.map((task, index) => (index === taskIndex ? settledTask : task));
+            return {
+                ...entry,
+                postCommitTasks: nextTasks,
+                pendingBackgroundActions: nextTasks
+                    .filter(isPendingPostCommitTask)
+                    .map((task) => task.name),
+            };
+        });
+        if (!nextHistory || !settlement.completed) {
+            return false;
+        }
+        const updated = {
+            ...existing,
+            statusHistory: pruneCompletedOutbox(nextHistory),
+        };
+        await saveAll(projectId, specs.map((spec, index) => (index === specIndex ? updated : spec)));
+        return true;
+    });
 }
 /**
  * Replace an existing spec entirely (non-status fields only).
@@ -198,7 +498,7 @@ export async function updateSpecStatus(_projectId, specId, status) {
  * Delete a spec by ID. Returns `true` if removed, `false` if not found.
  */
 export async function deleteSpec(projectId, specId) {
-    return withFileLock(specsFile(projectId), async () => {
+    return withSpecMutationLock(projectId, async () => {
         const specs = await loadAll(projectId);
         const idx = specs.findIndex((s) => s.id === specId);
         if (idx === -1) {