@korso/shepherd 0.11.0 → 0.11.2

package/README.md

@@ -105,34 +105,45 @@ default `~/.shepherd/inbox`). That file is then drained by two paths:
 > given client on this machine it **writes to that client's own configuration
 > file in your home directory**, without a separate prompt:
 >
-> | Client      | File it edits/creates                      | What it adds                                                     |
-> | ----------- | ------------------------------------------ | ---------------------------------------------------------------- |
-> | Claude Code | `~/.claude/settings.json`                  | `SessionStart` + `PreToolUse` hook entries                       |
-> | Codex       | `~/.codex/config.toml`                     | a `[[hooks.UserPromptSubmit]]` block (+ `features.hooks = true`) |
-> | Cursor      | `~/.cursor/hooks.json`                     | a `beforeSubmitPrompt` entry                                     |
-> | Pi          | `~/.pi/agent/extensions/shepherd-inbox.js` | copies the bundled extension                                     |
+> | Client      | File it edits/creates                      | What it adds                                              |
+> | ----------- | ------------------------------------------ | --------------------------------------------------------- |
+> | Claude Code | `~/.claude/settings.json`                  | `SessionStart` + `PreToolUse` hook entries                |
+> | Codex       | `~/.codex/config.toml`                     | the hooks feature plus all three canonical event handlers |
+> | Cursor      | `~/.cursor/hooks.json`                     | a `beforeSubmitPrompt` entry                              |
+> | Pi          | `~/.pi/agent/extensions/shepherd-inbox.js` | copies the bundled extension                              |
 >
-> This edit is **additive only** (existing keys/entries are never modified,
-> removed, or reordered), **marker-guarded** (attempted **at most once per
-> machine+client**, recorded under `~/.shepherd/hooks/`; if you later remove the
-> hook it is **never re-added**), **version-pinned** (the installed command runs
-> the exact shipped build, not a floating `npx latest`), and **fail-open** (any
-> file it can't confidently parse is left untouched with a stderr notice).
+> Fresh installs are **additive only** (existing keys/entries are never removed
+> or reordered), **record-guarded** under `~/.shepherd/hooks/`,
+> **version-pinned** (the installed command runs the exact shipped build, not a
+> floating `npx latest`). Unsupported client config shapes are left untouched;
+> installer and migration failures never block or break the agent session, and
+> failure logs may be emitted to stderr. Codex also has a one-time, versioned
+> migration, but only when it finds both a legacy auto-install record at
+> `~/.shepherd/hooks/codex.json` and the exact Shepherd-owned legacy block. It
+> preserves that block and appends only the missing handlers after saving a
+> persistent backup at
+> `~/.shepherd/hooks/backups/codex-config-before-v2.toml`. Ambiguous or manually
+> removed hooks are left alone. Existing users receive the migration after they
+> update `@korso/shepherd` and restart Codex so the updated MCP server starts.
 >
 > **To opt out entirely, set `SHEPHERD_NO_AUTO_HOOKS=1`** — the server then never
 > touches any client config, and you can wire the hook manually using the
 > per-client snippets below.
 
 On its first `initialize` handshake the server detects the connecting client
-and, for Claude Code / Codex / Pi, installs the delivery hook **once per
-machine**:
+and installs the delivery hook **once per machine**:
 
 - **Claude Code** — merges the `SessionStart` + `PreToolUse` hook entries into
   `~/.claude/settings.json` (additive JSON merge; an unparseable file is left
   untouched).
-- **Codex** — appends the `[[hooks.UserPromptSubmit]]` block (and
-  `features.hooks = true`) to `~/.codex/config.toml` (text-level append; it
-  respects an explicit `hooks = false` and never rewrites existing content).
+- **Codex** — enables `features.hooks` and appends canonical
+  `UserPromptSubmit`, `SessionStart`, and wildcard `PreToolUse` handlers to
+  `~/.codex/config.toml`. An explicit `hooks = false` is respected. Existing
+  installs are migrated only when a legacy `~/.shepherd/hooks/codex.json`
+  auto-install record and Shepherd's exact legacy `UserPromptSubmit` block are
+  both present. The migration retains that block, appends the two missing
+  handlers, and first writes a persistent backup. Update `@korso/shepherd` and
+  restart Codex to run it.
 - **Pi** — copies the bundled extension to
   `~/.pi/agent/extensions/shepherd-inbox.js`.
 - **Cursor** — merges a `beforeSubmitPrompt` entry into `~/.cursor/hooks.json`
@@ -140,10 +151,11 @@ machine**:
   verified to inject hook output into the agent's context, and wiring an
   unverified event would consume announcements without delivering them.
 
-A record under `~/.shepherd/hooks/` guarantees at-most-once: if you remove the
-hook, Shepherd won't re-add it. Everything is fail-open (an error just means no
-hook, never a broken session), and `SHEPHERD_NO_AUTO_HOOKS=1` disables the whole
-mechanism.
+A record under `~/.shepherd/hooks/` guarantees at-most-once installation (and
+tracks the current Codex migration version): if you remove the hook, Shepherd
+won't re-add it. Installation and migration are fail-open: a failure never
+blocks or breaks the agent session. `SHEPHERD_NO_AUTO_HOOKS=1` disables the
+whole mechanism.
 
 Both paths read the **same** inbox file and de-duplicate by announcement id, so
 running both is safe (the hub hands each announcement to exactly one drain; the
@@ -225,24 +237,41 @@ uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
 }
 ```
 
-### Codex — `UserPromptSubmit` hook
+### Codex — `UserPromptSubmit` + `SessionStart` + `PreToolUse` hooks
 
-_(Installed automatically on first run — shown for reference/manual setup.)_
+_(Installed automatically, with legacy Shepherd configs migrated once — shown
+for reference/manual setup.)_
 
 Codex uses the **same** hook contract as Claude Code (JSON on stdin, a
-`hookSpecificOutput.additionalContext` reply), so the **same bin** serves it. Use
-`UserPromptSubmit` — Codex's `PreToolUse` only fires for Bash, not `apply_patch`
-or MCP calls. Hooks must be enabled with `features.hooks = true`. In
-`~/.codex/config.toml`:
+`hookSpecificOutput.additionalContext` reply), so the **same bin** serves it.
+`UserPromptSubmit` and `SessionStart` cover turn and session boundaries. In
+local Codex testing, wildcard `PreToolUse` delivered before Bash,
+`apply_patch`, and MCP calls. Other richer tool paths, including WebSearch, are
+not guaranteed by the current Codex hook coverage. Hooks must be enabled with
+`features.hooks = true`. In `~/.codex/config.toml`:
 
 ```toml
 [features]
 hooks = true
 
 [[hooks.UserPromptSubmit]]
-command = ["npx", "-y", "--package=@korso/shepherd", "shepherd-inbox-hook"]
-# On Windows use command_windows instead:
-# command_windows = ["cmd", "/c", "npx -y --package=@korso/shepherd shepherd-inbox-hook"]
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = "npx -y --package=@korso/shepherd shepherd-inbox-hook"
+timeout = 20
+
+[[hooks.SessionStart]]
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "npx -y --package=@korso/shepherd shepherd-inbox-hook"
+timeout = 20
+
+[[hooks.PreToolUse]]
+matcher = "*"
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "npx -y --package=@korso/shepherd shepherd-inbox-hook"
+timeout = 20
 ```
 
 ### Pi — extension

package/dist/index.js

@@ -1723,8 +1723,12 @@ ${nudge}` : text;
     syncToolSurface();
   }
   let joinFailure = null;
+  let joinFailureTransient = false;
+  let targetWorkspaceSlug = null;
+  let gateRetry = null;
   let joinInFlight = Promise.resolve();
   async function activate(workspaceSlug) {
+    targetWorkspaceSlug = workspaceSlug;
     if (sessionId !== null && activeWorkspaceSlug === workspaceSlug) {
       return { ok: true };
     }
@@ -1744,6 +1748,7 @@ ${nudge}` : text;
         const parsed = JoinResponse.safeParse(raw);
         if (!parsed.success || !parsed.data.sessionId) {
           joinFailure = "validation";
+          joinFailureTransient = false;
           console.error(
             "[shepherd] join failed (validation): hub returned a malformed join response (no usable sessionId)"
           );
@@ -1759,10 +1764,12 @@ ${nudge}` : text;
         linked = true;
         hostedWorkspaceRejected = false;
         joinFailure = null;
+        joinFailureTransient = false;
         return { ok: true };
       } catch (err) {
         const reason = classifyActivateFailure(err);
         joinFailure = classifyJoinFailure(err);
+        joinFailureTransient = err instanceof HubUnreachable || err instanceof HubRequestError && reason === "unknown";
         if (reason === "workspaceRejected") {
           hostedWorkspaceRejected = true;
           console.error(
@@ -1823,6 +1830,13 @@ ${nudge}` : text;
     await awaitJoin();
     if (!linked) return notLinked();
     if (selfHostMismatch || hostedWorkspaceRejected) return workspaceMismatch();
+    if (sessionId === null && targetWorkspaceSlug !== null && joinFailureTransient) {
+      gateRetry ??= activate(targetWorkspaceSlug).finally(() => {
+        gateRetry = null;
+      });
+      await gateRetry;
+      if (hostedWorkspaceRejected) return workspaceMismatch();
+    }
     if (sessionId === null) return sessionNotReady();
     return null;
   }
@@ -2516,16 +2530,565 @@ async function ancestorChain(maxDepth = 32, snapshot = snapshotParentMap) {
 
 // src/hookInstall.ts
 import {
-  readFileSync as readFileSync6,
-  writeFileSync as writeFileSync6,
-  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync8,
+  writeFileSync as writeFileSync7,
+  mkdirSync as mkdirSync6,
   copyFileSync,
-  existsSync as existsSync4,
-  renameSync as renameSync2
+  existsSync as existsSync6,
+  renameSync as renameSync3
 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
-import { dirname as dirname6, join as join5 } from "node:path";
+import { dirname as dirname7, join as join7 } from "node:path";
 import { fileURLToPath } from "node:url";
+
+// src/codexHookMigration.ts
+import { existsSync as existsSync5, readFileSync as readFileSync7 } from "node:fs";
+import { createHash as createHash3 } from "node:crypto";
+import { join as join6 } from "node:path";
+import { z as z5 } from "zod";
+
+// src/codexHookInstall.ts
+import { parse, TomlDate } from "smol-toml";
+var CODEX_SHEPHERD_COMMENT = "# Added by Shepherd: delivers teammate announcements to the agent. Remove to disable.";
+function canonicalHandlerBlock(event, command, matcher) {
+  return [
+    "[[hooks." + event + "]]",
+    ...matcher === void 0 ? [] : ["matcher = " + JSON.stringify(matcher)],
+    "[[hooks." + event + ".hooks]]",
+    'type = "command"',
+    "command = " + JSON.stringify(command),
+    "timeout = 20",
+    ""
+  ].join("\n");
+}
+function canonicalHookBlock(command) {
+  return [
+    "",
+    CODEX_SHEPHERD_COMMENT,
+    canonicalHandlerBlock("UserPromptSubmit", command),
+    canonicalHandlerBlock("SessionStart", command),
+    canonicalHandlerBlock("PreToolUse", command, "*")
+  ].join("\n");
+}
+function parseConfig2(source) {
+  try {
+    return parse(source, { integersAsBigInt: false });
+  } catch {
+    return null;
+  }
+}
+function isTomlTable(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof TomlDate);
+}
+function hasEnabledHooks(config) {
+  const features = config["features"];
+  return isTomlTable(features) && features["hooks"] === true;
+}
+function insertHooksFeature(source) {
+  const featuresHeader = /^(\s*\[features\]\s*(?:#.*)?)$/gm;
+  let match;
+  while ((match = featuresHeader.exec(source)) !== null) {
+    const insertionPoint = match.index + match[0].length;
+    const candidate = source.slice(0, insertionPoint) + "\nhooks = true" + source.slice(insertionPoint);
+    const config = parseConfig2(candidate);
+    if (config !== null && hasEnabledHooks(config)) return candidate;
+  }
+  return null;
+}
+function installCandidate(source, config, command) {
+  const features = config["features"];
+  let candidate;
+  if (isTomlTable(features)) {
+    if (Object.prototype.hasOwnProperty.call(features, "hooks")) {
+      candidate = features["hooks"] === true ? source + canonicalHookBlock(command) : null;
+    } else {
+      const withFeature = insertHooksFeature(source);
+      candidate = withFeature === null ? null : withFeature + canonicalHookBlock(command);
+    }
+  } else if (features === void 0) {
+    candidate = source + (source.length === 0 ? "" : "\n") + "[features]\nhooks = true\n" + canonicalHookBlock(command);
+  } else {
+    candidate = null;
+  }
+  const parsed = candidate === null ? null : parseConfig2(candidate);
+  return parsed !== null && hasEnabledHooks(parsed) ? candidate : null;
+}
+function planCodexConfig(source, command) {
+  const config = parseConfig2(source);
+  if (config === null) return { kind: "skip", outcome: "unsupported-shape" };
+  const features = config["features"];
+  if (isTomlTable(features) && features["hooks"] !== void 0) {
+    if (features["hooks"] === false) {
+      return { kind: "skip", outcome: "opted-out" };
+    }
+    if (features["hooks"] !== true) {
+      return { kind: "skip", outcome: "unsupported-shape" };
+    }
+  } else if (features !== void 0 && !isTomlTable(features)) {
+    return { kind: "skip", outcome: "unsupported-shape" };
+  }
+  if (source.includes(canonicalHookBlock(command))) {
+    return { kind: "already-canonical" };
+  }
+  const candidate = installCandidate(source, config, command);
+  return candidate === null ? { kind: "skip", outcome: "unsupported-shape" } : { kind: "install", candidate };
+}
+function appendMissingCodexHandlers(source, command) {
+  const handlers = [
+    canonicalHandlerBlock("SessionStart", command),
+    canonicalHandlerBlock("PreToolUse", command, "*")
+  ].filter((handler) => !source.includes(handler));
+  const candidate = handlers.length === 0 ? source : source + (source.endsWith("\n") ? "" : "\n") + handlers.join("");
+  return parseConfig2(candidate) === null ? null : candidate;
+}
+
+// src/codexHookFs.ts
+import {
+  chmodSync,
+  closeSync,
+  existsSync as existsSync4,
+  fchmodSync,
+  fsyncSync,
+  linkSync,
+  mkdirSync as mkdirSync5,
+  openSync,
+  readFileSync as readFileSync6,
+  renameSync as renameSync2,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync6
+} from "node:fs";
+import { createHash as createHash2, randomUUID } from "node:crypto";
+import { basename as basename2, dirname as dirname6, join as join5 } from "node:path";
+import { z as z4 } from "zod";
+var STALE_LOCK_MS = 3e4;
+var lockSchema = z4.object({
+  pid: z4.number().int().positive(),
+  createdAt: z4.string(),
+  owner: z4.string().min(1).optional()
+});
+function errorCode(error) {
+  return error instanceof Error && "code" in error ? String(error.code) : void 0;
+}
+function modeOf(path3) {
+  try {
+    return statSync2(path3).mode & 511;
+  } catch {
+    return 384;
+  }
+}
+function syncParent(path3) {
+  if (process.platform === "win32") return;
+  const descriptor = openSync(dirname6(path3), "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+function durableTemp(path3, contents, mode) {
+  const descriptor = openSync(path3, "wx", mode);
+  try {
+    writeFileSync6(descriptor, contents);
+    fchmodSync(descriptor, mode);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+function atomicWrite(path3, contents) {
+  mkdirSync5(dirname6(path3), { recursive: true });
+  const temporary = join5(
+    dirname6(path3),
+    "." + basename2(path3) + "." + process.pid + "." + randomUUID() + ".tmp"
+  );
+  try {
+    durableTemp(temporary, contents, modeOf(path3));
+    renameSync2(temporary, path3);
+    syncParent(path3);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+    }
+    throw error;
+  }
+}
+function processIsLive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) !== "ESRCH";
+  }
+}
+function lockSnapshot(lockFile) {
+  try {
+    const bytes = readFileSync6(lockFile);
+    const modifiedAt = statSync2(lockFile).mtimeMs;
+    let owner = null;
+    let reclaimable = false;
+    try {
+      const decoded = JSON.parse(bytes.toString("utf8"));
+      const parsed = lockSchema.safeParse(decoded);
+      if (parsed.success) {
+        owner = parsed.data.owner ?? null;
+        const createdAt = Date.parse(parsed.data.createdAt);
+        const ageBasis = Number.isFinite(createdAt) ? createdAt : modifiedAt;
+        reclaimable = Date.now() - ageBasis > STALE_LOCK_MS && !processIsLive(parsed.data.pid);
+      }
+    } catch {
+    }
+    return { bytes, owner, reclaimable };
+  } catch {
+    return null;
+  }
+}
+function lockContents(owner) {
+  return JSON.stringify({
+    pid: process.pid,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    owner
+  });
+}
+function createOwnedLock(lockFile, owner) {
+  const temporary = lockFile + ".owner-" + owner + ".tmp";
+  try {
+    durableTemp(temporary, lockContents(owner), 384);
+    linkSync(temporary, lockFile);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch {
+    }
+  }
+}
+function ownedBy(lockFile, owner) {
+  try {
+    const decoded = JSON.parse(readFileSync6(lockFile, "utf8"));
+    const parsed = lockSchema.safeParse(decoded);
+    return parsed.success && parsed.data.owner === owner;
+  } catch {
+    return false;
+  }
+}
+function removeOwnedLock(lockFile, owner) {
+  if (ownedBy(lockFile, owner)) unlinkSync(lockFile);
+}
+function snapshotMatches(current, expected) {
+  return current !== null && current.reclaimable && current.bytes.equals(expected.bytes);
+}
+function nextReclaimClaim(rootClaim, snapshot) {
+  const generation = createHash2("sha256").update(snapshot.bytes).digest("hex");
+  return rootClaim + ".generation-" + generation;
+}
+function acquireReclaimClaim(rootClaim, owner) {
+  let claimFile = rootClaim;
+  for (let generation = 0; generation < 32; generation += 1) {
+    if (createOwnedLock(claimFile, owner)) return claimFile;
+    const snapshot = lockSnapshot(claimFile);
+    if (snapshot === null || !snapshot.reclaimable || snapshot.owner === null) {
+      return null;
+    }
+    claimFile = nextReclaimClaim(rootClaim, snapshot);
+  }
+  return null;
+}
+function replaceStaleLock(lockFile, claimFile, owner, expected) {
+  const replacement = lockFile + ".replacement-" + owner;
+  let published = false;
+  try {
+    durableTemp(replacement, lockContents(owner), 384);
+    if (!ownedBy(claimFile, owner)) return false;
+    if (!snapshotMatches(lockSnapshot(lockFile), expected)) return false;
+    renameSync2(replacement, lockFile);
+    published = true;
+    syncParent(lockFile);
+    if (ownedBy(claimFile, owner)) return true;
+    removeOwnedLock(lockFile, owner);
+    return false;
+  } catch {
+    if (published) removeOwnedLock(lockFile, owner);
+    return false;
+  } finally {
+    try {
+      unlinkSync(replacement);
+    } catch {
+    }
+  }
+}
+function acquireMigrationLock(lockFile) {
+  mkdirSync5(dirname6(lockFile), { recursive: true });
+  const owner = randomUUID();
+  if (createOwnedLock(lockFile, owner)) return owner;
+  const snapshot = lockSnapshot(lockFile);
+  if (snapshot === null || !snapshot.reclaimable) return null;
+  const claimFile = acquireReclaimClaim(lockFile + ".reclaim", owner);
+  if (claimFile === null) return null;
+  try {
+    return replaceStaleLock(lockFile, claimFile, owner, snapshot) ? owner : null;
+  } finally {
+    try {
+      removeOwnedLock(claimFile, owner);
+    } catch {
+    }
+  }
+}
+function releaseMigrationLock(lockFile, owner, log) {
+  try {
+    removeOwnedLock(lockFile, owner);
+  } catch (error) {
+    log(
+      "[shepherd] Codex hook migration lock cleanup failed: " + String(error)
+    );
+  }
+}
+function validateBackup(backupFile, source) {
+  if (!readFileSync6(backupFile).equals(source)) {
+    throw new Error("existing Codex migration backup does not match config");
+  }
+  chmodSync(backupFile, 384);
+}
+function ensureMigrationBackup(backupFile, source) {
+  const backupDirectory = dirname6(backupFile);
+  mkdirSync5(backupDirectory, { recursive: true });
+  syncParent(backupDirectory);
+  if (existsSync4(backupFile)) {
+    validateBackup(backupFile, source);
+    syncParent(backupFile);
+    return;
+  }
+  const temporary = backupFile + "." + process.pid + "." + randomUUID() + ".tmp";
+  try {
+    durableTemp(temporary, source, 384);
+    try {
+      linkSync(temporary, backupFile);
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") throw error;
+      validateBackup(backupFile, source);
+    }
+    syncParent(backupFile);
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch {
+    }
+  }
+}
+
+// src/codexHookMigration.ts
+var MIGRATION_VERSION = 2;
+var migrationOutcomeSchema = z5.enum([
+  "migrated",
+  "already-canonical",
+  "user-removed",
+  "ambiguous",
+  "opted-out",
+  "unsupported-shape"
+]);
+var recordSchema = z5.object({
+  status: z5.string(),
+  at: z5.string(),
+  migrationVersion: z5.number().int().nonnegative().optional(),
+  migrationOutcome: migrationOutcomeSchema.optional()
+}).passthrough();
+function migrationPaths(homeDir) {
+  const hooksDir = join6(homeDir, ".shepherd", "hooks");
+  return {
+    hooksDir,
+    recordFile: join6(hooksDir, "codex.json"),
+    lockFile: join6(hooksDir, "codex-migration-v2.lock"),
+    backupFile: join6(hooksDir, "backups", "codex-config-before-v2.toml"),
+    configFile: join6(homeDir, ".codex", "config.toml")
+  };
+}
+function readRecord(recordFile) {
+  if (!existsSync5(recordFile)) return { kind: "none" };
+  try {
+    const decoded = JSON.parse(readFileSync7(recordFile, "utf8"));
+    const parsed = recordSchema.safeParse(decoded);
+    if (!parsed.success) return { kind: "corrupt" };
+    const record = parsed.data;
+    const version = parsed.data.migrationVersion;
+    if (version === void 0 || version < MIGRATION_VERSION) {
+      return { kind: "legacy", record };
+    }
+    if (version > MIGRATION_VERSION) return { kind: "future", record };
+    return parsed.data.migrationOutcome === void 0 ? { kind: "corrupt" } : { kind: "current", record };
+  } catch {
+    return { kind: "corrupt" };
+  }
+}
+function migrationRecord(prior, status, outcome) {
+  return JSON.stringify(
+    {
+      ...prior,
+      status: typeof prior?.["status"] === "string" ? prior["status"] : status,
+      at: typeof prior?.["at"] === "string" ? prior["at"] : (/* @__PURE__ */ new Date()).toISOString(),
+      migrationVersion: MIGRATION_VERSION,
+      migrationOutcome: outcome
+    },
+    null,
+    2
+  ) + "\n";
+}
+function fingerprint(bytes) {
+  return createHash3("sha256").update(bytes).digest("hex");
+}
+function readConfigBytes(configFile) {
+  return existsSync5(configFile) ? readFileSync7(configFile) : Buffer.alloc(0);
+}
+function decodeConfig(bytes) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function advanceRecord(recordFile, state, status, outcome) {
+  atomicWrite(recordFile, migrationRecord(state.record, status, outcome));
+}
+function legacyHookBlock(commandValue) {
+  return [
+    "",
+    CODEX_SHEPHERD_COMMENT,
+    "[[hooks.UserPromptSubmit]]",
+    "command = " + commandValue,
+    ""
+  ].join("\n");
+}
+function exactOwnedLegacyBlock(source, hooksDir) {
+  const semver = "(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)";
+  const pinned = new RegExp(
+    '^command = (\\["npx", "-y", "--package=@korso/shepherd@' + semver + '", "shepherd-inbox-hook"\\])$',
+    "gm"
+  );
+  const candidates = Array.from(
+    source.matchAll(pinned),
+    (match) => legacyHookBlock(match[1])
+  );
+  candidates.push(
+    legacyHookBlock(
+      '["node", ' + JSON.stringify(join6(hooksDir, "shepherd-inbox-hook.mjs")) + "]"
+    )
+  );
+  const exact = candidates.filter(
+    (block) => source.indexOf(block) >= 0 && source.indexOf(block) === source.lastIndexOf(block)
+  );
+  return exact.length === 1 ? exact[0] : void 0;
+}
+function migrateLegacy(context, state, sourceBytes, source) {
+  const { paths, command, log } = context;
+  const candidate = appendMissingCodexHandlers(source, command);
+  if (candidate === null) {
+    advanceRecord(paths.recordFile, state, "skipped", "unsupported-shape");
+    return "skipped";
+  }
+  const recordBytes = readFileSync7(paths.recordFile);
+  const configChanged = candidate !== source;
+  ensureMigrationBackup(paths.backupFile, sourceBytes);
+  if (!readConfigBytes(paths.configFile).equals(sourceBytes)) return "skipped";
+  try {
+    if (configChanged) atomicWrite(paths.configFile, candidate);
+    advanceRecord(paths.recordFile, state, "installed", "migrated");
+  } catch (error) {
+    if (!readConfigBytes(paths.configFile).equals(sourceBytes)) {
+      atomicWrite(paths.configFile, sourceBytes);
+    }
+    if (!readFileSync7(paths.recordFile).equals(recordBytes)) {
+      atomicWrite(paths.recordFile, recordBytes);
+    }
+    throw error;
+  }
+  log(
+    "[shepherd] Migrated Codex hooks. Persistent backup: " + paths.backupFile + "; you may remove it after validation."
+  );
+  return "installed";
+}
+function processLockedConfig(context, expectedFingerprint) {
+  const { paths, command, hookMarker } = context;
+  const state = readRecord(paths.recordFile);
+  if (state.kind === "current" || state.kind === "future") {
+    return "already-attempted";
+  }
+  if (state.kind === "corrupt") return "skipped";
+  const sourceBytes = readConfigBytes(paths.configFile);
+  if (fingerprint(sourceBytes) !== expectedFingerprint) return "skipped";
+  const source = decodeConfig(sourceBytes);
+  if (source === null) {
+    advanceRecord(paths.recordFile, state, "skipped", "unsupported-shape");
+    return "skipped";
+  }
+  const plan = planCodexConfig(source, command);
+  if (plan.kind === "skip") {
+    advanceRecord(paths.recordFile, state, "skipped", plan.outcome);
+    return "skipped";
+  }
+  if (plan.kind === "already-canonical") {
+    advanceRecord(
+      paths.recordFile,
+      state,
+      "already-present",
+      "already-canonical"
+    );
+    return "already-present";
+  }
+  const ownedBlock = exactOwnedLegacyBlock(source, paths.hooksDir);
+  if (state.kind === "legacy" && ownedBlock !== void 0) {
+    return migrateLegacy(context, state, sourceBytes, source);
+  }
+  if (ownedBlock !== void 0 || source.includes(CODEX_SHEPHERD_COMMENT) || source.includes(hookMarker)) {
+    advanceRecord(paths.recordFile, state, "already-present", "ambiguous");
+    return "already-present";
+  }
+  if (state.kind === "legacy") {
+    advanceRecord(paths.recordFile, state, "skipped", "user-removed");
+    return "skipped";
+  }
+  atomicWrite(paths.configFile, plan.candidate);
+  advanceRecord(paths.recordFile, state, "installed", "already-canonical");
+  return "installed";
+}
+async function installCodexHooks({
+  homeDir,
+  command,
+  hookMarker,
+  log
+}) {
+  const paths = migrationPaths(homeDir);
+  const context = { paths, command, hookMarker, log };
+  const initialRecord = readRecord(paths.recordFile);
+  if (initialRecord.kind === "current" || initialRecord.kind === "future") {
+    return "already-attempted";
+  }
+  if (initialRecord.kind === "corrupt") return "skipped";
+  let initialBytes;
+  try {
+    initialBytes = readConfigBytes(paths.configFile);
+  } catch (error) {
+    log(
+      "[shepherd] Codex hook migration could not read config: " + String(error)
+    );
+    return "skipped";
+  }
+  const expectedFingerprint = fingerprint(initialBytes);
+  const owner = acquireMigrationLock(paths.lockFile);
+  if (owner === null) return "skipped";
+  try {
+    await Promise.resolve();
+    return processLockedConfig(context, expectedFingerprint);
+  } catch (error) {
+    log("[shepherd] Codex hook migration skipped: " + String(error));
+    return "skipped";
+  } finally {
+    releaseMigrationLock(paths.lockFile, owner, log);
+  }
+}
+
+// src/hookInstall.ts
 function detectClient(clientName) {
   const name = (clientName ?? "").toLowerCase();
   if (!name) return "unknown";
@@ -2538,17 +3101,17 @@ function detectClient(clientName) {
 var HOOK_COMMAND = `npx -y --package=@korso/shepherd@${PACKAGE_VERSION} shepherd-inbox-hook`;
 var HOOK_MARKER = "shepherd-inbox-hook";
 function ensureHookScript(homeDir, hookScriptSource) {
-  const source = hookScriptSource ?? join5(dirname6(fileURLToPath(import.meta.url)), "inboxHook.js");
+  const source = hookScriptSource ?? join7(dirname7(fileURLToPath(import.meta.url)), "inboxHook.js");
   try {
-    if (!existsSync4(source)) return null;
-    const dest = join5(homeDir, ".shepherd", "hooks", "shepherd-inbox-hook.mjs");
-    const next = readFileSync6(source);
-    const current = existsSync4(dest) ? readFileSync6(dest) : null;
+    if (!existsSync6(source)) return null;
+    const dest = join7(homeDir, ".shepherd", "hooks", "shepherd-inbox-hook.mjs");
+    const next = readFileSync8(source);
+    const current = existsSync6(dest) ? readFileSync8(dest) : null;
     if (current === null || !current.equals(next)) {
-      mkdirSync5(dirname6(dest), { recursive: true });
+      mkdirSync6(dirname7(dest), { recursive: true });
       const tmp = dest + ".tmp";
-      writeFileSync6(tmp, next);
-      renameSync2(tmp, dest);
+      writeFileSync7(tmp, next);
+      renameSync3(tmp, dest);
     }
     return dest;
   } catch {
@@ -2558,16 +3121,6 @@ function ensureHookScript(homeDir, hookScriptSource) {
 function hookCommandFor(scriptPath) {
   return scriptPath === null ? HOOK_COMMAND : `node "${scriptPath.replace(/\\/g, "/")}"`;
 }
-function codexHookBlock(scriptPath) {
-  const command = scriptPath === null ? `["npx", "-y", "--package=@korso/shepherd@${PACKAGE_VERSION}", "shepherd-inbox-hook"]` : `["node", ${JSON.stringify(scriptPath)}]`;
-  return [
-    "",
-    "# Added by Shepherd: delivers teammate announcements to the agent. Remove to disable.",
-    "[[hooks.UserPromptSubmit]]",
-    `command = ${command}`,
-    ""
-  ].join("\n");
-}
 async function autoInstallHooks({
   clientName,
   homeDir = homedir5(),
@@ -2583,20 +3136,32 @@ async function autoInstallHooks({
       return { client, status: "unsupported" };
     }
     const scriptPath = ensureHookScript(homeDir, hookScriptSource);
-    const recordFile = join5(homeDir, ".shepherd", "hooks", `${client}.json`);
-    if (existsSync4(recordFile)) return { client, status: "already-attempted" };
+    const recordFile = join7(homeDir, ".shepherd", "hooks", `${client}.json`);
+    if (client === "codex") {
+      const status2 = await installCodexHooks({
+        homeDir,
+        command: hookCommandFor(scriptPath),
+        hookMarker: HOOK_MARKER,
+        log
+      });
+      if (status2 === "installed") {
+        log(
+          "[shepherd] Installed the announcement-delivery hook for codex (disable by removing it, or set SHEPHERD_NO_AUTO_HOOKS=1 to never auto-install)."
+        );
+      }
+      return { client, status: status2 };
+    }
+    if (existsSync6(recordFile)) return { client, status: "already-attempted" };
     let status;
     if (client === "claude") {
       status = installClaude(homeDir, scriptPath, log);
-    } else if (client === "codex") {
-      status = installCodex(homeDir, scriptPath, log);
     } else if (client === "cursor") {
       status = installCursor(homeDir, scriptPath, log);
     } else {
       status = installPi(homeDir, extensionSource, log);
     }
-    mkdirSync5(dirname6(recordFile), { recursive: true });
-    writeFileSync6(
+    mkdirSync6(dirname7(recordFile), { recursive: true });
+    writeFileSync7(
       recordFile,
       JSON.stringify({ status, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n",
       "utf8"
@@ -2615,10 +3180,10 @@ async function autoInstallHooks({
   }
 }
 function installClaude(homeDir, scriptPath, log) {
-  const settingsFile = join5(homeDir, ".claude", "settings.json");
+  const settingsFile = join7(homeDir, ".claude", "settings.json");
   let raw = "";
-  if (existsSync4(settingsFile)) {
-    raw = readFileSync6(settingsFile, "utf8");
+  if (existsSync6(settingsFile)) {
+    raw = readFileSync8(settingsFile, "utf8");
     if (raw.includes(HOOK_MARKER)) return "already-present";
   }
   let settings = {};
@@ -2661,60 +3226,15 @@ function installClaude(homeDir, scriptPath, log) {
     matcher: "*",
     hooks: [{ type: "command", command }]
   });
-  mkdirSync5(dirname6(settingsFile), { recursive: true });
-  writeFileSync6(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
-  return "installed";
-}
-function installCodex(homeDir, scriptPath, log) {
-  const configFile = join5(homeDir, ".codex", "config.toml");
-  const manualHint = "Add the hook manually (see the dashboard's Connect screen).";
-  const hookBlock = codexHookBlock(scriptPath);
-  if (!existsSync4(configFile)) {
-    mkdirSync5(dirname6(configFile), { recursive: true });
-    writeFileSync6(configFile, `[features]
-hooks = true
-${hookBlock}`, "utf8");
-    return "installed";
-  }
-  const toml = readFileSync6(configFile, "utf8");
-  if (toml.includes(HOOK_MARKER)) return "already-present";
-  if (/^\s*\[hooks\.UserPromptSubmit\]\s*$/m.test(toml)) {
-    log(
-      `[shepherd] ${configFile} defines [hooks.UserPromptSubmit] \u2014 not touching it. ${manualHint}`
-    );
-    return "skipped";
-  }
-  if (/^\s*\[features\]/m.test(toml)) {
-    const hooksKey = /^\s*hooks\s*=\s*(.+)$/m.exec(toml);
-    if (hooksKey && hooksKey[1].trim() !== "true") {
-      log(
-        `[shepherd] ${configFile} sets hooks = ${hooksKey[1].trim()} \u2014 respecting it. ${manualHint}`
-      );
-      return "skipped";
-    }
-    let updated = toml;
-    if (!hooksKey) {
-      updated = toml.replace(/^(\s*\[features\]\s*)$/m, `$1
-hooks = true`);
-    }
-    writeFileSync6(configFile, updated + hookBlock, "utf8");
-    return "installed";
-  }
-  writeFileSync6(
-    configFile,
-    `${toml}
-[features]
-hooks = true
-${hookBlock}`,
-    "utf8"
-  );
+  mkdirSync6(dirname7(settingsFile), { recursive: true });
+  writeFileSync7(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installCursor(homeDir, scriptPath, log) {
-  const hooksFile = join5(homeDir, ".cursor", "hooks.json");
+  const hooksFile = join7(homeDir, ".cursor", "hooks.json");
   let raw = "";
-  if (existsSync4(hooksFile)) {
-    raw = readFileSync6(hooksFile, "utf8");
+  if (existsSync6(hooksFile)) {
+    raw = readFileSync8(hooksFile, "utf8");
     if (raw.includes(HOOK_MARKER)) return "already-present";
   }
   let config = {};
@@ -2749,21 +3269,21 @@ function installCursor(homeDir, scriptPath, log) {
     return "skipped";
   }
   entries.push({ command: hookCommandFor(scriptPath) });
-  mkdirSync5(dirname6(hooksFile), { recursive: true });
-  writeFileSync6(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
+  mkdirSync6(dirname7(hooksFile), { recursive: true });
+  writeFileSync7(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installPi(homeDir, extensionSource, log) {
-  const source = extensionSource ?? join5(dirname6(fileURLToPath(import.meta.url)), "inboxExtension.js");
-  const dest = join5(homeDir, ".pi", "agent", "extensions", "shepherd-inbox.js");
-  if (existsSync4(dest)) return "already-present";
-  if (!existsSync4(source)) {
+  const source = extensionSource ?? join7(dirname7(fileURLToPath(import.meta.url)), "inboxExtension.js");
+  const dest = join7(homeDir, ".pi", "agent", "extensions", "shepherd-inbox.js");
+  if (existsSync6(dest)) return "already-present";
+  if (!existsSync6(source)) {
     log(
       `[shepherd] bundled Pi extension not found at ${source} \u2014 skipping auto-install.`
     );
     return "skipped";
   }
-  mkdirSync5(dirname6(dest), { recursive: true });
+  mkdirSync6(dirname7(dest), { recursive: true });
   copyFileSync(source, dest);
   return "installed";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) advisory cross-session coordination tools (work/done/announce/sync, plus link/unlink/decline) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "homepage": "https://github.com/Korso-AI/shepherd#readme",
   "bugs": {
@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29",
+    "smol-toml": "1.7.0",
     "zod": "^3"
   },
   "devDependencies": {