@korso/shepherd 0.4.3 → 0.4.5

package/README.md

@@ -55,12 +55,21 @@ override only to replace what's detected:
 | `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korsoai/shepherd` |
 | `BRANCH` | `git rev-parse --abbrev-ref HEAD`, else `HEAD` | `main` |
 | `BASE_BRANCH` | `origin/HEAD`, else `origin/main` / `origin/master` (used for the change-awareness heads-up) | `origin/main` |
-| `HUMAN` | git `user.name`, else local-part of `user.email`, else a generated name | `daichi` |
+| `HUMAN` | git `user.name`, else local-part of `user.email`, else this device's **cached** last-detected name, else a generated name | `daichi` |
 | `PROGRAM` | defaults to `claude-code` | `codex` |
 | `MODEL` | omitted — **never auto-detected**, so set it if you want it shown | `claude-sonnet-4-6` |
 | `HEARTBEAT_INTERVAL_SECONDS` | defaults to `60` | `30` |
 | `SHEPHERD_INBOX_DIR` | defaults to `~/.shepherd/inbox`. Override only to relocate the **announcement-push** inbox (see below); the background heartbeat writes incoming announcements here. If you set it, point your client hook/extension at the **same** dir | `~/.shepherd/inbox` |
 
+**Device-identity cache.** Whenever `HUMAN` is unset and git **does** detect a
+name, that name is cached for your OS user at `~/.shepherd/identity.json`. A
+later launch from a directory where git can't be read (e.g. a multi-repo
+workspace root) then reuses the cached name instead of inventing a fresh random
+one each time. The cache refreshes automatically the next time git reports a
+different name, and an explicit `HUMAN` override always wins and never touches
+the cache. It is best-effort: if the file can't be read or written, resolution
+just falls back to a generated name.
+
 ---
 
 ## Announcement push (on by default)
@@ -322,6 +331,6 @@ npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatical
 |---|---|---|
 | `Configuration error — missing or invalid env vars` | `HUB_URL` or `TEAM_TOKEN` is absent (only these two are required) | Add the missing var(s) to your client's `env` block |
 | Tools report "session not ready … proceeding uncoordinated" | Startup auto-join rejected — usually a stale `TEAM_TOKEN`, or a `WORKSPACE` override the hub doesn't allow | Re-check `TEAM_TOKEN`; leave `WORKSPACE` unset (→ `default`) or match the hub's `ALLOWED_WORKSPACE`; restart |
-| Agent shows up under a surprising name/repo/branch | Identity auto-detected from git | Override with `HUMAN`/`REPO`/`BRANCH`/`MODEL` env vars (§2) |
+| Agent shows up under a surprising name/repo/branch | Identity auto-detected from git, or reused from the device-identity cache when launched outside a git work tree | Override with `HUMAN`/`REPO`/`BRANCH`/`MODEL` env vars (§2); a correct git `user.name` on the next in-repo launch refreshes the cache, or delete `~/.shepherd/identity.json` to clear it |
 | `npm error 404 … @korso/shepherd` | Package not published yet, or name typo | `npm view @korso/shepherd version` to confirm it's live |
 | Process exits immediately with no error | Rare; check for node version incompatibility | Requires Node 18+ (ESM support) |

package/dist/index.js

@@ -109,9 +109,17 @@ function createHubClient({
         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 {
+        }
         throw new HubRequestError(
           response.status,
-          `Hub returned HTTP ${response.status} for ${path2}`
+          `Hub returned HTTP ${response.status} for ${path2}${detail}`
         );
       }
       return response.json();
@@ -461,13 +469,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),
@@ -810,6 +827,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) {
@@ -931,6 +971,7 @@ function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
   let sessionId = null;
   let agentName = null;
+  let joinFailure = null;
   const joinBody = {
     workspace: context.workspace,
     repo: context.repo,
@@ -941,11 +982,23 @@ 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(() => {
+  const joinInFlight = 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);
+    console.error(
+      `[shepherd] join failed (${joinFailure}): ${err instanceof Error ? err.message : String(err)}`
+    );
   });
   async function awaitJoin() {
     await joinInFlight;
@@ -955,7 +1008,7 @@ 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.`
         }
       ]
     };
@@ -1068,7 +1121,7 @@ ${msgs}` : base }
     "announce",
     {
       title: "Broadcast a message to teammates",
-      description: "Broadcast a heads-up to the other agents, direct a finding to a specific agent, or reply to the human operator. This is awareness only \u2014 not a task assignment. To direct it to an agent, pass that agent's name (exactly as shown in the landscape) as targetAgentName; to reply to the operator (the dashboard), pass toAdmin: true; omit both to broadcast to everyone in the workspace. targetAgentName and toAdmin are mutually exclusive. Delivery is best-effort: the recipient sees it on their next work/sync, once.",
+      description: "Broadcast a heads-up to the other agents, direct a finding to a specific agent, or reply to the human operator. This is awareness only \u2014 not a task assignment. To direct it to an agent, pass that agent's EXACT name as shown in the landscape \u2014 including its numeric suffix (e.g. 'alex-rivera-2', NOT the bare handle 'alex-rivera') \u2014 as targetAgentName. Several agents can share one handle (alex-rivera-1, alex-rivera-2, \u2026); the suffix is what picks one, so the bare handle is rejected. The hub rejects any targetAgentName that doesn't match a live agent in your repo \u2014 if you mean the whole team, omit it to broadcast. To reply to the operator (the dashboard), pass toAdmin: true. targetAgentName and toAdmin are mutually exclusive. Delivery is best-effort: the recipient sees it on their next work/sync, once.",
       inputSchema: AnnounceAgentInput.shape
     },
     async (args) => {
@@ -1144,11 +1197,52 @@ ${msgs}` : base }
   return { ready: joinInFlight, leave };
 }
 
+// src/identityCache.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+function defaultIdentityCachePath() {
+  let base = "";
+  try {
+    base = homedir2();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir2();
+  return join2(base, ".shepherd", "identity.json");
+}
+function readCachedHuman(filePath = defaultIdentityCachePath()) {
+  let raw;
+  try {
+    raw = readFileSync2(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(dirname2(filePath), { recursive: true });
+    const payload = JSON.stringify({ human });
+    writeFileSync(filePath, payload + "\n", "utf8");
+  } catch {
+  }
+}
+
 // src/resolveContext.ts
 var defaultDeps = {
   detectRepo,
   detectBranch,
-  detectHuman
+  detectHuman,
+  readCachedHuman,
+  writeCachedHuman
 };
 var DEFAULT_WORKSPACE = "default";
 async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
@@ -1156,20 +1250,30 @@ 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 };
 }
+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
 function createHeartbeat({
   hubClient,
   intervalSeconds,
   buildReport,
-  deliverAnnouncements = false,
-  onAnnouncements
+  announcementSink
 }) {
   let timer = null;
   function stop() {
@@ -1189,17 +1293,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) {
@@ -1254,8 +1363,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" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory cross-session coordination tools (work/done/announce/sync) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "type": "module",
   "main": "dist/index.js",