@korso/shepherd 0.11.1 → 0.11.3

package/dist/index.js

@@ -745,20 +745,52 @@ var EntitlementsStatusResponse = z2.object({
     reposUsed: z2.number().int()
   })
 });
+var AnalyticsRange = z2.enum(["24h", "7d", "30d", "90d"]);
+var AnalyticsBucket = z2.enum(["hour", "day"]);
+var PeriodMetric = z2.object({
+  current: z2.number().int().nonnegative(),
+  previous: z2.number().int().nonnegative(),
+  changePct: z2.number().nullable()
+});
+var DurationPercentiles = z2.object({
+  p50: z2.number().nonnegative().nullable(),
+  p95: z2.number().nonnegative().nullable()
+});
 var TrendPoint = z2.object({
-  // `YYYY-MM-DD` (UTC day).
   date: z2.string(),
   count: z2.number()
 });
+var TrendSeries = z2.object({
+  current: z2.array(TrendPoint),
+  previous: z2.array(TrendPoint)
+});
 var TopWorkspace = z2.object({
   name: z2.string(),
   slug: z2.string(),
-  members: z2.number(),
-  agents: z2.number(),
-  liveSessions: z2.number()
+  members: z2.number().int().nonnegative(),
+  agents: z2.number().int().nonnegative(),
+  liveSessions: z2.number().int().nonnegative(),
+  // Distinct agents with any session activity inside the window.
+  activeAgents: z2.number().int().nonnegative(),
+  sessions: z2.number().int().nonnegative(),
+  commits: z2.number().int().nonnegative(),
+  claimsReleased: z2.number().int().nonnegative(),
+  // Median released-claim duration (created_at -> released_at), seconds.
+  medianClaimSeconds: z2.number().nonnegative().nullable(),
+  // ISO timestamp of the most recent observed activity, or null if none.
+  lastActivityAt: IsoTimestamp.nullable()
 });
 var ShepherdAnalyticsResponse = z2.object({
   generatedAt: IsoTimestamp,
+  // Echo of the (validated) requested window plus the bucket granularity and
+  // the exact half-open window [windowStart, windowEnd) the hub computed
+  // against — clients label charts from these instead of re-deriving time math.
+  range: AnalyticsRange,
+  bucket: AnalyticsBucket,
+  windowStart: IsoTimestamp,
+  windowEnd: IsoTimestamp,
+  // Current-state totals: whole-platform counts as of `generatedAt`,
+  // independent of the requested range.
   totals: z2.object({
     accounts: z2.number(),
     workspaces: z2.number(),
@@ -778,12 +810,30 @@ var ShepherdAnalyticsResponse = z2.object({
     avgMembersPerWorkspace: z2.number(),
     largestWorkspace: z2.number()
   }),
+  // Range-scoped KPIs, each with its aligned previous-period comparison.
+  period: z2.object({
+    activeWorkspaces: PeriodMetric,
+    newAccounts: PeriodMetric,
+    newSessions: PeriodMetric,
+    commits: PeriodMetric,
+    claimsReleased: PeriodMetric
+  }),
+  // Observed timing diagnostics over the current window: session span is
+  // created_at -> last_heartbeat_at; claim duration is created_at ->
+  // released_at (released claims only).
+  timing: z2.object({
+    sessionSpanSeconds: DurationPercentiles,
+    claimDurationSeconds: DurationPercentiles
+  }),
   feedbackByType: z2.array(z2.object({ type: z2.string(), count: z2.number() })),
+  // Bucketed activity series (hourly for 24h, daily otherwise), each carrying
+  // its aligned previous-period twin for chart overlays.
   trends: z2.object({
-    newAccounts: z2.array(TrendPoint),
-    newWorkspaces: z2.array(TrendPoint),
-    newSessions: z2.array(TrendPoint),
-    commits: z2.array(TrendPoint)
+    newAccounts: TrendSeries,
+    newWorkspaces: TrendSeries,
+    newSessions: TrendSeries,
+    commits: TrendSeries,
+    claimsReleased: TrendSeries
   }),
   topWorkspaces: z2.array(TopWorkspace)
 });
@@ -1208,6 +1258,12 @@ function sessionMailboxPath(dir, serverPid) {
 function sessionMetaPath(dir, serverPid) {
   return join3(dir, `agent-${serverPid}.json`);
 }
+var HOOK_CHAIN_REACH = { codex: 8 };
+var DEFAULT_HOOK_CHAIN_REACH = 3;
+var MAX_HOOK_CHAIN_REACH = Math.max(
+  DEFAULT_HOOK_CHAIN_REACH,
+  ...Object.values(HOOK_CHAIN_REACH)
+);
 function normalizeCwd(cwd) {
   let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
@@ -1220,7 +1276,12 @@ function writeMailboxMeta(dir, serverPid, meta) {
     const tmp = `${dest}.tmp`;
     writeFileSync3(
       tmp,
-      JSON.stringify({ v: 1, cwd: normalizeCwd(meta.cwd), chain: meta.chain })
+      JSON.stringify({
+        v: 1,
+        cwd: normalizeCwd(meta.cwd),
+        chain: meta.chain,
+        ...meta.client === void 0 ? {} : { client: meta.client }
+      })
     );
     renameSync(tmp, dest);
   } catch {
@@ -2403,143 +2464,585 @@ function createHeartbeat({
   return { start, stop };
 }
 
-// src/instructions.ts
-function sanitizeWorkspace(workspace) {
-  return workspace.replace(/\s+/g, " ").slice(0, 64);
-}
-function buildInstructions(state, workspace) {
-  switch (state) {
-    case "linked":
-      return `${INTRO} This repository is linked to the \`${workspace ? sanitizeWorkspace(workspace) : "team"}\` workspace, so coordination is active.
+// src/hookInstall.ts
+import {
+  readFileSync as readFileSync8,
+  writeFileSync as writeFileSync7,
+  mkdirSync as mkdirSync6,
+  copyFileSync,
+  existsSync as existsSync6,
+  renameSync as renameSync3
+} from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname7, join as join7 } from "node:path";
+import { fileURLToPath } from "node:url";
 
-${PROCEDURE}`;
-    case "declined":
-      return "Shepherd (team coordination) is connected, but the user declined coordination for this repository. Do not call Shepherd tools or bring up coordination here. If the user asks to start coordinating this repo, call `link`.";
-    case "unanswered":
-      return `${INTRO}
+// 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";
 
-${FIRST_RUN_ASK}`;
+// 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;
   }
 }
-var INTRO = "You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories.";
-var FIRST_RUN_ASK = `This repository isn't linked to a Shepherd workspace yet, so coordination is dormant. Shepherd normally asks the user directly (a popup) when file edits are detected \u2014 you don't need to raise it yourself.
-
-If the user asks you to set up coordination \u2014 or you're about to change files and no popup or Shepherd message has settled the question \u2014 ask at most once: call \`link\` with no argument. It auto-links when the user belongs to exactly one workspace, or lists the choices; ask the user which workspace, then call \`link\` again with their answer. If they say no, call \`decline\` so they're never asked again. Once linked, the tool results will guide the coordination procedure.`;
-var PROCEDURE = `Follow this procedure on every session, proactively and without being asked:
-
-1. Before you start producing or changing files in an AREA of the codebase, call \`work\` ONCE. This includes authoring a plan or design doc: claim the doc's path (e.g. ["docs/plans/auth.md"], or the directory you'll write into) BEFORE you write it \u2014 a plan you're about to author counts as a unit of work, not exploration. Pass a one-line \`intent\` and the \`pathGlobs\` covering the files you expect to touch. Scope the globs as specifically as you reasonably can \u2014 tight enough to avoid colliding with unrelated work, broad enough to cover the task (e.g. ["src/auth/**"], not ["src/**"] and not a single file). Hold that one claim across all your edits in that area; do NOT re-claim per file. If it reports a conflict, coordinate or pick different work \u2014 never silently collide.
-
-2. Call \`done\` when that unit of work is complete, using its \`workItemId\`, so teammates see the files freed.
-
-3. Re-call \`work\` only when you move to a DIFFERENT area not covered by a live claim. (\`work\` and \`sync\` also renew your existing claims.)
-
-4. Call \`announce\` whenever you discover something another agent needs \u2014 a shared decision, a gotcha, an API change, a finding. If the landscape shows a specific agent working in the affected area, direct it to them by passing their name as \`target\`; otherwise broadcast. A human teammate's name (or \`admin\`) as \`target\` reaches them on the dashboard \u2014 reply to a human's message that way, directed to its sender, never in your own chat. Awareness only, not task assignment.
-
-5. Call \`sync\` when you resume, start a new task, or before large changes, to refresh who is doing what.
-
-Skip \`work\` entirely for read-only exploration \u2014 reading, searching, or thinking that produces no file. The moment you're going to WRITE something, source or doc, claim it first. These tools are advisory and degrade gracefully if the hub is unreachable \u2014 never block your real work on them.
-
-Commit work-in-progress as you go rather than sitting on a large dirty tree: committed work becomes a precise, presence-independent signal to teammates (with line-level detail and automatic resolution once it lands), whereas uncommitted edits are only a best-effort, decaying hint.`;
+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 hasCanonicalHandler(source, event, hookMarker) {
+  const headers = new RegExp("^\\[\\[hooks\\." + event + "\\]\\]$", "gm");
+  const boundary = new RegExp("^\\[(?!\\[hooks\\." + event + "\\.)", "m");
+  const nested = new RegExp("^\\[\\[hooks\\." + event + "\\.hooks\\]\\]$", "m");
+  let header;
+  while ((header = headers.exec(source)) !== null) {
+    const rest = source.slice(header.index + header[0].length);
+    const end = rest.search(boundary);
+    const group = end === -1 ? rest : rest.slice(0, end);
+    if (group.includes(hookMarker) && nested.test(group)) return true;
+  }
+  return false;
+}
+function appendMissingCodexHandlers(source, command, hookMarker) {
+  const handlers = [
+    ["UserPromptSubmit", void 0],
+    ["SessionStart", void 0],
+    ["PreToolUse", "*"]
+  ].filter(([event]) => !hasCanonicalHandler(source, event, hookMarker)).map(([event, matcher]) => canonicalHandlerBlock(event, command, matcher));
+  const candidate = handlers.length === 0 ? source : source + (source.endsWith("\n") ? "" : "\n") + handlers.join("");
+  return parseConfig2(candidate) === null ? null : candidate;
+}
 
-// src/processTree.ts
-import { execFile as execFile2 } from "node:child_process";
-import { promisify } from "node:util";
-var execFileAsync = promisify(execFile2);
-function pidChainFromMap(startPid, parentOf, maxDepth = 32) {
-  const chain = [];
-  const seen = /* @__PURE__ */ new Set();
-  let pid = startPid;
-  while (chain.length < maxDepth && pid > 0 && !seen.has(pid)) {
-    chain.push(pid);
-    seen.add(pid);
-    const parent = parentOf.get(pid);
-    if (parent === void 0) break;
-    pid = parent;
+// 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;
   }
-  return chain;
 }
-function quickChain() {
-  return [process.pid, process.ppid];
+function syncParent(path3) {
+  if (process.platform === "win32") return;
+  const descriptor = openSync(dirname6(path3), "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
 }
-function parseWmicProcessList(text) {
-  const map = /* @__PURE__ */ new Map();
-  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
-  if (lines.length === 0) return map;
-  const header = lines[0].trimStart();
-  let pidFirst;
-  if (header.startsWith("ParentProcessId")) pidFirst = false;
-  else if (header.startsWith("ProcessId")) pidFirst = true;
-  else return map;
-  for (const line of lines.slice(1)) {
-    const nums = line.trim().split(/\s+/).map(Number);
-    if (nums.length !== 2 || nums.some((n) => !Number.isInteger(n))) continue;
-    const [a, b] = nums;
-    const [pid, ppid] = pidFirst ? [a, b] : [b, a];
-    map.set(pid, ppid);
+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;
   }
-  return map;
 }
-function parsePidPpidLines(text) {
-  const map = /* @__PURE__ */ new Map();
-  for (const line of text.split(/\r?\n/)) {
-    const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
-    if (m) map.set(Number(m[1]), Number(m[2]));
+function processIsLive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) !== "ESRCH";
   }
-  return map;
 }
-async function snapshotParentMap() {
-  if (process.platform === "win32") {
+function lockSnapshot(lockFile) {
+  try {
+    const bytes = readFileSync6(lockFile);
+    const modifiedAt = statSync2(lockFile).mtimeMs;
+    let owner = null;
+    let reclaimable = false;
     try {
-      const { stdout: stdout3 } = await execFileAsync(
-        "wmic",
-        ["process", "get", "ProcessId,ParentProcessId"],
-        { windowsHide: true, timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
-      );
-      const map = parseWmicProcessList(stdout3);
-      if (map.size > 0) return map;
+      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 {
     }
-    const { stdout: stdout2 } = await execFileAsync(
-      "powershell.exe",
-      [
-        "-NoProfile",
-        "-NonInteractive",
-        "-Command",
-        'Get-CimInstance -Query "SELECT ProcessId,ParentProcessId FROM Win32_Process" | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId)" }'
-      ],
-      { windowsHide: true, timeout: 15e3, maxBuffer: 8 * 1024 * 1024 }
+    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)
     );
-    return parsePidPpidLines(stdout2);
   }
-  const { stdout } = await execFileAsync(
-    "ps",
-    ["-eo", "pid=,ppid="],
-    { timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
-  );
-  return parsePidPpidLines(stdout);
 }
-async function ancestorChain(maxDepth = 32, snapshot = snapshotParentMap) {
+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 {
-    const map = await snapshot();
-    const chain = pidChainFromMap(process.pid, map, maxDepth);
-    return chain.length >= 2 ? chain : quickChain();
+    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 = 3;
+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-v${MIGRATION_VERSION}.lock`),
+    backupFile: join6(
+      hooksDir,
+      "backups",
+      `codex-config-before-v${MIGRATION_VERSION}.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 quickChain();
+    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, hookMarker, log } = context;
+  const candidate = appendMissingCodexHandlers(source, command, hookMarker);
+  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
-import {
-  readFileSync as readFileSync6,
-  writeFileSync as writeFileSync6,
-  mkdirSync as mkdirSync5,
-  copyFileSync,
-  existsSync as existsSync4,
-  renameSync as renameSync2
-} from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { dirname as dirname6, join as join5 } from "node:path";
-import { fileURLToPath } from "node:url";
 function detectClient(clientName) {
   const name = (clientName ?? "").toLowerCase();
   if (!name) return "unknown";
@@ -2552,17 +3055,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 {
@@ -2572,16 +3075,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(),
@@ -2597,20 +3090,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"
@@ -2629,10 +3134,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 = {};
@@ -2675,60 +3180,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 = {};
@@ -2763,25 +3223,177 @@ 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";
 }
 
+// src/instructions.ts
+function sanitizeWorkspace(workspace) {
+  return workspace.replace(/\s+/g, " ").slice(0, 64);
+}
+function buildInstructions(state, workspace) {
+  switch (state) {
+    case "linked":
+      return `${INTRO} This repository is linked to the \`${workspace ? sanitizeWorkspace(workspace) : "team"}\` workspace, so coordination is active.
+
+${PROCEDURE}`;
+    case "declined":
+      return "Shepherd (team coordination) is connected, but the user declined coordination for this repository. Do not call Shepherd tools or bring up coordination here. If the user asks to start coordinating this repo, call `link`.";
+    case "unanswered":
+      return `${INTRO}
+
+${FIRST_RUN_ASK}`;
+  }
+}
+var INTRO = "You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories.";
+var FIRST_RUN_ASK = `This repository isn't linked to a Shepherd workspace yet, so coordination is dormant. Shepherd normally asks the user directly (a popup) when file edits are detected \u2014 you don't need to raise it yourself.
+
+If the user asks you to set up coordination \u2014 or you're about to change files and no popup or Shepherd message has settled the question \u2014 ask at most once: call \`link\` with no argument. It auto-links when the user belongs to exactly one workspace, or lists the choices; ask the user which workspace, then call \`link\` again with their answer. If they say no, call \`decline\` so they're never asked again. Once linked, the tool results will guide the coordination procedure.`;
+var PROCEDURE = `Follow this procedure on every session, proactively and without being asked:
+
+1. Before you start producing or changing files in an AREA of the codebase, call \`work\` ONCE. This includes authoring a plan or design doc: claim the doc's path (e.g. ["docs/plans/auth.md"], or the directory you'll write into) BEFORE you write it \u2014 a plan you're about to author counts as a unit of work, not exploration. Pass a one-line \`intent\` and the \`pathGlobs\` covering the files you expect to touch. Scope the globs as specifically as you reasonably can \u2014 tight enough to avoid colliding with unrelated work, broad enough to cover the task (e.g. ["src/auth/**"], not ["src/**"] and not a single file). Hold that one claim across all your edits in that area; do NOT re-claim per file. If it reports a conflict, coordinate or pick different work \u2014 never silently collide.
+
+2. Call \`done\` when that unit of work is complete, using its \`workItemId\`, so teammates see the files freed.
+
+3. Re-call \`work\` only when you move to a DIFFERENT area not covered by a live claim. (\`work\` and \`sync\` also renew your existing claims.)
+
+4. Call \`announce\` whenever you discover something another agent needs \u2014 a shared decision, a gotcha, an API change, a finding. If the landscape shows a specific agent working in the affected area, direct it to them by passing their name as \`target\`; otherwise broadcast. A human teammate's name (or \`admin\`) as \`target\` reaches them on the dashboard \u2014 reply to a human's message that way, directed to its sender, never in your own chat. Awareness only, not task assignment.
+
+5. Call \`sync\` when you resume, start a new task, or before large changes, to refresh who is doing what.
+
+Skip \`work\` entirely for read-only exploration \u2014 reading, searching, or thinking that produces no file. The moment you're going to WRITE something, source or doc, claim it first. These tools are advisory and degrade gracefully if the hub is unreachable \u2014 never block your real work on them.
+
+Commit work-in-progress as you go rather than sitting on a large dirty tree: committed work becomes a precise, presence-independent signal to teammates (with line-level detail and automatic resolution once it lands), whereas uncommitted edits are only a best-effort, decaying hint.`;
+function clientInjectsInstructions(client) {
+  return client === "claude";
+}
+function stageCoordinationBriefing({
+  clientName,
+  linkState,
+  workspace,
+  append
+}) {
+  if (linkState !== "linked") return false;
+  if (clientInjectsInstructions(detectClient(clientName))) return false;
+  append([coordinationBriefing(workspace)]);
+  return true;
+}
+function coordinationBriefing(workspace) {
+  const safeWorkspace = sanitizeWorkspace(workspace ?? "team");
+  return {
+    // Negative, timestamp-derived: the mailbox dedupes by id and the hub's ids
+    // are positive, so a locally-minted id can never collide with a real one.
+    id: -Date.now(),
+    fromAgentName: "shepherd",
+    fromHuman: "shepherd",
+    targetAgentName: null,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    body: `Shepherd coordination is ACTIVE for this repository (workspace \`${safeWorkspace}\`), and your client does not surface Shepherd's standing instructions \u2014 so they arrive here. Procedure from now on, proactively and without being asked: call \`work\` (a one-line intent plus the \`pathGlobs\` you expect to touch) BEFORE you start changing files in an area \u2014 a plan or design doc you are about to author counts \u2014 and hold that ONE claim across every edit in that area; call \`done\` with its \`workItemId\` when the unit of work is complete; call \`announce\` whenever you find something teammates need; call \`sync\` when you resume or switch tasks. Skip \`work\` for read-only exploration that produces no file. If \`work\` reports a conflict, coordinate or pick different work \u2014 never silently collide. These tools are advisory: never block real work on them.`
+  };
+}
+
+// src/processTree.ts
+import { execFile as execFile2 } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile2);
+function pidChainFromMap(startPid, parentOf, maxDepth = 32) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let pid = startPid;
+  while (chain.length < maxDepth && pid > 0 && !seen.has(pid)) {
+    chain.push(pid);
+    seen.add(pid);
+    const parent = parentOf.get(pid);
+    if (parent === void 0) break;
+    pid = parent;
+  }
+  return chain;
+}
+function quickChain() {
+  return [process.pid, process.ppid];
+}
+function parseWmicProcessList(text) {
+  const map = /* @__PURE__ */ new Map();
+  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  if (lines.length === 0) return map;
+  const header = lines[0].trimStart();
+  let pidFirst;
+  if (header.startsWith("ParentProcessId")) pidFirst = false;
+  else if (header.startsWith("ProcessId")) pidFirst = true;
+  else return map;
+  for (const line of lines.slice(1)) {
+    const nums = line.trim().split(/\s+/).map(Number);
+    if (nums.length !== 2 || nums.some((n) => !Number.isInteger(n))) continue;
+    const [a, b] = nums;
+    const [pid, ppid] = pidFirst ? [a, b] : [b, a];
+    map.set(pid, ppid);
+  }
+  return map;
+}
+function parsePidPpidLines(text) {
+  const map = /* @__PURE__ */ new Map();
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+    if (m) map.set(Number(m[1]), Number(m[2]));
+  }
+  return map;
+}
+async function snapshotParentMap() {
+  if (process.platform === "win32") {
+    try {
+      const { stdout: stdout3 } = await execFileAsync(
+        "wmic",
+        ["process", "get", "ProcessId,ParentProcessId"],
+        { windowsHide: true, timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
+      );
+      const map = parseWmicProcessList(stdout3);
+      if (map.size > 0) return map;
+    } catch {
+    }
+    const { stdout: stdout2 } = await execFileAsync(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        'Get-CimInstance -Query "SELECT ProcessId,ParentProcessId FROM Win32_Process" | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId)" }'
+      ],
+      { windowsHide: true, timeout: 15e3, maxBuffer: 8 * 1024 * 1024 }
+    );
+    return parsePidPpidLines(stdout2);
+  }
+  const { stdout } = await execFileAsync(
+    "ps",
+    ["-eo", "pid=,ppid="],
+    { timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
+  );
+  return parsePidPpidLines(stdout);
+}
+async function ancestorChain(maxDepth = 32, snapshot = snapshotParentMap) {
+  try {
+    const map = await snapshot();
+    const chain = pidChainFromMap(process.pid, map, maxDepth);
+    return chain.length >= 2 ? chain : quickChain();
+  } catch {
+    return quickChain();
+  }
+}
+
 // src/index.ts
 async function main() {
   const config = loadConfig();
@@ -2794,10 +3406,12 @@ async function main() {
   const inboxFile = sessionMailboxPath(inboxDir, process.pid);
   const launchCwd = process.cwd();
   let serverChain = quickChain();
+  let serverClient;
   const liveness = {
     refresh: () => writeMailboxMeta(inboxDir, process.pid, {
       cwd: launchCwd,
-      chain: serverChain
+      chain: serverChain,
+      client: serverClient
     }),
     remove: () => removeMailboxMeta(inboxDir, process.pid)
   };
@@ -2837,10 +3451,19 @@ async function main() {
   });
   const transport = new StdioServerTransport();
   server.server.oninitialized = () => {
+    const clientName = server.server.getClientVersion()?.name;
     void autoInstallHooks({
-      clientName: server.server.getClientVersion()?.name,
+      clientName,
       disabled: config.SHEPHERD_NO_AUTO_HOOKS
     });
+    serverClient = detectClient(clientName);
+    liveness.refresh();
+    stageCoordinationBriefing({
+      clientName,
+      linkState: context.linkState,
+      workspace: context.workspace,
+      append: (announcements) => appendAnnouncements(inboxFile, announcements)
+    });
   };
   let shuttingDown = false;
   const shutdown = async () => {