@planu/cli 4.14.1 → 5.1.1

package/dist/storage/migrations/canonical-storage.js

@@ -253,27 +253,129 @@ function specKey(value, index) {
     }
     return `anonymous:${index}`;
 }
-function mergeSpecs(source, destination) {
-    if (!Array.isArray(source) || !Array.isArray(destination)) {
-        throw new Error('[Planu] specs.json must contain arrays');
+function unwrapSpecs(value) {
+    if (Array.isArray(value)) {
+        return { rows: value, envelope: false };
     }
+    if (value && typeof value === 'object' && Array.isArray(value.data)) {
+        return { rows: value.data, envelope: true };
+    }
+    throw new Error('[Planu] specs.json must contain an array or canonical envelope');
+}
+function conflictingUuidIdentity(left, right) {
+    if (!left || typeof left !== 'object' || !right || typeof right !== 'object') {
+        return false;
+    }
+    const leftRecord = left;
+    const rightRecord = right;
+    return (typeof leftRecord.uuid === 'string' &&
+        leftRecord.uuid.length > 0 &&
+        leftRecord.uuid === rightRecord.uuid &&
+        typeof leftRecord.id === 'string' &&
+        typeof rightRecord.id === 'string' &&
+        leftRecord.id !== rightRecord.id);
+}
+/** Reject split-brain source rows before any merge Map can discard one of them. */
+function validateRawSpecRows(rows, owningProjectId) {
+    const ids = new Map();
+    const identities = new Map();
+    for (const record of rows) {
+        if (!record || typeof record !== 'object') {
+            throw new Error('[Planu] Canonical spec ownership conflict during migration');
+        }
+        const value = record;
+        const id = typeof value.id === 'string' && value.id.length > 0 ? value.id : undefined;
+        const uuid = typeof value.uuid === 'string' && value.uuid.length > 0 ? value.uuid : undefined;
+        if (id !== undefined) {
+            if (ids.has(id)) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            ids.set(id, uuid);
+        }
+        if (typeof value.projectId !== 'string' || value.projectId !== owningProjectId) {
+            throw new Error('[Planu] Canonical spec ownership conflict during migration');
+        }
+        const aliases = Array.isArray(value.uuidAliases)
+            ? value.uuidAliases
+            : [];
+        for (const identity of [uuid, ...aliases]) {
+            if (typeof identity !== 'string' || identity.length === 0 || id === undefined) {
+                continue;
+            }
+            const owner = identities.get(identity);
+            if (owner !== undefined && owner !== id) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            identities.set(identity, id);
+        }
+    }
+}
+function validateSpecsDocument(value, owningProjectId) {
+    validateRawSpecRows(unwrapSpecs(value).rows, owningProjectId);
+}
+function mergeSpecs(source, destination, owningProjectId) {
+    const sourceStore = unwrapSpecs(source);
+    const destinationStore = unwrapSpecs(destination);
+    validateRawSpecRows(sourceStore.rows, owningProjectId);
+    validateRawSpecRows(destinationStore.rows, owningProjectId);
     const merged = new Map();
-    destination.forEach((record, index) => merged.set(specKey(record, index), record));
+    for (const [index, record] of destinationStore.rows.entries()) {
+        const key = specKey(record, index);
+        const previous = merged.get(key);
+        if (previous !== undefined && conflictingUuidIdentity(previous, record)) {
+            throw new Error('[Planu] Canonical spec identity conflict during migration');
+        }
+        merged.set(key, record);
+    }
     let sourceWon = false;
-    for (const [index, record] of source.entries()) {
+    for (const [index, record] of sourceStore.rows.entries()) {
         const key = specKey(record, index);
         const current = merged.get(key);
         if (current === undefined) {
             merged.set(key, record);
             continue;
         }
+        if (conflictingUuidIdentity(current, record)) {
+            throw new Error('[Planu] Canonical spec identity conflict during migration');
+        }
         if (recordTimestamp(record) > recordTimestamp(current)) {
             merged.set(key, record);
             sourceWon = true;
         }
     }
+    // Legacy fixtures may omit UUID/project metadata, but a merger must never
+    // silently publish two canonical IDs or UUID identities when they are present.
+    const seenIds = new Set();
+    const seenUuids = new Set();
+    for (const record of merged.values()) {
+        if (!record || typeof record !== 'object') {
+            continue;
+        }
+        const value = record;
+        if (typeof value.id === 'string' && value.id.length > 0) {
+            if (seenIds.has(value.id)) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            seenIds.add(value.id);
+        }
+        const aliases = Array.isArray(value.uuidAliases)
+            ? value.uuidAliases
+            : [];
+        const identities = [value.uuid, ...aliases];
+        for (const identity of identities) {
+            if (typeof identity !== 'string' || identity.length === 0) {
+                continue;
+            }
+            if (seenUuids.has(identity)) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            seenUuids.add(identity);
+        }
+    }
     return {
-        value: [...merged.values()],
+        value: sourceStore.envelope || destinationStore.envelope
+            ? { schemaVersion: 1, data: [...merged.values()] }
+            : [...merged.values()],
         resolution: sourceWon ? 'source-newer' : 'destination-newer',
     };
 }
@@ -285,6 +387,9 @@ async function mergeFile(sourceRoot, sourceDigest, stagingRoot, destinationRoot,
     if (sha256(current) !== file.sha256) {
         throw new Error(`[Planu] Legacy source changed during migration: ${sourcePath}`);
     }
+    if (file.relativePath === 'specs.json') {
+        validateSpecsDocument(JSON.parse(current.toString('utf8')), basename(destinationRoot));
+    }
     await mkdir(dirname(stagingPath), { recursive: true });
     if (!(await exists(stagingPath))) {
         await copyFile(sourcePath, stagingPath);
@@ -301,7 +406,7 @@ async function mergeFile(sourceRoot, sourceDigest, stagingRoot, destinationRoot,
         const destinationJson = JSON.parse(await readFile(stagingPath, 'utf8'));
         const merged = file.relativePath === 'knowledge.json'
             ? mergeKnowledge(sourceJson, destinationJson)
-            : mergeSpecs(sourceJson, destinationJson);
+            : mergeSpecs(sourceJson, destinationJson, basename(destinationRoot));
         await writeFile(stagingPath, `${JSON.stringify(merged.value, null, 2)}\n`, { mode: 0o600 });
         resolution = merged.resolution;
     }
@@ -342,11 +447,15 @@ async function planCollisions(sourceInventories, destination, destinationRoot) {
             const current = state.get(file.relativePath);
             const schemaFile = file.relativePath === 'knowledge.json' || file.relativePath === 'specs.json';
             if (!current) {
+                const schemaValue = schemaFile
+                    ? JSON.parse(await readFile(sourcePath, 'utf8'))
+                    : undefined;
+                if (file.relativePath === 'specs.json') {
+                    validateSpecsDocument(schemaValue, basename(destinationRoot));
+                }
                 state.set(file.relativePath, {
                     sha256: file.sha256,
-                    ...(schemaFile
-                        ? { value: JSON.parse(await readFile(sourcePath, 'utf8')) }
-                        : {}),
+                    ...(schemaFile ? { value: schemaValue } : {}),
                 });
                 continue;
             }
@@ -361,7 +470,7 @@ async function planCollisions(sourceInventories, destination, destinationRoot) {
                     JSON.parse(await readFile(join(destinationRoot, ...file.relativePath.split('/')), 'utf8'));
                 const merged = file.relativePath === 'knowledge.json'
                     ? mergeKnowledge(source, target)
-                    : mergeSpecs(source, target);
+                    : mergeSpecs(source, target, basename(destinationRoot));
                 resolution = merged.resolution;
                 state.set(file.relativePath, {
                     sha256: sha256(JSON.stringify(merged.value)),
@@ -403,6 +512,10 @@ async function prepare(journal) {
             await mergeFile(inventory.root, inventory.digest, journal.stagingRoot, journal.destinationRoot, file, journal.collisions);
         }
     }
+    const stagedSpecs = join(journal.stagingRoot, 'specs.json');
+    if (await exists(stagedSpecs)) {
+        validateSpecsDocument(JSON.parse(await readFile(stagedSpecs, 'utf8')), basename(journal.destinationRoot));
+    }
     journal.expectedInventory = await inventoryStorageRoot(journal.stagingRoot);
 }
 async function switchDestination(journal) {

package/dist/storage/runtime-db.d.ts

@@ -1,3 +1,10 @@
+import { type ValidationReceiptCheckpointLimits } from '../types/durable-validation.js';
+/** Count-only process diagnostic for deterministic resource lifecycle tests. */
+export declare function getRuntimeDatabaseDiagnosticsForTests(): {
+    readonly openConnections: number;
+    readonly integrityCheckedOpens: number;
+    readonly integrityBypassedOpens: number;
+};
 export type RuntimeRecordKind = 'mutation' | 'index' | 'audit-state';
 export interface RuntimeDatabaseOptions {
     readonly path: string;
@@ -131,6 +138,7 @@ export declare class RuntimeDatabase implements Disposable {
     recordJobProgress(input: JobLeaseInput & {
         readonly checkpoint: unknown;
     }): DurableJobRecord;
+    assertActiveJobLease(input: JobLeaseInput): void;
     checkpointJob(input: JobLeaseInput & {
         readonly checkpoint: unknown;
     }): DurableJobRecord;
@@ -142,6 +150,7 @@ export declare class RuntimeDatabase implements Disposable {
     }): DurableJobRecord;
     retryJob(projectId: string, workspaceId: string, id: string): DurableJobRecord;
     restartJob(projectId: string, workspaceId: string, id: string): DurableJobRecord;
+    restartReceiptPublication(projectId: string, workspaceId: string, id: string, limits: ValidationReceiptCheckpointLimits): DurableJobRecord;
     restartJobWithPayload(projectId: string, workspaceId: string, id: string, payload: unknown): DurableJobRecord;
     cancelJob(projectId: string, workspaceId: string, id: string): DurableJobRecord;
     private archiveCheckpointBeforeRestart;

package/dist/storage/runtime-db.js

@@ -2,10 +2,21 @@
 import { mkdirSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { parseValidationReceiptPendingCheckpoint, } from '../types/durable-validation.js';
 const CURRENT_SCHEMA_VERSION = 4;
 const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
 const DEFAULT_MAX_CONNECTIONS = 4;
 const openConnections = new Map();
+let integrityCheckedOpens = 0;
+let integrityBypassedOpens = 0;
+/** Count-only process diagnostic for deterministic resource lifecycle tests. */
+export function getRuntimeDatabaseDiagnosticsForTests() {
+    let count = 0;
+    for (const connections of openConnections.values()) {
+        count += connections;
+    }
+    return { openConnections: count, integrityCheckedOpens, integrityBypassedOpens };
+}
 export const DURABLE_JOB_STATES = [
     'accepted',
     'running',
@@ -101,6 +112,10 @@ export class RuntimeDatabase {
             this.migrate();
             if (options.checkIntegrity !== false) {
                 this.assertIntegrity();
+                integrityCheckedOpens += 1;
+            }
+            else {
+                integrityBypassedOpens += 1;
             }
         }
         catch (error) {
@@ -464,27 +479,39 @@ export class RuntimeDatabase {
         const now = input.now ?? new Date().toISOString();
         const expiresAt = new Date(Date.parse(now) + input.leaseMs).toISOString();
         const result = this.database
-            .prepare(`UPDATE jobs SET lease_expires_at = ?, updated_at = ?
+            .prepare(`UPDATE jobs
+         SET lease_expires_at = CASE WHEN lease_expires_at > ? THEN lease_expires_at ELSE ? END,
+             updated_at = ?
          WHERE project_id = ? AND workspace_id = ? AND id = ?
            AND state = 'running' AND lease_owner = ? AND fencing_token = ? AND cancel_requested = 0
            AND lease_expires_at > ?`)
-            .run(expiresAt, now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
+            .run(expiresAt, expiresAt, now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
         return result.changes === 1;
     }
     recordJobProgress(input) {
-        this.requireLeasedJob(input);
+        this.assertOpen();
+        validateLeaseInput(input);
         const now = input.now ?? new Date().toISOString();
+        const expiresAt = new Date(Date.parse(now) + input.leaseMs).toISOString();
         const result = this.database
-            .prepare(`UPDATE jobs SET checkpoint_json = ?, updated_at = ?
+            .prepare(`UPDATE jobs
+         SET checkpoint_json = ?,
+             lease_expires_at = CASE WHEN lease_expires_at > ? THEN lease_expires_at ELSE ? END,
+             updated_at = ?
          WHERE project_id = ? AND workspace_id = ? AND id = ?
            AND state = 'running' AND lease_owner = ? AND fencing_token = ? AND cancel_requested = 0
            AND lease_expires_at > ?`)
-            .run(stringifyJson(input.checkpoint), now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
+            .run(stringifyJson(input.checkpoint), expiresAt, expiresAt, now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
         if (result.changes !== 1) {
+            this.requireLeasedJob(input);
             throw new Error('[Planu] Job lease was lost before checkpoint');
         }
         return requireJobRecord(this.getJob(input.projectId, input.workspaceId, input.id), input.id);
     }
+    assertActiveJobLease(input) {
+        this.assertOpen();
+        this.requireLeasedJob(input);
+    }
     checkpointJob(input) {
         return this.finishLeasedUpdate(input, 'checkpointed', {
             checkpointJson: stringifyJson(input.checkpoint),
@@ -492,6 +519,7 @@ export class RuntimeDatabase {
     }
     completeJob(input) {
         return this.finishLeasedUpdate(input, 'completed', {
+            clearCheckpoint: true,
             resultJson: stringifyJson(input.result),
         });
     }
@@ -545,6 +573,33 @@ export class RuntimeDatabase {
         });
         return requireJobRecord(this.getJob(projectId, workspaceId, id), id);
     }
+    restartReceiptPublication(projectId, workspaceId, id, limits) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(id, 'job id');
+        const now = new Date().toISOString();
+        this.transaction(() => {
+            const current = this.getJob(projectId, workspaceId, id);
+            if (!current ||
+                !['failed', 'dead-letter'].includes(current.state) ||
+                current.cancelRequested ||
+                !parseValidationReceiptPendingCheckpoint(current.checkpoint, limits)) {
+                throw new Error('[Planu] Job receipt publication is not restartable');
+            }
+            const changed = this.database
+                .prepare(`UPDATE jobs SET state = 'accepted', attempts = 0, cancel_requested = 0,
+             result_json = NULL, error_message = NULL, lease_owner = NULL,
+             lease_expires_at = NULL, updated_at = ?
+           WHERE project_id = ? AND workspace_id = ? AND id = ?
+             AND state IN ('failed', 'dead-letter') AND cancel_requested = 0`)
+                .run(now, projectId, workspaceId, id);
+            if (changed.changes !== 1) {
+                throw new Error('[Planu] Job receipt publication is not restartable');
+            }
+        });
+        return requireJobRecord(this.getJob(projectId, workspaceId, id), id);
+    }
     restartJobWithPayload(projectId, workspaceId, id, payload) {
         this.assertOpen();
         requireIdentifier(projectId, 'projectId');
@@ -641,7 +696,8 @@ export class RuntimeDatabase {
         const current = this.getJob(input.projectId, input.workspaceId, input.id);
         if (current?.state !== 'running' ||
             current.leaseOwner !== input.workerId ||
-            current.fencingToken !== requireFencingToken(input)) {
+            current.fencingToken !== requireFencingToken(input) ||
+            current.cancelRequested) {
             throw new Error('[Planu] Job lease is stale or not owned by this worker');
         }
         const now = input.now ?? new Date().toISOString();
@@ -654,13 +710,13 @@ export class RuntimeDatabase {
         this.requireLeasedJob(input);
         const now = input.now ?? new Date().toISOString();
         const result = this.database
-            .prepare(`UPDATE jobs SET state = ?, checkpoint_json = COALESCE(?, checkpoint_json),
+            .prepare(`UPDATE jobs SET state = ?, checkpoint_json = CASE WHEN ? = 1 THEN NULL ELSE COALESCE(?, checkpoint_json) END,
            result_json = COALESCE(?, result_json), error_message = ?,
            lease_owner = NULL, lease_expires_at = NULL, updated_at = ?
          WHERE project_id = ? AND workspace_id = ? AND id = ?
            AND state = 'running' AND lease_owner = ? AND fencing_token = ?
            AND lease_expires_at > ? AND cancel_requested = 0`)
-            .run(state, values.checkpointJson ?? null, values.resultJson ?? null, values.errorMessage ?? null, now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
+            .run(state, values.clearCheckpoint === true ? 1 : 0, values.checkpointJson ?? null, values.resultJson ?? null, values.errorMessage ?? null, now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
         if (result.changes !== 1) {
             throw new Error('[Planu] Job lease was lost before commit');
         }

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

@@ -1,4 +1,4 @@
-import type { Spec, SpecStatus, SpecVersion, SpecSummary, DefinitionOfReady, DefinitionOfDone, PostCommitTaskClaim } from '../types/index.js';
+import type { Spec, SpecStatus, SpecVersion, SpecSummary, DefinitionOfReady, DefinitionOfDone, StatusHistoryEntry, PostCommitTaskClaim } from '../types/index.js';
 /**
  * Thrown when code tries to write `status` via `updateSpec` directly.
  * All status transitions must go through `handleUpdateStatus` → `transitionSpec`.
@@ -6,6 +6,18 @@ import type { Spec, SpecStatus, SpecVersion, SpecSummary, DefinitionOfReady, Def
 export declare class DirectStatusWriteForbiddenError extends Error {
     constructor(specId: string, attemptedStatus: string, caller: string);
 }
+/** Stable, privacy-safe canonical identity failure. */
+export declare class DuplicateSpecIdError extends Error {
+    readonly code: 'DUPLICATE_SPEC_ID';
+    constructor(projectId: string, specIds: readonly string[]);
+}
+/**
+ * Validate the single canonical identity namespace shared by every spec row.
+ * Keep the diagnostic deliberately small: UUIDs and storage paths are private.
+ */
+export declare function validateCanonicalSpecRows(projectId: string, specs: readonly Spec[]): void;
+/** Administrative-only lock boundary for the digest-bound raw-store repair. */
+export declare function withCanonicalSpecRepairLock<T>(projectId: string, fn: () => Promise<T>): Promise<T>;
 /** Evict the cache for a project (e.g. after external file changes). */
 export declare function invalidateSpecsCache(projectId: string): void;
 /**
@@ -34,7 +46,7 @@ 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, updates?: Omit<Partial<Spec>, 'status'>, pendingBackgroundActions?: readonly string[], expectedSnapshot?: Pick<Spec, 'status' | 'updatedAt'>): 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'>, transitionRootBinding?: string, reconciliation?: Pick<StatusHistoryEntry, 'reconciliationRequestId' | 'reconciliationBindingDigest' | 'trigger'>): Promise<Spec>;
 /**
  * Restore the exact snapshot captured before a lifecycle transition.
  * This is only used by transitionSpec compensation while the caller still

package/dist/storage/spec-store.js

@@ -22,6 +22,15 @@ export class DirectStatusWriteForbiddenError extends Error {
         this.name = 'DirectStatusWriteForbiddenError';
     }
 }
+/** Stable, privacy-safe canonical identity failure. */
+export class DuplicateSpecIdError extends Error {
+    code = 'DUPLICATE_SPEC_ID';
+    constructor(projectId, specIds) {
+        const ids = [...new Set(specIds)].sort((left, right) => left.localeCompare(right));
+        super(`[Planu] Canonical spec identity conflict in project ${projectId}: ${ids.join(', ')}`);
+        this.name = 'DuplicateSpecIdError';
+    }
+}
 // --- internal helpers ---
 function specsFile(projectId) {
     return `${projectDataDir(projectId)}/specs.json`;
@@ -41,8 +50,52 @@ function normalizeSpec(raw) {
     }
     // SPEC-601: Lazy UUID migration — generate if missing
     spec.uuid ??= crypto.randomUUID();
+    if (spec.uuidAliases !== undefined) {
+        spec.uuidAliases = [
+            ...new Set(spec.uuidAliases.filter((alias) => typeof alias === 'string' && alias)),
+        ].sort((left, right) => left.localeCompare(right));
+    }
     return spec;
 }
+/**
+ * Validate the single canonical identity namespace shared by every spec row.
+ * Keep the diagnostic deliberately small: UUIDs and storage paths are private.
+ */
+export function validateCanonicalSpecRows(projectId, specs) {
+    const ids = new Map();
+    const uuids = new Map();
+    const conflicts = new Set();
+    for (const spec of specs) {
+        const priorId = ids.get(spec.id);
+        if (priorId !== undefined) {
+            conflicts.add(spec.id);
+            conflicts.add(priorId);
+        }
+        else {
+            ids.set(spec.id, spec.id);
+        }
+        if (spec.projectId !== projectId) {
+            conflicts.add(spec.id);
+        }
+        const identities = [spec.uuid, ...(spec.uuidAliases ?? [])];
+        for (const identity of identities) {
+            if (typeof identity !== 'string' || identity.length === 0) {
+                continue;
+            }
+            const owner = uuids.get(identity);
+            if (owner !== undefined) {
+                conflicts.add(owner);
+                conflicts.add(spec.id);
+            }
+            else {
+                uuids.set(identity, spec.id);
+            }
+        }
+    }
+    if (conflicts.size > 0) {
+        throw new DuplicateSpecIdError(projectId, [...conflicts]);
+    }
+}
 // Write-through in-memory cache: projectId → Spec[].
 // Populated on first read; invalidated (updated) on every mutation.
 // Eliminates repeated disk I/O for a local single-user MCP server.
@@ -93,6 +146,10 @@ async function withSpecMutationLock(projectId, fn) {
         }
     });
 }
+/** Administrative-only lock boundary for the digest-bound raw-store repair. */
+export async function withCanonicalSpecRepairLock(projectId, fn) {
+    return withSpecMutationLock(projectId, fn);
+}
 /**
  * Load all specs — from cache on subsequent calls, disk only on first access.
  *
@@ -120,12 +177,15 @@ async function loadAll(projectId) {
     }
     const raw = decodeCriticalSchema(persisted, 'spec-store').data;
     const specs = raw.map(normalizeSpec);
+    validateCanonicalSpecRows(projectId, specs);
     specsCache.set(projectId, specs);
     return specs;
 }
 async function saveAll(projectId, specs) {
-    await writeJson(specsFile(projectId), { schemaVersion: 1, data: specs });
-    specsCache.set(projectId, specs);
+    const normalized = specs.map((spec) => normalizeSpec(spec));
+    validateCanonicalSpecRows(projectId, normalized);
+    await writeJson(specsFile(projectId), { schemaVersion: 1, data: normalized });
+    specsCache.set(projectId, normalized);
 }
 /** Evict the cache for a project (e.g. after external file changes). */
 export function invalidateSpecsCache(projectId) {
@@ -160,7 +220,7 @@ export async function getSpecFresh(projectId, specId) {
 /** SPEC-601: Lookup a spec by its globally unique UUID. */
 export async function getSpecByUuid(projectId, uuid) {
     const specs = await loadAll(projectId);
-    return specs.find((s) => s.uuid === uuid) ?? null;
+    return (specs.find((spec) => spec.uuid === uuid || spec.uuidAliases?.includes(uuid) === true) ?? null);
 }
 /**
  * Create a new spec. Throws if a spec with the same ID already exists.
@@ -186,7 +246,12 @@ 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, pendingBackgroundActions = [], expectedSnapshot) {
+function snapshotChanged(spec, expectedSnapshot) {
+    return Boolean(expectedSnapshot &&
+        (spec.status !== expectedSnapshot.status || spec.updatedAt !== expectedSnapshot.updatedAt));
+}
+// eslint-disable-next-line max-lines-per-function -- lifecycle status persistence is one atomic mutation boundary
+async function __internalUpdateSpec(projectId, specId, updates, pendingBackgroundActions = [], expectedSnapshot, transitionRootBinding, reconciliation) {
     return withSpecMutationLock(projectId, async () => {
         const specs = await loadAll(projectId);
         const idx = specs.findIndex((s) => s.id === specId);
@@ -197,9 +262,7 @@ async function __internalUpdateSpec(projectId, specId, updates, pendingBackgroun
         if (!existing) {
             throw new Error(`Spec "${specId}" not found in project "${projectId}"`);
         }
-        if (expectedSnapshot &&
-            (existing.status !== expectedSnapshot.status ||
-                existing.updatedAt !== expectedSnapshot.updatedAt)) {
+        if (snapshotChanged(existing, expectedSnapshot)) {
             throw new Error(`Spec "${specId}" changed after lifecycle gates ran; retry update_status with the fresh state.`);
         }
         const now = new Date().toISOString();
@@ -224,6 +287,8 @@ async function __internalUpdateSpec(projectId, specId, updates, pendingBackgroun
                 fromStatus: existing.status,
                 transitionId,
                 ...(pendingBackgroundActions.length > 0 && { pendingBackgroundActions }),
+                ...(pendingBackgroundActions.length > 0 &&
+                    transitionRootBinding && { transitionRootBinding }),
                 ...(pendingBackgroundActions.length > 0 && {
                     postCommitTasks: pendingBackgroundActions.map((name) => ({
                         name,
@@ -232,6 +297,13 @@ async function __internalUpdateSpec(projectId, specId, updates, pendingBackgroun
                         updatedAt: now,
                     })),
                 }),
+                ...(reconciliation?.reconciliationRequestId
+                    ? {
+                        reconciliationRequestId: reconciliation.reconciliationRequestId,
+                        reconciliationBindingDigest: reconciliation.reconciliationBindingDigest,
+                        trigger: reconciliation.trigger,
+                    }
+                    : {}),
             };
             updatedStatusHistory = [...(existing.statusHistory ?? []), entry];
         }
@@ -257,8 +329,8 @@ async function __internalUpdateSpec(projectId, specId, updates, pendingBackgroun
  * 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, updates = {}, pendingBackgroundActions = [], expectedSnapshot) {
-    return __internalUpdateSpec(projectId, specId, { ...updates, status }, pendingBackgroundActions, expectedSnapshot);
+export async function __internalSetStatus(projectId, specId, status, updates = {}, pendingBackgroundActions = [], expectedSnapshot, transitionRootBinding, reconciliation) {
+    return __internalUpdateSpec(projectId, specId, { ...updates, status }, pendingBackgroundActions, expectedSnapshot, transitionRootBinding, reconciliation);
 }
 /**
  * Restore the exact snapshot captured before a lifecycle transition.
@@ -313,6 +385,21 @@ function isPendingPostCommitTask(task) {
     return (task.status !== 'done' &&
         !(task.status === 'failed' && task.attempts >= MAX_POST_COMMIT_ATTEMPTS));
 }
+function terminalizeExhaustedPostCommitTask(entry, tasks, taskIndex, current, now) {
+    const failedTask = {
+        name: current.name,
+        status: 'failed',
+        attempts: current.attempts,
+        updatedAt: now,
+        ...(current.lastError ? { lastError: current.lastError } : {}),
+    };
+    const nextTasks = tasks.map((task, index) => (index === taskIndex ? failedTask : task));
+    return {
+        ...entry,
+        postCommitTasks: nextTasks,
+        pendingBackgroundActions: nextTasks.filter(isPendingPostCommitTask).map((task) => task.name),
+    };
+}
 function pruneCompletedOutbox(history) {
     let completedOutboxesKept = 0;
     return [...history]
@@ -336,6 +423,7 @@ function pruneCompletedOutbox(history) {
  * Atomically claim one durable post-commit task.
  * Legacy transition receipts are materialized only when the task was explicitly planned.
  */
+// eslint-disable-next-line max-lines-per-function -- claim and exhaustion normalization share one atomic mutation boundary
 export async function claimPostCommitTask(projectId, specId, transitionId, taskName, options = {}) {
     return withSpecMutationLock(projectId, async () => {
         const specs = await loadAll(projectId);
@@ -349,6 +437,7 @@ export async function claimPostCommitTask(projectId, specId, transitionId, taskN
         const claimResult = {
             value: { claimed: false, reason: 'missing' },
         };
+        const normalizedExhausted = { value: false };
         const nextHistory = updateOutboxReceipt(existing.statusHistory, transitionId, (entry) => {
             const tasks = materializePostCommitTasks(entry);
             const taskIndex = tasks.findIndex((task) => task.name === taskName);
@@ -360,10 +449,6 @@ export async function claimPostCommitTask(projectId, specId, transitionId, taskN
                 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) {
@@ -374,6 +459,11 @@ export async function claimPostCommitTask(projectId, specId, transitionId, taskN
                 };
                 return entry;
             }
+            if (current.attempts >= MAX_POST_COMMIT_ATTEMPTS) {
+                claimResult.value = { claimed: false, reason: 'done' };
+                normalizedExhausted.value = true;
+                return terminalizeExhaustedPostCommitTask(entry, tasks, taskIndex, current, now);
+            }
             const executionId = randomUUID();
             const attempts = current.attempts + 1;
             const claimedTask = {
@@ -394,7 +484,7 @@ export async function claimPostCommitTask(projectId, specId, transitionId, taskN
                     .map((task) => task.name),
             };
         });
-        if (!nextHistory || !claimResult.value.claimed) {
+        if (!nextHistory || (!claimResult.value.claimed && !normalizedExhausted.value)) {
             return claimResult.value;
         }
         const updated = { ...existing, statusHistory: nextHistory };

package/dist/storage/status-store/atomic-status-write.d.ts

@@ -0,0 +1,5 @@
+/** Publish one complete canonical status snapshot with same-directory atomic replacement. */
+export declare function atomicStatusWrite(statusPath: string, status: unknown): Promise<void>;
+/** Remove only default atomic-write temporaries whose local owner process is dead. */
+export declare function cleanupDeadStatusTemps(statusPath: string): Promise<number>;
+//# sourceMappingURL=atomic-status-write.d.ts.map