rea-agents 1.1.0 → 1.3.0

package/dist/application/ProcessOwnership.js

@@ -43,7 +43,13 @@ const systemHost = {
         process.kill(-processGroupId, signal);
     },
 };
-/** Verify run-token ownership before signaling a POSIX process group. */
+/**
+ * Verify run-token ownership before signaling a POSIX process group.
+ *
+ * Process IDs and group IDs can be reused. REA therefore re-reads every live
+ * member's environment immediately before signaling and fails closed if any
+ * member cannot be inspected or lacks the per-capture run token.
+ */
 export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
     let members;
     try {
@@ -97,6 +103,38 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     return { cleaned: true, signaled: true };
 };
+/** Observe one group without signaling it, failing closed on identity doubt. */
+export const observeOwnedProcessGroup = async (ownership, host = systemHost) => {
+    let members;
+    try {
+        members = await host.listMembers(ownership.processGroupId);
+    }
+    catch {
+        return {
+            state: "unverifiable",
+            reason: "process group could not be inspected",
+        };
+    }
+    if (members.length === 0)
+        return { state: "empty" };
+    for (const member of members) {
+        try {
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
+                ownership.runId)
+                return {
+                    state: "unverifiable",
+                    reason: "process ownership did not match",
+                };
+        }
+        catch {
+            return {
+                state: "unverifiable",
+                reason: "process ownership could not be revalidated",
+            };
+        }
+    }
+    return { state: "alive" };
+};
 const commandMatches = (actual, expected) => {
     const normalizedActual = actual.trim();
     const normalizedExpected = expected.trim();

package/dist/application/ProcessSampling.js

@@ -24,17 +24,25 @@ const parseProcStat = (identifier, stat) => {
         .split(/\s+/);
     const pid = Number(identifier);
     const parentPid = Number(fields[1]);
+    const processGroupId = Number(fields[2]);
+    const sessionId = Number(fields[3]);
     const startTime = fields[19];
     if (!Number.isSafeInteger(pid) ||
         pid <= 0 ||
         !Number.isSafeInteger(parentPid) ||
         parentPid < 0 ||
+        !Number.isSafeInteger(processGroupId) ||
+        processGroupId <= 0 ||
+        !Number.isSafeInteger(sessionId) ||
+        sessionId <= 0 ||
         startTime === undefined ||
         !/^\d+$/.test(startTime))
         return undefined;
     return {
         pid,
         parent_pid: parentPid,
+        process_group_id: processGroupId,
+        session_id: sessionId,
         command: "",
         startTime,
     };
@@ -104,13 +112,15 @@ const inspectProcess = async (pid, expectedParent, signal, identities) => {
     return {
         pid: before.pid,
         parent_pid: before.parent_pid,
+        process_group_id: before.process_group_id,
+        session_id: before.session_id,
         startTime: before.startTime,
         command,
         children: children ?? [],
     };
 };
 const sampleLinux = async (context) => {
-    const { rootPid, limit, signal, sampledPids, identities } = context;
+    const { rootPid, limit, signal, identities } = context;
     if (limit <= 0)
         return [];
     const rootStat = await readProcessStat(rootPid, signal);
@@ -131,11 +141,9 @@ const sampleLinux = async (context) => {
         for (const node of batchResults) {
             if (node === undefined)
                 continue;
-            if (!sampledPids.has(node.pid)) {
-                if (rows.length >= limit)
-                    break;
-                rows.push(node);
-            }
+            if (rows.length >= limit)
+                break;
+            rows.push(node);
             if (rows.length >= limit)
                 break;
             for (const child of node.children) {
@@ -152,15 +160,17 @@ const sampleLinux = async (context) => {
     return rows;
 };
 const readPsRows = async (signal) => {
-    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,command="], { signal });
+    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,pgid=,sess=,command="], { signal });
     return stdout
         .split("\n")
-        .map((line) => /\s*(\d+)\s+(\d+)\s+(.*)/u.exec(line))
+        .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(.*)/u.exec(line))
         .filter((match) => match !== null)
         .map((match) => ({
         pid: Number(match[1]),
         parent_pid: Number(match[2]),
-        command: match[3] ?? "",
+        process_group_id: Number(match[3]),
+        session_id: Number(match[4]),
+        command: match[5] ?? "",
         startTime: undefined,
     }))
         .filter((row) => Number.isSafeInteger(row.pid) &&
@@ -170,7 +180,7 @@ const readPsRows = async (signal) => {
         .sort((left, right) => left.pid - right.pid);
 };
 const samplePs = async (context) => {
-    const { rootPid, limit, signal, sampledPids } = context;
+    const { rootPid, limit, signal } = context;
     if (limit <= 0)
         return [];
     const rows = await readPsRows(signal);
@@ -194,9 +204,8 @@ const samplePs = async (context) => {
             continue;
         visited.add(pid);
         const row = rowByPid.get(pid);
-        if (row !== undefined && !sampledPids.has(row.pid)) {
+        if (row !== undefined)
             result.push(row);
-        }
         if (result.length >= limit)
             break;
         for (const child of childrenByParent.get(pid) ?? []) {
@@ -212,11 +221,9 @@ const sampleProcesses = async (context) => {
     const rows = process.platform === "linux"
         ? await sampleLinux(context)
         : await samplePs(context);
-    const { elapsedMs, sampledPids, identities } = context;
+    const { elapsedMs, identities } = context;
     const samples = [];
     for (const row of rows) {
-        if (sampledPids.has(row.pid))
-            continue;
         if (row.startTime !== undefined) {
             const existing = identities.get(row.pid);
             if (existing !== undefined && existing !== row.startTime)
@@ -228,6 +235,8 @@ const sampleProcesses = async (context) => {
             pid: row.pid,
             parent_pid: row.parent_pid,
             command: row.command,
+            process_group_id: row.process_group_id,
+            session_id: row.session_id,
         });
     }
     return samples;
@@ -235,31 +244,38 @@ const sampleProcesses = async (context) => {
 /** Start bounded process-tree sampling and expose an awaited stop. */
 export const startProcessSampler = (rootPid, started, limit, samples) => {
     const identities = new Map();
-    const sampledPids = new Set(samples.map(({ pid }) => pid));
+    const lastObservations = new Map();
     let pending;
     let stopped = false;
     let abortCurrent;
     let partial = false;
     const sample = () => {
-        if (stopped || pending !== undefined || sampledPids.size >= limit)
+        if (stopped || pending !== undefined)
             return;
         const controller = new AbortController();
         abortCurrent = () => controller.abort();
         pending = sampleProcesses({
             rootPid,
             elapsedMs: Date.now() - started,
-            limit: limit - sampledPids.size,
-            sampledPids,
+            limit: limit + 1,
             identities,
             signal: controller.signal,
         })
             .then((values) => {
             for (const value of values) {
-                if (sampledPids.size >= limit)
-                    break;
-                if (sampledPids.has(value.pid))
+                const observation = JSON.stringify({
+                    parent_pid: value.parent_pid,
+                    command: value.command,
+                    process_group_id: value.process_group_id,
+                    session_id: value.session_id,
+                });
+                if (lastObservations.get(value.pid) === observation)
+                    continue;
+                if (samples.length >= limit) {
+                    partial = true;
                     continue;
-                sampledPids.add(value.pid);
+                }
+                lastObservations.set(value.pid, observation);
                 samples.push(value);
             }
         })

package/dist/application/ReferenceSourceImportEntries.js

@@ -3,16 +3,31 @@ import { posix } from "node:path";
 import { classifyReferenceSourcePath, detectReferenceSourceLanguage, } from "../domain/referenceSourceClassification.js";
 import { parseReferenceSourceImports } from "../domain/referenceSourceImportParsing.js";
 import { PARSEABLE_REFERENCE_SOURCE_LANGUAGES } from "./ReferenceSourceImportTypes.js";
+/** Project a low-level entry failure into safe import guidance. */
+export const projectReferenceSourceEntryFailure = (entry) => {
+    if (entry.code === "cancelled")
+        return "This entry was not read because the import was cancelled. Start the import again when ready.";
+    if (entry.code === "limit")
+        return "This entry was not read because an import limit was reached. Import a smaller directory or raise the configured limits.";
+    if (entry.code === "unsupported")
+        return "This entry cannot be read safely on this system. Exclude it or import the directory on a supported system.";
+    if (entry.kind === "directory")
+        return "This directory could not be read. Check its permissions, then try again.";
+    if (entry.kind === "symlink")
+        return "This symbolic link could not be read safely. Check the link and its permissions, then try again.";
+    return "This file could not be read. Check its permissions, then try again.";
+};
 const hashBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const failedEntry = (entry) => {
     const classifications = classifyReferenceSourcePath(entry.path);
+    const limitation = projectReferenceSourceEntryFailure(entry);
     if (entry.kind === "directory")
         return {
             path: entry.path,
             kind: "directory",
             classifications,
             tree_state: entry.code === "limit" ? "partial" : "unreadable",
-            limitations: [entry.message],
+            limitations: [limitation],
         };
     if (entry.kind === "symlink")
         return {
@@ -21,7 +36,7 @@ const failedEntry = (entry) => {
             target: "<unreadable>",
             target_state: "unreadable",
             classifications,
-            limitations: [entry.message],
+            limitations: [limitation],
         };
     return {
         path: entry.path,
@@ -31,7 +46,7 @@ const failedEntry = (entry) => {
         language: null,
         classifications: entry.kind === "file" ? classifications : ["unknown"],
         content_state: entry.code === "limit" ? "too-large" : "unreadable",
-        limitations: [entry.message],
+        limitations: [limitation],
     };
 };
 const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {

package/dist/application/ReferenceSourceImportTypes.js

@@ -1,3 +1,35 @@
+/** Safe CLI projection for a historical-source import failure. */
+export const projectReferenceSourceImportError = (error) => {
+    if (error.code === "cancelled")
+        return {
+            category: "cancelled",
+            message: "Reference source import was cancelled. Start it again when ready.",
+        };
+    if (error.code === "invalid-limits")
+        return {
+            category: "invalid_input",
+            message: "Reference source limits are invalid. Use positive integer limits, then try again.",
+        };
+    if (error.code === "invalid-root")
+        return {
+            category: "invalid_input",
+            message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
+        };
+    if (error.code === "policy")
+        return {
+            category: "permission_required",
+            message: "Reference source directory is not approved. Add its directory to `REA_REFERENCE_ROOTS_JSON`, restart REA, then try again.",
+        };
+    if (error.code === "io")
+        return {
+            category: "execution_failure",
+            message: "Reference source files could not be read. Check directory permissions and try again.",
+        };
+    return {
+        category: "execution_failure",
+        message: "Reference source could not be indexed. Check that the source tree is readable, then try again.",
+    };
+};
 export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [
     ".git/",
     ".git/hooks/",

package/dist/application/Setup.js

@@ -9,6 +9,11 @@ import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 import { installMacHopper } from "./MacHopper.js";
+import { configureDetectedClients } from "./SetupClients.js";
+import { installCanonicalSkill } from "./SetupSkill.js";
+import { setupPlan } from "./SetupPlan.js";
+import { setupInstallFailure, } from "./SetupInstallFailure.js";
+export { installCanonicalSkill } from "./SetupSkill.js";
 const registrationCommand = () => process.env.npm_command === "exec"
     ? ["npx", "-y", PRODUCT_IDENTITY.packageName, "mcp"]
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
@@ -33,35 +38,13 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     if (unsupported !== undefined)
         return fail(unsupported);
     let hopperPath = await host.hopperPath();
+    const initialDoctor = await host.doctor();
+    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
+        (name === "hopper-demo-runtime" ||
+            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
+    const installHopper = hopperPath === undefined || linuxHopperRepairNeeded;
     const detectedClients = await host.detectedClients();
-    plannedActions = [
-        ...(hopperPath === undefined
-            ? [
-                {
-                    kind: "install_hopper",
-                    target: host.platform === "darwin"
-                        ? "~/Applications/Hopper Disassembler.app"
-                        : "system package manager",
-                    detail: "Download the official Hopper package, verify it, install it, and open Hopper for activation.",
-                    external: true,
-                },
-            ]
-            : []),
-        ...detectedClients
-            .filter(({ format }) => format !== "unsupported")
-            .map((client) => ({
-            kind: "configure_client",
-            target: client.configPath,
-            detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
-            external: false,
-        })),
-        {
-            kind: "install_skill",
-            target: "~/.agents/skills/rea-analysis/SKILL.md",
-            detail: "Install or update the bundled REA analysis skill.",
-            external: false,
-        },
-    ];
+    plannedActions = setupPlan(host.platform, installHopper, detectedClients);
     let approved = options.approved;
     let interactiveApproval = false;
     if (!approved && confirm !== undefined && !options.structured) {
@@ -77,53 +60,56 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             doctor: await host.doctor(),
             remediation: "Review the setup plan, then rerun interactively or with --yes.",
         };
-    if (hopperPath === undefined &&
-        (interactiveApproval || options.installHopper)) {
-        hopperPath = await host.installHopper();
-        if (hopperPath === undefined)
+    if (installHopper && (interactiveApproval || options.installHopper)) {
+        const installed = await host.installHopper();
+        if (installed.status === "failed")
             return {
                 status: "needs_human",
                 plannedActions,
                 appliedActions,
                 clients,
                 doctor: await host.doctor(),
-                remediation: "Hopper installation failed; install Hopper manually or rerun setup after resolving the reported system error.",
+                code: installed.code,
+                remediation: installed.remediation,
             };
+        hopperPath = installed.launcherPath;
         appliedActions.push("installed_hopper");
     }
-    for (const client of detectedClients) {
-        const result = await host.configureClient(client, hopperPath, registrationCommand());
-        clients[client.name] = result;
-        if (result.status === "failed")
-            return fail(`${client.name} configuration ${result.reason} verification failed; no successful configuration was reported.`);
-        if (result.status === "configured")
-            appliedActions.push(`configured_${client.name}`);
-    }
+    const clientFailure = await configureDetectedClients({
+        host,
+        detectedClients,
+        hopperPath,
+        command: registrationCommand(),
+        clients,
+        appliedActions,
+    });
+    if (clientFailure !== undefined)
+        return fail(clientFailure);
     const skill = await host.installSkill();
     if (skill === "failed")
-        return fail("Agent skill installation or readback failed.");
+        return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
     if (skill === "installed")
         appliedActions.push("installed_skill");
     const doctor = await host.doctor();
-    const activationRequired = appliedActions.includes("installed_hopper");
-    const ready = doctor.healthy && !activationRequired;
+    const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
     return {
-        status: ready ? "ready" : "needs_human",
+        status: remediation === undefined ? "ready" : "needs_human",
         plannedActions,
         appliedActions,
         clients,
         doctor,
-        ...(ready
-            ? {}
-            : {
-                remediation: activationRequired
-                    ? "Open Hopper, complete its one-time activation, then rerun rea doctor --json."
-                    : hopperPath === undefined
-                        ? "Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis."
-                        : "Run rea doctor and apply each reported remediation.",
-            }),
+        ...(remediation === undefined ? {} : { remediation }),
     };
 };
+const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) => {
+    if (platform === "darwin" && installedHopper)
+        return "Open Hopper, choose its demo mode or activate a license, then rerun rea doctor --json.";
+    if (healthy)
+        return undefined;
+    return hopperPath === undefined
+        ? "Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis."
+        : "Run rea doctor and apply each reported remediation.";
+};
 const hostRemediation = async (host) => {
     if (host.platform !== "darwin" && host.platform !== "linux")
         return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
@@ -152,7 +138,9 @@ const systemSetupHost = () => {
             const result = process.platform === "linux"
                 ? await installLinuxHopper()
                 : await installMacHopper();
-            return result.status === "installed" ? result.launcherPath : undefined;
+            if (result.status === "installed")
+                return result;
+            return setupInstallFailure(result.reason);
         },
         detectedClients: () => detectClients(homedir()),
         configureClient: (client, hopperPath, command) => client.format === "unsupported"
@@ -164,7 +152,7 @@ const systemSetupHost = () => {
         doctor: () => runDoctor(undefined, doctorHost),
     };
 };
-/** Detect supported coding agents from stable per-user installation markers. */
+/** Detect supported agents from stable per-user installation markers. */
 export const detectClients = async (home) => {
     const detected = [];
     for (const candidate of supportedClients(home))
@@ -353,46 +341,6 @@ export const configureTomlClient = async (client, hopperPath, command = [
         ...(backupPath === undefined ? {} : { backupPath }),
     };
 };
-/** Transactionally install or upgrade the versioned canonical REA skill. */
-export const installCanonicalSkill = async (home) => {
-    const destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
-    const backup = `${destination}.rea.backup`;
-    let original;
-    try {
-        const content = await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8");
-        original = await readFile(destination, "utf8").catch(() => undefined);
-        if (original === content)
-            return "unchanged";
-        await mkdir(dirname(destination), { recursive: true });
-        if (original !== undefined)
-            await writeFileAtomic(backup, original, {
-                encoding: "utf8",
-                mode: 0o600,
-            });
-        await writeFileAtomic(destination, content, {
-            encoding: "utf8",
-            mode: 0o600,
-        });
-        if ((await readFile(destination, "utf8")) !== content)
-            throw new Error("skill readback mismatch");
-        return "installed";
-    }
-    catch {
-        try {
-            if (original === undefined)
-                await rm(destination, { force: true });
-            else
-                await writeFileAtomic(destination, original, {
-                    encoding: "utf8",
-                    mode: 0o600,
-                });
-        }
-        catch {
-            // The backup remains beside the skill for explicit operator recovery.
-        }
-        return "failed";
-    }
-};
 const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
 const exists = async (path) => {
     try {

package/dist/application/SetupClients.js

@@ -0,0 +1,19 @@
+const failedConfigurationMessage = (reason) => {
+    if (reason === "backup")
+        return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";
+    if (reason === "write")
+        return "Agent configuration could not be updated. Check file permissions, then rerun setup.";
+    return "Agent configuration could not be verified after writing. Repair the configuration file or restore its `.rea.backup`, then rerun setup.";
+};
+/** Configure each detected agent, stopping after the first failed transaction. */
+export const configureDetectedClients = async (options) => {
+    for (const client of options.detectedClients) {
+        const result = await options.host.configureClient(client, options.hopperPath, options.command);
+        options.clients[client.name] = result;
+        if (result.status === "failed")
+            return failedConfigurationMessage(result.reason);
+        if (result.status === "configured")
+            options.appliedActions.push(`configured_${client.name}`);
+    }
+    return undefined;
+};

package/dist/application/SetupInstallFailure.js

@@ -0,0 +1,53 @@
+/** Map provider installer failures to stable setup codes and safe recovery. */
+export const setupInstallFailure = (reason) => {
+    switch (reason) {
+        case "unsupported_host":
+            return {
+                status: "failed",
+                code: "unsupported_host",
+                remediation: "Use a supported host, then rerun rea setup.",
+            };
+        case "integrity":
+            return {
+                status: "failed",
+                code: "integrity_mismatch",
+                remediation: "The Hopper download failed integrity verification. Retry setup; if it repeats, update REA before installing.",
+            };
+        case "authorization_or_package_manager":
+            return {
+                status: "failed",
+                code: "authorization_or_package_manager_failed",
+                remediation: "Allow the system package-manager operation or install the planned Hopper package and Linux runtime dependencies, then rerun rea setup.",
+            };
+        case "launcher_missing":
+            return {
+                status: "failed",
+                code: "launcher_missing",
+                remediation: "The package operation completed but Hopper is not runnable. Run rea doctor and repair the reported launcher issue.",
+            };
+        case "runtime_dependencies":
+            return {
+                status: "failed",
+                code: "runtime_dependency_unavailable",
+                remediation: "Hopper was installed but required shared libraries are missing. Rerun rea setup, then apply the hopper-demo-runtime remediation from rea doctor.",
+            };
+        case "unsupported_hopper_build":
+            return {
+                status: "failed",
+                code: "unsupported_hopper_build",
+                remediation: "The installed Hopper launcher does not match the build supported by this REA release. Unset HOPPER_LAUNCHER_PATH, reinstall through rea setup, or update REA.",
+            };
+        case "cancelled":
+            return {
+                status: "failed",
+                code: "setup_cancelled",
+                remediation: "Setup was cancelled before Hopper was installed. Rerun rea setup when ready.",
+            };
+        default:
+            return {
+                status: "failed",
+                code: "download_failed",
+                remediation: "REA could not download or unpack the official Hopper package. Check network and filesystem access, then retry setup.",
+            };
+    }
+};

package/dist/application/SetupPlan.js

@@ -0,0 +1,31 @@
+/** Build the complete setup mutation plan before approval. */
+export const setupPlan = (platform, installHopper, clients) => [
+    ...(installHopper
+        ? [
+            {
+                kind: "install_hopper",
+                target: platform === "darwin"
+                    ? "~/Applications/Hopper Disassembler.app"
+                    : "system package manager",
+                detail: platform === "linux"
+                    ? "Download, verify, and install Hopper plus its Xvfb demo-session dependencies. For the supported demo build, REA uses a private display and selects Hopper's offered demo mode for each analysis session."
+                    : "Download the official Hopper package, verify it, and install it. Hopper may show its demo or license prompt when first opened.",
+                external: true,
+            },
+        ]
+        : []),
+    ...clients
+        .filter(({ format }) => format !== "unsupported")
+        .map((client) => ({
+        kind: "configure_client",
+        target: client.configPath,
+        detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
+        external: false,
+    })),
+    {
+        kind: "install_skill",
+        target: "~/.agents/skills/rea-analysis/SKILL.md",
+        detail: "Install or update the bundled REA analysis skill.",
+        external: false,
+    },
+];

package/dist/application/SetupSkill.js

@@ -0,0 +1,44 @@
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { PRODUCT_IDENTITY } from "../identity.js";
+/** Transactionally install or upgrade the versioned canonical REA skill. */
+export const installCanonicalSkill = async (home) => {
+    const destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
+    const backup = `${destination}.rea.backup`;
+    let original;
+    try {
+        const content = await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8");
+        original = await readFile(destination, "utf8").catch(() => undefined);
+        if (original === content)
+            return "unchanged";
+        await mkdir(dirname(destination), { recursive: true });
+        if (original !== undefined)
+            await writeFileAtomic(backup, original, {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+        await writeFileAtomic(destination, content, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        if ((await readFile(destination, "utf8")) !== content)
+            throw new Error("skill readback mismatch");
+        return "installed";
+    }
+    catch {
+        try {
+            if (original === undefined)
+                await rm(destination, { force: true });
+            else
+                await writeFileAtomic(destination, original, {
+                    encoding: "utf8",
+                    mode: 0o600,
+                });
+        }
+        catch {
+            // The backup remains beside the skill for explicit operator recovery.
+        }
+        return "failed";
+    }
+};