@kisev/skills-opencode 2.0.3 → 2.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 [Русский](README.ru.md)
 
-`@kisev/skills-opencode@2.0.3` is the optional OpenCode-specific layer. Portable
+`@kisev/skills-opencode@2.0.4` is the optional OpenCode-specific layer. Portable
 skills have a separate lifecycle and must be installed independently through the
 [root portable flow](../../README.md).
 
@@ -30,7 +30,7 @@ Install in the repository's npm project and run the CLI from that project root:
 
 ```shell
 cd /path/to/project
-npm install --save-exact @kisev/skills-opencode@2.0.3
+npm install --save-exact @kisev/skills-opencode@2.0.4
 npm exec -- skills-opencode install --scope project --dry-run
 ```
 
@@ -45,7 +45,7 @@ Use `~/.config/opencode` as the persistent npm project:
 mkdir -p "$HOME/.config/opencode"
 cd "$HOME/.config/opencode"
 test -f package.json || npm init --yes
-npm install --save-exact @kisev/skills-opencode@2.0.3
+npm install --save-exact @kisev/skills-opencode@2.0.4
 npm exec -- skills-opencode install --scope global --dry-run
 ```
 
@@ -100,8 +100,12 @@ under `~/.config/opencode`. Restart OpenCode after activation or asset changes.
 ## Preview and Confirm
 
 Every mutation begins with `--dry-run`. The preview reports operations,
-conflicts, restart requirements, receipt expiry, a SHA-256 digest, and the exact
-confirmation command.
+conflicts, restart requirements, receipt expiry, separate plan and confirmation
+digests, and the exact confirmation command. If reconcile reports modified
+managed files or ownership conflicts, it is blocked: no receipt or Apply command
+is issued. Install or upgrade the current package first, apply its exact
+installer confirmation, then repeat reconcile; resolve ownership conflicts
+manually.
 
 ```shell
 npm exec -- skills-opencode install --scope project --dry-run
@@ -110,8 +114,13 @@ npm exec -- skills-opencode install --scope project --dry-run
 The mandatory OpenCode flow is: persistent npm install, `install --dry-run`, the
 exact confirmation command printed by that preview, add the package to the
 user-owned `plugin` entry, and restart OpenCode. Use the persistent npm project
-at `~/.config/opencode` for global commands. Only after this flow is complete,
-update the package and apply its installer plan before running reconcile.
+at `~/.config/opencode` for global commands. Install or upgrade the package and
+apply its installer plan before every reconcile.
+
+The preview has a deterministic `plan_digest` and a unique
+`confirmation_digest`. A later dry-run in the same scope supersedes any older
+unconsumed preview, including previews from another package or agent operation;
+the older confirmation is rejected.
 
 Run the command printed by the preview, including all selection flags. Receipts
 are private, valid for 10 minutes, single-use, and bound to the action, scope,
@@ -140,7 +149,7 @@ version, preview and confirm `install` with the same scope and desired selection
 then restart OpenCode:
 
 ```shell
-npm install --save-exact @kisev/skills-opencode@2.0.3
+npm install --save-exact @kisev/skills-opencode@2.0.4
 npm exec -- skills-opencode install --scope project --dry-run
 ```
 

package/README.ru.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [Русский](README.ru.md)
 
-`@kisev/skills-opencode@2.0.3` - optional OpenCode-specific слой. У portable
+`@kisev/skills-opencode@2.0.4` - optional OpenCode-specific слой. У portable
 skills отдельный lifecycle: их нужно установить независимо через
 [корневую инструкцию](../../README.ru.md).
 
@@ -30,7 +30,7 @@ assets или portable skills и не меняют OpenCode configuration.
 
 ```shell
 cd /path/to/project
-npm install --save-exact @kisev/skills-opencode@2.0.3
+npm install --save-exact @kisev/skills-opencode@2.0.4
 npm exec -- skills-opencode install --scope project --dry-run
 ```
 
@@ -45,7 +45,7 @@ Package остаётся в project `node_modules`, confirmed assets разме
 mkdir -p "$HOME/.config/opencode"
 cd "$HOME/.config/opencode"
 test -f package.json || npm init --yes
-npm install --save-exact @kisev/skills-opencode@2.0.3
+npm install --save-exact @kisev/skills-opencode@2.0.4
 npm exec -- skills-opencode install --scope global --dry-run
 ```
 
@@ -101,8 +101,12 @@ OpenCode.
 ## Preview и confirm
 
 Каждая mutation начинается с `--dry-run`. Preview показывает operations,
-conflicts, необходимость restart, срок действия receipt, SHA-256 digest и точную
-confirmation command.
+conflicts, необходимость restart, срок действия receipt, отдельные plan и
+confirmation digests и точную confirmation command. Если reconcile показывает
+modified managed files или ownership conflicts, он блокируется: receipt и Apply
+command не создаются. Сначала установите или обновите текущий package,
+примените его exact installer confirmation, затем повторите reconcile; ownership
+conflicts нужно разрешить вручную.
 
 ```shell
 npm exec -- skills-opencode install --scope project --dry-run
@@ -111,8 +115,12 @@ npm exec -- skills-opencode install --scope project --dry-run
 Обязательный OpenCode flow: persistent npm install, `install --dry-run`, exact
 confirmation command из preview, добавление package в user-owned `plugin` и
 перезапуск OpenCode. Для global-команд используйте persistent npm project в
-`~/.config/opencode`. Только после этого обновите package, примените installer
-plan и запускайте reconcile.
+`~/.config/opencode`. Перед каждым reconcile установите или обновите package и
+примените его installer plan.
+
+Preview имеет deterministic `plan_digest` и unique `confirmation_digest`. Новый
+dry-run в том же scope supersede-ит любой старый unconsumed preview, включая
+preview другой package или agent operation; старая confirmation отклоняется.
 
 Выполните команду из preview со всеми selection flags. Receipts приватны,
 действуют 10 минут, применяются один раз и связаны с action, scope, root и
@@ -141,7 +149,7 @@ incomplete probe failure.
 перезапустите OpenCode:
 
 ```shell
-npm install --save-exact @kisev/skills-opencode@2.0.3
+npm install --save-exact @kisev/skills-opencode@2.0.4
 npm exec -- skills-opencode install --scope project --dry-run
 ```
 

package/dist/agent-profiles.d.ts

@@ -1,4 +1,4 @@
-import { LifecycleError, type FileMutation, type Scope, type TransactionOptions } from "./lifecycle.js";
+import { LifecycleError, type SupersededPlan, type FileMutation, type Scope, type TransactionOptions } from "./lifecycle.js";
 export { type Scope as AgentProfileScope } from "./lifecycle.js";
 export declare const FIXED_AGENT_ROLES: readonly ["manager", "architect", "mapper", "worker", "review", "critic"];
 export type FixedAgentRole = (typeof FIXED_AGENT_ROLES)[number];
@@ -70,6 +70,9 @@ export type AgentProfilePlan = {
     root: string;
     operations: AgentProfileOperation[];
     critic_pool: string[];
+    plan_digest: string;
+    confirmation_digest?: string;
+    superseded_plan?: SupersededPlan;
     digest: string;
     receipt_expires_at?: string;
     requires_restart: boolean;

package/dist/agent-profiles.js

@@ -520,9 +520,11 @@ export async function buildAgentProfilePlan(request, scope, cwd = process.cwd(),
         critic_pool: desired?.critic_pool ?? finalManifest?.critic_pool ?? [],
         requires_restart: mutations.some((item) => item.path.startsWith("agents/")),
     };
+    const planDigest = planDigestBase(base, inventoryDigest, request);
     const plan = {
         ...base,
-        digest: planDigestBase(base, inventoryDigest, request),
+        plan_digest: planDigest,
+        digest: planDigest,
     };
     return {
         plan,
@@ -639,8 +641,15 @@ export async function previewAgentProfileChange(request, scope, cwd = process.cw
         if (await recoverTransaction(deploymentRoot(scope, cwd, home), stateRoot))
             throw new AgentProfileError("recovered_transaction", "Recovered an interrupted transaction; request a fresh plan");
         const built = await buildAgentProfilePlan(request, scope, cwd, home);
-        const receipt = await saveReceipt(stateRoot, `agent:${request.action}`, scope, built.plan.root, { request, digest: built.plan.digest });
-        return { ...built.plan, digest: receipt.digest, receipt_expires_at: receipt.expires_at };
+        const receipt = await saveReceipt(stateRoot, `agent:${request.action}`, scope, built.plan.root, { request, plan_digest: built.plan.digest }, Date.now(), built.plan.digest);
+        return {
+            ...built.plan,
+            plan_digest: built.plan.digest,
+            confirmation_digest: receipt.digest,
+            digest: receipt.digest,
+            receipt_expires_at: receipt.expires_at,
+            ...(receipt.superseded_plan ? { superseded_plan: receipt.superseded_plan } : {}),
+        };
     });
 }
 export async function applyAgentProfileChange(request, scope, confirmationDigest, cwd = process.cwd(), home = homedir(), options = {}) {
@@ -658,7 +667,7 @@ export async function applyAgentProfileChange(request, scope, confirmationDigest
         if (stable(receipt.request) !== stable(request))
             throw new AgentProfileError("confirmation_unknown", "Saved confirmation belongs to a different request");
         const built = await buildAgentProfilePlan(request, scope, cwd, home);
-        if (built.plan.digest !== receipt.digest)
+        if (built.plan.digest !== receipt.plan_digest)
             throw new AgentProfileError("stale_plan", "Agent inventory changed after preview");
         if (built.plan.operations.some((item) => item.operation === "conflict" && item.reason.includes("collision")))
             throw new AgentProfileError("collision", "Exact-name user-owned collision blocks apply");

package/dist/catalog.d.ts

@@ -4,5 +4,5 @@ export declare const CATALOG: {
     readonly agents: readonly ["manager", "architect", "mapper", "worker", "review", "critic"];
     readonly package_commands: readonly ["capabilities", "doctor", "reconcile", "agent-profiles"];
     readonly tools: readonly ["capabilities", "route", "doctor", "agent_profiles", "reconcile"];
-    readonly version: "2.0.3";
+    readonly version: "2.0.4";
 };

package/dist/catalog.js

@@ -34,5 +34,5 @@ export const CATALOG = {
     agents: ["manager", "architect", "mapper", "worker", "review", "critic"],
     package_commands: ["capabilities", "doctor", "reconcile", "agent-profiles"],
     tools: ["capabilities", "route", "doctor", "agent_profiles", "reconcile"],
-    version: "2.0.3",
+    version: "2.0.4",
 };

package/dist/cli-output.js

@@ -119,9 +119,16 @@ export function renderPlan(plan, options) {
         ? `Restart required: ${plan.requires_restart ? "yes" : "no"}`
         : `Restart after apply: ${plan.requires_restart ? "yes" : "no"}`);
     if (!options.applied) {
+        if (plan.superseded_plan)
+            lines.push("", "Superseded plan:", `  kind: ${terminalSafe(plan.superseded_plan.kind)}`, `  confirmation: ${terminalSafe(plan.superseded_plan.confirmation_digest)}`, `  created: ${terminalSafe(plan.superseded_plan.created_at)}`, `  expires: ${terminalSafe(plan.superseded_plan.expires_at)}`);
         if (plan.receipt_expires_at)
             lines.push(`Confirmation expires: ${plan.receipt_expires_at}`);
-        lines.push(`Digest: ${plan.digest}`);
+        if ("plan_digest" in plan)
+            lines.push(`Plan digest: ${plan.plan_digest}`);
+        if (plan.confirmation_digest ?? plan.digest) {
+            lines.push(`Confirmation digest: ${plan.confirmation_digest ?? plan.digest}`);
+            lines.push(`Digest: ${plan.confirmation_digest ?? plan.digest}`);
+        }
         if (options.confirmationCommand)
             lines.push("", "Apply:", `  ${options.confirmationCommand}`);
     }
@@ -183,9 +190,6 @@ export function renderReconcile(plan, options) {
     if (plan.modified_managed.length)
         lines.push("", "Modified managed:", ...plan.modified_managed.map((entry) => `  ${terminalSafe(entry.path)} (${terminalSafe(entry.reason)})`));
     if (!options.applied) {
-        lines.push("", `Digest: ${plan.digest}`);
-        if (plan.receipt_expires_at)
-            lines.push(`Confirmation expires: ${plan.receipt_expires_at}`);
         const blocked = plan.modified_managed.length > 0 || plan.conflicts.length > 0;
         if (blocked) {
             lines.push("", "Blocked:");
@@ -195,6 +199,13 @@ export function renderReconcile(plan, options) {
                 lines.push("  Manually resolve every ownership conflict listed above before reconciling.");
         }
         else if (options.confirmationCommand) {
+            if (plan.superseded_plan)
+                lines.push("", "Superseded plan:", `  kind: ${terminalSafe(plan.superseded_plan.kind)}`, `  confirmation: ${terminalSafe(plan.superseded_plan.confirmation_digest)}`, `  created: ${terminalSafe(plan.superseded_plan.created_at)}`, `  expires: ${terminalSafe(plan.superseded_plan.expires_at)}`);
+            lines.push("", `Plan digest: ${plan.plan_digest}`);
+            if (plan.receipt_expires_at)
+                lines.push(`Confirmation expires: ${plan.receipt_expires_at}`);
+            if (plan.confirmation_digest ?? plan.digest)
+                lines.push(`Confirmation digest: ${plan.confirmation_digest ?? plan.digest}`, `Digest: ${plan.confirmation_digest ?? plan.digest}`);
             lines.push("", "Apply:", `  ${options.confirmationCommand}`);
         }
     }

package/dist/cli.js

@@ -353,7 +353,7 @@ async function run(arguments_) {
             if (options.json)
                 process.stdout.write(`${JSON.stringify({ status: "ok", applied: false, plan }, null, 2)}\n`);
             else
-                process.stdout.write(renderReconcile(plan, { applied: false, confirmationCommand: shellCommand(["reconcile", "--scope", options.scope, "--confirm", plan.digest]) }));
+                process.stdout.write(renderReconcile(plan, { applied: false, confirmationCommand: plan.confirmable ? shellCommand(["reconcile", "--scope", options.scope, "--confirm", plan.confirmation_digest ?? plan.digest]) : undefined }));
         }
         else {
             const applied = await applyReconcile(options.scope, options.confirm);

package/dist/installer.d.ts

@@ -1,4 +1,4 @@
-import { LifecycleError, type FileMutation, type Scope, type TransactionOptions } from "./lifecycle.js";
+import { LifecycleError, type SupersededPlan, type FileMutation, type Scope, type TransactionOptions } from "./lifecycle.js";
 import { CATALOG } from "./catalog.js";
 import { type FixedAgentRole } from "./agent-profiles.js";
 export type { Scope } from "./lifecycle.js";
@@ -25,6 +25,9 @@ export type Plan = {
     package_version: string;
     selection: InstallerSelection;
     operations: PlanItem[];
+    plan_digest: string;
+    confirmation_digest?: string;
+    superseded_plan?: SupersededPlan;
     digest: string;
     receipt_expires_at?: string;
     requires_restart: boolean;

package/dist/installer.js

@@ -404,8 +404,9 @@ async function build(action, scope, cwd = process.cwd(), home = homedir(), reque
     }
     const sorted = operations.sort((left, right) => left.path.localeCompare(right.path) || left.operation.localeCompare(right.operation));
     const base = { schema_version: 2, action, scope, root, package_version: packageVersion(), selection, operations: sorted, requires_restart: (action === "install" && owned.manifest?.package_version !== packageVersion()) || profiles.plan.requires_restart || mutations.some((item) => item.path.startsWith("agents/") || item.path.startsWith("commands/") || item.path.startsWith("plugins/")) };
+    const planDigest = digest(base);
     return {
-        plan: { ...base, digest: digest(base) },
+        plan: { ...base, plan_digest: planDigest, digest: planDigest },
         mutations,
         expectedManifest: manifestContent,
         profiles,
@@ -419,8 +420,15 @@ export async function preview(action, scope, cwd = process.cwd(), home = homedir
             if (await recoverTransaction(root, stateRoot))
                 throw new InstallerError("recovered_transaction", "Recovered an interrupted transaction; request a fresh plan");
             const built = await build(action, scope, cwd, home, selection);
-            const receipt = await saveReceipt(stateRoot, `installer:${action}`, scope, root, { digest: built.plan.digest });
-            return { ...built.plan, digest: receipt.digest, receipt_expires_at: receipt.expires_at };
+            const receipt = await saveReceipt(stateRoot, `installer:${action}`, scope, root, { plan_digest: built.plan.digest }, Date.now(), built.plan.digest);
+            return {
+                ...built.plan,
+                plan_digest: built.plan.digest,
+                confirmation_digest: receipt.digest,
+                digest: receipt.digest,
+                receipt_expires_at: receipt.expires_at,
+                ...(receipt.superseded_plan ? { superseded_plan: receipt.superseded_plan } : {}),
+            };
         });
     }
     catch (error) {
@@ -440,7 +448,7 @@ export async function apply(action, scope, confirmationDigest, cwd = process.cwd
                 throw new InstallerError("recovered_transaction", "Recovered an interrupted transaction; request a fresh plan");
             const receipt = (await consumeReceipt(stateRoot, { digest: confirmationDigest, kind: `installer:${action}`, scope, root }));
             const built = await build(action, scope, cwd, home, selection);
-            if (built.plan.digest !== receipt.digest)
+            if (built.plan.digest !== receipt.plan_digest)
                 throw new InstallerError("stale_plan", "Installer plan changed after preview");
             if (built.plan.operations.some((item) => item.operation === "conflict" && (item.reason === "unmanaged_file" || item.reason === "v1.0.0_agent_ownership_mismatch" || item.reason?.includes("collision")))) {
                 throw new InstallerError("conflict", "Installer plan contains an exact-name ownership conflict");

package/dist/lifecycle.d.ts

@@ -21,6 +21,12 @@ export type FileMutation = {
     operation: "remove";
     expected: FileExpectation;
 };
+export type SupersededPlan = {
+    kind: string;
+    confirmation_digest: string;
+    created_at: string;
+    expires_at: string;
+};
 export declare function stable(value: unknown): string;
 export declare function sha256(value: Buffer | string): string;
 export declare function digest(value: unknown): string;
@@ -36,9 +42,11 @@ export declare function deploymentRoot(scope: Scope, cwd?: string, home?: string
 export declare function lifecycleRoot(scope: Scope, cwd?: string, home?: string): string;
 export declare function archiveRoot(scope: Scope, cwd?: string, home?: string): string;
 export declare function withLifecycleLock<T>(stateRoot: string, callback: () => Promise<T>): Promise<T>;
-export declare function saveReceipt(stateRoot: string, kind: string, scope: Scope, root: string, payload: unknown, now?: number): Promise<{
+export declare function saveReceipt(stateRoot: string, kind: string, scope: Scope, root: string, payload: unknown, now?: number, planDigest?: string): Promise<{
     digest: string;
+    plan_digest: string;
     expires_at: string;
+    superseded_plan?: SupersededPlan;
 }>;
 export declare function consumeReceipt(stateRoot: string, expected: {
     digest: string;
@@ -46,6 +54,8 @@ export declare function consumeReceipt(stateRoot: string, expected: {
     scope: Scope;
     root: string;
 }, now?: number): Promise<unknown>;
+/** Invalidate an active receipt when a preview is blocked before a replacement exists. */
+export declare function supersedeReceipt(stateRoot: string, now?: number): Promise<void>;
 export declare function recoverTransaction(root: string, stateRoot: string): Promise<boolean>;
 export type TransactionOptions = {
     beforePublish?: (index: number) => void;

package/dist/lifecycle.js

@@ -240,37 +240,52 @@ export async function withLifecycleLock(stateRoot, callback) {
 function receiptPath(stateRoot) {
     return join(stateRoot, "receipt.json");
 }
-export async function saveReceipt(stateRoot, kind, scope, root, payload, now = Date.now()) {
-    const confirmationDigest = digest({ schema_version: 1, kind, scope, root, payload });
+export async function saveReceipt(stateRoot, kind, scope, root, payload, now = Date.now(), planDigest = digest(payload)) {
     const existingRaw = await readRegular(receiptPath(stateRoot));
+    let superseded;
     if (existingRaw) {
         const existing = parseReceipt(existingRaw);
-        if (!existing.consumed &&
-            Date.parse(existing.expires_at) >= now &&
-            existing.digest !== confirmationDigest) {
-            throw new LifecycleError("active_receipt", "An unconsumed agent or installer plan is still active");
-        }
-        if (!existing.consumed &&
-            Date.parse(existing.expires_at) >= now &&
-            existing.digest === confirmationDigest) {
-            return { digest: existing.digest, expires_at: existing.expires_at };
+        if (!existing.consumed && Date.parse(existing.expires_at) >= now) {
+            superseded = existing;
         }
     }
+    const confirmationDigest = sha256(randomBytes(32));
     const receipt = {
         schema_version: 1,
         digest: confirmationDigest,
+        plan_digest: planDigest,
         nonce: randomBytes(32).toString("base64url"),
+        created_at: new Date(now).toISOString(),
         expires_at: new Date(now + RECEIPT_TTL_MS).toISOString(),
         consumed: false,
         kind,
         scope,
         root,
         payload,
+        ...(superseded
+            ? {
+                superseded_digests: [superseded.digest, ...(superseded.superseded_digests ?? [])],
+            }
+            : {}),
         integrity: "",
     };
     receipt.integrity = receiptIntegrity(receipt);
     await writeAtomic(receiptPath(stateRoot), Buffer.from(`${stable(receipt)}\n`), 0o600);
-    return { digest: receipt.digest, expires_at: receipt.expires_at };
+    return {
+        digest: receipt.digest,
+        plan_digest: receipt.plan_digest,
+        expires_at: receipt.expires_at,
+        ...(superseded
+            ? {
+                superseded_plan: {
+                    kind: superseded.kind,
+                    confirmation_digest: superseded.digest.slice(0, 12),
+                    created_at: superseded.created_at,
+                    expires_at: superseded.expires_at,
+                },
+            }
+            : {}),
+    };
 }
 function parseReceipt(raw) {
     let value;
@@ -285,23 +300,29 @@ function parseReceipt(raw) {
         receipt.schema_version !== 1 ||
         typeof receipt.digest !== "string" ||
         !/^[a-f0-9]{64}$/.test(receipt.digest) ||
+        typeof receipt.plan_digest !== "string" ||
+        !/^[a-f0-9]{64}$/.test(receipt.plan_digest) ||
         typeof receipt.nonce !== "string" ||
+        typeof receipt.created_at !== "string" ||
         typeof receipt.expires_at !== "string" ||
         typeof receipt.consumed !== "boolean" ||
+        (receipt.superseded !== undefined && typeof receipt.superseded !== "boolean") ||
         typeof receipt.kind !== "string" ||
         (receipt.scope !== "global" && receipt.scope !== "project") ||
         typeof receipt.root !== "string" ||
+        (receipt.superseded_digests !== undefined &&
+            (!Array.isArray(receipt.superseded_digests) ||
+                !receipt.superseded_digests.every((value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value)))) ||
         typeof receipt.integrity !== "string") {
         throw new LifecycleError("invalid_receipt", "Receipt has an unsupported schema");
     }
-    if (receipt.digest !==
-        digest({
-            schema_version: 1,
-            kind: receipt.kind,
-            scope: receipt.scope,
-            root: receipt.root,
-            payload: receipt.payload,
-        })) {
+    const payloadRecord = receipt.payload;
+    const payloadPlanDigest = payloadRecord &&
+        typeof payloadRecord === "object" &&
+        typeof payloadRecord.plan_digest === "string"
+        ? payloadRecord.plan_digest
+        : digest(receipt.payload);
+    if (receipt.plan_digest !== payloadPlanDigest) {
         throw new LifecycleError("invalid_receipt", "Receipt digest does not match its payload");
     }
     if (receipt.integrity !== receiptIntegrity(receipt))
@@ -323,8 +344,12 @@ export async function consumeReceipt(stateRoot, expected, now = Date.now()) {
         receipt.kind !== expected.kind ||
         receipt.scope !== expected.scope ||
         receipt.root !== expected.root) {
+        if (receipt.superseded_digests?.includes(expected.digest))
+            throw new LifecycleError("superseded_plan", "Confirmation receipt was superseded by a newer plan");
         throw new LifecycleError("confirmation_unknown", "Confirmation does not match the saved plan");
     }
+    if (receipt.superseded)
+        throw new LifecycleError("superseded_plan", "Confirmation receipt was superseded by a newer plan");
     if (receipt.consumed)
         throw new LifecycleError("confirmation_consumed", "Confirmation receipt was already consumed");
     if (Date.parse(receipt.expires_at) < now)
@@ -334,6 +359,19 @@ export async function consumeReceipt(stateRoot, expected, now = Date.now()) {
     await writeAtomic(receiptPath(stateRoot), Buffer.from(`${stable(consumed)}\n`), 0o600);
     return receipt.payload;
 }
+/** Invalidate an active receipt when a preview is blocked before a replacement exists. */
+export async function supersedeReceipt(stateRoot, now = Date.now()) {
+    const path = receiptPath(stateRoot);
+    const raw = await readRegular(path);
+    if (!raw)
+        return;
+    const receipt = parseReceipt(raw);
+    if (receipt.consumed || receipt.superseded || Date.parse(receipt.expires_at) < now)
+        return;
+    const superseded = { ...receipt, consumed: true, superseded: true, integrity: "" };
+    superseded.integrity = receiptIntegrity(superseded);
+    await writeAtomic(path, Buffer.from(`${stable(superseded)}\n`), 0o600);
+}
 function journalPath(stateRoot) {
     return join(stateRoot, "transaction-journal.json");
 }

package/dist/reconcile.d.ts

@@ -1,4 +1,4 @@
-import { LifecycleError, type Scope, type TransactionOptions } from "./lifecycle.js";
+import { LifecycleError, type SupersededPlan, type Scope, type TransactionOptions } from "./lifecycle.js";
 export type ReconcileStatus = "current" | "retired" | "archive-pending" | "renamed" | "modified-managed" | "user-owned" | "unknown" | "conflict" | "diagnostic-state-only";
 export type ReconcileItem = {
     path: string;
@@ -27,7 +27,11 @@ export type ReconcilePlan = {
         operation: "remove" | "write";
         sha256?: string;
     }>;
-    digest: string;
+    plan_digest: string;
+    confirmation_digest?: string;
+    superseded_plan?: SupersededPlan;
+    confirmable: boolean;
+    digest?: string;
     receipt_expires_at?: string;
 };
 export type ReconcileResult = {

package/dist/reconcile.js

@@ -3,7 +3,7 @@ import { lstat, readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { applyTransaction, assertSafePath, consumeReceipt, destination, digest, LifecycleError, lifecycleRoot, recoverTransaction, saveReceipt, sha256, stable, withLifecycleLock, } from "./lifecycle.js";
+import { applyTransaction, assertSafePath, consumeReceipt, destination, digest, LifecycleError, lifecycleRoot, recoverTransaction, saveReceipt, supersedeReceipt, sha256, stable, withLifecycleLock, } from "./lifecycle.js";
 import { archiveMutations } from "./installer.js";
 const PACKAGE_NAME = "@kisev/skills-opencode";
 const GENERIC_MANIFEST = ".skills-opencode-manifest.json";
@@ -437,7 +437,11 @@ async function build(scope, cwd = process.cwd(), home = homedir()) {
         diagnostic_state_only: diagnostic(scope, cwd, home),
         operations: operations.sort((left, right) => left.path.localeCompare(right.path)),
     };
-    return { plan: { ...base, digest: digest(base) }, mutations };
+    const planDigest = digest(base);
+    return {
+        plan: { ...base, plan_digest: planDigest, confirmable: true, digest: planDigest },
+        mutations,
+    };
 }
 export async function previewReconcile(scope, cwd = process.cwd(), home = homedir()) {
     const stateRoot = lifecycleRoot(scope, cwd, home);
@@ -447,10 +451,24 @@ export async function previewReconcile(scope, cwd = process.cwd(), home = homedi
             if (await recoverTransaction(root, stateRoot))
                 throw new ReconcileError("recovered_transaction", "Recovered an interrupted transaction; request a fresh plan");
             const built = await build(scope, cwd, home);
+            const blocked = built.plan.modified_managed.length > 0 || built.plan.conflicts.length > 0;
+            if (blocked) {
+                await supersedeReceipt(stateRoot);
+                const { digest: _digest, ...withoutReceipt } = built.plan;
+                return { ...withoutReceipt, confirmable: false };
+            }
             const receipt = await saveReceipt(stateRoot, "reconcile", scope, root, {
-                digest: built.plan.digest,
-            });
-            return { ...built.plan, digest: receipt.digest, receipt_expires_at: receipt.expires_at };
+                plan_digest: built.plan.plan_digest,
+            }, Date.now(), built.plan.plan_digest);
+            return {
+                ...built.plan,
+                plan_digest: built.plan.plan_digest,
+                confirmation_digest: receipt.digest,
+                digest: receipt.digest,
+                confirmable: true,
+                receipt_expires_at: receipt.expires_at,
+                ...(receipt.superseded_plan ? { superseded_plan: receipt.superseded_plan } : {}),
+            };
         });
     }
     catch (error) {
@@ -479,7 +497,7 @@ export async function applyReconcile(scope, confirmationDigest, cwd = process.cw
                 root,
             }));
             const built = await build(scope, cwd, home);
-            if (built.plan.digest !== payload.digest)
+            if (built.plan.plan_digest !== payload.plan_digest)
                 throw new ReconcileError("stale_plan", "Reconcile inventory changed after preview");
             if (built.plan.conflicts.length || built.plan.modified_managed.length)
                 throw new ReconcileError("conflict", "Reconcile contains unsafe ownership conflicts");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/skills-opencode",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "OpenCode integration and opt-in installer for portable Agent Skills.",
   "license": "MIT",
   "repository": {