@korso/shepherd 0.2.0 → 0.3.0

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,20 +713,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,6 +749,24 @@ 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",
@@ -292,14 +781,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) {
@@ -385,9 +878,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) {
@@ -400,6 +896,51 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
   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.
 
@@ -415,18 +956,37 @@ 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. 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
+  });
   const server = new McpServer(
     { name: "shepherd", version: "0.1.0" },
     { instructions: SHEPHERD_INSTRUCTIONS }
   );
-  registerTools(server, { hubClient, config });
+  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,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.2.0",
+  "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",