@korso/shepherd 0.9.0 → 0.10.0

package/dist/index.js

@@ -9,7 +9,9 @@ import { z } from "zod";
 var DEFAULT_WORKSPACE = "default";
 var ConfigSchema = z.object({
   // Hard-required: Hub endpoint.
-  HUB_URL: z.string({ required_error: "HUB_URL is required" }).url("HUB_URL must be a full URL, e.g. https://your-shepherd-hub.example.com"),
+  HUB_URL: z.string({ required_error: "HUB_URL is required" }).url(
+    "HUB_URL must be a full URL, e.g. https://your-shepherd-hub.example.com"
+  ),
   // Auth credentials. Exactly one form is needed (enforced by the refine below):
   //   - SHEPHERD_TOKEN: the hosted Hub credential (carries its own workspace).
   //   - TEAM_TOKEN: the self-host credential.
@@ -67,33 +69,51 @@ function parseConfig(env) {
 function loadConfig(env = process.env) {
   try {
     const config = parseConfig(env);
-    warnInsecureHubUrl(config.HUB_URL);
+    assertHubUrlAllowed(config.HUB_URL, env);
     return config;
   } catch (err) {
     if (err instanceof z.ZodError) {
       const messages = err.issues.map((e) => `  ${e.path.join(".")}: ${e.message}`).join("\n");
-      process.stderr.write(`[shepherd] Configuration error \u2014 missing or invalid env vars:
+      process.stderr.write(
+        `[shepherd] Configuration error \u2014 missing or invalid env vars:
 ${messages}
+`
+      );
+    } else if (err instanceof Error) {
+      process.stderr.write(`[shepherd] Configuration error: ${err.message}
 `);
     } else {
-      process.stderr.write(`[shepherd] Unexpected configuration error: ${String(err)}
-`);
+      process.stderr.write(
+        `[shepherd] Unexpected configuration error: ${String(err)}
+`
+      );
     }
     process.exit(1);
   }
 }
-function warnInsecureHubUrl(hubUrl) {
+function assertHubUrlAllowed(hubUrl, env = process.env) {
+  let url;
   try {
-    const url = new URL(hubUrl);
-    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
-    if (url.protocol === "http:" && !loopback) {
-      process.stderr.write(
-        `[shepherd] WARNING: HUB_URL (${hubUrl}) uses plain http to a non-local host \u2014 the team token and all coordination traffic travel unencrypted. Use https.
-`
-      );
-    }
+    url = new URL(hubUrl);
   } catch {
+    return;
+  }
+  if (url.protocol !== "http:") return;
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
+  if (loopback) return;
+  const allowInsecure = ["1", "true", "yes"].includes(
+    (env["SHEPHERD_ALLOW_INSECURE_HTTP"] ?? "").toLowerCase()
+  );
+  if (allowInsecure) {
+    process.stderr.write(
+      `[shepherd] WARNING: HUB_URL (${hubUrl}) uses plain http to a non-local host \u2014 the team token and all coordination traffic travel unencrypted (permitted via SHEPHERD_ALLOW_INSECURE_HTTP). Use https.
+`
+    );
+    return;
   }
+  throw new Error(
+    `HUB_URL (${hubUrl}) uses plain http to a non-local host \u2014 the team token would travel unencrypted. Use https, or set SHEPHERD_ALLOW_INSECURE_HTTP=1 to permit cleartext to a private-network hub (not recommended).`
+  );
 }
 
 // src/hubClient.ts
@@ -125,7 +145,7 @@ function createHubClient({
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     const headers = {
-      "Authorization": `Bearer ${token}`
+      Authorization: `Bearer ${token}`
     };
     if (method === "POST") {
       headers["Content-Type"] = "application/json";
@@ -520,7 +540,10 @@ var SyncRequest = z2.object({
 var SyncResponse = z2.object({
   landscape: Landscape
 });
-var WorkAgentInput = WorkRequest.omit({ sessionId: true, changeReport: true });
+var WorkAgentInput = WorkRequest.omit({
+  sessionId: true,
+  changeReport: true
+});
 var AnnounceAgentInput = AnnounceRequest.omit({ sessionId: true });
 var DoneAgentInput = DoneRequest.omit({ sessionId: true });
 var JoinAgentInput = z2.object({});
@@ -576,7 +599,10 @@ var WorkspaceSummary = z2.object({
   isOwner: z2.boolean()
 });
 var CreateWorkspaceRequest = z2.object({
-  name: z2.string().min(1)
+  // Cap the name like every other persisted string field (256), so a workspace
+  // name (and the slug candidate derived from it) can't be inflated toward the
+  // request body limit. min(1) keeps the "non-empty" contract.
+  name: z2.string().min(1).max(256)
 });
 var ListWorkspacesResponse = z2.object({
   workspaces: z2.array(WorkspaceSummary)
@@ -670,15 +696,50 @@ var TransferOwnershipResponse = z2.object({
   ok: z2.literal(true)
 });
 var FeedbackType = z2.enum(["bug", "suggestion", "other"]);
+var FeedbackContext = z2.object({
+  route: z2.string().max(256).optional(),
+  appVersion: z2.string().max(256).optional(),
+  userAgent: z2.string().max(512).optional(),
+  viewport: z2.string().max(256).optional()
+});
 var FeedbackRequest = z2.object({
   type: FeedbackType,
-  body: z2.string().trim().min(1).max(4e3)
+  body: z2.string().trim().min(1).max(4e3),
+  context: FeedbackContext.optional()
 });
 var FeedbackResponse = z2.object({
   ok: z2.literal(true),
   // 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(),
@@ -723,9 +784,10 @@ var ShepherdAnalyticsResponse = z2.object({
 });
 
 // src/marker.ts
-import * as fs from "fs";
-import * as path from "path";
+import * as fs from "node:fs";
+import * as path from "node:path";
 var MARKER_FILENAME = ".shepherd";
+var WORKSPACE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 function findRepoRoot(cwd) {
   let dir = path.resolve(cwd);
   for (; ; ) {
@@ -750,8 +812,12 @@ function readMarker(cwd = process.cwd()) {
   }
   try {
     const parsed = JSON.parse(raw);
-    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string" && parsed.workspace.length > 0) {
-      return { workspace: parsed.workspace };
+    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string") {
+      const workspace = parsed.workspace;
+      if (WORKSPACE_SLUG_PATTERN.test(workspace)) {
+        return { workspace };
+      }
+      return null;
     }
     return null;
   } catch {
@@ -761,7 +827,9 @@ function readMarker(cwd = process.cwd()) {
 function writeMarker(cwd = process.cwd(), slug) {
   const file = markerPath(cwd);
   if (file === null) {
-    throw new Error("not inside a git repository \u2014 cannot write .shepherd marker");
+    throw new Error(
+      "not inside a git repository \u2014 cannot write .shepherd marker"
+    );
   }
   fs.writeFileSync(file, JSON.stringify({ workspace: slug }) + "\n", "utf8");
 }
@@ -775,10 +843,16 @@ function removeMarker(cwd = process.cwd()) {
 }
 
 // src/declined.ts
-import { createHash } from "crypto";
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
-import { homedir, tmpdir } from "os";
-import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { createHash } from "node:crypto";
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
 function defaultDeclinedDir() {
   let base = "";
   try {
@@ -814,7 +888,9 @@ function setDeclined(repoRoot, dir = defaultDeclinedDir()) {
   const file = declinedFilePath(repoRoot, dir);
   try {
     mkdirSync(dirname2(file), { recursive: true });
-    const payload = JSON.stringify({ declinedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    const payload = JSON.stringify({
+      declinedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
     writeFileSync2(file, payload + "\n", "utf8");
   } catch (err) {
     console.error(
@@ -835,8 +911,8 @@ function clearDeclined(repoRoot, dir = defaultDeclinedDir()) {
 }
 
 // src/gitContext.ts
-import { execFileSync } from "child_process";
-import * as path2 from "path";
+import { execFileSync } from "node:child_process";
+import * as path2 from "node:path";
 var GIT_TIMEOUT_MS = 2e3;
 var MAX_COMMITS = 100;
 var MAX_PATHS_PER_COMMIT = 500;
@@ -911,13 +987,22 @@ function detectHuman(cwd = process.cwd()) {
   return null;
 }
 function detectBaseBranch(cwd = process.cwd()) {
-  const symref = runGit(cwd, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]);
+  const symref = runGit(cwd, [
+    "symbolic-ref",
+    "--quiet",
+    "refs/remotes/origin/HEAD"
+  ]);
   if (symref) {
     const stripped = symref.replace(/^refs\/remotes\//, "");
     if (stripped) return stripped;
   }
   for (const candidate of ["origin/main", "origin/master"]) {
-    if (runGitExitOk(cwd, ["rev-parse", "--verify", "--quiet", `refs/remotes/${candidate}`])) {
+    if (runGitExitOk(cwd, [
+      "rev-parse",
+      "--verify",
+      "--quiet",
+      `refs/remotes/${candidate}`
+    ])) {
       return candidate;
     }
   }
@@ -970,7 +1055,12 @@ function unlandedCommits(cwd = process.cwd(), baseBranch) {
   return { commits, truncated };
 }
 function dirtyPaths(cwd = process.cwd()) {
-  const out = runGit(cwd, ["status", "--porcelain", "-z", "--untracked-files=all"]);
+  const out = runGit(cwd, [
+    "status",
+    "--porcelain",
+    "-z",
+    "--untracked-files=all"
+  ]);
   if (out === null) {
     return { paths: [], truncated: false };
   }
@@ -1082,17 +1172,19 @@ async function buildChangeReport(cwd, config) {
 }
 
 // src/inbox.ts
-import { createHash as createHash2 } from "crypto";
 import {
   appendFileSync,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync3,
+  readdirSync,
   renameSync,
   rmSync as rmSync3,
+  statSync,
+  writeFileSync as writeFileSync3,
   existsSync as existsSync3
-} from "fs";
-import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
-import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
+} from "node:fs";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "node:os";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "node:path";
 function defaultInboxDir() {
   let base = "";
   try {
@@ -1103,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;
@@ -1159,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) {
@@ -1171,7 +1302,7 @@ function mergeAnnouncements(...lists) {
 }
 
 // src/editTripwire.ts
-import { execFile } from "child_process";
+import { execFile } from "node:child_process";
 function createEditTripwire({
   cwd,
   intervalMs = 3e4,
@@ -1325,7 +1456,7 @@ function formatLandscape(landscape) {
     lines.push("CONFLICTS (files overlapping with your claim):");
     for (const c of landscape.conflicts) {
       lines.push(
-        `  [${c.agentName} / ${c.human}] "${oneLine(c.intent)}" \u2014 globs: ${oneLine(c.pathGlobs.join(", "))}`
+        `  [${oneLine(c.agentName)} / ${oneLine(c.human)}] "${oneLine(c.intent)}" \u2014 globs: ${oneLine(c.pathGlobs.join(", "))}`
       );
     }
   } else {
@@ -1335,7 +1466,7 @@ function formatLandscape(landscape) {
     lines.push("ACTIVE CLAIMS (other agents currently working):");
     for (const c of landscape.activeClaims) {
       lines.push(
-        `  [${c.agentName} / ${c.human}] "${oneLine(c.intent)}" \u2014 globs: ${oneLine(c.pathGlobs.join(", "))}`
+        `  [${oneLine(c.agentName)} / ${oneLine(c.human)}] "${oneLine(c.intent)}" \u2014 globs: ${oneLine(c.pathGlobs.join(", "))}`
       );
     }
   } else {
@@ -1355,8 +1486,10 @@ function formatLandscape(landscape) {
   if (landscape.announcements.length > 0) {
     lines.push("ANNOUNCEMENTS:");
     for (const a of landscape.announcements) {
-      const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
-      lines.push(`  [${a.fromAgentName}${target}] ${indentContinuation(a.body)}`);
+      const target = a.targetAgentName ? ` \u2192 ${oneLine(a.targetAgentName)}` : " (broadcast)";
+      lines.push(
+        `  [${oneLine(a.fromAgentName)}${target}, ${relativeAge(a.createdAt)}] ${indentContinuation(a.body)}`
+      );
     }
     lines.push(REPLY_ROUTING_HINT);
   } else {
@@ -1368,25 +1501,14 @@ function formatAnnouncements(announcements) {
   if (!announcements || announcements.length === 0) return "";
   const lines = ["Messages for you:"];
   for (const a of announcements) {
-    const target = a.targetAgentName ? ` \u2192 ${a.targetAgentName}` : " (broadcast)";
-    lines.push(`  [${a.fromAgentName}${target}] ${indentContinuation(a.body)}`);
+    const target = a.targetAgentName ? ` \u2192 ${oneLine(a.targetAgentName)}` : " (broadcast)";
+    lines.push(
+      `  [${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)}`;
 }
@@ -1402,7 +1524,7 @@ function formatChangeRecords(records, cwd = process.cwd()) {
       const state = present ? "landed, not yet in your branch \u2014 pull/rebase" : "not yet on your base \u2014 unpushed, coordinate";
       const intent = oneLine(rec.message ?? "(work in progress)");
       lines.push(
-        `  ${rec.agentName} / ${rec.human} (${presence(rec)}) \u2014 committed (${state}): "${intent}"`
+        `  ${oneLine(rec.agentName)} / ${oneLine(rec.human)} (${presence(rec)}) \u2014 committed (${state}): "${intent}"`
       );
       lines.push(`    files: ${oneLine(rec.paths.join(", "))}`);
       if (sha && present && lineRangeBudget > 0) {
@@ -1410,7 +1532,9 @@ function formatChangeRecords(records, cwd = process.cwd()) {
         lineRangeBudget -= budgetedPaths.length;
         const ranges = changedLineRanges(cwd, sha, budgetedPaths);
         for (const p of Object.keys(ranges)) {
-          const spans = ranges[p].map((r) => r.start === r.end ? `${r.start}` : `${r.start}-${r.end}`);
+          const spans = ranges[p].map(
+            (r) => r.start === r.end ? `${r.start}` : `${r.start}-${r.end}`
+          );
           if (spans.length > 0) {
             lines.push(`    ${p}: lines ${spans.join(", ")} (for context)`);
           }
@@ -1419,7 +1543,7 @@ function formatChangeRecords(records, cwd = process.cwd()) {
     } else {
       const claim = oneLine(rec.message ?? "uncommitted edits in progress");
       lines.push(
-        `  ${rec.agentName} / ${rec.human} (${presence(rec)}) \u2014 ${claim} (uncommitted, may change)`
+        `  ${oneLine(rec.agentName)} / ${oneLine(rec.human)} (${presence(rec)}) \u2014 ${claim} (uncommitted, may change)`
       );
       lines.push(`    files: ${oneLine(rec.paths.join(", "))}`);
     }
@@ -1441,6 +1565,19 @@ function degradedResult(err) {
     ]
   };
 }
+function malformedResponseResult(endpoint) {
+  console.error(
+    `[shepherd] ${endpoint} returned a response that failed contract validation \u2014 proceeding uncoordinated.`
+  );
+  return {
+    content: [
+      {
+        type: "text",
+        text: "Coordination hub returned an invalid response \u2014 proceeding uncoordinated."
+      }
+    ]
+  };
+}
 function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
   const markerCwd = deps.cwd ?? process.cwd();
@@ -1448,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;
@@ -1480,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,
@@ -1505,6 +1646,7 @@ function registerTools(server, deps) {
         heartbeat.start(newSessionId);
         sessionId = newSessionId;
         agentName = parsed.data.agentName;
+        activeWorkspaceSlug = workspaceSlug;
         linked = true;
         hostedWorkspaceRejected = false;
         joinFailure = null;
@@ -1598,7 +1740,10 @@ ${body}` : body;
   function withChangeRecords(landscape, body) {
     let section = "";
     try {
-      section = formatChangeRecords(landscape.changeRecords ?? [], process.cwd());
+      section = formatChangeRecords(
+        landscape.changeRecords ?? [],
+        process.cwd()
+      );
     } catch {
       section = "";
     }
@@ -1618,8 +1763,16 @@ ${section}` : body;
       if (gated) return gated;
       try {
         const changeReport = await changeReportForBody();
-        const body = { sessionId, ...args, ...changeReport ? { changeReport } : {} };
-        const result = await hubClient.post("/work", body);
+        const body = {
+          sessionId,
+          ...args,
+          ...changeReport ? { changeReport } : {}
+        };
+        const parsed = WorkResponse.safeParse(
+          await hubClient.post("/work", body)
+        );
+        if (!parsed.success) return malformedResponseResult("/work");
+        const result = parsed.data;
         result.landscape.announcements = mergeAnnouncements(
           result.landscape.announcements,
           drainLocalInbox()
@@ -1655,17 +1808,19 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
       if (gated) return gated;
       try {
         const body = { sessionId, ...args };
-        const result = await hubClient.post("/done", body);
+        const parsed = DoneResponse.safeParse(
+          await hubClient.post("/done", body)
+        );
+        if (!parsed.success) return malformedResponseResult("/done");
+        const result = parsed.data;
         const base = "Work item released. Call work again before your next edit in a new area.";
         const msgs = formatAnnouncements(
           mergeAnnouncements(result.announcements, drainLocalInbox())
         );
         return {
-          content: [
-            { type: "text", text: msgs ? `${base}
+          content: [{ type: "text", text: msgs ? `${base}
 
-${msgs}` : base }
-          ]
+${msgs}` : base }]
         };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -1687,17 +1842,19 @@ ${msgs}` : base }
       if (gated) return gated;
       try {
         const body = { sessionId, ...args };
-        const result = await hubClient.post("/announce", body);
+        const parsed = AnnounceResponse.safeParse(
+          await hubClient.post("/announce", body)
+        );
+        if (!parsed.success) return malformedResponseResult("/announce");
+        const result = parsed.data;
         const base = `Announcement sent (id: ${result.announcementId}).`;
         const msgs = formatAnnouncements(
           mergeAnnouncements(result.announcements, drainLocalInbox())
         );
         return {
-          content: [
-            { type: "text", text: msgs ? `${base}
+          content: [{ type: "text", text: msgs ? `${base}
 
-${msgs}` : base }
-          ]
+${msgs}` : base }]
         };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -1720,13 +1877,20 @@ ${msgs}` : base }
       try {
         const changeReport = await changeReportForBody();
         const body = { sessionId, ...changeReport ? { changeReport } : {} };
-        const result = await hubClient.post("/sync", body);
+        const parsed = SyncResponse.safeParse(
+          await hubClient.post("/sync", body)
+        );
+        if (!parsed.success) return malformedResponseResult("/sync");
+        const result = parsed.data;
         result.landscape.announcements = mergeAnnouncements(
           result.landscape.announcements,
           drainLocalInbox()
         );
         const text = withIdentity(
-          withChangeRecords(result.landscape, formatLandscape(result.landscape))
+          withChangeRecords(
+            result.landscape,
+            formatLandscape(result.landscape)
+          )
         );
         return { content: [{ type: "text", text }] };
       } catch (err) {
@@ -1752,7 +1916,9 @@ ${msgs}` : base }
     tripwire?.stop();
     const result = await activate(slug);
     if (result.ok) {
-      return advisory(`Linked this repo to \`${slug}\` \u2014 coordinating in \`${slug}\` now.`);
+      return advisory(
+        `Linked this repo to \`${slug}\` \u2014 coordinating in \`${slug}\` now.`
+      );
     }
     return advisory(
       `Linked this repo to \`${slug}\`, but coordination couldn't start just now (${joinFailureCause(joinFailure)}). It'll connect on your next tool call or session.`
@@ -1764,7 +1930,9 @@ ${msgs}` : base }
       title: "Link this repo to a Shepherd workspace",
       description: "Opt this repository into Shepherd coordination by writing a committed `.shepherd` marker naming the workspace. Call with no argument: if you belong to exactly one workspace it is linked and coordination starts immediately; if you belong to several, the choices are listed for you to confirm one with the agent's user, then call `link` again with that `workspace`. You can only link to a workspace you are a member of. Takes effect immediately \u2014 no restart. Use `unlink` to opt out, or `decline` to stay uncoordinated without linking.",
       inputSchema: z3.object({
-        workspace: z3.string().min(1).optional().describe("The workspace slug to link this repo to. Omit to auto-pick or list choices.")
+        workspace: z3.string().min(1).optional().describe(
+          "The workspace slug to link this repo to. Omit to auto-pick or list choices."
+        )
       }).shape
     },
     async (args) => {
@@ -1825,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."
@@ -1861,7 +2030,14 @@ ${msgs}` : base }
       );
     }
   }
-  gatedTools.push(workTool, doneTool, announceTool, syncTool, unlinkTool, declineTool);
+  gatedTools.push(
+    workTool,
+    doneTool,
+    announceTool,
+    syncTool,
+    unlinkTool,
+    declineTool
+  );
   surfaceVisible = true;
   syncToolSurface();
   async function runFirstRunAsk() {
@@ -1889,7 +2065,9 @@ ${msgs}` : base }
         appendAnnouncements(inboxFile, [postLinkGuidance(workspace ?? "")]);
       }
       if (outcome !== "unanswered") {
-        console.error(`[shepherd] first-run ask answered by the user: ${outcome}`);
+        console.error(
+          `[shepherd] first-run ask answered by the user: ${outcome}`
+        );
       }
     } catch (err) {
       console.error(
@@ -1910,20 +2088,21 @@ ${msgs}` : base }
   return { ready: joinInFlight, leave };
 }
 function postLinkGuidance(workspace) {
+  const safeWorkspace = workspace.replace(/\s+/g, " ").slice(0, 64);
   return {
     id: -Date.now(),
     fromAgentName: "shepherd",
     fromHuman: "shepherd",
     targetAgentName: null,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    body: `The user just linked this repository to the \`${workspace}\` workspace \u2014 coordination is NOW ACTIVE. Standing procedure from here on: call \`work\` (one-line intent + pathGlobs) BEFORE changing files in an area; \`done\` when that unit of work is complete; \`announce\` anything teammates need to know; \`sync\` when you resume or switch tasks. Start by calling \`work\` for the files you're editing right now.`
+    body: `The user just linked this repository to the \`${safeWorkspace}\` workspace \u2014 coordination is NOW ACTIVE. Standing procedure from here on: call \`work\` (one-line intent + pathGlobs) BEFORE changing files in an area; \`done\` when that unit of work is complete; \`announce\` anything teammates need to know; \`sync\` when you resume or switch tasks. Start by calling \`work\` for the files you're editing right now.`
   };
 }
 
 // src/identityCache.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
-import { homedir as homedir3, tmpdir as tmpdir3 } from "os";
-import { dirname as dirname4, join as join4 } from "path";
+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() {
   let base = "";
   try {
@@ -1954,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 {
   }
 }
@@ -1984,7 +2163,17 @@ async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
   const repoRoot = deps.findRepoRoot(cwd);
   const declined = repoRoot !== null ? deps.isDeclined(repoRoot) : false;
   const linkState = linked ? "linked" : declined ? "declined" : "unanswered";
-  return { workspace, repo, branch, human, program, model, linked, declined, linkState };
+  return {
+    workspace,
+    repo,
+    branch,
+    human,
+    program,
+    model,
+    linked,
+    declined,
+    linkState
+  };
 }
 function resolveHuman(config, cwd, deps) {
   if (config.HUMAN) return config.HUMAN;
@@ -2003,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) {
@@ -2023,9 +2219,22 @@ function createHeartbeat({
     }
     const body = { sessionId };
     if (changeReport) body.changeReport = changeReport;
+    if (liveness) {
+      try {
+        liveness.refresh();
+      } catch {
+      }
+    }
     if (announcementSink) body.deliverAnnouncements = true;
-    const response = await hubClient.post("/heartbeat", body);
-    const delivered = response?.announcements;
+    const parsed = HeartbeatResponse.safeParse(
+      await hubClient.post("/heartbeat", body)
+    );
+    if (!parsed.success) {
+      console.error(
+        "[shepherd] heartbeat returned a response that failed contract validation \u2014 ignoring this beat's announcements."
+      );
+    }
+    const delivered = parsed.success ? parsed.data.announcements : [];
     if (announcementSink && Array.isArray(delivered) && delivered.length > 0) {
       try {
         announcementSink(delivered);
@@ -2043,6 +2252,12 @@ function createHeartbeat({
   }
   function start(sessionId) {
     stop();
+    if (liveness) {
+      try {
+        liveness.refresh();
+      } catch {
+      }
+    }
     timer = setInterval(() => {
       void beat(sessionId).catch((err) => {
         console.error(
@@ -2056,10 +2271,13 @@ function createHeartbeat({
 }
 
 // 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 ?? "team"}\` workspace, so coordination is active.
+      return `${INTRO} This repository is linked to the \`${workspace ? sanitizeWorkspace(workspace) : "team"}\` workspace, so coordination is active.
 
 ${PROCEDURE}`;
     case "declined":
@@ -2090,14 +2308,108 @@ 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, copyFileSync, existsSync as existsSync4, renameSync as renameSync2 } from "fs";
-import { homedir as homedir4 } from "os";
-import { dirname as dirname5, join as join5 } from "path";
-import { fileURLToPath } from "url";
+import {
+  readFileSync as readFileSync5,
+  writeFileSync as writeFileSync5,
+  mkdirSync as mkdirSync4,
+  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 { fileURLToPath } from "node:url";
 
 // src/version.ts
-import { createRequire } from "module";
+import { createRequire } from "node:module";
 var PACKAGE_VERSION = (() => {
   try {
     const req = createRequire(import.meta.url);
@@ -2130,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;
@@ -2139,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)}]`;
@@ -2179,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"
@@ -2221,14 +2533,18 @@ function installClaude(homeDir, scriptPath, log) {
   }
   const hooks = settings["hooks"] ??= {};
   if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) {
-    log(`[shepherd] ${settingsFile} has an unexpected "hooks" shape \u2014 not touching it.`);
+    log(
+      `[shepherd] ${settingsFile} has an unexpected "hooks" shape \u2014 not touching it.`
+    );
     return "skipped";
   }
   const hooksObj = hooks;
   for (const event of ["SessionStart", "PreToolUse"]) {
     const existing = hooksObj[event] ??= [];
     if (!Array.isArray(existing)) {
-      log(`[shepherd] ${settingsFile} has an unexpected hooks.${event} shape \u2014 not touching it.`);
+      log(
+        `[shepherd] ${settingsFile} has an unexpected hooks.${event} shape \u2014 not touching it.`
+      );
       return "skipped";
     }
   }
@@ -2241,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) {
@@ -2250,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";
@@ -2258,13 +2574,17 @@ ${hookBlock}`, "utf8");
   const toml = readFileSync5(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}`);
+    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}`);
+      log(
+        `[shepherd] ${configFile} sets hooks = ${hooksKey[1].trim()} \u2014 respecting it. ${manualHint}`
+      );
       return "skipped";
     }
     let updated = toml;
@@ -2272,13 +2592,17 @@ ${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(configFile, `${toml}
+  writeFileSync5(
+    configFile,
+    `${toml}
 [features]
 hooks = true
-${hookBlock}`, "utf8");
+${hookBlock}`,
+    "utf8"
+  );
   return "installed";
 }
 function installCursor(homeDir, scriptPath, log) {
@@ -2306,7 +2630,9 @@ function installCursor(homeDir, scriptPath, log) {
   config["version"] ??= 1;
   const hooks = config["hooks"] ??= {};
   if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) {
-    log(`[shepherd] ${hooksFile} has an unexpected "hooks" shape \u2014 not touching it.`);
+    log(
+      `[shepherd] ${hooksFile} has an unexpected "hooks" shape \u2014 not touching it.`
+    );
     return "skipped";
   }
   const hooksObj = hooks;
@@ -2319,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) {
@@ -2327,7 +2653,9 @@ function installPi(homeDir, extensionSource, log) {
   const dest = join5(homeDir, ".pi", "agent", "extensions", "shepherd-inbox.js");
   if (existsSync4(dest)) return "already-present";
   if (!existsSync4(source)) {
-    log(`[shepherd] bundled Pi extension not found at ${source} \u2014 skipping auto-install.`);
+    log(
+      `[shepherd] bundled Pi extension not found at ${source} \u2014 skipping auto-install.`
+    );
     return "skipped";
   }
   mkdirSync4(dirname5(dest), { recursive: true });
@@ -2338,10 +2666,27 @@ function installPi(homeDir, extensionSource, log) {
 // src/index.ts
 async function main() {
   const config = loadConfig();
-  const hubClient = createHubClient({ hubUrl: config.HUB_URL, token: config.authToken });
+  const hubClient = createHubClient({
+    hubUrl: config.HUB_URL,
+    token: config.authToken
+  });
   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,
@@ -2354,16 +2699,23 @@ 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 },
     { instructions: buildInstructions(context.linkState, context.workspace) }
   );
-  const tools = registerTools(server, { hubClient, config, context, heartbeat, inboxFile });
+  const tools = registerTools(server, {
+    hubClient,
+    config,
+    context,
+    heartbeat,
+    inboxFile
+  });
   const transport = new StdioServerTransport();
   server.server.oninitialized = () => {
     void autoInstallHooks({