superpowers-manager 0.8.0 → 0.9.0

package/dist/harnesses/pi/install.js

@@ -1,20 +1,19 @@
 import { randomBytes } from "node:crypto";
-import { cp, lstat, mkdir, open, readFile, readdir, rm, rmdir, unlink, } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { cp, mkdir, readdir, rm } from "node:fs/promises";
 import { failureResult, successResult, } from "../../adapter-result.js";
-import { atomicWriteFile, beginDirectoryPublication, } from "../../atomic.js";
+import { beginDirectoryPublication, } from "../../atomic.js";
 import { digestArtifactTree } from "../../artifact-tree.js";
 import { normalizeSnapshotRuntimeVersion } from "../../harness-command-result.js";
 import { runPi } from "./native.js";
 import { readPiPackageAssessment, readPiReceipt, } from "./package.js";
 import { piPaths } from "./paths.js";
-import { readPiSettings, resolveCanonicalPiLocalSource, } from "./settings.js";
+import { readPiSettings } from "./settings.js";
 import { inspectPiControl, inspectPiOwnership, } from "./state.js";
 import { assertNoFollowType, canonicalizeProspectivePath, classifyPathNoFollow, } from "../../safe-path.js";
+import { createJournal, createSnapshotJournal, hasRecovery, identity, journalPath, publicationPaths, requireNoRecovery, } from "../../snapshot-journal.js";
 const DEFAULTS = {
     run: runPi,
     beginPublication: beginDirectoryPublication,
-    readSettings: readPiSettings,
 };
 function fail(code, message) {
     return failureResult("pi-lifecycle", code, message, [], []);
@@ -24,20 +23,6 @@ function accepted(result) {
         throw new Error("Pi operation did not succeed");
     return result.outcome.result;
 }
-function sameIdentity(a, b) {
-    return a.dev === b.dev && a.ino === b.ino;
-}
-async function identity(path) {
-    await assertNoFollowType(path, ["directory"]);
-    return await lstat(path);
-}
-async function requireIdentity(path, expected) {
-    if (!sameIdentity(await identity(path), expected))
-        throw new Error("Pi directory changed");
-}
-function journalPath(p) {
-    return join(p.paths.recoveryRoot, "transaction.json");
-}
 function journalBytes(journal) {
     return Buffer.from(JSON.stringify(journal) + "\n");
 }
@@ -47,38 +32,15 @@ async function validatePaths(paths) {
     await assertNoFollowType(paths.installedRoot, ["directory", "missing"]);
     return await canonicalizeProspectivePath(paths.installedRoot);
 }
-async function requireNoRecovery(paths) {
-    await assertNoFollowType(paths.recoveryRoot, ["missing"]);
-}
-async function syncDirectoryStrict(path) {
-    const directory = await open(path, "r");
-    try {
-        await directory.sync();
-    }
-    finally {
-        await directory.close();
-    }
-}
-async function hasRecovery(paths) {
-    try {
-        return (await classifyPathNoFollow(paths.recoveryRoot)) !== "missing";
-    }
-    catch {
-        return true;
-    }
-}
-async function registration(paths, deps) {
-    const settings = await deps.readSettings(paths.settingsFile, paths.homeDir);
-    const canonicalRoot = await canonicalizeProspectivePath(paths.installedRoot);
-    const matches = [];
-    for (const entry of settings.packages) {
-        if ((await resolveCanonicalPiLocalSource(entry.source, paths.agentDir, paths.homeDir)) === canonicalRoot) {
-            matches.push(entry);
-        }
-    }
-    if (matches.length > 1)
-        throw new Error("duplicate Pi registration");
-    return matches[0] ?? null;
+const { requireIdentity, requireJournal, phase, retireJournal } = createSnapshotJournal({
+    label: "Pi",
+    validatePaths,
+    serialize: journalBytes,
+    readCap: 64 * 1024,
+});
+async function registration(paths) {
+    return (await readPiSettings(paths.settingsFile, paths.homeDir))
+        .managerRegistration;
 }
 function sameRegistration(a, b) {
     return a === null
@@ -115,39 +77,6 @@ async function requireSnapshot(root, expected) {
     if (!sameArtifact(await snapshot(root), expected))
         throw new Error("Pi artifact changed");
 }
-async function requireJournal(p) {
-    if ((await validatePaths(p.paths)) !== p.canonicalRoot ||
-        p.journal.installedRoot !== p.canonicalRoot ||
-        !/^[a-f0-9]{32}$/u.test(p.journal.token))
-        throw new Error("Pi recovery root changed");
-    await requireIdentity(p.paths.recoveryRoot, p.recoveryIdentity);
-    const path = journalPath(p);
-    await assertNoFollowType(path, ["regular-file"]);
-    const stat = await lstat(path);
-    if (!sameIdentity(stat, p.journalIdentity) ||
-        stat.size > 64 * 1024 ||
-        !(await readFile(path)).equals(journalBytes(p.journal)))
-        throw new Error("Pi recovery journal changed");
-    if (p.backup !==
-        join(dirname(p.canonicalRoot), `.${basename(p.canonicalRoot)}.bak.${p.journal.token}`) ||
-        p.stage !==
-            join(dirname(p.canonicalRoot), `.${basename(p.canonicalRoot)}.stage.${p.journal.token}`))
-        throw new Error("Pi recovery paths changed");
-}
-async function phase(p, next, changes = {}) {
-    await requireJournal(p);
-    const journal = { ...p.journal, ...changes, phase: next };
-    const bytes = journalBytes(journal);
-    await atomicWriteFile(journalPath(p), bytes, {
-        validate: async (temporary) => {
-            if (!(await readFile(temporary)).equals(bytes))
-                throw new Error("Pi journal write changed");
-        },
-    });
-    await syncDirectoryStrict(p.paths.recoveryRoot);
-    p.journal = journal;
-    p.journalIdentity = await lstat(journalPath(p));
-}
 async function beginJournal(paths, oldArtifact, newArtifact, priorRegistration, ctx, deps) {
     const canonicalRoot = await validatePaths(paths);
     await mkdir(paths.managerRoot, { recursive: true });
@@ -166,38 +95,20 @@ async function beginJournal(paths, oldArtifact, newArtifact, priorRegistration,
         createdRegistration: null,
         phase: newArtifact === null ? "removing" : "staging",
     };
-    const path = join(paths.recoveryRoot, "transaction.json");
-    const handle = await open(path, "wx", 0o600);
-    try {
-        await handle.writeFile(journalBytes(journal));
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
     // The first journal is durable before either a staging tree or backup exists.
-    await syncDirectoryStrict(paths.recoveryRoot);
+    const journalIdentity = await createJournal(paths.recoveryRoot, journalBytes(journal));
     return {
         paths,
         canonicalRoot,
         recoveryIdentity,
-        backup: join(dirname(canonicalRoot), `.${basename(canonicalRoot)}.bak.${token}`),
-        stage: join(dirname(canonicalRoot), `.${basename(canonicalRoot)}.stage.${token}`),
+        ...publicationPaths(canonicalRoot, token),
         ctx,
         deps,
         journal,
-        journalIdentity: await lstat(path),
+        journalIdentity,
         settled: false,
     };
 }
-async function retireJournal(p) {
-    await requireJournal(p);
-    if ((await readdir(p.paths.recoveryRoot)).some((name) => name !== "transaction.json"))
-        throw new Error("unknown Pi recovery material");
-    await unlink(journalPath(p));
-    await requireIdentity(p.paths.recoveryRoot, p.recoveryIdentity);
-    await rmdir(p.paths.recoveryRoot);
-}
 async function journalRetirementGuidance(p) {
     try {
         const kind = await classifyPathNoFollow(p.paths.recoveryRoot);
@@ -243,7 +154,7 @@ async function finalizePiPublication(p, publication) {
     let publicationCleanupCompleted = false;
     try {
         await requirePublication(p);
-        const current = await registration(p.paths, p.deps);
+        const current = await registration(p.paths);
         const expectedRegistration = p.journal.priorRegistration ?? p.journal.createdRegistration;
         if (expectedRegistration === null ||
             !sameRegistration(current, expectedRegistration) ||
@@ -273,7 +184,7 @@ async function rollbackPiPublication(p, publication) {
     let retirementStarted = false;
     try {
         await requirePublication(p);
-        const current = await registration(p.paths, p.deps);
+        const current = await registration(p.paths);
         if (p.journal.priorRegistration !== null) {
             if (!sameRegistration(current, p.journal.priorRegistration))
                 throw new Error("prior Pi registration changed");
@@ -288,13 +199,13 @@ async function rollbackPiPublication(p, publication) {
             await p.deps
                 .run(["remove", p.canonicalRoot, "--no-approve"], p.paths, p.ctx)
                 .catch(() => undefined);
-            if ((await registration(p.paths, p.deps)) !== null)
+            if ((await registration(p.paths)) !== null)
                 throw new Error("Pi deregistration unverified");
         }
         await requirePublication(p);
         await publication.rollback();
         await requireSnapshot(p.canonicalRoot, p.journal.oldArtifact);
-        if (!sameRegistration(await registration(p.paths, p.deps), p.journal.priorRegistration))
+        if (!sameRegistration(await registration(p.paths), p.journal.priorRegistration))
             throw new Error("Pi registration restoration unverified");
         await phase(p, "restored");
         retirementStarted = true;
@@ -312,7 +223,7 @@ async function recoverBeforePublication(p) {
         await requireJournal(p);
         await requireSnapshot(p.canonicalRoot, p.journal.oldArtifact);
         await assertNoFollowType(p.backup, ["missing"]);
-        if (!sameRegistration(await registration(p.paths, p.deps), p.journal.priorRegistration))
+        if (!sameRegistration(await registration(p.paths), p.journal.priorRegistration))
             return false;
         if ((await assertNoFollowType(p.stage, ["directory", "missing"])) !==
             "missing") {
@@ -346,13 +257,13 @@ export async function installPi(artifact, ctx, deps = DEFAULTS) {
             throw new Error("Pi prepared artifact changed");
         await requireActivationEligibility(ctx);
         const previous = await snapshot(paths.installedRoot);
-        const priorRegistration = await registration(paths, deps);
+        const priorRegistration = await registration(paths);
         if (previous === null && priorRegistration !== null)
             throw new Error("unowned Pi registration");
         accepted(normalizeSnapshotRuntimeVersion("Pi", await deps.run(["--version"], paths, ctx)));
         // Recheck after the native preflight, before claiming mutation ownership.
         await requireSnapshot(paths.installedRoot, previous);
-        if (!sameRegistration(await registration(paths, deps), priorRegistration))
+        if (!sameRegistration(await registration(paths), priorRegistration))
             throw new Error("Pi registration changed");
         pending = await beginJournal(paths, previous, assessment.receipt, priorRegistration, ctx, deps);
         await mkdir(pending.stage);
@@ -371,20 +282,20 @@ export async function installPi(artifact, ctx, deps = DEFAULTS) {
         await requireIdentity(pending.stage, pending.stageIdentity);
         await requireActivationEligibility(ctx);
         await requireSnapshot(paths.installedRoot, previous);
-        if (!sameRegistration(await registration(paths, deps), priorRegistration))
+        if (!sameRegistration(await registration(paths), priorRegistration))
             throw new Error("Pi registration changed");
         publication = await deps.beginPublication(pending.stage, pending.canonicalRoot, { backupPath: pending.backup });
         pending.publishedIdentity = pending.stageIdentity;
         await phase(pending, "published");
         if (priorRegistration === null) {
             await phase(pending, "registering");
-            if ((await registration(paths, deps)) !== null)
+            if ((await registration(paths)) !== null)
                 throw new Error("Pi registration changed");
             const result = await deps
                 .run(["install", pending.canonicalRoot, "--no-approve"], paths, ctx)
                 .catch(() => fail("native-failed", "Pi native installation failed"));
             // Even an unsuccessful command may have changed settings. Read them first.
-            const registered = await registration(paths, deps);
+            const registered = await registration(paths);
             if (registered === null || registered.resourceState !== "enabled")
                 throw new Error("Pi activation unverified");
             await phase(pending, "registered", {
@@ -393,7 +304,7 @@ export async function installPi(artifact, ctx, deps = DEFAULTS) {
             accepted(result);
         }
         await requirePublication(pending);
-        const registered = await registration(paths, deps);
+        const registered = await registration(paths);
         if (registered === null || registered.resourceState !== "enabled")
             throw new Error("Pi activation unverified");
         await phase(pending, "ready");
@@ -444,7 +355,7 @@ export async function removePi(input, ctx, deps = DEFAULTS) {
             input.receiptDigest !== current.receiptDigest)
             throw new Error("stale Pi removal input");
         const previous = await snapshot(paths.installedRoot);
-        const registered = await registration(paths, deps);
+        const registered = await registration(paths);
         if (previous === null) {
             if (registered !== null)
                 throw new Error("unowned Pi registration");
@@ -453,7 +364,7 @@ export async function removePi(input, ctx, deps = DEFAULTS) {
         if (registered !== null)
             accepted(normalizeSnapshotRuntimeVersion("Pi", await deps.run(["--version"], paths, ctx)));
         await requireSnapshot(paths.installedRoot, previous);
-        if (!sameRegistration(await registration(paths, deps), registered))
+        if (!sameRegistration(await registration(paths), registered))
             throw new Error("Pi registration changed");
         pending = await beginJournal(paths, previous, null, registered, ctx, deps);
         const installedIdentity = await identity(paths.installedRoot);
@@ -461,7 +372,7 @@ export async function removePi(input, ctx, deps = DEFAULTS) {
             const result = await deps
                 .run(["remove", pending.canonicalRoot, "--no-approve"], paths, ctx)
                 .catch(() => fail("native-failed", "Pi native removal failed"));
-            const after = await registration(paths, deps);
+            const after = await registration(paths);
             if (after !== null) {
                 if (sameRegistration(after, registered)) {
                     await requireSnapshot(paths.installedRoot, previous);
@@ -480,7 +391,7 @@ export async function removePi(input, ctx, deps = DEFAULTS) {
         await phase(pending, "deregistered");
         await requireIdentity(paths.installedRoot, installedIdentity);
         await requireSnapshot(paths.installedRoot, previous);
-        if ((await registration(paths, deps)) !== null)
+        if ((await registration(paths)) !== null)
             throw new Error("Pi registration returned");
         await rm(paths.installedRoot, { recursive: true });
         await requireSnapshot(paths.installedRoot, null);

package/dist/harnesses/pi/native.js

@@ -1,37 +1,12 @@
-import { tmpdir } from "node:os";
-import { isAbsolute, resolve, sep } from "node:path";
-import { failureResult, } from "../../adapter-result.js";
-import { nativeCommandResult, } from "../../harness-command-result.js";
+import {} from "../../adapter-result.js";
+import { runIsolatedNative, } from "../../harness-command-result.js";
 import { BOUNDED_EXECUTABLE, runValidator as runBoundedCommand, } from "../../validator.js";
-import { withWorkspace } from "../../workspace.js";
-function selectedExecutable(env, invocationCwd) {
-    const configured = env.SUPERPOWERS_PI || "pi";
-    return configured.includes(sep) && !isAbsolute(configured)
-        ? resolve(invocationCwd, configured)
-        : configured;
-}
 export async function runPi(args, paths, ctx, execute = runBoundedCommand) {
-    const operation = "pi-command";
-    const env = ctx.env ?? {};
-    const invocationCwd = process.cwd();
-    const executable = selectedExecutable(env, invocationCwd);
-    let entered = false;
-    try {
-        return await withWorkspace(env.TMPDIR ?? tmpdir(), "superpowers-manager.pi.", async (workspace) => {
-            entered = true;
-            const result = await execute([executable, ...args], BOUNDED_EXECUTABLE, {
-                ...env,
-                HOME: paths.homeDir,
-                PI_CODING_AGENT_DIR: paths.agentDir,
-                PI_OFFLINE: "1",
-                PI_SKIP_VERSION_CHECK: "1",
-            }, workspace, workspace);
-            return nativeCommandResult("Pi", result);
-        });
-    }
-    catch {
-        return failureResult(operation, "workspace-failed", entered
-            ? "cannot complete Pi command in its isolated workspace"
-            : "cannot create an isolated Pi command workspace", [], []);
-    }
+    return await runIsolatedNative("Pi", (ctx.env ?? {}).SUPERPOWERS_PI || "pi", ctx, async (executable, workspace, env) => await execute([executable, ...args], BOUNDED_EXECUTABLE, {
+        ...env,
+        HOME: paths.homeDir,
+        PI_CODING_AGENT_DIR: paths.agentDir,
+        PI_OFFLINE: "1",
+        PI_SKIP_VERSION_CHECK: "1",
+    }, workspace, workspace));
 }

package/dist/harnesses/pi/package.js

@@ -1,51 +1,10 @@
-import { join } from "node:path";
-import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, digestArtifactTree, readArtifactObject, } from "../../artifact-tree.js";
-import { COMMIT_RE } from "../../domain/refs.js";
-import { SafetyError } from "../../safety-error.js";
-import { validateSource } from "../../selection.js";
+import { createSnapshotReceipts, } from "../../snapshot-package.js";
 import { assessPiCompatibility } from "./compatibility.js";
-import { snapshotReceiptBinding } from "../../snapshot-package.js";
-export async function readPiReceipt(root) {
-    const path = join(root, ARTIFACT_RECEIPT);
-    try {
-        const value = await readArtifactObject(root, path);
-        if (value.schema !== 1 ||
-            value.manager !== "superpowers-manager" ||
-            value.harness !== "pi" ||
-            typeof value.source !== "string" ||
-            typeof value.commit !== "string" ||
-            !COMMIT_RE.test(value.commit) ||
-            typeof value.digest !== "string" ||
-            !ARTIFACT_DIGEST_RE.test(value.digest) ||
-            typeof value.binding !== "string" ||
-            !ARTIFACT_DIGEST_RE.test(value.binding))
-            throw new Error("receipt fields");
-        validateSource(value.source);
-        if (snapshotReceiptBinding(value) !== value.binding)
-            throw new Error("receipt binding");
-        const compatibility = value.compatibility;
-        if (!compatibility ||
-            typeof compatibility !== "object" ||
-            Array.isArray(compatibility) ||
-            typeof compatibility.reason !== "string" ||
-            typeof compatibility.kind !== "string" ||
-            !["unknown", "unsupported", "supported", "experimental"].includes(compatibility.kind) ||
-            ((compatibility.kind === "supported" ||
-                compatibility.kind === "experimental") &&
-                typeof compatibility.generation !== "string"))
-            throw new Error("receipt compatibility");
-        return value;
-    }
-    catch (cause) {
-        throw new SafetyError("pi-package", `invalid Pi artifact receipt: ${path}`, { cause });
-    }
-}
-export async function readPiPackageAssessment(root) {
-    const receipt = await readPiReceipt(root);
-    if ((await digestArtifactTree(root)) !== receipt.digest)
-        throw new SafetyError("pi-package", `Pi artifact digest mismatch: ${root}`);
-    const compatibility = await assessPiCompatibility(root, {
-        effectiveSource: receipt.source,
-    });
-    return { receipt, compatibility };
-}
+const receipts = createSnapshotReceipts({
+    harness: "pi",
+    label: "Pi",
+    strictGeneration: false,
+    assessCompatibility: assessPiCompatibility,
+});
+export const readPiReceipt = receipts.readReceipt;
+export const readPiPackageAssessment = receipts.readAssessment;

package/dist/harnesses/pi/prepare.js

@@ -1,20 +1,15 @@
 import { createSnapshotPreparation } from "../../snapshot-prepare.js";
-import { piPaths } from "./paths.js";
 import { assessPiCompatibility } from "./compatibility.js";
 import { readPiPackageAssessment } from "./package.js";
-export function piPreparationLocation(ctx) {
-    return {
-        destinationRoot: piPaths(ctx.env ?? {}, process.cwd()).preparedRoot,
-        stagingLeaf: "superpowers",
-    };
-}
+import { piPaths } from "./paths.js";
 const preparation = createSnapshotPreparation({
     harness: "pi",
     label: "Pi",
-    preparationLocation: piPreparationLocation,
+    paths: piPaths,
     assessCompatibility: assessPiCompatibility,
     readAssessment: readPiPackageAssessment,
 });
+export const piPreparationLocation = preparation.preparationLocation;
 export const preparePiCandidate = preparation.prepareCandidate;
 export const inspectPiPrepared = preparation.inspectPrepared;
 export const readPiPrepared = preparation.readPrepared;

package/dist/harnesses/pi/presentation.js

@@ -1,4 +1,4 @@
-import { createSnapshotPresentation } from "../../snapshot-presentation.js";
+import { createSnapshotPresentation, probeOutput, } from "../../snapshot-presentation.js";
 const renderProbe = (facts) => {
     const fields = [
         ["harness", "pi"],
@@ -14,11 +14,6 @@ const renderProbe = (facts) => {
         ["compatibility_reason", facts.compatibility.reason],
         ["status", facts.status],
     ];
-    return {
-        human: fields
-            .map(([key, value]) => `${key.replaceAll("_", " ")}: ${value || "not present"}\n`)
-            .join(""),
-        porcelain: fields.map(([key, value]) => `${key}=${value}\n`).join(""),
-    };
+    return probeOutput(fields);
 };
 export const piPresentation = createSnapshotPresentation("Pi", renderProbe, (input) => input.receiptDigest === null && input.registrationIdentity === null);

package/dist/harnesses/pi/settings.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { canonicalizeProspectivePath } from "../../safe-path.js";
+import { canonicalizeProspectivePath, isErrno } from "../../safe-path.js";
 import { SafetyError } from "../../safety-error.js";
 import { parseStrictJson, } from "../../strict-json.js";
 const SETTINGS_PROFILE = {
@@ -88,12 +88,6 @@ function parsePackage(value, index, path) {
         }),
     };
 }
-function isMissing(cause) {
-    return (typeof cause === "object" &&
-        cause !== null &&
-        "code" in cause &&
-        cause.code === "ENOENT");
-}
 export function resolvePiLocalSource(source, agentDir, homeDir) {
     let normalized = source.trim();
     if (normalized.length === 0 ||
@@ -127,8 +121,9 @@ export async function readPiSettings(path, homeDir) {
         bytes = await readFile(path);
     }
     catch (cause) {
-        if (isMissing(cause))
-            return { packages: [] };
+        if (isErrno(cause, "ENOENT")) {
+            return { packages: [], managerRegistration: null };
+        }
         throw new SafetyError("pi-settings", `cannot read Pi settings ${path}`, {
             cause,
         });
@@ -166,6 +161,7 @@ export async function readPiSettings(path, homeDir) {
     }
     return {
         packages,
+        managerRegistration: managerRegistrations[0] ?? null,
         ...(settings.skills === undefined ? {} : { skills: settings.skills }),
     };
 }

package/dist/harnesses/pi/shared-skills.js

@@ -1,7 +1,12 @@
 import { readdir, readFile, readlink, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
 import { fileURLToPath } from "node:url";
-import { classifyPathNoFollow, isContained } from "../../safe-path.js";
+import { classifyPathNoFollow, isContained, } from "../../safe-path.js";
+// Every caller in this module treats a classification failure as its own
+// indeterminate/false outcome; null carries that failure without a try block.
+function classifyOrNull(path) {
+    return classifyPathNoFollow(path).catch(() => null);
+}
 const PI_IGNORE_FILES = [".gitignore", ".ignore", ".fdignore"];
 function toPosixPath(path) {
     return path.split(sep).join("/");
@@ -9,13 +14,9 @@ function toPosixPath(path) {
 async function ignoreControlState(directory) {
     for (const filename of PI_IGNORE_FILES) {
         const path = join(directory, filename);
-        let kind;
-        try {
-            kind = await classifyPathNoFollow(path);
-        }
-        catch {
+        const kind = await classifyOrNull(path);
+        if (kind === null)
             return "indeterminate";
-        }
         if (kind === "missing")
             continue;
         if (kind !== "regular-file")
@@ -42,13 +43,9 @@ async function collectSharedSkillDirectory(directory) {
         return { kind: "indeterminate" };
     }
     const declaredSkill = join(directory, "SKILL.md");
-    let declaredKind;
-    try {
-        declaredKind = await classifyPathNoFollow(declaredSkill);
-    }
-    catch {
+    const declaredKind = await classifyOrNull(declaredSkill);
+    if (declaredKind === null)
         return { kind: "indeterminate" };
-    }
     if (declaredKind === "regular-file") {
         return { kind: "candidates", paths: [declaredSkill] };
     }
@@ -68,13 +65,9 @@ async function collectSharedSkillDirectory(directory) {
         if (entry.name === "SKILL.md")
             return { kind: "indeterminate" };
         const path = join(directory, entry.name);
-        let kind;
-        try {
-            kind = await classifyPathNoFollow(path);
-        }
-        catch {
+        const kind = await classifyOrNull(path);
+        if (kind === null)
             return { kind: "indeterminate" };
-        }
         if (kind === "symlink" || kind === "missing") {
             return { kind: "indeterminate" };
         }
@@ -96,38 +89,26 @@ async function collectSharedPiSkills(paths) {
     const skillsRoot = join(agentsRoot, "skills");
     const sharedRoot = join(skillsRoot, "superpowers");
     for (const directory of [agentsRoot, skillsRoot]) {
-        let kind;
-        try {
-            kind = await classifyPathNoFollow(directory);
-        }
-        catch {
+        const kind = await classifyOrNull(directory);
+        if (kind === null)
             return { kind: "indeterminate" };
-        }
         if (kind === "missing")
             return { kind: "none" };
         if (kind !== "directory")
             return { kind: "indeterminate" };
     }
-    let sharedRootKind;
-    try {
-        sharedRootKind = await classifyPathNoFollow(sharedRoot);
-    }
-    catch {
+    const sharedRootKind = await classifyOrNull(sharedRoot);
+    if (sharedRootKind === null)
         return { kind: "indeterminate" };
-    }
     if (sharedRootKind === "missing")
         return { kind: "none" };
     if ((await ignoreControlState(skillsRoot)) === "indeterminate") {
         return { kind: "indeterminate" };
     }
     const discoveryRootSkill = join(skillsRoot, "SKILL.md");
-    let discoveryRootSkillKind;
-    try {
-        discoveryRootSkillKind = await classifyPathNoFollow(discoveryRootSkill);
-    }
-    catch {
+    const discoveryRootSkillKind = await classifyOrNull(discoveryRootSkill);
+    if (discoveryRootSkillKind === null)
         return { kind: "indeterminate" };
-    }
     if (discoveryRootSkillKind === "regular-file")
         return { kind: "none" };
     if (discoveryRootSkillKind !== "missing") {
@@ -248,13 +229,8 @@ async function hasSafeSharedSkillAncestors(path, sharedRoot) {
         directories.push(cursor);
     }
     for (const directory of directories) {
-        try {
-            if ((await classifyPathNoFollow(directory)) !== "directory")
-                return false;
-        }
-        catch {
+        if ((await classifyOrNull(directory)) !== "directory")
             return false;
-        }
     }
     return true;
 }
@@ -305,11 +281,8 @@ async function explicitSharedSkillActivities(settings, paths) {
             }
             continue;
         }
-        let lexicalKind;
-        try {
-            lexicalKind = await classifyPathNoFollow(path);
-        }
-        catch {
+        const lexicalKind = await classifyOrNull(path);
+        if (lexicalKind === null) {
             if (isContained(sharedRoot, path) || isContained(path, sharedRoot)) {
                 indeterminate = true;
             }
@@ -343,11 +316,8 @@ async function explicitSharedSkillActivities(settings, paths) {
             isContained(canonicalPath, canonicalSharedRoot);
         if (!related)
             continue;
-        let canonicalKind;
-        try {
-            canonicalKind = await classifyPathNoFollow(canonicalPath);
-        }
-        catch {
+        const canonicalKind = await classifyOrNull(canonicalPath);
+        if (canonicalKind === null) {
             indeterminate = true;
             continue;
         }