@korso/shepherd 0.4.5 → 0.5.0

package/README.md

@@ -1,336 +1,336 @@
-# @korso/shepherd — Shepherd MCP Server
-
-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.
-
----
-
-## CRITICAL: WORKSPACE must match the hub exactly
-
-> **`WORKSPACE` defaults to `default`. If you override it, the value must equal the hub's `ALLOWED_WORKSPACE` env var exactly.**
-
-The server fires an automatic `join` call to the hub at startup. If the workspace it sends does not match the hub's `ALLOWED_WORKSPACE`, that call returns HTTP 400 and coordination degrades: every tool reports "session not ready … proceeding uncoordinated" instead of a landscape. The safe default is to **leave `WORKSPACE` unset** so it resolves to `default` — only set it when a maintainer points you at a different workspace. If your agent never sees teammates, check `WORKSPACE` (and `TEAM_TOKEN`) first.
-
----
-
-## Install
-
-The server is published to npm and runs via `npx` — no clone or build required
-(Node 18+):
-
-```sh
-npx -y @korso/shepherd
-```
-
-You won't normally run that by hand; you put it in your MCP client config (below)
-with the required env vars. `npx` caches the package, so startup is fast after the
-first fetch, and `@korso/shepherd@latest` picks up updates automatically.
-
-> Hacking on the server itself? See **[Develop from source](#develop-from-source)**
-> at the bottom.
-
----
-
-## 2. Environment variables
-
-**Only two are required:**
-
-| Variable | Description | Example |
-|---|---|---|
-| `HUB_URL` | Base URL of the deployed hub | `https://shepherd.example.com` |
-| `TEAM_TOKEN` | Shared bearer token accepted by the hub | `tok_abc123` |
-
-Missing either causes an immediate startup failure with a clear error on stderr
-listing which vars are absent. (No other var triggers this.)
-
-**Everything else is optional** — each identity field is resolved at startup as
-**env var → git detection → fallback**, so a plain `npx -y @korso/shepherd` with
-just the two required vars produces a valid, fully-identified session. Set an
-override only to replace what's detected:
-
-| Variable | If omitted | Example |
-|---|---|---|
-| `WORKSPACE` | defaults to `default` (**must match hub's `ALLOWED_WORKSPACE` if overridden**) | `shepherd` |
-| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korsoai/shepherd` |
-| `BRANCH` | `git rev-parse --abbrev-ref HEAD`, else `HEAD` | `main` |
-| `BASE_BRANCH` | `origin/HEAD`, else `origin/main` / `origin/master` (used for the change-awareness heads-up) | `origin/main` |
-| `HUMAN` | git `user.name`, else local-part of `user.email`, else this device's **cached** last-detected name, else a generated name | `daichi` |
-| `PROGRAM` | defaults to `claude-code` | `codex` |
-| `MODEL` | omitted — **never auto-detected**, so set it if you want it shown | `claude-sonnet-4-6` |
-| `HEARTBEAT_INTERVAL_SECONDS` | defaults to `60` | `30` |
-| `SHEPHERD_INBOX_DIR` | defaults to `~/.shepherd/inbox`. Override only to relocate the **announcement-push** inbox (see below); the background heartbeat writes incoming announcements here. If you set it, point your client hook/extension at the **same** dir | `~/.shepherd/inbox` |
-
-**Device-identity cache.** Whenever `HUMAN` is unset and git **does** detect a
-name, that name is cached for your OS user at `~/.shepherd/identity.json`. A
-later launch from a directory where git can't be read (e.g. a multi-repo
-workspace root) then reuses the cached name instead of inventing a fresh random
-one each time. The cache refreshes automatically the next time git reports a
-different name, and an explicit `HUMAN` override always wins and never touches
-the cache. It is best-effort: if the file can't be read or written, resolution
-just falls back to a generated name.
-
----
-
-## Announcement push (on by default)
-
-Announcements reach an agent **without it having to ask**. The background
-heartbeat pulls any pending announcements from the hub every beat and stages them
-in a local **inbox file** (per working directory, under `SHEPHERD_INBOX_DIR`,
-default `~/.shepherd/inbox`). That file is then drained by two paths:
-
-1. **Universal drainer (always on, every client).** Whenever the agent calls any
-   Shepherd tool (`work`/`sync`/`done`/`announce`), the result also includes
-   anything sitting in the inbox. So even with no hook configured, no announcement
-   is ever lost — the worst case is the old behaviour (delivered on the next
-   Shepherd tool call), never silent drops.
-2. **Passive client hook/extension (optional, per client).** To get announcements
-   **without** waiting for a Shepherd tool call — surfaced on the agent's next
-   action of any kind — wire up your client's hook below. This is the
-   "a subagent finished" style of notification.
-
-Both paths read the **same** inbox file and de-duplicate by announcement id, so
-running both is safe (the hub hands each announcement to exactly one drain; the
-merge is just defensive). It's cheap: a **local file read — no network** (the
-heartbeat already did the fetch), and it only adds to the model's context when
-something is actually waiting.
-
-It delivers to an agent **while it's active**; an idle agent picks messages up the
-moment it next does anything. (Waking a fully-idle agent is out of scope — for
-Claude Code that needs Channels; Codex/Pi have no equivalent.)
-
-### Claude Code — `PreToolUse` hook
-
-`PreToolUse` fires before every tool, giving the most frequent passive delivery.
-The hook needs no arguments — it resolves the same default inbox dir the server
-uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
-
-```json
-{
-  "mcpServers": {
-    "shepherd": {
-      "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
-      "env": {
-        "HUB_URL": "https://shepherd.example.com",
-        "TEAM_TOKEN": "tok_abc123"
-      }
-    }
-  },
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          { "type": "command", "command": "npx -y -p @korso/shepherd shepherd-inbox-hook" }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Codex — `UserPromptSubmit` hook
-
-Codex uses the **same** hook contract as Claude Code (JSON on stdin, a
-`hookSpecificOutput.additionalContext` reply), so the **same bin** serves it. Use
-`UserPromptSubmit` — Codex's `PreToolUse` only fires for Bash, not `apply_patch`
-or MCP calls. Hooks must be enabled with `features.hooks = true`. In
-`~/.codex/config.toml`:
-
-```toml
-[features]
-hooks = true
-
-[[hooks.UserPromptSubmit]]
-command = ["npx", "-y", "-p", "@korso/shepherd", "shepherd-inbox-hook"]
-# On Windows use command_windows instead:
-# command_windows = ["cmd", "/c", "npx -y -p @korso/shepherd shepherd-inbox-hook"]
-```
-
-### Pi — extension
-
-Pi has no stdin/stdout hook; it loads in-process extensions. Ship the bundled
-extension into Pi's extensions dir:
-
-```sh
-# global, applies everywhere:
-mkdir -p ~/.pi/agent/extensions
-cp "$(npm root -g)/@korso/shepherd/dist/inboxExtension.js" ~/.pi/agent/extensions/shepherd-inbox.js
-# …or per-project: copy into .pi/extensions/ in the repo root.
-```
-
-It runs on every user turn (`before_agent_start`), drains the same inbox, and
-injects pending announcements. (Or load it ad hoc with
-`pi -e /abs/path/to/dist/inboxExtension.js`.)
-
-### Notes
-
-Every path is **fail-open**: a missing dir, unreachable hub, or any error means
-nothing is surfaced and the tool call / turn proceeds normally — coordination
-never blocks the agent. The inbox is keyed per working directory; two sessions in
-the exact same directory share it (a benign edge — they're the same repo). If you
-override `SHEPHERD_INBOX_DIR` on the server, set it on the hook/extension to the
-same value (the Claude/Codex bin and the Pi extension both read
-`SHEPHERD_INBOX_DIR`, or you can pass the dir as the first CLI arg to the bin).
-
----
-
-## 3. MCP client configuration
-
-### Claude Code
-
-> **Do not use `~/.claude/mcp.json` — Claude Code does not read it** (a config
-> there loads silently into nothing). Use `claude mcp add` (user scope, applies
-> everywhere) or a project-root `.mcp.json`. Confirm with `claude mcp list`,
-> which should show `shepherd … ✔ Connected`.
-
-Recommended — register once at user scope. Written as a **single line** so it
-pastes cleanly into PowerShell, cmd, bash, and zsh (on PowerShell the bash `\`
-line-continuation does not work). Minimal: just the two required vars (identity
-is auto-detected from git):
-
-```powershell
-claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y @korso/shepherd
-```
-
-Add any optional overrides from §2 with extra `-e` flags (e.g. `-e MODEL=claude-sonnet-4-6 -e HUMAN=daichi`).
-
-Alternative — a `.mcp.json` at the **root of the repo you're working in**
-(optional overrides shown commented-style; drop the ones you don't need):
-
-```json
-{
-  "mcpServers": {
-    "shepherd": {
-      "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
-      "env": {
-        "HUB_URL": "https://shepherd.example.com",
-        "TEAM_TOKEN": "tok_abc123",
-        "MODEL": "claude-sonnet-4-6"
-      }
-    }
-  }
-}
-```
-
-> Windows note: the server is a thin stdio client to the Linux-hosted hub, and
-> `npx` works the same on every OS — no file paths to escape. The hub itself runs
-> on Linux (Postgres), so the Windows-native durability concerns from the spike
-> don't apply to clients.
-
-### Codex (`~/.codex/config.toml`)
-
-Codex uses the same MCP stdio protocol but configures it in **TOML**, not JSON —
-at `~/.codex/config.toml` (global) or `.codex/config.toml` in a trusted project.
-The table is `mcp_servers` with an **underscore** (`mcp-servers`/`mcpServers` are
-silently ignored). Either run `codex mcp add`:
-
-```sh
-codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y @korso/shepherd
-```
-
-…or add the table directly:
-
-```toml
-[mcp_servers.shepherd]
-command = "npx"
-args = ["-y", "@korso/shepherd"]
-env = { HUB_URL = "https://shepherd.example.com", TEAM_TOKEN = "tok_abc123", PROGRAM = "codex", MODEL = "o4-mini" }
-```
-
-### Pi (`~/.pi/agent/mcp.json` or `.pi/mcp.json`)
-
-Pi uses a JSON `mcpServers` block (project config overrides global):
-
-```json
-{
-  "mcpServers": {
-    "shepherd": {
-      "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
-      "env": {
-        "HUB_URL": "https://shepherd.example.com",
-        "TEAM_TOKEN": "tok_abc123",
-        "PROGRAM": "pi"
-      }
-    }
-  }
-}
-```
-
----
-
-## 4. Verify the server starts (quick smoke test)
-
-Run with the two required vars set to confirm it connects and idles on stdin.
-PowerShell (set env vars, then run):
-
-```powershell
-$env:HUB_URL = "https://shepherd.example.com"
-$env:TEAM_TOKEN = "tok_abc123"
-npx -y @korso/shepherd
-```
-
-bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y @korso/shepherd`
-
-No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
-
-**Missing env vars:** if you omit `HUB_URL` or `TEAM_TOKEN`, you will see:
-
-```
-[shepherd] Configuration error — missing or invalid env vars:
-  HUB_URL: HUB_URL is required
-  TEAM_TOKEN: TEAM_TOKEN is required
-```
-
-and the process exits 1 immediately. This is by design. The optional identity
-vars never cause this — they fall back to git detection / defaults.
-
-**Wrong WORKSPACE:** if you override `WORKSPACE` to a value the hub doesn't allow, the server starts and connects but the startup auto-join is rejected (400), so every tool call (`work`, `sync`, etc.) reports "session not ready … proceeding uncoordinated". Either leave `WORKSPACE` unset (resolves to `default`) or set it to exactly match the hub's `ALLOWED_WORKSPACE`, then restart.
-
----
-
-## Develop from source
-
-Only needed if you're changing the MCP server itself. Clone the monorepo and
-point your client at a local build instead of npx:
-
-```sh
-git clone https://github.com/Korsoai/shepherd.git
-cd shepherd
-npm install
-npm run build         # tsc -b — compiles the workspace for dev + tests
-```
-
-For an exact preview of the published artifact (a single self-contained bundle
-with `@shepherd/shared` inlined), build the package directly:
-
-```sh
-npm run build --workspace=@korso/shepherd   # runs tsup → packages/mcp-server/dist/index.js
-```
-
-Then use `node /absolute/path/to/shepherd/packages/mcp-server/dist/index.js` as
-the `command` in your MCP config (Windows: escape backslashes in JSON).
-
-### Publishing a new version
-
-```sh
-# bump "version" in packages/mcp-server/package.json, then:
-npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatically
-```
-
-`publishConfig.access` is `public`, so the scoped package publishes publicly.
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `Configuration error — missing or invalid env vars` | `HUB_URL` or `TEAM_TOKEN` is absent (only these two are required) | Add the missing var(s) to your client's `env` block |
-| Tools report "session not ready … proceeding uncoordinated" | Startup auto-join rejected — usually a stale `TEAM_TOKEN`, or a `WORKSPACE` override the hub doesn't allow | Re-check `TEAM_TOKEN`; leave `WORKSPACE` unset (→ `default`) or match the hub's `ALLOWED_WORKSPACE`; restart |
-| Agent shows up under a surprising name/repo/branch | Identity auto-detected from git, or reused from the device-identity cache when launched outside a git work tree | Override with `HUMAN`/`REPO`/`BRANCH`/`MODEL` env vars (§2); a correct git `user.name` on the next in-repo launch refreshes the cache, or delete `~/.shepherd/identity.json` to clear it |
-| `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) |
+# @korso/shepherd — Shepherd MCP Server
+
+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.
+
+---
+
+## CRITICAL: WORKSPACE must match the hub exactly
+
+> **`WORKSPACE` defaults to `default`. If you override it, the value must equal the hub's `ALLOWED_WORKSPACE` env var exactly.**
+
+The server fires an automatic `join` call to the hub at startup. If the workspace it sends does not match the hub's `ALLOWED_WORKSPACE`, that call returns HTTP 400 and coordination degrades: every tool reports "session not ready … proceeding uncoordinated" instead of a landscape. The safe default is to **leave `WORKSPACE` unset** so it resolves to `default` — only set it when a maintainer points you at a different workspace. If your agent never sees teammates, check `WORKSPACE` (and `TEAM_TOKEN`) first.
+
+---
+
+## Install
+
+The server is published to npm and runs via `npx` — no clone or build required
+(Node 18+):
+
+```sh
+npx -y @korso/shepherd
+```
+
+You won't normally run that by hand; you put it in your MCP client config (below)
+with the required env vars. `npx` caches the package, so startup is fast after the
+first fetch, and `@korso/shepherd@latest` picks up updates automatically.
+
+> Hacking on the server itself? See **[Develop from source](#develop-from-source)**
+> at the bottom.
+
+---
+
+## 2. Environment variables
+
+**Only two are required:**
+
+| Variable | Description | Example |
+|---|---|---|
+| `HUB_URL` | Base URL of the deployed hub | `https://shepherd.example.com` |
+| `TEAM_TOKEN` | Shared bearer token accepted by the hub | `tok_abc123` |
+
+Missing either causes an immediate startup failure with a clear error on stderr
+listing which vars are absent. (No other var triggers this.)
+
+**Everything else is optional** — each identity field is resolved at startup as
+**env var → git detection → fallback**, so a plain `npx -y @korso/shepherd` with
+just the two required vars produces a valid, fully-identified session. Set an
+override only to replace what's detected:
+
+| Variable | If omitted | Example |
+|---|---|---|
+| `WORKSPACE` | defaults to `default` (**must match hub's `ALLOWED_WORKSPACE` if overridden**) | `shepherd` |
+| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korsoai/shepherd` |
+| `BRANCH` | `git rev-parse --abbrev-ref HEAD`, else `HEAD` | `main` |
+| `BASE_BRANCH` | `origin/HEAD`, else `origin/main` / `origin/master` (used for the change-awareness heads-up) | `origin/main` |
+| `HUMAN` | git `user.name`, else local-part of `user.email`, else this device's **cached** last-detected name, else a generated name | `daichi` |
+| `PROGRAM` | defaults to `claude-code` | `codex` |
+| `MODEL` | omitted — **never auto-detected**, so set it if you want it shown | `claude-sonnet-4-6` |
+| `HEARTBEAT_INTERVAL_SECONDS` | defaults to `60` | `30` |
+| `SHEPHERD_INBOX_DIR` | defaults to `~/.shepherd/inbox`. Override only to relocate the **announcement-push** inbox (see below); the background heartbeat writes incoming announcements here. If you set it, point your client hook/extension at the **same** dir | `~/.shepherd/inbox` |
+
+**Device-identity cache.** Whenever `HUMAN` is unset and git **does** detect a
+name, that name is cached for your OS user at `~/.shepherd/identity.json`. A
+later launch from a directory where git can't be read (e.g. a multi-repo
+workspace root) then reuses the cached name instead of inventing a fresh random
+one each time. The cache refreshes automatically the next time git reports a
+different name, and an explicit `HUMAN` override always wins and never touches
+the cache. It is best-effort: if the file can't be read or written, resolution
+just falls back to a generated name.
+
+---
+
+## Announcement push (on by default)
+
+Announcements reach an agent **without it having to ask**. The background
+heartbeat pulls any pending announcements from the hub every beat and stages them
+in a local **inbox file** (per working directory, under `SHEPHERD_INBOX_DIR`,
+default `~/.shepherd/inbox`). That file is then drained by two paths:
+
+1. **Universal drainer (always on, every client).** Whenever the agent calls any
+   Shepherd tool (`work`/`sync`/`done`/`announce`), the result also includes
+   anything sitting in the inbox. So even with no hook configured, no announcement
+   is ever lost — the worst case is the old behaviour (delivered on the next
+   Shepherd tool call), never silent drops.
+2. **Passive client hook/extension (optional, per client).** To get announcements
+   **without** waiting for a Shepherd tool call — surfaced on the agent's next
+   action of any kind — wire up your client's hook below. This is the
+   "a subagent finished" style of notification.
+
+Both paths read the **same** inbox file and de-duplicate by announcement id, so
+running both is safe (the hub hands each announcement to exactly one drain; the
+merge is just defensive). It's cheap: a **local file read — no network** (the
+heartbeat already did the fetch), and it only adds to the model's context when
+something is actually waiting.
+
+It delivers to an agent **while it's active**; an idle agent picks messages up the
+moment it next does anything. (Waking a fully-idle agent is out of scope — for
+Claude Code that needs Channels; Codex/Pi have no equivalent.)
+
+### Claude Code — `PreToolUse` hook
+
+`PreToolUse` fires before every tool, giving the most frequent passive delivery.
+The hook needs no arguments — it resolves the same default inbox dir the server
+uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123"
+      }
+    }
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "npx -y -p @korso/shepherd shepherd-inbox-hook" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Codex — `UserPromptSubmit` hook
+
+Codex uses the **same** hook contract as Claude Code (JSON on stdin, a
+`hookSpecificOutput.additionalContext` reply), so the **same bin** serves it. Use
+`UserPromptSubmit` — Codex's `PreToolUse` only fires for Bash, not `apply_patch`
+or MCP calls. Hooks must be enabled with `features.hooks = true`. In
+`~/.codex/config.toml`:
+
+```toml
+[features]
+hooks = true
+
+[[hooks.UserPromptSubmit]]
+command = ["npx", "-y", "-p", "@korso/shepherd", "shepherd-inbox-hook"]
+# On Windows use command_windows instead:
+# command_windows = ["cmd", "/c", "npx -y -p @korso/shepherd shepherd-inbox-hook"]
+```
+
+### Pi — extension
+
+Pi has no stdin/stdout hook; it loads in-process extensions. Ship the bundled
+extension into Pi's extensions dir:
+
+```sh
+# global, applies everywhere:
+mkdir -p ~/.pi/agent/extensions
+cp "$(npm root -g)/@korso/shepherd/dist/inboxExtension.js" ~/.pi/agent/extensions/shepherd-inbox.js
+# …or per-project: copy into .pi/extensions/ in the repo root.
+```
+
+It runs on every user turn (`before_agent_start`), drains the same inbox, and
+injects pending announcements. (Or load it ad hoc with
+`pi -e /abs/path/to/dist/inboxExtension.js`.)
+
+### Notes
+
+Every path is **fail-open**: a missing dir, unreachable hub, or any error means
+nothing is surfaced and the tool call / turn proceeds normally — coordination
+never blocks the agent. The inbox is keyed per working directory; two sessions in
+the exact same directory share it (a benign edge — they're the same repo). If you
+override `SHEPHERD_INBOX_DIR` on the server, set it on the hook/extension to the
+same value (the Claude/Codex bin and the Pi extension both read
+`SHEPHERD_INBOX_DIR`, or you can pass the dir as the first CLI arg to the bin).
+
+---
+
+## 3. MCP client configuration
+
+### Claude Code
+
+> **Do not use `~/.claude/mcp.json` — Claude Code does not read it** (a config
+> there loads silently into nothing). Use `claude mcp add` (user scope, applies
+> everywhere) or a project-root `.mcp.json`. Confirm with `claude mcp list`,
+> which should show `shepherd … ✔ Connected`.
+
+Recommended — register once at user scope. Written as a **single line** so it
+pastes cleanly into PowerShell, cmd, bash, and zsh (on PowerShell the bash `\`
+line-continuation does not work). Minimal: just the two required vars (identity
+is auto-detected from git):
+
+```powershell
+claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y @korso/shepherd
+```
+
+Add any optional overrides from §2 with extra `-e` flags (e.g. `-e MODEL=claude-sonnet-4-6 -e HUMAN=daichi`).
+
+Alternative — a `.mcp.json` at the **root of the repo you're working in**
+(optional overrides shown commented-style; drop the ones you don't need):
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "MODEL": "claude-sonnet-4-6"
+      }
+    }
+  }
+}
+```
+
+> Windows note: the server is a thin stdio client to the Linux-hosted hub, and
+> `npx` works the same on every OS — no file paths to escape. The hub itself runs
+> on Linux (Postgres), so the Windows-native durability concerns from the spike
+> don't apply to clients.
+
+### Codex (`~/.codex/config.toml`)
+
+Codex uses the same MCP stdio protocol but configures it in **TOML**, not JSON —
+at `~/.codex/config.toml` (global) or `.codex/config.toml` in a trusted project.
+The table is `mcp_servers` with an **underscore** (`mcp-servers`/`mcpServers` are
+silently ignored). Either run `codex mcp add`:
+
+```sh
+codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y @korso/shepherd
+```
+
+…or add the table directly:
+
+```toml
+[mcp_servers.shepherd]
+command = "npx"
+args = ["-y", "@korso/shepherd"]
+env = { HUB_URL = "https://shepherd.example.com", TEAM_TOKEN = "tok_abc123", PROGRAM = "codex", MODEL = "o4-mini" }
+```
+
+### Pi (`~/.pi/agent/mcp.json` or `.pi/mcp.json`)
+
+Pi uses a JSON `mcpServers` block (project config overrides global):
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "PROGRAM": "pi"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 4. Verify the server starts (quick smoke test)
+
+Run with the two required vars set to confirm it connects and idles on stdin.
+PowerShell (set env vars, then run):
+
+```powershell
+$env:HUB_URL = "https://shepherd.example.com"
+$env:TEAM_TOKEN = "tok_abc123"
+npx -y @korso/shepherd
+```
+
+bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y @korso/shepherd`
+
+No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
+
+**Missing env vars:** if you omit `HUB_URL` or `TEAM_TOKEN`, you will see:
+
+```
+[shepherd] Configuration error — missing or invalid env vars:
+  HUB_URL: HUB_URL is required
+  TEAM_TOKEN: TEAM_TOKEN is required
+```
+
+and the process exits 1 immediately. This is by design. The optional identity
+vars never cause this — they fall back to git detection / defaults.
+
+**Wrong WORKSPACE:** if you override `WORKSPACE` to a value the hub doesn't allow, the server starts and connects but the startup auto-join is rejected (400), so every tool call (`work`, `sync`, etc.) reports "session not ready … proceeding uncoordinated". Either leave `WORKSPACE` unset (resolves to `default`) or set it to exactly match the hub's `ALLOWED_WORKSPACE`, then restart.
+
+---
+
+## Develop from source
+
+Only needed if you're changing the MCP server itself. Clone the monorepo and
+point your client at a local build instead of npx:
+
+```sh
+git clone https://github.com/Korsoai/shepherd.git
+cd shepherd
+npm install
+npm run build         # tsc -b — compiles the workspace for dev + tests
+```
+
+For an exact preview of the published artifact (a single self-contained bundle
+with `@shepherd/shared` inlined), build the package directly:
+
+```sh
+npm run build --workspace=@korso/shepherd   # runs tsup → packages/mcp-server/dist/index.js
+```
+
+Then use `node /absolute/path/to/shepherd/packages/mcp-server/dist/index.js` as
+the `command` in your MCP config (Windows: escape backslashes in JSON).
+
+### Publishing a new version
+
+```sh
+# bump "version" in packages/mcp-server/package.json, then:
+npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatically
+```
+
+`publishConfig.access` is `public`, so the scoped package publishes publicly.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Configuration error — missing or invalid env vars` | `HUB_URL` or `TEAM_TOKEN` is absent (only these two are required) | Add the missing var(s) to your client's `env` block |
+| Tools report "session not ready … proceeding uncoordinated" | Startup auto-join rejected — usually a stale `TEAM_TOKEN`, or a `WORKSPACE` override the hub doesn't allow | Re-check `TEAM_TOKEN`; leave `WORKSPACE` unset (→ `default`) or match the hub's `ALLOWED_WORKSPACE`; restart |
+| Agent shows up under a surprising name/repo/branch | Identity auto-detected from git, or reused from the device-identity cache when launched outside a git work tree | Override with `HUMAN`/`REPO`/`BRANCH`/`MODEL` env vars (§2); a correct git `user.name` on the next in-repo launch refreshes the cache, or delete `~/.shepherd/identity.json` to clear it |
+| `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,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,119 @@ 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(),
+  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(),
+  maxUses: z2.number().int().positive(),
+  useCount: z2.number().int().nonnegative()
+});
+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)
+});
+
+// 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/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 +684,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;
@@ -749,13 +883,13 @@ import { createHash } from "crypto";
 import {
   appendFileSync,
   mkdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   renameSync,
-  rmSync,
-  existsSync
+  rmSync as rmSync2,
+  existsSync as existsSync2
 } from "fs";
 import { homedir, tmpdir } from "os";
-import { dirname, join, resolve } from "path";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 function defaultInboxDir() {
   let base = "";
   try {
@@ -764,18 +898,18 @@ function defaultInboxDir() {
     base = "";
   }
   if (!base) base = tmpdir();
-  return join(base, ".shepherd", "inbox");
+  return join2(base, ".shepherd", "inbox");
 }
 function inboxFilePath(dir, cwd) {
-  let normalized = resolve(cwd);
+  let normalized = resolve2(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
   const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(dir, `${hash}.jsonl`);
+  return join2(dir, `${hash}.jsonl`);
 }
 function appendAnnouncements(filePath, announcements) {
   if (!announcements || announcements.length === 0) return;
   try {
-    mkdirSync(dirname(filePath), { recursive: true });
+    mkdirSync(dirname2(filePath), { recursive: true });
     const payload = announcements.map((a) => JSON.stringify(a)).join("\n") + "\n";
     appendFileSync(filePath, payload, "utf8");
   } catch {
@@ -785,17 +919,17 @@ function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync(tmp)) {
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+    if (existsSync2(tmp)) {
+      raw += readFileSync2(tmp, "utf8");
+      rmSync2(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync(filePath)) {
+    if (existsSync2(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync(tmp, "utf8");
-      rmSync(tmp, { force: true });
+      raw += readFileSync2(tmp, "utf8");
+      rmSync2(tmp, { force: true });
     }
   } catch {
   }
@@ -956,8 +1090,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,8 +1106,13 @@ function degradedResult(err) {
 }
 function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
+  const markerCwd = deps.cwd ?? process.cwd();
   let sessionId = null;
   let agentName = null;
+  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 joinFailure = null;
   const joinBody = {
     workspace: context.workspace,
@@ -982,7 +1124,16 @@ function registerTools(server, deps) {
   if (context.model !== void 0) {
     joinBody.model = context.model;
   }
-  const joinInFlight = hubClient.post("/join", joinBody).then((raw) => {
+  if (!context.linked) {
+    console.error(
+      "[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.`
+    );
+  }
+  const joinInFlight = dormant ? Promise.resolve() : hubClient.post("/join", joinBody).then((raw) => {
     const parsed = JoinResponse.safeParse(raw);
     if (!parsed.success || !parsed.data.sessionId) {
       joinFailure = "validation";
@@ -996,9 +1147,16 @@ function registerTools(server, deps) {
     heartbeat.start(parsed.data.sessionId);
   }).catch((err) => {
     joinFailure = classifyJoinFailure(err);
-    console.error(
-      `[shepherd] join failed (${joinFailure}): ${err instanceof Error ? err.message : String(err)}`
-    );
+    if (err instanceof HubRequestError && (err.status === 403 || err.status === 404)) {
+      hostedWorkspaceRejected = true;
+      console.error(
+        `[shepherd] This repo is linked to workspace "${context.workspace}" but your configured token is for a different workspace \u2014 coordination disabled.`
+      );
+    } else {
+      console.error(
+        `[shepherd] join failed (${joinFailure}): ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
   });
   async function awaitJoin() {
     await joinInFlight;
@@ -1013,6 +1171,33 @@ function registerTools(server, deps) {
       ]
     };
   }
+  function notLinked() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "This repo isn't linked to a Shepherd workspace \u2014 run `link` to choose one, or ignore to stay uncoordinated."
+        }
+      ]
+    };
+  }
+  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 (!context.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 +1237,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 +1274,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 +1306,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 +1338,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 +1360,88 @@ ${msgs}` : base }
       }
     }
   );
+  function advisory(text) {
+    return { content: [{ type: "text", text }] };
+  }
+  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 to see the workspaces you can link to, then call again with one. You can only link to a workspace you are a member of. Takes effect on the next session (restart to coordinate now). Use `unlink` to opt out.",
+      inputSchema: z3.object({
+        workspace: z3.string().min(1).optional().describe("The workspace slug to link this repo to. Omit to list your 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) {
+          return advisory(
+            `This is a self-host deployment with a single workspace: \`${allowed}\`.
+Run \`link\` again with workspace "${allowed}" to opt this repo in.`
+          );
+        }
+        if (requested !== allowed) {
+          return advisory(
+            `This self-host deployment only serves the workspace \`${allowed}\`; you asked for \`${requested}\`. Choose: ${allowed}`
+          );
+        }
+        writeMarker(markerCwd, allowed);
+        return advisory(
+          `Linked this repo to \`${allowed}\` \u2014 restart the session for it to take effect (it applies on the next launch).`
+        );
+      }
+      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 or join a workspace first, then run `link` again."
+        );
+      }
+      if (requested === void 0) {
+        return advisory(
+          "You can link this repo to one of these workspaces:\n" + slugs.map((s) => `  - ${s}`).join("\n") + "\n\nRun `link` again with one of them as the `workspace` argument."
+        );
+      }
+      if (!slugs.includes(requested)) {
+        return advisory(
+          `You're not a member of \`${requested}\`; choose one of: ${slugs.join(", ")}`
+        );
+      }
+      writeMarker(markerCwd, requested);
+      return advisory(
+        `Linked this repo to \`${requested}\` \u2014 restart the session for it to take effect (it applies on the next launch).`
+      );
+    }
+  );
+  server.registerTool(
+    "unlink",
+    {
+      title: "Unlink this repo from its Shepherd workspace",
+      description: "Opt this repository OUT of Shepherd coordination by removing its `.shepherd` marker. The repo stays uncoordinated (no claims, no presence) until you `link` it again.",
+      inputSchema: z3.object({}).shape
+    },
+    async () => {
+      removeMarker(markerCwd);
+      return advisory(
+        "Unlinked \u2014 this repo will stay uncoordinated until re-linked."
+      );
+    }
+  );
   async function leave() {
     try {
       await joinInFlight;
@@ -1198,9 +1457,9 @@ ${msgs}` : base }
 }
 
 // src/identityCache.ts
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname3, join as join3 } from "path";
 function defaultIdentityCachePath() {
   let base = "";
   try {
@@ -1209,12 +1468,12 @@ function defaultIdentityCachePath() {
     base = "";
   }
   if (!base) base = tmpdir2();
-  return join2(base, ".shepherd", "identity.json");
+  return join3(base, ".shepherd", "identity.json");
 }
 function readCachedHuman(filePath = defaultIdentityCachePath()) {
   let raw;
   try {
-    raw = readFileSync2(filePath, "utf8");
+    raw = readFileSync3(filePath, "utf8");
   } catch {
     return null;
   }
@@ -1229,9 +1488,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 });
+    mkdirSync2(dirname3(filePath), { recursive: true });
     const payload = JSON.stringify({ human });
-    writeFileSync(filePath, payload + "\n", "utf8");
+    writeFileSync2(filePath, payload + "\n", "utf8");
   } catch {
   }
 }
@@ -1241,6 +1500,7 @@ var defaultDeps = {
   detectRepo,
   detectBranch,
   detectHuman,
+  readMarker,
   readCachedHuman,
   writeCachedHuman
 };
@@ -1253,8 +1513,10 @@ 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;
+  return { workspace, repo, branch, human, program, model, linked };
 }
 function resolveHuman(config, cwd, deps) {
   if (config.HUMAN) return config.HUMAN;
@@ -1347,7 +1609,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());

package/package.json

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