@planu/cli 4.13.0 → 5.0.0

package/dist/storage/schema-registry.d.ts

@@ -0,0 +1,5 @@
+import type { CriticalSchema, VersionedDocument } from '../types/schema-registry.js';
+export declare function registerCriticalSchema<T>(schema: CriticalSchema<T>): void;
+export declare function readCriticalSchema<T>(filePath: string, schemaName: string): Promise<VersionedDocument<T>>;
+export declare function decodeCriticalSchema<T>(parsed: unknown, schemaName: string): VersionedDocument<T>;
+//# sourceMappingURL=schema-registry.d.ts.map

package/dist/storage/schema-registry.js

@@ -0,0 +1,74 @@
+import { readFile } from 'node:fs/promises';
+import { BoundaryFailure, classifyBoundaryFailure } from '../errors/error-taxonomy.js';
+const schemas = new Map();
+export function registerCriticalSchema(schema) {
+    if (!schema.name.trim() ||
+        !Number.isSafeInteger(schema.currentVersion) ||
+        schema.currentVersion < 1) {
+        throw new BoundaryFailure('IncompatibleVersion', 'schema registration', 'Register a named schema with a positive integer version.');
+    }
+    if (schemas.has(schema.name)) {
+        const existing = schemas.get(schema.name);
+        if (existing === schema) {
+            return;
+        }
+        throw new BoundaryFailure('Conflict', 'schema registration', `Schema ${schema.name} is already registered and cannot be replaced.`);
+    }
+    schemas.set(schema.name, schema);
+}
+export async function readCriticalSchema(filePath, schemaName) {
+    const schema = schemas.get(schemaName);
+    if (!schema) {
+        throw new BoundaryFailure('IncompatibleVersion', 'critical schema read', `Register schema ${schemaName} before reading persistent state.`);
+    }
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        const failure = classifyBoundaryFailure(error, `read ${schema.name}`, 'Restore access to the state file or initialize it if it does not exist.');
+        if (failure.kind === 'NotFound') {
+            return { schemaVersion: schema.currentVersion, data: schema.createDefault() };
+        }
+        throw failure;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new BoundaryFailure('Corrupt', `read ${schema.name}`, 'Recover the original file; Planu will not replace corrupt state with defaults.');
+    }
+    return decodeCriticalSchema(parsed, schemaName);
+}
+export function decodeCriticalSchema(parsed, schemaName) {
+    const schema = schemas.get(schemaName);
+    if (!schema) {
+        throw new BoundaryFailure('IncompatibleVersion', 'critical schema decode', `Register schema ${schemaName} before decoding persistent state.`);
+    }
+    const isEnvelope = parsed !== null && typeof parsed === 'object' && 'schemaVersion' in parsed && 'data' in parsed;
+    const document = isEnvelope
+        ? parsed
+        : { schemaVersion: 0, data: parsed };
+    if (typeof document.schemaVersion !== 'number' || !Number.isSafeInteger(document.schemaVersion)) {
+        throw new BoundaryFailure('Corrupt', `read ${schema.name}`, 'Recover a versioned document.');
+    }
+    if (document.schemaVersion > schema.currentVersion || document.schemaVersion < 0) {
+        throw new BoundaryFailure('IncompatibleVersion', `read ${schema.name}`, `Use a Planu runtime compatible with schema version ${String(document.schemaVersion)}.`);
+    }
+    let data;
+    try {
+        data =
+            document.schemaVersion === schema.currentVersion
+                ? document.data
+                : schema.migrate?.(document.data, document.schemaVersion);
+    }
+    catch {
+        throw new BoundaryFailure('IncompatibleVersion', `migrate ${schema.name}`, `Use a supported migration path to schema version ${String(schema.currentVersion)}.`);
+    }
+    if (data === undefined || !schema.validate(data)) {
+        throw new BoundaryFailure('Corrupt', `read ${schema.name}`, 'Recover state that satisfies the registered schema; no overwrite was performed.');
+    }
+    return { schemaVersion: schema.currentVersion, data };
+}
+//# sourceMappingURL=schema-registry.js.map

package/dist/storage/sentry-store.js

@@ -1,22 +1,33 @@
+import { technologyValue } from '../engine/technology-registry.js';
 // storage/sentry-store.ts — Sentry integration persistence (SPEC-435)
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { safeJsonParse } from './base-store.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { hashProjectPath, projectDataDir, safeJsonParse } from './base-store.js';
+import { resolveSecretField, storeSecretField } from '../security/secret-field.js';
 function sentryConfigPath(projectPath) {
-    return join(projectPath, 'data', 'sentry', 'config.json');
+    return join(projectDataDir(hashProjectPath(projectPath)), technologyValue('technology-sentry-0cf685'), 'config.json');
 }
 export async function getSentryConfig(projectPath) {
     try {
         const raw = await readFile(sentryConfigPath(projectPath), 'utf-8');
-        return safeJsonParse(raw, null);
+        const config = safeJsonParse(raw, null);
+        return config ? { ...config, authToken: await resolveSecretField(config.authToken) } : null;
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error.code === 'ENOENT' ||
+            (error instanceof Error && error.message === 'ENOENT')) {
+            return null;
+        }
+        throw error;
     }
 }
 export async function saveSentryConfig(projectPath, config) {
     const filePath = sentryConfigPath(projectPath);
-    await mkdir(dirname(filePath), { recursive: true });
-    await writeFile(filePath, JSON.stringify(config, null, 2), 'utf-8');
+    const authToken = await storeSecretField(`${hashProjectPath(projectPath)}/sentry/auth`, 'sentry-auth', config.authToken);
+    await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+    await writeFile(filePath, JSON.stringify({ ...config, authToken }, null, 2), {
+        encoding: 'utf-8',
+        mode: 0o600,
+    });
 }
 //# sourceMappingURL=sentry-store.js.map

package/dist/storage/session-state-store.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { getUniqueTopLevelFrontmatterString } from '../engine/frontmatter-parser.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -35,7 +36,9 @@ export function getStagedFiles(projectPath) {
             .map((f) => f.trim())
             .filter((f) => f.length > 0);
     }
-    catch {
+    catch (error) {
+        // reliability-optional: GIT_SESSION_FILE_LIST — filesystem fallback runs next
+        reportClassifiedDegradation('GIT_SESSION_FILE_LIST', error);
         return [];
     }
 }
@@ -58,14 +61,18 @@ export async function getActiveSpecIds(projectPath) {
                     active.add(match[0]);
                 }
             }
-            catch {
-                // A single unreadable candidate must not suppress other valid active specs.
+            catch (error) {
+                // reliability-compat: UNREADABLE_SPEC_CANDIDATE — preserve other valid active specs
+                reportClassifiedDegradation('UNREADABLE_SPEC_CANDIDATE', error);
             }
         }
         return [...active];
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
     }
 }
 // ---------------------------------------------------------------------------

package/dist/storage/skill-registry-storage.d.ts

@@ -1,6 +1,6 @@
 import type { SkillSource, SkillRegistryEntry, SkillRegistry } from '../types/skill-registry.js';
 export type { SkillSource, SkillRegistryEntry, SkillRegistry };
-export declare const REGISTRY_RELATIVE_PATH = ".planu/skill-registry.json";
+export declare const REGISTRY_RELATIVE_PATH = "planu/skill-registry.json";
 export declare const DEFAULT_TTL_DAYS = 30;
 export declare const ALL_SKILL_SOURCES: SkillSource[];
 /**

package/dist/storage/skill-registry-storage.js

@@ -3,14 +3,13 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { withFileLock } from './file-mutex.js';
-import { safeJsonParse } from './base-store.js';
 function isValidRegistry(parsed) {
     return (parsed !== null && typeof parsed === 'object' && 'installed' in parsed && 'sources' in parsed);
 }
 // ---------------------------------------------------------------------------
 // Configuration constants (no hardcodes in function bodies)
 // ---------------------------------------------------------------------------
-export const REGISTRY_RELATIVE_PATH = '.planu/skill-registry.json';
+export const REGISTRY_RELATIVE_PATH = 'planu/skill-registry.json';
 export const DEFAULT_TTL_DAYS = 30;
 export const ALL_SKILL_SOURCES = ['superpowers', 'anthropic', 'local', 'community'];
 // ---------------------------------------------------------------------------
@@ -41,14 +40,15 @@ export async function readSkillRegistry(projectPath) {
     try {
         raw = await readFile(filePath, 'utf-8');
     }
-    catch {
-        // File does not exist
-        return emptyRegistry();
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return emptyRegistry();
+        }
+        throw error;
     }
-    const parsed = safeJsonParse(raw, null);
+    const parsed = JSON.parse(raw);
     if (!isValidRegistry(parsed)) {
-        console.warn(`[skill-registry] Corrupted registry at ${filePath} — falling back to empty`);
-        return emptyRegistry();
+        throw new Error(`Skill registry is corrupt: ${filePath}`);
     }
     return parsed;
 }
@@ -79,7 +79,7 @@ export async function writeSkillRegistryEntry(projectPath, entry) {
         let registry;
         try {
             const raw = await readFile(filePath, 'utf-8');
-            const parsed = safeJsonParse(raw, null);
+            const parsed = JSON.parse(raw);
             if (isValidRegistry(parsed)) {
                 registry = parsed;
             }
@@ -87,8 +87,10 @@ export async function writeSkillRegistryEntry(projectPath, entry) {
                 throw new Error('invalid');
             }
         }
-        catch {
-            // Missing or corrupt — start fresh
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
             const now = new Date().toISOString();
             registry = {
                 createdAt: now,

package/dist/storage/slack-store.js

@@ -1,14 +1,16 @@
 // storage/slack-store.ts — Slack integration persistence (SPEC-292)
 import { join } from 'node:path';
-import { hashProjectPath, readJson, writeJson } from './base-store.js';
+import { hashProjectPath, projectDataDir, readJson, writeJson } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+import { deleteSecretField, resolveSecretField, storeSecretField, } from '../security/secret-field.js';
+import { writeSecureJson } from '../security/secure-json.js';
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
 const MAX_DELIVERIES = 20;
 function getProjectDir(projectPath) {
     const hash = hashProjectPath(projectPath);
-    return join('data', 'projects', hash);
+    return projectDataDir(hash);
 }
 function getConfigPath(projectPath) {
     return join(getProjectDir(projectPath), 'slack-config.json');
@@ -24,19 +26,22 @@ function getDeliveryLogPath(projectPath) {
  */
 export async function getSlackConfig(projectPath) {
     const config = await readJson(getConfigPath(projectPath), null);
-    return config;
+    return config ? { ...config, webhookUrl: await resolveSecretField(config.webhookUrl) } : null;
 }
 /**
  * Persist the Slack config for a project.
  */
 export async function saveSlackConfig(projectPath, config) {
-    await writeJson(getConfigPath(projectPath), config);
+    const webhookUrl = await storeSecretField(`${hashProjectPath(projectPath)}/slack/webhook`, 'slack-webhook', config.webhookUrl);
+    await writeSecureJson(getConfigPath(projectPath), { ...config, webhookUrl });
 }
 /**
  * Remove the Slack config for a project.
  */
 export async function removeSlackConfig(projectPath) {
-    await writeJson(getConfigPath(projectPath), null);
+    const config = await readJson(getConfigPath(projectPath), null);
+    await deleteSecretField(config?.webhookUrl);
+    await writeSecureJson(getConfigPath(projectPath), null);
 }
 /**
  * Read the last N delivery log entries for a project.

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

@@ -1,7 +1,8 @@
-import { readCriticalJson, readJson, writeJson, projectDataDir } from './base-store.js';
-import { migrateLegacyDataDir } from './migrations/cwd-to-absolute.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+import { CriticalJsonReadError, readCriticalJson, readJson, writeJson, projectDataDir, } from './base-store.js';
+import { decodeCriticalSchema, registerCriticalSchema } from './schema-registry.js';
+import { BoundaryFailure } from '../errors/error-taxonomy.js';
 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';
@@ -21,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`;
@@ -40,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.
@@ -52,16 +106,27 @@ 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;
+registerCriticalSchema({
+    name: 'spec-store',
+    currentVersion: 1,
+    createDefault: () => [],
+    validate: (value) => Array.isArray(value),
+    migrate: (value, fromVersion) => {
+        if (fromVersion === 0 && Array.isArray(value)) {
+            return value;
+        }
+        throw new Error('[Planu] Unsupported spec-store schema migration');
+    },
+});
 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, {
+        let handle = await acquireLock(projectId, 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, {
+            handle = await acquireLock(projectId, STORE_LOCK_ID, {
                 reason: `spec-store mutation for ${projectId}`,
             });
         }
@@ -75,14 +140,16 @@ async function withSpecMutationLock(projectId, 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),
-                });
+                // reliability-cleanup: SPEC_MUTATION_LOCK_RELEASE — mutation outcome is already durable
+                reportClassifiedDegradation('SPEC_MUTATION_LOCK_RELEASE', error);
             });
         }
     });
 }
+/** 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.
  *
@@ -96,29 +163,29 @@ async function loadAll(projectId) {
     if (cached !== undefined) {
         return cached;
     }
-    // SPEC-1007: migrate legacy <cwd>/data/projects/{id} to absolute home once.
-    await migrateLegacyDataDir(projectId);
     const directFile = specsFile(projectId);
-    let raw = await readCriticalJson(directFile, [], {
-        validate: (value) => Array.isArray(value),
-        expectedDescription: 'an array of specs',
-    });
-    if (raw.length === 0) {
-        const discovered = await discoverProjectDataFile(projectId, 'specs.json');
-        if (discovered !== null && discovered !== directFile) {
-            raw = await readCriticalJson(discovered, [], {
-                validate: (value) => Array.isArray(value),
-                expectedDescription: 'an array of specs',
-            });
+    let persisted;
+    try {
+        persisted = await readCriticalJson(directFile, []);
+    }
+    catch (error) {
+        if (error instanceof CriticalJsonReadError) {
+            const cause = new BoundaryFailure('Corrupt', 'critical JSON parse', 'The persisted bytes did not contain a valid JSON document.');
+            throw new BoundaryFailure('Corrupt', 'read spec-store', 'Recover specs.json; Planu will not replace corrupt state with defaults.', cause);
         }
+        throw error;
     }
+    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), 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) {
@@ -153,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.
@@ -179,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);
@@ -190,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();
@@ -217,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,
@@ -225,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];
         }
@@ -250,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.
@@ -306,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]
@@ -329,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);
@@ -342,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);
@@ -353,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) {
@@ -367,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 = {
@@ -387,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