fullstackgtm 0.48.0 → 0.49.0

package/dist/mcp.js

@@ -158,12 +158,19 @@ const toolDefinitions = [
         },
         handler: async ({ provider, inputPath, configPath, rules, output, today, staleDealDays }) => {
             const loaded = configPath ? loadConfig(configPath) : null;
+            if (loaded?.config.rulePackages?.length) {
+                throw new Error("MCP refuses executable rulePackages from tool-call configPath. " +
+                    "MCP plugin execution is disabled because mutable tool-call paths are not a durable code-trust boundary. " +
+                    "Run reviewed plugins through the CLI with --config <path> --allow-plugins instead.");
+            }
             const policy = mergePolicy(defaultPolicy(today), loaded?.config);
             if (today)
                 policy.today = today;
             if (staleDealDays !== undefined)
                 policy.staleDealDays = staleDealDays;
-            const ruleSet = await resolveConfiguredRules(loaded);
+            const ruleSet = await resolveConfiguredRules(loaded, undefined, {
+                disableRulePackages: true,
+            });
             const selected = rules?.length
                 ? ruleSet.filter((rule) => rules.includes(rule.id))
                 : ruleSet;
@@ -273,122 +280,79 @@ const toolDefinitions = [
         writesCrm: true,
         config: {
             title: "Apply Approved Patch Operations",
-            description: "Apply explicitly approved operations from a patch plan through a provider " +
-                "connector. Operations not listed in approvedOperationIds are never written, " +
-                "and requires_human_* placeholders need a value override. When the plan is in " +
-                "the local plan store (saved via `audit --save`), approvals are verified against " +
-                "the store's HMAC approval digests — ids not approved with `plans approve` are " +
-                "refused — and the run is recorded onto the stored plan so `plans show` and " +
+            description: "Apply a stored, human-approved patch plan through a provider connector. The plan, " +
+                "approved operation ids, and concrete placeholder values are loaded exclusively from " +
+                "the local plan store and verified against its HMAC approval digests. Callers cannot " +
+                "supply or widen approvals. Every apply run is recorded so `plans show` and " +
                 "`audit-log export` include it.",
             inputSchema: strictSchema({
                 provider: z.enum(["hubspot", "salesforce"]),
-                planPath: z.string(),
-                approvedOperationIds: z.array(z.string()).min(1),
-                valueOverrides: z.record(z.string(), z.string()).optional(),
+                planId: z.string().regex(/^[\w.-]+$/),
                 output: z.enum(["json", "markdown"]).optional(),
             }),
         },
-        handler: async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
-            // The file may be a raw PatchPlan (audit --out) or a StoredPlan envelope
-            // (a file straight out of the plan-store directory).
-            const parsed = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8"));
-            const filePlan = isStoredPlanFile(parsed) ? parsed.plan : parsed;
-            if (!filePlan || !Array.isArray(filePlan.operations)) {
-                throw new Error(`${planPath} is not a patch plan (expected { id, operations: [...] }).`);
-            }
-            // Governance parity with CLI apply: when this plan id exists in the local
-            // plan store, the STORE is the source of truth — the approved-id set must
-            // come from `plans approve` (which HMAC-signed each approved op), the
-            // signatures are re-verified here, and the run is recorded back onto the
-            // plan so audit-log export sees MCP applies exactly like CLI applies.
+        handler: async ({ provider, planId, output }) => {
+            // The store is the only authority accepted over MCP. In particular, do
+            // not accept a plan body/path, approval ids, or value overrides from the
+            // agent call: combining proposal and approval in one call defeats the
+            // human approval boundary the plan lifecycle is meant to enforce.
             const store = createFilePlanStore();
-            const stored = typeof filePlan.id === "string" && /^[\w.-]+$/.test(filePlan.id)
-                ? await store.get(filePlan.id)
-                : null;
-            let plan;
-            let effectiveOverrides;
-            if (stored) {
-                if (stored.status !== "approved") {
-                    throw new Error(`Plan ${filePlan.id} is ${stored.status}; approve operations first with ` +
-                        `\`fullstackgtm plans approve ${filePlan.id} --operations <ids|all>\`.`);
-                }
-                // Downgrade guard (same as CLI apply): an approved plan with no
-                // signatures either predates 0.26 or had approvalDigests stripped to
-                // skip the integrity check. Refuse rather than trust the file.
-                if (stored.approvedOperationIds.length > 0 && !stored.approvalDigests) {
-                    throw new Error(`Refusing to apply plan ${filePlan.id}: it was approved without integrity signatures ` +
-                        "(approved before 0.26.0, or its signatures were removed). Re-approve it with " +
-                        `\`fullstackgtm plans approve ${filePlan.id} --operations <ids|all>\`.`);
-                }
-                // Never widen: every id the tool wants applied must already be
-                // store-approved. (A subset is fine — narrowing never writes more.)
-                const storeApproved = new Set(stored.approvedOperationIds);
-                const unapproved = approvedOperationIds.filter((id) => !storeApproved.has(id));
-                if (unapproved.length > 0) {
-                    throw new Error(`Refusing to apply plan ${filePlan.id}: operation(s) ${unapproved.join(", ")} were never ` +
-                        "approved in the plan store. Approve them first with " +
-                        `\`fullstackgtm plans approve ${filePlan.id} --operations <ids>\`.`);
-                }
-                // Integrity gate: verify against the EFFECTIVE overrides (stored ∪ tool
-                // args), so a tool-supplied value that changes what the human approved
-                // is treated as tamper, not a live override — what gets written must
-                // equal what was signed.
-                effectiveOverrides = { ...stored.valueOverrides, ...(valueOverrides ?? {}) };
-                const verification = verifyApprovalDigests(stored.plan.operations, stored.approvedOperationIds, effectiveOverrides, stored.approvalDigests);
-                if (!verification.ok) {
-                    const detail = verification.reason === "no_key"
-                        ? "the plan-signing key is missing (was this plan approved on another machine?). Re-approve it here with `fullstackgtm plans approve`."
-                        : `these operations differ from what was approved: ${verification.tampered.join(", ")}. ` +
-                            "If you want a different value, set it at approval (`plans approve --value <op>=<v>`) and re-approve; " +
-                            "otherwise the plan was edited after approval — review and re-approve.";
-                    throw new Error(`Refusing to apply plan ${filePlan.id}: ${detail}`);
-                }
-                plan = stored.plan; // apply what was signed, not what the file says now
+            const stored = await store.get(planId);
+            if (!stored) {
+                throw new Error(`No stored plan with id ${planId}. Save it with \`fullstackgtm audit --save\`, then approve it with \`fullstackgtm plans approve\`.`);
             }
-            else {
-                // External plan file, not in the store: no digests exist to verify, but
-                // approvals must still reference real operations in the plan content.
-                plan = filePlan;
-                const known = new Set(plan.operations.map((operation) => operation.id));
-                const unknown = approvedOperationIds.filter((id) => !known.has(id));
-                if (unknown.length > 0) {
-                    throw new Error(`Plan ${planPath} has no operation(s) ${unknown.join(", ")} — approvedOperationIds ` +
-                        "must reference operations in the plan.");
-                }
-                effectiveOverrides = valueOverrides ?? {};
+            if (stored.status !== "approved") {
+                throw new Error(`Plan ${planId} is ${stored.status}; approve operations first with ` +
+                    `\`fullstackgtm plans approve ${planId} --operations <ids|all>\`.`);
             }
-            const run = await applyPatchPlan(await connectorFor(provider), plan, {
-                approvedOperationIds,
-                valueOverrides: effectiveOverrides,
-            });
-            // Persist the run (same data the CLI records) so runs[] and plan status
-            // update and audit-log export includes MCP applies. External plan files
-            // have no store entry to update — say so instead of silently dropping it.
-            let runRecorded = false;
-            if (stored) {
-                await store.recordRun(plan.id, run);
-                runRecorded = true;
+            if (stored.approvedOperationIds.length === 0) {
+                throw new Error(`Plan ${planId} has no approved operations.`);
+            }
+            if (!stored.approvalDigests) {
+                throw new Error(`Refusing to apply plan ${planId}: it was approved without integrity signatures ` +
+                    "(approved before 0.26.0, or its signatures were removed). Re-approve it with " +
+                    `\`fullstackgtm plans approve ${planId} --operations <ids|all>\`.`);
+            }
+            const verification = verifyApprovalDigests(stored.plan.operations, stored.approvedOperationIds, stored.valueOverrides, stored.approvalDigests);
+            if (!verification.ok) {
+                const detail = verification.reason === "no_key"
+                    ? "the plan-signing key is missing (was this plan approved on another machine?). Re-approve it here with `fullstackgtm plans approve`."
+                    : `these operations differ from what was approved: ${verification.tampered.join(", ")}. ` +
+                        "The stored plan or approved values changed after approval — review and re-approve.";
+                throw new Error(`Refusing to apply plan ${planId}: ${detail}`);
             }
+            const connector = await connectorFor(provider);
+            // Claim only after all preflight checks and credential resolution. The
+            // atomic store transition prevents a second CLI/MCP process from
+            // applying the same approval concurrently.
+            const claimed = await store.claimApply(planId, { provider, source: "mcp" });
+            const claimedVerification = verifyApprovalDigests(claimed.stored.plan.operations, claimed.stored.approvedOperationIds, claimed.stored.valueOverrides, claimed.stored.approvalDigests);
+            if (!claimedVerification.ok) {
+                await store.abortApplyPreflight(planId, claimed.claimId, "Approval integrity verification failed after the claim and before provider I/O.");
+                throw new Error(`Refusing to apply plan ${planId}: the claimed plan differs from what was approved: ` +
+                    `${claimedVerification.tampered.join(", ") || "signing key unavailable"}.`);
+            }
+            let run;
+            try {
+                run = await applyPatchPlan(connector, claimed.stored.plan, {
+                    approvedOperationIds: claimed.stored.approvedOperationIds,
+                    valueOverrides: claimed.stored.valueOverrides,
+                });
+            }
+            catch (error) {
+                await store.markApplyUncertain(planId, claimed.claimId);
+                throw error;
+            }
+            await store.recordRun(claimed.stored.plan.id, run, claimed.claimId);
             const governance = {
-                planSource: stored ? "store" : "external",
-                approvalDigestsVerified: stored !== null,
-                runRecorded,
-                ...(stored
-                    ? {}
-                    : {
-                        note: "Plan file is not in the local plan store: approvals came from tool arguments " +
-                            "(verified against the plan content only — no approval-digest check) and the run " +
-                            "was not recorded. Use `fullstackgtm audit --save` + `plans approve` for " +
-                            "store-backed governance.",
-                    }),
+                planSource: "store",
+                approvalDigestsVerified: true,
+                runRecorded: true,
             };
             if (output === "markdown") {
                 return content(`${formatPatchPlanRun(run)}\n\nGovernance: plan source ${governance.planSource}; ` +
-                    (runRecorded
-                        ? "approval digests verified; run recorded on the stored plan (audit-log export includes it)."
-                        : governance.note));
+                    "approval digests verified; run recorded on the stored plan (audit-log export includes it).");
             }
-            // Backward compatible: the run's own fields stay top-level; governance is additive.
             return content({ ...run, governance });
         },
     },
@@ -470,7 +434,7 @@ toolDefinitions.unshift({
             writesCrm,
         })),
         safety: "Only tools flagged writesCrm can reach a CRM; fullstackgtm_apply writes only operations " +
-            "listed in approvedOperationIds and never writes requires_human_* placeholders without a value override.",
+            "from a stored plan whose ids and values were human-approved and HMAC-verified.",
         server: { command: "npx -y fullstackgtm-mcp" },
         cli: {
             command: "npx fullstackgtm <command> [--json]",
@@ -497,18 +461,6 @@ export async function startMcpServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-/**
- * A plan-store file is a StoredPlan envelope ({ plan, status, runs, ... });
- * `audit --out` writes a bare PatchPlan. fullstackgtm_apply accepts either.
- */
-function isStoredPlanFile(value) {
-    if (typeof value !== "object" || value === null || !("plan" in value))
-        return false;
-    const plan = value.plan;
-    return (typeof plan === "object" &&
-        plan !== null &&
-        Array.isArray(plan.operations));
-}
 function loadMarketConfigOrHint(path) {
     try {
         return loadMarketConfig(path);

package/dist/planStore.d.ts

@@ -17,17 +17,44 @@ export type StoredPlan = {
      * file is caught instead of written. Absent on plans approved before 0.26.0.
      */
     approvalDigests?: Record<string, string>;
+    /** Monotonic store revision used to make lifecycle changes explicit. */
+    revision: number;
+    /** Present only while one process owns the right to apply this plan. */
+    applyClaim?: {
+        id: string;
+        claimedAt: string;
+        revision: number;
+    };
+    /** Durable journal of apply ownership. An unresolved entry must never be replayed automatically. */
+    applyAttempts?: ApplyAttempt[];
     runs: PatchPlanRun[];
     createdAt: string;
     updatedAt: string;
 };
+export type ApplyAttempt = {
+    id: string;
+    claimedAt: string;
+    provider: string;
+    source: "cli" | "fix" | "mcp";
+    status: "in_progress" | "preflight_aborted" | "completed" | "uncertain";
+    resolvedAt?: string;
+    /** Deliberately generic: provider errors can contain CRM data or credentials. */
+    note?: string;
+};
 export interface PlanStore {
     save(plan: PatchPlan): Promise<StoredPlan>;
     get(planId: string): Promise<StoredPlan | null>;
     list(status?: ApprovalStatus): Promise<StoredPlan[]>;
     approveOperations(planId: string, operationIds: string[], valueOverrides?: Record<string, unknown>): Promise<StoredPlan>;
     reject(planId: string): Promise<StoredPlan>;
-    recordRun(planId: string, run: PatchPlanRun): Promise<StoredPlan>;
+    claimApply(planId: string, metadata?: Pick<ApplyAttempt, "provider" | "source">): Promise<{
+        stored: StoredPlan;
+        claimId: string;
+    }>;
+    recordRun(planId: string, run: PatchPlanRun, claimId: string): Promise<StoredPlan>;
+    abortApplyPreflight(planId: string, claimId: string, note: string): Promise<StoredPlan>;
+    markApplyUncertain(planId: string, claimId: string): Promise<StoredPlan>;
+    recoverApply(planId: string): Promise<StoredPlan>;
 }
 /**
  * Plans as JSON files in a directory (default `$FSGTM_HOME/plans`), one file

package/dist/planStore.js

@@ -1,7 +1,9 @@
-import { chmodSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { chmodSync, closeSync, mkdirSync, openSync, readdirSync, unlinkSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
 import { computeApprovalDigests, loadOrCreateSigningKey } from "./integrity.js";
+import { assertNoSymlinkComponents, readSecureRegularFile, UnsafeManagedPathError } from "./secureFile.js";
 /**
  * Plans as JSON files in a directory (default `$FSGTM_HOME/plans`), one file
  * per plan id. Filesystem-shaped on purpose: greppable, diffable, and any
@@ -9,6 +11,11 @@ import { computeApprovalDigests, loadOrCreateSigningKey } from "./integrity.js";
  */
 export function createFilePlanStore(directory) {
     const dir = directory ?? join(credentialsDir(), "plans");
+    function ensurePlanDirectory() {
+        assertNoSymlinkComponents(dir);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        assertNoSymlinkComponents(dir);
+    }
     function pathFor(planId) {
         if (!/^[\w.-]+$/.test(planId))
             throw new Error(`Invalid plan id: ${planId}`);
@@ -16,9 +23,12 @@ export function createFilePlanStore(directory) {
     }
     function read(planId) {
         try {
-            return JSON.parse(readFileSync(pathFor(planId), "utf8"));
+            assertNoSymlinkComponents(dir);
+            return JSON.parse(readSecureRegularFile(pathFor(planId)));
         }
-        catch {
+        catch (error) {
+            if (error instanceof UnsafeManagedPathError)
+                throw error;
             return null;
         }
     }
@@ -29,14 +39,18 @@ export function createFilePlanStore(directory) {
         // directory world-readable.
         if (!directory)
             ensureSecureHomeDir();
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        ensurePlanDirectory();
         try {
             chmodSync(dir, 0o700);
         }
         catch {
             // Non-POSIX filesystems ignore chmod.
         }
-        const next = { ...stored, updatedAt: new Date().toISOString() };
+        const next = {
+            ...stored,
+            revision: (stored.revision ?? 0) + 1,
+            updatedAt: new Date().toISOString(),
+        };
         writeSecureFile(pathFor(stored.plan.id), `${JSON.stringify(next, null, 2)}\n`);
         return next;
     }
@@ -46,23 +60,56 @@ export function createFilePlanStore(directory) {
             throw new Error(`No stored plan with id ${planId}.`);
         return stored;
     }
+    function withPlanLock(planId, action) {
+        ensurePlanDirectory();
+        const lockPath = `${pathFor(planId)}.lock`;
+        let fd;
+        try {
+            fd = openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "unknown";
+            if (code === "EEXIST") {
+                throw new Error(`Plan ${planId} is being updated by another process; retry after it finishes.`);
+            }
+            throw error;
+        }
+        try {
+            return action();
+        }
+        finally {
+            closeSync(fd);
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* a missing lock is already released */ }
+        }
+    }
     return {
         async save(plan) {
-            const now = new Date().toISOString();
-            return write({
-                plan,
-                status: plan.status,
-                approvedOperationIds: [],
-                valueOverrides: {},
-                runs: [],
-                createdAt: now,
-                updatedAt: now,
+            return withPlanLock(plan.id, () => {
+                const existing = read(plan.id);
+                if (existing && ["approved", "applying", "applied"].includes(existing.status)) {
+                    throw new Error(`Plan ${plan.id} is already ${existing.status}; refusing to replace its approval or apply history.`);
+                }
+                const now = new Date().toISOString();
+                return write({
+                    plan,
+                    status: plan.status,
+                    approvedOperationIds: [],
+                    valueOverrides: {},
+                    revision: 0,
+                    runs: [],
+                    createdAt: now,
+                    updatedAt: now,
+                });
             });
         },
         async get(planId) {
             return read(planId);
         },
         async list(status) {
+            assertNoSymlinkComponents(dir);
             let entries = [];
             try {
                 entries = readdirSync(dir);
@@ -78,46 +125,145 @@ export function createFilePlanStore(directory) {
             return status ? plans.filter((stored) => stored.status === status) : plans;
         },
         async approveOperations(planId, operationIds, valueOverrides = {}) {
-            const stored = mustRead(planId);
-            if (stored.status === "applied") {
-                throw new Error(`Plan ${planId} has already been applied.`);
-            }
-            if (stored.status === "rejected") {
-                throw new Error(`Plan ${planId} was rejected; re-run the audit for a fresh plan.`);
-            }
-            const known = new Set(stored.plan.operations.map((operation) => operation.id));
-            for (const operationId of operationIds) {
-                if (!known.has(operationId)) {
-                    throw new Error(`Plan ${planId} has no operation ${operationId}.`);
+            return withPlanLock(planId, () => {
+                const stored = mustRead(planId);
+                if (stored.status === "applied") {
+                    throw new Error(`Plan ${planId} has already been applied.`);
                 }
-            }
-            const approvedOperationIds = Array.from(new Set([...stored.approvedOperationIds, ...operationIds]));
-            const mergedOverrides = { ...stored.valueOverrides, ...valueOverrides };
-            // Bind the approval to the operation content so apply can detect a
-            // post-approval edit. Recompute over ALL approved ops (a later approve
-            // call may add overrides that change an earlier op's resolved value).
-            const approvalDigests = computeApprovalDigests(stored.plan.operations, approvedOperationIds, mergedOverrides, loadOrCreateSigningKey());
-            return write({
-                ...stored,
-                status: "approved",
-                approvedOperationIds,
-                valueOverrides: mergedOverrides,
-                approvalDigests,
+                if (stored.status === "rejected") {
+                    throw new Error(`Plan ${planId} was rejected; re-run the audit for a fresh plan.`);
+                }
+                if (stored.status === "applying" || stored.applyClaim) {
+                    throw new Error(`Plan ${planId} is applying; approvals are frozen until the attempt is resolved.`);
+                }
+                const known = new Set(stored.plan.operations.map((operation) => operation.id));
+                for (const operationId of operationIds) {
+                    if (!known.has(operationId)) {
+                        throw new Error(`Plan ${planId} has no operation ${operationId}.`);
+                    }
+                }
+                const approvedOperationIds = Array.from(new Set([...stored.approvedOperationIds, ...operationIds]));
+                const mergedOverrides = { ...stored.valueOverrides, ...valueOverrides };
+                // Bind the approval to the operation content so apply can detect a
+                // post-approval edit. Recompute over ALL approved ops (a later approve
+                // call may add overrides that change an earlier op's resolved value).
+                const approvalDigests = computeApprovalDigests(stored.plan.operations, approvedOperationIds, mergedOverrides, loadOrCreateSigningKey());
+                return write({
+                    ...stored,
+                    status: "approved",
+                    approvedOperationIds,
+                    valueOverrides: mergedOverrides,
+                    approvalDigests,
+                });
             });
         },
         async reject(planId) {
-            const stored = mustRead(planId);
-            if (stored.status === "applied") {
-                throw new Error(`Plan ${planId} has already been applied.`);
-            }
-            return write({ ...stored, status: "rejected", approvedOperationIds: [] });
+            return withPlanLock(planId, () => {
+                const stored = mustRead(planId);
+                if (stored.status === "applied") {
+                    throw new Error(`Plan ${planId} has already been applied.`);
+                }
+                if (stored.status === "applying" || stored.applyClaim) {
+                    throw new Error(`Plan ${planId} is applying and cannot be rejected until the attempt is resolved.`);
+                }
+                return write({ ...stored, status: "rejected", approvedOperationIds: [], applyClaim: undefined });
+            });
+        },
+        async claimApply(planId, metadata) {
+            return withPlanLock(planId, () => {
+                const stored = mustRead(planId);
+                if (stored.status === "applying" || stored.applyClaim) {
+                    throw new Error(`Plan ${planId} is already applying; inspect its recorded attempts before any retry.`);
+                }
+                if (stored.status !== "approved") {
+                    throw new Error(`Plan ${planId} is ${stored.status}; only an approved plan can be claimed for apply.`);
+                }
+                const claimId = randomUUID();
+                const claimedAt = new Date().toISOString();
+                const claimed = write({
+                    ...stored,
+                    status: "applying",
+                    applyClaim: {
+                        id: claimId,
+                        claimedAt,
+                        revision: stored.revision ?? 0,
+                    },
+                    applyAttempts: [...(stored.applyAttempts ?? []), {
+                            id: claimId,
+                            claimedAt,
+                            provider: metadata?.provider ?? "unknown",
+                            source: metadata?.source ?? "cli",
+                            status: "in_progress",
+                        }],
+                });
+                return { stored: claimed, claimId };
+            });
         },
-        async recordRun(planId, run) {
-            const stored = mustRead(planId);
-            return write({
-                ...stored,
-                status: run.status === "applied" || run.status === "partial" ? "applied" : stored.status,
-                runs: [...stored.runs, run],
+        async recordRun(planId, run, claimId) {
+            return withPlanLock(planId, () => {
+                const stored = mustRead(planId);
+                if (stored.status !== "applying" || stored.applyClaim?.id !== claimId) {
+                    throw new Error(`Refusing to record run for plan ${planId}: apply claim is missing or does not match.`);
+                }
+                return write({
+                    ...stored,
+                    status: run.status === "applied" || run.status === "partial" ? "applied" : "approved",
+                    applyClaim: undefined,
+                    applyAttempts: (stored.applyAttempts ?? []).map((attempt) => attempt.id === claimId
+                        ? { ...attempt, status: "completed", resolvedAt: new Date().toISOString() }
+                        : attempt),
+                    runs: [...stored.runs, run],
+                });
+            });
+        },
+        async abortApplyPreflight(planId, claimId, note) {
+            return withPlanLock(planId, () => {
+                const stored = mustRead(planId);
+                if (stored.status !== "applying" || stored.applyClaim?.id !== claimId) {
+                    throw new Error(`Refusing to abort preflight for plan ${planId}: apply claim is missing or does not match.`);
+                }
+                return write({
+                    ...stored,
+                    status: "approved",
+                    applyClaim: undefined,
+                    applyAttempts: (stored.applyAttempts ?? []).map((attempt) => attempt.id === claimId
+                        ? { ...attempt, status: "preflight_aborted", resolvedAt: new Date().toISOString(), note }
+                        : attempt),
+                });
+            });
+        },
+        async markApplyUncertain(planId, claimId) {
+            return withPlanLock(planId, () => {
+                const stored = mustRead(planId);
+                if (stored.status !== "applying" || stored.applyClaim?.id !== claimId)
+                    return stored;
+                return write({
+                    ...stored,
+                    applyAttempts: (stored.applyAttempts ?? []).map((attempt) => attempt.id === claimId
+                        ? { ...attempt, status: "uncertain", note: "Apply exited without a completed run; some provider writes may have landed." }
+                        : attempt),
+                });
+            });
+        },
+        async recoverApply(planId) {
+            return withPlanLock(planId, () => {
+                const stored = mustRead(planId);
+                if (stored.status !== "applying" || !stored.applyClaim) {
+                    throw new Error(`Plan ${planId} has no unresolved apply attempt.`);
+                }
+                // Recovery is deliberately privilege-decaying: discard the old approval.
+                // An operator must inspect the provider, then explicitly approve a fresh attempt.
+                return write({
+                    ...stored,
+                    status: "needs_approval",
+                    applyClaim: undefined,
+                    approvedOperationIds: [],
+                    valueOverrides: {},
+                    approvalDigests: undefined,
+                    applyAttempts: (stored.applyAttempts ?? []).map((attempt) => attempt.id === stored.applyClaim.id
+                        ? { ...attempt, status: "uncertain", resolvedAt: new Date().toISOString(), note: "Operator acknowledged uncertain provider state; approval cleared before any retry." }
+                        : attempt),
+                });
             });
         },
     };

package/dist/providerError.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A persistence-safe provider failure. Third-party response bodies are
+ * deliberately excluded: they can reflect credentials, filters, or PII and
+ * errors are rendered in terminals, MCP responses, and scheduled-run files.
+ */
+export declare class ProviderHttpError extends Error {
+    readonly code = "PROVIDER_HTTP_ERROR";
+    readonly provider: string;
+    readonly operation: string;
+    readonly status: number;
+    readonly retryable: boolean;
+    constructor(provider: string, operation: string, status: number, retryable?: boolean);
+    toJSON(): {
+        code: string;
+        provider: string;
+        operation: string;
+        status: number;
+        retryable: boolean;
+        message: string;
+    };
+}

package/dist/providerError.js

@@ -0,0 +1,30 @@
+/**
+ * A persistence-safe provider failure. Third-party response bodies are
+ * deliberately excluded: they can reflect credentials, filters, or PII and
+ * errors are rendered in terminals, MCP responses, and scheduled-run files.
+ */
+export class ProviderHttpError extends Error {
+    code = "PROVIDER_HTTP_ERROR";
+    provider;
+    operation;
+    status;
+    retryable;
+    constructor(provider, operation, status, retryable = status === 429 || status >= 500) {
+        super(`${provider} ${operation} failed: HTTP ${status}.`);
+        this.name = "ProviderHttpError";
+        this.provider = provider;
+        this.operation = operation;
+        this.status = status;
+        this.retryable = retryable;
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            provider: this.provider,
+            operation: this.operation,
+            status: this.status,
+            retryable: this.retryable,
+            message: this.message,
+        };
+    }
+}