claude-slack-channel-bots 0.6.7 → 0.7.0

package/README.md

@@ -38,7 +38,7 @@ See the sections below for manual configuration details if you prefer not to use
 
 - [Bun](https://bun.sh) `>= 1.0.21` (agent-director minimum)
 - [Claude Code](https://claude.ai/code) installed and authenticated
-- [`agent-director`](https://github.com/gabemahoney/agent-director) **runtime dependency** — pulled in transitively when you install this package. Hard required at server boot: CSCB refuses to start if the library is missing, the host platform is unsupported, Bun is too old, or the installed version is below `MIN_AD_VERSION` (`^0.6.3`). agent-director itself requires [tmux](https://github.com/tmux/tmux) on the operator's PATH; CSCB no longer probes for it directly.
+- [`agent-director`](https://github.com/gabemahoney/agent-director) **installed system-wide** as a prerequisite — like `git` or `docker`. CSCB no longer vendors the AD binary. The npm `agent-director` package CSCB depends on is now a thin TypeScript shim that locates the system-installed binary at startup via `resolveSystemBinary()` / `Client.create()` and refuses to start when the binary is missing, too old, or unreachable. The startup gate enforces AD's required version (declared by AD in `dist/version-floor.json`) and reports the required version on mismatch. agent-director itself requires [tmux](https://github.com/tmux/tmux) on the operator's PATH; CSCB no longer probes for it directly.
 - Slack workspace admin access (to create and configure the Slack app)
 - **cozempic** (optional) — Python 3.10+ and `pip install cozempic` — used by JSONL path resolution helpers retained for downstream callers.
 
@@ -52,9 +52,74 @@ See the sections below for manual configuration details if you prefer not to use
 | `darwin-x64` (Intel Mac) | **Not supported** by agent-director |
 | Windows | **Not supported** by agent-director |
 
-If the host is unsupported, the SR-5.1 startup gate exits non-zero at server boot with a typed error from agent-director (`ErrPlatformPackageMissing` or `ErrUnsupportedPlatform`) and writes the failure to `~/.claude/channels/slack/startup-errors.log` and stderr. See [Startup errors](#startup-errors) below.
+If the host is unsupported, the system-installed `agent-director` itself will refuse to install or run; CSCB's startup gate then exits non-zero with one of the `ad-system-install-*` class labels (see [Startup errors](#startup-errors)) and writes the failure to `~/.claude/channels/slack/startup-errors.log` and stderr. Consult [agent-director's documentation](https://github.com/gabemahoney/agent-director) for the canonical platform support list.
 
-> **Note on agent-director versions.** v0.4.1 is a zombie release (the published tarball is missing `dist/` and cannot be imported). v0.4.2 lacks the `MakeTemplateParams.overwrite` field CSCB needs for the boot-time template refresh. v0.5.4 and earlier lack `allow_pending` on `readPane`/`sendKeys`, causing `ErrSpawnNotInteractive` during dev-channels dialog approval on freshly-spawned bots. v0.6.0 shipped a stale TS shim whose `Client` dropped `getPermission`, whose `buildDecide()` dropped `--request-token`, and whose error catalog omitted `ErrInvalidFlags` / `ErrPermissionRequestNotFound` / `ErrAmbiguousRequest` — each silently breaks the disambiguation relay. v0.6.1–0.6.2 still lack the full `permission_requests` plural projection + composite-key disambiguation surface CSCB depends on for concurrent open requests. CSCB pins `^0.6.3` to get past all of these.
+> **Note on agent-director versions.** v0.4.1 is a zombie release (the published tarball is missing `dist/` and cannot be imported). v0.4.2 lacks the `MakeTemplateParams.overwrite` field CSCB needs for the boot-time template refresh. v0.5.4 and earlier lack `allow_pending` on `readPane`/`sendKeys`, causing `ErrSpawnNotInteractive` during dev-channels dialog approval on freshly-spawned bots. v0.6.0 shipped a stale TS shim whose `Client` dropped `getPermission`, whose `buildDecide()` dropped `--request-token`, and whose error catalog omitted `ErrInvalidFlags` / `ErrPermissionRequestNotFound` / `ErrAmbiguousRequest` — each silently breaks the disambiguation relay. v0.6.1–0.6.2 still lack the full `permission_requests` plural projection + composite-key disambiguation surface CSCB depends on for concurrent open requests. From v0.7.0 onward, AD ships as a thin npm shim around a system-installed binary, and CSCB defers the minimum-AD-version decision to AD itself via `dist/version-floor.json` (AD's library-side `Client.create()` reads it). CSCB's `package.json` caret-pin on `agent-director` governs npm resolution of AD's TypeScript shim only — not the runtime floor, which is owned by the AD release the system binary belongs to.
+
+### Checking your agent-director install
+
+Before starting the server, you can confirm `agent-director` is installed system-wide and meets the declared minimum with:
+
+```sh
+bun run install-check
+```
+
+The script calls the same discovery + floor-comparison pipeline the startup gate uses (it reads AD's `dist/version-floor.json`, calls `resolveSystemBinary()`, and compares versions via `semver.gte`). It exits 0 on success with a single-line block naming `agent-director`, the absolute resolved binary path, the detected version, and the floor. On failure it writes one of the canonical class labels to stderr and exits non-zero:
+
+- `ad-system-install-not-found` — no agent-director on PATH or at the standard install path. Install AD and retry. The stderr also points at the install-cscb skill for interactive remediation.
+- `ad-system-install-too-old` — AD binary is below the floor. Upgrade AD and retry. The stderr points at the skill.
+- `ad-system-install-unreachable` — AD discovered but the probe could not invoke it (eight `.reason` values exposed verbatim). The stderr points at the skill.
+- `ad-version-floor-unreadable` — `dist/version-floor.json` is missing, malformed, or lacks `min_binary_version`. The remediation is to reinstall `agent-director` from npm; the install-cscb skill cannot fix a corrupt AD package, so this case does NOT append the skill instructions block.
+
+The script is purely diagnostic — it never prompts, never runs an install command, never fetches the skill. The startup gate enforces the same floor automatically at server boot via AD's `Client.create()`; `install-check` is for operators who want to confirm their setup ahead of time.
+
+### Installing the install-cscb skill
+
+If `bun run install-check` (or the startup gate) reports one of the
+`ad-system-install-*` failure classes, you can install the `install-cscb`
+Claude skill for an interactive walkthrough. The skill drives the same
+shared check module but walks you through install/upgrade and a
+per-reason remediation flow for each of the eight
+`ErrSystemInstallUnreachable.reason` values.
+
+The skill is NOT auto-installed by `bun install` — fetch it manually
+from CSCB's GitHub repo and place it in your local Claude skills
+folder:
+
+1. **Fetch** `SKILL.md` from:
+
+   ```
+   https://github.com/gabemahoney/claude-slack-channel-bots/blob/main/skills/install-cscb/SKILL.md
+   ```
+
+   (The startup gate's `ad-system-install-*` error log line includes
+   this URL automatically.)
+
+2. **Place** it at:
+
+   ```
+   ~/.claude/skills/install-cscb/SKILL.md
+   ```
+
+3. **Invoke** the skill from Claude Code:
+
+   ```
+   /install-cscb
+   ```
+
+The skill calls `bun run install-check` on each iteration, surfaces
+`agent-director`'s published install/upgrade command verbatim (no
+CSCB-owned install command — AD's documentation is the source of
+truth), prompts before running, and loops until the check passes or
+you decline. The `ad-version-floor-unreadable` class is handled
+separately: the skill prints reinstall-from-npm guidance and does NOT
+loop on it (the skill cannot fix a corrupt AD npm package).
+
+The published CSCB npm tarball includes `skills/install-cscb/SKILL.md`
+under its `files` array, so the skill source is also available via
+`node_modules/claude-slack-channel-bots/skills/install-cscb/SKILL.md`
+after `bun install`. The manual GitHub-fetch step above is for users
+who haven't yet installed CSCB at all.
 
 ---
 
@@ -433,15 +498,15 @@ CSCB writes fatal startup errors to `~/.claude/channels/slack/startup-errors.log
 
 Classes you may see:
 
-- `ad-platform-package-missing` — agent-director's platform-native peer dependency is absent. The host is unsupported by agent-director.
-- `ad-unsupported-platform` — agent-director's runtime check rejected the host's `process.platform`/`process.arch` tuple.
+- `ad-system-install-not-found` — `Client.create()` could not locate an `agent-director` binary on PATH or at the standard install path. Install agent-director system-wide and retry. The log line appends a manual-skill-install instructions block pointing at `skills/install-cscb/SKILL.md` (URL, target path under `~/.claude/skills/`, and invocation command `/install-cscb`) for the interactive install/upgrade flow.
+- `ad-system-install-too-old` — the system-installed agent-director binary is below the floor declared in `dist/version-floor.json`. The log line names the detected and required versions, and appends the manual-skill-install instructions block.
+- `ad-system-install-unreachable` — agent-director was discovered but the probe could not execute it (e.g. permission bits, broken symlink, runtime crash). The log line surfaces AD's supplied `err.reason` value verbatim (one of `not-executable`, `not-a-regular-file`, `probe-timeout`, `probe-nonzero-exit`, `probe-killed-by-signal`, `unparseable-version`, `spawn-failed`, `other`) and appends the manual-skill-install instructions block.
 - `ad-bun-version-too-old` — agent-director needs Bun `>= 1.0.21`. Upgrade Bun.
-- `ad-cli-not-executable` — the resolved agent-director CLI binary exists but is not executable. Run `chmod +x` on the binary referenced in the log line.
 - `ad-version-probe` — `agent-director` was loaded but the `version()` probe failed (subprocess invocation, platform binary, etc.).
-- `ad-version-stale` — installed `agent-director` is below the minimum version this CSCB requires. Run `bun add agent-director@^<minimum>`.
-- `ad-shim-missing-get-permission` — the installed `agent-director` TS shim's `Client` does not expose `getPermission`. The npm-published package is out of sync with its bundled binary. Reinstall and confirm the resolved version actually ships the method.
+- `ad-shim-missing-get-permission` — the installed `agent-director` TS shim's `Client` does not expose `getPermission`. The npm-published package is out of sync with the system-installed binary. Reinstall a matching `agent-director` version and confirm the resolved package actually ships the method.
 - `ad-shim-catalog-incomplete` — the installed `agent-director` TS error catalog is missing one or more of `ErrInvalidFlags`, `ErrPermissionRequestNotFound`, `ErrAmbiguousRequest`. The log line lists the missing names. Same remediation as `ad-shim-missing-get-permission`.
-- `ad-shim-decide-drops-token` — the installed `agent-director` dist does not include `--request-token` in its bundled JS, meaning `buildDecide()` would resolve permission clicks against the wrong row. Reinstall and confirm `buildDecide` carries the flag.
+- `ad-shim-decide-drops-token` — the installed `agent-director` dist does not include `--request-token` in its bundled JS, meaning `buildDecide()` would resolve permission clicks against the wrong row. Reinstall a matching `agent-director` version and confirm `buildDecide` carries the flag.
+- `ad-version-floor-unreadable` — `node_modules/agent-director/dist/version-floor.json` could not be read, parsed, or is missing `.min_binary_version`. This is a packaging defect — reinstall `agent-director` from npm. Surfaced by `bun run install-check`; the startup gate itself does not emit this label (it relies on `Client.create()`, which fails differently when the AD package is corrupt).
 - `ad-call-timeout` — an agent-director verb call exceeded the configured `callTimeoutMs` (default 30 s). Investigate the subprocess or increase the timeout.
 - `ad-same-user` — `~/.agent-director/state.db` is owned by a different UID than the CSCB process. Reinstall agent-director as the correct user or remove the mismatched file.
 - `ad-same-user-stat` — Non-ENOENT stat error on the state DB (permissions, I/O). Investigate the file before re-launching.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "start": "bun install --no-summary && bun src/server.ts",
     "pretest": "bun scripts/fixup-bun-cache.ts && bun scripts/check-no-toplevel-mock-module.ts",
     "check:mocks": "bun scripts/check-no-toplevel-mock-module.ts",
+    "install-check": "bun scripts/install-check.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
@@ -29,11 +30,12 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@slack/socket-mode": "^2.0.0",
     "@slack/web-api": "^7.0.0",
-    "agent-director": "^0.6.3"
+    "agent-director": "^0.7.0",
+    "semver": "^7.6.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
-    "semver": "^7.6.0",
+    "@types/semver": "^7.7.1",
     "typescript": "^5.4.0"
   },
   "license": "MIT",

package/skills/install-cscb/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: install-cscb
+description: Interactive walkthrough that installs or upgrades the system-installed `agent-director` so claude-slack-channel-bots can boot. Drives Epic 2's bun run install-check and per-reason remediation.
+version: 1.0.0
+author: Gabe Mahoney
+license: MIT
+user-invocable: true
+argument-hint: "(no arguments)"
+allowed-tools: [Bash, Read]
+---
+
+# /install-cscb
+
+Diagnose and fix a broken or missing `agent-director` system install so
+`claude-slack-channel-bots` (CSCB) can boot. This skill is the interactive
+counterpart to the diagnostic `bun run install-check` script — same shared
+check module, but with a guided remediation loop for each failure class.
+
+## When to invoke
+
+Invoke this skill when CSCB's startup gate emits one of these class labels
+in `~/.claude/channels/slack/startup-errors.log`:
+
+- `ad-system-install-not-found`
+- `ad-system-install-too-old`
+- `ad-system-install-unreachable`
+
+The gate appends a pointer to this skill on those three classes. Other
+failure classes (`ad-bun-version-too-old`, `ad-shim-*`, `ad-same-user`,
+`ad-version-floor-unreadable`) are NOT remediated by this skill — see
+the README's Startup-errors section for those.
+
+## Step 1 — Run the shared check
+
+From the CSCB project root, run:
+
+```sh
+bun run install-check
+```
+
+This is the same command you can run directly from the shell. It calls
+the shared check module (`src/install-check.ts`) which is also what this
+skill drives internally on every iteration.
+
+Read the output carefully:
+
+- **Exit 0 + "OK"**: agent-director is satisfied. Print the resolved
+  binary path, detected version, and floor from the success output, then
+  exit cleanly. No further action required.
+
+- **Exit non-zero**: identify the class label on stderr (one of
+  `ad-system-install-not-found`, `ad-system-install-too-old`,
+  `ad-system-install-unreachable`, `ad-version-floor-unreadable`) and
+  branch on it as documented below.
+
+## Step 2 — Identify the user's platform
+
+Detect the platform via `uname -sm`. CSCB supports two platforms:
+
+- **linux-x64** — `Linux x86_64`
+- **darwin-arm64** — `Darwin arm64` (Apple Silicon Mac)
+
+Any other platform is unsupported by `agent-director` itself and the
+skill cannot proceed; surface the platform mismatch to the user and
+exit non-zero.
+
+## Step 3 — Branch on the class label
+
+### `ad-system-install-not-found` — agent-director missing
+
+Surface the install command published by `agent-director` verbatim for
+the detected platform. Do NOT invent or maintain a CSCB-owned command —
+consult agent-director's documentation
+(<https://github.com/gabemahoney/agent-director>) for the canonical
+install procedure. The current installer is `install.sh` from
+agent-director's repo; recommend running it.
+
+Prompt the user (using AskUserQuestion or an equivalent) — the literal
+command must be visible:
+
+> agent-director is not installed system-wide. Run the AD-published install
+> command? `<command>`
+>
+> - **Yes** — run the command via Bash and continue.
+> - **No** — install manually then continue.
+
+- **Yes**: run the command via Bash. Capture stdout/stderr for the user
+  to see. Return to Step 1.
+- **No**: instruct the user to install manually. Wait for confirmation.
+  Return to Step 1.
+
+If the user declines to proceed at any point, exit non-zero with a
+one-line summary: "Aborted by user — agent-director still not installed."
+
+### `ad-system-install-too-old` — agent-director below floor
+
+Same flow as `ad-system-install-not-found` but with the upgrade command
+instead of the install command. Surface the detected version and the
+required floor from the stderr block so the user understands what they
+are upgrading from and to.
+
+Prompt:
+
+> agent-director is installed but at version `<detected>`, below the
+> required floor `<required>`. Run the AD-published upgrade command?
+> `<command>`
+>
+> - **Yes** — run the command via Bash and continue.
+> - **No** — upgrade manually then continue.
+
+- **Yes**: run via Bash. Return to Step 1.
+- **No**: wait for manual upgrade. Return to Step 1.
+
+### `ad-system-install-unreachable` — exhaustive reason switch
+
+The stderr block carries an `err.reason` value verbatim. Branch on it
+explicitly — every reason has a named branch, no `default:`-only
+fallthrough.
+
+1. **`not-executable`** — the agent-director file exists but lacks the
+   executable bit. Show the user the binary path from the stderr block
+   and suggest:
+   ```sh
+   chmod +x <binary_path>
+   ```
+   Re-run Step 1.
+
+2. **`not-a-regular-file`** — the path resolved by `resolveSystemBinary()`
+   is a directory, broken symlink, or other non-file. Recommend
+   inspection (`ls -la <binary_path>`) and removal of the bad entry,
+   then re-installation via the AD install command. Re-run Step 1.
+
+3. **`probe-timeout`** — `agent-director --version` did not return within
+   the probe window. Likely the binary is hanging on startup
+   (corrupted, mismatched architecture, missing shared library).
+   Recommend a manual `<binary_path> --version` invocation to confirm,
+   then reinstall via the AD install command. Re-run Step 1.
+
+4. **`probe-nonzero-exit`** — `agent-director --version` exited with a
+   non-zero code. The stderr block surfaces `exitCode` and any
+   `diagnostic` from AD. Show the user the values and recommend a
+   manual reproduction (`<binary_path> --version`), then reinstall.
+   Re-run Step 1.
+
+5. **`probe-killed-by-signal`** — `agent-director --version` was killed
+   by a signal (SIGSEGV, SIGBUS, etc.). The stderr block surfaces
+   `signal`. The binary is likely corrupted or built for a different
+   architecture. Recommend a full reinstall via the AD install command.
+   Re-run Step 1.
+
+6. **`unparseable-version`** — `agent-director --version` returned but
+   the output could not be parsed as semver. The stderr's `diagnostic`
+   field carries the raw output. Likely the installed binary is from
+   a pre-release line that uses non-semver tags (e.g. `v0.6.3-dev`
+   without sentinel handling). Recommend upgrading to a release AD
+   version via the AD install command. Re-run Step 1.
+
+7. **`spawn-failed`** — the OS rejected the spawn before the subprocess
+   ran (ENOENT after stat succeeded, EACCES, EPERM, etc.). The stderr's
+   `diagnostic` field carries the underlying OS error. Recommend
+   checking filesystem permissions, then reinstalling. Re-run Step 1.
+
+8. **`other`** — an unexpected failure mode AD's `resolveSystemBinary()`
+   could not classify. Print the raw underlying error message from
+   `detail.underlying` (or `diagnostic`) and direct the user to file
+   a bug against `agent-director`:
+   <https://github.com/gabemahoney/agent-director/issues>
+
+   This is the only branch that recommends bug-filing rather than a
+   local remediation step.
+
+After rendering the per-reason remediation, ask the user to confirm
+they have applied it, then return to Step 1.
+
+### `ad-version-floor-unreadable` — corrupt agent-director npm package
+
+This class is NOT a system-install problem — it indicates the
+`node_modules/agent-director/dist/version-floor.json` file is missing,
+malformed, or lacks `.min_binary_version`. The skill cannot walk the
+user through fixing a corrupt AD npm package.
+
+Print the reinstall guidance:
+
+> The agent-director npm package appears corrupted. Reinstall it from
+> npm in CSCB's project root:
+>
+> ```sh
+> bun add agent-director@latest
+> ```
+
+Then exit. Do NOT loop on this class — the user must manually verify
+the AD package is intact before re-invoking the skill.
+
+## Step 4 — Loop or exit
+
+After each remediation step, re-run Step 1. The skill keeps looping
+until the check passes (exit cleanly with the success output) or the
+user declines to proceed (exit non-zero with the abort summary).
+
+## Notes
+
+- This skill does not maintain its own list of agent-director install
+  commands. AD's documentation is the source of truth; the skill
+  surfaces AD's published command verbatim.
+- This skill does not touch `~/.claude/channels/slack/` or CSCB's
+  routing configuration. It only acts on the system-wide
+  `agent-director` install.
+- The skill is callable repeatedly; each invocation re-runs Step 1
+  from a clean state.

package/src/agent-director-client.ts

@@ -3,19 +3,20 @@
  * `agent-director` library Client (SR-0.1).
  *
  * Public API:
- *   - getClient(): Client                          — lazy-construct + return the singleton
+ *   - getClient(): Client                          — sync cached accessor for the singleton
+ *   - setClient(client): void                       — install a pre-built Client (startup gate only)
  *   - closeClient(): void                           — idempotent shutdown for SR-11 Event 11
- *   - MIN_AD_VERSION: string                        — semver string derived from package.json
  *   - DEFAULT_STORE_PATH / DEFAULT_TEMPLATE_NAME    — paths CSCB pins
  *   - resetClientForTests(): void                   — test-only handle reset
  *
- * MIN_AD_VERSION is read once at module init from this package.json's
- * `dependencies['agent-director']` range, stripping leading semver operators
- * (`^`, `~`, `>=`, etc.) so a single source of truth covers both the install-
- * time dep declaration (SR-5.3) and the runtime version gate (SR-5.1 step 3).
- *
- * Construction uses `{ storePath, createIfMissing: true, logger: console }`
- * per SR-0.1; tilde expansion is the library's responsibility.
+ * Construction: AD 0.7.0+ exposes an async `Client.create()` factory; the
+ * subprocess constructor is protected and `new Client(...)` is a compile-time
+ * TS error. The SR-5.1 startup gate (src/agent-director-startup.ts) awaits
+ * `Client.create({ storePath, createIfMissing: true, logger: console })` and
+ * then hands the resolved instance to `setClient()`. Verb call sites pull the
+ * installed singleton through `getClient()`; calling `getClient()` before the
+ * gate has installed a Client throws an internal bug-marker error (it
+ * indicates a caller-site bug, not a runtime condition).
  *
  * Concurrency: AD's Client is internally safe for concurrent verb calls
  * (the subprocess-CLI transport serializes its own dispatch) per SR-0.1,
@@ -24,9 +25,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-import { readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { AgentDirectorError, Client } from 'agent-director'
 import type {
   DecideParams as ADDecideParams,
@@ -45,40 +43,6 @@ export const DEFAULT_STORE_PATH = '~/.agent-director/state.db'
 /** Name of the CSCB-shipped template (SR-3.1). */
 export const DEFAULT_TEMPLATE_NAME = 'slack-channel-bot'
 
-/**
- * Resolve the package.json that ships with this module, then extract and
- * normalize `dependencies['agent-director']` into a bare semver string.
- *
- * Throws at module init if the dep is missing or shaped wrong — that's a
- * packaging bug worth failing loudly on, not a runtime condition.
- */
-function readMinAdVersion(): string {
-  const moduleDir = dirname(fileURLToPath(import.meta.url))
-  // src/agent-director-client.ts → package.json lives one level up
-  const pkgPath = join(moduleDir, '..', 'package.json')
-  const raw = readFileSync(pkgPath, 'utf-8')
-  const pkg = JSON.parse(raw) as { dependencies?: Record<string, string> }
-  const range = pkg.dependencies?.['agent-director']
-  if (typeof range !== 'string' || range.length === 0) {
-    throw new Error(
-      `agent-director-client: package.json dependencies['agent-director'] is missing or empty — cannot derive MIN_AD_VERSION`,
-    )
-  }
-  // Strip leading semver operators: ^, ~, >=, >, =, v. Anything left should
-  // parse as semver; we don't validate further here — the SR-5.1 version gate
-  // does the actual comparison.
-  const stripped = range.replace(/^[\^~]|^>=|^>|^=/, '').replace(/^v/, '').trim()
-  if (stripped.length === 0) {
-    throw new Error(
-      `agent-director-client: dependencies['agent-director']=${range} reduced to empty string after stripping operators`,
-    )
-  }
-  return stripped
-}
-
-/** Minimum agent-director version CSCB requires at runtime (SR-5.3). */
-export const MIN_AD_VERSION: string = readMinAdVersion()
-
 // ---------------------------------------------------------------------------
 // Singleton state
 // ---------------------------------------------------------------------------
@@ -86,20 +50,19 @@ export const MIN_AD_VERSION: string = readMinAdVersion()
 let singleton: Client | null = null
 
 /**
- * Return the singleton Client, lazy-constructing it on first call.
+ * Return the singleton Client installed by the SR-5.1 startup gate.
  *
- * Construction is synchronous: all platform / Bun / subprocess-resolution
- * errors fire eagerly here per SR-0.1, not at first verb call. Typed `Err*`
- * subclasses propagate; the SR-5.1 startup gate is the only intended
- * caller-of-record that branches them.
+ * This is a sync cached accessor; it does NOT construct the Client. The
+ * startup gate (`runAgentDirectorStartupGate`) is responsible for awaiting
+ * `Client.create(...)` and installing the result via `setClient`. Calling
+ * `getClient()` before the gate has run is a caller-site bug and throws
+ * loudly — there is no lazy-construction fallback.
  */
 export function getClient(): Client {
   if (singleton === null) {
-    singleton = new Client({
-      storePath: DEFAULT_STORE_PATH,
-      createIfMissing: true,
-      logger: console,
-    })
+    throw new Error(
+      'agent-director-client: getClient() called before the startup gate installed a Client — caller-site bug. The startup gate must run first (via runAgentDirectorStartupGate).',
+    )
   }
   return singleton
 }
@@ -128,6 +91,17 @@ export function resetClientForTests(): void {
   singleton = null
 }
 
+/**
+ * Install a pre-built Client into the singleton slot. Called once by the
+ * startup gate (src/agent-director-startup.ts) after `await Client.create(opts)`
+ * resolves. Production verb call sites never invoke this — they go through
+ * `getClient()`. Lexically distinct from `setClientForTests` so the test
+ * helper stays grep-discoverable.
+ */
+export function setClient(client: Client): void {
+  singleton = client
+}
+
 /**
  * Test-only helper: install a pre-built Client (typically a stub) as the
  * singleton. Skip the Client construction path entirely.
@@ -156,9 +130,9 @@ export interface DecideParamsWithToken extends ADDecideParams {
 }
 
 /**
- * Always-include-token decide wrapper. MIN_AD_VERSION is now pinned at
- * `^0.6.0`, which carries `request_token` on `DecideParams` natively. The
- * structural cast is retained because, until the lockfile is refreshed to
+ * Always-include-token decide wrapper. The `agent-director` package.json pin
+ * is at `^0.6.0`+, which carries `request_token` on `DecideParams` natively.
+ * The structural cast is retained because, until the lockfile is refreshed to
  * resolve the bumped pin, the imported `DecideParams` type still comes from
  * the locked `0.5.6` package — same lockfile-lag pattern as
  * `GetResultWithPermissionRequests`.
@@ -201,13 +175,14 @@ export function isErrPermissionRequestNotFound(err: unknown): boolean {
 }
 
 /**
- * `get-permission` wrapper (SR-7.1). MIN_AD_VERSION is pinned at `^0.6.0`,
- * which carries the verb; the SR-6.1 startup gate is the compatibility
- * boundary that keeps stale-version installs from reaching this path. The
- * wrapper takes a structural client (rather than `Pick<Client, 'getPermission'>`)
- * because the locked `0.5.6` types do not yet expose the method shape, and
- * fails loudly at runtime when the verb is missing as defense-in-depth for
- * the dev/test edge (e.g. stub clients that omit it on purpose).
+ * `get-permission` wrapper (SR-7.1). The `agent-director` package.json pin is
+ * at `^0.6.0`+, which carries the verb; the SR-6.1 startup gate is the
+ * compatibility boundary that keeps stale-version installs from reaching this
+ * path. The wrapper takes a structural client (rather than
+ * `Pick<Client, 'getPermission'>`) because the locked `0.5.6` types do not yet
+ * expose the method shape, and fails loudly at runtime when the verb is
+ * missing as defense-in-depth for the dev/test edge (e.g. stub clients that
+ * omit it on purpose).
  */
 export async function getPermission(
   client: { getPermission?: (params: GetPermissionParams) => Promise<GetPermissionResult> },
@@ -216,7 +191,7 @@ export async function getPermission(
   if (typeof client.getPermission !== 'function') {
     throw new Error(
       'agent-director-client: getPermission verb unavailable — ' +
-        'confirm installed agent-director version meets the MIN_AD_VERSION pin',
+        'confirm installed agent-director version meets the package.json pin',
     )
   }
   return client.getPermission(params)

package/src/agent-director-errors.ts

@@ -7,10 +7,10 @@
  * keep the subset list in sync with SRD edits.
  *
  * Catalog (SR-0.2):
- *   - ErrUnsupportedPlatform    (Client constructor / platform gate)
  *   - ErrBunVersionTooOld       (Client constructor / Bun version gate)
- *   - ErrPlatformPackageMissing (Client constructor / @agent-director/<plat>)
- *   - ErrCliNotExecutable       (Client constructor / CLI binary lacks +x)
+ *   - ErrSystemInstallNotFound  (Client.create / resolveSystemBinary — no `agent-director` on PATH or at ~/.agent-director)
+ *   - ErrSystemInstallTooOld    (Client.create / resolveSystemBinary — system binary older than required minimum)
+ *   - ErrSystemInstallUnreachable (Client.create / resolveSystemBinary — system binary present but not executable or fails --version)
  *   - ErrInstanceIdCollision    (spawn / SR-1.4 idempotency)
  *   - ErrSpawnNotFound          (get / status / decide on missing row)
  *   - ErrNoSessionId            (resume / SR-1.3 fallthrough)
@@ -37,10 +37,10 @@
 export {
   AgentDirectorError,
   ErrClientClosed,
-  ErrUnsupportedPlatform,
-  ErrPlatformPackageMissing,
   ErrBunVersionTooOld,
-  ErrCliNotExecutable,
+  ErrSystemInstallNotFound,
+  ErrSystemInstallTooOld,
+  ErrSystemInstallUnreachable,
   ErrCallTimeout,
   ErrInstanceIdCollision,
   ErrSpawnNotFound,

package/src/agent-director-startup.ts

@@ -8,11 +8,11 @@
  *      time; module-not-found surfaces as a top-level import error caught
  *      by callers' try/catch (see runAgentDirectorStartupGate's
  *      module-load-error branch below).
- *   2. new Client(opts)                          — typed catches for
- *      ErrPlatformPackageMissing, ErrUnsupportedPlatform,
- *      ErrBunVersionTooOld; other throws surface verbatim.
- *   3. await client.version({})                  — strip leading 'v',
- *      compare to MIN_AD_VERSION via semverGte.
+ *   2. await d.createClient(opts)                — typed catches for
+ *      ErrBunVersionTooOld, ErrSystemInstallNotFound,
+ *      ErrSystemInstallTooOld, ErrSystemInstallUnreachable; other throws
+ *      surface verbatim. The factory resolves to a constructed Client
+ *      (production injects `Client.create`).
  *   3.5. API surface probes (SR-6.1 publish-skew defense)  — short-circuit,
  *      run in order: probeGetPermission (ad-shim-missing-get-permission) →
  *      probeErrorCatalog (ad-shim-catalog-incomplete) → probeDecideArgv
@@ -36,22 +36,21 @@ import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 
 import {
+  Client,
   ErrBunVersionTooOld,
-  ErrCallTimeout,
-  ErrCliNotExecutable,
-  ErrPlatformPackageMissing,
-  ErrUnsupportedPlatform,
-  AgentDirectorError,
+  ErrSystemInstallNotFound,
+  ErrSystemInstallTooOld,
+  ErrSystemInstallUnreachable,
 } from 'agent-director'
-import type { VersionResult } from 'agent-director'
+import type { ClientOptions } from 'agent-director'
 
 import { recordStartupError } from './startup-errors.ts'
 import {
-  MIN_AD_VERSION,
   DEFAULT_STORE_PATH,
-  getClient,
+  setClient,
   setClientForTests,
 } from './agent-director-client.ts'
+import { renderInstallSkillInstructions } from './install-skill-pointer.ts'
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -111,53 +110,17 @@ function readAdDistSource(): string | Error {
   return cachedAdDistSource
 }
 
-// ---------------------------------------------------------------------------
-// Pure helper: semver-gte for the three-segment versions AD ships
-// ---------------------------------------------------------------------------
-
-/**
- * Compare two `MAJOR.MINOR.PATCH` strings (no pre-release/build suffix
- * handling needed: AD ships canonical three-segment numerics).
- *
- * Returns true when `a` is greater than or equal to `b`. Inputs must parse
- * as integers — any non-numeric segment makes the comparison treat the
- * value as below `b` (i.e. fail closed).
- *
- * Exported for direct testing.
- */
-export function semverGte(a: string, b: string): boolean {
-  const split = (s: string): number[] =>
-    s.split('.').map((seg) => {
-      const n = parseInt(seg, 10)
-      return Number.isFinite(n) ? n : -1
-    })
-  const av = split(a)
-  const bv = split(b)
-  const len = Math.max(av.length, bv.length)
-  for (let i = 0; i < len; i++) {
-    const ai = av[i] ?? 0
-    const bi = bv[i] ?? 0
-    if (ai > bi) return true
-    if (ai < bi) return false
-  }
-  return true
-}
-
 // ---------------------------------------------------------------------------
 // Injectable dependency surface
 // ---------------------------------------------------------------------------
 
 export interface StartupGateDeps {
   /**
-   * Hook that resolves to the singleton Client. Construction failures
-   * surface as throws here (the synchronous construction path) — production code
-   * passes getClient from src/agent-director-client.ts; tests pass either
-   * `() => makeStubClient(...)` or a thrower that simulates the typed
-   * Err* constructor failure modes.
+   * Async factory that resolves to a constructed Client. Production injects
+   * `Client.create`; tests inject `makeStubCreateClient({...})` from
+   * tests/test-helpers/agent-director-stub.ts to drive the catch ladder.
    */
-  getClient: () => unknown
-  /** Hook that returns the client's `version()` result. */
-  callVersion: (client: unknown) => Promise<VersionResult>
+  createClient: (opts: object) => Promise<unknown>
   /** Hook that returns the client's `close()` for the failure-path cleanup. */
   closeClient: (client: unknown) => void
   /** Stat hook for the SR-5.1 same-user check. */
@@ -202,11 +165,8 @@ export interface StartupGateDeps {
 // ---------------------------------------------------------------------------
 
 const prodDeps: StartupGateDeps = {
-  getClient: () => getClient(),
-  callVersion: async (client) => {
-    // Cast: production getClient returns the real Client; tests inject a stub
-    // with the same structural shape. Either way, .version({}) exists.
-    return await (client as { version: (p: object) => Promise<VersionResult> }).version({})
+  createClient: async (opts) => {
+    return await Client.create(opts as ClientOptions)
   },
   closeClient: (client) => {
     try {
@@ -304,55 +264,60 @@ export async function runStartupGate(
 ): Promise<StartupGateOutcome> {
   const d = mergeDeps(deps)
 
-  // Step 2: construct Client (synchronous construction path).
+  // Step 2: construct Client via async factory (Client.create in prod).
   let client: unknown
   try {
-    client = d.getClient()
+    client = await d.createClient({
+      storePath: DEFAULT_STORE_PATH,
+      createIfMissing: true,
+      logger: console,
+    })
   } catch (err) {
-    if (err instanceof ErrPlatformPackageMissing) {
+    if (err instanceof ErrBunVersionTooOld) {
       return {
         ok: false,
         phase: 'construct',
-        classLabel: 'ad-platform-package-missing',
+        classLabel: 'ad-bun-version-too-old',
         message:
-          `agent-director platform-native peer dependency missing — ` +
-          `your host is unsupported by agent-director. ` +
-          `Supported: ${SUPPORTED_PLATFORMS.join(', ')}. ` +
-          `Detected: ${process.platform}-${process.arch}. ` +
-          `Detail: ${err.errDescription}`,
+          `agent-director requires Bun >= 1.0.21 but the running runtime is older. ` +
+          `Upgrade Bun (https://bun.sh) and retry. Detail: ${err.errDescription}`,
       }
     }
-    if (err instanceof ErrUnsupportedPlatform) {
+    if (err instanceof ErrSystemInstallNotFound) {
       return {
         ok: false,
         phase: 'construct',
-        classLabel: 'ad-unsupported-platform',
+        classLabel: 'ad-system-install-not-found',
         message:
-          `agent-director does not support this platform. ` +
-          `Detected: ${process.platform}-${process.arch}. ` +
-          `Supported: ${SUPPORTED_PLATFORMS.join(', ')}. ` +
-          `Detail: ${err.errDescription}`,
+          `agent-director system install not found. The startup gate searched ` +
+          `the standard install path and PATH but did not locate the agent-director ` +
+          `binary. Install agent-director (system-wide) and retry.` +
+          renderInstallSkillInstructions(),
       }
     }
-    if (err instanceof ErrBunVersionTooOld) {
+    if (err instanceof ErrSystemInstallTooOld) {
       return {
         ok: false,
         phase: 'construct',
-        classLabel: 'ad-bun-version-too-old',
+        classLabel: 'ad-system-install-too-old',
         message:
-          `agent-director requires Bun >= 1.0.21 but the running runtime is older. ` +
-          `Upgrade Bun (https://bun.sh) and retry. Detail: ${err.errDescription}`,
+          `agent-director system install is too old. ` +
+          `Detected version ${err.actualVersion} is below the required floor ${err.requiredVersion} ` +
+          `(binary at ${err.binaryPath}). Upgrade agent-director and retry.` +
+          renderInstallSkillInstructions(),
       }
     }
-    if (err instanceof ErrCliNotExecutable) {
+    if (err instanceof ErrSystemInstallUnreachable) {
       return {
         ok: false,
         phase: 'construct',
-        classLabel: 'ad-cli-not-executable',
+        classLabel: 'ad-system-install-unreachable',
         message:
-          `agent-director CLI binary is not executable. ` +
-          `Detail: ${err.errDescription}. ` +
-          `Remediation: chmod +x the binary referenced above, then retry.`,
+          `agent-director system install is unreachable. ` +
+          `Reason: ${err.reason}. ` +
+          `Binary at ${err.binaryPath} could not be invoked successfully. ` +
+          `Diagnose with the install-cscb skill or re-install agent-director.` +
+          renderInstallSkillInstructions(),
       }
     }
     const detail = err instanceof Error ? err.message : String(err)
@@ -364,54 +329,17 @@ export async function runStartupGate(
     }
   }
 
-  // Step 3: version probe.
-  let versionResult: VersionResult
-  try {
-    versionResult = await d.callVersion(client)
-  } catch (err) {
-    if (err instanceof ErrCallTimeout) {
-      d.closeClient(client)
-      return {
-        ok: false,
-        phase: 'version',
-        classLabel: 'ad-call-timeout',
-        message:
-          `agent-director ${err.verb}() timed out after ${err.elapsedMs}ms ` +
-          `(configured callTimeoutMs: ${err.timeoutMs}ms). ` +
-          `Either the subprocess hung or the timeout is set too low; ` +
-          `set ClientOptions.callTimeoutMs higher (default 30000) or investigate the agent-director subprocess.`,
-      }
-    }
-    d.closeClient(client)
-    const detail =
-      err instanceof AgentDirectorError
-        ? `${err.errName}: ${err.errDescription}`
-        : err instanceof Error
-        ? err.message
-        : String(err)
-    return {
-      ok: false,
-      phase: 'version',
-      classLabel: 'ad-version-probe',
-      message: `agent-director version probe failed. Detail: ${detail}`,
-    }
-  }
+  // Construction succeeded: install the live Client into the module-level
+  // singleton so subsequent `getClient()` call sites resolve to it.
+  setClient(client as Client)
 
-  const adVersion = versionResult.version.replace(/^v/, '')
-  if (!semverGte(adVersion, MIN_AD_VERSION)) {
-    d.closeClient(client)
-    return {
-      ok: false,
-      phase: 'version',
-      classLabel: 'ad-version-stale',
-      message:
-        `agent-director version ${adVersion} is below the required minimum ${MIN_AD_VERSION}. ` +
-        `Run: bun add agent-director@^${MIN_AD_VERSION}`,
-    }
-  }
+  // adVersion is sourced directly from the constructed Client; AD 0.7.0
+  // exposes `binaryVersion` as a readonly getter populated during
+  // `Client.create()`'s version probe of the resolved system binary.
+  const adVersion = (client as { binaryVersion: string }).binaryVersion
 
-  // Step 3.5: API surface probes. The version gate above confirms the AD
-  // binary meets MIN_AD_VERSION, but published agent-director npm packages
+  // Step 3.5: API surface probes. `Client.create()` confirms the AD binary
+  // meets the required floor, but published agent-director npm packages
   // have shipped a stale TS shim that drops methods (getPermission), drops
   // CLI flags (--request-token in buildDecide), and misses err_names in the
   // catalog. Each of those silently breaks CSCB at click-handling time. The
@@ -426,7 +354,7 @@ export async function runStartupGate(
       message:
         `agent-director Client is missing the 'getPermission' method. ` +
         `The installed shim is stale relative to the AD binary (${adVersion}). ` +
-        `Run: bun add agent-director@^${MIN_AD_VERSION} (and confirm the resolved version actually ships getPermission).`,
+        `Run: reinstall a matching 'agent-director' version (confirm the resolved package ships getPermission).`,
     }
   }
 
@@ -442,7 +370,7 @@ export async function runStartupGate(
         `${catalogProbe.missing.join(', ')}. ` +
         `Envelopes with these names would surface as the base AgentDirectorError ` +
         `instead of typed subclasses, breaking CSCB's instanceof Err<Name> branches. ` +
-        `Run: bun add agent-director@^${MIN_AD_VERSION} (confirm the resolved package ships the full catalog).`,
+        `Run: reinstall a matching 'agent-director' version (confirm the resolved package ships the full catalog).`,
     }
   }
 
@@ -456,7 +384,7 @@ export async function runStartupGate(
       message:
         `agent-director shim's decide() does not pass --request-token to the CLI: ${argvProbe.detail} ` +
         `Permission clicks would resolve against the wrong row. ` +
-        `Run: bun add agent-director@^${MIN_AD_VERSION} (confirm the resolved package's buildDecide includes the flag).`,
+        `Run: reinstall a matching 'agent-director' version (confirm the resolved package's buildDecide includes the flag).`,
     }
   }
 
@@ -533,7 +461,6 @@ export async function runAgentDirectorStartupGate(
 // ---------------------------------------------------------------------------
 
 export {
-  MIN_AD_VERSION,
   DEFAULT_STORE_PATH,
   AD_STATE_DB_PATH as DEFAULT_STATE_DB_PATH,
   SUPPORTED_PLATFORMS,

package/src/install-check.ts

@@ -0,0 +1,268 @@
+/**
+ * install-check.ts — SR-5 shared install-check module.
+ *
+ * Source of truth for "is agent-director system-installed at a version
+ * meeting AD's declared floor?" — consumed by:
+ *   - The `bun run install-check` script (Epic 2).
+ *   - The install-cscb skill (Epic 3).
+ *
+ * The startup gate (Epic 1, agent-director-startup.ts) does NOT call this
+ * module — AD's own `Client.create()` enforces the same floor against the
+ * same `dist/version-floor.json`, so there are two callers that drive the
+ * same enforcement path. CSCB never duplicates the floor decision.
+ *
+ * The module is strictly side-effect-free:
+ *   - No process.exit.
+ *   - No disk writes.
+ *   - No stdout / stderr output.
+ *
+ * Callers own all presentation, exit code, and skill-instruction-block
+ * appending decisions.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import semver from 'semver'
+import {
+  DEV_SENTINEL_VERSION,
+  ErrSystemInstallNotFound,
+  ErrSystemInstallTooOld,
+  ErrSystemInstallUnreachable,
+  resolveSystemBinary,
+} from 'agent-director'
+import type { UnreachableReason } from 'agent-director'
+
+/** Canonical class labels emitted by the check; mirrors the startup gate's. */
+export type InstallCheckClassLabel =
+  | 'ad-system-install-not-found'
+  | 'ad-system-install-too-old'
+  | 'ad-system-install-unreachable'
+  | 'ad-version-floor-unreadable'
+
+/** Success arm: AD is installed, version satisfies the declared floor. */
+export interface InstallCheckSuccess {
+  ok: true
+  binaryPath: string
+  binaryVersion: string
+  floor: string
+}
+
+/** Failure arm: one of the four canonical class labels. */
+export interface InstallCheckFailure {
+  ok: false
+  classLabel: InstallCheckClassLabel
+  message: string
+  detail: Record<string, unknown>
+}
+
+export type InstallCheckResult = InstallCheckSuccess | InstallCheckFailure
+
+/**
+ * Cached `.min_binary_version` value, or the cached failure-arm result for
+ * the `ad-version-floor-unreadable` class so we surface the same shape on
+ * every call without re-reading a known-bad file.
+ */
+let cachedFloor: string | InstallCheckFailure | null = null
+
+/**
+ * Read AD's `dist/version-floor.json` via the subpath export and return the
+ * `.min_binary_version` value. Returns a pre-built failure-arm result on
+ * any failure mode (missing file, parse error, missing/non-string field).
+ */
+function loadFloor(): string | InstallCheckFailure {
+  if (cachedFloor !== null) return cachedFloor
+
+  let resolved: string
+  try {
+    resolved = import.meta.resolve('agent-director/dist/version-floor.json')
+  } catch (err) {
+    cachedFloor = {
+      ok: false,
+      classLabel: 'ad-version-floor-unreadable',
+      message:
+        `Could not resolve 'agent-director/dist/version-floor.json' from the installed ` +
+        `agent-director package. Reinstall agent-director from npm and retry.`,
+      detail: { underlying: (err as Error).message },
+    }
+    return cachedFloor
+  }
+
+  let raw: string
+  try {
+    raw = readFileSync(fileURLToPath(resolved), 'utf-8')
+  } catch (err) {
+    cachedFloor = {
+      ok: false,
+      classLabel: 'ad-version-floor-unreadable',
+      message:
+        `Could not read agent-director's dist/version-floor.json. ` +
+        `Reinstall agent-director from npm and retry.`,
+      detail: { underlying: (err as Error).message },
+    }
+    return cachedFloor
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    cachedFloor = {
+      ok: false,
+      classLabel: 'ad-version-floor-unreadable',
+      message:
+        `agent-director's dist/version-floor.json failed to parse as JSON. ` +
+        `Reinstall agent-director from npm and retry.`,
+      detail: { underlying: (err as Error).message },
+    }
+    return cachedFloor
+  }
+
+  const floor = (parsed as { min_binary_version?: unknown } | null)?.min_binary_version
+  if (typeof floor !== 'string' || floor.length === 0) {
+    cachedFloor = {
+      ok: false,
+      classLabel: 'ad-version-floor-unreadable',
+      message:
+        `agent-director's dist/version-floor.json is missing the required '.min_binary_version' field ` +
+        `(or it is not a non-empty string). Reinstall agent-director from npm and retry.`,
+      detail: { parsed },
+    }
+    return cachedFloor
+  }
+
+  cachedFloor = floor
+  return floor
+}
+
+/**
+ * Strip a leading 'v' from a version string, idempotent for inputs that
+ * already lack the prefix. AD has historically shipped both forms.
+ */
+function stripLeadingV(version: string): string {
+  return version.startsWith('v') ? version.slice(1) : version
+}
+
+/**
+ * Run the full check. See module header for semantics. The result is one of
+ * five shapes: success, or one of the four failure class labels.
+ */
+export async function runInstallCheck(): Promise<InstallCheckResult> {
+  const floorOrFailure = loadFloor()
+  if (typeof floorOrFailure !== 'string') return floorOrFailure
+  const floor = floorOrFailure
+
+  let resolved: { path: string; version: string }
+  try {
+    resolved = await resolveSystemBinary()
+  } catch (err) {
+    if (err instanceof ErrSystemInstallNotFound) {
+      return {
+        ok: false,
+        classLabel: 'ad-system-install-not-found',
+        message:
+          `agent-director not found on PATH or at the standard install path. ` +
+          `Install agent-director system-wide and retry.`,
+        detail: { checkedLocations: err.checkedLocations },
+      }
+    }
+    if (err instanceof ErrSystemInstallTooOld) {
+      return {
+        ok: false,
+        classLabel: 'ad-system-install-too-old',
+        message:
+          `agent-director system install at ${err.binaryPath} reports version ${err.actualVersion}, ` +
+          `which is below the declared floor ${err.requiredVersion}. Upgrade agent-director and retry.`,
+        detail: {
+          detected: err.actualVersion,
+          required: err.requiredVersion,
+          binaryPath: err.binaryPath,
+        },
+      }
+    }
+    if (err instanceof ErrSystemInstallUnreachable) {
+      const reason: UnreachableReason = err.reason
+      return {
+        ok: false,
+        classLabel: 'ad-system-install-unreachable',
+        message:
+          `agent-director system install at ${err.binaryPath} is unreachable. ` +
+          `Reason: ${reason}. Diagnose with the install-cscb skill or re-install agent-director.`,
+        detail: {
+          reason,
+          binaryPath: err.binaryPath,
+          diagnostic: err.diagnostic,
+          exitCode: err.exitCode,
+          signal: err.signal,
+        },
+      }
+    }
+    // Non-typed throw — surface verbatim under the unreachable label so
+    // callers have one failure-arm shape to dispatch on.
+    return {
+      ok: false,
+      classLabel: 'ad-system-install-unreachable',
+      message:
+        `agent-director system install probe threw an unexpected error: ` +
+        `${(err as Error).message ?? String(err)}. Re-install agent-director or file a bug.`,
+      detail: { underlying: String(err), reason: 'other' as UnreachableReason },
+    }
+  }
+
+  const detectedRaw = resolved.version
+
+  // SR-5: sentinel-equality short-circuit. A detected version exactly equal
+  // to DEV_SENTINEL_VERSION passes unconditionally — this is how locally-
+  // built dev binaries (without a real semver) pass the check.
+  if (detectedRaw === DEV_SENTINEL_VERSION) {
+    return {
+      ok: true,
+      binaryPath: resolved.path,
+      binaryVersion: detectedRaw,
+      floor,
+    }
+  }
+
+  const detected = stripLeadingV(detectedRaw)
+  if (!semver.gte(detected, floor)) {
+    return {
+      ok: false,
+      classLabel: 'ad-system-install-too-old',
+      message:
+        `agent-director system install at ${resolved.path} reports version ${detectedRaw}, ` +
+        `which is below the declared floor ${floor}. Upgrade agent-director and retry.`,
+      detail: { detected: detectedRaw, required: floor, binaryPath: resolved.path },
+    }
+  }
+
+  return {
+    ok: true,
+    binaryPath: resolved.path,
+    binaryVersion: detectedRaw,
+    floor,
+  }
+}
+
+/**
+ * @internal Test-only — reset the cached floor so subsequent calls re-read
+ * `dist/version-floor.json`. Used by the install-check tests to exercise
+ * both the cache and the per-failure-mode read paths.
+ */
+export function resetCacheForTests(): void {
+  cachedFloor = null
+}
+
+/**
+ * @internal Test-only — pre-populate the floor cache with a synthetic value
+ * (or a pre-built failure-arm result) so tests can drive every code path
+ * without mocking `node:fs`. Tests must call `resetCacheForTests()` in
+ * teardown to leave the module in a clean state for the next test file.
+ *
+ * Pass a `string` to simulate a successful read of `dist/version-floor.json`
+ * with that `.min_binary_version` value. Pass an `InstallCheckFailure` to
+ * simulate a malformed-JSON / missing-field / unresolvable-subpath read.
+ */
+export function setFloorForTests(value: string | InstallCheckFailure): void {
+  cachedFloor = value
+}

package/src/install-skill-pointer.ts

@@ -0,0 +1,123 @@
+/**
+ * install-skill-pointer.ts — Render the manual-fetch instructions block
+ * appended to the gate's three system-install typed-error failure messages
+ * (SR-4.5, SR-9.3).
+ *
+ * The block tells the operator where to fetch `skills/install-cscb/SKILL.md`
+ * from CSCB's GitHub repo, where to place it under `~/.claude/skills/`, and
+ * how to invoke the skill once installed. The skill itself walks the user
+ * through the interactive `agent-director` install/upgrade flow.
+ *
+ * The append-on-three-branches rule lives in `agent-director-startup.ts` —
+ * this module only renders. The block is appended verbatim regardless of
+ * whether the skill is already installed; the gate cannot detect that and
+ * must not try.
+ *
+ * Public API:
+ *   - renderInstallSkillInstructions(): string  — production wrapper; reads
+ *     `package.json` once at module init, normalizes `repository.url`, and
+ *     renders. Cached for the life of the process.
+ *   - renderInstallSkillInstructionsFrom(repositoryUrl): string  — pure
+ *     function used by tests to feed synthetic `repository.url` values
+ *     without `mock.module`. Throws on missing / non-string / unparseable
+ *     input.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** In-repo path of the install skill — module-local constant, not derived from package.json. */
+const IN_REPO_SKILL_PATH = 'skills/install-cscb/SKILL.md'
+
+/** Target path under `~/.claude/skills/` where the user must place SKILL.md. */
+const TARGET_SKILL_PATH = '~/.claude/skills/install-cscb/SKILL.md'
+
+/** Literal slash-command the user invokes after installing the skill. */
+const SKILL_INVOCATION_COMMAND = '/install-cscb'
+
+/**
+ * Normalize a `repository.url` value to a plain `https://github.com/<owner>/<repo>`
+ * base URL. Strips a leading `git+` prefix and a trailing `.git` suffix.
+ *
+ * Throws a CSCB-internal packaging-bug Error when the input cannot be normalized
+ * to a `https://github.com/...` form — this is a CSCB bug, not a runtime
+ * condition, so failing loudly is correct.
+ */
+export function normalizeRepositoryUrl(repositoryUrl: string): string {
+  let url = repositoryUrl
+  if (url.startsWith('git+')) url = url.slice(4)
+  if (url.endsWith('.git')) url = url.slice(0, -4)
+  if (!url.startsWith('https://github.com/')) {
+    throw new Error(
+      `install-skill-pointer: repository.url=${repositoryUrl} does not normalize to ` +
+        `a https://github.com/<owner>/<repo> base URL — CSCB packaging bug.`,
+    )
+  }
+  return url
+}
+
+/**
+ * Pure render function. Used by tests with synthetic `repository.url`
+ * inputs. The production wrapper below reads `package.json` once and
+ * forwards the value here.
+ */
+export function renderInstallSkillInstructionsFrom(repositoryUrl: string): string {
+  if (typeof repositoryUrl !== 'string' || repositoryUrl.length === 0) {
+    throw new Error(
+      `install-skill-pointer: repository.url is missing or not a string — CSCB packaging bug.`,
+    )
+  }
+  const base = normalizeRepositoryUrl(repositoryUrl)
+  const skillUrl = `${base}/blob/main/${IN_REPO_SKILL_PATH}`
+  return [
+    '',
+    'Interactive remediation is available via the install-cscb skill.',
+    `Fetch the skill from: ${skillUrl}`,
+    `Place it at: ${TARGET_SKILL_PATH}`,
+    `Then run: ${SKILL_INVOCATION_COMMAND}`,
+  ].join('\n')
+}
+
+/**
+ * Read this package's `repository.url` once at module init. Throws at module
+ * init when the field is missing / non-string — a CSCB packaging bug.
+ */
+function readRepositoryUrl(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url))
+  const pkgPath = join(moduleDir, '..', 'package.json')
+  const raw = readFileSync(pkgPath, 'utf-8')
+  const pkg = JSON.parse(raw) as { repository?: { url?: unknown } }
+  const url = pkg.repository?.url
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new Error(
+      `install-skill-pointer: package.json repository.url is missing or not a string — CSCB packaging bug.`,
+    )
+  }
+  return url
+}
+
+/** Cached production-rendered block. Populated lazily on first call. */
+let cachedBlock: string | null = null
+
+/**
+ * Production wrapper: render the block using this package's `repository.url`.
+ * Cached for the life of the process; idempotent.
+ */
+export function renderInstallSkillInstructions(): string {
+  if (cachedBlock === null) {
+    cachedBlock = renderInstallSkillInstructionsFrom(readRepositoryUrl())
+  }
+  return cachedBlock
+}
+
+/**
+ * @internal Test-only — reset the cached block so the production wrapper
+ * re-reads `package.json` on the next call. Used by the helper's own tests
+ * to exercise the cache + the read path.
+ */
+export function resetCacheForTests(): void {
+  cachedBlock = null
+}

package/src/postinstall.ts

@@ -18,8 +18,8 @@ import { MCP_SERVER_NAME } from './config.ts'
 
 /**
  * Read the agent-director dependency range from the shipping package.json.
- * Same pattern as src/agent-director-client.ts's MIN_AD_VERSION derivation —
- * one source of truth for the AD version requirement.
+ * One source of truth for the AD version requirement; used in the
+ * postinstall-probe failure warning to point operators at the right pin.
  */
 export function readAdDependencyRange(): string {
   const pkgPath = resolve(dirname(import.meta.filename), '..', 'package.json')
@@ -149,19 +149,21 @@ export function runPostinstall(options: PostinstallOptions = {}): void {
 export async function runAgentDirectorPostinstallProbe(): Promise<void> {
   try {
     const ad = await import('agent-director')
-    // Construct + version() probe. Client construction is synchronous;
-    // any platform / Bun / subprocess-resolution error fires here and is
-    // caught below.
-    const client = new ad.Client({
+    // AD 0.7.0+ exposes an async `Client.create()` factory; the constructor
+    // is protected. Any platform / Bun / subprocess-resolution error fires
+    // here (Err* subclasses + system-install errors) and is caught below.
+    const client = await ad.Client.create({
       storePath: '~/.agent-director/state.db',
       createIfMissing: true,
     })
     try {
-      const v = await client.version({})
-      const adVersion = v.version.replace(/^v/, '')
+      // Now that Client.create() has resolved, the binary version is on the
+      // Client itself (binaryVersion getter, AD 0.7.0+). Skip the verb-call
+      // probe — the factory already enforced the floor.
+      const adVersion = client.binaryVersion.replace(/^v/, '')
       console.log(`postinstall: agent-director ${adVersion} OK`)
     } finally {
-      try { client.close() } catch { /* close never throws but be defensive */ }
+      try { client.close() } catch { /* defensive */ }
     }
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err)