agent-director 0.11.1 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,32 +16,17 @@ Requires Bun >=1.0.21. The package ships pure JavaScript — there are
16
16
  optional platform dependencies. `bun add --ignore-scripts agent-director`
17
17
  is a no-op and installs the library with identical functionality.
18
18
 
19
- **You must separately install the CLI binary on the host.** The
20
- fastest path on a fresh machine is the one-liner published with the
21
- agent-director GitHub repo — it downloads the binary for your OS/arch
22
- from the [latest release](https://github.com/gabemahoney/agent-director/releases/latest)
23
- and sets up `~/.agent-director/`:
24
-
25
- ```sh
26
- curl -fsSL https://raw.githubusercontent.com/gabemahoney/agent-director/main/skills/install-agent-director/install.sh | bash -s -- --from-release
27
- ```
28
-
29
- `Client.create()` discovers the installed binary at construction time
30
- (either at `~/.agent-director/bin/agent-director` or anywhere on
31
- `$PATH`) and rejects if it cannot find one. Other supported install
32
- mechanisms — `install.sh --binary <path> --admin-binary <path>` with
33
- locally-staged artifacts, or any drop-in copy onto `$PATH` — are documented in the
34
- [repo README](https://github.com/gabemahoney/agent-director#install-the-cli).
19
+ Install the CLI separately using the [install guide](../../docs/install.md).
20
+ `Client.create()` finds it at the standard install path or on `$PATH`;
21
+ its version must meet the client floor.
35
22
 
36
23
  ## Supported platforms
37
24
 
38
25
  - `linux/x64` (Linux on x86_64)
39
26
  - `darwin/arm64` (Apple Silicon Mac)
40
27
 
41
- The library's published npm package admits installs on any host (no
42
- `os`/`cpu` restrictions on the library itself); the platform gate is
43
- the CLI binary's own platform coverage. The CLI must be installed
44
- separately per the platform list above.
28
+ Package installation may also succeed on `linux/arm64` and `darwin/x64`;
29
+ those are not supported CLI install hosts. See [Requirements](../../docs/install.md#requirements).
45
30
 
46
31
  ## Quick start
47
32
 
@@ -53,6 +38,9 @@ const v = await client.version({});
53
38
  console.log(v.version);
54
39
  ```
55
40
 
41
+ The `version` result is `{ version, commit, config_dir }`; `config_dir` is the
42
+ directory the CLI keeps its files in, `~/.config/agent-director` (unexpanded).
43
+
56
44
  Explicit `try/finally` (portable fallback):
57
45
 
58
46
  ```ts
@@ -65,78 +53,126 @@ try {
65
53
  }
66
54
  ```
67
55
 
68
- All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
56
+ All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.config/agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
69
57
 
70
- `ClientOptions` overrides forward verbatim to the CLI subprocess as global flags:
58
+ `ClientOptions` overrides forward to the CLI subprocess as global flags:
71
59
 
72
60
  - `storePath` → `--store-path`
73
61
  - `home` → `--home`
74
62
  - `tmuxCommand` → `--tmux-command`
63
+ - `createIfMissing: false` → `--create-if-missing false` (`true` forwards nothing)
75
64
 
76
- The CLI, not the client, expands a `~` in them, against `HOME` and nothing
77
- else (never the passwd entry's home). It applies `home` first, so with `home`
65
+ The paths are forwarded verbatim. The CLI, not the client, expands a `~` in
66
+ them, against `HOME` and nothing else (never the passwd entry's home). It applies `home` first, so with `home`
78
67
  set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
79
68
  `HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
80
69
  `ErrInvalidFlags`, and with no `home` either, every call that opens the store
81
70
  is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
82
- expand its config path `~/.agent-director/config.toml`.
71
+ expand its config path `~/.config/agent-director/config.toml`.
72
+
73
+ Set them when the consumer needs to override that field's CLI default.
83
74
 
84
- Set them only when the consumer needs to override the CLI's default for that field.
75
+ By default, the first call that opens the store creates it when it does not
76
+ exist (parent directories, file and schema). With `createIfMissing: false`,
77
+ such a call rejects with `ErrStoreOpen` (`database not initialized`) and
78
+ creates none of it; an existing store opens as usual, and calls that open no
79
+ store, such as `version`, are unaffected.
80
+
81
+ For spawning under another home or store, use
82
+ [Permissions](../../docs/permissions.md#one-spawn-under-another-home-or-store).
85
83
 
86
84
  ## Verb examples
87
85
 
88
- ### spawn
86
+ Shared CLI use is in [Usage](../../docs/usage.md).
89
87
 
90
- Launch a tracked Claude Code instance in a new tmux session.
88
+ A call that carries an old name of a renamed key (on any verb) throws
89
+ `ErrInvalidFlags` before the client starts any process; its description names
90
+ the new key.
91
91
 
92
- ```sh
93
- agent-director spawn --cwd ~/my-project
94
- ```
92
+ ### spawn
93
+
94
+ Launch a tracked agent in a new tmux session. A spawn names its agent, `"claude"` or `"codex"` (case-sensitive), in `agent` or through its template; with neither it throws `ErrAgentMissing`. An empty `agent` counts as not given.
95
95
 
96
96
  ```ts
97
- const result = await client.spawn({ cwd: "~/my-project" });
98
- console.log(result.claude_instance_id);
97
+ const result = await client.spawn({ cwd: "~/my-project", agent: "claude" });
98
+ console.log(result.instance_id);
99
99
  ```
100
100
 
101
+ The `SpawnResult` has `instance_id`, `pre_trust` and optional
102
+ `dropped_args?: string[]`. On a switching reuse, `dropped_args` contains
103
+ removed original argument tokens in argv order; it is omitted when empty.
104
+ The switch starts fresh and resumes nothing. Selector lists and reporting
105
+ rules are in the
106
+ [caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals).
107
+
108
+ Same-agent reuse retains current-life session history and subagent records;
109
+ switching agents starts another life, including when switching back.
110
+ `resume` continues only the recorded agent's latest reported session and
111
+ never selects an archived one. See [Usage](../../docs/usage.md#naming-the-agent)
112
+ and [Transcript recovery](../../docs/caller-contract.md#transcript-recovery).
113
+
101
114
  ### status
102
115
 
103
116
  Get the current lifecycle state of a Spawn.
104
117
 
105
- ```sh
106
- agent-director status --claude-instance-id <id>
107
- ```
108
-
109
118
  ```ts
110
- const result = await client.status({ claude_instance_id: "<id>" });
119
+ const result = await client.status({ instance_id: "<id>" });
111
120
  console.log(result.state);
112
121
  ```
113
122
 
123
+ With `[state] settle_ms` set in the CLI's `~/.config/agent-director/config.toml`,
124
+ `status`, `get` and `list` report the settled state: a state a hook wrote
125
+ shows only once it has held that long, the last settled state until then;
126
+ `ended`, `missing` and a state a verb wrote show at once, and `list`'s
127
+ `state` filter matches the settled state. Every verb that acts on a Spawn
128
+ judges its live state, which can be newer. The client adds no field and
129
+ no state value for it.
130
+
114
131
  ### list
115
132
 
116
133
  Query Spawns with optional filters.
117
134
 
118
- ```sh
119
- agent-director list --state waiting
120
- ```
121
-
122
135
  ```ts
123
136
  const result = await client.list({ state: ["waiting"] });
124
137
  for (const spawn of result.spawns) {
125
- console.log(spawn.claude_instance_id, spawn.state);
138
+ console.log(spawn.instance_id, spawn.state, spawn.agent);
126
139
  }
127
140
  ```
128
141
 
129
- ### sendKeys
142
+ Each row, like `get`'s result, carries `agent` (`"claude"` or `"codex"`), the agent the row runs.
130
143
 
131
- Send text to the agent's own pane, then one Enter to submit it. An empty
132
- `text` sends the Enter only, submitting what is already typed.
144
+ ### listSubagents
133
145
 
134
- ```sh
135
- agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
146
+ Read the subagent records across launches of one agent's current life, and
147
+ whether the agent is tracked. `subagent_id` is unique among the returned
148
+ records; earlier-life records remain stored but are hidden. See
149
+ [visibility and retention](../../docs/usage.md#read-an-agents-subagent-records).
150
+
151
+ ```ts
152
+ const result = await client.listSubagents({ instance_id: "<id>" });
153
+ console.log(result.tracked);
154
+ for (const sub of result.subagents) {
155
+ console.log(sub.subagent_id, sub.state, sub.subagent_type ?? "unknown type");
156
+ }
136
157
  ```
137
158
 
159
+ `tracked` is `false`, with `subagents` `[]`, for a `"codex"` agent (from its spawn, and after every `resume` or reuse of its id) and for a `"claude"` agent that predates subagent tracking (it becomes `true` when that agent is next resumed or its id is reused). `subagents` is never null; a field with no known value is `null`, and times are RFC 3339 UTC strings. The fields and values are described in [Read an agent's subagent records](../../docs/usage.md#read-an-agents-subagent-records).
160
+
161
+ ### sendKeys
162
+
163
+ Send text to the agent's own pane, then one Enter to submit it. An empty
164
+ or omitted `text` sends the Enter only, submitting what is already typed.
165
+ `no_enter: true` types the text without the Enter, and `key` sends one key
166
+ alone (`"Escape"`, `"Enter"`, `"Up"`, `"Down"`, `"Tab"`, or one character),
167
+ never followed by Enter. With `expect_pane_sha256` (the `pane_sha256` of
168
+ the `readPane` you looked at, with its `n_lines`), nothing is sent if the
169
+ pane changed since (`ErrPaneChanged`); on a relayed Spawn a match also
170
+ passes the dialog hold (`ErrDialogMaybeOpen`, see "Answering a request at
171
+ the pane" below). Pass it only for a pane a person or an LLM judged, never
172
+ from an automatic flow.
173
+
138
174
  ```ts
139
- await client.sendKeys({ claude_instance_id: "<id>", text: "what is 2+2?" });
175
+ await client.sendKeys({ instance_id: "<id>", text: "what is 2+2?" });
140
176
  ```
141
177
 
142
178
  Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
@@ -147,30 +183,23 @@ still rejected. A `pending` row whose launch start or launch token is not record
147
183
  only a session an earlier launch left behind is found, gets
148
184
  `ErrSpawnNotInteractive` and nothing is sent.
149
185
 
150
- Send an empty string with `allow_pending: true` to press Enter and dismiss such
151
- a prompt:
152
-
153
- ```ts
154
- await client.sendKeys({
155
- claude_instance_id: "<id>",
156
- text: "",
157
- allow_pending: true,
158
- });
159
- ```
186
+ `liveness_note: "unreported"` means an alive agent has not reported since
187
+ launch. Action on a pending row belongs to the
188
+ [caller contract](../../docs/caller-contract.md#caller-contract).
160
189
 
161
190
  ### readPane
162
191
 
163
192
  Read the last N lines of the agent's own pane (default 25).
164
193
 
165
- ```sh
166
- agent-director read-pane --claude-instance-id <id> --n-lines 50
167
- ```
168
-
169
194
  ```ts
170
- const result = await client.readPane({ claude_instance_id: "<id>", n_lines: 50 });
171
- console.log(result.pane);
195
+ const result = await client.readPane({ instance_id: "<id>", n_lines: 50 });
196
+ console.log(result.pane, result.pane_sha256);
172
197
  ```
173
198
 
199
+ `pane_sha256` is the SHA-256 of exactly the bytes of `pane`; pass it back as
200
+ `sendKeys`' or `recordPaneAnswer`'s `expect_pane_sha256`, with the same
201
+ `n_lines`, when you act on what this pane shows.
202
+
174
203
  `readPane` has no state guard — it works on `pending`, `ended`, and `missing`
175
204
  rows as well as live ones. The `allow_pending` flag is accepted for symmetry
176
205
  with `sendKeys` but has no behavioral effect.
@@ -187,47 +216,167 @@ resolves with `kill_sent: false`; that is not verification that the agent
187
216
  exited. `kill` never changes the row's state: `find-missing` marks the row once
188
217
  its agent process is gone.
189
218
 
190
- ```sh
191
- agent-director kill --claude-instance-id <id>
192
- ```
193
-
194
219
  ```ts
195
- const { kill_sent } = await client.kill({ claude_instance_id: "<id>" });
220
+ const { kill_sent } = await client.kill({ instance_id: "<id>" });
196
221
  console.log(kill_sent);
197
222
  ```
198
223
 
199
224
  Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
200
- retry later), `ErrTmuxSessionConflict` (CONFLICT: a human must look),
201
- `ErrTmuxNotAvailable` (ENVIRONMENT: an operator must fix the environment) and
202
- `ErrSpawnNotFound`. None of these means the agent is dead. The caller must run
203
- as the same user and in the same tmux environment as the agents. See the "tmux
204
- transport" table under [Errors](#errors).
225
+ retry later), `ErrTmuxSessionConflict` (CONFLICT),
226
+ `ErrTmuxNotAvailable` (ENVIRONMENT) and
227
+ `ErrSpawnNotFound`. None of these proves exit. See the [caller contract](../../docs/caller-contract.md#caller-contract)
228
+ for the live-row sequence and finished-row limits.
229
+
230
+ ### pause
231
+
232
+ Shut down a `waiting` Spawn: type `/exit` in its pane and wait up to
233
+ `pause.timeout_seconds` for `ended`. A finished Spawn is a no-op. A live Codex
234
+ Spawn whose agent already exited with an end report resolves, in any live
235
+ state, having typed nothing, and its row is `ended`; otherwise any live state
236
+ but `waiting` throws `ErrSpawnNotPausable`. On a Codex Spawn
237
+ `pause` ends the row itself once the agent exits (see the
238
+ [caller contract](../../docs/caller-contract.md#when-a-codex-agent-exits)).
239
+
240
+ ```ts
241
+ await client.pause({ instance_id: "<id>" });
242
+ ```
243
+
244
+ `pause` is held like a `sendKeys` without `request_token` and without
245
+ `expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
246
+ `ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
247
+ with the same `errDetails`, typing nothing and starting no wait, whenever
248
+ that `sendKeys` would. It takes no pane hash, so it stays held until the
249
+ agent's hooks prove each request gone (after a subagent's denied request, or on
250
+ a Codex Spawn an allowed one, until the agent ends). Stopping a held spawn and handling these refusals are in the
251
+ [caller contract](../../docs/caller-contract.md#permission-relay).
205
252
 
206
253
  ### makeTemplate
207
254
 
208
- Save a reusable spawn preset. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
255
+ Save a reusable spawn preset. Pass `agent` to bake in the template's agent; a template with `agent_args` needs one. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
209
256
 
210
- ```sh
211
- agent-director make-template --name dev --cwd /repos/widget --overwrite
257
+ ```ts
258
+ await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude", overwrite: true });
212
259
  ```
213
260
 
261
+ ### decide
262
+
263
+ Answer a relayed permission request of a Spawn launched with
264
+ `relay_mode: "on"`. `decide` records the verdict, waits at most 1 s for the
265
+ agent's relay hook to confirm it, and resolves with the request's
266
+ `delivery`.
267
+
214
268
  ```ts
215
- await client.makeTemplate({ name: "dev", cwd: "/repos/widget", overwrite: true });
269
+ const result = await client.decide({
270
+ instance_id: "<id>",
271
+ request_token: "<token>",
272
+ decision: "allow",
273
+ max_wait_ms: 2000, // at most your deadline minus 1 s
274
+ });
275
+ if (result.delivery === "not_confirmed") {
276
+ const later = await client.getPermission({ request_token: "<token>" });
277
+ console.log(later.delivery, later.confirm_by);
278
+ }
216
279
  ```
217
280
 
218
- ## Consumption
281
+ `"delivered"`: the relay hook confirmed the verdict before handing it to
282
+ the agent. `"not_confirmed"`: the relay hook has not confirmed the verdict;
283
+ `getPermission` exposes subsequent delivery and `confirm_by`. See the
284
+ [caller contract](../../docs/caller-contract.md#permission-relay) for
285
+ confirmation handling. `decision`
286
+ is the verdict recorded, not the outcome: read `delivery`. `max_wait_ms`
287
+ bounds the whole call, its reads and its write, and has no default; without
288
+ it `decide` can wait up to the store's busy timeout. `decide` rejects,
289
+ recording no verdict, with `ErrRelayFallenBack` when the request's relay
290
+ hook is gone and took no verdict, with `ErrStoreBusy` when `max_wait_ms`
291
+ ran out before the verdict was recorded, and with
292
+ `ErrNoOpenPermissionRequest` when no open request has that token or the
293
+ request is closed. Pane answers, retries and closed-request handling are
294
+ in the [caller contract](../../docs/caller-contract.md#permission-relay). The
295
+ `permission_requests` of `get` and of each `list` row carry the same
296
+ delivery fields, `pane_answer` and `pane_as` included, for requests that
297
+ still await an answer only; a row can read `waiting`, `working` or
298
+ `ask_user` while a request is still open, so follow the requests you track
299
+ with `getPermission`.
300
+ `decision_reason` is one of `"operator"`, `"timeout"`, `"find_missing"`,
301
+ `"ended"`, `"pane"`, `"pane_outside"` and `"tool_ran"`. For a reason you
302
+ do not know, read the recorded verdict from `decision` (`null` for a
303
+ `"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
304
+ `pane_answer`; never read a reason as a verdict.
305
+
306
+ `proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, its
307
+ tool ran (a Claude Spawn only); `"turn_end"`, the turn of the agent that asked
308
+ ended after it was written, which a Codex main agent's Interrupt also proves; or
309
+ `"agent_gone"`, the agent ended) say when and how the agent's
310
+ hooks showed the request's dialog gone; `"delivered"` and a pane answer are
311
+ agent-director's own records, not proof. `get`'s `unproven_requests` lists
312
+ every request not yet proven gone, each with `unproven_since`. A request
313
+ that reads `"delivered"` or closed at the pane can remain unproven; its dialog
314
+ may still be there. Handling is in the
315
+ [caller contract](../../docs/caller-contract.md#permission-relay).
316
+
317
+ ### Answering a request at the pane
318
+
319
+ `sendKeys` with a `request_token` answers a request at the pane.
320
+ The [caller contract](../../docs/caller-contract.md#permission-relay) owns
321
+ when to use a pane answer and how to judge the screen. Example:
219
322
 
220
- The supported consumption mode is Bun-runtime ESM:
323
+ ```ts
324
+ const seen = await client.readPane({ instance_id: "<id>" });
325
+ // having looked at seen.pane, the caller picks the key and the verdict it gives
326
+ await client.sendKeys({
327
+ instance_id: "<id>",
328
+ request_token: "<token>",
329
+ as: "deny",
330
+ key: "<key>",
331
+ expect_pane_sha256: seen.pane_sha256,
332
+ });
333
+ ```
221
334
 
222
- ```sh
223
- bun add agent-director
335
+ It sends exactly that key and no Enter, then records the request
336
+ `pane_answer` `"sent"` with `decision` your `as` and `decision_reason`
337
+ `"pane"`. `as`, `key` and `expect_pane_sha256` are required.
338
+ An `ErrInternal` whose `errDetails` is a `PaneKeySentDetails`
339
+ (`key_sent` `true`) means the key was sent but not recorded; hash use and
340
+ recovery are in the [caller contract](../../docs/caller-contract.md#permission-relay).
341
+ `recordPaneAnswer` records an answer made outside agent-director and types
342
+ nothing:
343
+
344
+ ```ts
345
+ try {
346
+ await client.recordPaneAnswer({
347
+ request_token: "<token>",
348
+ as: "unknown",
349
+ expect_pane_sha256: "<pane_sha256>",
350
+ });
351
+ } catch (e) {
352
+ if (e instanceof ErrClaimTooSoon) {
353
+ // errDetails is a ClaimTooSoonDetails here.
354
+ console.log("retry at", e.errDetails?.["not_before"]);
355
+ } else {
356
+ throw e;
357
+ }
358
+ }
224
359
  ```
225
360
 
361
+ `as` is the caller's claim; use `"unknown"` when the answer was not seen.
362
+ `ErrPaneChanged`, `ErrPaneAnswerInProgress`, `ErrClaimTooSoon` and
363
+ `ErrDialogMaybeOpen` carry structured facts in `errDetails`.
364
+ `recordPaneAnswer` types nothing; `sendKeys` with a request token sends one
365
+ key and records it. Delivery does not prove the dialog gone. See
366
+ [Permissions](../../docs/permissions.md) and the
367
+ [caller contract](../../docs/caller-contract.md#permission-relay) for the
368
+ complete pane-answer and held-agent procedures.
369
+
370
+ ## Consumption
371
+
372
+ The supported consumption mode is Bun-runtime ESM:
373
+
226
374
  ```ts
227
375
  import { Client } from "agent-director";
228
376
  ```
229
377
 
230
- The package uses `import.meta.resolve` and `import.meta.url` at runtime to locate the installed `package.json`. Bundling it through webpack or other bundlers that do not support these features is not supported.
378
+ Bundling without support for module-relative resource resolution is unsupported.
379
+ Use the package as Bun-runtime ESM.
231
380
 
232
381
  ## Versioning
233
382
 
@@ -240,8 +389,7 @@ The library version equals the agent-director release tag — released in lockst
240
389
  ## Minimum required CLI binary version
241
390
 
242
391
  The library declares the minimum CLI-binary version it requires on two
243
- surfaces, both backed by the same single source of truth shipped in the
244
- published npm package at `dist/version-floor.json`.
392
+ surfaces, available from the published package at `dist/version-floor.json`.
245
393
 
246
394
  **TS export (preferred for JS/TS consumers):**
247
395
 
@@ -256,8 +404,7 @@ if (binaryVersion === DEV_SENTINEL_VERSION) {
256
404
  ```
257
405
 
258
406
  `MIN_BINARY_VERSION` is a strict-SemVer-2.0 string (e.g. `0.7.0` or
259
- `0.7.0-rc1`). The value is inlined into the bundle at build time; no
260
- runtime file read. `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
407
+ `0.7.0-rc1`). `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
261
408
  — a dev-built CLI binary stamps this value and satisfies any floor by
262
409
  short-circuit. The library returns the binary's reported version
263
410
  verbatim — no leading-`v` stripping, no normalization. Consumers
@@ -273,21 +420,24 @@ jq -r .min_binary_version < node_modules/agent-director/dist/version-floor.json
273
420
  This pattern is part of the public contract. It does not require the
274
421
  agent-director CLI to be installed, does not spawn a JS runtime, and
275
422
  does not require any agent-director-specific environment setup — read
276
- the field from the file at the stable documented path. The `-r` flag
277
- returns a bare string suitable for shell comparison.
423
+ the field from the file at the stable documented path.
278
424
 
279
425
  ## Supported Bun versions
280
426
 
281
- Minimum: `>=1.0.21` (set in `engines.bun`). Tested on Bun 1.3.x as of this release. The `using` block syntax (Explicit Resource Management) requires Bun 1.0.21+.
427
+ Minimum: `>=1.0.21` (set in `engines.bun`). The `using` block syntax (Explicit Resource Management) requires Bun 1.0.21+.
282
428
 
283
429
  ## Errors
284
430
 
285
- Every error thrown by this package extends `AgentDirectorError`, so you can catch by subclass with `instanceof`:
431
+ Named client and CLI errors extend `AgentDirectorError`, so you can catch
432
+ by subclass with `instanceof`. Subprocess spawn failures can also surface
433
+ as their original errors: an unclassified `ENOENT` (neither the binary nor
434
+ the caller's cwd is verifiably gone) and every other spawn failure are
435
+ re-thrown unchanged. Keep a general fallback catch for these paths:
286
436
 
287
437
  ```ts
288
438
  import { Client, ErrSpawnNotFound } from "agent-director";
289
439
  try {
290
- await client.status({ claude_instance_id: "bogus" });
440
+ await client.status({ instance_id: "bogus" });
291
441
  } catch (e) {
292
442
  if (e instanceof ErrSpawnNotFound) {
293
443
  // recover
@@ -297,24 +447,24 @@ try {
297
447
  }
298
448
  ```
299
449
 
300
- The public typed-error surface falls into four groups. Every class named below is exported from the package entry point. The tables are self-sufficient for choosing what to catch; the raw generated catalog for the group-4 classes lives in [`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json).
301
-
302
- ### Realistic catch-site shortlist
303
-
304
- Most services only need to route on the "agent-director is sick" set. Alert on these eight:
305
-
306
- - `ErrSystemInstallNotFound`
307
- - `ErrSystemInstallTooOld`
308
- - `ErrSystemInstallUnreachable`
309
- - `ErrCallerCwdUnreachable`
310
- - `ErrSystemInstallDisappeared`
311
- - `ErrCallTimeout`
312
- - `ErrStoreOpen`
313
- - `ErrConfigMalformed`
314
-
315
- Also alert on an `ErrUnknownErrorName` whose `unknownName` is `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`: the store needs an operator (see the per-call infrastructure table below). Let everything else propagate.
316
-
317
- Everything else is either **programmer error** (bad arguments — fix the call site, do not retry) or a **normal operational signal** (an expected verb outcome you branch on, like "no such spawn" or "already decided"). `ErrConsumerSignal` sits in between: it is a runtime infrastructure failure, but a routine one during shutdown, so treat it as an operational signal rather than a page.
450
+ Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
451
+ the error envelope's optional `err_details` object, or `null`. Five errors
452
+ carry one, typed as exported interfaces: `ErrRelayFallenBack`
453
+ (`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
454
+ (`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
455
+ `ErrPaneChanged` (`PaneChangedDetails`) and `ErrDialogMaybeOpen`
456
+ (`DialogMaybeOpenDetails`). So does the `ErrInternal` of a
457
+ pane answer whose key was sent but not recorded (`PaneKeySentDetails`:
458
+ `key_sent` `true` and `request_token`). Read facts from `errDetails`, never
459
+ from `errDescription`.
460
+
461
+ The public typed-error surface falls into four groups. Every class named below is exported from the package entry point. The tables are self-sufficient for choosing what to catch; the CLI error contract also applies to group 4.
462
+
463
+ For retry, escalation and shared CLI refusal handling see the
464
+ [caller contract](../../docs/caller-contract.md). Binary installation and
465
+ upgrade procedures are in [Installation](../../docs/install.md), and
466
+ human repairs in [Operator actions](../../docs/operator-actions.md).
467
+ The tables below describe the typed classes and their fields.
318
468
 
319
469
  ### 1. Library lifecycle
320
470
 
@@ -323,19 +473,19 @@ Raised by the client wrapper itself, independent of any agent-director binary.
323
473
  | Error | When it fires |
324
474
  |---|---|
325
475
  | `ErrClientClosed` | A verb was called on a `Client` after `close()`/disposal. Obtain a fresh handle with `Client.create()`. Programmer error. |
326
- | `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Upgrade Bun. Fires at construction. |
476
+ | `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Fires at construction. |
327
477
 
328
478
  ### 2. System install (agent-director binary)
329
479
 
330
- The "AD is sick" group. **Construction-time** errors are thrown by `Client.create()` / `resolveSystemBinary()` before any verb runs; **runtime** errors are thrown at verb-dispatch time on a client that constructed successfully.
480
+ **Construction-time** errors are thrown by `Client.create()` / `resolveSystemBinary()` before any verb runs; **runtime** errors are thrown at verb-dispatch time on a client that constructed successfully.
331
481
 
332
482
  | Error | Phase | When it fires |
333
483
  |---|---|---|
334
484
  | `ErrSystemInstallNotFound` | Construction | No agent-director binary was found in any checked location. Carries `checkedLocations`. |
335
485
  | `ErrSystemInstallTooOld` | Construction | A binary was found but its version is below the required floor. Carries `actualVersion`, `requiredVersion`, `binaryPath`. |
336
486
  | `ErrSystemInstallUnreachable` | Construction | A binary was found but failed the version probe (not executable, wrong arch, non-zero exit, killed). Carries `binaryPath`, `reason`, `diagnostic`, `exitCode`, `signal`. |
337
- | `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`. Restart your service from a valid directory. |
338
- | `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`. Re-install the binary, then create a new `Client`. |
487
+ | `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`. See [Installation](../../docs/install.md) for environment requirements. |
488
+ | `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`. Installation repair is owned by [Installation](../../docs/install.md). |
339
489
 
340
490
  ### 3. Per-call infrastructure
341
491
 
@@ -343,13 +493,13 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
343
493
 
344
494
  | Error | When it fires | Category |
345
495
  |---|---|---|
346
- | `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational — include in your "AD is sick" alert set. |
496
+ | `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational; see the caller contract. |
347
497
  | `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
348
- | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for: either the binary is newer than the client, or the name is one the binary emits but the shared catalog leaves out (for example `ErrInternal`, `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`). Carries `unknownName` (the real `err_name`) and `envelope`. | Read `unknownName`. `ErrSchemaMismatch` or `ErrSchemaMigrationRequired`: operational — the store needs an operator and no verb ran, so alert, as for `ErrStoreOpen`. A name the binary has and this client lacks because the binary is newer: version error — upgrade the client. |
498
+ | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for. This client has a class for every `err_name` the binary of its own version gives, so the binary is of a different version, most often a newer one. Carries `unknownName` (the real `err_name`) and `envelope`. | Version error; see [Installation](../../docs/install.md). |
349
499
 
350
500
  ### 4. Catalog-derived (CLI-side validation)
351
501
 
352
- These 44 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input, a verb's own state preconditions, or a config or store the CLI cannot open — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
502
+ These classes correspond to the shared CLI `err_name` contract. They surface bad input, a verb's own state preconditions, a config or store the CLI cannot open, or a failure of the CLI itself — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
353
503
 
354
504
  **cwd validation** (bad `cwd` argument to `spawn` — programmer error):
355
505
 
@@ -360,14 +510,19 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
360
510
  | `ErrCwdNotFound` | `cwd` resolved to a path that does not exist on disk. |
361
511
  | `ErrCwdNotADirectory` | `cwd` resolved to a file (or other non-directory inode). |
362
512
 
363
- **spawn config validation** (bad `spawn` arguments — programmer error):
513
+ **spawn and template config validation** (bad `spawn` or `makeTemplate` arguments — programmer error):
364
514
 
365
515
  | Error | When it fires |
366
516
  |---|---|
367
517
  | `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
368
- | `ErrSpawnDeniedFlag` | `claude_args` contains a flag the supervisor must own (`--settings`, `--resume`, `--continue`, `--print`, `--output-format`). |
369
- | `ErrReservedEnvKey` | `extra_env` contains an `AGENT_DIRECTOR_*` key (reserved prefix). |
370
- | `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `claude_instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
518
+ | `ErrSpawnDeniedFlag` | The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst` or `features.hooks`, `--disable hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
519
+ | `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"` or `"codex"`), or put one in the template. |
520
+ | `ErrAgentInvalid` | `agent` is neither `"claude"` nor `"codex"` (the value is case-sensitive); nothing is written. |
521
+ | `ErrAgentArgsMismatch` | The template's `agent_args` are for another agent than the one this spawn resolves to, so they are not inherited; nothing is written. Spawn that agent, or pass this call's own non-empty `agent_args`, which replace the template's. |
522
+ | `ErrTemplateAgentMissing` | A template has `agent_args` and names no agent. From `makeTemplate` (`agent_args` without `agent`) and from a `spawn` that loads such a template; nothing is written. Give the template an `agent`, or remove its `agent_args`. |
523
+ | `ErrPermissionsUnsupported` | A `"codex"` spawn, or a `makeTemplate` with `agent: "codex"`, carries an `allow`, `deny` or `ask` entry; nothing is written. Drop the lists and set permission rules in the group's Codex folder, with Codex's own permission controls. |
524
+ | `ErrReservedEnvKey` | From `spawn`: an `extra_env` key (a template's included) is reserved or is not a valid env-var name; nothing is written or launched, and the description says which. Reserved: an `AGENT_DIRECTOR_*` key, or a key that sets `HOME` (`HOME` itself, or one such as `HOME=/x`), with any value, an empty one included. An `extra_env` `HOME` would send the agent's hook events to another agent-director store; set an absolute `CLAUDE_CONFIG_DIR` (a Claude Code agent) or `CODEX_HOME` (a Codex agent) to give the agent its own config. Not a valid name: the key is empty, or contains `=` or a NUL character; give each variable its own name as the key and its value as the value (`{ CLAUDE_CONFIG_DIR: "/cfg" }`, not `{ "CLAUDE_CONFIG_DIR=/cfg": "" }`). This client refuses an invalid key in the call's `extra_env` itself, before it runs the CLI. From `makeTemplate`: the template's `extra_env` has such a key, reserved or not a valid name, refused by spawn's own check; no template is written or replaced, so none is saved that `spawn` would refuse (this client refuses an invalid key itself, as for `spawn`). From `resume`: the row's stored `extra_env` has a key that sets `HOME` or is not a valid name (a row spawned before spawn refused it); nothing is written or launched. Shared repair and reuse handling is in [Spawn and template input refusals](../../docs/caller-contract.md#spawn-and-template-input-refusals); a fresh conversation has no memory of the old conversation. |
525
+ | `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
371
526
 
372
527
  **tmux session naming** (bad `tmux_session_name` — programmer error):
373
528
 
@@ -381,13 +536,13 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
381
536
 
382
537
  | Error | When it fires |
383
538
  |---|---|
384
- | `ErrSpawnNotFound` | No spawn row matches the supplied `claude_instance_id`. |
539
+ | `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
385
540
  | `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. |
386
541
  | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
387
- | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry the pause; the agent may still be running. |
388
- | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. If that launch was abandoned or failed, `find-missing` marks the row `missing` once the pending grace period has passed; then a row with a `claude_session_id` (typically a resume's launch) can be resumed, and one without (typically a spawn's or reuse's launch), if `get` still shows no `claude_session_id`, is spawned again with `reuse_finished: true`, as the error says. An agent that reports in late records a `claude_session_id`, and its row, once `missing`, can be resumed instead. Also returned when the row changed after `resume` examined it; nothing is written. |
389
- | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart, or a spawn's or reuse's launch that never reported in and that `find-missing` marked `missing`), so there is nothing to resume — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
390
- | `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
542
+ | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. The agent may still be running; see [Caller contract](../../docs/caller-contract.md). |
543
+ | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Abandoned or failed launch handling is owned by [Caller contract](../../docs/caller-contract.md) and [Maintenance](../../docs/maintenance.md). Also returned when the row changed after `resume` examined it; nothing is written. |
544
+ | `ErrNoSessionId` | The spawn has no `session_id` (killed before its first SessionStart, or a spawn's or reuse's launch that never reported in and that `find-missing` marked `missing`), so there is nothing to resume; recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
545
+ | `ErrJsonlMissing` | The current session's resume JSONL could not be located at any candidate path (for a Codex agent, only its current recorded path; older sessions are never tried); recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
391
546
  | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
392
547
  | `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
393
548
 
@@ -396,10 +551,10 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
396
551
  | Error | Class | When it fires |
397
552
  |---|---|---|
398
553
  | `ErrTmuxNotAvailable` | ENVIRONMENT | The `tmux` binary is not on PATH or refuses to execute, the tmux socket is not accessible to this user, or its per-user socket directory cannot be used (`spawn` then writes nothing). `kill`, `resume`, `readPane`, `sendKeys` and `pause` return it too: tmux could not be run, the socket is not accessible to this user, or this is not the tmux server the agent was launched on. |
399
- | `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled; the new row stays `pending`. After tmux answers "duplicate session", `spawn` returns it only when the session holding the requested name was gone by the re-lookup; the new row is then ended (the error says if it was not), and the error names the instance id (a minted one included) and the retry: spawn that `claude_instance_id` again with `reuse_finished: true` once the name is free (if the row was not ended, once `get` shows it `ended` or `missing`), since a plain `spawn` of the id collides with its row. From `resume`, the session could not be created or labelled, or after "duplicate session" no session held the name when it was looked up again; the row is restored to `ended` or `missing` (the error says if it was not). A name found held is never this error. |
400
- | `ErrTmuxUnresponsive` | UNAVAILABLE (transient) | tmux did not answer in time, or gave a reply agent-director does not recognise. From `spawn`'s or `resume`'s session-creating call: the session may have been created and the row stays `pending`; do not retry until `get` shows the row `ended` or `missing`; then a `spawn` of an explicit `claude_instance_id` is retried with `reuse_finished: true`, since a plain `spawn` of the id collides with its finished row. From a plain `spawn` after "duplicate session": the re-lookup could not be read, or more than one session's name matches the requested name; the new row is ended (the error says if it was not) and the error names the retry with `reuse_finished: true`, as for `ErrTmuxSessionCreate`. From `resume`'s check before the launch, with nothing written: the row's own session or agent process appears to still be stopping or still starting, tmux's answer could not be read, or more than one session's name matches the row's session name; retry later. After "duplicate session" at the create, the same cases, and the row is restored; if it was not, the error says so and names the next step in place of "retry later": do not retry until `get` shows the row `ended` or `missing`, or, for a removed row, later a `spawn` of the id starts afresh. From `kill`: the lookup or the pane listing could not be read (nothing was done), or a kill was sent, the agent process could not be checked and the follow-up lookup could not be read (the kill may or may not have taken effect); retry later with backoff. From `readPane`, `sendKeys` and `pause`: tmux did not answer usably; after a timed-out send the keys (or `/exit`) may have been delivered. Where `sendKeys`' text may be typed, the error names the next step instead of "retry later", because the same call would type the text a second time: after a timed-out text call, `readPane` and, if the text is typed, `sendKeys` with empty `text`, otherwise the same `sendKeys`; after a failed or timed-out Enter, `sendKeys` with empty `text`, which submits it. A `pause` is retried later as it is: before typing `/exit` it clears the line the agent's cursor is on, so an `/exit` the failed `pause` left typed is not doubled. |
401
- | `ErrTmuxSessionConflict` | CONFLICT (permanent until a human looks) | A tmux session conflict that needs a human. From `spawn` with an explicit `claude_instance_id` that has no row: a session of this store still labelled with that id is left over from an earlier life, or labels conflict; nothing is written. From a plain `spawn` whose requested tmux session name is already held (tmux answered "duplicate session"): the holder is a session left over from an earlier life of this id, another row's session, a session of another agent-director store, or one with no valid instance id, or labels conflict; the new row is ended (the error says if it was not) and the error names the blocking session. Another row's or another store's session is another agent and is never ended; the holding session is never read or typed into. From `resume` of a finished row, before anything is written and with no session touched: a session holds the row's session name (another row's session, a session of another agent-director store, or one with no valid instance id), a session is left over from an earlier life of this id, the row's own old session (or its agent process still running with no session) is past the stopping window and the starting-session bound, or labels conflict; the error names the blocking session. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). None of these means the agent is dead. From `kill` on a live row: the session found is not this launch's session (it carries the label of an earlier launch with this row's own id), or labels conflict; no kill was sent. From `readPane`, `sendKeys` and `pause`: the agent's pane was not found, a session an earlier launch left behind is there (for `readPane`, more than one; for `sendKeys`, on a live row), or labels conflict; nothing was read or sent. See "Operator actions" in the agent-director README. |
402
- | `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry `kill` later; never `delete` the row. |
554
+ | `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled. A plain launch normally stays `pending`; a duplicate-name re-lookup finding no holder ends its new row. Resume and reuse attempt a guarded restore after a non-timeout failure; the description reports whether it applied. |
555
+ | `ErrTmuxUnresponsive` | UNAVAILABLE | tmux did not answer usably, or a launch still appears to be starting or stopping. A timed-out launch stays `pending`; after a timed-out send, keys may have been delivered. See the [caller contract](../../docs/caller-contract.md#caller-contract) before retrying. |
556
+ | `ErrTmuxSessionConflict` | CONFLICT | A held name, a session left over from an earlier life (an earlier launch), conflicting labels, or the agent pane was not found. The description names the blocker and whether a new row was ended or a prior row restored. Nothing is sent to a conflicting session. Human repair is owned by [Operator actions](../../docs/operator-actions.md). |
557
+ | `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry and refusal handling is owned by [Caller contract](../../docs/caller-contract.md). |
403
558
  | `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
404
559
  | `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
405
560
 
@@ -409,13 +564,18 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
409
564
 
410
565
  | Error | When it fires |
411
566
  |---|---|
412
- | `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. Time-bounded: refused until 1 s after every one of the spawn's permission requests' relay windows has elapsed; from then this guard lets `send-keys` through. |
413
- | `ErrRelayFallenBack` | `decide` was called on an open request whose relay window has run out (from 1 s before it ends); no verdict was recorded. Answer at the pane with `send-keys` once its relay guard releases, 1 s after every request's window (for this request, at most 2 s after the refusal); until then `send-keys` may throw `ErrSendKeysWhileRelayed`. |
567
+ | `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while a relay hook may still answer a request. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
568
+ | `ErrRelayFallenBack` | A request's relay hook is gone and acked no verdict, with no pane answer recorded through agent-director: no answer from the relay reached the agent. Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
569
+ | `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by the agent's hooks (a Claude agent's tool's PostToolUse, the main agent's end of turn after it (on a Codex Spawn, its `Stop` or Interrupt), or the agent's end), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A subagent's denied request holds until the agent ends, and on a Codex Spawn so does an allowed one. `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
570
+ | `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
571
+ | `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
572
+ | `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
414
573
  | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
415
- | `ErrInvalidDecision` | `--decision` was neither `allow` nor `deny`. |
574
+ | `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
416
575
  | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
417
- | `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair (or it was already decided). |
418
- | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. |
576
+ | `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or `find-missing` or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when `find-missing` marked it `missing`) before the request's relay hook confirmed a verdict recorded on it, `find-missing`'s own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (`"delivered"` only if its relay hook confirmed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
577
+ | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay hook denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the hook recorded that deny with its confirmation before returning it to the agent, so there is nothing to answer at the pane. It also includes a request `find-missing` denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay hook confirmed, or one already closed at the pane, throws it too. |
578
+ | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and the bound ran out, during its reads or its write, before its verdict was recorded: another agent-director process held the store that long (or, for a request recorded by an older binary, `decide` would have had to wait past the bound for the end of its relay window). Nothing was recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). Once the verdict is recorded, `decide` never throws it: a bound reached while it waits for the relay hook's confirmation resolves with `delivery` `"not_confirmed"`. Without `max_wait_ms`, `decide` never throws it. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout; nothing was sent or recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). |
419
579
  | `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
420
580
  | `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
421
581
 
@@ -425,22 +585,35 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
425
585
  |---|---|
426
586
  | `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
427
587
  | `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
428
- | `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, wrong types, bad enums). |
429
- | `ErrTemplateExists` | `make-template` target already exists; the verb never overwrites. |
588
+ | `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, an `agent` other than `claude` or `codex`, the old name of the `agent_args` key, wrong types, bad enums, or one key set under names that differ only in letter case, such as `RELAY_MODE` and `relay_mode`). `makeTemplate` also throws it, before writing anything, for an `agent` that is not exactly `claude` or `codex`. |
589
+ | `ErrTemplateExists` | `make-template` target already exists and `overwrite` is not `true`. |
430
590
 
431
591
  **misc**:
432
592
 
433
593
  | Error | When it fires |
434
594
  |---|---|
435
- | `ErrInvalidFlags` | CLI flag parsing rejected the invocation, or `spawn` was given an explicit `claude_instance_id` containing an ASCII control character (0x00–0x1f or 0x7f). |
595
+ | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; a call carried an old name of a renamed key (thrown before any process starts, naming the new key); `spawn` was given an explicit `instance_id` containing an ASCII control character (0x00–0x1f or 0x7f); `readPane`'s `n_lines` or `list`'s `limit` is negative (0 or omitted gives the default: 25 lines, no cap); `decide` was given a negative `max_wait_ms`; `sendKeys` was given params that do not fit together (a pane answer without `as`, `key` or `expect_pane_sha256` or with `text`; `key` with a non-empty `text`; `no_enter` with neither; `as` without `request_token`; a `key` that is neither a named key nor one character; a malformed hash); or `recordPaneAnswer` was given an `as` other than `"allow"`, `"deny"` or `"unknown"`, or a missing or malformed hash. Nothing was changed, sent or recorded. |
596
+
597
+ **CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational):
598
+
599
+ | Error | When it fires |
600
+ |---|---|
601
+ | `ErrConfigMalformed` | The CLI refused its config file, `~/.config/agent-director/config.toml`: it cannot be read, does not parse as TOML, or sets a value agent-director refuses (for example a negative `[pause] timeout_seconds`). The description names the file and why: the parse error, or every refused key with its value and the values it allows. Every call that opens the store fails this way until an operator fixes the file. See the caller contract for handling. |
602
+ | `ErrStoreOpen` | The CLI could not open its store; the description says what failed. This includes `HOME` unset or empty with no `home` option (`api: expand config path: …`): every call that opens the store is then refused, whatever `storePath` is. With `createIfMissing: false` it includes a store that does not exist (`database not initialized`); nothing was created. It says nothing about any agent. |
603
+ | `ErrSchemaMismatch` | The CLI refused to open its store: the store was written by a newer agent-director than the binary (`found user_version=<N>, want <M>`), or it has no valid store id. The description says which. Nothing was written, and every call that opens the store fails this way until an operator acts: a newer store needs the agent-director release that wrote it. See Operator actions for recovery. It says nothing about any agent. |
604
+ | `ErrSchemaMigrationRequired` | The CLI refused to open its store: the store is older than the binary and must be migrated first. The description gives both schema versions. Nothing was written, and every call that opens the store fails this way until an administrator migrates the store; no call through this client can. See the caller contract for handling. It says nothing about any agent. |
605
+ | `ErrOldLayout` | The CLI refused to open its store: it was about to open the default store (no `storePath`, and no `[store] db_path` in its config file), no store exists in `~/.config/agent-director`, and the old directory exists. Nothing was created, and every call that opens the store fails this way until an operator runs this release's `install.sh`. See the caller contract for handling. It says nothing about any agent. |
436
606
 
437
- **CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational; both are in the "AD is sick" alert set):
607
+ **CLI itself** (the CLI failed, or does not know the verb, rather than refusing the call's input or state):
438
608
 
439
609
  | Error | When it fires |
440
610
  |---|---|
441
- | `ErrConfigMalformed` | The CLI refused its config file, `~/.agent-director/config.toml`: it cannot be read, does not parse as TOML, or sets a value agent-director refuses (for example a negative `[pause] timeout_seconds`). The description names the file and why: the parse error, or every refused key with its value and the values it allows. Every call that opens the store fails this way until an operator fixes the file. Do not retry or act on any agent; alert an operator once, and never read it as an agent being dead. |
442
- | `ErrStoreOpen` | The CLI could not open its store; the description says what failed. This includes `HOME` unset or empty with no `home` option (`api: expand config path: …`): every call that opens the store is then refused, whatever `storePath` is. It says nothing about any agent. |
611
+ | `ErrInternal` | A CLI failure with no more specific name. Its description reports what failed and whether anything changed. A pane answer whose key was sent but not recorded carries `PaneKeySentDetails` with `key_sent: true`; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
612
+ | `ErrJSONMarshal` | The verb ran and succeeded, but the CLI could not write its JSON result, so the result is lost and whatever the call changes was changed (a `spawn` launched its agent). A bug in agent-director. Check with `get`, `status` or `list` before you repeat a call that changes something. |
613
+ | `ErrUnknownVerb` | The binary does not know the called verb. No verb ran; binary and client versions differ. See [Installation](../../docs/install.md). |
614
+ | `ErrTrailWrite` | Only the CLI's internal `trail-emit` command gives it, when it cannot write its trail event. No method of this client runs `trail-emit`, so a call through this client does not get it. |
443
615
 
444
- ## Architecture
616
+ ## See also
445
617
 
446
- See [`../../docs/architecture.md`](../../docs/architecture.md) for the internal design. Dedicated subsections cover: Client lifecycle, the subprocess call recipe, Per-platform packaging, Error mapping, TS smoke-test harness, and TS envelope-diff regression.
618
+ [Caller contract](../../docs/caller-contract.md), [Permissions](../../docs/permissions.md)
619
+ and [Installation](../../docs/install.md) own shared procedures.