@ahood/cli 0.8.6 → 0.8.8

package/README.md

@@ -81,13 +81,15 @@ Requires Node.js 18 or later.
 | `AHOOD_API_URL` | Overrides the registry endpoint (default: `https://ahood.vercel.app`). Must be `https://`, except for `localhost`/`127.0.0.1` or a `.test`/`.invalid`/`.example`/`.localhost` host, which may use plain `http://` for local development. |
 | `XDG_CONFIG_HOME` | If set, browser-login credentials are stored under `$XDG_CONFIG_HOME/ahood/credentials.json` instead of the default `~/.config/ahood/credentials.json`. |
 
-Paths `ahood` reads and writes in your project, none of which need to be gitignored (the lockfile is meant to be committed, same as `package-lock.json`):
+Paths `ahood` reads and writes in your project. The lockfile is meant to be committed, same as `package-lock.json`:
 
 | Path | What's in it |
 | --- | --- |
 | `.claude/skills/<owner>@<skill>/` | Installed skill files. |
 | `.claude/agents/<owner>@<skill>.md` | An installed agent, as a single file (`@` owner/skill separator, since Claude Code's own subagent loader scans `.claude/agents/*.md` flat, non-recursively). |
 | `.claude/skills.lock.json` | Exact installed version + checksum per skill or agent, written by `add`/`update`, read by every install to verify integrity. |
+| `.mcp.json` | MCP server entries, for `mcp`-kind artifacts only. Merged into rather than owned — other MCP clients share this file. **May contain secrets in plaintext**, since a server manifest can declare credentials that `add` prompts for; `add` warns when it writes one. |
+| `*.json.tmp-<pid>-<hrtime>` | Never, in normal operation. Writes to the two `.json` files above go through a temp file that is renamed into place, and only a hard kill (SIGKILL, OOM, power loss) mid-write can strand one. A stranded copy of `.mcp.json` carries the same plaintext secrets, so **gitignore this pattern**. The next successful write removes any left by a process that is no longer running. |
 
 ## Usage examples
 

package/dist/commands/add.js

@@ -114,7 +114,7 @@ export async function extractTarGz(buffer, destDir) {
             const fullPath = resolve(destDir, entryPath);
             if (fullPath !== resolvedDest && !fullPath.startsWith(resolvedDest + sep)) {
                 stream.resume();
-                reject(new Error(`Refusing to extract unsafe archive entry: ${header.name}`));
+                reject(new Error(`Refusing to extract unsafe archive entry: ${sanitizeForTerminal(header.name)}`));
                 // next() is deliberately NOT called -- nothing further in this archive
                 // should be processed. destroy() tears the paused extractor down
                 // rather than leaving it stalled mid-entry.
@@ -237,17 +237,24 @@ export async function extractSingleFileContent(buffer, entryName) {
         throw new Error(`${entryName} not found in the downloaded archive`);
     return found;
 }
-// Every manifest field used below reaches the terminal (an error message, or
+// Every manifest field used below -- and every tar entry name extractTarGz
+// quotes back in an error above -- reaches the terminal (an error message, or
 // -- worse -- the text printed immediately before a masked secret prompt)
-// but comes verbatim from a third-party-published server.json: server-side
+// but comes verbatim from a third-party-published archive: server-side
 // validation only checks these are strings, not that they're free of
 // control/escape characters. A malicious description could otherwise smuggle
 // a terminal control sequence (cursor movement, line-clear) that repaints
 // what the user sees at the exact moment they're about to type a credential.
 // Strips C0/C1 control characters (including ESC, \x1b) and caps length so a
 // single field can't also flood the terminal.
+//
+// Takes `unknown` rather than `string` because every caller's "string" is a
+// declared type over an unchecked `as ServerManifest` cast of downloaded JSON,
+// not a guarantee: calling .replace() directly on a `registry_type: 123` would
+// turn a diagnosable message into the raw TypeError ahood-cli#121 removed from
+// this same path (ahood-cli#122).
 function sanitizeForTerminal(text) {
-    return text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 200);
+    return String(text).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 200);
 }
 // Only npm+npx is supported in v1 (docs/superpowers/specs/2026-09-03-mcp-server-artifacts-design.md) --
 // server-side publish validation (lib/publish/parse-server-manifest.ts) already
@@ -260,7 +267,7 @@ function buildMcpServerConfig(manifest, env) {
     if (manifest.packages && manifest.packages.length === 1) {
         const pkg = manifest.packages[0];
         if (pkg.registry_type !== "npm" || pkg.runtime_hint !== "npx") {
-            throw new Error(`${manifestName}'s server.json uses registry_type "${pkg.registry_type}"/runtime_hint "${pkg.runtime_hint}", which this version of ahood does not know how to install (only npm+npx is supported).`);
+            throw new Error(`${manifestName}'s server.json uses registry_type "${sanitizeForTerminal(pkg.registry_type)}"/runtime_hint "${sanitizeForTerminal(pkg.runtime_hint)}", which this version of ahood does not know how to install (only npm+npx is supported).`);
         }
         const config = { command: "npx", args: ["-y", `${pkg.identifier}@${pkg.version}`] };
         if (Object.keys(env).length > 0)
@@ -379,8 +386,8 @@ function assertNoCollision(fileContents, owner, skill) {
             `Remove it manually first if you want to reinstall ${owner}/${skill}.`);
     }
 }
-// Extracts server.json, validates its shape, and resolves every secret
-// environment variable it declares (prompting only for ones not already
+// Extracts server.json, validates its shape, and resolves every
+// environment variable it declares (prompting only for secrets not already
 // set in the shell) -- the part of installing an mcp entry that's identical
 // whether this is a fresh `add` or an `update` moving an existing pin
 // forward. Exported so update.ts's real mcp-update path (ahood-cli#169)
@@ -401,10 +408,38 @@ function assertNoCollision(fileContents, owner, skill) {
 // timeout -- against this CLI's "must never hang" rule -- or, worse, silently
 // bank the first line of unrelated piped input (`echo y | ahood skill
 // update`) as the credential and fingerprint over it.
+//
+// `secretNames` comes back alongside the config because `env` also carries
+// non-secret configuration now (ahood-cli#120): callers that need to know
+// whether what they just wrote to disk is actually a credential can no longer
+// infer it from `env` being non-empty.
 export async function resolveMcpServerConfig(buffer, options = {}) {
     const { existingEnv, allowNonTtyPrompt = true } = options;
     const content = await extractSingleFileContent(buffer, "server.json");
-    const manifest = JSON.parse(content.toString("utf-8"));
+    // Guarded the same way readMcpConfig guards .mcp.json: an unguarded parse
+    // surfaced a raw V8 SyntaxError with a stack instead of this CLI's usual
+    // single-line error (ahood-cli#121). The parser's own message is dropped
+    // rather than run through sanitizeForTerminal, because V8 quotes a snippet
+    // of the offending source in it -- that source is third-party archive
+    // content, and sanitizing would still paste it into the terminal, just
+    // with its control characters flattened.
+    let parsed;
+    try {
+        parsed = JSON.parse(content.toString("utf-8"));
+    }
+    catch {
+        throw new Error("The downloaded archive's server.json is not valid JSON -- this published version is malformed and cannot be installed.");
+    }
+    // Checked before the cast because buildMcpServerConfig immediately reads
+    // properties off the result: valid JSON that isn't an object (`[]`, `"x"`,
+    // `3`, `null`) would otherwise reach it and surface as an unactionable raw
+    // TypeError (ahood-cli#121). Deliberately stops at "is it an object" -- the
+    // manifest's actual shape is buildMcpServerConfig's job just below, and a
+    // second implementation of that check here would be free to drift from it.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("The downloaded archive's server.json is valid JSON but its top level is not an object -- this published version is malformed and cannot be installed.");
+    }
+    const manifest = parsed;
     // Validate the manifest's shape (unsupported registry_type/runtime_hint,
     // or neither a single 'packages' nor a single 'remotes' entry) BEFORE
     // prompting for any secret -- an install/update that's going to be
@@ -414,10 +449,46 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
     // secretEnv is known.
     buildMcpServerConfig(manifest, {});
     const envVars = manifest.packages?.[0]?.environment_variables ?? [];
-    const secretEnv = {};
+    const env = {};
+    // Non-secret variables used to be skipped outright, so a server declaring
+    // one installed into a config that could not start it, with no diagnostic
+    // (ahood-cli#120). They're configuration, not credentials: read them from
+    // the shell, but never prompt -- a prompt here would reintroduce exactly
+    // the unattended-use hazard ahood-cli#169/0.8.2 removed from the update
+    // path, and there is nothing to mask anyway.
+    //
+    // Resolved in a first pass, ahead of any masked prompt below, for the same
+    // reason buildMcpServerConfig is dry-run above and assertNoCollision runs
+    // before installMcpEntry's resolve: an install that's going to be refused
+    // for a missing required variable must not first cost the user a secret
+    // prompt.
+    for (const variable of envVars) {
+        if (variable.is_secret)
+            continue;
+        // Same truthiness rule as the secret branch below: an empty-string env
+        // var reads as "not set" rather than installing an empty value.
+        const fromEnv = process.env[variable.name];
+        if (fromEnv) {
+            env[variable.name] = fromEnv;
+            continue;
+        }
+        // `is_required` was parsed and validated but never consulted at install
+        // time (ahood-cli#120). Optional means optional -- install without it.
+        // Required means the server cannot start without it, so refusing beats
+        // writing a config that is broken in a way nothing reports.
+        if (variable.is_required) {
+            throw new Error(`${sanitizeForTerminal(variable.name)} is required by ${sanitizeForTerminal(manifest.name)} but is not set -- export ${sanitizeForTerminal(variable.name)} and re-run.`);
+        }
+    }
+    // Required-ness is consulted on the secret path only in the one branch
+    // where a secret can still end up unresolved: the unattended update guard
+    // below. Every other branch either resolves a value or prompts for one, so
+    // an `is_required` check there would change nothing (ahood-cli#120).
+    const secretNames = [];
     for (const variable of envVars) {
         if (!variable.is_secret)
             continue;
+        secretNames.push(variable.name);
         const fromEnv = process.env[variable.name];
         // Truthiness, not `!== undefined` -- matches credentials.ts's
         // resolveToken(), the precedent this feature was explicitly modeled on
@@ -425,24 +496,56 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
         // specifically so an empty-string env var falls through to the real
         // source instead of silently installing an empty secret.
         if (fromEnv) {
-            secretEnv[variable.name] = fromEnv;
+            env[variable.name] = fromEnv;
             continue;
         }
         // Ordered after the env var deliberately: exporting the variable stays
         // the way to rotate a credential during an update, rather than being
-        // shadowed by the stale value already on disk.
+        // shadowed by the stale value already on disk. Deliberately not extended
+        // to non-secret variables (ahood-cli#120): carrying a value forward from
+        // .mcp.json is credential-preservation machinery, and a non-secret is
+        // plain configuration that the shell should stay authoritative for.
         const carriedForward = existingEnv?.[variable.name];
         if (carriedForward) {
-            secretEnv[variable.name] = carriedForward;
+            env[variable.name] = carriedForward;
             continue;
         }
         if (!allowNonTtyPrompt && !process.stdin.isTTY) {
+            // Optional means optional here too, exactly as it does on the
+            // non-secret pass above (ahood-cli#126). This guard used to fire for
+            // ANY unresolved secret, so a single artifact declaring an optional
+            // token that nothing had exported aborted the whole `ahood skill
+            // update` walk -- and said the variable "is required" while the
+            // manifest that declared it said otherwise. Announced rather than
+            // silent because skipping and carrying forward leave different entries
+            // in .mcp.json and nothing else distinguishes them; the notice is
+            // confined to this branch, so an interactive `add` (which still prompts
+            // for optional secrets) and a routine update whose credential carries
+            // forward both stay quiet.
+            if (!variable.is_required) {
+                console.warn(`${sanitizeForTerminal(variable.name)} is optional and is not set -- updating ${sanitizeForTerminal(manifest.name)} without it.`);
+                continue;
+            }
             throw new Error(`${sanitizeForTerminal(variable.name)} is required by ${sanitizeForTerminal(manifest.name)} but is not set, and there is no terminal to prompt on -- export ${sanitizeForTerminal(variable.name)} and re-run.`);
         }
-        secretEnv[variable.name] = await promptSecret(`${sanitizeForTerminal(variable.name)} (${sanitizeForTerminal(variable.description)}): `);
+        env[variable.name] = await promptSecret(`${sanitizeForTerminal(variable.name)} (${sanitizeForTerminal(variable.description)}): `);
     }
-    const serverConfig = buildMcpServerConfig(manifest, secretEnv);
-    return { manifest, serverConfig };
+    const serverConfig = buildMcpServerConfig(manifest, env);
+    return { manifest, serverConfig, secretNames };
+}
+// The plaintext-secret warning printed after a successful mcp install/update.
+// Still derived from the config that actually landed on disk -- the property
+// the old bare `serverConfig.env` check was chosen for -- but intersected with
+// the manifest's declared secrets, because `env` now also holds non-secret
+// configuration (ahood-cli#120) and would otherwise warn about credentials
+// for a server that declares none.
+function warnIfSecretsWereWritten(serverConfig, secretNames) {
+    const env = serverConfig.env;
+    if (!env)
+        return;
+    if (!secretNames.some((name) => Object.prototype.hasOwnProperty.call(env, name)))
+        return;
+    console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
 }
 // Fingerprint of exactly what ahood wrote into .mcp.json's mcpServers.<skill>
 // entry, stored in the lockfile alongside the version/checksum pin. Lets
@@ -520,7 +623,7 @@ async function installMcpEntry(owner, skill, meta, buffer) {
     // something that's going to be refused anyway" reasoning, just for the
     // collision check specifically rather than the manifest-shape check.
     assertNoCollision(readMcpConfig(), owner, skill);
-    const { serverConfig } = await resolveMcpServerConfig(buffer);
+    const { serverConfig, secretNames } = await resolveMcpServerConfig(buffer);
     // Read-modify-write under an advisory lock, mirroring lockfile.ts's own
     // writeLockfileEntry: .mcp.json sits right next to the lockfile and can
     // hold other servers' secrets, so it gets the same protection against a
@@ -558,13 +661,8 @@ async function installMcpEntry(owner, skill, meta, buffer) {
     }
     console.log(`Installed ${owner}/${skill}@${meta.version} into ${MCP_CONFIG_PATH} as "${skill}"`);
     // Only the npm+npx package path ever carries secrets into `env` (headers
-    // on a remote entry are static per v1's scope, per buildMcpServerConfig) --
-    // checking the final serverConfig's own `env` key (rather than threading
-    // secretEnv out of resolveMcpServerConfig separately) means this warning
-    // can never drift from what was actually written to disk.
-    if (serverConfig.env && Object.keys(serverConfig.env).length > 0) {
-        console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
-    }
+    // on a remote entry are static per v1's scope, per buildMcpServerConfig).
+    warnIfSecretsWereWritten(serverConfig, secretNames);
 }
 // Re-runs the mcp install flow for an already-installed entry, moving its
 // lockfile pin forward -- update.ts's real mcp-update path (ahood-cli#169).
@@ -610,7 +708,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
     // (no entry on disk at all) there's nothing to carry forward and a genuine
     // prompt is correct.
     const existingEnv = readMcpEntryEnv(existingOnDisk);
-    const { serverConfig } = await resolveMcpServerConfig(buffer, { existingEnv, allowNonTtyPrompt: false });
+    const { serverConfig, secretNames } = await resolveMcpServerConfig(buffer, { existingEnv, allowNonTtyPrompt: false });
     // Read-modify-write under an advisory lock, mirroring installMcpEntry's
     // own pattern. Re-checks the fingerprint here too (not just above) since
     // arbitrary time may have passed since the pre-check -- the download, and
@@ -675,9 +773,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         throw error;
     }
     console.log(`Updated ${key} to ${meta.version}`);
-    if (serverConfig.env && Object.keys(serverConfig.env).length > 0) {
-        console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
-    }
+    warnIfSecretsWereWritten(serverConfig, secretNames);
 }
 // Downloads a specific version's archive and verifies it against the
 // checksum in `meta`, WITHOUT extracting anything -- the shared first half

package/dist/http.js

@@ -37,6 +37,30 @@ export async function apiFetch(path, init = {}) {
     }
 }
 const MAX_ERROR_MESSAGE_LENGTH = 500;
+// The HTML/length checks below (ahood-cli#31) let a *short, non-HTML* body
+// through verbatim, which meant an error string could still carry ANSI escapes
+// straight to the terminal (ahood-cli#127). That matters here more than in the
+// archive-content path ahood-cli#122 hardened, because sanitizeErrorMessage
+// sits on every apiJson call in the CLI -- including `add`, which prints
+// server-sourced text immediately before a masked secret prompt, the exact
+// moment a cursor-movement/line-clear sequence can repaint what the user sees.
+//
+// Control characters are replaced with a space rather than deleted so that
+// stripping can't silently glue two tokens into one misleading word.
+//
+// Newlines (\x0a) and carriage returns (\x0d) are inside this range and are
+// deliberately flattened too: a forged prompt line ("...\n\nEnter your token:")
+// needs no escape sequence at all, just a newline, so preserving them would
+// leave the spoofing half of the threat model open while closing the escape
+// half. The readability cost is small because anything reaching this branch is
+// already capped at MAX_ERROR_MESSAGE_LENGTH -- a few lines' worth of text, not
+// a stack trace.
+//
+// Known duplication: this is the same substitution as `sanitizeForTerminal` in
+// src/commands/add.ts (ahood-cli#122). It is copied rather than shared on
+// purpose -- promoting a shared helper means editing add.ts's call sites, which
+// is follow-up refactor work kept out of this security fix; see ahood-cli#127.
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/g;
 // Defense in depth (ahood-cli#31): the API is expected to never forward a raw
 // upstream error body (an HTML block page from a proxy/WAF, a giant stack
 // trace, etc.) into `error`, but this CLI shouldn't trust that unconditionally
@@ -46,7 +70,7 @@ const MAX_ERROR_MESSAGE_LENGTH = 500;
 export function sanitizeErrorMessage(message) {
     const looksLikeHtml = /<!DOCTYPE|<html[\s>]/i.test(message);
     if (!looksLikeHtml && message.length <= MAX_ERROR_MESSAGE_LENGTH)
-        return message;
+        return message.replace(CONTROL_CHARACTERS, " ");
     // No preview of the raw content: an HTML-shaped body's first bytes are
     // exactly where infra details (e.g. a Cloudflare block page's title, Ray
     // ID) live, so a "helpful" excerpt would leak the same details this

package/dist/lockfile.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
 export function readLockfile(path) {
     if (!existsSync(path))
         return {};
@@ -15,6 +15,63 @@ export function readLockfile(path) {
         throw new Error(`Lockfile at ${path} is corrupted and could not be parsed as JSON. Fix or delete it before continuing.`);
     }
 }
+// Signal 0 doesn't deliver anything, it just probes whether the process could
+// be signaled. ESRCH means it's gone; EPERM means it's alive but owned by
+// someone else, which is conservatively treated as still alive since that
+// can't be disproven. Shared by the stale-lock reclaim (ahood-cli#100) and the
+// stale-temp sweep (ahood-cli#125) so both answer "is the process that left
+// this behind still around?" the same way, rather than growing two divergent
+// staleness rules.
+function isPidDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+// Exactly what the temp name below produces: a decimal pid and a decimal
+// hrtime, nothing else. Anything the user merely happened to name
+// `<basename>.tmp-something` fails this and is left alone -- deleting a file
+// that was never ours is far worse than leaving a stale temp file behind
+// (ahood-cli#125).
+const TEMP_SUFFIX_RE = /^([1-9][0-9]{0,9})-[0-9]{1,25}$/;
+// The finally in writeJsonFileAtomic can't run on SIGKILL, an OOM kill or
+// power loss, so a temp file can still be orphaned in the window between the
+// write and the rename -- and for .mcp.json that orphan holds resolved MCP
+// server secrets under a name nothing else ever removes (ahood-cli#125). The
+// next successful write to the same destination collects them.
+//
+// withLock serializes the writers this CLI itself starts, but a temp file is
+// only provably collectable once the process that created it is gone, so the
+// pid embedded in the name is checked rather than trusting the lock alone. A
+// pid recycled since the last boot can only make a dead writer look alive,
+// which just defers the cleanup; it can never make a live writer look dead, so
+// this never deletes a file still being written.
+function sweepStaleTempFiles(path, ownTempName) {
+    const dir = dirname(path);
+    const prefix = `${basename(path)}.tmp-`;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (entry.name === ownTempName)
+            continue;
+        if (!entry.name.startsWith(prefix))
+            continue;
+        const match = TEMP_SUFFIX_RE.exec(entry.name.slice(prefix.length));
+        if (!match)
+            continue;
+        if (!isPidDead(Number(match[1])))
+            continue;
+        try {
+            rmSync(join(dir, entry.name), { force: true });
+        }
+        catch {
+            // One unremovable orphan must not stop the rest of the sweep.
+        }
+    }
+}
 // Generalized so callers other than the lockfile itself (e.g. add.ts's
 // .mcp.json merge, which sits right next to the lockfile and can hold other
 // servers' secrets) get the same crash-safety guarantee instead of a bare
@@ -25,22 +82,70 @@ export function writeJsonFileAtomic(path, data) {
     // truncated file on disk -- a reader always sees either the old or the new
     // complete content, never a partial one.
     const tmpPath = `${path}.tmp-${process.pid}-${process.hrtime.bigint()}`;
-    writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
-    renameSync(tmpPath, path);
+    // The mode the destination must end up with. Preserving an existing file's
+    // permissions matters because .mcp.json is a project-shared config other MCP
+    // clients read: whether it should be 0644 or tighter is its own decision
+    // (ahood#169), not something this write path gets to change as a side effect
+    // of the 0600 temp file below (ahood-cli#119). With no destination yet there
+    // is nothing to preserve, so fall back to what a plain writeFileSync would
+    // have produced -- 0666 masked by the process umask.
+    let finalMode;
+    try {
+        finalMode = statSync(path).mode & 0o777;
+    }
+    catch {
+        finalMode = 0o666 & ~process.umask();
+    }
+    try {
+        // 0600 from the moment of creation: for .mcp.json this temp file holds
+        // resolved MCP server secrets, and it must never be world-readable, not
+        // even for the instant before the rename (ahood-cli#119).
+        writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+        renameSync(tmpPath, path);
+        try {
+            chmodSync(path, finalMode);
+        }
+        catch {
+            // Best-effort, and deliberately after the rename rather than on the temp
+            // file: widening the temp file first would reopen the world-readable
+            // window this fix closes. A failure here leaves the file MORE restrictive
+            // than intended, never less, so it isn't worth failing a write that has
+            // already landed -- the caller would roll back a successful install.
+        }
+        try {
+            sweepStaleTempFiles(path, basename(tmpPath));
+        }
+        catch {
+            // Swallowed for the same reason as the chmod above and #119's unlink:
+            // the rename has already landed, so failing to tidy up somebody else's
+            // abandoned temp file must never turn a successful write into an error
+            // the caller rolls back (ahood-cli#125).
+        }
+    }
+    finally {
+        // The rename consumes the temp file on success; this only bites when the
+        // write or the rename threw, where an orphaned *.tmp-* copy of .mcp.json
+        // would strand plaintext secrets under a name no .gitignore rule matches
+        // (ahood-cli#119). Swallowed because it must never mask the real reason
+        // the write failed -- that error is what the caller has to report.
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best effort, see comment above
+        }
+    }
 }
 function writeLockfile(path, lockfile) {
     writeJsonFileAtomic(path, lockfile);
 }
 // A lock directory is stale if the PID recorded inside it (written by the
-// acquirer below) belongs to a process that's no longer running -- signal 0
-// doesn't actually deliver a signal, just probes whether the process could
-// be signaled. ESRCH means it's dead; EPERM means it's alive but owned by
-// someone else, which is conservatively treated as still alive since that
-// can't be disproven. A missing/unparseable pid file is also treated as
-// "not stale" -- either a lock from before this file existed, or another
-// process is still mid-way through acquiring (mkdirSync succeeded, the pid
-// write hasn't landed yet) -- safer to wait it out than to reclaim a lock
-// that's actually still being set up.
+// acquirer below) belongs to a process that's no longer running, per
+// isPidDead above. A missing/unparseable pid file is treated as "not stale"
+// -- either a lock from before this file existed, or another process is
+// still mid-way through acquiring (mkdirSync succeeded, the pid write hasn't
+// landed yet) -- safer to wait it out than to reclaim a lock that's actually
+// still being set up.
 function isLockStale(pidFile) {
     let pidText;
     try {
@@ -52,13 +157,7 @@ function isLockStale(pidFile) {
     const pid = Number(pidText);
     if (!Number.isInteger(pid) || pid <= 0)
         return false;
-    try {
-        process.kill(pid, 0);
-        return false;
-    }
-    catch (error) {
-        return error.code === "ESRCH";
-    }
+    return isPidDead(pid);
 }
 // Simple advisory lock via mkdir's atomicity (EEXIST on a second caller),
 // so two concurrent `ahood skill add`/`remove` invocations against the same
@@ -109,7 +208,7 @@ export function withLock(path, fn) {
                 continue;
             }
             if (Date.now() > deadline) {
-                throw new Error(`Timed out waiting for the lockfile lock at ${lockDir}. If no other ahood process is running, delete that directory manually.`);
+                throw new Error(`Timed out waiting for the lock on ${path} at ${lockDir}. If no other ahood process is running, delete that directory manually.`);
             }
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",