@korso/shepherd 0.4.5 → 0.6.0

package/dist/index.js

@@ -7,11 +7,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/config.ts
 import { z } from "zod";
 var ConfigSchema = z.object({
-  // Hard-required: connection credentials.
+  // Hard-required: Hub endpoint.
   HUB_URL: z.string().min(1, "HUB_URL is required"),
-  TEAM_TOKEN: z.string().min(1, "TEAM_TOKEN is required"),
+  // Auth credentials. Exactly one form is needed (enforced by the refine below):
+  //   - SHEPHERD_TOKEN: the hosted Hub credential (carries its own workspace).
+  //   - TEAM_TOKEN: the self-host credential.
+  // SHEPHERD_TOKEN wins when both are present (see the derived `authToken`).
+  SHEPHERD_TOKEN: z.string().min(1).optional(),
+  TEAM_TOKEN: z.string().min(1).optional(),
   // Optional overrides — resolveContext will apply defaults for any that are absent.
   // WORKSPACE default is applied in resolveContext (auto-detected from cwd basename).
+  // NOTE: WORKSPACE is IGNORED by the hosted Hub — the SHEPHERD_TOKEN carries the
+  // workspace identity. It remains meaningful only for self-host (TEAM_TOKEN) setups.
   WORKSPACE: z.string().min(1).optional(),
   REPO: z.string().min(1).optional(),
   BRANCH: z.string().min(1).optional(),
@@ -28,10 +35,14 @@ var ConfigSchema = z.object({
   // work/sync/done/announce tool results as before. Both the MCP server and the
   // hook must agree on this path.
   SHEPHERD_INBOX_DIR: z.string().min(1).optional()
+}).refine((c) => Boolean(c.SHEPHERD_TOKEN || c.TEAM_TOKEN), {
+  message: "Either SHEPHERD_TOKEN or TEAM_TOKEN is required",
+  path: ["SHEPHERD_TOKEN"]
 });
 function parseConfig(env) {
-  return ConfigSchema.parse({
+  const parsed = ConfigSchema.parse({
     HUB_URL: env["HUB_URL"],
+    SHEPHERD_TOKEN: env["SHEPHERD_TOKEN"],
     TEAM_TOKEN: env["TEAM_TOKEN"],
     WORKSPACE: env["WORKSPACE"],
     REPO: env["REPO"],
@@ -43,6 +54,8 @@ function parseConfig(env) {
     HEARTBEAT_INTERVAL_SECONDS: env["HEARTBEAT_INTERVAL_SECONDS"],
     SHEPHERD_INBOX_DIR: env["SHEPHERD_INBOX_DIR"]
   });
+  const authToken = parsed.SHEPHERD_TOKEN ?? parsed.TEAM_TOKEN;
+  return { ...parsed, authToken };
 }
 function loadConfig(env = process.env) {
   try {
@@ -82,51 +95,63 @@ var HubRequestError = class extends Error {
 };
 function createHubClient({
   hubUrl,
-  teamToken,
+  token,
   timeoutMs = DEFAULT_TIMEOUT_MS
 }) {
   const baseUrl = hubUrl.replace(/\/$/, "");
-  return {
-    async post(path2, body) {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeoutMs);
-      let response;
+  async function request(method, path3, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const headers = {
+      "Authorization": `Bearer ${token}`
+    };
+    if (method === "POST") {
+      headers["Content-Type"] = "application/json";
+    }
+    let response;
+    try {
+      response = await fetch(`${baseUrl}${path3}`, {
+        method,
+        headers,
+        ...method === "POST" ? { body: JSON.stringify(body) } : {},
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      const message = err instanceof DOMException && err.name === "AbortError" ? `Hub request timed out after ${timeoutMs}ms (${path3})` : `Hub unreachable at ${baseUrl}${path3}: ${String(err)}`;
+      throw new HubUnreachable(message, err);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      let detail = "";
       try {
-        response = await fetch(`${baseUrl}${path2}`, {
-          method: "POST",
-          headers: {
-            "Authorization": `Bearer ${teamToken}`,
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify(body),
-          signal: controller.signal
-        });
-      } catch (err) {
-        clearTimeout(timer);
-        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);
-      }
-      if (!response.ok) {
-        let detail = "";
-        try {
-          const data = await response.json();
-          if (data && typeof data === "object" && "error" in data && typeof data.error === "string") {
-            detail = `: ${data.error}`;
-          }
-        } catch {
+        const data = await response.json();
+        if (data && typeof data === "object" && "error" in data && typeof data.error === "string") {
+          detail = `: ${data.error}`;
         }
-        throw new HubRequestError(
-          response.status,
-          `Hub returned HTTP ${response.status} for ${path2}${detail}`
-        );
+      } catch {
       }
-      return response.json();
+      throw new HubRequestError(
+        response.status,
+        `Hub returned HTTP ${response.status} for ${path3}${detail}`
+      );
+    }
+    return response.json();
+  }
+  return {
+    post(path3, body) {
+      return request("POST", path3, body);
+    },
+    get(path3) {
+      return request("GET", path3);
     }
   };
 }
 
+// src/tools.ts
+import { z as z3 } from "zod";
+
 // ../shared/dist/names.js
 var adjectives = [
   "Able",
@@ -499,10 +524,199 @@ var LeaveRequest = z2.object({
 var LeaveResponse = z2.object({
   ok: z2.literal(true)
 });
+var Role = z2.enum(["admin", "member"]);
+var WorkspaceSummary = z2.object({
+  id: z2.string(),
+  slug: z2.string(),
+  name: z2.string(),
+  role: Role
+});
+var CreateWorkspaceRequest = z2.object({
+  name: z2.string().min(1)
+});
+var ListWorkspacesResponse = z2.object({
+  workspaces: z2.array(WorkspaceSummary)
+});
+var MintTokenRequest = z2.object({
+  name: z2.string().min(1).optional()
+});
+var MintTokenResponse = z2.object({
+  // The raw shp_ token, shown once at creation and never returned again.
+  token: z2.string(),
+  id: z2.string()
+});
+var TokenSummary = z2.object({
+  id: z2.string(),
+  name: z2.string().nullable(),
+  // ISO timestamp string (see IsoTimestamp note above) or null when unused / not revoked.
+  lastUsedAt: IsoTimestamp.nullable(),
+  createdAt: IsoTimestamp,
+  revokedAt: IsoTimestamp.nullable()
+});
+var ListTokensResponse = z2.object({
+  tokens: z2.array(TokenSummary)
+});
+var CreateInviteRequest = z2.object({
+  expiresInDays: z2.number().int().positive().optional(),
+  // Omitted = unlimited, redeemable until explicitly revoked. Pass a positive
+  // integer to cap it instead.
+  maxUses: z2.number().int().positive().optional()
+});
+var InviteResponse = z2.object({
+  code: z2.string(),
+  // ISO timestamp string, or null when the invite never expires.
+  expiresAt: IsoTimestamp.nullable(),
+  // null = unlimited (redeemable until revoked).
+  maxUses: z2.number().int().positive().nullable(),
+  useCount: z2.number().int().nonnegative()
+});
+var InviteByEmailRequest = z2.object({
+  email: z2.string().email()
+});
+var InviteByEmailResponse = z2.object({
+  email: z2.string(),
+  sentAt: IsoTimestamp
+});
+var RedeemInviteResponse = z2.object({
+  // The workspace the caller just joined.
+  workspace: WorkspaceSummary
+});
+var MemberSummary = z2.object({
+  accountId: z2.string(),
+  displayName: z2.string().nullable(),
+  githubLogin: z2.string().nullable(),
+  avatarUrl: z2.string().nullable(),
+  role: Role
+});
+var ListMembersResponse = z2.object({
+  members: z2.array(MemberSummary)
+});
+var FeedbackType = z2.enum(["bug", "suggestion", "other"]);
+var FeedbackRequest = z2.object({
+  type: FeedbackType,
+  body: z2.string().trim().min(1).max(4e3)
+});
+var FeedbackResponse = z2.object({
+  ok: z2.literal(true),
+  // uuid PK (the feedback table, like workspaces, uses gen_random_uuid()).
+  id: z2.string()
+});
+
+// src/marker.ts
+import * as fs from "fs";
+import * as path from "path";
+var MARKER_FILENAME = ".shepherd";
+function findRepoRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (; ; ) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function markerPath(cwd) {
+  const root = findRepoRoot(cwd);
+  return root === null ? null : path.join(root, MARKER_FILENAME);
+}
+function readMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && typeof parsed.workspace === "string" && parsed.workspace.length > 0) {
+      return { workspace: parsed.workspace };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeMarker(cwd = process.cwd(), slug) {
+  const file = markerPath(cwd);
+  if (file === null) {
+    throw new Error("not inside a git repository \u2014 cannot write .shepherd marker");
+  }
+  fs.writeFileSync(file, JSON.stringify({ workspace: slug }) + "\n", "utf8");
+}
+function removeMarker(cwd = process.cwd()) {
+  const file = markerPath(cwd);
+  if (file === null) return;
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+  }
+}
+
+// src/declined.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir, tmpdir } from "os";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+function defaultDeclinedDir() {
+  let base = "";
+  try {
+    base = homedir();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir();
+  return join2(base, ".shepherd", "declined");
+}
+function declinedFilePath(repoRoot, dir = defaultDeclinedDir()) {
+  let normalized = resolve2(repoRoot);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join2(dir, hash);
+}
+function isDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  let raw;
+  try {
+    raw = readFileSync2(file, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.declinedAt === "string";
+  } catch {
+    return false;
+  }
+}
+function setDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  try {
+    mkdirSync(dirname2(file), { recursive: true });
+    const payload = JSON.stringify({ declinedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    writeFileSync2(file, payload + "\n", "utf8");
+  } catch (err) {
+    console.error(
+      `[shepherd] declined-state write failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function clearDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  if (!existsSync2(file)) return;
+  try {
+    rmSync2(file, { force: true });
+  } catch (err) {
+    console.error(
+      `[shepherd] declined-state clear failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
 
 // src/gitContext.ts
 import { execFileSync } from "child_process";
-import * as path from "path";
+import * as path2 from "path";
 var GIT_TIMEOUT_MS = 2e3;
 var MAX_COMMITS = 100;
 var MAX_PATHS_PER_COMMIT = 500;
@@ -550,7 +764,7 @@ function detectRepo(cwd = process.cwd()) {
   }
   const top = runGit(cwd, ["rev-parse", "--show-toplevel"]);
   if (top) {
-    const base = path.basename(top);
+    const base = path2.basename(top);
     if (base) return base;
   }
   return null;
@@ -745,37 +959,37 @@ async function buildChangeReport(cwd, config) {
 }
 
 // src/inbox.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import {
   appendFileSync,
-  mkdirSync,
-  readFileSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
   renameSync,
-  rmSync,
-  existsSync
+  rmSync as rmSync3,
+  existsSync as existsSync3
 } from "fs";
-import { homedir, tmpdir } from "os";
-import { dirname, join, resolve } from "path";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
 function defaultInboxDir() {
   let base = "";
   try {
-    base = homedir();
+    base = homedir2();
   } catch {
     base = "";
   }
-  if (!base) base = tmpdir();
-  return join(base, ".shepherd", "inbox");
+  if (!base) base = tmpdir2();
+  return join3(base, ".shepherd", "inbox");
 }
 function inboxFilePath(dir, cwd) {
-  let normalized = resolve(cwd);
+  let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
-  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(dir, `${hash}.jsonl`);
+  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join3(dir, `${hash}.jsonl`);
 }
 function appendAnnouncements(filePath, announcements) {
   if (!announcements || announcements.length === 0) return;
   try {
-    mkdirSync(dirname(filePath), { recursive: true });
+    mkdirSync2(dirname3(filePath), { recursive: true });
     const payload = announcements.map((a) => JSON.stringify(a)).join("\n") + "\n";
     appendFileSync(filePath, payload, "utf8");
   } catch {
@@ -785,17 +999,17 @@ function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync(tmp)) {
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+    if (existsSync3(tmp)) {
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync(filePath)) {
+    if (existsSync3(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
@@ -836,6 +1050,12 @@ function classifyJoinFailure(err) {
   }
   return "unknown";
 }
+function classifyActivateFailure(err) {
+  if (err instanceof HubRequestError && (err.status === 403 || err.status === 404)) {
+    return "workspaceRejected";
+  }
+  return classifyJoinFailure(err);
+}
 function joinFailureCause(reason) {
   switch (reason) {
     case "unreachable":
@@ -956,8 +1176,11 @@ function formatChangeRecords(records, cwd = process.cwd()) {
   if (lines.length === 0) return "";
   return "Unlanded changes touching your area (awareness only \u2014 these are not blockers):\n" + lines.join("\n");
 }
+function hubErrorDetail(err) {
+  return err instanceof HubUnreachable || err instanceof HubRequestError ? err.message : String(err);
+}
 function degradedResult(err) {
-  const detail = err instanceof HubUnreachable || err instanceof HubRequestError ? err.message : String(err);
+  const detail = hubErrorDetail(err);
   return {
     content: [
       {
@@ -969,37 +1192,89 @@ function degradedResult(err) {
 }
 function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
+  const markerCwd = deps.cwd ?? process.cwd();
+  const declinedDir = deps.declinedDir;
+  const repoRoot = findRepoRoot(markerCwd);
   let sessionId = null;
   let agentName = null;
-  let joinFailure = 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 isHosted = Boolean(config.SHEPHERD_TOKEN);
+  const selfHostMismatch = !isHosted && context.linked && config.WORKSPACE !== void 0 && config.WORKSPACE !== context.workspace;
+  let hostedWorkspaceRejected = false;
+  const dormant = !context.linked || selfHostMismatch;
+  let linked = context.linked;
+  let declined = context.declined;
+  function rememberDecline() {
+    if (repoRoot !== null) setDeclined(repoRoot, declinedDir);
+    declined = true;
   }
-  const joinInFlight = hubClient.post("/join", joinBody).then((raw) => {
-    const parsed = JoinResponse.safeParse(raw);
-    if (!parsed.success || !parsed.data.sessionId) {
-      joinFailure = "validation";
-      console.error(
-        "[shepherd] join failed (validation): hub returned a malformed join response (no usable sessionId)"
-      );
-      return;
+  function forgetDecline() {
+    if (repoRoot !== null) clearDeclined(repoRoot, declinedDir);
+    declined = false;
+  }
+  let joinFailure = null;
+  let joinInFlight = Promise.resolve();
+  async function activate(workspaceSlug) {
+    const joinBody = {
+      workspace: workspaceSlug,
+      repo: context.repo,
+      branch: context.branch,
+      human: context.human,
+      program: context.program
+    };
+    if (context.model !== void 0) {
+      joinBody.model = context.model;
     }
-    sessionId = parsed.data.sessionId;
-    agentName = parsed.data.agentName;
-    heartbeat.start(parsed.data.sessionId);
-  }).catch((err) => {
-    joinFailure = classifyJoinFailure(err);
+    const attempt = (async () => {
+      try {
+        const raw = await hubClient.post("/join", joinBody);
+        const parsed = JoinResponse.safeParse(raw);
+        if (!parsed.success || !parsed.data.sessionId) {
+          joinFailure = "validation";
+          console.error(
+            "[shepherd] join failed (validation): hub returned a malformed join response (no usable sessionId)"
+          );
+          return { ok: false, reason: "validation" };
+        }
+        const newSessionId = parsed.data.sessionId;
+        heartbeat.start(newSessionId);
+        sessionId = newSessionId;
+        agentName = parsed.data.agentName;
+        linked = true;
+        hostedWorkspaceRejected = false;
+        joinFailure = null;
+        return { ok: true };
+      } catch (err) {
+        const reason = classifyActivateFailure(err);
+        joinFailure = classifyJoinFailure(err);
+        if (reason === "workspaceRejected") {
+          hostedWorkspaceRejected = true;
+          console.error(
+            `[shepherd] This repo is linked to workspace "${workspaceSlug}" but your configured token is for a different workspace \u2014 coordination disabled.`
+          );
+        } else {
+          console.error(
+            `[shepherd] join failed (${reason}): ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        return { ok: false, reason };
+      }
+    })();
+    joinInFlight = attempt.then(() => void 0);
+    return attempt;
+  }
+  if (!context.linked) {
     console.error(
-      `[shepherd] join failed (${joinFailure}): ${err instanceof Error ? err.message : String(err)}`
+      context.declined ? "[shepherd] This repo was declined \u2014 staying uncoordinated. Run `link` to change your mind." : "[shepherd] This repo isn't linked to a Shepherd workspace \u2014 staying uncoordinated. Run `link` to choose one."
     );
-  });
+  } else if (selfHostMismatch) {
+    console.error(
+      `[shepherd] This repo is linked to workspace "${context.workspace}" but your configured token is for a different workspace \u2014 coordination disabled.`
+    );
+  }
+  if (!dormant) {
+    forgetDecline();
+    void activate(context.workspace);
+  }
   async function awaitJoin() {
     await joinInFlight;
   }
@@ -1013,6 +1288,27 @@ function registerTools(server, deps) {
       ]
     };
   }
+  function notLinked() {
+    const text = declined ? "Not coordinating this repo \u2014 you declined. Run `link` anytime to change your mind." : "This repo isn't linked to a Shepherd workspace \u2014 run `link` to choose one, or `decline` to stay uncoordinated and not be asked again.";
+    return { content: [{ type: "text", text }] };
+  }
+  function workspaceMismatch() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `This repo is linked to \`${context.workspace}\` but your configured token is for a different workspace \u2014 coordination disabled.`
+        }
+      ]
+    };
+  }
+  async function coordinationGate() {
+    await awaitJoin();
+    if (!linked) return notLinked();
+    if (selfHostMismatch || hostedWorkspaceRejected) return workspaceMismatch();
+    if (sessionId === null) return sessionNotReady();
+    return null;
+  }
   function withIdentity(body) {
     return agentName ? `You are ${agentName}.
 
@@ -1052,10 +1348,8 @@ ${section}` : body;
       inputSchema: WorkAgentInput.shape
     },
     async (args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const changeReport = await changeReportForBody();
         const body = { sessionId, ...args, ...changeReport ? { changeReport } : {} };
@@ -1091,10 +1385,8 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
       inputSchema: DoneAgentInput.shape
     },
     async (args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const body = { sessionId, ...args };
         const result = await hubClient.post("/done", body);
@@ -1125,10 +1417,8 @@ ${msgs}` : base }
       inputSchema: AnnounceAgentInput.shape
     },
     async (args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const body = { sessionId, ...args };
         const result = await hubClient.post("/announce", body);
@@ -1159,10 +1449,8 @@ ${msgs}` : base }
       inputSchema: SyncAgentInput.shape
     },
     async (_args) => {
-      await awaitJoin();
-      if (sessionId === null) {
-        return sessionNotReady();
-      }
+      const gated = await coordinationGate();
+      if (gated) return gated;
       try {
         const changeReport = await changeReportForBody();
         const body = { sessionId, ...changeReport ? { changeReport } : {} };
@@ -1183,6 +1471,118 @@ ${msgs}` : base }
       }
     }
   );
+  function advisory(text) {
+    return { content: [{ type: "text", text }] };
+  }
+  async function linkAndActivate(slug) {
+    writeMarker(markerCwd, slug);
+    forgetDecline();
+    linked = true;
+    const result = await activate(slug);
+    if (result.ok) {
+      return advisory(`Linked this repo to \`${slug}\` \u2014 coordinating in \`${slug}\` now.`);
+    }
+    return advisory(
+      `Linked this repo to \`${slug}\`, but coordination couldn't start just now (${joinFailureCause(joinFailure)}). It'll connect on your next tool call or session.`
+    );
+  }
+  server.registerTool(
+    "link",
+    {
+      title: "Link this repo to a Shepherd workspace",
+      description: "Opt this repository into Shepherd coordination by writing a committed `.shepherd` marker naming the workspace. Call with no argument: if you belong to exactly one workspace it is linked and coordination starts immediately; if you belong to several, the choices are listed for you to confirm one with the agent's user, then call `link` again with that `workspace`. You can only link to a workspace you are a member of. Takes effect immediately \u2014 no restart. Use `unlink` to opt out, or `decline` to stay uncoordinated without linking.",
+      inputSchema: z3.object({
+        workspace: z3.string().min(1).optional().describe("The workspace slug to link this repo to. Omit to auto-pick or list choices.")
+      }).shape
+    },
+    async (args) => {
+      const requested = args.workspace;
+      if (!isHosted) {
+        const allowed = config.WORKSPACE;
+        if (!allowed) {
+          return advisory(
+            "Self-host mode has no configured workspace (WORKSPACE is unset) \u2014 cannot link."
+          );
+        }
+        if (requested !== void 0 && requested !== allowed) {
+          return advisory(
+            `This self-host deployment only serves the workspace \`${allowed}\`; you asked for \`${requested}\`. Choose: ${allowed}`
+          );
+        }
+        return linkAndActivate(allowed);
+      }
+      let slugs;
+      try {
+        const res = await hubClient.get("/workspaces");
+        slugs = (res.workspaces ?? []).map((w) => w.slug).filter((s) => typeof s === "string" && s.length > 0);
+      } catch (err) {
+        const detail = hubErrorDetail(err);
+        return advisory(
+          `Couldn't reach the coordination hub to list your workspaces \u2014 link not changed. ${detail}`
+        );
+      }
+      if (slugs.length === 0) {
+        return advisory(
+          "Your account isn't a member of any workspaces yet \u2014 nothing to link to. Create one in the Shepherd dashboard, then run `link` again."
+        );
+      }
+      if (requested === void 0) {
+        if (slugs.length === 1) {
+          return linkAndActivate(slugs[0]);
+        }
+        return advisory(
+          "You're a member of multiple Shepherd workspaces:\n" + slugs.map((s) => `  - ${s}`).join("\n") + "\n\nAsk the user which one to use for this repo, then call `link` again with it as the `workspace` argument."
+        );
+      }
+      if (!slugs.includes(requested)) {
+        return advisory(
+          `You're not a member of \`${requested}\`; choose one of: ${slugs.join(", ")}`
+        );
+      }
+      return linkAndActivate(requested);
+    }
+  );
+  server.registerTool(
+    "unlink",
+    {
+      title: "Unlink this repo from its Shepherd workspace",
+      description: "Opt this repository OUT of Shepherd coordination by removing its `.shepherd` marker. Also records a local decline so you aren't re-prompted to link on the next session. The repo stays uncoordinated (no claims, no presence) until you `link` it again.",
+      inputSchema: z3.object({}).shape
+    },
+    async () => {
+      removeMarker(markerCwd);
+      rememberDecline();
+      linked = false;
+      if (sessionId !== null) {
+        heartbeat.stop();
+        await leave();
+        sessionId = null;
+        agentName = null;
+      }
+      return advisory(
+        "Unlinked \u2014 this repo will stay uncoordinated and won't ask again. Run `link` to re-enable."
+      );
+    }
+  );
+  server.registerTool(
+    "decline",
+    {
+      title: "Decline Shepherd coordination for this repo",
+      description: "Opt out of Shepherd for this repo WITHOUT linking: records a local, per-user 'don't ask again' so this repo stays uncoordinated and you aren't prompted to link on future sessions. This is local only \u2014 it is never committed, so a teammate on the same repo can still link it. Run `link` anytime to change your mind.",
+      inputSchema: z3.object({}).shape
+    },
+    async () => {
+      if (linked) {
+        return advisory(
+          `Already coordinating \`${context.workspace}\` \u2014 run \`unlink\` to stop coordinating this repo.`
+        );
+      }
+      rememberDecline();
+      return advisory(
+        "Won't coordinate this repo or ask again. Run `link` anytime to change your mind."
+      );
+    }
+  );
   async function leave() {
     try {
       await joinInFlight;
@@ -1198,23 +1598,23 @@ ${msgs}` : base }
 }
 
 // src/identityCache.ts
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
-import { dirname as dirname2, join as join2 } from "path";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { homedir as homedir3, tmpdir as tmpdir3 } from "os";
+import { dirname as dirname4, join as join4 } from "path";
 function defaultIdentityCachePath() {
   let base = "";
   try {
-    base = homedir2();
+    base = homedir3();
   } catch {
     base = "";
   }
-  if (!base) base = tmpdir2();
-  return join2(base, ".shepherd", "identity.json");
+  if (!base) base = tmpdir3();
+  return join4(base, ".shepherd", "identity.json");
 }
 function readCachedHuman(filePath = defaultIdentityCachePath()) {
   let raw;
   try {
-    raw = readFileSync2(filePath, "utf8");
+    raw = readFileSync4(filePath, "utf8");
   } catch {
     return null;
   }
@@ -1229,9 +1629,9 @@ function readCachedHuman(filePath = defaultIdentityCachePath()) {
 function writeCachedHuman(human, filePath = defaultIdentityCachePath()) {
   if (typeof human !== "string" || human.trim().length === 0) return;
   try {
-    mkdirSync2(dirname2(filePath), { recursive: true });
+    mkdirSync3(dirname4(filePath), { recursive: true });
     const payload = JSON.stringify({ human });
-    writeFileSync(filePath, payload + "\n", "utf8");
+    writeFileSync3(filePath, payload + "\n", "utf8");
   } catch {
   }
 }
@@ -1241,6 +1641,9 @@ var defaultDeps = {
   detectRepo,
   detectBranch,
   detectHuman,
+  readMarker,
+  findRepoRoot,
+  isDeclined: (repoRoot) => isDeclined(repoRoot),
   readCachedHuman,
   writeCachedHuman
 };
@@ -1253,8 +1656,13 @@ async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
   const human = resolveHuman(config, cwd, deps);
   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 };
+  const marker = deps.readMarker(cwd);
+  const linked = marker !== null;
+  const workspace = marker?.workspace ?? config.WORKSPACE ?? DEFAULT_WORKSPACE;
+  const repoRoot = deps.findRepoRoot(cwd);
+  const declined = repoRoot !== null ? deps.isDeclined(repoRoot) : false;
+  const linkState = linked ? "linked" : declined ? "declined" : "unanswered";
+  return { workspace, repo, branch, human, program, model, linked, declined, linkState };
 }
 function resolveHuman(config, cwd, deps) {
   if (config.HUMAN) return config.HUMAN;
@@ -1326,9 +1734,11 @@ function createHeartbeat({
 }
 
 // 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.
+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.
+
+On your first coordination-relevant action in a repo, if it isn't linked and hasn't been declined, call \`link\` with no argument: it auto-starts coordination if you belong to exactly one workspace, or lists your workspaces \u2014 ask the user "Coordinate this repo with Shepherd? Which workspace?" then call \`link <workspace>\` with their answer, or \`decline\` if they say no. Ask at most once per repo: once linked or declined, do not ask again \u2014 the marker is committed and teammates inherit it, so coordination is automatic from then on.
 
-Follow this procedure on every session, proactively and without being asked:
+Once linked, 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.
 
@@ -1347,7 +1757,7 @@ Commit work-in-progress as you go rather than sitting on a large dirty tree: com
 // src/index.ts
 async function main() {
   const config = loadConfig();
-  const hubClient = createHubClient({ hubUrl: config.HUB_URL, teamToken: config.TEAM_TOKEN });
+  const hubClient = createHubClient({ hubUrl: config.HUB_URL, token: config.authToken });
   const context = await resolveContext(config);
   const inboxDir = config.SHEPHERD_INBOX_DIR ?? defaultInboxDir();
   const inboxFile = inboxFilePath(inboxDir, process.cwd());