@korso/shepherd 0.2.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

@@ -7,14 +7,20 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/config.ts
 import { z } from "zod";
 var ConfigSchema = z.object({
+  // Hard-required: connection credentials.
   HUB_URL: z.string().min(1, "HUB_URL is required"),
   TEAM_TOKEN: z.string().min(1, "TEAM_TOKEN is required"),
-  WORKSPACE: z.string().min(1, "WORKSPACE is required"),
-  REPO: z.string().min(1, "REPO is required"),
-  BRANCH: z.string().min(1, "BRANCH is required"),
-  HUMAN: z.string().min(1, "HUMAN is required"),
-  PROGRAM: z.string().min(1, "PROGRAM is required"),
-  MODEL: z.string().min(1, "MODEL is required")
+  // Optional overrides — resolveContext will apply defaults for any that are absent.
+  // WORKSPACE default is applied in resolveContext (auto-detected from cwd basename).
+  WORKSPACE: z.string().min(1).optional(),
+  REPO: z.string().min(1).optional(),
+  BRANCH: z.string().min(1).optional(),
+  BASE_BRANCH: z.string().min(1).optional(),
+  HUMAN: z.string().min(1).optional(),
+  PROGRAM: z.string().min(1).optional(),
+  MODEL: z.string().min(1).optional(),
+  // Heartbeat cadence in seconds; coerced from string env var.
+  HEARTBEAT_INTERVAL_SECONDS: z.coerce.number().int().positive().default(60)
 });
 function parseConfig(env) {
   return ConfigSchema.parse({
@@ -23,9 +29,11 @@ function parseConfig(env) {
     WORKSPACE: env["WORKSPACE"],
     REPO: env["REPO"],
     BRANCH: env["BRANCH"],
+    BASE_BRANCH: env["BASE_BRANCH"],
     HUMAN: env["HUMAN"],
     PROGRAM: env["PROGRAM"],
-    MODEL: env["MODEL"]
+    MODEL: env["MODEL"],
+    HEARTBEAT_INTERVAL_SECONDS: env["HEARTBEAT_INTERVAL_SECONDS"]
   });
 }
 function loadConfig(env = process.env) {
@@ -71,12 +79,12 @@ function createHubClient({
 }) {
   const baseUrl = hubUrl.replace(/\/$/, "");
   return {
-    async post(path, body) {
+    async post(path2, body) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeoutMs);
       let response;
       try {
-        response = await fetch(`${baseUrl}${path}`, {
+        response = await fetch(`${baseUrl}${path2}`, {
           method: "POST",
           headers: {
             "Authorization": `Bearer ${teamToken}`,
@@ -87,7 +95,7 @@ function createHubClient({
         });
       } catch (err) {
         clearTimeout(timer);
-        const message = err instanceof DOMException && err.name === "AbortError" ? `Hub request timed out after ${timeoutMs}ms (${path})` : `Hub unreachable at ${baseUrl}${path}: ${String(err)}`;
+        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);
@@ -95,7 +103,7 @@ function createHubClient({
       if (!response.ok) {
         throw new HubRequestError(
           response.status,
-          `Hub returned HTTP ${response.status} for ${path}`
+          `Hub returned HTTP ${response.status} for ${path2}`
         );
       }
       return response.json();
@@ -103,10 +111,145 @@ function createHubClient({
   };
 }
 
+// ../shared/dist/names.js
+var adjectives = [
+  "Able",
+  "Agile",
+  "Artful",
+  "Avid",
+  "Balanced",
+  "Brave",
+  "Bright",
+  "Brisk",
+  "Calm",
+  "Clear",
+  "Clever",
+  "Crisp",
+  "Daring",
+  "Diligent",
+  "Deft",
+  "Deep",
+  "Dynamic",
+  "Eager",
+  "Earnest",
+  "Elegant",
+  "Energetic",
+  "Fair",
+  "Faithful",
+  "Fertile",
+  "Fierce",
+  "Firm",
+  "Fleet",
+  "Frank",
+  "Fresh",
+  "Friendly",
+  "Frisky",
+  "Gentle",
+  "Giant",
+  "Gifted",
+  "Global",
+  "Golden",
+  "Good",
+  "Grace",
+  "Grand",
+  "Green"
+];
+var nouns = [
+  "Anchor",
+  "Arrow",
+  "Beacon",
+  "Bear",
+  "Beast",
+  "Bell",
+  "Blade",
+  "Blaze",
+  "Bridge",
+  "Bronze",
+  "Brook",
+  "Builder",
+  "Buzz",
+  "Castle",
+  "Cedar",
+  "Chain",
+  "Charm",
+  "Chase",
+  "Cliff",
+  "Cloud",
+  "Coast",
+  "Compass",
+  "Crown",
+  "Crystal",
+  "Current",
+  "Eagle",
+  "Earth",
+  "Echo",
+  "Edge",
+  "Element",
+  "Ember",
+  "Engine",
+  "Fable",
+  "Falcon",
+  "Fate",
+  "Fawn",
+  "Feather",
+  "Fiber",
+  "Field",
+  "Fire",
+  "Fisher",
+  "Flame",
+  "Flash",
+  "Fleet",
+  "Flight",
+  "Flint",
+  "Flood",
+  "Flow"
+];
+function generateName() {
+  const randomAdj = adjectives[Math.floor(Math.random() * adjectives.length)];
+  const randomNoun = nouns[Math.floor(Math.random() * nouns.length)];
+  return randomAdj + randomNoun;
+}
+
 // ../shared/dist/contract.js
 import { z as z2 } from "zod";
 var IsoTimestamp = z2.string();
 var DbId = z2.number();
+var ChangeRecord = z2.object({
+  agentName: z2.string(),
+  human: z2.string(),
+  branch: z2.string(),
+  kind: z2.enum(["committed", "uncommitted"]),
+  commitSha: z2.string().nullable(),
+  message: z2.string().nullable(),
+  paths: z2.array(z2.string()).min(1),
+  authorIsLive: z2.boolean(),
+  authorLastActiveAt: IsoTimestamp,
+  updatedAt: IsoTimestamp
+});
+var ChangeReportEntry = z2.object({
+  kind: z2.enum(["committed", "uncommitted"]),
+  // A git object id (lowercase hex, 4–64 chars) for `committed` entries, or null
+  // for `uncommitted`. This value is forwarded by the hub to OTHER clients, which
+  // feed it straight into local `git` argument vectors (isAncestor/hasCommit/
+  // changedLineRanges). Validating the shape at the wire boundary stops an
+  // attacker-controlled, flag-like value (e.g. "--output=...") from being parsed
+  // by git as an option on a teammate's machine (argument injection). gitContext
+  // re-validates defensively as well.
+  sha: z2.string().regex(/^[0-9a-f]{4,64}$/).nullable(),
+  message: z2.string().nullable(),
+  paths: z2.array(z2.string()).min(1).max(500)
+});
+var ChangeReport = z2.object({
+  branch: z2.string(),
+  baseBranch: z2.string(),
+  head: z2.string(),
+  truncated: z2.boolean().default(false),
+  // The only producer (gitContext.unlandedCommits) emits at most MAX_COMMITS
+  // (100) committed entries + 1 uncommitted, so this ceiling is generous. If
+  // MAX_COMMITS is ever raised above ~599, raise this in lockstep or the hub
+  // will start 400-rejecting otherwise-valid reports.
+  entries: z2.array(ChangeReportEntry).max(600)
+});
 var Claim = z2.object({
   workItemId: z2.string().uuid(),
   agentName: z2.string(),
@@ -134,7 +277,50 @@ var Landscape = z2.object({
   // claim is live. Optional with a default so an older client talking to a
   // newer hub (or vice-versa) never fails validation on its absence.
   yourClaims: z2.array(Claim).default([]),
-  announcements: z2.array(Announcement)
+  announcements: z2.array(Announcement),
+  // 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),
@@ -142,7 +328,7 @@ var JoinRequest = z2.object({
   branch: z2.string().min(1),
   human: z2.string().min(1),
   program: z2.string().min(1),
-  model: z2.string().min(1)
+  model: z2.string().min(1).optional()
 });
 var JoinResponse = z2.object({
   agentName: z2.string(),
@@ -152,7 +338,8 @@ var WorkRequest = z2.object({
   sessionId: z2.string().uuid(),
   intent: z2.string().min(1).max(2048),
   pathGlobs: z2.array(z2.string().min(1).max(512)).min(1).max(64),
-  ttlSeconds: z2.number().int().positive().optional()
+  ttlSeconds: z2.number().int().positive().optional(),
+  changeReport: ChangeReport.optional()
 });
 var WorkResponse = z2.object({
   workItemId: z2.string().uuid(),
@@ -163,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(),
@@ -174,19 +365,312 @@ 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()
+  sessionId: z2.string().uuid(),
+  changeReport: ChangeReport.optional()
 });
 var SyncResponse = z2.object({
   landscape: Landscape
 });
-var WorkAgentInput = WorkRequest.omit({ sessionId: 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({});
 var SyncAgentInput = z2.object({});
+var HeartbeatRequest = z2.object({
+  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";
+import * as path from "path";
+var GIT_TIMEOUT_MS = 2e3;
+var MAX_COMMITS = 100;
+var MAX_PATHS_PER_COMMIT = 500;
+var MAX_DIRTY_PATHS = 500;
+var MAX_LINE_RANGE_PATHS = 50;
+function runGit(cwd, args) {
+  try {
+    const out = execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: GIT_TIMEOUT_MS,
+      // Keep git from prompting for credentials/editors and hanging the timeout.
+      windowsHide: true,
+      maxBuffer: 64 * 1024 * 1024,
+      // Capture stdout; silence stderr so failures stay quiet (we fail open).
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.trim();
+  } catch {
+    return null;
+  }
+}
+function runGitExitOk(cwd, args) {
+  try {
+    execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: GIT_TIMEOUT_MS,
+      windowsHide: true,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isValidSha(sha) {
+  return /^[0-9a-f]{4,64}$/.test(sha);
+}
+function normalizeRemoteUrl(url) {
+  let s = url.trim();
+  if (!s) return null;
+  s = s.replace(/\.git$/, "");
+  const scp = s.match(/^[^/@]+@[^:]+:(.+)$/);
+  if (scp) {
+    s = scp[1];
+  } else {
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+    const slash = s.indexOf("/");
+    if (slash !== -1) {
+      s = s.slice(slash + 1);
+    }
+  }
+  s = s.replace(/^\/+|\/+$/g, "");
+  const segments = s.split("/").filter(Boolean);
+  if (segments.length < 2) return null;
+  const owner = segments[segments.length - 2];
+  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) {
+    const normalized = normalizeRemoteUrl(origin);
+    if (normalized) return normalized;
+  }
+  const top = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+  if (top) {
+    const base = path.basename(top);
+    if (base) return base;
+  }
+  return null;
+}
+function detectBranch(cwd = process.cwd()) {
+  const branch = runGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (branch === null || branch === "") return null;
+  return branch;
+}
+function detectHuman(cwd = process.cwd()) {
+  if (!runGitExitOk(cwd, ["rev-parse", "--is-inside-work-tree"])) {
+    return null;
+  }
+  const name = runGit(cwd, ["config", "user.name"]);
+  if (name) return name;
+  const email = runGit(cwd, ["config", "user.email"]);
+  if (email) {
+    const local = email.split("@")[0];
+    if (local) return local;
+  }
+  return null;
+}
+function detectBaseBranch(cwd = process.cwd()) {
+  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}`])) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function headSha(cwd = process.cwd()) {
+  const sha = runGit(cwd, ["rev-parse", "HEAD"]);
+  if (sha === null || sha === "") return null;
+  return sha;
+}
+function unlandedCommits(cwd = process.cwd(), baseBranch) {
+  if (!baseBranch || baseBranch.startsWith("-")) {
+    return { commits: [], truncated: false };
+  }
+  const out = runGit(cwd, [
+    "log",
+    `${baseBranch}..HEAD`,
+    "--name-only",
+    `--max-count=${MAX_COMMITS}`,
+    "--format=%x01%H%x00%s"
+  ]);
+  if (out === null) {
+    return { commits: [], truncated: false };
+  }
+  if (out === "") {
+    return { commits: [], truncated: false };
+  }
+  let truncated = false;
+  const commits = [];
+  const records = out.split("
").filter((r) => r.length > 0);
+  for (const record of records) {
+    const newlineIdx = record.indexOf("\n");
+    const header = newlineIdx === -1 ? record : record.slice(0, newlineIdx);
+    const rest = newlineIdx === -1 ? "" : record.slice(newlineIdx + 1);
+    const nulIdx = header.indexOf("\0");
+    const sha = (nulIdx === -1 ? header : header.slice(0, nulIdx)).trim();
+    const message = nulIdx === -1 ? "" : header.slice(nulIdx + 1);
+    if (!sha) continue;
+    let paths = rest.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    if (paths.length > MAX_PATHS_PER_COMMIT) {
+      paths = paths.slice(0, MAX_PATHS_PER_COMMIT);
+      truncated = true;
+    }
+    if (paths.length === 0) continue;
+    commits.push({ sha, message, paths });
+  }
+  if (commits.length >= MAX_COMMITS) {
+    truncated = true;
+  }
+  return { commits, truncated };
+}
+function dirtyPaths(cwd = process.cwd()) {
+  const out = runGit(cwd, ["status", "--porcelain", "-z", "--untracked-files=all"]);
+  if (out === null) {
+    return { paths: [], truncated: false };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const fields = out.split("\0").filter((f) => f.length > 0);
+  for (let i = 0; i < fields.length; i++) {
+    const field = fields[i];
+    const status = field.slice(0, 2);
+    const rest = field.slice(2).replace(/^\s+/, "");
+    if (rest) seen.add(rest);
+    if (/[RC]/.test(status)) {
+      const src = fields[i + 1];
+      if (src) {
+        seen.add(src);
+        i++;
+      }
+    }
+  }
+  let paths = Array.from(seen);
+  let truncated = false;
+  if (paths.length > MAX_DIRTY_PATHS) {
+    paths = paths.slice(0, MAX_DIRTY_PATHS);
+    truncated = true;
+  }
+  return { paths, truncated };
+}
+function isAncestor(cwd = process.cwd(), sha) {
+  if (!isValidSha(sha)) return false;
+  return runGitExitOk(cwd, ["merge-base", "--is-ancestor", sha, "HEAD"]);
+}
+function hasCommit(cwd = process.cwd(), sha) {
+  if (!isValidSha(sha)) return false;
+  return runGitExitOk(cwd, ["cat-file", "-e", `${sha}^{commit}`]);
+}
+function parseHunkRanges(diff) {
+  const ranges = [];
+  const re = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm;
+  let m;
+  while ((m = re.exec(diff)) !== null) {
+    const start = parseInt(m[1], 10);
+    const count = m[2] === void 0 ? 1 : parseInt(m[2], 10);
+    if (count <= 0) {
+      ranges.push({ start, end: start });
+    } else {
+      ranges.push({ start, end: start + count - 1 });
+    }
+  }
+  return ranges;
+}
+function changedLineRanges(cwd = process.cwd(), sha, paths) {
+  if (!isValidSha(sha) || !paths || paths.length === 0) return {};
+  const result = {};
+  const capped = paths.length > MAX_LINE_RANGE_PATHS ? paths.slice(0, MAX_LINE_RANGE_PATHS) : paths;
+  for (const p of capped) {
+    let diff = runGit(cwd, ["diff", "--unified=0", `${sha}~1`, sha, "--", p]);
+    if (diff === null) {
+      diff = runGit(cwd, ["show", "--unified=0", "--format=", sha, "--", p]);
+    }
+    if (diff === null || diff === "") continue;
+    const ranges = parseHunkRanges(diff);
+    if (ranges.length > 0) {
+      result[p] = ranges;
+    }
+  }
+  return result;
+}
+
+// src/changeReport.ts
+var UNRESOLVED_BASE = "(unknown)";
+async function buildChangeReport(cwd, config) {
+  const branch = detectBranch(cwd);
+  const head = headSha(cwd);
+  if (branch === null && head === null) {
+    return void 0;
+  }
+  const base = config.BASE_BRANCH ?? detectBaseBranch(cwd);
+  const entries = [];
+  let truncated = false;
+  const dirty = dirtyPaths(cwd);
+  if (dirty.truncated) truncated = true;
+  if (dirty.paths.length > 0) {
+    entries.push({
+      kind: "uncommitted",
+      sha: null,
+      message: null,
+      paths: dirty.paths
+    });
+  }
+  if (base) {
+    const unlanded = unlandedCommits(cwd, base);
+    if (unlanded.truncated) truncated = true;
+    for (const c of unlanded.commits) {
+      if (c.paths.length === 0) continue;
+      entries.push({
+        kind: "committed",
+        sha: c.sha,
+        message: c.message,
+        paths: c.paths
+      });
+    }
+  }
+  return {
+    branch: branch ?? "HEAD",
+    baseBranch: base ?? UNRESOLVED_BASE,
+    head: head ?? "",
+    truncated,
+    entries
+  };
+}
 
 // src/tools.ts
 function formatLandscape(landscape) {
@@ -233,6 +717,68 @@ 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";
+  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)}`;
+}
+function formatChangeRecords(records, cwd = process.cwd()) {
+  if (!records || records.length === 0) return "";
+  let lineRangeBudget = MAX_LINE_RANGE_PATHS;
+  const lines = [];
+  for (const rec of records) {
+    if (rec.kind === "committed") {
+      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 (${state}): "${intent}"`
+      );
+      lines.push(`    files: ${rec.paths.join(", ")}`);
+      if (sha && present && lineRangeBudget > 0) {
+        const budgetedPaths = rec.paths.slice(0, lineRangeBudget);
+        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}`);
+          if (spans.length > 0) {
+            lines.push(`    ${p}: lines ${spans.join(", ")} (for context)`);
+          }
+        }
+      }
+    } else {
+      const claim = rec.message ?? "uncommitted edits in progress";
+      lines.push(
+        `  ${rec.agentName} / ${rec.human} (${presence(rec)}) \u2014 ${claim} (uncommitted, may change)`
+      );
+      lines.push(`    files: ${rec.paths.join(", ")}`);
+    }
+  }
+  if (lines.length === 0) return "";
+  return "Unlanded changes touching your area (awareness only \u2014 these are not blockers):\n" + lines.join("\n");
+}
 function degradedResult(err) {
   const detail = err instanceof HubUnreachable || err instanceof HubRequestError ? err.message : String(err);
   return {
@@ -245,20 +791,23 @@ function degradedResult(err) {
   };
 }
 function registerTools(server, deps) {
-  const { hubClient, config } = deps;
+  const { hubClient, config, context, heartbeat } = deps;
   let sessionId = null;
   let agentName = null;
   const joinBody = {
-    workspace: config.WORKSPACE,
-    repo: config.REPO,
-    branch: config.BRANCH,
-    human: config.HUMAN,
-    program: config.PROGRAM,
-    model: config.MODEL
+    workspace: context.workspace,
+    repo: context.repo,
+    branch: context.branch,
+    human: context.human,
+    program: context.program
   };
+  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(() => {
   });
   async function awaitJoin() {
@@ -278,12 +827,30 @@ function registerTools(server, deps) {
     return agentName ? `You are ${agentName}.
 
 ${body}` : body;
+  }
+  async function changeReportForBody() {
+    try {
+      return await buildChangeReport(process.cwd(), config) ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  function withChangeRecords(landscape, body) {
+    let section = "";
+    try {
+      section = formatChangeRecords(landscape.changeRecords ?? [], process.cwd());
+    } catch {
+      section = "";
+    }
+    return section ? `${body}
+
+${section}` : body;
   }
   server.registerTool(
     "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) => {
@@ -292,14 +859,18 @@ ${body}` : body;
         return sessionNotReady();
       }
       try {
-        const body = { sessionId, ...args };
+        const changeReport = await changeReportForBody();
+        const body = { sessionId, ...args, ...changeReport ? { changeReport } : {} };
         const result = await hubClient.post("/work", body);
         const text = withIdentity(
-          `Work claimed (workItemId: ${result.workItemId})
+          withChangeRecords(
+            result.landscape,
+            `Work claimed (workItemId: ${result.workItemId})
 
 ` + formatLandscape(result.landscape) + `
 
 You hold this claim until you call done (workItemId: ${result.workItemId}) or it expires (~30 min). Calling work or sync renews it.`
+          )
         );
         return { content: [{ type: "text", text }] };
       } catch (err) {
@@ -324,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) {
@@ -356,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) {
@@ -385,9 +958,12 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
         return sessionNotReady();
       }
       try {
-        const body = { sessionId };
+        const changeReport = await changeReportForBody();
+        const body = { sessionId, ...changeReport ? { changeReport } : {} };
         const result = await hubClient.post("/sync", body);
-        const text = withIdentity(formatLandscape(result.landscape));
+        const text = withIdentity(
+          withChangeRecords(result.landscape, formatLandscape(result.landscape))
+        );
         return { content: [{ type: "text", text }] };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -397,7 +973,76 @@ 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
+var defaultDeps = {
+  detectRepo,
+  detectBranch,
+  detectHuman
+};
+var DEFAULT_WORKSPACE = "default";
+async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
+  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";
+  const model = config.MODEL ?? void 0;
+  const workspace = config.WORKSPACE ?? DEFAULT_WORKSPACE;
+  return { workspace, repo, branch, human, program, model };
+}
+
+// src/heartbeat.ts
+function createHeartbeat({
+  hubClient,
+  intervalSeconds,
+  buildReport
+}) {
+  let timer = null;
+  function stop() {
+    if (timer !== null) {
+      clearInterval(timer);
+      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 beat(sessionId).catch((err) => {
+        console.error(
+          `[shepherd] heartbeat failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      });
+    }, intervalSeconds * 1e3);
+    timer.unref();
+  }
+  return { start, stop };
 }
 
 // src/instructions.ts
@@ -405,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.
 
@@ -415,18 +1060,50 @@ 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.`;
 
 // src/index.ts
 async function main() {
   const config = loadConfig();
   const hubClient = createHubClient({ hubUrl: config.HUB_URL, teamToken: config.TEAM_TOKEN });
+  const context = await resolveContext(config);
+  const heartbeat = createHeartbeat({
+    hubClient,
+    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 });
+  const tools = registerTools(server, { hubClient, config, context, heartbeat });
   const transport = new StdioServerTransport();
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    heartbeat.stop();
+    await tools.leave();
+  };
+  process.once("SIGINT", () => {
+    void shutdown().finally(() => process.exit(0));
+  });
+  process.once("SIGTERM", () => {
+    void shutdown().finally(() => process.exit(0));
+  });
+  transport.onclose = () => {
+    void shutdown();
+  };
   await server.connect(transport);
 }
 main().catch((err) => {

package/package.json

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