pi-session-mcp 0.8.0 → 0.8.2

package/dist/setup-ownership.d.ts

@@ -8,7 +8,10 @@ export interface OwnershipRecord {
     readonly transactionId: string;
     /**
      * Skill records only, while pending: the fingerprint of setup's own copy that the pending
-     * update replaces, so an interrupted update can still be completed or removed.
+     * update replaces, so an interrupted update can still be completed or removed. The
+     * transaction id also names the update's intermediate directories, so recovery needs no path.
+     * Skill fingerprints are `v2:` values; a bare 64-hex value is a record that 0.8.0 wrote and
+     * names a tree only once a trusted reference proves it.
      */
     readonly replaces?: string;
 }

package/dist/setup-ownership.js

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { acquireSetupGuardian } from "./setup-process.js";
 import { assertSupportedFilesystem, currentSetupPlatform, openLockedDarwin } from "./setup-platform.js";
-import { SKILL_NAME_PATTERN } from "./skill-library.js";
+import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, SKILL_NAME_PATTERN, SKILL_TREE_FINGERPRINT_PATTERN } from "./skill-library.js";
 /** Safe default for one process; callers needing recovery inject a durable store. */
 export class MemoryOwnershipStore {
     entries = new Map();
@@ -231,10 +231,13 @@ export function isRecord(value) {
     const skill = skillAlias !== null && SKILL_NAME_PATTERN.test(skillAlias[1]) &&
         (client === "codex" ? scope === "user" && skillAlias[2] === undefined
             : client === "claude-code" && ((scope === "user" && skillAlias[2] === undefined) || (scope === "project" && skillAlias[2] !== undefined)));
+    // A registration fingerprint is a snapshot hash; a skill fingerprint is a version 2 tree value or a 0.8.0 legacy one.
+    const validFingerprint = (value) => typeof value === "string" &&
+        (skill ? SKILL_TREE_FINGERPRINT_PATTERN.test(value) || LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) : /^[a-f0-9]{64}$/.test(value));
     // `replaces` belongs only to a pending skill record.
-    if ("replaces" in x && !(skill && x.phase === "pending" && typeof x.replaces === "string" && /^[a-f0-9]{64}$/.test(x.replaces)))
+    if ("replaces" in x && !(skill && x.phase === "pending" && validFingerprint(x.replaces)))
         return false;
-    return (registration || skill) && typeof x.fingerprint === "string" && /^[a-f0-9]{64}$/.test(x.fingerprint) &&
+    return (registration || skill) && validFingerprint(x.fingerprint) &&
         (x.phase === "pending" || x.phase === "owned") && x.previous === "absent" &&
         typeof x.transactionId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(x.transactionId);
 }

package/dist/setup-skills.d.ts

@@ -1,3 +1,4 @@
+import { type ReleasedSkillTree } from "./skill-library.js";
 import type { OwnershipAccess } from "./setup-ownership.js";
 import type { SetupFinding, SetupOperation, SetupTarget } from "./setup-result.js";
 export interface SetupSkillInstaller {
@@ -15,12 +16,22 @@ export interface SetupSkillRoots {
     readonly home: string;
     readonly cwd: string;
 }
+/** The crash-relevant points of an update, in order. Only a test seam observes them. */
+export type SkillCheckpoint = "staged" | "backup-renamed" | "installed" | "trash-renamed" | "trash-entry-removed" | "trash-deleted" | "before-ownership";
+export interface SetupSkillDependencies {
+    /** Trusted released trees that prove 0.8.0 records; defaults to the shipped table. */
+    readonly released?: readonly ReleasedSkillTree[];
+    /** Test seam, called after each step in `SkillCheckpoint` completed; defaults to a no-op. */
+    readonly checkpoint?: (step: SkillCheckpoint) => void | Promise<void>;
+}
 /** Paths remain internal. Ownership identifies a client slot, never its location. */
 export declare class FileSetupSkillInstaller implements SetupSkillInstaller {
     private readonly roots;
-    constructor(roots: SetupSkillRoots);
+    private readonly dependencies;
+    constructor(roots: SetupSkillRoots, dependencies?: SetupSkillDependencies);
     run(operation: SetupOperation, target: SetupTarget, ownership: OwnershipAccess): Promise<readonly SetupFinding[]>;
     owns(target: SetupTarget, ownership: OwnershipAccess): Promise<boolean>;
+    private step;
     /**
      * The slot path and its ownership key. A project may be untrusted: only its root is
      * canonicalized, and a link below it (for example `.claude` pointing elsewhere) makes the
@@ -32,6 +43,40 @@ export declare class FileSetupSkillInstaller implements SetupSkillInstaller {
      */
     private location;
     private library;
+    /**
+     * Whether the record names this installed tree: its version 2 value, or a 0.8.0 value that a
+     * trusted reference proves for exactly these bytes. A bare legacy value never proves identity.
+     */
+    private ownsTree;
     private skill;
+    /**
+     * Installs the new tree through the transaction's own intermediates. A failure leaves them for
+     * recovery; nothing here deletes by guess.
+     */
     private replace;
+    /**
+     * Deletes the backup only after it is verified to be the exact old copy: it is renamed to the
+     * transaction's trash name first, so the deletion never leaves an unverifiable partial tree
+     * under the backup name.
+     */
+    private discardBackup;
+    /**
+     * Deletes the transaction's trash entry by entry, so a crash leaves only a smaller partial tree.
+     * Callers must have proven the trash to be the complete replaced copy; a later recovery retains
+     * a partial tree instead of deleting it.
+     */
+    private discardTrash;
+    /**
+     * Settles an interrupted update of the pending record's transaction, inside the ownership
+     * transaction. Only directories with this transaction's exact names are examined, and only
+     * verified ones are deleted: the backup must equal the replaced copy, the staging directory
+     * the target or an interrupted write of it, the trash the complete replaced copy. Anything
+     * else stays and is reported, including a partial or changed trash.
+     * A proven trash is still deleted when a later intermediate (backup or staging) is retained.
+     *
+     * apply, slot absent: a complete staging directory is renamed into the slot (forward);
+     * otherwise a verified backup is moved back. remove and rollback do not restore, they delete
+     * what is verified and leave the slot to the caller.
+     */
+    private recover;
 }

package/dist/setup-skills.js

@@ -1,16 +1,33 @@
 import { createHash, randomUUID } from "node:crypto";
-import { lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
-import { CONTROLLER_SKILLS, readSkillTree, resolveLibrarySkill, skillOverrideDirectory } from "./skill-library.js";
-/** Whether a fingerprint is setup's own copy: the owned one, or the one a pending update replaces. */
+import { lstat, mkdir, open, readdir, readFile, realpath, rename, rm, rmdir } from "node:fs/promises";
+import { basename, dirname, join, posix } from "node:path";
+import { CONTROLLER_SKILLS, LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, MAX_SKILL_TREE_BYTES, MAX_SKILL_TREE_FILES, provesLegacyFingerprint, RELEASED_SKILL_TREES, readSkillTree, resolveLibrarySkill, SKILL_TREE_FINGERPRINT_PATTERN, skillOverrideDirectory, } from "./skill-library.js";
+const TRANSACTION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAX_TREE_DEPTH = 8;
+const MAX_TREE_ENTRIES = 256;
+/** Whether a version 2 fingerprint is setup's own copy: the owned one, or the one a pending update replaces. */
 function ownsFingerprint(record, fingerprint) {
     return fingerprint === record.fingerprint || (record.phase === "pending" && record.replaces === fingerprint);
 }
+const isLegacy = (value) => value !== undefined && LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value);
+const hasLegacy = (record) => isLegacy(record.fingerprint) || isLegacy(record.replaces);
+/**
+ * Every intermediate directory of an update is named after the pending record's transaction id
+ * in the slot's parent, so recovery derives them from persisted state and never searches.
+ */
+function intermediates(path, name, transactionId) {
+    if (!TRANSACTION_ID.test(transactionId))
+        throw new Error("skill_transaction_invalid");
+    const base = join(dirname(path), `.pi-session-mcp-${name}-${transactionId}`);
+    return { staging: `${base}.staging`, backup: `${base}.backup`, trash: `${base}.trash` };
+}
 /** Paths remain internal. Ownership identifies a client slot, never its location. */
 export class FileSetupSkillInstaller {
     roots;
-    constructor(roots) {
+    dependencies;
+    constructor(roots, dependencies = {}) {
         this.roots = roots;
+        this.dependencies = dependencies;
     }
     async run(operation, target, ownership) {
         const findings = [];
@@ -29,6 +46,7 @@ export class FileSetupSkillInstaller {
                 return true;
         return false;
     }
+    async step(step) { await this.dependencies.checkpoint?.(step); }
     /**
      * The slot path and its ownership key. A project may be untrusted: only its root is
      * canonicalized, and a link below it (for example `.claude` pointing elsewhere) makes the
@@ -50,6 +68,16 @@ export class FileSetupSkillInstaller {
     library(name) {
         return resolveLibrarySkill(name, { overrideDirectory: skillOverrideDirectory(this.roots.configPath), packageRoot: this.roots.packageRoot });
     }
+    /**
+     * Whether the record names this installed tree: its version 2 value, or a 0.8.0 value that a
+     * trusted reference proves for exactly these bytes. A bare legacy value never proves identity.
+     */
+    ownsTree(name, record, slot, references) {
+        if (ownsFingerprint(record, slot.fingerprint))
+            return true;
+        const named = record.phase === "pending" ? [record.fingerprint, record.replaces] : [record.fingerprint];
+        return named.some((value) => isLegacy(value) && provesLegacyFingerprint(name, value, slot, references, this.dependencies.released ?? RELEASED_SKILL_TREES));
+    }
     async skill(operation, target, name, ownership) {
         const finding = (code, status) => ({ target: { ...target, alias: name }, code, status });
         let location;
@@ -63,9 +91,10 @@ export class FileSetupSkillInstaller {
         }
         const { path, owned: ownedTarget } = location;
         const library = this.library(name);
-        // Only a usable library skill can stand behind an accepted link; otherwise verify and apply would disagree.
-        const usable = library ? await readSkillTree(library.directory).then(() => true, () => false) : false;
-        const linkTarget = usable ? await realpath(library.directory).catch(() => undefined) : undefined;
+        // Only a usable library skill can stand behind an accepted link or a legacy proof; otherwise verify and apply would disagree.
+        const desired = library ? await readSkillTree(library.directory).catch(() => undefined) : undefined;
+        const linkTarget = desired ? await realpath(library.directory).catch(() => undefined) : undefined;
+        const references = desired ? [desired] : [];
         if (operation === "remove" || operation === "rollback") {
             try {
                 const owned = await ownership.get(ownedTarget);
@@ -76,6 +105,9 @@ export class FileSetupSkillInstaller {
                     if (other?.phase === "owned")
                         return finding("skill_kept_shared", "unchanged");
                 }
+                if (owned.phase === "pending" && SKILL_TREE_FINGERPRINT_PATTERN.test(owned.fingerprint)
+                    && await this.recover(operation, path, name, owned, desired, linkTarget, ownership) === "retained")
+                    return finding("skill_recovery_retained", "divergent");
                 const current = await inspectSlot(path, linkTarget);
                 if (current.state === "absent") {
                     healthy(ownership);
@@ -90,8 +122,10 @@ export class FileSetupSkillInstaller {
                     healthy(ownership);
                     return finding("skill_not_owned", "unchanged");
                 }
-                if (current.state !== "tree" || !ownsFingerprint(owned, current.fingerprint))
+                if (current.state !== "tree")
                     return finding("skill_divergent", "divergent");
+                if (!this.ownsTree(name, owned, current, references))
+                    return finding(hasLegacy(owned) ? "skill_legacy_unverified" : "skill_divergent", "divergent");
                 healthy(ownership);
                 if (!await sameSlot(path, current, linkTarget))
                     return finding("skill_divergent", "divergent");
@@ -114,29 +148,26 @@ export class FileSetupSkillInstaller {
                 return finding("skill_missing", "failed");
             if (current.state === "linked")
                 return finding("skill_verified", "ok");
-            try {
-                if (!library)
-                    throw new Error("skill_source_invalid");
-                const desired = await readSkillTree(library.directory);
-                return current.state === "tree" && current.fingerprint === desired.fingerprint
-                    ? finding("skill_verified", "ok") : finding("skill_not_equivalent", "failed");
-            }
-            catch {
-                return finding("skill_not_equivalent", "failed");
-            }
+            return desired && current.state === "tree" && current.fingerprint === desired.fingerprint
+                ? finding("skill_verified", "ok") : finding("skill_not_equivalent", "failed");
         }
-        let desired;
-        try {
-            if (!library)
-                throw new Error("skill_source_invalid");
-            desired = await readSkillTree(library.directory);
-        }
-        catch {
+        if (!desired)
             return finding("skill_source_invalid", "failed");
-        }
         try {
+            let owned = await ownership.get(ownedTarget);
+            let recovered = false;
+            if (operation === "apply" && owned?.phase === "pending" && SKILL_TREE_FINGERPRINT_PATTERN.test(owned.fingerprint)) {
+                const outcome = await this.recover("apply", path, name, owned, desired, linkTarget, ownership);
+                if (outcome === "retained")
+                    return finding("skill_recovery_retained", "divergent");
+                recovered = outcome === "recovered";
+            }
+            // A dry-run never recovers; it announces the settlement apply would perform for a version 2 transaction, or its retention.
+            const recoveryPlanned = operation === "dry-run" && owned?.phase === "pending" && SKILL_TREE_FINGERPRINT_PATTERN.test(owned.fingerprint) && !hasLegacy(owned);
+            // The classification apply's recovery acts on, read-only: an intermediate apply would retain is not announced as planned.
+            if (recoveryPlanned && (await classifyIntermediates(path, name, owned, desired, linkTarget)).state === "retained")
+                return finding("skill_recovery_retained", "divergent");
             const current = await inspectSlot(path, linkTarget);
-            const owned = await ownership.get(ownedTarget);
             if (current.state === "linked") {
                 if (operation === "apply" && owned) {
                     healthy(ownership);
@@ -147,6 +178,17 @@ export class FileSetupSkillInstaller {
             }
             if (current.state === "divergent")
                 return finding("skill_divergent", "divergent");
+            if (owned && current.state === "tree" && hasLegacy(owned)) {
+                // A record from 0.8.0: it names the slot only if a trusted reference proves these exact bytes.
+                if (!this.ownsTree(name, owned, current, references))
+                    return finding("skill_legacy_unverified", "divergent");
+                owned = { target: ownedTarget, fingerprint: current.fingerprint, previous: owned.previous, phase: "owned", transactionId: owned.transactionId };
+                if (operation === "apply") {
+                    healthy(ownership);
+                    await ownership.put(owned);
+                    healthy(ownership);
+                }
+            }
             // A copy setup did not write, or its own copy modified since, is never replaced.
             if (current.state === "tree" && (!owned || !ownsFingerprint(owned, current.fingerprint))) {
                 if (!owned && current.fingerprint === desired.fingerprint)
@@ -154,17 +196,26 @@ export class FileSetupSkillInstaller {
                 return finding("skill_divergent", "divergent");
             }
             if (current.state === "tree" && current.fingerprint === desired.fingerprint) {
+                if (recoveryPlanned)
+                    return finding("skill_recovery_planned", "planned");
                 if (operation === "apply" && owned?.phase === "pending") {
                     healthy(ownership);
                     await ownership.put(ownedRecord(owned, desired.fingerprint));
                     healthy(ownership);
+                    return finding("skill_recovered", "ok");
                 }
+                if (operation === "apply" && recovered)
+                    return finding("skill_recovered", "ok");
                 return finding(operation === "apply" ? "skill_already_equivalent" : "skill_equivalent", "unchanged");
             }
-            if (operation === "dry-run")
+            if (operation === "dry-run") {
+                if (recoveryPlanned)
+                    return finding("skill_recovery_planned", "planned");
                 return current.state === "absent" ? finding("skill_absent", "absent") : finding("skill_update_planned", "planned");
-            // The pending record keeps the replaced fingerprint, so an interrupted update leaves a copy
-            // that setup can still finish or remove.
+            }
+            // The pending record is persisted before any intermediate exists. It names the intermediates
+            // (transaction id), the target and the replaced copy, so an interrupted update can be
+            // recovered, finished or removed from persisted state alone.
             const pending = {
                 target: ownedTarget, fingerprint: desired.fingerprint, previous: "absent", phase: "pending", transactionId: randomUUID(),
                 ...(current.state === "tree" ? { replaces: current.fingerprint } : {}),
@@ -172,11 +223,12 @@ export class FileSetupSkillInstaller {
             healthy(ownership);
             await ownership.put(pending);
             healthy(ownership);
-            await this.replace(path, name, desired, current, ownership);
+            await this.replace(path, name, desired, current, pending, ownership);
             healthy(ownership);
             const after = await inspectSlot(path);
             if (after.state !== "tree" || after.fingerprint !== desired.fingerprint)
                 throw new Error("skill_post_install_mismatch");
+            await this.step("before-ownership");
             healthy(ownership);
             await ownership.put(ownedRecord(pending, desired.fingerprint));
             healthy(ownership);
@@ -186,69 +238,185 @@ export class FileSetupSkillInstaller {
             return finding(operation === "apply" ? "skill_install_failed" : "skill_source_invalid", "failed");
         }
     }
-    async replace(path, name, desired, current, ownership) {
+    /**
+     * Installs the new tree through the transaction's own intermediates. A failure leaves them for
+     * recovery; nothing here deletes by guess.
+     */
+    async replace(path, name, desired, current, record, ownership) {
         const parent = dirname(path);
+        const names = intermediates(path, name, record.transactionId);
         healthy(ownership);
         await ensureParents(parent, ownership);
         healthy(ownership);
-        const temporary = join(parent, `.pi-session-mcp-${name}-${randomUUID()}`);
-        const backup = join(parent, `.pi-session-mcp-${name}-${randomUUID()}`);
-        let staged = false;
-        try {
-            healthy(ownership);
-            await mkdir(temporary, { mode: 0o755 });
-            staged = true;
-            for (const file of desired.files) {
-                healthy(ownership);
-                const destination = join(temporary, ...file.path.split("/"));
-                await ensureParents(dirname(destination), ownership);
-                healthy(ownership);
-                const handle = await open(destination, "wx", 0o644);
-                try {
-                    await handle.writeFile(file.bytes);
-                    await handle.sync();
-                }
-                finally {
-                    await handle.close();
-                }
-            }
-            await syncTreeDirectories(temporary, desired, ownership);
+        healthy(ownership);
+        await mkdir(names.staging, { mode: 0o755 });
+        for (const file of desired.files) {
             healthy(ownership);
-            if (!await sameSlot(path, current))
-                throw new Error("skill_slot_changed");
+            const destination = join(names.staging, ...file.path.split("/"));
+            await ensureParents(dirname(destination), ownership);
             healthy(ownership);
-            if (current.state === "tree") {
-                await rename(path, backup);
-                healthy(ownership);
-                await syncDirectory(parent);
-                healthy(ownership);
+            const handle = await open(destination, "wx", 0o644);
+            try {
+                await handle.writeFile(file.bytes);
+                await handle.sync();
             }
-            await rename(temporary, path);
-            staged = false;
+            finally {
+                await handle.close();
+            }
+        }
+        await syncTreeDirectories(names.staging, desired, ownership);
+        await this.step("staged");
+        healthy(ownership);
+        if (!await sameSlot(path, current))
+            throw new Error("skill_slot_changed");
+        healthy(ownership);
+        if (current.state === "tree") {
+            // A rename onto an existing empty directory would replace it silently.
+            if (await present(names.backup))
+                throw new Error("skill_backup_exists");
+            await rename(path, names.backup);
             healthy(ownership);
             await syncDirectory(parent);
             healthy(ownership);
-            const after = await inspectSlot(path);
-            if (after.state !== "tree" || after.fingerprint !== desired.fingerprint)
-                throw new Error("skill_post_install_mismatch");
-            if (current.state === "tree") {
-                // Delete only the exact old tree moved by this transaction.
-                if (!await sameSlot(backup, current))
-                    throw new Error("skill_backup_changed");
+            await this.step("backup-renamed");
+        }
+        await rename(names.staging, path);
+        healthy(ownership);
+        await syncDirectory(parent);
+        healthy(ownership);
+        await this.step("installed");
+        const after = await inspectSlot(path);
+        if (after.state !== "tree" || after.fingerprint !== desired.fingerprint)
+            throw new Error("skill_post_install_mismatch");
+        if (current.state === "tree")
+            await this.discardBackup(names, current, parent, ownership);
+    }
+    /**
+     * Deletes the backup only after it is verified to be the exact old copy: it is renamed to the
+     * transaction's trash name first, so the deletion never leaves an unverifiable partial tree
+     * under the backup name.
+     */
+    async discardBackup(names, backup, parent, ownership) {
+        if (await present(names.trash))
+            throw new Error("skill_trash_exists");
+        if (!await sameSlot(names.backup, backup))
+            throw new Error("skill_backup_changed");
+        healthy(ownership);
+        await rename(names.backup, names.trash);
+        healthy(ownership);
+        await syncDirectory(parent);
+        healthy(ownership);
+        await this.step("trash-renamed");
+        await this.discardTrash(names, parent, ownership);
+        await this.step("trash-deleted");
+    }
+    /**
+     * Deletes the transaction's trash entry by entry, so a crash leaves only a smaller partial tree.
+     * Callers must have proven the trash to be the complete replaced copy; a later recovery retains
+     * a partial tree instead of deleting it.
+     */
+    async discardTrash(names, parent, ownership) {
+        await removeEntries(names.trash, parent, ownership, () => this.step("trash-entry-removed"));
+    }
+    /**
+     * Settles an interrupted update of the pending record's transaction, inside the ownership
+     * transaction. Only directories with this transaction's exact names are examined, and only
+     * verified ones are deleted: the backup must equal the replaced copy, the staging directory
+     * the target or an interrupted write of it, the trash the complete replaced copy. Anything
+     * else stays and is reported, including a partial or changed trash.
+     * A proven trash is still deleted when a later intermediate (backup or staging) is retained.
+     *
+     * apply, slot absent: a complete staging directory is renamed into the slot (forward);
+     * otherwise a verified backup is moved back. remove and rollback do not restore, they delete
+     * what is verified and leave the slot to the caller.
+     */
+    async recover(operation, path, name, record, library, linkTarget, ownership) {
+        const parent = dirname(path);
+        const names = intermediates(path, name, record.transactionId);
+        const target = record.fingerprint;
+        const previous = record.replaces !== undefined && SKILL_TREE_FINGERPRINT_PATTERN.test(record.replaces) ? record.replaces : undefined;
+        let found = await classifyIntermediates(path, name, record, library, linkTarget);
+        if (found.state === "untouched")
+            return "untouched";
+        let changed = false;
+        if (found.deleteTrash) {
+            await this.discardTrash(names, parent, ownership);
+            changed = true;
+            // Backup and staging are read again once the trash is gone; the slot stays the one first read.
+            found = await classifyIntermediates(path, name, record, library, linkTarget, found.slot);
+        }
+        if (found.state !== "settle")
+            return found.state;
+        const { slot } = found;
+        let { backup, staging } = found;
+        if (operation === "apply" && slot.state === "absent") {
+            if (staging === "complete" || backup.state === "tree") {
+                const source = staging === "complete" ? names.staging : names.backup;
+                const expected = staging === "complete" ? target : previous;
                 healthy(ownership);
-                await rm(backup, { recursive: true });
+                if (!await sameSlot(path, slot))
+                    throw new Error("skill_slot_changed");
+                healthy(ownership);
+                await rename(source, path);
                 healthy(ownership);
                 await syncDirectory(parent);
-            }
-        }
-        finally {
-            // An unhealthy fence retains staged/backup content for conservative recovery.
-            if (staged) {
                 healthy(ownership);
-                await rm(temporary, { recursive: true, force: true });
+                const restored = await inspectSlot(path);
+                if (restored.state !== "tree" || restored.fingerprint !== expected)
+                    throw new Error("skill_recovery_mismatch");
+                changed = true;
+                if (staging === "complete")
+                    staging = "absent";
+                else
+                    backup = { state: "absent" };
             }
         }
+        if (backup.state === "tree") {
+            await this.discardBackup(names, backup, parent, ownership);
+            changed = true;
+        }
+        if (staging !== "absent") {
+            healthy(ownership);
+            await removeEntries(names.staging, parent, ownership);
+            changed = true;
+        }
+        return changed ? "recovered" : "settled";
+    }
+}
+/**
+ * Reads a pending version 2 transaction's slot, trash, backup and staging directory, by their
+ * exact names, and never writes. The slot is only inspected when `known` is not given. Shared by
+ * recovery and the dry-run, so both apply the same rules.
+ *
+ * Only an empty slot, a link or one of setup's two copies can have intermediates settled. A trash
+ * is deletable only while it is the complete replaced copy; a partial or changed trash, a backup
+ * that is not the replaced copy and a foreign staging directory are retained.
+ */
+async function classifyIntermediates(path, name, record, library, linkTarget, known) {
+    const names = intermediates(path, name, record.transactionId);
+    const target = record.fingerprint;
+    const previous = record.replaces !== undefined && SKILL_TREE_FINGERPRINT_PATTERN.test(record.replaces) ? record.replaces : undefined;
+    const slot = known ?? await inspectSlot(path, linkTarget);
+    if (slot.state === "divergent" || (slot.state === "tree" && slot.fingerprint !== target && slot.fingerprint !== previous))
+        return { state: "untouched" };
+    // A trash directory with the transaction's name holds the verified replaced copy, but only
+    // while it is complete: it is deleted only when it still equals the record's replaced
+    // fingerprint. A partial trash (an interrupted deletion) or any changed content cannot be
+    // proven to be setup's own, so it is retained and reported for the operator to settle.
+    let deleteTrash = false;
+    if (await present(names.trash)) {
+        const trash = await inspectSlot(names.trash);
+        if (trash.state !== "tree" || previous === undefined || trash.fingerprint !== previous)
+            return { state: "retained", slot, deleteTrash };
+        deleteTrash = true;
     }
+    const backup = await inspectSlot(names.backup);
+    if (backup.state === "divergent" || (backup.state === "tree" && backup.fingerprint !== previous))
+        return { state: "retained", slot, deleteTrash };
+    const staging = await classifyStaging(names.staging, target, library);
+    if (staging === "foreign")
+        return { state: "retained", slot, deleteTrash };
+    return { state: "settle", slot, deleteTrash, backup, staging };
 }
 function healthy(ownership) { ownership.assertHealthy?.(); }
 /** The owned form of a record, without the replaced fingerprint of a finished update. */
@@ -310,6 +478,109 @@ async function sameSlot(path, expected, linkTarget) {
     return expected.state === "absent" ? actual.state === "absent" :
         expected.state === "tree" && actual.state === "tree" && actual.fingerprint === expected.fingerprint && actual.dev === expected.dev && actual.ino === expected.ino;
 }
+async function present(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/**
+ * The regular files and directories (relative, `/` separated) below a directory, or undefined
+ * unless it is a real directory with only regular files and directories, no hidden entry, and
+ * within the tree limits. A link or special file is never followed or counted as plain.
+ */
+async function collectPlain(root) {
+    const files = [];
+    const directories = [];
+    let bytes = 0;
+    let entries = 0;
+    const visit = async (current, prefix, depth) => {
+        if (depth > MAX_TREE_DEPTH)
+            return false;
+        for (const entry of await readdir(current)) {
+            if (entry.startsWith(".") || ++entries > MAX_TREE_ENTRIES)
+                return false;
+            const path = join(current, entry);
+            const relative = prefix === "" ? entry : `${prefix}/${entry}`;
+            const info = await lstat(path);
+            if (info.isDirectory()) {
+                directories.push(relative);
+                if (!await visit(path, relative, depth + 1))
+                    return false;
+                continue;
+            }
+            if (!info.isFile())
+                return false;
+            bytes += info.size;
+            if (files.length + 1 > MAX_SKILL_TREE_FILES || bytes > MAX_SKILL_TREE_BYTES)
+                return false;
+            files.push(relative);
+        }
+        return true;
+    };
+    try {
+        const info = await lstat(root);
+        return info.isDirectory() && await visit(root, "", 0) ? { files, directories } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * How a staging directory of the pending record relates to its target: `complete` (its tree
+ * equals the target fingerprint), `partial` (an interrupted write: every entry is a regular file
+ * of the target tree whose content equals that file or a prefix of it, or a directory on the path
+ * of one, checked only against the current library tree when it is the record's target),
+ * `absent`, or `foreign`, which is never deleted.
+ */
+async function classifyStaging(staging, target, library) {
+    const staged = await inspectSlot(staging);
+    if (staged.state === "absent")
+        return "absent";
+    if (staged.state === "tree" && staged.fingerprint === target)
+        return "complete";
+    if (!library || library.fingerprint !== target)
+        return "foreign";
+    const plain = await collectPlain(staging);
+    if (!plain)
+        return "foreign";
+    const expected = new Map(library.files.map((file) => [file.path, file.bytes]));
+    const ancestors = new Set();
+    for (const file of library.files)
+        for (let cursor = posix.dirname(file.path); cursor !== "."; cursor = posix.dirname(cursor))
+            ancestors.add(cursor);
+    if (!plain.directories.every((directory) => ancestors.has(directory)))
+        return "foreign";
+    for (const file of plain.files) {
+        const bytes = expected.get(file);
+        if (!bytes)
+            return "foreign";
+        const content = await readFile(join(staging, ...file.split("/")));
+        if (content.length > bytes.length || !bytes.subarray(0, content.length).equals(content))
+            return "foreign";
+    }
+    return "partial";
+}
+/** Removes a verified directory entry by entry and then itself, with directory fsyncs, so a crash leaves a smaller partial tree. */
+async function removeEntries(directory, parent, ownership, afterEntry) {
+    for (const entry of await readdir(directory)) {
+        healthy(ownership);
+        await rm(join(directory, entry), { recursive: true });
+        healthy(ownership);
+        await syncDirectory(directory);
+        await afterEntry?.();
+    }
+    healthy(ownership);
+    await rmdir(directory);
+    healthy(ownership);
+    await syncDirectory(parent);
+    healthy(ownership);
+}
 async function ensureParents(directory, ownership) {
     if (dirname(directory) !== directory)
         await ensureParents(dirname(directory), ownership);