@korso/shepherd 0.4.4 → 0.5.0

package/dist/index.js

@@ -7,11 +7,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/config.ts
 import { z } from "zod";
 var ConfigSchema = z.object({
-  // Hard-required: connection credentials.
+  // Hard-required: Hub endpoint.
   HUB_URL: z.string().min(1, "HUB_URL is required"),
-  TEAM_TOKEN: z.string().min(1, "TEAM_TOKEN is required"),
+  // 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.
+  // SHEPHERD_TOKEN wins when both are present (see the derived `authToken`).
+  SHEPHERD_TOKEN: z.string().min(1).optional(),
+  TEAM_TOKEN: z.string().min(1).optional(),
   // Optional overrides — resolveContext will apply defaults for any that are absent.
   // WORKSPACE default is applied in resolveContext (auto-detected from cwd basename).
+  // NOTE: WORKSPACE is IGNORED by the hosted Hub — the SHEPHERD_TOKEN carries the
+  // workspace identity. It remains meaningful only for self-host (TEAM_TOKEN) setups.
   WORKSPACE: z.string().min(1).optional(),
   REPO: z.string().min(1).optional(),
   BRANCH: z.string().min(1).optional(),
@@ -28,10 +35,14 @@ var ConfigSchema = z.object({
   // work/sync/done/announce tool results as before. Both the MCP server and the
   // hook must agree on this path.
   SHEPHERD_INBOX_DIR: z.string().min(1).optional()
+}).refine((c) => Boolean(c.SHEPHERD_TOKEN || c.TEAM_TOKEN), {
+  message: "Either SHEPHERD_TOKEN or TEAM_TOKEN is required",
+  path: ["SHEPHERD_TOKEN"]
 });
 function parseConfig(env) {
-  return ConfigSchema.parse({
+  const parsed = ConfigSchema.parse({
     HUB_URL: env["HUB_URL"],
+    SHEPHERD_TOKEN: env["SHEPHERD_TOKEN"],
     TEAM_TOKEN: env["TEAM_TOKEN"],
     WORKSPACE: env["WORKSPACE"],
     REPO: env["REPO"],
@@ -43,6 +54,8 @@ function parseConfig(env) {
     HEARTBEAT_INTERVAL_SECONDS: env["HEARTBEAT_INTERVAL_SECONDS"],
     SHEPHERD_INBOX_DIR: env["SHEPHERD_INBOX_DIR"]
   });
+  const authToken = parsed.SHEPHERD_TOKEN ?? parsed.TEAM_TOKEN;
+  return { ...parsed, authToken };
 }
 function loadConfig(env = process.env) {
   try {
@@ -82,51 +95,63 @@ var HubRequestError = class extends Error {
 };
 function createHubClient({
   hubUrl,
-  teamToken,
+  token,
   timeoutMs = DEFAULT_TIMEOUT_MS
 }) {
   const baseUrl = hubUrl.replace(/\/$/, "");
-  return {
-    async post(path2, body) {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeoutMs);
-      let response;
+  async function request(method, path3, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const headers = {
+      "Authorization": `Bearer ${token}`
+    };
+    if (method === "POST") {
+      headers["Content-Type"] = "application/json";
+    }
+    let response;
+    try {
+      response = await fetch(`${baseUrl}${path3}`, {
+        method,
+        headers,
+        ...method === "POST" ? { body: JSON.stringify(body) } : {},
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      const message = err instanceof DOMException && err.name === "AbortError" ? `Hub request timed out after ${timeoutMs}ms (${path3})` : `Hub unreachable at ${baseUrl}${path3}: ${String(err)}`;
+      throw new HubUnreachable(message, err);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      let detail = "";
       try {
-        response = await fetch(`${baseUrl}${path2}`, {
-          method: "POST",
-          headers: {
-            "Authorization": `Bearer ${teamToken}`,
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify(body),
-          signal: controller.signal
-        });
-      } catch (err) {
-        clearTimeout(timer);
-        const message = err instanceof DOMException && err.name === "AbortError" ? `Hub request timed out after ${timeoutMs}ms (${path2})` : `Hub unreachable at ${baseUrl}${path2}: ${String(err)}`;
-        throw new HubUnreachable(message, err);
-      } finally {
-        clearTimeout(timer);
-      }
-      if (!response.ok) {
-        let detail = "";
-        try {
-          const data = await response.json();
-          if (data && typeof data === "object" && "error" in data && typeof data.error === "string") {
-            detail = `: ${data.error}`;
-          }
-        } catch {
+        const data = await response.json();
+        if (data && typeof data === "object" && "error" in data && typeof data.error === "string") {
+          detail = `: ${data.error}`;
         }
-        throw new HubRequestError(
-          response.status,
-          `Hub returned HTTP ${response.status} for ${path2}${detail}`
-        );
+      } catch {
       }
-      return response.json();
+      throw new HubRequestError(
+        response.status,
+        `Hub returned HTTP ${response.status} for ${path3}${detail}`
+      );
+    }
+    return response.json();
+  }
+  return {
+    post(path3, body) {
+      return request("POST", path3, body);
+    },
+    get(path3) {
+      return request("GET", path3);
     }
   };
 }
 
+// src/tools.ts
+import { z as z3 } from "zod";
+
 // ../shared/dist/names.js
 var adjectives = [
   "Able",
@@ -469,13 +494,22 @@ var HeartbeatRequest = z2.object({
   // only when it next calls work/sync). Processed presence-style: it refreshes
   // change records but, like the rest of heartbeat, does NOT renew claim TTLs.
   changeReport: ChangeReport.optional(),
-  // Opt-in: when set, the heartbeat ALSO delivers (and marks delivered) any
-  // pending announcements for the caller, returned in the response. The MCP
-  // client only sets this when it has somewhere model-visible to surface them
-  // (a local inbox file drained by a hook) — otherwise the long-standing
-  // invariant holds: heartbeat must NOT consume announcements the model can't
-  // see. Absent for older clients, so default delivery is unchanged.
-  deliverAnnouncements: z2.boolean().optional()
+  // Opt-in: when set, the heartbeat returns any pending announcements for the
+  // caller in the response. Delivery is now TWO-PHASE and crash-safe: this fetch
+  // phase does NOT mark them delivered — the client persists them to its
+  // model-visible sink (the local inbox file drained by a hook) FIRST, then acks
+  // via `ackAnnouncementIds` so the hub records the delivery only after the local
+  // write is confirmed. The MCP client only sets this when it actually has such a
+  // sink. Absent for older clients, so default behaviour (no delivery) is
+  // unchanged.
+  deliverAnnouncements: z2.boolean().optional(),
+  // Phase-two ack of a previous `deliverAnnouncements` fetch: the ids the client
+  // has now durably written to its model-visible sink. The hub marks exactly
+  // these delivered to the caller's session. Decoupling the mark from the fetch
+  // guarantees a message is never recorded delivered before the client holds it
+  // (a lost response or a failed local append simply leaves it pending for the
+  // next beat). Absent on a plain presence/fetch beat.
+  ackAnnouncementIds: z2.array(DbId).optional()
 });
 var HeartbeatResponse = z2.object({
   ok: z2.literal(true),
@@ -490,10 +524,119 @@ var LeaveRequest = z2.object({
 var LeaveResponse = z2.object({
   ok: z2.literal(true)
 });
+var Role = z2.enum(["admin", "member"]);
+var WorkspaceSummary = z2.object({
+  id: z2.string(),
+  slug: z2.string(),
+  name: z2.string(),
+  role: Role
+});
+var CreateWorkspaceRequest = z2.object({
+  name: z2.string().min(1)
+});
+var ListWorkspacesResponse = z2.object({
+  workspaces: z2.array(WorkspaceSummary)
+});
+var MintTokenRequest = z2.object({
+  name: z2.string().min(1).optional()
+});
+var MintTokenResponse = z2.object({
+  // The raw shp_ token, shown once at creation and never returned again.
+  token: z2.string(),
+  id: z2.string()
+});
+var TokenSummary = z2.object({
+  id: z2.string(),
+  name: z2.string().nullable(),
+  // ISO timestamp string (see IsoTimestamp note above) or null when unused / not revoked.
+  lastUsedAt: IsoTimestamp.nullable(),
+  createdAt: IsoTimestamp,
+  revokedAt: IsoTimestamp.nullable()
+});
+var ListTokensResponse = z2.object({
+  tokens: z2.array(TokenSummary)
+});
+var CreateInviteRequest = z2.object({
+  expiresInDays: z2.number().int().positive().optional(),
+  maxUses: z2.number().int().positive().optional()
+});
+var InviteResponse = z2.object({
+  code: z2.string(),
+  // ISO timestamp string, or null when the invite never expires.
+  expiresAt: IsoTimestamp.nullable(),
+  maxUses: z2.number().int().positive(),
+  useCount: z2.number().int().nonnegative()
+});
+var RedeemInviteResponse = z2.object({
+  // The workspace the caller just joined.
+  workspace: WorkspaceSummary
+});
+var MemberSummary = z2.object({
+  accountId: z2.string(),
+  displayName: z2.string().nullable(),
+  githubLogin: z2.string().nullable(),
+  avatarUrl: z2.string().nullable(),
+  role: Role
+});
+var ListMembersResponse = z2.object({
+  members: z2.array(MemberSummary)
+});
+
+// src/marker.ts
+import * as fs from "fs";
+import * as path from "path";
+var MARKER_FILENAME = ".shepherd";
+function findRepoRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (; ; ) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function markerPath(cwd) {
+  const root = findRepoRoot(cwd);
+  return root === null ? null : path.join(root, MARKER_FILENAME);
+}
+function readMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string" && parsed.workspace.length > 0) {
+      return { workspace: parsed.workspace };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+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");
+  }
+  fs.writeFileSync(file, JSON.stringify({ workspace: slug }) + "\n", "utf8");
+}
+function removeMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return;
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+  }
+}
 
 // src/gitContext.ts
 import { execFileSync } from "child_process";
-import * as path from "path";
+import * as path2 from "path";
 var GIT_TIMEOUT_MS = 2e3;
 var MAX_COMMITS = 100;
 var MAX_PATHS_PER_COMMIT = 500;
@@ -541,7 +684,7 @@ function detectRepo(cwd = process.cwd()) {
   }
   const top = runGit(cwd, ["rev-parse", "--show-toplevel"]);
   if (top) {
-    const base = path.basename(top);
+    const base = path2.basename(top);
     if (base) return base;
   }
   return null;
@@ -740,13 +883,13 @@ import { createHash } from "crypto";
 import {
   appendFileSync,
   mkdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   renameSync,
-  rmSync,
-  existsSync
+  rmSync as rmSync2,
+  existsSync as existsSync2
 } from "fs";
 import { homedir, tmpdir } from "os";
-import { dirname, join, resolve } from "path";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 function defaultInboxDir() {
   let base = "";
   try {
@@ -755,18 +898,18 @@ function defaultInboxDir() {
     base = "";
   }
   if (!base) base = tmpdir();
-  return join(base, ".shepherd", "inbox");
+  return join2(base, ".shepherd", "inbox");
 }
 function inboxFilePath(dir, cwd) {
-  let normalized = resolve(cwd);
+  let normalized = resolve2(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
   const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(dir, `${hash}.jsonl`);
+  return join2(dir, `${hash}.jsonl`);
 }
 function appendAnnouncements(filePath, announcements) {
   if (!announcements || announcements.length === 0) return;
   try {
-    mkdirSync(dirname(filePath), { recursive: true });
+    mkdirSync(dirname2(filePath), { recursive: true });
     const payload = announcements.map((a) => JSON.stringify(a)).join("\n") + "\n";
     appendFileSync(filePath, payload, "utf8");
   } catch {
@@ -776,17 +919,17 @@ function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync(tmp)) {
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+    if (existsSync2(tmp)) {
+      raw += readFileSync2(tmp, "utf8");
+      rmSync2(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync(filePath)) {
+    if (existsSync2(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+      raw += readFileSync2(tmp, "utf8");
+      rmSync2(tmp, { force: true });
     }
   } catch {
   }
@@ -818,6 +961,29 @@ function mergeAnnouncements(...lists) {
 }
 
 // src/tools.ts
+function classifyJoinFailure(err) {
+  if (err instanceof HubUnreachable) return "unreachable";
+  if (err instanceof HubRequestError) {
+    if (err.status === 401) return "auth";
+    if (err.status === 400) return "validation";
+    return "unknown";
+  }
+  return "unknown";
+}
+function joinFailureCause(reason) {
+  switch (reason) {
+    case "unreachable":
+      return "hub unreachable at startup";
+    case "auth":
+      return "hub rejected the team token (check SHEPHERD/TEAM token)";
+    case "validation":
+      return "hub rejected the join (workspace/branch not allowed, or returned an invalid response)";
+    case "unknown":
+      return "join failed with an unexpected error";
+    default:
+      return "coordination session not established yet";
+  }
+}
 function formatLandscape(landscape) {
   const lines = [];
   if (landscape.conflicts.length > 0) {
@@ -924,8 +1090,11 @@ function formatChangeRecords(records, cwd = process.cwd()) {
   if (lines.length === 0) return "";
   return "Unlanded changes touching your area (awareness only \u2014 these are not blockers):\n" + lines.join("\n");
 }
+function hubErrorDetail(err) {
+  return err instanceof HubUnreachable || err instanceof HubRequestError ? err.message : String(err);
+}
 function degradedResult(err) {
-  const detail = err instanceof HubUnreachable || err instanceof HubRequestError ? err.message : String(err);
+  const detail = hubErrorDetail(err);
   return {
     content: [
       {
@@ -937,8 +1106,14 @@ function degradedResult(err) {
 }
 function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
+  const markerCwd = deps.cwd ?? process.cwd();
   let sessionId = null;
   let agentName = null;
+  const isHosted = Boolean(config.SHEPHERD_TOKEN);
+  const selfHostMismatch = !isHosted && context.linked && config.WORKSPACE !== void 0 && config.WORKSPACE !== context.workspace;
+  let hostedWorkspaceRejected = false;
+  const dormant = !context.linked || selfHostMismatch;
+  let joinFailure = null;
   const joinBody = {
     workspace: context.workspace,
     repo: context.repo,
@@ -949,11 +1124,39 @@ function registerTools(server, deps) {
   if (context.model !== void 0) {
     joinBody.model = context.model;
   }
-  const joinInFlight = hubClient.post("/join", joinBody).then((r) => {
-    sessionId = r.sessionId;
-    agentName = r.agentName;
-    heartbeat.start(r.sessionId);
-  }).catch(() => {
+  if (!context.linked) {
+    console.error(
+      "[shepherd] This repo isn't linked to a Shepherd workspace \u2014 staying uncoordinated. Run `link` to choose one."
+    );
+  } else if (selfHostMismatch) {
+    console.error(
+      `[shepherd] This repo is linked to workspace "${context.workspace}" but your configured token is for a different workspace \u2014 coordination disabled.`
+    );
+  }
+  const joinInFlight = dormant ? Promise.resolve() : hubClient.post("/join", joinBody).then((raw) => {
+    const parsed = JoinResponse.safeParse(raw);
+    if (!parsed.success || !parsed.data.sessionId) {
+      joinFailure = "validation";
+      console.error(
+        "[shepherd] join failed (validation): hub returned a malformed join response (no usable sessionId)"
+      );
+      return;
+    }
+    sessionId = parsed.data.sessionId;
+    agentName = parsed.data.agentName;
+    heartbeat.start(parsed.data.sessionId);
+  }).catch((err) => {
+    joinFailure = classifyJoinFailure(err);
+    if (err instanceof HubRequestError && (err.status === 403 || err.status === 404)) {
+      hostedWorkspaceRejected = true;
+      console.error(
+        `[shepherd] This repo is linked to workspace "${context.workspace}" but your configured token is for a different workspace \u2014 coordination disabled.`
+      );
+    } else {
+      console.error(
+        `[shepherd] join failed (${joinFailure}): ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
   });
   async function awaitJoin() {
     await joinInFlight;
@@ -963,11 +1166,38 @@ function registerTools(server, deps) {
       content: [
         {
           type: "text",
-          text: "Shepherd coordination session not ready (hub unreachable at startup) \u2014 proceeding uncoordinated."
+          text: `Shepherd coordination session not ready (${joinFailureCause(joinFailure)}) \u2014 proceeding uncoordinated.`
         }
       ]
     };
   }
+  function notLinked() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "This repo isn't linked to a Shepherd workspace \u2014 run `link` to choose one, or ignore to stay uncoordinated."
+        }
+      ]
+    };
+  }
+  function workspaceMismatch() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `This repo is linked to \`${context.workspace}\` but your configured token is for a different workspace \u2014 coordination disabled.`
+        }
+      ]
+    };
+  }
+  async function coordinationGate() {
+    await awaitJoin();
+    if (!context.linked) return notLinked();
+    if (selfHostMismatch || hostedWorkspaceRejected) return workspaceMismatch();
+    if (sessionId === null) return sessionNotReady();
+    return null;
+  }
   function withIdentity(body) {
     return agentName ? `You are ${agentName}.
 
@@ -1007,10 +1237,8 @@ ${section}` : body;
       inputSchema: WorkAgentInput.shape
     },
     async (args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const changeReport = await changeReportForBody();
         const body = { sessionId, ...args, ...changeReport ? { changeReport } : {} };
@@ -1046,10 +1274,8 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
       inputSchema: DoneAgentInput.shape
     },
     async (args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const body = { sessionId, ...args };
         const result = await hubClient.post("/done", body);
@@ -1080,10 +1306,8 @@ ${msgs}` : base }
       inputSchema: AnnounceAgentInput.shape
     },
     async (args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const body = { sessionId, ...args };
         const result = await hubClient.post("/announce", body);
@@ -1114,10 +1338,8 @@ ${msgs}` : base }
       inputSchema: SyncAgentInput.shape
     },
     async (_args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const changeReport = await changeReportForBody();
         const body = { sessionId, ...changeReport ? { changeReport } : {} };
@@ -1138,6 +1360,88 @@ ${msgs}` : base }
       }
     }
   );
+  function advisory(text) {
+    return { content: [{ type: "text", text }] };
+  }
+  server.registerTool(
+    "link",
+    {
+      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 to see the workspaces you can link to, then call again with one. You can only link to a workspace you are a member of. Takes effect on the next session (restart to coordinate now). Use `unlink` to opt out.",
+      inputSchema: z3.object({
+        workspace: z3.string().min(1).optional().describe("The workspace slug to link this repo to. Omit to list your choices.")
+      }).shape
+    },
+    async (args) => {
+      const requested = args.workspace;
+      if (!isHosted) {
+        const allowed = config.WORKSPACE;
+        if (!allowed) {
+          return advisory(
+            "Self-host mode has no configured workspace (WORKSPACE is unset) \u2014 cannot link."
+          );
+        }
+        if (requested === void 0) {
+          return advisory(
+            `This is a self-host deployment with a single workspace: \`${allowed}\`.
+Run \`link\` again with workspace "${allowed}" to opt this repo in.`
+          );
+        }
+        if (requested !== allowed) {
+          return advisory(
+            `This self-host deployment only serves the workspace \`${allowed}\`; you asked for \`${requested}\`. Choose: ${allowed}`
+          );
+        }
+        writeMarker(markerCwd, allowed);
+        return advisory(
+          `Linked this repo to \`${allowed}\` \u2014 restart the session for it to take effect (it applies on the next launch).`
+        );
+      }
+      let slugs;
+      try {
+        const res = await hubClient.get("/workspaces");
+        slugs = (res.workspaces ?? []).map((w) => w.slug).filter((s) => typeof s === "string" && s.length > 0);
+      } catch (err) {
+        const detail = hubErrorDetail(err);
+        return advisory(
+          `Couldn't reach the coordination hub to list your workspaces \u2014 link not changed. ${detail}`
+        );
+      }
+      if (slugs.length === 0) {
+        return advisory(
+          "Your account isn't a member of any workspaces yet \u2014 nothing to link to. Create or join a workspace first, then run `link` again."
+        );
+      }
+      if (requested === void 0) {
+        return advisory(
+          "You can link this repo to one of these workspaces:\n" + slugs.map((s) => `  - ${s}`).join("\n") + "\n\nRun `link` again with one of them as the `workspace` argument."
+        );
+      }
+      if (!slugs.includes(requested)) {
+        return advisory(
+          `You're not a member of \`${requested}\`; choose one of: ${slugs.join(", ")}`
+        );
+      }
+      writeMarker(markerCwd, requested);
+      return advisory(
+        `Linked this repo to \`${requested}\` \u2014 restart the session for it to take effect (it applies on the next launch).`
+      );
+    }
+  );
+  server.registerTool(
+    "unlink",
+    {
+      title: "Unlink this repo from its Shepherd workspace",
+      description: "Opt this repository OUT of Shepherd coordination by removing its `.shepherd` marker. The repo stays uncoordinated (no claims, no presence) until you `link` it again.",
+      inputSchema: z3.object({}).shape
+    },
+    async () => {
+      removeMarker(markerCwd);
+      return advisory(
+        "Unlinked \u2014 this repo will stay uncoordinated until re-linked."
+      );
+    }
+  );
   async function leave() {
     try {
       await joinInFlight;
@@ -1152,11 +1456,53 @@ ${msgs}` : base }
   return { ready: joinInFlight, leave };
 }
 
+// src/identityCache.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, join as join3 } from "path";
+function defaultIdentityCachePath() {
+  let base = "";
+  try {
+    base = homedir2();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir2();
+  return join3(base, ".shepherd", "identity.json");
+}
+function readCachedHuman(filePath = defaultIdentityCachePath()) {
+  let raw;
+  try {
+    raw = readFileSync3(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const human = typeof parsed?.human === "string" ? parsed.human.trim() : "";
+    return human.length > 0 ? human : null;
+  } catch {
+    return null;
+  }
+}
+function writeCachedHuman(human, filePath = defaultIdentityCachePath()) {
+  if (typeof human !== "string" || human.trim().length === 0) return;
+  try {
+    mkdirSync2(dirname3(filePath), { recursive: true });
+    const payload = JSON.stringify({ human });
+    writeFileSync2(filePath, payload + "\n", "utf8");
+  } catch {
+  }
+}
+
 // src/resolveContext.ts
 var defaultDeps = {
   detectRepo,
   detectBranch,
-  detectHuman
+  detectHuman,
+  readMarker,
+  readCachedHuman,
+  writeCachedHuman
 };
 var DEFAULT_WORKSPACE = "default";
 async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
@@ -1164,11 +1510,24 @@ async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
     config.REPO ?? deps.detectRepo(cwd) ?? "unknown-repo"
   );
   const branch = config.BRANCH ?? deps.detectBranch(cwd) ?? "HEAD";
-  const human = config.HUMAN ?? deps.detectHuman(cwd) ?? generateName();
+  const human = resolveHuman(config, cwd, deps);
   const program = config.PROGRAM ?? "claude-code";
   const model = config.MODEL ?? void 0;
-  const workspace = config.WORKSPACE ?? DEFAULT_WORKSPACE;
-  return { workspace, repo, branch, human, program, model };
+  const marker = deps.readMarker(cwd);
+  const linked = marker !== null;
+  const workspace = marker?.workspace ?? config.WORKSPACE ?? DEFAULT_WORKSPACE;
+  return { workspace, repo, branch, human, program, model, linked };
+}
+function resolveHuman(config, cwd, deps) {
+  if (config.HUMAN) return config.HUMAN;
+  const detected = deps.detectHuman(cwd);
+  if (detected) {
+    deps.writeCachedHuman(detected);
+    return detected;
+  }
+  const cached = deps.readCachedHuman();
+  if (cached) return cached;
+  return generateName();
 }
 
 // src/heartbeat.ts
@@ -1176,8 +1535,7 @@ function createHeartbeat({
   hubClient,
   intervalSeconds,
   buildReport,
-  deliverAnnouncements = false,
-  onAnnouncements
+  announcementSink
 }) {
   let timer = null;
   function stop() {
@@ -1197,17 +1555,22 @@ function createHeartbeat({
     }
     const body = { sessionId };
     if (changeReport) body.changeReport = changeReport;
-    if (deliverAnnouncements) body.deliverAnnouncements = true;
+    if (announcementSink) body.deliverAnnouncements = true;
     const response = await hubClient.post("/heartbeat", body);
     const delivered = response?.announcements;
-    if (onAnnouncements && Array.isArray(delivered) && delivered.length > 0) {
+    if (announcementSink && Array.isArray(delivered) && delivered.length > 0) {
       try {
-        onAnnouncements(delivered);
+        announcementSink(delivered);
       } catch (err) {
         console.error(
-          `[shepherd] inbox delivery failed: ${err instanceof Error ? err.message : String(err)}`
+          `[shepherd] inbox delivery failed (not acking, will retry): ${err instanceof Error ? err.message : String(err)}`
         );
+        return;
       }
+      await hubClient.post("/heartbeat", {
+        sessionId,
+        ackAnnouncementIds: delivered.map((a) => a.id)
+      });
     }
   }
   function start(sessionId) {
@@ -1246,7 +1609,7 @@ Commit work-in-progress as you go rather than sitting on a large dirty tree: com
 // src/index.ts
 async function main() {
   const config = loadConfig();
-  const hubClient = createHubClient({ hubUrl: config.HUB_URL, teamToken: config.TEAM_TOKEN });
+  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());
@@ -1262,8 +1625,10 @@ async function main() {
         return void 0;
       }
     },
-    deliverAnnouncements: true,
-    onAnnouncements: (announcements) => appendAnnouncements(inboxFile, announcements)
+    // A model-visible sink (this working dir's inbox file). 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)
   });
   const server = new McpServer(
     { name: "shepherd", version: "0.1.0" },