@korso/shepherd 0.11.2 → 0.11.4

package/dist/inboxExtension.js

@@ -139,6 +139,15 @@ var MAILBOX_FRESH_MS = 15 * 60 * 1e3;
 function sessionMailboxPath(dir, serverPid) {
   return join3(dir, `agent-${serverPid}.jsonl`);
 }
+var HOOK_CHAIN_REACH = { codex: 8 };
+var DEFAULT_HOOK_CHAIN_REACH = 3;
+var MAX_HOOK_CHAIN_REACH = Math.max(
+  DEFAULT_HOOK_CHAIN_REACH,
+  ...Object.values(HOOK_CHAIN_REACH)
+);
+function hookChainReach(client) {
+  return (client === void 0 ? void 0 : HOOK_CHAIN_REACH[client]) ?? DEFAULT_HOOK_CHAIN_REACH;
+}
 function normalizeCwd(cwd) {
   let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
@@ -146,7 +155,7 @@ function normalizeCwd(cwd) {
 }
 function selectSessionMailboxes(dir, hookChain, hookCwd, staleMs = MAILBOX_FRESH_MS, nowMs = Date.now()) {
   try {
-    const chain = hookChain.slice(0, 3);
+    const chain = hookChain.slice(0, MAX_HOOK_CHAIN_REACH);
     const wantedCwd = hookCwd === null ? null : normalizeCwd(hookCwd);
     const candidates = [];
     for (const name of readdirSync(dir)) {
@@ -180,7 +189,7 @@ function selectSessionMailboxes(dir, hookChain, hookCwd, staleMs = MAILBOX_FRESH
       }
       if (!Array.isArray(meta.chain) || typeof meta.cwd !== "string") continue;
       const i = chain.findIndex((pid) => meta.chain.includes(pid));
-      if (i === -1) continue;
+      if (i === -1 || i >= hookChainReach(meta.client)) continue;
       const j = meta.chain.indexOf(chain[i]);
       if (i >= 2 && (j > 2 || wantedCwd === null || meta.cwd !== wantedCwd))
         continue;
@@ -280,6 +289,51 @@ function mergeAnnouncements(...lists) {
   return [...byId.values()].sort((x, y) => x.id - y.id);
 }
 
+// src/codexHookMigration.ts
+import { z as z2 } from "zod";
+
+// src/codexHookInstall.ts
+import { parse, TomlDate } from "smol-toml";
+
+// src/codexHookFs.ts
+import { z } from "zod";
+var lockSchema = z.object({
+  pid: z.number().int().positive(),
+  createdAt: z.string(),
+  owner: z.string().min(1).optional()
+});
+
+// src/codexHookMigration.ts
+var migrationOutcomeSchema = z2.enum([
+  "migrated",
+  "already-canonical",
+  "user-removed",
+  "ambiguous",
+  "opted-out",
+  "unsupported-shape"
+]);
+var recordSchema = z2.object({
+  status: z2.string(),
+  at: z2.string(),
+  migrationVersion: z2.number().int().nonnegative().optional(),
+  migrationOutcome: migrationOutcomeSchema.optional()
+}).passthrough();
+
+// src/version.ts
+import { createRequire } from "node:module";
+var PACKAGE_VERSION = (() => {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkg = req("../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+// src/hookInstall.ts
+var HOOK_COMMAND = `npx -y --package=@korso/shepherd@${PACKAGE_VERSION} shepherd-inbox-hook`;
+
 // src/instructions.ts
 function sanitizeWorkspace(workspace) {
   return workspace.replace(/\s+/g, " ").slice(0, 64);

package/dist/inboxHook.js

@@ -141,6 +141,15 @@ var MAILBOX_FRESH_MS = 15 * 60 * 1e3;
 function sessionMailboxPath(dir, serverPid) {
   return join3(dir, `agent-${serverPid}.jsonl`);
 }
+var HOOK_CHAIN_REACH = { codex: 8 };
+var DEFAULT_HOOK_CHAIN_REACH = 3;
+var MAX_HOOK_CHAIN_REACH = Math.max(
+  DEFAULT_HOOK_CHAIN_REACH,
+  ...Object.values(HOOK_CHAIN_REACH)
+);
+function hookChainReach(client) {
+  return (client === void 0 ? void 0 : HOOK_CHAIN_REACH[client]) ?? DEFAULT_HOOK_CHAIN_REACH;
+}
 function normalizeCwd(cwd) {
   let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
@@ -163,7 +172,7 @@ function hasFreshSessionMeta(dir, staleMs = MAILBOX_FRESH_MS, nowMs = Date.now()
 }
 function selectSessionMailboxes(dir, hookChain, hookCwd, staleMs = MAILBOX_FRESH_MS, nowMs = Date.now()) {
   try {
-    const chain = hookChain.slice(0, 3);
+    const chain = hookChain.slice(0, MAX_HOOK_CHAIN_REACH);
     const wantedCwd = hookCwd === null ? null : normalizeCwd(hookCwd);
     const candidates = [];
     for (const name of readdirSync(dir)) {
@@ -197,7 +206,7 @@ function selectSessionMailboxes(dir, hookChain, hookCwd, staleMs = MAILBOX_FRESH
       }
       if (!Array.isArray(meta.chain) || typeof meta.cwd !== "string") continue;
       const i = chain.findIndex((pid) => meta.chain.includes(pid));
-      if (i === -1) continue;
+      if (i === -1 || i >= hookChainReach(meta.client)) continue;
       const j = meta.chain.indexOf(chain[i]);
       if (i >= 2 && (j > 2 || wantedCwd === null || meta.cwd !== wantedCwd))
         continue;

package/dist/index.js

@@ -358,6 +358,7 @@ var ChangeReportEntry = z2.object({
   message: z2.string().max(4096).nullable(),
   paths: z2.array(z2.string().min(1).max(1024)).min(1).max(500)
 });
+var CHANGE_REPORT_MAX_BYTES = 48 * 1024;
 var ChangeReport = z2.object({
   branch: z2.string().max(512),
   baseBranch: z2.string().max(512),
@@ -745,20 +746,52 @@ var EntitlementsStatusResponse = z2.object({
     reposUsed: z2.number().int()
   })
 });
+var AnalyticsRange = z2.enum(["24h", "7d", "30d", "90d"]);
+var AnalyticsBucket = z2.enum(["hour", "day"]);
+var PeriodMetric = z2.object({
+  current: z2.number().int().nonnegative(),
+  previous: z2.number().int().nonnegative(),
+  changePct: z2.number().nullable()
+});
+var DurationPercentiles = z2.object({
+  p50: z2.number().nonnegative().nullable(),
+  p95: z2.number().nonnegative().nullable()
+});
 var TrendPoint = z2.object({
-  // `YYYY-MM-DD` (UTC day).
   date: z2.string(),
   count: z2.number()
 });
+var TrendSeries = z2.object({
+  current: z2.array(TrendPoint),
+  previous: z2.array(TrendPoint)
+});
 var TopWorkspace = z2.object({
   name: z2.string(),
   slug: z2.string(),
-  members: z2.number(),
-  agents: z2.number(),
-  liveSessions: z2.number()
+  members: z2.number().int().nonnegative(),
+  agents: z2.number().int().nonnegative(),
+  liveSessions: z2.number().int().nonnegative(),
+  // Distinct agents with any session activity inside the window.
+  activeAgents: z2.number().int().nonnegative(),
+  sessions: z2.number().int().nonnegative(),
+  commits: z2.number().int().nonnegative(),
+  claimsReleased: z2.number().int().nonnegative(),
+  // Median released-claim duration (created_at -> released_at), seconds.
+  medianClaimSeconds: z2.number().nonnegative().nullable(),
+  // ISO timestamp of the most recent observed activity, or null if none.
+  lastActivityAt: IsoTimestamp.nullable()
 });
 var ShepherdAnalyticsResponse = z2.object({
   generatedAt: IsoTimestamp,
+  // Echo of the (validated) requested window plus the bucket granularity and
+  // the exact half-open window [windowStart, windowEnd) the hub computed
+  // against — clients label charts from these instead of re-deriving time math.
+  range: AnalyticsRange,
+  bucket: AnalyticsBucket,
+  windowStart: IsoTimestamp,
+  windowEnd: IsoTimestamp,
+  // Current-state totals: whole-platform counts as of `generatedAt`,
+  // independent of the requested range.
   totals: z2.object({
     accounts: z2.number(),
     workspaces: z2.number(),
@@ -778,12 +811,30 @@ var ShepherdAnalyticsResponse = z2.object({
     avgMembersPerWorkspace: z2.number(),
     largestWorkspace: z2.number()
   }),
+  // Range-scoped KPIs, each with its aligned previous-period comparison.
+  period: z2.object({
+    activeWorkspaces: PeriodMetric,
+    newAccounts: PeriodMetric,
+    newSessions: PeriodMetric,
+    commits: PeriodMetric,
+    claimsReleased: PeriodMetric
+  }),
+  // Observed timing diagnostics over the current window: session span is
+  // created_at -> last_heartbeat_at; claim duration is created_at ->
+  // released_at (released claims only).
+  timing: z2.object({
+    sessionSpanSeconds: DurationPercentiles,
+    claimDurationSeconds: DurationPercentiles
+  }),
   feedbackByType: z2.array(z2.object({ type: z2.string(), count: z2.number() })),
+  // Bucketed activity series (hourly for 24h, daily otherwise), each carrying
+  // its aligned previous-period twin for chart overlays.
   trends: z2.object({
-    newAccounts: z2.array(TrendPoint),
-    newWorkspaces: z2.array(TrendPoint),
-    newSessions: z2.array(TrendPoint),
-    commits: z2.array(TrendPoint)
+    newAccounts: TrendSeries,
+    newWorkspaces: TrendSeries,
+    newSessions: TrendSeries,
+    commits: TrendSeries,
+    claimsReleased: TrendSeries
   }),
   topWorkspaces: z2.array(TopWorkspace)
 });
@@ -1167,13 +1218,30 @@ async function buildChangeReport(cwd, config) {
       });
     }
   }
-  return {
+  return fitToBudget({
     branch: branch ?? "HEAD",
     baseBranch: base ?? UNRESOLVED_BASE,
     head: head ?? "",
     truncated,
     entries
-  };
+  });
+}
+function serializedBytes(report) {
+  return Buffer.byteLength(JSON.stringify(report));
+}
+function fitToBudget(report) {
+  if (serializedBytes(report) <= CHANGE_REPORT_MAX_BYTES) return report;
+  report.truncated = true;
+  while (report.entries.length > 0 && report.entries[report.entries.length - 1].kind === "committed" && serializedBytes(report) > CHANGE_REPORT_MAX_BYTES) {
+    report.entries.pop();
+  }
+  const dirty = report.entries[0];
+  if (dirty?.kind === "uncommitted") {
+    while (dirty.paths.length > 1 && serializedBytes(report) > CHANGE_REPORT_MAX_BYTES) {
+      dirty.paths.length = Math.ceil(dirty.paths.length / 2);
+    }
+  }
+  return report;
 }
 
 // src/inbox.ts
@@ -1208,6 +1276,12 @@ function sessionMailboxPath(dir, serverPid) {
 function sessionMetaPath(dir, serverPid) {
   return join3(dir, `agent-${serverPid}.json`);
 }
+var HOOK_CHAIN_REACH = { codex: 8 };
+var DEFAULT_HOOK_CHAIN_REACH = 3;
+var MAX_HOOK_CHAIN_REACH = Math.max(
+  DEFAULT_HOOK_CHAIN_REACH,
+  ...Object.values(HOOK_CHAIN_REACH)
+);
 function normalizeCwd(cwd) {
   let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
@@ -1220,7 +1294,12 @@ function writeMailboxMeta(dir, serverPid, meta) {
     const tmp = `${dest}.tmp`;
     writeFileSync3(
       tmp,
-      JSON.stringify({ v: 1, cwd: normalizeCwd(meta.cwd), chain: meta.chain })
+      JSON.stringify({
+        v: 1,
+        cwd: normalizeCwd(meta.cwd),
+        chain: meta.chain,
+        ...meta.client === void 0 ? {} : { client: meta.client }
+      })
     );
     renameSync(tmp, dest);
   } catch {
@@ -2403,131 +2482,6 @@ function createHeartbeat({
   return { start, stop };
 }
 
-// src/instructions.ts
-function sanitizeWorkspace(workspace) {
-  return workspace.replace(/\s+/g, " ").slice(0, 64);
-}
-function buildInstructions(state, workspace) {
-  switch (state) {
-    case "linked":
-      return `${INTRO} This repository is linked to the \`${workspace ? sanitizeWorkspace(workspace) : "team"}\` workspace, so coordination is active.
-
-${PROCEDURE}`;
-    case "declined":
-      return "Shepherd (team coordination) is connected, but the user declined coordination for this repository. Do not call Shepherd tools or bring up coordination here. If the user asks to start coordinating this repo, call `link`.";
-    case "unanswered":
-      return `${INTRO}
-
-${FIRST_RUN_ASK}`;
-  }
-}
-var INTRO = "You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories.";
-var FIRST_RUN_ASK = `This repository isn't linked to a Shepherd workspace yet, so coordination is dormant. Shepherd normally asks the user directly (a popup) when file edits are detected \u2014 you don't need to raise it yourself.
-
-If the user asks you to set up coordination \u2014 or you're about to change files and no popup or Shepherd message has settled the question \u2014 ask at most once: call \`link\` with no argument. It auto-links when the user belongs to exactly one workspace, or lists the choices; ask the user which workspace, then call \`link\` again with their answer. If they say no, call \`decline\` so they're never asked again. Once linked, the tool results will guide the coordination procedure.`;
-var PROCEDURE = `Follow this procedure on every session, proactively and without being asked:
-
-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.
-
-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 \`target\`; otherwise broadcast. A human teammate's name (or \`admin\`) as \`target\` reaches them on the dashboard \u2014 reply to a human's message that way, directed to its sender, never in your own chat. 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 \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/processTree.ts
-import { execFile as execFile2 } from "node:child_process";
-import { promisify } from "node:util";
-var execFileAsync = promisify(execFile2);
-function pidChainFromMap(startPid, parentOf, maxDepth = 32) {
-  const chain = [];
-  const seen = /* @__PURE__ */ new Set();
-  let pid = startPid;
-  while (chain.length < maxDepth && pid > 0 && !seen.has(pid)) {
-    chain.push(pid);
-    seen.add(pid);
-    const parent = parentOf.get(pid);
-    if (parent === void 0) break;
-    pid = parent;
-  }
-  return chain;
-}
-function quickChain() {
-  return [process.pid, process.ppid];
-}
-function parseWmicProcessList(text) {
-  const map = /* @__PURE__ */ new Map();
-  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
-  if (lines.length === 0) return map;
-  const header = lines[0].trimStart();
-  let pidFirst;
-  if (header.startsWith("ParentProcessId")) pidFirst = false;
-  else if (header.startsWith("ProcessId")) pidFirst = true;
-  else return map;
-  for (const line of lines.slice(1)) {
-    const nums = line.trim().split(/\s+/).map(Number);
-    if (nums.length !== 2 || nums.some((n) => !Number.isInteger(n))) continue;
-    const [a, b] = nums;
-    const [pid, ppid] = pidFirst ? [a, b] : [b, a];
-    map.set(pid, ppid);
-  }
-  return map;
-}
-function parsePidPpidLines(text) {
-  const map = /* @__PURE__ */ new Map();
-  for (const line of text.split(/\r?\n/)) {
-    const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
-    if (m) map.set(Number(m[1]), Number(m[2]));
-  }
-  return map;
-}
-async function snapshotParentMap() {
-  if (process.platform === "win32") {
-    try {
-      const { stdout: stdout3 } = await execFileAsync(
-        "wmic",
-        ["process", "get", "ProcessId,ParentProcessId"],
-        { windowsHide: true, timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
-      );
-      const map = parseWmicProcessList(stdout3);
-      if (map.size > 0) return map;
-    } catch {
-    }
-    const { stdout: stdout2 } = await execFileAsync(
-      "powershell.exe",
-      [
-        "-NoProfile",
-        "-NonInteractive",
-        "-Command",
-        'Get-CimInstance -Query "SELECT ProcessId,ParentProcessId FROM Win32_Process" | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId)" }'
-      ],
-      { windowsHide: true, timeout: 15e3, maxBuffer: 8 * 1024 * 1024 }
-    );
-    return parsePidPpidLines(stdout2);
-  }
-  const { stdout } = await execFileAsync(
-    "ps",
-    ["-eo", "pid=,ppid="],
-    { timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
-  );
-  return parsePidPpidLines(stdout);
-}
-async function ancestorChain(maxDepth = 32, snapshot = snapshotParentMap) {
-  try {
-    const map = await snapshot();
-    const chain = pidChainFromMap(process.pid, map, maxDepth);
-    return chain.length >= 2 ? chain : quickChain();
-  } catch {
-    return quickChain();
-  }
-}
-
 // src/hookInstall.ts
 import {
   readFileSync as readFileSync8,
@@ -2633,11 +2587,25 @@ function planCodexConfig(source, command) {
   const candidate = installCandidate(source, config, command);
   return candidate === null ? { kind: "skip", outcome: "unsupported-shape" } : { kind: "install", candidate };
 }
-function appendMissingCodexHandlers(source, command) {
+function hasCanonicalHandler(source, event, hookMarker) {
+  const headers = new RegExp("^\\[\\[hooks\\." + event + "\\]\\]$", "gm");
+  const boundary = new RegExp("^\\[(?!\\[hooks\\." + event + "\\.)", "m");
+  const nested = new RegExp("^\\[\\[hooks\\." + event + "\\.hooks\\]\\]$", "m");
+  let header;
+  while ((header = headers.exec(source)) !== null) {
+    const rest = source.slice(header.index + header[0].length);
+    const end = rest.search(boundary);
+    const group = end === -1 ? rest : rest.slice(0, end);
+    if (group.includes(hookMarker) && nested.test(group)) return true;
+  }
+  return false;
+}
+function appendMissingCodexHandlers(source, command, hookMarker) {
   const handlers = [
-    canonicalHandlerBlock("SessionStart", command),
-    canonicalHandlerBlock("PreToolUse", command, "*")
-  ].filter((handler) => !source.includes(handler));
+    ["UserPromptSubmit", void 0],
+    ["SessionStart", void 0],
+    ["PreToolUse", "*"]
+  ].filter(([event]) => !hasCanonicalHandler(source, event, hookMarker)).map(([event, matcher]) => canonicalHandlerBlock(event, command, matcher));
   const candidate = handlers.length === 0 ? source : source + (source.endsWith("\n") ? "" : "\n") + handlers.join("");
   return parseConfig2(candidate) === null ? null : candidate;
 }
@@ -2880,7 +2848,7 @@ function ensureMigrationBackup(backupFile, source) {
 }
 
 // src/codexHookMigration.ts
-var MIGRATION_VERSION = 2;
+var MIGRATION_VERSION = 3;
 var migrationOutcomeSchema = z5.enum([
   "migrated",
   "already-canonical",
@@ -2900,8 +2868,12 @@ function migrationPaths(homeDir) {
   return {
     hooksDir,
     recordFile: join6(hooksDir, "codex.json"),
-    lockFile: join6(hooksDir, "codex-migration-v2.lock"),
-    backupFile: join6(hooksDir, "backups", "codex-config-before-v2.toml"),
+    lockFile: join6(hooksDir, `codex-migration-v${MIGRATION_VERSION}.lock`),
+    backupFile: join6(
+      hooksDir,
+      "backups",
+      `codex-config-before-v${MIGRATION_VERSION}.toml`
+    ),
     configFile: join6(homeDir, ".codex", "config.toml")
   };
 }
@@ -2981,8 +2953,8 @@ function exactOwnedLegacyBlock(source, hooksDir) {
   return exact.length === 1 ? exact[0] : void 0;
 }
 function migrateLegacy(context, state, sourceBytes, source) {
-  const { paths, command, log } = context;
-  const candidate = appendMissingCodexHandlers(source, command);
+  const { paths, command, hookMarker, log } = context;
+  const candidate = appendMissingCodexHandlers(source, command, hookMarker);
   if (candidate === null) {
     advanceRecord(paths.recordFile, state, "skipped", "unsupported-shape");
     return "skipped";
@@ -3288,6 +3260,158 @@ function installPi(homeDir, extensionSource, log) {
   return "installed";
 }
 
+// src/instructions.ts
+function sanitizeWorkspace(workspace) {
+  return workspace.replace(/\s+/g, " ").slice(0, 64);
+}
+function buildInstructions(state, workspace) {
+  switch (state) {
+    case "linked":
+      return `${INTRO} This repository is linked to the \`${workspace ? sanitizeWorkspace(workspace) : "team"}\` workspace, so coordination is active.
+
+${PROCEDURE}`;
+    case "declined":
+      return "Shepherd (team coordination) is connected, but the user declined coordination for this repository. Do not call Shepherd tools or bring up coordination here. If the user asks to start coordinating this repo, call `link`.";
+    case "unanswered":
+      return `${INTRO}
+
+${FIRST_RUN_ASK}`;
+  }
+}
+var INTRO = "You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories.";
+var FIRST_RUN_ASK = `This repository isn't linked to a Shepherd workspace yet, so coordination is dormant. Shepherd normally asks the user directly (a popup) when file edits are detected \u2014 you don't need to raise it yourself.
+
+If the user asks you to set up coordination \u2014 or you're about to change files and no popup or Shepherd message has settled the question \u2014 ask at most once: call \`link\` with no argument. It auto-links when the user belongs to exactly one workspace, or lists the choices; ask the user which workspace, then call \`link\` again with their answer. If they say no, call \`decline\` so they're never asked again. Once linked, the tool results will guide the coordination procedure.`;
+var PROCEDURE = `Follow this procedure on every session, proactively and without being asked:
+
+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.
+
+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 \`target\`; otherwise broadcast. A human teammate's name (or \`admin\`) as \`target\` reaches them on the dashboard \u2014 reply to a human's message that way, directed to its sender, never in your own chat. 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 \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.`;
+function clientInjectsInstructions(client) {
+  return client === "claude";
+}
+function stageCoordinationBriefing({
+  clientName,
+  linkState,
+  workspace,
+  append
+}) {
+  if (linkState !== "linked") return false;
+  if (clientInjectsInstructions(detectClient(clientName))) return false;
+  append([coordinationBriefing(workspace)]);
+  return true;
+}
+function coordinationBriefing(workspace) {
+  const safeWorkspace = sanitizeWorkspace(workspace ?? "team");
+  return {
+    // Negative, timestamp-derived: the mailbox dedupes by id and the hub's ids
+    // are positive, so a locally-minted id can never collide with a real one.
+    id: -Date.now(),
+    fromAgentName: "shepherd",
+    fromHuman: "shepherd",
+    targetAgentName: null,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    body: `Shepherd coordination is ACTIVE for this repository (workspace \`${safeWorkspace}\`), and your client does not surface Shepherd's standing instructions \u2014 so they arrive here. Procedure from now on, proactively and without being asked: call \`work\` (a one-line intent plus the \`pathGlobs\` you expect to touch) BEFORE you start changing files in an area \u2014 a plan or design doc you are about to author counts \u2014 and hold that ONE claim across every edit in that area; call \`done\` with its \`workItemId\` when the unit of work is complete; call \`announce\` whenever you find something teammates need; call \`sync\` when you resume or switch tasks. Skip \`work\` for read-only exploration that produces no file. If \`work\` reports a conflict, coordinate or pick different work \u2014 never silently collide. These tools are advisory: never block real work on them.`
+  };
+}
+
+// src/processTree.ts
+import { execFile as execFile2 } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile2);
+function pidChainFromMap(startPid, parentOf, maxDepth = 32) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let pid = startPid;
+  while (chain.length < maxDepth && pid > 0 && !seen.has(pid)) {
+    chain.push(pid);
+    seen.add(pid);
+    const parent = parentOf.get(pid);
+    if (parent === void 0) break;
+    pid = parent;
+  }
+  return chain;
+}
+function quickChain() {
+  return [process.pid, process.ppid];
+}
+function parseWmicProcessList(text) {
+  const map = /* @__PURE__ */ new Map();
+  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  if (lines.length === 0) return map;
+  const header = lines[0].trimStart();
+  let pidFirst;
+  if (header.startsWith("ParentProcessId")) pidFirst = false;
+  else if (header.startsWith("ProcessId")) pidFirst = true;
+  else return map;
+  for (const line of lines.slice(1)) {
+    const nums = line.trim().split(/\s+/).map(Number);
+    if (nums.length !== 2 || nums.some((n) => !Number.isInteger(n))) continue;
+    const [a, b] = nums;
+    const [pid, ppid] = pidFirst ? [a, b] : [b, a];
+    map.set(pid, ppid);
+  }
+  return map;
+}
+function parsePidPpidLines(text) {
+  const map = /* @__PURE__ */ new Map();
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+    if (m) map.set(Number(m[1]), Number(m[2]));
+  }
+  return map;
+}
+async function snapshotParentMap() {
+  if (process.platform === "win32") {
+    try {
+      const { stdout: stdout3 } = await execFileAsync(
+        "wmic",
+        ["process", "get", "ProcessId,ParentProcessId"],
+        { windowsHide: true, timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
+      );
+      const map = parseWmicProcessList(stdout3);
+      if (map.size > 0) return map;
+    } catch {
+    }
+    const { stdout: stdout2 } = await execFileAsync(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        'Get-CimInstance -Query "SELECT ProcessId,ParentProcessId FROM Win32_Process" | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId)" }'
+      ],
+      { windowsHide: true, timeout: 15e3, maxBuffer: 8 * 1024 * 1024 }
+    );
+    return parsePidPpidLines(stdout2);
+  }
+  const { stdout } = await execFileAsync(
+    "ps",
+    ["-eo", "pid=,ppid="],
+    { timeout: 1e4, maxBuffer: 8 * 1024 * 1024 }
+  );
+  return parsePidPpidLines(stdout);
+}
+async function ancestorChain(maxDepth = 32, snapshot = snapshotParentMap) {
+  try {
+    const map = await snapshot();
+    const chain = pidChainFromMap(process.pid, map, maxDepth);
+    return chain.length >= 2 ? chain : quickChain();
+  } catch {
+    return quickChain();
+  }
+}
+
 // src/index.ts
 async function main() {
   const config = loadConfig();
@@ -3300,10 +3424,12 @@ async function main() {
   const inboxFile = sessionMailboxPath(inboxDir, process.pid);
   const launchCwd = process.cwd();
   let serverChain = quickChain();
+  let serverClient;
   const liveness = {
     refresh: () => writeMailboxMeta(inboxDir, process.pid, {
       cwd: launchCwd,
-      chain: serverChain
+      chain: serverChain,
+      client: serverClient
     }),
     remove: () => removeMailboxMeta(inboxDir, process.pid)
   };
@@ -3343,10 +3469,19 @@ async function main() {
   });
   const transport = new StdioServerTransport();
   server.server.oninitialized = () => {
+    const clientName = server.server.getClientVersion()?.name;
     void autoInstallHooks({
-      clientName: server.server.getClientVersion()?.name,
+      clientName,
       disabled: config.SHEPHERD_NO_AUTO_HOOKS
     });
+    serverClient = detectClient(clientName);
+    liveness.refresh();
+    stageCoordinationBriefing({
+      clientName,
+      linkState: context.linkState,
+      workspace: context.workspace,
+      append: (announcements) => appendAnnouncements(inboxFile, announcements)
+    });
   };
   let shuttingDown = false;
   const shutdown = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) advisory cross-session coordination tools (work/done/announce/sync, plus link/unlink/decline) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "homepage": "https://github.com/Korso-AI/shepherd#readme",
   "bugs": {