@korso/shepherd 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @korso/shepherd — Shepherd MCP Server
 
-Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) five advisory coordination tools backed by the shared hub: `join`, `work`, `done`, `announce`, and `sync`.
+Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory coordination tools backed by the shared hub: `work`, `done`, `announce`, and `sync`. The agent **joins the workspace automatically** on startup (no `join` tool), and the server ships standing instructions so the agent self-coordinates without the user prompting it.
 
 > **New here?** The [developer quickstart](https://github.com/Korsoai/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y @korso/shepherd` with the env vars below.
 
@@ -10,7 +10,7 @@ Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, et
 
 > **Everyone must set `WORKSPACE` to the identical string, and that string must equal the hub's `ALLOWED_WORKSPACE` env var.**
 
-If `WORKSPACE` does not match, the server's `join` call to the hub returns HTTP 400 immediately. The error is loud on purpose — you will see it in stderr the moment the first tool is called. This is the most common silent onboarding mistake; the guard turns it into a loud, immediate failure.
+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.
 
 ---
 
@@ -156,7 +156,7 @@ No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to ex
 
 and the process exits 1 immediately. This is by design.
 
-**Wrong WORKSPACE:** the server starts and connects, but the first tool call (`work`, `sync`, etc.) returns a 400 from the hub. Check that your `WORKSPACE` value exactly matches the hub's `ALLOWED_WORKSPACE`.
+**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.
 
 ---
 
@@ -198,6 +198,6 @@ 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 |
-| Hub returns 400 on first tool call | `WORKSPACE` mismatch between client and hub | Set `WORKSPACE` to exactly match the hub's `ALLOWED_WORKSPACE` |
+| 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 |
 | `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,9 @@ 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 JoinRequest = z2.object({
   workspace: z2.string().min(1),
@@ -142,7 +287,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 +297,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(),
@@ -177,16 +323,288 @@ var AnnounceResponse = z2.object({
   announcementId: DbId
 });
 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()
+});
+var HeartbeatResponse = 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 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 +651,56 @@ function formatLandscape(landscape) {
   }
   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") {
+      if (rec.commitSha && isAncestor(cwd, rec.commitSha)) continue;
+      const intent = rec.message ?? "(work in progress)";
+      lines.push(
+        `  ${rec.agentName} / ${rec.human} (${presence(rec)}) \u2014 committed (not yet on your base): "${intent}"`
+      );
+      lines.push(`    files: ${rec.paths.join(", ")}`);
+      if (rec.commitSha && lineRangeBudget > 0 && hasCommit(cwd, rec.commitSha)) {
+        const budgetedPaths = rec.paths.slice(0, lineRangeBudget);
+        lineRangeBudget -= budgetedPaths.length;
+        const ranges = changedLineRanges(cwd, rec.commitSha, 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,73 +713,87 @@ function degradedResult(err) {
   };
 }
 function registerTools(server, deps) {
-  const { hubClient, config } = deps;
+  const { hubClient, config, context, heartbeat } = deps;
   let sessionId = null;
-  let joinInFlight = null;
+  let agentName = null;
+  const joinBody = {
+    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() {
-    if (joinInFlight) await joinInFlight;
+    await joinInFlight;
   }
-  server.registerTool(
-    "join",
-    {
-      title: "Join coordination hub",
-      description: "Register yourself with the team coordination hub at the start of a session. Call once before any other coordination tool. Returns your assigned agent name and session ID that the other tools use automatically.",
-      inputSchema: JoinAgentInput.shape
-    },
-    async (_args) => {
-      try {
-        const body = {
-          workspace: config.WORKSPACE,
-          repo: config.REPO,
-          branch: config.BRANCH,
-          human: config.HUMAN,
-          program: config.PROGRAM,
-          model: config.MODEL
-        };
-        const pending = hubClient.post("/join", body);
-        joinInFlight = pending.then((r) => {
-          sessionId = r.sessionId;
-        }).catch(() => {
-        });
-        const result = await pending;
-        sessionId = result.sessionId;
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Joined as ${result.agentName}.`
-            }
-          ]
-        };
-      } catch (err) {
-        if (err instanceof HubUnreachable || err instanceof HubRequestError) {
-          return degradedResult(err);
+  function sessionNotReady() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Shepherd coordination session not ready (hub unreachable at startup) \u2014 proceeding uncoordinated."
         }
-        throw err;
-      }
+      ]
+    };
+  }
+  function withIdentity(body) {
+    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: "Call this BEFORE you start a unit of work. It atomically checks whether any teammate's agent is already touching the same files and claims the work for you, returning any conflicts and what others are working on. Always call this before editing files.",
+      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.',
       inputSchema: WorkAgentInput.shape
     },
     async (args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        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 = `Work claimed (workItemId: ${result.workItemId})
+        const text = withIdentity(
+          withChangeRecords(
+            result.landscape,
+            `Work claimed (workItemId: ${result.workItemId})
+
+` + formatLandscape(result.landscape) + `
 
-` + 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) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -325,16 +807,13 @@ function registerTools(server, deps) {
     "done",
     {
       title: "Release a work claim",
-      description: "Call when you finish a unit of work to release your claim so teammates know the files are free. Pass the workItemId returned by the work tool.",
+      description: "Call when a unit of work is complete to release your claim so teammates know the files are free. Pass the workItemId returned by the work tool.",
       inputSchema: DoneAgentInput.shape
     },
     async (args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        return sessionNotReady();
       }
       try {
         const body = { sessionId, ...args };
@@ -343,7 +822,7 @@ function registerTools(server, deps) {
           content: [
             {
               type: "text",
-              text: "Work item released."
+              text: "Work item released. Call work again before your next edit in a new area."
             }
           ]
         };
@@ -359,16 +838,13 @@ function registerTools(server, deps) {
     "announce",
     {
       title: "Broadcast a message to teammates",
-      description: "Broadcast a heads-up to the other agents (or hand a specific agent a finding). This is awareness only \u2014 not a task assignment. Omit targetAgentName to broadcast to everyone in the workspace.",
+      description: "Broadcast a heads-up to the other agents, or direct a finding to a specific agent. This is awareness only \u2014 not a task assignment. To direct it, pass that agent's name (exactly as shown in the landscape) as targetAgentName; omit it to broadcast to everyone in the workspace. Delivery is best-effort: the recipient sees it on their next work/sync, once.",
       inputSchema: AnnounceAgentInput.shape
     },
     async (args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        return sessionNotReady();
       }
       try {
         const body = { sessionId, ...args };
@@ -393,21 +869,21 @@ function registerTools(server, deps) {
     "sync",
     {
       title: "Sync team landscape",
-      description: "Optional periodic pull of the latest team landscape (who's working on what, any messages for you). Also keeps your claims alive. Call this if you want to check for teammate activity without starting new work.",
+      description: "Pull the latest team landscape (who's working on what, any messages for you) and renew your active claims. Call when you resume, start a new task, or before large changes \u2014 or any time you want to check for teammate activity without claiming work.",
       inputSchema: SyncAgentInput.shape
     },
     async (_args) => {
       await awaitJoin();
       if (sessionId === null) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: "Call join first \u2014 no active session." }]
-        };
+        return sessionNotReady();
       }
       try {
-        const body = { sessionId };
+        const changeReport = await changeReportForBody();
+        const body = { sessionId, ...changeReport ? { changeReport } : {} };
         const result = await hubClient.post("/sync", body);
-        const text = 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) {
@@ -417,15 +893,100 @@ function registerTools(server, deps) {
       }
     }
   );
+  return { ready: joinInFlight };
+}
+
+// src/resolveContext.ts
+var defaultDeps = {
+  detectRepo,
+  detectBranch,
+  detectHuman
+};
+var DEFAULT_WORKSPACE = "default";
+async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
+  const repo = 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
+}) {
+  let timer = null;
+  function stop() {
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+  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)}`
+          );
+        }
+      );
+    }, intervalSeconds * 1e3);
+    timer.unref();
+  }
+  return { start, stop };
 }
 
+// src/instructions.ts
+var SHEPHERD_INSTRUCTIONS = `You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories. You have ALREADY been joined to the workspace automatically \u2014 there is no setup step, and you must not ask the user how to connect.
+
+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.
+
+2. Call \`done\` when that unit of work is complete, using its \`workItemId\`, so teammates see the files freed.
+
+3. Re-call \`work\` only when you move to a DIFFERENT area not covered by a live claim. (\`work\` and \`sync\` also renew your existing claims.)
+
+4. Call \`announce\` whenever you discover something another agent needs \u2014 a shared decision, a gotcha, an API change, a finding. If the landscape shows a specific agent working in the affected area, direct it to them by passing their name as \`targetAgentName\`; otherwise broadcast. Awareness only, not task assignment.
+
+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.
+
+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 server = new McpServer({ name: "shepherd", version: "0.1.0" });
-  registerTools(server, { hubClient, config });
+  const context = await resolveContext(config);
+  const heartbeat = createHeartbeat({
+    hubClient,
+    intervalSeconds: config.HEARTBEAT_INTERVAL_SECONDS
+  });
+  const server = new McpServer(
+    { name: "shepherd", version: "0.1.0" },
+    { instructions: SHEPHERD_INSTRUCTIONS }
+  );
+  registerTools(server, { hubClient, config, context, heartbeat });
   const transport = new StdioServerTransport();
+  const shutdown = () => {
+    heartbeat.stop();
+  };
+  process.once("SIGINT", () => {
+    shutdown();
+    process.exit(0);
+  });
+  process.once("SIGTERM", () => {
+    shutdown();
+    process.exit(0);
+  });
+  transport.onclose = shutdown;
   await server.connect(transport);
 }
 main().catch((err) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.1.0",
-  "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) five advisory cross-session coordination tools (join/work/done/announce/sync) backed by the shared Shepherd hub.",
+  "version": "0.3.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",
   "bin": {