@korso/shepherd 0.3.0 → 0.4.0

package/README.md

@@ -8,9 +8,9 @@ Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, et
 
 ## CRITICAL: WORKSPACE must match the hub exactly
 
-> **Everyone must set `WORKSPACE` to the identical string, and that string must equal the hub's `ALLOWED_WORKSPACE` env var.**
+> **`WORKSPACE` defaults to `default`. If you override it, the value must equal the hub's `ALLOWED_WORKSPACE` env var exactly.**
 
-If `WORKSPACE` does not match, the server's automatic `join` call to the hub (fired at startup) returns HTTP 400. Coordination then degrades: every tool reports "session not ready … proceeding uncoordinated" instead of a landscape. This is the most common silent onboarding mistake — if your agent never sees teammates, check `WORKSPACE` first.
+The server fires an automatic `join` call to the hub at startup. If the workspace it sends does not match the hub's `ALLOWED_WORKSPACE`, that call returns HTTP 400 and coordination degrades: every tool reports "session not ready … proceeding uncoordinated" instead of a landscape. The safe default is to **leave `WORKSPACE` unset** so it resolves to `default` — only set it when a maintainer points you at a different workspace. If your agent never sees teammates, check `WORKSPACE` (and `TEAM_TOKEN`) first.
 
 ---
 
@@ -32,22 +32,33 @@ first fetch, and `@korso/shepherd@latest` picks up updates automatically.
 
 ---
 
-## 2. Required environment variables
+## 2. Environment variables
 
-Every instance of the MCP server needs these eight env vars set in its client config:
+**Only two are required:**
 
 | Variable | Description | Example |
 |---|---|---|
 | `HUB_URL` | Base URL of the deployed hub | `https://shepherd.example.com` |
 | `TEAM_TOKEN` | Shared bearer token accepted by the hub | `tok_abc123` |
-| `WORKSPACE` | **Must match hub's `ALLOWED_WORKSPACE` exactly** | `shepherd` |
-| `REPO` | Repository slug (used for scoping claims) | `shepherd` |
-| `BRANCH` | Git branch name | `main` |
-| `HUMAN` | Founder name — identifies you in the presence feed | `daichi` |
-| `PROGRAM` | Agent program name | `claude-code` |
-| `MODEL` | Model ID being used | `claude-sonnet-4-6` |
 
-All eight are required. Missing any one causes an immediate startup failure with a clear error on stderr listing which vars are absent.
+Missing either causes an immediate startup failure with a clear error on stderr
+listing which vars are absent. (No other var triggers this.)
+
+**Everything else is optional** — each identity field is resolved at startup as
+**env var → git detection → fallback**, so a plain `npx -y @korso/shepherd` with
+just the two required vars produces a valid, fully-identified session. Set an
+override only to replace what's detected:
+
+| Variable | If omitted | Example |
+|---|---|---|
+| `WORKSPACE` | defaults to `default` (**must match hub's `ALLOWED_WORKSPACE` if overridden**) | `shepherd` |
+| `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` |
+| `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` |
 
 ---
 
@@ -60,19 +71,19 @@ All eight are required. Missing any one causes an immediate startup failure with
 > everywhere) or a project-root `.mcp.json`. Confirm with `claude mcp list`,
 > which should show `shepherd … ✔ Connected`.
 
-Recommended — register once at user scope (works identically on Windows/macOS/Linux):
+Recommended — register once at user scope. Written as a **single line** so it
+pastes cleanly into PowerShell, cmd, bash, and zsh (on PowerShell the bash `\`
+line-continuation does not work). Minimal: just the two required vars (identity
+is auto-detected from git):
 
-```sh
-claude mcp add shepherd -s user \
-  -e HUB_URL=https://shepherd.example.com \
-  -e TEAM_TOKEN=tok_abc123 \
-  -e WORKSPACE=shepherd \
-  -e REPO=shepherd -e BRANCH=main -e HUMAN=daichi \
-  -e PROGRAM=claude-code -e MODEL=claude-sonnet-4-6 \
-  -- npx -y @korso/shepherd
+```powershell
+claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y @korso/shepherd
 ```
 
-Alternative — a `.mcp.json` at the **root of the repo you're working in**:
+Add any optional overrides from §2 with extra `-e` flags (e.g. `-e MODEL=claude-sonnet-4-6 -e HUMAN=daichi`).
+
+Alternative — a `.mcp.json` at the **root of the repo you're working in**
+(optional overrides shown commented-style; drop the ones you don't need):
 
 ```json
 {
@@ -83,11 +94,6 @@ Alternative — a `.mcp.json` at the **root of the repo you're working in**:
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123",
-        "WORKSPACE": "shepherd",
-        "REPO": "shepherd",
-        "BRANCH": "main",
-        "HUMAN": "daichi",
-        "PROGRAM": "claude-code",
         "MODEL": "claude-sonnet-4-6"
       }
     }
@@ -100,9 +106,29 @@ Alternative — a `.mcp.json` at the **root of the repo you're working in**:
 > on Linux (Postgres), so the Windows-native durability concerns from the spike
 > don't apply to clients.
 
-### Codex (`~/.codex/config.json` or `codex.json`)
+### Codex (`~/.codex/config.toml`)
+
+Codex uses the same MCP stdio protocol but configures it in **TOML**, not JSON —
+at `~/.codex/config.toml` (global) or `.codex/config.toml` in a trusted project.
+The table is `mcp_servers` with an **underscore** (`mcp-servers`/`mcpServers` are
+silently ignored). Either run `codex mcp add`:
 
-Codex uses the same MCP stdio protocol. Add a server entry under `mcpServers`:
+```sh
+codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y @korso/shepherd
+```
+
+…or add the table directly:
+
+```toml
+[mcp_servers.shepherd]
+command = "npx"
+args = ["-y", "@korso/shepherd"]
+env = { HUB_URL = "https://shepherd.example.com", TEAM_TOKEN = "tok_abc123", PROGRAM = "codex", MODEL = "o4-mini" }
+```
+
+### Pi (`~/.pi/agent/mcp.json` or `.pi/mcp.json`)
+
+Pi uses a JSON `mcpServers` block (project config overrides global):
 
 ```json
 {
@@ -113,12 +139,7 @@ Codex uses the same MCP stdio protocol. Add a server entry under `mcpServers`:
       "env": {
         "HUB_URL": "https://shepherd.example.com",
         "TEAM_TOKEN": "tok_abc123",
-        "WORKSPACE": "shepherd",
-        "REPO": "shepherd",
-        "BRANCH": "main",
-        "HUMAN": "alex",
-        "PROGRAM": "codex",
-        "MODEL": "o4-mini"
+        "PROGRAM": "pi"
       }
     }
   }
@@ -129,34 +150,31 @@ Codex uses the same MCP stdio protocol. Add a server entry under `mcpServers`:
 
 ## 4. Verify the server starts (quick smoke test)
 
-Run with all env vars set to confirm it connects and idles on stdin:
+Run with the two required vars set to confirm it connects and idles on stdin.
+PowerShell (set env vars, then run):
 
-```sh
-HUB_URL=https://shepherd.example.com \
-TEAM_TOKEN=tok_abc123 \
-WORKSPACE=shepherd \
-REPO=shepherd \
-BRANCH=main \
-HUMAN=daichi \
-PROGRAM=claude-code \
-MODEL=claude-sonnet-4-6 \
+```powershell
+$env:HUB_URL = "https://shepherd.example.com"
+$env:TEAM_TOKEN = "tok_abc123"
 npx -y @korso/shepherd
 ```
 
+bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y @korso/shepherd`
+
 No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
 
-**Missing env vars:** if you deliberately omit a var, you will see:
+**Missing env vars:** if you omit `HUB_URL` or `TEAM_TOKEN`, you will see:
 
 ```
 [shepherd] Configuration error — missing or invalid env vars:
   HUB_URL: HUB_URL is required
   TEAM_TOKEN: TEAM_TOKEN is required
-  ...
 ```
 
-and the process exits 1 immediately. This is by design.
+and the process exits 1 immediately. This is by design. The optional identity
+vars never cause this — they fall back to git detection / defaults.
 
-**Wrong WORKSPACE:** the server starts and connects, but the startup auto-join is rejected (400), so every tool call (`work`, `sync`, etc.) reports "session not ready … proceeding uncoordinated". Check that your `WORKSPACE` value exactly matches the hub's `ALLOWED_WORKSPACE`, then restart.
+**Wrong WORKSPACE:** if you override `WORKSPACE` to a value the hub doesn't allow, the server starts and connects but the startup auto-join is rejected (400), so every tool call (`work`, `sync`, etc.) reports "session not ready … proceeding uncoordinated". Either leave `WORKSPACE` unset (resolves to `default`) or set it to exactly match the hub's `ALLOWED_WORKSPACE`, then restart.
 
 ---
 
@@ -197,7 +215,8 @@ npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatical
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
-| `Configuration error — missing or invalid env vars` | One or more of the 8 env vars is absent | Add the missing vars to your client's `env` block |
-| Tools report "session not ready … proceeding uncoordinated" | Startup auto-join rejected — usually `WORKSPACE` mismatch (or stale `TEAM_TOKEN`) | Set `WORKSPACE` to exactly match the hub's `ALLOWED_WORKSPACE`; re-check `TEAM_TOKEN`; restart |
+| `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) |
 | `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

@@ -281,6 +281,47 @@ var Landscape = z2.object({
   // Per-agent change records for the workspace. Defaulted for version-skew safety.
   changeRecords: z2.array(ChangeRecord).default([])
 });
+var WorkspaceAgent = z2.object({
+  name: z2.string(),
+  human: z2.string(),
+  program: z2.string(),
+  // model is nullable in the DB (may be unknown when an agent first joins).
+  model: z2.string().nullable(),
+  // repo/branch/lastHeartbeatAt come from the agent's most-recent session and
+  // are null when the agent has no session yet.
+  repo: z2.string().nullable(),
+  branch: z2.string().nullable(),
+  lastHeartbeatAt: IsoTimestamp.nullable(),
+  presence: z2.enum(["live", "offline"])
+});
+var TaskStatus = z2.enum(["active", "done", "dropped"]);
+var WorkspaceTask = z2.object({
+  agentName: z2.string(),
+  program: z2.string(),
+  model: z2.string().nullable(),
+  repo: z2.string(),
+  intent: z2.string(),
+  pathGlobs: z2.array(z2.string()),
+  status: TaskStatus,
+  createdAt: IsoTimestamp,
+  endedAt: IsoTimestamp.nullable()
+});
+var WorkspaceAnnouncement = z2.object({
+  fromAgentName: z2.string(),
+  fromHuman: z2.string(),
+  body: z2.string(),
+  targetAgentName: z2.string().nullable(),
+  repo: z2.string(),
+  createdAt: IsoTimestamp
+});
+var WorkspaceLandscapeResponse = z2.object({
+  agents: z2.array(WorkspaceAgent),
+  tasks: z2.array(WorkspaceTask),
+  announcements: z2.array(WorkspaceAnnouncement),
+  // The server's clock, so the client computes "expires in / last seen" against
+  // the hub rather than the (possibly skewed) browser clock.
+  serverTime: IsoTimestamp
+});
 var JoinRequest = z2.object({
   workspace: z2.string().min(1),
   repo: z2.string().min(1),
@@ -309,7 +350,11 @@ var DoneRequest = z2.object({
   workItemId: z2.string().uuid()
 });
 var DoneResponse = z2.object({
-  ok: z2.literal(true)
+  ok: z2.literal(true),
+  // Pending announcements for the caller, delivered as a side effect of done so
+  // a message lands the moment a teammate finishes a unit of work (not only on
+  // their next work/sync). Defaulted for version-skew safety with older hubs.
+  announcements: z2.array(Announcement).default([])
 });
 var AnnounceRequest = z2.object({
   sessionId: z2.string().uuid(),
@@ -320,7 +365,11 @@ var AnnounceRequest = z2.object({
 var AnnounceResponse = z2.object({
   ok: z2.literal(true),
   // bigint PK serialised as number; see DbId note above
-  announcementId: DbId
+  announcementId: DbId,
+  // Pending announcements for the caller, delivered as a side effect of announce
+  // (a turn where the agent is already reading hub output) so inbound messages
+  // surface promptly. Excludes the just-sent one. Defaulted for version skew.
+  announcements: z2.array(Announcement).default([])
 });
 var SyncRequest = z2.object({
   sessionId: z2.string().uuid(),
@@ -335,11 +384,22 @@ var DoneAgentInput = DoneRequest.omit({ sessionId: true });
 var JoinAgentInput = z2.object({});
 var SyncAgentInput = z2.object({});
 var HeartbeatRequest = z2.object({
-  sessionId: z2.string().uuid()
+  sessionId: z2.string().uuid(),
+  // Optional change report so the BACKGROUND heartbeat keeps an agent's durable
+  // change records fresh (commits surface within ~one heartbeat interval, not
+  // 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()
 });
 var HeartbeatResponse = z2.object({
   ok: z2.literal(true)
 });
+var LeaveRequest = z2.object({
+  sessionId: z2.string().uuid()
+});
+var LeaveResponse = z2.object({
+  ok: z2.literal(true)
+});
 
 // src/gitContext.ts
 import { execFileSync } from "child_process";
@@ -404,6 +464,12 @@ function normalizeRemoteUrl(url) {
   const repo = segments[segments.length - 1];
   return `${owner}/${repo}`;
 }
+function canonicalizeRepo(input) {
+  const s = input.trim();
+  const looksLikeUrl = /:\/\//.test(s) || /^[^/@]+@[^:]+:/.test(s);
+  const base = looksLikeUrl ? normalizeRemoteUrl(s) ?? s : s.replace(/\.git$/, "").replace(/^\/+|\/+$/g, "");
+  return base.toLowerCase();
+}
 function detectRepo(cwd = process.cwd()) {
   const origin = runGit(cwd, ["config", "--get", "remote.origin.url"]);
   if (origin) {
@@ -651,6 +717,15 @@ function formatLandscape(landscape) {
   }
   return lines.join("\n");
 }
+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}] ${a.body}`);
+  }
+  return lines.join("\n");
+}
 function relativeAge(iso) {
   const then = Date.parse(iso);
   if (Number.isNaN(then)) return "recently";
@@ -673,16 +748,19 @@ function formatChangeRecords(records, cwd = process.cwd()) {
   const lines = [];
   for (const rec of records) {
     if (rec.kind === "committed") {
-      if (rec.commitSha && isAncestor(cwd, rec.commitSha)) continue;
+      const sha = rec.commitSha;
+      if (sha && isAncestor(cwd, sha)) continue;
+      const present = sha ? hasCommit(cwd, sha) : false;
+      const state = present ? "landed, not yet in your branch \u2014 pull/rebase" : "not yet on your base \u2014 unpushed, coordinate";
       const intent = rec.message ?? "(work in progress)";
       lines.push(
-        `  ${rec.agentName} / ${rec.human} (${presence(rec)}) \u2014 committed (not yet on your base): "${intent}"`
+        `  ${rec.agentName} / ${rec.human} (${presence(rec)}) \u2014 committed (${state}): "${intent}"`
       );
       lines.push(`    files: ${rec.paths.join(", ")}`);
-      if (rec.commitSha && lineRangeBudget > 0 && hasCommit(cwd, rec.commitSha)) {
+      if (sha && present && lineRangeBudget > 0) {
         const budgetedPaths = rec.paths.slice(0, lineRangeBudget);
         lineRangeBudget -= budgetedPaths.length;
-        const ranges = changedLineRanges(cwd, rec.commitSha, budgetedPaths);
+        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}`);
           if (spans.length > 0) {
@@ -772,7 +850,7 @@ ${section}` : body;
     "work",
     {
       title: "Claim a unit of work",
-      description: 'Claim a unit of work BEFORE you start editing files in an area of the codebase (per unit of work, NOT per edit). Pass a one-line `intent` and the `pathGlobs` covering the files you expect to touch \u2014 scope them as specifically as you reasonably can (e.g. ["src/auth/**"], not ["src/**"] and not a single file). It atomically checks whether a teammate is already in those files and claims them for you, returning any conflicts and what others are working on. Hold one claim across all edits in that area; don\'t re-claim per file.',
+      description: 'Claim a unit of work BEFORE you start producing or changing files in an area of the codebase \u2014 source OR a plan/design doc (per unit of work, NOT per edit). Authoring a plan counts: claim the doc\'s path before you write it. Pass a one-line `intent` and the `pathGlobs` covering the files you expect to touch \u2014 scope them as specifically as you reasonably can (e.g. ["src/auth/**"], not ["src/**"] and not a single file). It atomically checks whether a teammate is already in those files and claims them for you, returning any conflicts and what others are working on. Hold one claim across all edits in that area; don\'t re-claim per file.',
       inputSchema: WorkAgentInput.shape
     },
     async (args) => {
@@ -817,13 +895,14 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
       }
       try {
         const body = { sessionId, ...args };
-        await hubClient.post("/done", body);
+        const result = await hubClient.post("/done", body);
+        const base = "Work item released. Call work again before your next edit in a new area.";
+        const msgs = formatAnnouncements(result.announcements ?? []);
         return {
           content: [
-            {
-              type: "text",
-              text: "Work item released. Call work again before your next edit in a new area."
-            }
+            { type: "text", text: msgs ? `${base}
+
+${msgs}` : base }
           ]
         };
       } catch (err) {
@@ -849,12 +928,13 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
       try {
         const body = { sessionId, ...args };
         const result = await hubClient.post("/announce", body);
+        const base = `Announcement sent (id: ${result.announcementId}).`;
+        const msgs = formatAnnouncements(result.announcements ?? []);
         return {
           content: [
-            {
-              type: "text",
-              text: `Announcement sent (id: ${result.announcementId}).`
-            }
+            { type: "text", text: msgs ? `${base}
+
+${msgs}` : base }
           ]
         };
       } catch (err) {
@@ -893,7 +973,18 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
       }
     }
   );
-  return { ready: joinInFlight };
+  async function leave() {
+    try {
+      await joinInFlight;
+      if (!sessionId) return;
+      await hubClient.post("/leave", { sessionId });
+    } catch (err) {
+      console.error(
+        `[shepherd] leave failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  return { ready: joinInFlight, leave };
 }
 
 // src/resolveContext.ts
@@ -904,7 +995,9 @@ var defaultDeps = {
 };
 var DEFAULT_WORKSPACE = "default";
 async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
-  const repo = config.REPO ?? deps.detectRepo(cwd) ?? "unknown-repo";
+  const repo = canonicalizeRepo(
+    config.REPO ?? deps.detectRepo(cwd) ?? "unknown-repo"
+  );
   const branch = config.BRANCH ?? deps.detectBranch(cwd) ?? "HEAD";
   const human = config.HUMAN ?? deps.detectHuman(cwd) ?? generateName();
   const program = config.PROGRAM ?? "claude-code";
@@ -916,7 +1009,8 @@ async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
 // src/heartbeat.ts
 function createHeartbeat({
   hubClient,
-  intervalSeconds
+  intervalSeconds,
+  buildReport
 }) {
   let timer = null;
   function stop() {
@@ -925,16 +1019,26 @@ function createHeartbeat({
       timer = null;
     }
   }
+  async function beat(sessionId) {
+    let changeReport;
+    if (buildReport) {
+      try {
+        changeReport = await buildReport();
+      } catch {
+        changeReport = void 0;
+      }
+    }
+    const body = changeReport ? { sessionId, changeReport } : { sessionId };
+    await hubClient.post("/heartbeat", body);
+  }
   function start(sessionId) {
     stop();
     timer = setInterval(() => {
-      void Promise.resolve(hubClient.post("/heartbeat", { sessionId })).catch(
-        (err) => {
-          console.error(
-            `[shepherd] heartbeat failed: ${err instanceof Error ? err.message : String(err)}`
-          );
-        }
-      );
+      void beat(sessionId).catch((err) => {
+        console.error(
+          `[shepherd] heartbeat failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      });
     }, intervalSeconds * 1e3);
     timer.unref();
   }
@@ -946,7 +1050,7 @@ var SHEPHERD_INSTRUCTIONS = `You are connected to Shepherd, the shared coordinat
 
 Follow this procedure on every session, proactively and without being asked:
 
-1. Before you start working on an AREA of the codebase, call \`work\` ONCE. Pass a one-line \`intent\` and the \`pathGlobs\` covering the files you expect to touch. Scope the globs as specifically as you reasonably can \u2014 tight enough to avoid colliding with unrelated work, broad enough to cover the task (e.g. ["src/auth/**"], not ["src/**"] and not a single file). Hold that one claim across all your edits in that area; do NOT re-claim per file. If it reports a conflict, coordinate or pick different work \u2014 never silently collide.
+1. Before you start producing or changing files in an AREA of the codebase, call \`work\` ONCE. This includes authoring a plan or design doc: claim the doc's path (e.g. ["docs/plans/auth.md"], or the directory you'll write into) BEFORE you write it \u2014 a plan you're about to author counts as a unit of work, not exploration. Pass a one-line \`intent\` and the \`pathGlobs\` covering the files you expect to touch. Scope the globs as specifically as you reasonably can \u2014 tight enough to avoid colliding with unrelated work, broad enough to cover the task (e.g. ["src/auth/**"], not ["src/**"] and not a single file). Hold that one claim across all your edits in that area; do NOT re-claim per file. If it reports a conflict, coordinate or pick different work \u2014 never silently collide.
 
 2. Call \`done\` when that unit of work is complete, using its \`workItemId\`, so teammates see the files freed.
 
@@ -956,7 +1060,7 @@ Follow this procedure on every session, proactively and without being asked:
 
 5. Call \`sync\` when you resume, start a new task, or before large changes, to refresh who is doing what.
 
-Skip \`work\` entirely for read-only exploration. These tools are advisory and degrade gracefully if the hub is unreachable \u2014 never block your real work on them.
+Skip \`work\` entirely for read-only exploration \u2014 reading, searching, or thinking that produces no file. The moment you're going to WRITE something, source or doc, claim it first. These tools are advisory and degrade gracefully if the hub is unreachable \u2014 never block your real work on them.
 
 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.`;
 
@@ -967,26 +1071,39 @@ async function main() {
   const context = await resolveContext(config);
   const heartbeat = createHeartbeat({
     hubClient,
-    intervalSeconds: config.HEARTBEAT_INTERVAL_SECONDS
+    intervalSeconds: config.HEARTBEAT_INTERVAL_SECONDS,
+    // Attach a best-effort change report to each beat so commits surface to
+    // teammates within ~one interval. Fail-open: any git error → presence-only.
+    buildReport: async () => {
+      try {
+        return await buildChangeReport(process.cwd(), config) ?? void 0;
+      } catch {
+        return void 0;
+      }
+    }
   });
   const server = new McpServer(
     { name: "shepherd", version: "0.1.0" },
     { instructions: SHEPHERD_INSTRUCTIONS }
   );
-  registerTools(server, { hubClient, config, context, heartbeat });
+  const tools = registerTools(server, { hubClient, config, context, heartbeat });
   const transport = new StdioServerTransport();
-  const shutdown = () => {
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
     heartbeat.stop();
+    await tools.leave();
   };
   process.once("SIGINT", () => {
-    shutdown();
-    process.exit(0);
+    void shutdown().finally(() => process.exit(0));
   });
   process.once("SIGTERM", () => {
-    shutdown();
-    process.exit(0);
+    void shutdown().finally(() => process.exit(0));
   });
-  transport.onclose = shutdown;
+  transport.onclose = () => {
+    void shutdown();
+  };
   await server.connect(transport);
 }
 main().catch((err) => {

package/package.json

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