@korso/shepherd 0.9.1 → 0.10.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

@@ -712,6 +712,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 +1172,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 +1195,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 +1277,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) {
@@ -1419,7 +1488,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 +1503,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)}`;
 }
@@ -1529,6 +1585,7 @@ function registerTools(server, deps) {
   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 +1618,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 +1646,7 @@ function registerTools(server, deps) {
         heartbeat.start(newSessionId);
         sessionId = newSessionId;
         agentName = parsed.data.agentName;
+        activeWorkspaceSlug = workspaceSlug;
         linked = true;
         hostedWorkspaceRejected = false;
         joinFailure = null;
@@ -1932,6 +1993,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,7 +2100,7 @@ function postLinkGuidance(workspace) {
 }
 
 // src/identityCache.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
 import { homedir as homedir3, tmpdir as tmpdir3 } from "node:os";
 import { dirname as dirname4, join as join4 } from "node:path";
 function defaultIdentityCachePath() {
@@ -2071,7 +2133,7 @@ function writeCachedHuman(human, filePath = defaultIdentityCachePath()) {
   try {
     mkdirSync3(dirname4(filePath), { recursive: true });
     const payload = JSON.stringify({ human });
-    writeFileSync3(filePath, payload + "\n", "utf8");
+    writeFileSync4(filePath, payload + "\n", "utf8");
   } catch {
   }
 }
@@ -2130,13 +2192,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 +2219,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 +2252,12 @@ function createHeartbeat({
   }
   function start(sessionId) {
     stop();
+    if (liveness) {
+      try {
+        liveness.refresh();
+      } catch {
+      }
+    }
     timer = setInterval(() => {
       void beat(sessionId).catch((err) => {
         console.error(
@@ -2227,10 +2308,97 @@ 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,
+  writeFileSync as writeFileSync5,
   mkdirSync as mkdirSync4,
   copyFileSync,
   existsSync as existsSync4,
@@ -2274,7 +2442,7 @@ function ensureHookScript(homeDir, hookScriptSource) {
     if (current === null || !current.equals(next)) {
       mkdirSync4(dirname5(dest), { recursive: true });
       const tmp = dest + ".tmp";
-      writeFileSync4(tmp, next);
+      writeFileSync5(tmp, next);
       renameSync2(tmp, dest);
     }
     return dest;
@@ -2283,7 +2451,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)}]`;
@@ -2323,7 +2491,7 @@ async function autoInstallHooks({
       status = installPi(homeDir, extensionSource, log);
     }
     mkdirSync4(dirname5(recordFile), { recursive: true });
-    writeFileSync4(
+    writeFileSync5(
       recordFile,
       JSON.stringify({ status, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n",
       "utf8"
@@ -2389,7 +2557,7 @@ function installClaude(homeDir, scriptPath, log) {
     hooks: [{ type: "command", command }]
   });
   mkdirSync4(dirname5(settingsFile), { recursive: true });
-  writeFileSync4(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  writeFileSync5(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installCodex(homeDir, scriptPath, log) {
@@ -2398,7 +2566,7 @@ function installCodex(homeDir, scriptPath, log) {
   const hookBlock = codexHookBlock(scriptPath);
   if (!existsSync4(configFile)) {
     mkdirSync4(dirname5(configFile), { recursive: true });
-    writeFileSync4(configFile, `[features]
+    writeFileSync5(configFile, `[features]
 hooks = true
 ${hookBlock}`, "utf8");
     return "installed";
@@ -2424,10 +2592,10 @@ ${hookBlock}`, "utf8");
       updated = toml.replace(/^(\s*\[features\]\s*)$/m, `$1
 hooks = true`);
     }
-    writeFileSync4(configFile, updated + hookBlock, "utf8");
+    writeFileSync5(configFile, updated + hookBlock, "utf8");
     return "installed";
   }
-  writeFileSync4(
+  writeFileSync5(
     configFile,
     `${toml}
 [features]
@@ -2477,7 +2645,7 @@ function installCursor(homeDir, scriptPath, log) {
   }
   entries.push({ command: hookCommandFor(scriptPath) });
   mkdirSync4(dirname5(hooksFile), { recursive: true });
-  writeFileSync4(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
+  writeFileSync5(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installPi(homeDir, extensionSource, log) {
@@ -2504,7 +2672,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 +2699,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.10.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": {