claude-slack-channel-bots 0.6.7 → 0.7.1

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.1",
   "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "src/*.ts",
     "!src/*.test.ts",
     "scripts/fixup-bun-cache.ts",
+    "scripts/install-check.ts",
     "slack-app-manifest.yml",
     "README.md",
     "skills/"
@@ -22,6 +23,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 +31,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/scripts/install-check.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env bun
+/**
+ * scripts/install-check.ts — `bun run install-check` entry point.
+ *
+ * SR-6: standalone diagnostic command. Calls runInstallCheck() once,
+ * renders the result to stdout (success) or stderr (failure), and exits
+ * with the appropriate code.
+ *
+ * Appends the manual-skill-install instructions block to every failure
+ * class EXCEPT ad-version-floor-unreadable — that case's remediation is
+ * "reinstall agent-director from npm," not "install the install skill."
+ *
+ * The script MUST NOT prompt for input, MUST NOT run any install command,
+ * MUST NOT attempt to fetch the install skill. It is purely diagnostic.
+ *
+ * Not wired to any npm/bun lifecycle (no preinstall, postinstall, prepare,
+ * prepublishOnly). Operator runs it manually via `bun run install-check`.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+import { runInstallCheck } from '../src/install-check.ts'
+import type { InstallCheckResult } from '../src/install-check.ts'
+import { renderInstallSkillInstructions } from '../src/install-skill-pointer.ts'
+
+export function renderSuccess(result: InstallCheckResult & { ok: true }): string {
+  return [
+    'agent-director install check: OK',
+    `  binary:  ${result.binaryPath}`,
+    `  version: ${result.binaryVersion}`,
+    `  floor:   ${result.floor}`,
+  ].join('\n')
+}
+
+export function renderFailure(result: InstallCheckResult & { ok: false }): string {
+  const lines = [
+    `agent-director install check: FAILED (${result.classLabel})`,
+    result.message,
+  ]
+  if (Object.keys(result.detail).length > 0) {
+    lines.push(`  detail: ${JSON.stringify(result.detail)}`)
+  }
+  return lines.join('\n')
+}
+
+export async function main(): Promise<void> {
+  const result = await runInstallCheck()
+
+  if (result.ok) {
+    process.stdout.write(renderSuccess(result) + '\n')
+    process.exit(0)
+  }
+
+  let body = renderFailure(result)
+  // SR-6.3: append the manual-skill-install block to every failure class
+  // EXCEPT ad-version-floor-unreadable (the skill can't fix a corrupt AD
+  // package; remediation is "reinstall agent-director").
+  if (result.classLabel !== 'ad-version-floor-unreadable') {
+    body += renderInstallSkillInstructions()
+  }
+  process.stderr.write(body + '\n')
+  process.exit(1)
+}
+
+if (import.meta.main) {
+  void main()
+}

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,