@ahood/cli 0.9.0 → 0.10.0

package/dist/index.js

@@ -20,15 +20,16 @@ import { versions } from "./commands/versions.js";
 import { diff } from "./commands/diff.js";
 import { completion } from "./commands/completion.js";
 import { mcp } from "./commands/mcp.js";
+import { extractKindFlag, resolveScope } from "./kinds.js";
+import { readUseme } from "./useme.js";
+import { UsageError } from "./usage-error.js";
 import { init } from "./commands/init.js";
 import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
 import { createSnap, listSnaps, searchSnaps, showSnap, removeSnap, shareSnap, unshareSnap, tagsSnap, } from "./commands/snap.js";
-import { formatHelp, formatSkillHelp, formatGroupHelp, formatSnapHelp, formatCommandHelp, findCommandHelp } from "./help.js";
+import { formatHelp, formatKindHelp, formatGroupHelp, formatSnapHelp, formatCommandHelp, findCommandHelp } from "./help.js";
 import { ApiError } from "./http.js";
 import { exitCodeFor } from "./exit-code.js";
 import { CLI_NAME, CLI_VERSION } from "./version.js";
-// Every skill-entity verb, reached only as `ahood skill <verb>` -- see
-// dispatchSkill() below. "show" is an alias for "view" (issue #30).
 const SKILL_COMMANDS = {
     search,
     view,
@@ -44,7 +45,7 @@ const SKILL_COMMANDS = {
     // can never accidentally move a pin forward. Reuses update()'s existing
     // "no targets = every installed skill, explicit targets = just those"
     // behavior as-is; no new logic.
-    outdated: (args) => update([...args, "--dry-run"]),
+    outdated: (args, scope) => (scope ? update([...args, "--dry-run"], scope) : update([...args, "--dry-run"])),
     remove,
     edit,
     unpublish,
@@ -92,8 +93,9 @@ const COMMANDS = {
     whoami,
     token,
     completion,
-    mcp,
+    mcp: dispatchMcp,
     skill: dispatchSkill,
+    agent: dispatchAgent,
     group: dispatchGroup,
     snap: dispatchSnap,
 };
@@ -105,7 +107,8 @@ const COMMANDS = {
 // here just means "a command that owns its own sub-verb dispatch", the same
 // sense "skill" already used before "group" (the entity) existed. "snap"
 // joins this set for the exact same reason (ahood-cli#107).
-const GROUP_COMMANDS = new Set(["skill", "group", "snap"]);
+// "agent" and "mcp" join it as registry nouns (ahood-cli#172).
+const GROUP_COMMANDS = new Set(["skill", "agent", "mcp", "group", "snap"]);
 function levenshtein(a, b) {
     const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
     for (let i = 0; i <= a.length; i++)
@@ -143,31 +146,96 @@ function closestGroupVerb(input) {
 function closestSnapVerb(input) {
     return closestOf(input, Object.keys(SNAP_VERBS));
 }
-// `ahood skill <verb> [...]` -- owns its own help handling at both the
-// group level (`ahood skill` / `ahood skill --help`) and the per-verb level
-// (`ahood skill <verb> --help`), since neither should fall through to
-// main()'s generic top-level --help interception (see GROUP_COMMANDS).
-async function dispatchSkill(args) {
+// `ahood <noun> <verb> [...]` for every registry noun (skill, agent, mcp) --
+// owns its own help handling at both the noun level (`ahood agent` /
+// `ahood agent --help`) and the per-verb level (`ahood agent <verb> --help`),
+// since neither should fall through to main()'s generic top-level --help
+// interception (see GROUP_COMMANDS).
+//
+// Scope (ahood-cli#172): `--kind <k|all>` is consumed here, never by a
+// handler, and resolved by resolveScope(): agent/mcp are strict for their own
+// kind (a contradictory --kind is a usage error), while skill stays legacy
+// cross-kind unless --kind narrows it. `ahood skill publish` is the one
+// exception: its --kind has always been publish's own "what kind of artifact
+// is this folder" flag, so it is passed through untouched.
+async function dispatchRegistry(noun, args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h") {
-        console.log(formatSkillHelp());
+        console.log(formatKindHelp(noun));
         return;
     }
     const handler = SKILL_COMMANDS[sub];
     if (!handler) {
-        console.error(`Unknown skill command: ${sub}`);
-        const suggestion = closestSkillCommand(sub);
+        console.error(`Unknown ${noun} command: ${sub}`);
+        const suggestion = closestOf(sub, noun === "mcp" ? ["serve", ...Object.keys(SKILL_COMMANDS)] : Object.keys(SKILL_COMMANDS));
         if (suggestion)
             console.error(`Did you mean '${suggestion}'?`);
-        console.error("Run `ahood skill --help` for a list of commands.");
+        console.error(`Run \`ahood ${noun} --help\` for a list of commands.`);
+        if (noun === "mcp") {
+            console.error("To start the local MCP server, run `ahood mcp serve` (or `ahood mcp` with no arguments).");
+        }
         process.exit(2);
     }
     if (rest.includes("--help") || rest.includes("-h")) {
-        const entry = findCommandHelp("skill", sub);
-        console.log(entry ? formatCommandHelp(entry) : formatSkillHelp());
+        const entry = findCommandHelp(noun, sub);
+        console.log(entry ? formatCommandHelp(entry) : formatKindHelp(noun));
         return;
     }
-    await handler(rest);
+    if (noun === "skill" && sub === "publish") {
+        await handler(rest);
+        return;
+    }
+    const { kind, rest: handlerArgs } = extractKindFlag(rest);
+    const scope = resolveScope(noun, kind);
+    if (scope.kind === "all") {
+        // Legacy: the exact pre-#172 call, minus an explicit `--kind all`.
+        await handler(kind === undefined ? rest : handlerArgs);
+        return;
+    }
+    try {
+        await handler(handlerArgs, scope);
+    }
+    catch (error) {
+        // Handlers phrase their usage lines as `ahood skill <verb>`; under another
+        // noun, say the command the user actually typed.
+        if (error instanceof UsageError && noun !== "skill") {
+            error.message = error.message.replace(/(Usage: |or: )ahood skill /g, `$1ahood ${noun} `);
+        }
+        throw error;
+    }
+}
+async function dispatchSkill(args) {
+    await dispatchRegistry("skill", args);
+}
+async function dispatchAgent(args) {
+    await dispatchRegistry("agent", args);
+}
+// `ahood mcp` keeps its original contract byte-for-byte: with NO arguments it
+// is the local stdio MCP server that existing host configs launch -- nothing
+// is printed and nothing else runs first. `ahood mcp serve` is the same
+// server under an explicit, documented name. Every other first word is a
+// registry verb for mcp-kind entries, help, or an error: an unrecognized one
+// fails with usage (dispatchRegistry) rather than silently starting a
+// long-lived server that a typo would otherwise leave hanging.
+async function dispatchMcp(args) {
+    if (args.length === 0) {
+        await mcp(args);
+        return;
+    }
+    const [sub, ...rest] = args;
+    if (sub === "serve") {
+        if (rest.includes("--help") || rest.includes("-h")) {
+            const entry = findCommandHelp("mcp", "serve");
+            console.log(entry ? formatCommandHelp(entry) : formatKindHelp("mcp"));
+            return;
+        }
+        if (rest.length > 0) {
+            throw new UsageError(`\`ahood mcp serve\` takes no arguments (got: ${rest.join(" ")}).\nUsage: ahood mcp serve`);
+        }
+        await mcp([]);
+        return;
+    }
+    await dispatchRegistry("mcp", args);
 }
 // `ahood group <verb> [...]` -- owns its own help handling at both the
 // group level (`ahood group` / `ahood group --help`) and the per-verb level
@@ -228,10 +296,26 @@ async function main() {
     }
     if (command === "help") {
         const sub = args[0];
-        if (sub === "skill") {
+        // `ahood help useme` (ahood-cli#172): the bundled self-skill, as raw
+        // bytes on stdout and nothing else -- no banner, no trailing newline of
+        // our own -- so the output IS the SKILL.md. No network, no credentials,
+        // no project writes.
+        if (sub === "useme") {
+            let content;
+            try {
+                content = readUseme();
+            }
+            catch (error) {
+                console.error(`Could not read the bundled ahood SKILL.md: ${error instanceof Error ? error.message : String(error)}`);
+                process.exit(1);
+            }
+            process.stdout.write(content);
+            return;
+        }
+        if (sub === "skill" || sub === "agent" || sub === "mcp") {
             const verb = args[1];
-            const entry = verb ? findCommandHelp("skill", verb) : undefined;
-            console.log(entry ? formatCommandHelp(entry) : formatSkillHelp());
+            const entry = verb ? findCommandHelp(sub, verb) : undefined;
+            console.log(entry ? formatCommandHelp(entry) : formatKindHelp(sub));
             return;
         }
         if (sub === "group") {
@@ -310,4 +394,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };
+export { main, dispatchSkill, dispatchAgent, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };

package/dist/kind-info.js

@@ -0,0 +1,40 @@
+// Pure kind metadata (no imports, no I/O) so help.ts -- which
+// scripts/sync-readme.mjs imports straight from dist/ -- can use it without
+// pulling in the HTTP/filesystem layer. Behavior lives in kinds.ts.
+//
+// Kind-aware registry commands (ahood-cli#172).
+//
+// The registry stores four artifact kinds (the backend's
+// lib/skills/validation.ts ALLOWED_KINDS: skill, agent, mcp, doc), and a
+// kind is fixed when an entry is created -- PATCH's allow-list has no `kind`
+// -- so the kind an entry reports now is the kind it has always had. This
+// CLI has a noun group for three of them. `doc` is a real registry kind left
+// out of this CLI's scope on purpose; adding it means one entry in KINDS
+// below plus its help/init template, not a new dispatcher.
+export const KINDS = {
+    skill: {
+        label: "skill",
+        article: "a",
+        plural: "skills",
+        rootDoc: "SKILL.md",
+        installsTo: ".claude/skills/<owner>@<skill>/",
+    },
+    agent: {
+        label: "agent",
+        article: "an",
+        plural: "agents",
+        rootDoc: "AGENT.md",
+        installsTo: ".claude/agents/<owner>@<agent>.md",
+    },
+    mcp: {
+        label: "MCP server manifest",
+        article: "an",
+        plural: "MCP server manifests",
+        rootDoc: "server.json",
+        installsTo: "an entry in .mcp.json",
+    },
+};
+export const CLI_KINDS = Object.keys(KINDS);
+export function isCliKind(value) {
+    return typeof value === "string" && CLI_KINDS.includes(value);
+}

package/dist/kinds.js

@@ -0,0 +1,122 @@
+// Kind-aware registry commands (ahood-cli#172): scope resolution and the
+// wrong-kind guards every kind-scoped verb runs before its first side effect.
+// The kind table itself lives in kind-info.ts.
+import { existsSync } from "node:fs";
+import { apiJson } from "./http.js";
+import { agentPath, skillDir } from "./spec.js";
+import { UsageError } from "./usage-error.js";
+import { KINDS, CLI_KINDS, isCliKind } from "./kind-info.js";
+export { KINDS, CLI_KINDS, isCliKind };
+export const LEGACY_SCOPE = { noun: "skill", kind: "all" };
+export function strictKind(scope) {
+    return scope && scope.kind !== "all" ? scope.kind : undefined;
+}
+// A wrong-kind target: the user pointed a noun at the wrong kind of entry, so
+// it maps to exit 2 ("fix your input") through UsageError, the same code a
+// server-side validation refusal gets.
+export class KindMismatchError extends UsageError {
+}
+export function describeKind(kind) {
+    return `${KINDS[kind].article} ${KINDS[kind].label}`;
+}
+// Throws unless `actual` is the scope's kind. A no-op for the legacy scope.
+//
+// Missing or unrecognized kind metadata is refused, never guessed: the legacy
+// code treated a missing `kind` as a skill, and a strict verb that did the
+// same would silently misclassify exactly the entry it exists to protect.
+// That refusal is a plain Error (exit 1) rather than a KindMismatchError,
+// since nothing about the user's input is wrong -- the registry's answer is.
+export function assertKind(scope, key, actual, verb, action) {
+    const expected = strictKind(scope);
+    if (expected === undefined || actual === expected)
+        return;
+    const legacyHint = `\`ahood skill ${verb} ${key}\` (legacy, any kind)`;
+    if (isCliKind(actual)) {
+        throw new KindMismatchError(`${key} is ${describeKind(actual)}, not ${describeKind(expected)} -- refusing to ${action} it. ` +
+            `Use \`ahood ${actual} ${verb} ${key}\` instead.`);
+    }
+    if (actual === undefined || actual === null || actual === "") {
+        throw new Error(`The registry did not report a kind for ${key}, so ahood cannot confirm it is ${describeKind(expected)} -- ` +
+            `refusing to ${action} it. If you are sure, use ${legacyHint}.`);
+    }
+    throw new Error(`${key} has kind "${String(actual).slice(0, 40)}", which \`ahood ${scope.noun}\` does not handle -- ` +
+        `refusing to ${action} it. Use ${legacyHint} if you really mean it.`);
+}
+// Resolves an existing registry entry's kind and asserts it, for verbs whose
+// own request carries no kind (star, share, edit, versions, ...). A no-op --
+// and, importantly, no extra request -- for the legacy scope, so
+// `ahood skill <verb>` sends exactly what it always has.
+export async function ensureRemoteKind(scope, owner, skill, verb, action) {
+    if (strictKind(scope) === undefined)
+        return;
+    const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+    assertKind(scope, `${owner}/${skill}`, detail.kind, verb, action);
+}
+// What this project's own files say an installed pin is, without asking the
+// registry. The lockfile records no `kind` (and this change does not migrate
+// it), so the footprint each kind leaves is the evidence:
+//   skill -> a .claude/skills/<owner>@<skill>/ directory
+//   agent -> a .claude/agents/<owner>@<skill>.md file
+//   mcp   -> neither, plus the mcp_config_hash only an mcp install records
+// Anything else (both, or a bare pin with no hash -- a legacy mcp pin or a
+// skill whose directory was deleted by hand) is undefined: unknown, and the
+// caller must ask the registry rather than guess.
+export function localInstalledKind(owner, skill, entry) {
+    const hasDir = existsSync(skillDir(owner, skill));
+    const hasAgentFile = existsSync(agentPath(owner, skill));
+    if (hasDir && !hasAgentFile)
+        return "skill";
+    if (hasAgentFile && !hasDir)
+        return "agent";
+    if (!hasDir && !hasAgentFile && entry?.mcp_config_hash !== undefined)
+        return "mcp";
+    return undefined;
+}
+// Pulls `--kind <value>` / `--kind=<value>` out of a registry verb's args.
+// Returns the remaining args untouched otherwise, so a handler never sees a
+// flag it does not declare.
+export function extractKindFlag(args) {
+    let kind;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--kind" || arg.startsWith("--kind=")) {
+            if (kind !== undefined)
+                throw new UsageError("--kind given more than once. Pass it once.");
+            if (arg === "--kind") {
+                const value = args[i + 1];
+                if (value === undefined || value.startsWith("--"))
+                    throw new UsageError("--kind requires a value.");
+                kind = value;
+                i++;
+            }
+            else {
+                kind = arg.slice("--kind=".length);
+            }
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { kind, rest };
+}
+// Resolves the scope for `ahood <noun> <verb> [--kind <k>]`.
+//   skill noun, no --kind or --kind all  -> legacy (cross-kind)
+//   skill noun, --kind <k>               -> strict <k>
+//   agent/mcp noun, no --kind or --kind <same> -> strict <noun>
+//   agent/mcp noun, any other --kind     -> usage error (contradiction)
+export function resolveScope(noun, kindFlag) {
+    const valid = [...CLI_KINDS, "all"].join(", ");
+    if (kindFlag !== undefined && kindFlag !== "all" && !isCliKind(kindFlag)) {
+        throw new UsageError(`--kind must be one of: ${valid} (got "${kindFlag}").`);
+    }
+    if (noun === "skill") {
+        return kindFlag === undefined || kindFlag === "all" ? LEGACY_SCOPE : { noun, kind: kindFlag };
+    }
+    if (kindFlag !== undefined && kindFlag !== noun) {
+        throw new UsageError(`\`ahood ${noun}\` only operates on ${KINDS[noun].plural} -- --kind ${kindFlag} contradicts it. ` +
+            (kindFlag === "all"
+                ? "Use `ahood skill <verb>` (legacy, any kind) for a cross-kind operation."
+                : `Use \`ahood ${kindFlag} <verb>\` instead.`));
+    }
+    return { noun, kind: noun };
+}

package/dist/lockfile.js

@@ -1,5 +1,6 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { hostname } from "node:os";
 export function readLockfile(path) {
     if (!existsSync(path))
         return {};
@@ -130,7 +131,21 @@ function resolveWriteTarget(path) {
 // .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
 // writeFileSync that risks truncating the file on interruption.
-export function writeJsonFileAtomic(path, data) {
+//
+// `mode` (ahood-cli#158) lets a caller decide the mode of a file this write
+// CREATES: installMcpEntry requests 0600 when the payload it just resolved
+// holds a credential, because only the caller knows whether the data is a
+// secret store or a shared config. It never applies to an existing
+// destination -- that file's mode is its owner's (or another tool's) choice,
+// and preserving it is #119's whole point -- so an existing file is untouched
+// no matter what is requested, and the caller learns about a loose existing
+// file some other way (the warning in add.ts). Omitted, the fallback stays
+// exactly what a plain writeFileSync would have produced. An explicitly
+// requested mode is applied exactly, via the post-rename chmod below, rather
+// than umask-masked at creation: a caller making a security decision about a
+// file it is creating must get what it asked for regardless of the ambient
+// umask.
+export function writeJsonFileAtomic(path, data, mode) {
     // Resolved before the mkdir so the directory that actually gets created is
     // the resolved target's, not the link's -- a link set up ahead of the first
     // install can point somewhere that doesn't exist yet -- and so that every
@@ -153,9 +168,11 @@ export function writeJsonFileAtomic(path, data) {
     // 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.
+    // of the 0600 temp file below (ahood-cli#119) -- and that is true even when
+    // the caller passed `mode`, which therefore only ever governs creation. With
+    // no destination yet there is nothing to preserve: an explicit request wins
+    // (see the comment above), and without one the fallback is what a plain
+    // writeFileSync would have produced -- 0666 masked by the process umask.
     //
     // lstatSync rather than statSync even though `dest` is by construction never
     // a symlink (resolveWriteTarget walked until it wasn't): the two agree here,
@@ -166,7 +183,7 @@ export function writeJsonFileAtomic(path, data) {
         finalMode = lstatSync(dest).mode & 0o777;
     }
     catch {
-        finalMode = 0o666 & ~process.umask();
+        finalMode = mode !== undefined ? mode & 0o777 : 0o666 & ~process.umask();
     }
     try {
         // 0600 from the moment of creation: for .mcp.json this temp file holds
@@ -233,20 +250,98 @@ function readLockPid(pidFile) {
     const pid = Number(pidText);
     return Number.isInteger(pid) && pid > 0 ? pid : undefined;
 }
+// /etc/machine-id is the stable per-machine identifier on systemd Linux:
+// stable across reboots, distinct per machine. Hostname alone is not a
+// sufficient identity -- two containers from the same image routinely share
+// it -- so the machine id anchors the comparison wherever it exists. Read
+// errors are swallowed (macOS has no such file; a read can also fail) and
+// leave the identity to the hostname alone, the same best-effort posture the
+// pid write below already takes.
+function readMachineId() {
+    try {
+        const machineId = readFileSync("/etc/machine-id", "utf-8").trim();
+        return machineId.length > 0 ? machineId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// The exact string written into a lock's `host` file: first line the machine
+// id (empty when this host has none), second line the hostname. Computed once
+// and cached -- neither value can change under a running process, and the
+// retry loop below re-checks staleness every 25ms. Exported so a test can
+// plant a lock recorded by THIS host (a foreign one just writes any other
+// string), and so the format a reader must parse has exactly one definition.
+let cachedHostIdentity;
+export function currentHostIdentity() {
+    cachedHostIdentity ??= `${readMachineId() ?? ""}\n${hostname()}`;
+    return cachedHostIdentity;
+}
+function parseHostIdentity(text) {
+    const newline = text.indexOf("\n");
+    // No newline: tolerate hostname-only content rather than reading the whole
+    // line as a machine id that could never match.
+    if (newline === -1)
+        return { hostname: text };
+    return { machineId: text.slice(0, newline) || undefined, hostname: text.slice(newline + 1) };
+}
+// A recorded identity matches this host when the machine ids agree, or -- when
+// either side has no machine id -- the hostnames do. Machine id deliberately
+// wins over hostname where both exist: the same machine-id under a different
+// hostname is the same machine (renamed), while a shared hostname over
+// different machine ids is exactly the two-containers-from-one-image case
+// hostname-only matching cannot tell apart -- the bug this exists to close.
+function isSameHost(recorded) {
+    const ours = parseHostIdentity(currentHostIdentity());
+    const theirs = parseHostIdentity(recorded);
+    if (ours.machineId && theirs.machineId)
+        return ours.machineId === theirs.machineId;
+    return ours.hostname === theirs.hostname;
+}
+// The `host` file a lock records its holder's identity in, or undefined when
+// there is no readable one: no host file at all, or contents that trim to
+// nothing. See isLockStale for what a missing host line means.
+function readLockHost(hostFile) {
+    try {
+        const host = readFileSync(hostFile, "utf-8").trim();
+        return host.length > 0 ? host : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 // A lock directory is stale if the pid recorded inside it belongs to a process
-// that's no longer running, per isPidDead above. No readable pid means "not
-// stale": safer to wait out a lock that may still be being set up than to
-// reclaim one that is actually held.
-function isLockStale(pidFile) {
+// that's no longer running, per isPidDead above -- but only a lock recorded on
+// THIS host: the pid probe cannot see another host's processes, so a lock
+// whose host line names a different machine is treated as live and waited out
+// no matter what the pid probe answers (ahood-cli#157). A missing host line is
+// judged by pid alone, exactly as <=0.9.0 code judged every lock: the only
+// such locks are legacy ones and those whose best-effort host write failed,
+// and reading them as foreign instead would strand every stale local lock
+// behind a misleading "held on another host" timeout -- a regression #100's
+// reclaim exists to prevent, in exchange for keeping only the pre-#157 status
+// quo, which disappears as soon as a lock carries a host line.
+//
+// No readable pid still means "not stale": safer to wait out a lock that may
+// still be being set up than to reclaim one that is actually held.
+function isLockStale(pidFile, hostFile) {
     const pid = readLockPid(pidFile);
-    return pid !== undefined && isPidDead(pid);
+    if (pid === undefined)
+        return false;
+    const host = readLockHost(hostFile);
+    return (host === undefined || isSameHost(host)) && isPidDead(pid);
 }
 // Deliberately NOT the negation of isLockStale: with no readable pid at all a
 // lock is neither stale nor demonstrably held, and the two callers want
 // opposite answers in that case. Reclaiming needs proof the holder is dead
 // (hence isLockStale), while withLock's deadline branch needs proof that
 // someone is alive before it backs off a reclaim failure it already observed.
-function isLockHeldByLiveProcess(pidFile) {
+// A foreign-host lock counts as held no matter what the pid probe answers:
+// that holder is exactly the process this machine cannot see (ahood-cli#157).
+function isLockHeldByLiveProcess(pidFile, hostFile) {
+    const host = readLockHost(hostFile);
+    if (host !== undefined && !isSameHost(host))
+        return true;
     const pid = readLockPid(pidFile);
     return pid !== undefined && !isPidDead(pid);
 }
@@ -287,7 +382,7 @@ const RECLAIM_CLAIM = "reclaiming";
 //
 // Returns the error to remember for withLock's deadline branch (see
 // ahood-cli#140), or undefined when there is nothing worth remembering.
-function reclaimStaleLock(lockDir, pidFile) {
+function reclaimStaleLock(lockDir, pidFile, hostFile) {
     const claim = join(lockDir, RECLAIM_CLAIM);
     try {
         mkdirSync(claim);
@@ -303,7 +398,7 @@ function reclaimStaleLock(lockDir, pidFile) {
             return undefined;
         return existsSync(lockDir) ? error : undefined;
     }
-    if (!isLockStale(pidFile)) {
+    if (!isLockStale(pidFile, hostFile)) {
         // Not the directory that was judged stale after all -- it was reclaimed and
         // retaken while this process looked, or it belongs to a holder that hasn't
         // written its pid yet. Hand the claim back, leaving the lock exactly as it
@@ -340,11 +435,16 @@ function reclaimStaleLock(lockDir, pidFile) {
 // hard-killed (SIGKILL/OOM) mid-critical-section: without this, such a lock
 // is never released, and every subsequent add/remove/update in that project
 // busy-waits out the full timeout below and then fails permanently until a
-// human manually deletes the stale directory (ahood-cli#100).
+// human manually deletes the stale directory (ahood-cli#100). It also holds
+// a `host` file recording WHERE that holder ran, because a pid is only
+// meaningful on the machine it belongs to: on a shared filesystem a live
+// holder on another host reads as dead here, and reclaiming its lock puts
+// two processes inside the critical section at once (ahood-cli#157).
 export function withLock(path, fn) {
     mkdirSync(dirname(path), { recursive: true });
     const lockDir = `${path}.lock`;
     const pidFile = join(lockDir, "pid");
+    const hostFile = join(lockDir, "host");
     const deadline = Date.now() + 5000;
     // Set when the lock was judged stale but could not actually be removed and
     // that directory is still sitting there -- see the reclaim branch below.
@@ -364,6 +464,13 @@ export function withLock(path, fn) {
             try {
                 writeFileSync(pidFile, String(process.pid));
                 wrotePid = true;
+                // Best-effort like the pid write above, and for the same reason:
+                // mkdirSync is what actually holds the lock. A lock whose host line
+                // never landed carries no host identity and is judged exactly as
+                // pre-#157 code judged every lock -- by pid alone (see isLockStale's
+                // missing-host rule) -- so a failed write here degrades to today's
+                // behaviour rather than to something new.
+                writeFileSync(hostFile, currentHostIdentity());
             }
             catch {
                 // non-fatal, see comment above
@@ -391,12 +498,30 @@ export function withLock(path, fn) {
                 // (inode, birthtime) deliberately isn't used for this: a removed and
                 // immediately recreated directory routinely gets the same inode back,
                 // so it can't tell a replacement from the original anyway.
-                if (reclaimError && existsSync(lockDir) && !isLockHeldByLiveProcess(pidFile)) {
+                if (reclaimError && existsSync(lockDir) && !isLockHeldByLiveProcess(pidFile, hostFile)) {
                     throw new Error(`Could not reclaim the stale lock on ${path} at ${lockDir}: ${reclaimError.code ?? reclaimError.message}. The process that held it is gone, but this one cannot remove that directory -- delete it manually (it may belong to another user, e.g. left behind by a sudo/root run, or sit on a read-only filesystem).`);
                 }
+                // A lock recorded on another host never reaches the reclaim branch
+                // (isLockStale refuses to judge it stale), so its timeout lands here.
+                // Name the holder's host rather than falling through to the generic
+                // message: the pid in that lock is dead by this host's lights, so "if
+                // no other ahood process is running" reads as permission to delete a
+                // lock that may well belong to a live process this machine cannot see
+                // (ahood-cli#157).
+                const recordedHost = readLockHost(hostFile);
+                if (recordedHost !== undefined && !isSameHost(recordedHost)) {
+                    const holder = parseHostIdentity(recordedHost);
+                    const holderPid = readLockPid(pidFile);
+                    const holderParts = [
+                        `hostname "${holder.hostname}"`,
+                        ...(holder.machineId ? [`machine id ${holder.machineId}`] : []),
+                        ...(holderPid !== undefined ? [`pid ${holderPid}`] : []),
+                    ].join(", ");
+                    throw new Error(`Timed out waiting for the lock on ${path} at ${lockDir}: it is held on another host (${holderParts}), which this machine cannot probe for liveness. If nothing on that host holds it any more, delete that directory.`);
+                }
                 throw new Error(`Timed out waiting for the lock on ${path} at ${lockDir}. If no other ahood process is running, delete that directory manually.`);
             }
-            if (isLockStale(pidFile)) {
+            if (isLockStale(pidFile, hostFile)) {
                 // Reclaim it. Two very different conditions can fail that, and only
                 // one of them is the race the old comment here claimed: if the
                 // directory is GONE afterwards, a concurrent process reclaimed it (or
@@ -419,7 +544,7 @@ export function withLock(path, fn) {
                 // failure. Clearing it per-iteration made the error message depend on
                 // that detail, which is why it read correctly on one machine and fell
                 // back to the generic timeout on another (ahood-cli#145).
-                reclaimError = reclaimStaleLock(lockDir, pidFile) ?? reclaimError;
+                reclaimError = reclaimStaleLock(lockDir, pidFile, hostFile) ?? reclaimError;
             }
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
         }

package/dist/mcp/safe-tool.js

@@ -38,8 +38,20 @@ export function safeTool(fn) {
             return { content: [{ type: "text", text: JSON.stringify(result ?? null) }] };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const body = { error: message, error_code: errorCodeFor(error) };
+            const code = errorCodeFor(error);
+            let message = error instanceof Error ? error.message : String(error);
+            // ahood-cli#159 / ahood#313 Phase 5. The registry's 401 body is always
+            // the byte-identical `{ error: "Unauthorized" }` (lib/api-auth.ts) --
+            // correct, but not actionable: an MCP client here is a coding agent
+            // reading this JSON, and "Unauthorized" names no remedy. The CLI's own
+            // top-level handler already prints the fix (src/index.ts: "Run `ahood
+            // login` first (or set AHOOD_TOKEN)."); append the same sentence here
+            // verbatim so both surfaces say the same thing rather than two
+            // near-copies drifting apart. Only auth_error: usage/not-found/network
+            // errors carry their own already-actionable text.
+            if (code === "auth_error")
+                message += " Run `ahood login` first (or set AHOOD_TOKEN).";
+            const body = { error: message, error_code: code };
             return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
         }
     };