@korso/shepherd 0.9.1 → 0.11.0

package/dist/inboxExtension.js

@@ -4,8 +4,11 @@ import {
   appendFileSync,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync3,
+  readdirSync,
   renameSync,
   rmSync as rmSync3,
+  statSync,
+  writeFileSync as writeFileSync3,
   existsSync as existsSync3
 } from "node:fs";
 import { homedir as homedir2, tmpdir as tmpdir2 } from "node:os";
@@ -123,11 +126,79 @@ function defaultInboxDir() {
   if (!base) base = tmpdir2();
   return join3(base, ".shepherd", "inbox");
 }
+function cwdHash(cwd) {
+  let normalized = resolve3(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  return createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+}
 function inboxFilePath(dir, cwd) {
+  return join3(dir, `${cwdHash(cwd)}.jsonl`);
+}
+var MAILBOX_TTL_MS = 24 * 60 * 60 * 1e3;
+var MAILBOX_FRESH_MS = 15 * 60 * 1e3;
+function sessionMailboxPath(dir, serverPid) {
+  return join3(dir, `agent-${serverPid}.jsonl`);
+}
+function normalizeCwd(cwd) {
   let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
-  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join3(dir, `${hash}.jsonl`);
+  return normalized;
+}
+function selectSessionMailboxes(dir, hookChain, hookCwd, staleMs = MAILBOX_FRESH_MS, nowMs = Date.now()) {
+  try {
+    const chain = hookChain.slice(0, 3);
+    const wantedCwd = hookCwd === null ? null : normalizeCwd(hookCwd);
+    const candidates = [];
+    for (const name of readdirSync(dir)) {
+      const m = /^agent-(\d+)\.json$/.exec(name);
+      if (!m) continue;
+      const serverPid = Number(m[1]);
+      const metaFile = join3(dir, name);
+      let mtimeMs;
+      try {
+        mtimeMs = statSync(metaFile).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (nowMs - mtimeMs > MAILBOX_TTL_MS) {
+        try {
+          rmSync3(metaFile, { force: true });
+          rmSync3(sessionMailboxPath(dir, serverPid), { force: true });
+          rmSync3(`${sessionMailboxPath(dir, serverPid)}.draining`, {
+            force: true
+          });
+        } catch {
+        }
+        continue;
+      }
+      if (nowMs - mtimeMs > staleMs) continue;
+      let meta;
+      try {
+        meta = JSON.parse(readFileSync3(metaFile, "utf8"));
+      } catch {
+        continue;
+      }
+      if (!Array.isArray(meta.chain) || typeof meta.cwd !== "string") continue;
+      const i = chain.findIndex((pid) => meta.chain.includes(pid));
+      if (i === -1) continue;
+      const j = meta.chain.indexOf(chain[i]);
+      if (i >= 2 && (j > 2 || wantedCwd === null || meta.cwd !== wantedCwd))
+        continue;
+      candidates.push({ pid: serverPid, i, j, cwd: meta.cwd });
+    }
+    if (candidates.length === 0) return [];
+    const best = candidates.reduce(
+      (a, b) => b.i < a.i || b.i === a.i && b.j < a.j ? b : a
+    );
+    let winners = candidates.filter((c) => c.i === best.i && c.j === best.j);
+    if (winners.length > 1 && new Set(winners.map((w) => w.cwd)).size > 1) {
+      if (wantedCwd === null) return [];
+      winners = winners.filter((w) => w.cwd === wantedCwd);
+    }
+    return winners.map((w) => sessionMailboxPath(dir, w.pid));
+  } catch {
+    return [];
+  }
 }
 function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
@@ -170,21 +241,44 @@ function oneLine(text) {
 function indentContinuation(text) {
   return text.replace(/\r?\n/g, "\n      ");
 }
+function relativeAge(iso) {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return "recently";
+  const ms = Date.now() - then;
+  if (ms < 0) return "just now";
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
 function formatInboxAnnouncements(announcements) {
   if (!announcements || announcements.length === 0) return "";
   const count = announcements.length;
   const lines = [
-    `[Shepherd] ${count} new announcement${count === 1 ? "" : "s"} from your teammates:`
+    `[Shepherd] ${count} announcement${count === 1 ? "" : "s"} from your teammates:`
   ];
   for (const a of announcements) {
     const target = a.targetAgentName ? ` \u2192 ${oneLine(a.targetAgentName)}` : " (broadcast)";
     lines.push(
-      `  [${oneLine(a.fromAgentName)}${target}] ${indentContinuation(a.body)}`
+      `  [${oneLine(a.fromAgentName)}${target}, ${relativeAge(a.createdAt)}] ${indentContinuation(a.body)}`
     );
   }
   lines.push(REPLY_ROUTING_HINT);
   return lines.join("\n");
 }
+function mergeAnnouncements(...lists) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    if (!list) continue;
+    for (const a of list) {
+      if (!byId.has(a.id)) byId.set(a.id, a);
+    }
+  }
+  return [...byId.values()].sort((x, y) => x.id - y.id);
+}
 
 // src/instructions.ts
 function sanitizeWorkspace(workspace) {
@@ -235,7 +329,10 @@ function shepherdInbox(pi) {
     try {
       const dir = process.env["SHEPHERD_INBOX_DIR"] || defaultInboxDir();
       const cwd = ctx?.cwd ?? process.cwd();
-      const announcements = drainInbox(inboxFilePath(dir, cwd));
+      const announcements = mergeAnnouncements(
+        ...selectSessionMailboxes(dir, [process.pid], cwd).map(drainInbox),
+        drainInbox(inboxFilePath(dir, cwd))
+      );
       const messageContent = [
         buildLinkNudge(cwd),
         formatInboxAnnouncements(announcements)

package/dist/inboxHook.js

@@ -6,8 +6,11 @@ import {
   appendFileSync,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync3,
+  readdirSync,
   renameSync,
   rmSync as rmSync3,
+  statSync,
+  writeFileSync as writeFileSync3,
   existsSync as existsSync3
 } from "node:fs";
 import { homedir as homedir2, tmpdir as tmpdir2 } from "node:os";
@@ -125,11 +128,94 @@ function defaultInboxDir() {
   if (!base) base = tmpdir2();
   return join3(base, ".shepherd", "inbox");
 }
+function cwdHash(cwd) {
+  let normalized = resolve3(cwd);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  return createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+}
 function inboxFilePath(dir, cwd) {
+  return join3(dir, `${cwdHash(cwd)}.jsonl`);
+}
+var MAILBOX_TTL_MS = 24 * 60 * 60 * 1e3;
+var MAILBOX_FRESH_MS = 15 * 60 * 1e3;
+function sessionMailboxPath(dir, serverPid) {
+  return join3(dir, `agent-${serverPid}.jsonl`);
+}
+function normalizeCwd(cwd) {
   let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
-  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join3(dir, `${hash}.jsonl`);
+  return normalized;
+}
+function hasFreshSessionMeta(dir, staleMs = MAILBOX_FRESH_MS, nowMs = Date.now()) {
+  try {
+    for (const name of readdirSync(dir)) {
+      if (!/^agent-\d+\.json$/.test(name)) continue;
+      try {
+        if (nowMs - statSync(join3(dir, name)).mtimeMs <= staleMs) return true;
+      } catch {
+        continue;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function selectSessionMailboxes(dir, hookChain, hookCwd, staleMs = MAILBOX_FRESH_MS, nowMs = Date.now()) {
+  try {
+    const chain = hookChain.slice(0, 3);
+    const wantedCwd = hookCwd === null ? null : normalizeCwd(hookCwd);
+    const candidates = [];
+    for (const name of readdirSync(dir)) {
+      const m = /^agent-(\d+)\.json$/.exec(name);
+      if (!m) continue;
+      const serverPid = Number(m[1]);
+      const metaFile = join3(dir, name);
+      let mtimeMs;
+      try {
+        mtimeMs = statSync(metaFile).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (nowMs - mtimeMs > MAILBOX_TTL_MS) {
+        try {
+          rmSync3(metaFile, { force: true });
+          rmSync3(sessionMailboxPath(dir, serverPid), { force: true });
+          rmSync3(`${sessionMailboxPath(dir, serverPid)}.draining`, {
+            force: true
+          });
+        } catch {
+        }
+        continue;
+      }
+      if (nowMs - mtimeMs > staleMs) continue;
+      let meta;
+      try {
+        meta = JSON.parse(readFileSync3(metaFile, "utf8"));
+      } catch {
+        continue;
+      }
+      if (!Array.isArray(meta.chain) || typeof meta.cwd !== "string") continue;
+      const i = chain.findIndex((pid) => meta.chain.includes(pid));
+      if (i === -1) continue;
+      const j = meta.chain.indexOf(chain[i]);
+      if (i >= 2 && (j > 2 || wantedCwd === null || meta.cwd !== wantedCwd))
+        continue;
+      candidates.push({ pid: serverPid, i, j, cwd: meta.cwd });
+    }
+    if (candidates.length === 0) return [];
+    const best = candidates.reduce(
+      (a, b) => b.i < a.i || b.i === a.i && b.j < a.j ? b : a
+    );
+    let winners = candidates.filter((c) => c.i === best.i && c.j === best.j);
+    if (winners.length > 1 && new Set(winners.map((w) => w.cwd)).size > 1) {
+      if (wantedCwd === null) return [];
+      winners = winners.filter((w) => w.cwd === wantedCwd);
+    }
+    return winners.map((w) => sessionMailboxPath(dir, w.pid));
+  } catch {
+    return [];
+  }
 }
 function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
@@ -172,26 +258,60 @@ function oneLine(text) {
 function indentContinuation(text) {
   return text.replace(/\r?\n/g, "\n      ");
 }
+function relativeAge(iso) {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return "recently";
+  const ms = Date.now() - then;
+  if (ms < 0) return "just now";
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
 function formatInboxAnnouncements(announcements) {
   if (!announcements || announcements.length === 0) return "";
   const count = announcements.length;
   const lines = [
-    `[Shepherd] ${count} new announcement${count === 1 ? "" : "s"} from your teammates:`
+    `[Shepherd] ${count} announcement${count === 1 ? "" : "s"} from your teammates:`
   ];
   for (const a of announcements) {
     const target = a.targetAgentName ? ` \u2192 ${oneLine(a.targetAgentName)}` : " (broadcast)";
     lines.push(
-      `  [${oneLine(a.fromAgentName)}${target}] ${indentContinuation(a.body)}`
+      `  [${oneLine(a.fromAgentName)}${target}, ${relativeAge(a.createdAt)}] ${indentContinuation(a.body)}`
     );
   }
   lines.push(REPLY_ROUTING_HINT);
   return lines.join("\n");
 }
+function mergeAnnouncements(...lists) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    if (!list) continue;
+    for (const a of list) {
+      if (!byId.has(a.id)) byId.set(a.id, a);
+    }
+  }
+  return [...byId.values()].sort((x, y) => x.id - y.id);
+}
 function nativeWorkspacePath(root) {
   const win = /^\/([A-Za-z]:[/\\].*)$/.exec(root);
   return win ? win[1] : root;
 }
-function buildHookOutput(rawStdin, inboxDir, drain = drainInbox, nudge = buildLinkNudge) {
+function parseHookPairingInput(rawStdin) {
+  try {
+    const input = JSON.parse(rawStdin.replace(/^\uFEFF/, ""));
+    const sessionId = typeof input.session_id === "string" && input.session_id.length > 0 ? input.session_id : void 0;
+    const firstRoot = Array.isArray(input.workspace_roots) ? input.workspace_roots[0] : void 0;
+    const cwd = typeof input.cwd === "string" && input.cwd.length > 0 ? input.cwd : typeof firstRoot === "string" && firstRoot.length > 0 ? nativeWorkspacePath(firstRoot) : null;
+    return { sessionId, cwd };
+  } catch {
+    return { sessionId: void 0, cwd: null };
+  }
+}
+function buildHookOutput(rawStdin, inboxDir, drain = drainInbox, nudge = buildLinkNudge, sessionMailboxes = []) {
   let input;
   try {
     input = JSON.parse(rawStdin.replace(/^\uFEFF/, ""));
@@ -210,7 +330,11 @@ function buildHookOutput(rawStdin, inboxDir, drain = drainInbox, nudge = buildLi
   );
   if (nudgeText) parts.push(nudgeText);
   if (inboxDir) {
-    const text = formatInboxAnnouncements(drain(inboxFilePath(inboxDir, cwd)));
+    const drained = mergeAnnouncements(
+      ...sessionMailboxes.map((box) => drain(box)),
+      drain(inboxFilePath(inboxDir, cwd))
+    );
+    const text = formatInboxAnnouncements(drained);
     if (text) parts.push(text);
   }
   if (parts.length === 0) return "";
@@ -228,6 +352,168 @@ function buildHookOutput(rawStdin, inboxDir, drain = drainInbox, nudge = buildLi
   });
 }
 
+// src/hookPairing.ts
+import { createHash as createHash3 } from "node:crypto";
+import {
+  readFileSync as readFileSync4,
+  writeFileSync as writeFileSync4,
+  renameSync as renameSync2,
+  readdirSync as readdirSync2,
+  rmSync as rmSync4,
+  statSync as statSync2
+} from "node:fs";
+import { join as join4 } from "node:path";
+
+// src/processTree.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+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/hookPairing.ts
+function pairingCachePath(dir, sessionId) {
+  const key = createHash3("sha256").update(sessionId).digest("hex").slice(0, 16);
+  return join4(dir, `pairing-${key}.json`);
+}
+function readCachedChain(file, nowMs) {
+  try {
+    const parsed = JSON.parse(readFileSync4(file, "utf8"));
+    if (!Array.isArray(parsed.chain) || typeof parsed.ts !== "number")
+      return null;
+    if (nowMs - parsed.ts > MAILBOX_TTL_MS) return null;
+    return parsed.chain;
+  } catch {
+    return null;
+  }
+}
+function writeCachedChain(dir, file, chain, nowMs) {
+  try {
+    for (const name of readdirSync2(dir)) {
+      if (!name.startsWith("pairing-") || !name.endsWith(".json")) continue;
+      try {
+        if (nowMs - statSync2(join4(dir, name)).mtimeMs > MAILBOX_TTL_MS) {
+          rmSync4(join4(dir, name), { force: true });
+        }
+      } catch {
+      }
+    }
+    const tmp = `${file}.tmp`;
+    writeFileSync4(tmp, JSON.stringify({ chain, ts: nowMs }));
+    renameSync2(tmp, file);
+  } catch {
+  }
+}
+async function resolveHookMailboxes(inboxDir, { sessionId, cwd }, deps = {}) {
+  const quick = deps.quick ?? quickChain;
+  const full = deps.full ?? (() => ancestorChain());
+  const nowMs = deps.nowMs ?? Date.now();
+  try {
+    let boxes = selectSessionMailboxes(
+      inboxDir,
+      quick(),
+      cwd,
+      void 0,
+      nowMs
+    );
+    if (boxes.length > 0) return boxes;
+    if (!hasFreshSessionMeta(inboxDir, void 0, nowMs)) return [];
+    const cacheFile = sessionId ? pairingCachePath(inboxDir, sessionId) : null;
+    if (cacheFile) {
+      const cached = readCachedChain(cacheFile, nowMs);
+      if (cached) {
+        boxes = selectSessionMailboxes(inboxDir, cached, cwd, void 0, nowMs);
+        if (boxes.length > 0) return boxes;
+      }
+    }
+    const chain = await full();
+    if (cacheFile) writeCachedChain(inboxDir, cacheFile, chain, nowMs);
+    return selectSessionMailboxes(inboxDir, chain, cwd, void 0, nowMs);
+  } catch {
+    return [];
+  }
+}
+
 // src/inboxHook.ts
 async function readStdin() {
   const chunks = [];
@@ -240,7 +526,15 @@ async function main() {
   try {
     const raw = await readStdin();
     const inboxDir = process.argv[2] || process.env["SHEPHERD_INBOX_DIR"] || defaultInboxDir();
-    const out = buildHookOutput(raw, inboxDir);
+    let mailboxes = [];
+    try {
+      mailboxes = await resolveHookMailboxes(
+        inboxDir,
+        parseHookPairingInput(raw)
+      );
+    } catch {
+    }
+    const out = buildHookOutput(raw, inboxDir, void 0, void 0, mailboxes);
     if (out) process.stdout.write(out);
   } catch {
   }

package/dist/index.js

@@ -481,7 +481,12 @@ var JoinRequest = z2.object({
 });
 var JoinResponse = z2.object({
   agentName: z2.string(),
-  sessionId: z2.string().uuid()
+  sessionId: z2.string().uuid(),
+  // Advertised so clients can nudge their humans to update. Optional: older
+  // hubs omit them, and a hub that cannot determine its bundled client
+  // version fails open by leaving them out.
+  latestClientVersion: z2.string().optional(),
+  minimumClientVersion: z2.string().optional()
 });
 var WorkRequest = z2.object({
   sessionId: z2.string().uuid(),
@@ -712,6 +717,34 @@ var FeedbackResponse = z2.object({
   // uuid PK (the feedback table, like workspaces, uses gen_random_uuid()).
   id: z2.string()
 });
+var NullableCap = z2.number().int().positive().nullable();
+var EntitlementLimits = z2.object({
+  seatsLimit: NullableCap,
+  reposLimit: NullableCap,
+  retentionDays: NullableCap
+});
+var LimitExceededErrorBody = z2.object({
+  error: z2.string(),
+  code: z2.literal("limit_exceeded"),
+  limit: z2.enum(["seats", "repos"]),
+  current: z2.number().int(),
+  max: z2.number().int()
+});
+var WorkspaceEntitlements = EntitlementLimits.extend({
+  expiresAt: IsoTimestamp.nullable(),
+  updatedAt: IsoTimestamp
+});
+var PutEntitlementsRequest = EntitlementLimits.extend({
+  expiresAt: IsoTimestamp.nullable()
+});
+var EntitlementsStatusResponse = z2.object({
+  record: WorkspaceEntitlements.nullable(),
+  effective: EntitlementLimits,
+  usage: z2.object({
+    seatsUsed: z2.number().int(),
+    reposUsed: z2.number().int()
+  })
+});
 var TrendPoint = z2.object({
   // `YYYY-MM-DD` (UTC day).
   date: z2.string(),
@@ -1144,13 +1177,15 @@ async function buildChangeReport(cwd, config) {
 }
 
 // src/inbox.ts
-import { createHash as createHash2 } from "node:crypto";
 import {
   appendFileSync,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync3,
+  readdirSync,
   renameSync,
   rmSync as rmSync3,
+  statSync,
+  writeFileSync as writeFileSync3,
   existsSync as existsSync3
 } from "node:fs";
 import { homedir as homedir2, tmpdir as tmpdir2 } from "node:os";
@@ -1165,11 +1200,37 @@ function defaultInboxDir() {
   if (!base) base = tmpdir2();
   return join3(base, ".shepherd", "inbox");
 }
-function inboxFilePath(dir, cwd) {
+var MAILBOX_TTL_MS = 24 * 60 * 60 * 1e3;
+var MAILBOX_FRESH_MS = 15 * 60 * 1e3;
+function sessionMailboxPath(dir, serverPid) {
+  return join3(dir, `agent-${serverPid}.jsonl`);
+}
+function sessionMetaPath(dir, serverPid) {
+  return join3(dir, `agent-${serverPid}.json`);
+}
+function normalizeCwd(cwd) {
   let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
-  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join3(dir, `${hash}.jsonl`);
+  return normalized;
+}
+function writeMailboxMeta(dir, serverPid, meta) {
+  try {
+    mkdirSync2(dir, { recursive: true });
+    const dest = sessionMetaPath(dir, serverPid);
+    const tmp = `${dest}.tmp`;
+    writeFileSync3(
+      tmp,
+      JSON.stringify({ v: 1, cwd: normalizeCwd(meta.cwd), chain: meta.chain })
+    );
+    renameSync(tmp, dest);
+  } catch {
+  }
+}
+function removeMailboxMeta(dir, serverPid) {
+  try {
+    rmSync3(sessionMetaPath(dir, serverPid), { force: true });
+  } catch {
+  }
 }
 function appendAnnouncements(filePath, announcements) {
   if (!announcements || announcements.length === 0) return;
@@ -1221,6 +1282,19 @@ function oneLine(text) {
 function indentContinuation(text) {
   return text.replace(/\r?\n/g, "\n      ");
 }
+function relativeAge(iso) {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return "recently";
+  const ms = Date.now() - then;
+  if (ms < 0) return "just now";
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
 function mergeAnnouncements(...lists) {
   const byId = /* @__PURE__ */ new Map();
   for (const list of lists) {
@@ -1299,6 +1373,81 @@ function defaultRunGitStatus(cwd) {
   });
 }
 
+// src/updateNudge.ts
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname4 } from "node:path";
+var NUDGE_COOLDOWN_MS = 24 * 60 * 60 * 1e3;
+function parseVersion(v) {
+  const m = /^v?(\d+(?:\.\d+)*)/.exec(v.trim());
+  if (!m) return null;
+  return m[1].split(".").map(Number);
+}
+function compareVersions(a, b) {
+  const pa = parseVersion(a) ?? [];
+  const pb = parseVersion(b) ?? [];
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function readStamp(stampFile) {
+  try {
+    const parsed = JSON.parse(readFileSync4(stampFile, "utf8"));
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.latest === "string" && typeof parsed.at === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+function writeStamp(stampFile, stamp) {
+  try {
+    mkdirSync3(dirname4(stampFile), { recursive: true });
+    writeFileSync4(stampFile, JSON.stringify(stamp), "utf8");
+  } catch {
+  }
+}
+var SUGGEST = "Let your human know, and suggest the update command that matches how Shepherd is installed on this machine (global npm, an npx cache, a version manager, \u2026).";
+function maybeUpdateNudge(opts) {
+  const now = opts.nowMs ?? Date.now();
+  if (!parseVersion(opts.current)) return "";
+  const latest = opts.latest !== void 0 && parseVersion(opts.latest) ? opts.latest : void 0;
+  const minimum = opts.minimum !== void 0 && parseVersion(opts.minimum) ? opts.minimum : void 0;
+  const belowMinimum = minimum !== void 0 && compareVersions(opts.current, minimum) < 0;
+  const behind = latest !== void 0 && compareVersions(opts.current, latest) < 0;
+  if (!belowMinimum && !behind) return "";
+  if (!belowMinimum) {
+    const stamp = readStamp(opts.stampFile);
+    if (stamp !== null && compareVersions(latest, stamp.latest) <= 0 && now - stamp.at < NUDGE_COOLDOWN_MS) {
+      return "";
+    }
+  }
+  writeStamp(opts.stampFile, { latest: latest ?? opts.current, at: now });
+  if (belowMinimum) {
+    const latestPart = latest !== void 0 ? ` (latest: ${latest})` : "";
+    return `[shepherd] This client (${opts.current}) is below the minimum supported version ${minimum}${latestPart} \u2014 coordination may misbehave until it is updated. ${SUGGEST}`;
+  }
+  return `[shepherd] Update available: @korso/shepherd ${latest} (this machine runs ${opts.current}). ${SUGGEST}`;
+}
+
+// src/version.ts
+import { createRequire } from "node:module";
+var PACKAGE_VERSION = (() => {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkg = req("../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+// src/tools.ts
+import { homedir as homedir3 } from "node:os";
+import nodePath from "node:path";
+
 // src/linkPopup.ts
 var NEVER_ASK_CHOICE = "No \u2014 don't ask again";
 async function offerLinkPopup({
@@ -1419,7 +1568,7 @@ function formatLandscape(landscape) {
     for (const a of landscape.announcements) {
       const target = a.targetAgentName ? ` \u2192 ${oneLine(a.targetAgentName)}` : " (broadcast)";
       lines.push(
-        `  [${oneLine(a.fromAgentName)}${target}] ${indentContinuation(a.body)}`
+        `  [${oneLine(a.fromAgentName)}${target}, ${relativeAge(a.createdAt)}] ${indentContinuation(a.body)}`
       );
     }
     lines.push(REPLY_ROUTING_HINT);
@@ -1434,25 +1583,12 @@ function formatAnnouncements(announcements) {
   for (const a of announcements) {
     const target = a.targetAgentName ? ` \u2192 ${oneLine(a.targetAgentName)}` : " (broadcast)";
     lines.push(
-      `  [${oneLine(a.fromAgentName)}${target}] ${indentContinuation(a.body)}`
+      `  [${oneLine(a.fromAgentName)}${target}, ${relativeAge(a.createdAt)}] ${indentContinuation(a.body)}`
     );
   }
   lines.push(REPLY_ROUTING_HINT);
   return lines.join("\n");
 }
-function relativeAge(iso) {
-  const then = Date.parse(iso);
-  if (Number.isNaN(then)) return "recently";
-  const ms = Date.now() - then;
-  if (ms < 0) return "just now";
-  const mins = Math.floor(ms / 6e4);
-  if (mins < 1) return "just now";
-  if (mins < 60) return `${mins}m ago`;
-  const hours = Math.floor(mins / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  return `${days}d ago`;
-}
 function presence(rec) {
   return rec.authorIsLive ? "active now" : `offline, last seen ${relativeAge(rec.authorLastActiveAt)}`;
 }
@@ -1526,9 +1662,37 @@ function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
   const markerCwd = deps.cwd ?? process.cwd();
   const declinedDir = deps.declinedDir;
+  const updateNudge = deps.updateNudge ?? ((versions) => maybeUpdateNudge({
+    current: PACKAGE_VERSION,
+    latest: versions.latest,
+    minimum: versions.minimum,
+    stampFile: nodePath.join(homedir3(), ".shepherd", "update-nudge.json")
+  }));
+  let latestClientVersion;
+  let minimumClientVersion;
+  let nudgeDelivered = false;
+  function withUpdateNudge(text) {
+    if (nudgeDelivered) return text;
+    if (latestClientVersion === void 0 && minimumClientVersion === void 0) {
+      return text;
+    }
+    nudgeDelivered = true;
+    let nudge = "";
+    try {
+      nudge = updateNudge({
+        latest: latestClientVersion,
+        minimum: minimumClientVersion
+      });
+    } catch {
+    }
+    return nudge ? `${text}
+
+${nudge}` : text;
+  }
   const repoRoot = findRepoRoot(markerCwd);
   let sessionId = null;
   let agentName = null;
+  let activeWorkspaceSlug = null;
   const isHosted = Boolean(config.SHEPHERD_TOKEN);
   const selfHostMismatch = !isHosted && context.linked && config.WORKSPACE !== void 0 && config.WORKSPACE !== context.workspace;
   let hostedWorkspaceRejected = false;
@@ -1561,6 +1725,9 @@ function registerTools(server, deps) {
   let joinFailure = null;
   let joinInFlight = Promise.resolve();
   async function activate(workspaceSlug) {
+    if (sessionId !== null && activeWorkspaceSlug === workspaceSlug) {
+      return { ok: true };
+    }
     const joinBody = {
       workspace: workspaceSlug,
       repo: context.repo,
@@ -1586,6 +1753,9 @@ function registerTools(server, deps) {
         heartbeat.start(newSessionId);
         sessionId = newSessionId;
         agentName = parsed.data.agentName;
+        latestClientVersion = parsed.data.latestClientVersion;
+        minimumClientVersion = parsed.data.minimumClientVersion;
+        activeWorkspaceSlug = workspaceSlug;
         linked = true;
         hostedWorkspaceRejected = false;
         joinFailure = null;
@@ -1726,7 +1896,7 @@ ${section}` : body;
 You hold this claim until you call done (workItemId: ${result.workItemId}) or it expires (~60 min). Calling work or sync renews it.`
           )
         );
-        return { content: [{ type: "text", text }] };
+        return { content: [{ type: "text", text: withUpdateNudge(text) }] };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
           return degradedResult(err);
@@ -1757,9 +1927,14 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
           mergeAnnouncements(result.announcements, drainLocalInbox())
         );
         return {
-          content: [{ type: "text", text: msgs ? `${base}
+          content: [
+            {
+              type: "text",
+              text: withUpdateNudge(msgs ? `${base}
 
-${msgs}` : base }]
+${msgs}` : base)
+            }
+          ]
         };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -1791,9 +1966,14 @@ ${msgs}` : base }]
           mergeAnnouncements(result.announcements, drainLocalInbox())
         );
         return {
-          content: [{ type: "text", text: msgs ? `${base}
+          content: [
+            {
+              type: "text",
+              text: withUpdateNudge(msgs ? `${base}
 
-${msgs}` : base }]
+${msgs}` : base)
+            }
+          ]
         };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -1831,7 +2011,7 @@ ${msgs}` : base }]
             formatLandscape(result.landscape)
           )
         );
-        return { content: [{ type: "text", text }] };
+        return { content: [{ type: "text", text: withUpdateNudge(text) }] };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
           return degradedResult(err);
@@ -1932,6 +2112,7 @@ ${msgs}` : base }]
         await leave();
         sessionId = null;
         agentName = null;
+        activeWorkspaceSlug = null;
       }
       return advisory(
         "Unlinked \u2014 this repo will stay uncoordinated and won't ask again. Run `link` to re-enable."
@@ -2038,13 +2219,13 @@ function postLinkGuidance(workspace) {
 }
 
 // src/identityCache.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
-import { homedir as homedir3, tmpdir as tmpdir3 } from "node:os";
-import { dirname as dirname4, join as join4 } from "node:path";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir4, tmpdir as tmpdir3 } from "node:os";
+import { dirname as dirname5, join as join4 } from "node:path";
 function defaultIdentityCachePath() {
   let base = "";
   try {
-    base = homedir3();
+    base = homedir4();
   } catch {
     base = "";
   }
@@ -2054,7 +2235,7 @@ function defaultIdentityCachePath() {
 function readCachedHuman(filePath = defaultIdentityCachePath()) {
   let raw;
   try {
-    raw = readFileSync4(filePath, "utf8");
+    raw = readFileSync5(filePath, "utf8");
   } catch {
     return null;
   }
@@ -2069,9 +2250,9 @@ function readCachedHuman(filePath = defaultIdentityCachePath()) {
 function writeCachedHuman(human, filePath = defaultIdentityCachePath()) {
   if (typeof human !== "string" || human.trim().length === 0) return;
   try {
-    mkdirSync3(dirname4(filePath), { recursive: true });
+    mkdirSync4(dirname5(filePath), { recursive: true });
     const payload = JSON.stringify({ human });
-    writeFileSync3(filePath, payload + "\n", "utf8");
+    writeFileSync5(filePath, payload + "\n", "utf8");
   } catch {
   }
 }
@@ -2130,13 +2311,20 @@ function createHeartbeat({
   hubClient,
   intervalSeconds,
   buildReport,
-  announcementSink
+  announcementSink,
+  liveness
 }) {
   let timer = null;
   function stop() {
     if (timer !== null) {
       clearInterval(timer);
       timer = null;
+      if (liveness) {
+        try {
+          liveness.remove();
+        } catch {
+        }
+      }
     }
   }
   async function beat(sessionId) {
@@ -2150,6 +2338,12 @@ function createHeartbeat({
     }
     const body = { sessionId };
     if (changeReport) body.changeReport = changeReport;
+    if (liveness) {
+      try {
+        liveness.refresh();
+      } catch {
+      }
+    }
     if (announcementSink) body.deliverAnnouncements = true;
     const parsed = HeartbeatResponse.safeParse(
       await hubClient.post("/heartbeat", body)
@@ -2177,6 +2371,12 @@ function createHeartbeat({
   }
   function start(sessionId) {
     stop();
+    if (liveness) {
+      try {
+        liveness.refresh();
+      } catch {
+      }
+    }
     timer = setInterval(() => {
       void beat(sessionId).catch((err) => {
         console.error(
@@ -2227,32 +2427,105 @@ Skip \`work\` entirely for read-only exploration \u2014 reading, searching, or t
 
 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.`;
 
+// 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/hookInstall.ts
 import {
-  readFileSync as readFileSync5,
-  writeFileSync as writeFileSync4,
-  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync6,
+  writeFileSync as writeFileSync6,
+  mkdirSync as mkdirSync5,
   copyFileSync,
   existsSync as existsSync4,
   renameSync as renameSync2
 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { dirname as dirname5, join as join5 } from "node:path";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname6, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
-
-// src/version.ts
-import { createRequire } from "node:module";
-var PACKAGE_VERSION = (() => {
-  try {
-    const req = createRequire(import.meta.url);
-    const pkg = req("../package.json");
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-})();
-
-// src/hookInstall.ts
 function detectClient(clientName) {
   const name = (clientName ?? "").toLowerCase();
   if (!name) return "unknown";
@@ -2265,16 +2538,16 @@ 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(dirname5(fileURLToPath(import.meta.url)), "inboxHook.js");
+  const source = hookScriptSource ?? join5(dirname6(fileURLToPath(import.meta.url)), "inboxHook.js");
   try {
     if (!existsSync4(source)) return null;
     const dest = join5(homeDir, ".shepherd", "hooks", "shepherd-inbox-hook.mjs");
-    const next = readFileSync5(source);
-    const current = existsSync4(dest) ? readFileSync5(dest) : null;
+    const next = readFileSync6(source);
+    const current = existsSync4(dest) ? readFileSync6(dest) : null;
     if (current === null || !current.equals(next)) {
-      mkdirSync4(dirname5(dest), { recursive: true });
+      mkdirSync5(dirname6(dest), { recursive: true });
       const tmp = dest + ".tmp";
-      writeFileSync4(tmp, next);
+      writeFileSync6(tmp, next);
       renameSync2(tmp, dest);
     }
     return dest;
@@ -2283,7 +2556,7 @@ function ensureHookScript(homeDir, hookScriptSource) {
   }
 }
 function hookCommandFor(scriptPath) {
-  return scriptPath === null ? HOOK_COMMAND : `node "${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)}]`;
@@ -2297,7 +2570,7 @@ function codexHookBlock(scriptPath) {
 }
 async function autoInstallHooks({
   clientName,
-  homeDir = homedir4(),
+  homeDir = homedir5(),
   disabled = false,
   extensionSource,
   hookScriptSource,
@@ -2322,8 +2595,8 @@ async function autoInstallHooks({
     } else {
       status = installPi(homeDir, extensionSource, log);
     }
-    mkdirSync4(dirname5(recordFile), { recursive: true });
-    writeFileSync4(
+    mkdirSync5(dirname6(recordFile), { recursive: true });
+    writeFileSync6(
       recordFile,
       JSON.stringify({ status, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n",
       "utf8"
@@ -2345,7 +2618,7 @@ function installClaude(homeDir, scriptPath, log) {
   const settingsFile = join5(homeDir, ".claude", "settings.json");
   let raw = "";
   if (existsSync4(settingsFile)) {
-    raw = readFileSync5(settingsFile, "utf8");
+    raw = readFileSync6(settingsFile, "utf8");
     if (raw.includes(HOOK_MARKER)) return "already-present";
   }
   let settings = {};
@@ -2388,8 +2661,8 @@ function installClaude(homeDir, scriptPath, log) {
     matcher: "*",
     hooks: [{ type: "command", command }]
   });
-  mkdirSync4(dirname5(settingsFile), { recursive: true });
-  writeFileSync4(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  mkdirSync5(dirname6(settingsFile), { recursive: true });
+  writeFileSync6(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installCodex(homeDir, scriptPath, log) {
@@ -2397,13 +2670,13 @@ function installCodex(homeDir, scriptPath, log) {
   const manualHint = "Add the hook manually (see the dashboard's Connect screen).";
   const hookBlock = codexHookBlock(scriptPath);
   if (!existsSync4(configFile)) {
-    mkdirSync4(dirname5(configFile), { recursive: true });
-    writeFileSync4(configFile, `[features]
+    mkdirSync5(dirname6(configFile), { recursive: true });
+    writeFileSync6(configFile, `[features]
 hooks = true
 ${hookBlock}`, "utf8");
     return "installed";
   }
-  const toml = readFileSync5(configFile, "utf8");
+  const toml = readFileSync6(configFile, "utf8");
   if (toml.includes(HOOK_MARKER)) return "already-present";
   if (/^\s*\[hooks\.UserPromptSubmit\]\s*$/m.test(toml)) {
     log(
@@ -2424,10 +2697,10 @@ ${hookBlock}`, "utf8");
       updated = toml.replace(/^(\s*\[features\]\s*)$/m, `$1
 hooks = true`);
     }
-    writeFileSync4(configFile, updated + hookBlock, "utf8");
+    writeFileSync6(configFile, updated + hookBlock, "utf8");
     return "installed";
   }
-  writeFileSync4(
+  writeFileSync6(
     configFile,
     `${toml}
 [features]
@@ -2441,7 +2714,7 @@ function installCursor(homeDir, scriptPath, log) {
   const hooksFile = join5(homeDir, ".cursor", "hooks.json");
   let raw = "";
   if (existsSync4(hooksFile)) {
-    raw = readFileSync5(hooksFile, "utf8");
+    raw = readFileSync6(hooksFile, "utf8");
     if (raw.includes(HOOK_MARKER)) return "already-present";
   }
   let config = {};
@@ -2476,12 +2749,12 @@ function installCursor(homeDir, scriptPath, log) {
     return "skipped";
   }
   entries.push({ command: hookCommandFor(scriptPath) });
-  mkdirSync4(dirname5(hooksFile), { recursive: true });
-  writeFileSync4(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
+  mkdirSync5(dirname6(hooksFile), { recursive: true });
+  writeFileSync6(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installPi(homeDir, extensionSource, log) {
-  const source = extensionSource ?? join5(dirname5(fileURLToPath(import.meta.url)), "inboxExtension.js");
+  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)) {
@@ -2490,7 +2763,7 @@ function installPi(homeDir, extensionSource, log) {
     );
     return "skipped";
   }
-  mkdirSync4(dirname5(dest), { recursive: true });
+  mkdirSync5(dirname6(dest), { recursive: true });
   copyFileSync(source, dest);
   return "installed";
 }
@@ -2504,7 +2777,21 @@ async function main() {
   });
   const context = await resolveContext(config);
   const inboxDir = config.SHEPHERD_INBOX_DIR ?? defaultInboxDir();
-  const inboxFile = inboxFilePath(inboxDir, process.cwd());
+  const inboxFile = sessionMailboxPath(inboxDir, process.pid);
+  const launchCwd = process.cwd();
+  let serverChain = quickChain();
+  const liveness = {
+    refresh: () => writeMailboxMeta(inboxDir, process.pid, {
+      cwd: launchCwd,
+      chain: serverChain
+    }),
+    remove: () => removeMailboxMeta(inboxDir, process.pid)
+  };
+  void ancestorChain().then((chain) => {
+    serverChain = chain;
+    liveness.refresh();
+  }).catch(() => {
+  });
   const heartbeat = createHeartbeat({
     hubClient,
     intervalSeconds: config.HEARTBEAT_INTERVAL_SECONDS,
@@ -2517,10 +2804,11 @@ async function main() {
         return void 0;
       }
     },
-    // A model-visible sink (this working dir's inbox file). Its presence opts
-    // the heartbeat into two-phase announcement delivery: append locally, then
+    // A model-visible sink (this session's mailbox). Its presence opts the
+    // heartbeat into two-phase announcement delivery: append locally, then
     // ack the hub. appendAnnouncements is itself fail-open.
-    announcementSink: (announcements) => appendAnnouncements(inboxFile, announcements)
+    announcementSink: (announcements) => appendAnnouncements(inboxFile, announcements),
+    liveness
   });
   const server = new McpServer(
     { name: "shepherd", version: PACKAGE_VERSION },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "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": {