agent-director 0.10.0 → 0.11.1

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
@@ -29,8 +29,8 @@ curl -fsSL https://raw.githubusercontent.com/gabemahoney/agent-director/main/ski
29
29
  `Client.create()` discovers the installed binary at construction time
30
30
  (either at `~/.agent-director/bin/agent-director` or anywhere on
31
31
  `$PATH`) and rejects if it cannot find one. Other supported install
32
- mechanisms — `install.sh --binary <path>` with a locally-staged
33
- artifact, or any drop-in copy onto `$PATH` — are documented in the
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
34
  [repo README](https://github.com/gabemahoney/agent-director#install-the-cli).
35
35
 
36
36
  ## Supported platforms
@@ -65,7 +65,7 @@ try {
65
65
  }
66
66
  ```
67
67
 
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. Tilde expansion (`~` → home directory) is handled automatically before paths are forwarded to the CLI subprocess. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
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"]`).
69
69
 
70
70
  `ClientOptions` overrides forward verbatim to the CLI subprocess as global flags:
71
71
 
@@ -73,6 +73,14 @@ All constructor options are optional. Omitted fields fall back to the CLI binary
73
73
  - `home` → `--home`
74
74
  - `tmuxCommand` → `--tmux-command`
75
75
 
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`
78
+ set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
79
+ `HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
80
+ `ErrInvalidFlags`, and with no `home` either, every call that opens the store
81
+ is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
82
+ expand its config path `~/.agent-director/config.toml`.
83
+
76
84
  Set them only when the consumer needs to override the CLI's default for that field.
77
85
 
78
86
  ## Verb examples
@@ -120,7 +128,8 @@ for (const spawn of result.spawns) {
120
128
 
121
129
  ### sendKeys
122
130
 
123
- Send text to a Spawn's tmux pane.
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.
124
133
 
125
134
  ```sh
126
135
  agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
@@ -130,14 +139,16 @@ agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
130
139
  await client.sendKeys({ claude_instance_id: "<id>", text: "what is 2+2?" });
131
140
  ```
132
141
 
133
- Pass `allow_pending: true` to also permit sending to a `pending` Spawn (state
134
- before `SessionStart` fires). The primary use case is dismissing interactive
135
- prompts that Claude Code renders before the session becomes interactive — for
136
- example the `--dangerously-load-development-channels` safety warning. `ended`
137
- and `missing` Spawns are still rejected regardless of the flag.
142
+ Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
143
+ reuse or resume) whose agent has not reported in yet, for example to dismiss a
144
+ prompt the agent shows before it reports in. Keys are delivered only to a
145
+ session started by the row's current launch. `ended` and `missing` rows are
146
+ still rejected. A `pending` row whose launch start or launch token is not recorded, or where
147
+ only a session an earlier launch left behind is found, gets
148
+ `ErrSpawnNotInteractive` and nothing is sent.
138
149
 
139
- Send an empty string with `allow_pending: true` to press Enter and dismiss the
140
- pre-`SessionStart` prompt:
150
+ Send an empty string with `allow_pending: true` to press Enter and dismiss such
151
+ a prompt:
141
152
 
142
153
  ```ts
143
154
  await client.sendKeys({
@@ -149,7 +160,7 @@ await client.sendKeys({
149
160
 
150
161
  ### readPane
151
162
 
152
- Read the last N lines of a Spawn's tmux pane (default 25).
163
+ Read the last N lines of the agent's own pane (default 25).
153
164
 
154
165
  ```sh
155
166
  agent-director read-pane --claude-instance-id <id> --n-lines 50
@@ -161,23 +172,37 @@ console.log(result.pane);
161
172
  ```
162
173
 
163
174
  `readPane` has no state guard — it works on `pending`, `ended`, and `missing`
164
- Spawns as well as live ones. The `allow_pending` flag is accepted for symmetry
175
+ rows as well as live ones. The `allow_pending` flag is accepted for symmetry
165
176
  with `sendKeys` but has no behavioral effect.
166
177
 
167
178
  ---
168
179
 
169
180
  ### kill
170
181
 
171
- Terminate a Spawn's tmux session.
182
+ End the agent of a live Spawn's current launch (`pending` included). `kill`
183
+ resolves only once the agent process is gone, and returns `{ kill_sent }`:
184
+ `true` when a kill was sent to the agent's pane or its session, `false` when
185
+ none was. On a finished Spawn (`ended` or `missing`) `kill` is a no-op that
186
+ resolves with `kill_sent: false`; that is not verification that the agent
187
+ exited. `kill` never changes the row's state: `find-missing` marks the row once
188
+ its agent process is gone.
172
189
 
173
190
  ```sh
174
191
  agent-director kill --claude-instance-id <id>
175
192
  ```
176
193
 
177
194
  ```ts
178
- await client.kill({ claude_instance_id: "<id>" });
195
+ const { kill_sent } = await client.kill({ claude_instance_id: "<id>" });
196
+ console.log(kill_sent);
179
197
  ```
180
198
 
199
+ 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).
205
+
181
206
  ### makeTemplate
182
207
 
183
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.
@@ -276,7 +301,7 @@ The public typed-error surface falls into four groups. Every class named below i
276
301
 
277
302
  ### Realistic catch-site shortlist
278
303
 
279
- Most services only need to route on the "agent-director is sick" set. Alert on these six and let everything else propagate:
304
+ Most services only need to route on the "agent-director is sick" set. Alert on these eight:
280
305
 
281
306
  - `ErrSystemInstallNotFound`
282
307
  - `ErrSystemInstallTooOld`
@@ -284,6 +309,10 @@ Most services only need to route on the "agent-director is sick" set. Alert on t
284
309
  - `ErrCallerCwdUnreachable`
285
310
  - `ErrSystemInstallDisappeared`
286
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.
287
316
 
288
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.
289
318
 
@@ -316,11 +345,11 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
316
345
  |---|---|---|
317
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. |
318
347
  | `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
319
- | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client version does not recognize (client older than the binary). Carries `unknownName`, `envelope`. | Programmer/version error — upgrade the client. |
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. |
320
349
 
321
350
  ### 4. Catalog-derived (CLI-side validation)
322
351
 
323
- These 37 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 or a verb's own state preconditions — 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.
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.
324
353
 
325
354
  **cwd validation** (bad `cwd` argument to `spawn` — programmer error):
326
355
 
@@ -338,14 +367,14 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
338
367
  | `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
339
368
  | `ErrSpawnDeniedFlag` | `claude_args` contains a flag the supervisor must own (`--settings`, `--resume`, `--continue`, `--print`, `--output-format`). |
340
369
  | `ErrReservedEnvKey` | `extra_env` contains an `AGENT_DIRECTOR_*` key (reserved prefix). |
341
- | `ErrInstanceIdCollision` | The supplied `claude_instance_id` is already in use by a live spawn. |
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. |
342
371
 
343
- **tmux session naming** (bad `--tmux-session-name` — programmer error):
372
+ **tmux session naming** (bad `tmux_session_name` — programmer error):
344
373
 
345
374
  | Error | When it fires |
346
375
  |---|---|
347
- | `ErrTmuxSessionNameEmpty` | `--tmux-session-name` was explicitly supplied but empty. |
348
- | `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, an ASCII control character, or is invalid UTF-8. |
376
+ | `ErrTmuxSessionNameEmpty` | `tmux_session_name` was explicitly supplied but empty. |
377
+ | `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, `$`, `\`, an ASCII control character, or is invalid UTF-8. |
349
378
  | `ErrTmuxSessionNameTooLong` | The name exceeds the app-layer byte cap. |
350
379
 
351
380
  **spawn state / lookup** (verb preconditions — mostly normal operational signals):
@@ -353,29 +382,35 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
353
382
  | Error | When it fires |
354
383
  |---|---|
355
384
  | `ErrSpawnNotFound` | No spawn row matches the supplied `claude_instance_id`. |
356
- | `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected (`AllowPending=true` relaxes the `pending` rejection). |
385
+ | `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. |
357
386
  | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
358
- | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry or `kill`. |
359
- | `ErrSpawnNotResumable` | The target spawn is not terminal (`ended`/`missing`), so it cannot be resumed. |
360
- | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), so there is nothing to resume — `delete` and spawn fresh. |
361
- | `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — `delete` and spawn fresh. |
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. |
362
391
  | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
363
- | `ErrProbeUnsupported` | The liveness probe has no implementation for the current platform (`find-missing`). |
392
+ | `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. |
364
393
 
365
- **tmux transport** (infrastructure failures at the tmux layer — runtime):
394
+ **tmux transport** (infrastructure failures at the tmux layer — runtime). Each name has a class: GONE (the row's session is not there), UNAVAILABLE (transient; retry later), CONFLICT (permanent until a human looks), ENVIRONMENT (an environment problem for an operator to fix) or LAUNCH FAILURE (the launch failed).
366
395
 
367
- | Error | When it fires |
368
- |---|---|
369
- | `ErrTmuxNotAvailable` | The `tmux` binary is not on PATH or refuses to execute. |
370
- | `ErrTmuxSessionCreate` | `tmux new-session` exited non-zero (name collision, invalid cwd, missing default-shell). |
371
- | `ErrTmuxSendKeys` | `tmux send-keys` exited non-zero (typically no live pane). |
372
- | `ErrTmuxCaptureFailed` | `tmux capture-pane` exited non-zero (session/pane vanished mid-call). |
396
+ | Error | Class | When it fires |
397
+ |---|---|---|
398
+ | `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. |
403
+ | `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
404
+ | `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
405
+
406
+ Only a GONE error means the row's session is not there (for `kill`, GONE is success); no other tmux error ever means the agent is dead.
373
407
 
374
408
  **relay / permissions** (relay-mode and permission-decision preconditions — normal operational signals):
375
409
 
376
410
  | Error | When it fires |
377
411
  |---|---|
378
- | `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. |
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`. |
379
414
  | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
380
415
  | `ErrInvalidDecision` | `--decision` was neither `allow` nor `deny`. |
381
416
  | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
@@ -397,7 +432,14 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
397
432
 
398
433
  | Error | When it fires |
399
434
  |---|---|
400
- | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; not tied to any single verb handler. |
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). |
436
+
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):
438
+
439
+ | Error | When it fires |
440
+ |---|---|
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. |
401
443
 
402
444
  ## Architecture
403
445
 
package/dist/errors.d.ts CHANGED
@@ -69,8 +69,10 @@ export declare class ErrCallTimeout extends AgentDirectorError {
69
69
  /**
70
70
  * ErrUnknownErrorName — thrown when a subprocess JSON envelope contains an
71
71
  * `err_name` field that is not present in the static catalog-derived error map.
72
- * This indicates the Go-side catalog has a new entry that the TS catalog has
73
- * not yet been regenerated to include.
72
+ * Either the binary is newer than this client, or the name is one the binary
73
+ * emits but the shared catalog leaves out (for example ErrInternal or
74
+ * ErrSchemaMismatch; cross-ref: b.cm7). Read `unknownName` for the
75
+ * real err_name.
74
76
  *
75
77
  * Constructor: `new ErrUnknownErrorName(unknownName, envelope)`
76
78
  * - `unknownName` — the unrecognised err_name string from the envelope.
@@ -237,6 +239,15 @@ export declare class ErrTmuxSendKeys extends AgentDirectorError {
237
239
  /** Mirrors ErrTmuxCaptureFailed (package: tmux) */
238
240
  export declare class ErrTmuxCaptureFailed extends AgentDirectorError {
239
241
  }
242
+ /** Mirrors ErrTmuxUnresponsive (package: tmux) */
243
+ export declare class ErrTmuxUnresponsive extends AgentDirectorError {
244
+ }
245
+ /** Mirrors ErrTmuxSessionConflict (package: tmux) */
246
+ export declare class ErrTmuxSessionConflict extends AgentDirectorError {
247
+ }
248
+ /** Mirrors ErrTmuxKillFailed (package: tmux) */
249
+ export declare class ErrTmuxKillFailed extends AgentDirectorError {
250
+ }
240
251
  /** Mirrors ErrSpawnNotInteractive (package: api) */
241
252
  export declare class ErrSpawnNotInteractive extends AgentDirectorError {
242
253
  }
@@ -306,6 +317,12 @@ export declare class ErrMissingRequestToken extends AgentDirectorError {
306
317
  /** Mirrors ErrInvalidFlags (package: api) */
307
318
  export declare class ErrInvalidFlags extends AgentDirectorError {
308
319
  }
320
+ /** Mirrors ErrConfigMalformed (package: clisetup) */
321
+ export declare class ErrConfigMalformed extends AgentDirectorError {
322
+ }
323
+ /** Mirrors ErrStoreOpen (package: clisetup) */
324
+ export declare class ErrStoreOpen extends AgentDirectorError {
325
+ }
309
326
  /**
310
327
  * errorFromEnvelope creates a typed AgentDirectorError subclass from the
311
328
  * subprocess error envelope fields.
package/dist/index.d.ts CHANGED
@@ -7,8 +7,8 @@ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./c
7
7
  export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
8
8
  export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
9
9
  ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after valid construction
10
- ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, } from "./errors.js";
10
+ ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, } from "./errors.js";
11
11
  export type { CheckedLocation, UnreachableReason } from "./errors.js";
12
12
  export type { ClientOptions, Logger } from "./types.js";
13
13
  export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
14
- export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, DeleteParams, DeleteResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
14
+ export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
package/dist/index.js CHANGED
@@ -28,12 +28,15 @@ __export(exports_errors, {
28
28
  errorFromEnvelope: () => errorFromEnvelope,
29
29
  TS_ONLY_ERROR_NAMES: () => TS_ONLY_ERROR_NAMES,
30
30
  ErrUnknownErrorName: () => ErrUnknownErrorName,
31
+ ErrTmuxUnresponsive: () => ErrTmuxUnresponsive,
31
32
  ErrTmuxSessionNameTooLong: () => ErrTmuxSessionNameTooLong,
32
33
  ErrTmuxSessionNameInvalid: () => ErrTmuxSessionNameInvalid,
33
34
  ErrTmuxSessionNameEmpty: () => ErrTmuxSessionNameEmpty,
34
35
  ErrTmuxSessionCreate: () => ErrTmuxSessionCreate,
36
+ ErrTmuxSessionConflict: () => ErrTmuxSessionConflict,
35
37
  ErrTmuxSendKeys: () => ErrTmuxSendKeys,
36
38
  ErrTmuxNotAvailable: () => ErrTmuxNotAvailable,
39
+ ErrTmuxKillFailed: () => ErrTmuxKillFailed,
37
40
  ErrTmuxCaptureFailed: () => ErrTmuxCaptureFailed,
38
41
  ErrTemplateNotFound: () => ErrTemplateNotFound,
39
42
  ErrTemplateNameUnsafe: () => ErrTemplateNameUnsafe,
@@ -43,6 +46,7 @@ __export(exports_errors, {
43
46
  ErrSystemInstallTooOld: () => ErrSystemInstallTooOld,
44
47
  ErrSystemInstallNotFound: () => ErrSystemInstallNotFound,
45
48
  ErrSystemInstallDisappeared: () => ErrSystemInstallDisappeared,
49
+ ErrStoreOpen: () => ErrStoreOpen,
46
50
  ErrSpawnNotResumable: () => ErrSpawnNotResumable,
47
51
  ErrSpawnNotPausable: () => ErrSpawnNotPausable,
48
52
  ErrSpawnNotInteractive: () => ErrSpawnNotInteractive,
@@ -70,6 +74,7 @@ __export(exports_errors, {
70
74
  ErrCwdNotADirectory: () => ErrCwdNotADirectory,
71
75
  ErrCwdMissing: () => ErrCwdMissing,
72
76
  ErrConsumerSignal: () => ErrConsumerSignal,
77
+ ErrConfigMalformed: () => ErrConfigMalformed,
73
78
  ErrClientClosed: () => ErrClientClosed,
74
79
  ErrCallerCwdUnreachable: () => ErrCallerCwdUnreachable,
75
80
  ErrCallTimeout: () => ErrCallTimeout,
@@ -288,6 +293,15 @@ class ErrTmuxSendKeys extends AgentDirectorError {
288
293
  class ErrTmuxCaptureFailed extends AgentDirectorError {
289
294
  }
290
295
 
296
+ class ErrTmuxUnresponsive extends AgentDirectorError {
297
+ }
298
+
299
+ class ErrTmuxSessionConflict extends AgentDirectorError {
300
+ }
301
+
302
+ class ErrTmuxKillFailed extends AgentDirectorError {
303
+ }
304
+
291
305
  class ErrSpawnNotInteractive extends AgentDirectorError {
292
306
  }
293
307
 
@@ -356,6 +370,12 @@ class ErrMissingRequestToken extends AgentDirectorError {
356
370
 
357
371
  class ErrInvalidFlags extends AgentDirectorError {
358
372
  }
373
+
374
+ class ErrConfigMalformed extends AgentDirectorError {
375
+ }
376
+
377
+ class ErrStoreOpen extends AgentDirectorError {
378
+ }
359
379
  var ERROR_TABLE = {
360
380
  ErrCwdMissing,
361
381
  ErrCwdNotAPath,
@@ -377,6 +397,9 @@ var ERROR_TABLE = {
377
397
  ErrTmuxSessionCreate,
378
398
  ErrTmuxSendKeys,
379
399
  ErrTmuxCaptureFailed,
400
+ ErrTmuxUnresponsive,
401
+ ErrTmuxSessionConflict,
402
+ ErrTmuxKillFailed,
380
403
  ErrSpawnNotInteractive,
381
404
  ErrSendKeysWhileRelayed,
382
405
  ErrSpawnNotPausable,
@@ -395,7 +418,9 @@ var ERROR_TABLE = {
395
418
  ErrTemplateNotFound,
396
419
  ErrTemplateMalformed,
397
420
  ErrTemplateExists,
398
- ErrProbeUnsupported
421
+ ErrProbeUnsupported,
422
+ ErrConfigMalformed,
423
+ ErrStoreOpen
399
424
  };
400
425
  function errorFromEnvelope(verb, err_name, err_description) {
401
426
  const Ctor = ERROR_TABLE[err_name];
@@ -807,19 +832,6 @@ function checkBunVersion() {
807
832
  import { readFile } from "fs/promises";
808
833
  import { statSync as statSync2 } from "fs";
809
834
 
810
- // src/internal/tilde.ts
811
- import * as os from "os";
812
- function expandTilde(p) {
813
- if (p === "")
814
- return "";
815
- if (p !== "~" && !p.startsWith("~/"))
816
- return p;
817
- const home = process.env["HOME"] ?? os.homedir();
818
- if (p === "~")
819
- return home;
820
- return home + p.slice(1);
821
- }
822
-
823
835
  // src/internal/argv.ts
824
836
  function buildArgv(cliPath, verb, params, globalOpts) {
825
837
  const globalFlags = buildGlobalFlags(globalOpts);
@@ -864,8 +876,6 @@ function buildVerbFlags(verb, params) {
864
876
  return buildFindMissing();
865
877
  case "expire":
866
878
  return buildExpire(params);
867
- case "delete":
868
- return buildDelete(params);
869
879
  case "make-template":
870
880
  return buildMakeTemplate(params);
871
881
  case "list":
@@ -894,6 +904,8 @@ function buildSpawn(p) {
894
904
  f.push("--relay-mode", p.relay_mode);
895
905
  if (p.no_pre_trust === true)
896
906
  f.push("--no-pre-trust");
907
+ if (p.reuse_finished === true)
908
+ f.push("--reuse-finished");
897
909
  if (p.label) {
898
910
  for (const lv of p.label)
899
911
  f.push("--label", lv);
@@ -979,12 +991,6 @@ function buildExpire(p) {
979
991
  f.push("--older-than", p.older_than);
980
992
  return f;
981
993
  }
982
- function buildDelete(p) {
983
- const f = ["delete"];
984
- for (const id of p.claude_instance_id)
985
- f.push("--claude-instance-id", id);
986
- return f;
987
- }
988
994
  function buildMakeTemplate(p) {
989
995
  const f = ["make-template", "--name", p.name];
990
996
  if (p.cwd !== undefined)
@@ -1140,6 +1146,21 @@ var catalog_default = [
1140
1146
  package: "tmux",
1141
1147
  description: ""
1142
1148
  },
1149
+ {
1150
+ name: "ErrTmuxUnresponsive",
1151
+ package: "tmux",
1152
+ description: ""
1153
+ },
1154
+ {
1155
+ name: "ErrTmuxSessionConflict",
1156
+ package: "tmux",
1157
+ description: ""
1158
+ },
1159
+ {
1160
+ name: "ErrTmuxKillFailed",
1161
+ package: "tmux",
1162
+ description: ""
1163
+ },
1143
1164
  {
1144
1165
  name: "ErrSpawnNotInteractive",
1145
1166
  package: "api",
@@ -1254,6 +1275,16 @@ var catalog_default = [
1254
1275
  name: "ErrAmbiguousRequest",
1255
1276
  package: "store",
1256
1277
  description: ""
1278
+ },
1279
+ {
1280
+ name: "ErrConfigMalformed",
1281
+ package: "clisetup",
1282
+ description: ""
1283
+ },
1284
+ {
1285
+ name: "ErrStoreOpen",
1286
+ package: "clisetup",
1287
+ description: ""
1257
1288
  }
1258
1289
  ];
1259
1290
 
@@ -1317,11 +1348,11 @@ class SubprocessClient {
1317
1348
  this.#binaryVersion = init.binaryVersion;
1318
1349
  const g = {};
1319
1350
  if (opts.storePath !== undefined)
1320
- g.storePath = expandTilde(opts.storePath);
1351
+ g.storePath = opts.storePath;
1321
1352
  if (opts.tmuxCommand !== undefined)
1322
- g.tmuxCommand = expandTilde(opts.tmuxCommand);
1353
+ g.tmuxCommand = opts.tmuxCommand;
1323
1354
  if (opts.home !== undefined)
1324
- g.home = expandTilde(opts.home);
1355
+ g.home = opts.home;
1325
1356
  this.#globalOpts = g;
1326
1357
  this.#open = true;
1327
1358
  this.#tail = Promise.resolve();
@@ -1517,10 +1548,6 @@ class SubprocessClient {
1517
1548
  this.#assertOpen();
1518
1549
  return this.#enqueue("expire", params);
1519
1550
  }
1520
- async delete(params) {
1521
- this.#assertOpen();
1522
- return this.#enqueue("delete", params);
1523
- }
1524
1551
  async makeTemplate(params) {
1525
1552
  this.#assertOpen();
1526
1553
  return this.#enqueue("make-template", params);
@@ -1635,12 +1662,15 @@ export {
1635
1662
  errorFromEnvelope,
1636
1663
  MIN_BINARY_VERSION,
1637
1664
  ErrUnknownErrorName,
1665
+ ErrTmuxUnresponsive,
1638
1666
  ErrTmuxSessionNameTooLong,
1639
1667
  ErrTmuxSessionNameInvalid,
1640
1668
  ErrTmuxSessionNameEmpty,
1641
1669
  ErrTmuxSessionCreate,
1670
+ ErrTmuxSessionConflict,
1642
1671
  ErrTmuxSendKeys,
1643
1672
  ErrTmuxNotAvailable,
1673
+ ErrTmuxKillFailed,
1644
1674
  ErrTmuxCaptureFailed,
1645
1675
  ErrTemplateNotFound,
1646
1676
  ErrTemplateNameUnsafe,
@@ -1650,6 +1680,7 @@ export {
1650
1680
  ErrSystemInstallTooOld,
1651
1681
  ErrSystemInstallNotFound,
1652
1682
  ErrSystemInstallDisappeared,
1683
+ ErrStoreOpen,
1653
1684
  ErrSpawnNotResumable,
1654
1685
  ErrSpawnNotPausable,
1655
1686
  ErrSpawnNotInteractive,
@@ -1677,6 +1708,7 @@ export {
1677
1708
  ErrCwdNotADirectory,
1678
1709
  ErrCwdMissing,
1679
1710
  ErrConsumerSignal,
1711
+ ErrConfigMalformed,
1680
1712
  ErrClientClosed,
1681
1713
  ErrCallerCwdUnreachable,
1682
1714
  ErrCallTimeout,
@@ -12,11 +12,11 @@
12
12
  * - Mapping between camelCase method name and kebab CLI verb follows the
13
13
  * same mapping in src/internal/verbs.ts.
14
14
  * - Optional fields are omitted when undefined / falsy.
15
- * - Boolean flags (--no-pre-trust, --ansi, --overwrite) are only appended
16
- * when the field is explicitly true.
15
+ * - Boolean flags (--no-pre-trust, --reuse-finished, --ansi, --overwrite)
16
+ * are only appended when the field is explicitly true.
17
17
  * - Global flags (b.32k: --store-path, --home, --tmux-command) appear
18
18
  * BEFORE the verb token so the CLI's global-flag parser in
19
- * cmd/agent-director/global_flags.go strips them prior to verb dispatch.
19
+ * internal/clisetup/globalflags.go strips them prior to verb dispatch.
20
20
  *
21
21
  * Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
22
22
  *
@@ -28,15 +28,14 @@ import type { VerbName } from "./verbs.js";
28
28
  * bug b.32k. Each field is optional; when undefined the corresponding flag
29
29
  * is omitted from argv and the CLI's own default-resolution kicks in.
30
30
  *
31
- * Tilde-expansion is the caller's responsibility (typically done at Client
32
- * construction time via src/internal/tilde.ts).
31
+ * Values are forwarded verbatim; the CLI expands `~` in them (b.38a).
33
32
  */
34
33
  export interface GlobalArgvOptions {
35
- /** Tilde-expanded path forwarded to the CLI as `--store-path`. */
34
+ /** Path forwarded to the CLI as `--store-path`. */
36
35
  storePath?: string;
37
- /** Tilde-expanded path forwarded to the CLI as `--home`. */
36
+ /** Path forwarded to the CLI as `--home`. */
38
37
  home?: string;
39
- /** Tilde-expanded path forwarded to the CLI as `--tmux-command`. */
38
+ /** Path forwarded to the CLI as `--tmux-command`. */
40
39
  tmuxCommand?: string;
41
40
  }
42
41
  /**
@@ -46,8 +45,8 @@ export interface GlobalArgvOptions {
46
45
  * [cliPath, ...globalFlags, verbName, ...verbFlags]
47
46
  *
48
47
  * Global flags are inserted BEFORE the verb token because the CLI's
49
- * `parseGlobalFlags` pre-scan operates on os.Args[1:] before verb dispatch
50
- * (see cmd/agent-director/global_flags.go). b.32k.
48
+ * `ParseGlobalFlags` pre-scan operates on os.Args[1:] before verb dispatch
49
+ * (see internal/clisetup/globalflags.go). b.32k.
51
50
  *
52
51
  * @param cliPath The absolute path to the CLI binary (argv[0]).
53
52
  * @param verb The kebab-case verb name (must be a VerbName).
@@ -2,7 +2,7 @@
2
2
  * errorMap.ts — catalog-driven static error map for the subprocess Client.
3
3
  *
4
4
  * Builds a `Map<string, ErrConstructor>` at module load time by iterating
5
- * `pkg/api/errnames/catalog.json` (37 entries as of 2026-05-31). The map
5
+ * `pkg/api/errnames/catalog.json` (44 entries). The map
6
6
  * keys are the canonical `err_name` strings (e.g. "ErrSpawnNotFound");
7
7
  * values are the typed constructors already exported from `src/errors.ts`.
8
8
  *
@@ -10,8 +10,11 @@
10
10
  * - Looks up `envelope.err_name` in the static map.
11
11
  * - Throws the typed subclass when found (carrying verb + envelope fields).
12
12
  * - Throws `ErrUnknownErrorName` when the err_name is not in the map
13
- * (SRD SR-4.3 — defensive against Go-side catalog additions that race
14
- * the TS-side regen).
13
+ * (SRD SR-4.3): either a Go-side catalog addition that races the TS-side
14
+ * regen, or a name the binary emits but the catalog leaves out —
15
+ * currently ErrInternal, ErrSchemaMismatch, ErrSchemaMigrationRequired,
16
+ * ErrUnknownVerb, ErrJSONMarshal and ErrTrailWrite (tracked in b.cm7).
17
+ * Callers read `unknownName` for the real err_name.
15
18
  *
16
19
  * Implements SRD SR-4.1 (static module-load-time map), SR-4.2 (throw by
17
20
  * constructor with envelope fields), SR-4.3 (ErrUnknownErrorName for
@@ -24,7 +24,7 @@
24
24
  * and the timeout was not the cause, ErrConsumerSignal is thrown.
25
25
  */
26
26
  import type { ClientOptions } from "../types.js";
27
- import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, DeleteParams, DeleteResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
27
+ import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
28
28
  /**
29
29
  * Internal construction parameters. Carries pre-resolved binaryPath +
30
30
  * binaryVersion so the runtime constructor doesn't run discovery itself.
@@ -111,14 +111,15 @@ export declare class SubprocessClient {
111
111
  decide(params: DecideParams): Promise<DecideResult>;
112
112
  /** getPermission — fetch a permission_requests row by request_token. */
113
113
  getPermission(params: GetPermissionParams): Promise<GetPermissionResult>;
114
- /** resume — restart a terminated Spawn. */
114
+ /** resume — relaunch a finished (ended or missing) row. */
115
115
  resume(params: ResumeParams): Promise<ResumeResult>;
116
- /** findMissing — reconcile Spawns whose tmux sessions have disappeared. */
116
+ /** findMissing — sweep live Spawns, marking each `missing` or leaving it unverified on process and tmux evidence; see FindMissingResult. */
117
117
  findMissing(params: FindMissingParams): Promise<FindMissingResult>;
118
- /** expire — remove terminal-state rows older than the retention window. */
118
+ /**
119
+ * expire — remove finished rows older than the retention window whose
120
+ * agent is gone, and report the rows it keeps.
121
+ */
119
122
  expire(params: ExpireParams): Promise<ExpireResult>;
120
- /** delete — hard-delete Spawn rows by id. */
121
- delete(params: DeleteParams): Promise<DeleteResult>;
122
123
  /** makeTemplate — save a reusable spawn preset. */
123
124
  makeTemplate(params: MakeTemplateParams): Promise<MakeTemplateResult>;
124
125
  /** list — query Spawns with optional filter params. */
@@ -6,14 +6,14 @@
6
6
  * pkg/api/manifest/manifest.go. It includes every verb where `Callable: true`
7
7
  * and excludes the three non-callable verbs (help, serve, hook).
8
8
  *
9
- * Currently 16 callable verbs: spawn, status, get, send-keys, read-pane,
10
- * kill, decide, get-permission, resume, find-missing, expire, delete,
9
+ * Currently 15 callable verbs: spawn, status, get, send-keys, read-pane,
10
+ * kill, decide, get-permission, resume, find-missing, expire,
11
11
  * make-template, list, pause, version.
12
12
  *
13
13
  * NOTE: `help` has `Callable: false` in manifest.go (source of truth); it is
14
14
  * intentionally excluded here. The .go source wins.
15
15
  */
16
16
  /** All callable verbs in their canonical kebab form (matches manifest). */
17
- export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "resume", "find-missing", "expire", "delete", "make-template", "list", "pause", "version"];
17
+ export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "resume", "find-missing", "expire", "make-template", "list", "pause", "version"];
18
18
  /** Union type of every callable verb name. */
19
19
  export type VerbName = (typeof VERBS)[number];
package/dist/types.d.ts CHANGED
@@ -18,14 +18,25 @@ export interface Logger {
18
18
  * does NOT provide a fallback; it forwards user input verbatim to keep the
19
19
  * CLI as the single source of truth for default resolution. See bug b.32k.
20
20
  *
21
- * Tilde expansion is handled TS-side by `src/internal/tilde.ts` before paths
22
- * are forwarded to the CLI subprocess, so the subprocess never receives a
23
- * leading `~`.
21
+ * `storePath`, `home` and `tmuxCommand` are forwarded verbatim; the TS Client
22
+ * does no tilde expansion of its own. The CLI subprocess, which inherits this
23
+ * process's environment, expands `~`: a bare `~` or a leading `~/` in `home`
24
+ * against the inherited `HOME`, then a leading `~/` in `storePath` and
25
+ * `tmuxCommand` (and a bare `~` in `tmuxCommand`) against the resulting
26
+ * `HOME`, which is `home` when set. The CLI never resolves `~` against the
27
+ * passwd home: with `HOME` unset or empty, a `~` or `~/` `home` rejects every
28
+ * call with `ErrInvalidFlags`, and with no `home` either, every call that
29
+ * opens the store is refused. Other values, relative paths included, are
30
+ * forwarded unchanged and the CLI resolves them. b.38a.
31
+ *
32
+ * An empty `storePath`, `home` or `tmuxCommand` is forwarded as given (e.g.
33
+ * `--store-path ""`); the CLI rejects it on every verb call, which then
34
+ * rejects with `ErrInvalidFlags`. It never falls back to the default. b.pu2.
24
35
  */
25
36
  export interface ClientOptions {
26
37
  /**
27
- * Path to the SQLite store file. Tilde-expanded before being forwarded as
28
- * `--store-path` to the CLI subprocess.
38
+ * Path to the SQLite store file. Forwarded verbatim as `--store-path` to the
39
+ * CLI subprocess, which expands a leading `~/`.
29
40
  *
30
41
  * When omitted, the CLI's three-tier default resolution applies:
31
42
  * 1. CLI flag (this field, when set) → 2. cfg.Store.DbPath in
@@ -36,15 +47,15 @@ export interface ClientOptions {
36
47
  */
37
48
  storePath?: string;
38
49
  /**
39
- * Override the tmux binary. Tilde-expanded before being forwarded as
40
- * `--tmux-command` to the CLI subprocess. When omitted, the CLI looks up
41
- * `tmux` on PATH.
50
+ * Override the tmux binary. Forwarded verbatim as `--tmux-command` to the
51
+ * CLI subprocess, which expands a bare `~` or a leading `~/`. When omitted,
52
+ * the CLI looks up `tmux` on PATH.
42
53
  */
43
54
  tmuxCommand?: string;
44
55
  /**
45
56
  * Override HOME for the duration of every subprocess call this Client
46
- * issues. Tilde-expanded before being forwarded as `--home` to the CLI
47
- * subprocess.
57
+ * issues. Forwarded verbatim as `--home` to the CLI subprocess, which
58
+ * expands a bare `~` or a leading `~/` against the inherited `HOME`.
48
59
  *
49
60
  * When omitted, the CLI subprocess inherits HOME from the calling process
50
61
  * environment (which is the correct default — set HOME at the
@@ -99,7 +110,12 @@ export interface ListRow {
99
110
  claude_instance_id: string;
100
111
  /** Parent Spawn id (omitted when launched from a plain shell). */
101
112
  parent_id?: string;
102
- /** Current lifecycle state. */
113
+ /**
114
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
115
+ * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
116
+ * reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
117
+ * prompt. A resumed pending row keeps its session id and history.
118
+ */
103
119
  state: string;
104
120
  /** Canonicalized working directory. */
105
121
  cwd: string;
@@ -115,9 +131,24 @@ export interface ListRow {
115
131
  last_seen_at: string;
116
132
  /** Set when state moves to ended (omitted while live). */
117
133
  ended_at?: string | null;
118
- /** RFC3339 timestamp of the first sweep that could not verify this live row's liveness; omitted/null when never unverified. */
134
+ /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
135
+ launch_started_at?: string | null;
136
+ /**
137
+ * RFC3339 timestamp of the first sweep that left this live row unverified;
138
+ * kept while later sweeps change `liveness_note`. Cleared together with
139
+ * `liveness_note` when a sweep finds the agent process alive; omitted/null
140
+ * while not unverified.
141
+ */
119
142
  liveness_unverified_since?: string | null;
120
- /** Human-readable reason liveness could not be verified; omitted/null when never unverified. */
143
+ /**
144
+ * Reason token of the latest sweep that left this live row unverified (its
145
+ * agent process could not be checked and tmux did not settle it), for
146
+ * example `process_not_seen_session_present`,
147
+ * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
148
+ * or `provenance_conflict`; overwritten when the reason changes. Cleared
149
+ * together with `liveness_unverified_since` when a sweep finds the agent
150
+ * process alive; omitted/null while not unverified.
151
+ */
121
152
  liveness_note?: string | null;
122
153
  }
123
154
  /** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
@@ -142,15 +173,40 @@ export interface SpawnParams {
142
173
  extra_env?: Record<string, string>;
143
174
  /** Pass-through argv to `claude` after --settings. */
144
175
  claude_args?: string[];
145
- /** Skip pre-writing workspace-trust into ~/.claude.json. Default false. */
176
+ /**
177
+ * Skip pre-writing the folder-trust entry for `cwd` (into
178
+ * `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets `CLAUDE_CONFIG_DIR`,
179
+ * otherwise `~/.claude.json`). The choice is recorded on the row for its life,
180
+ * and every `resume` of that life follows it. The result then reports
181
+ * `pre_trust: "skipped"`. Default false.
182
+ */
146
183
  no_pre_trust?: boolean;
147
184
  /** Explicit tmux session name. Auto-derived when absent. */
148
185
  tmux_session_name?: string;
186
+ /**
187
+ * Reuse an explicit `claude_instance_id` whose row is `ended` or `missing`;
188
+ * a live row, `pending` included, still collides. No effect without an
189
+ * explicit `claude_instance_id`; applies to this call only. Default false:
190
+ * any existing row with the id collides with `ErrInstanceIdCollision`.
191
+ */
192
+ reuse_finished?: boolean;
149
193
  }
150
- /** Mirrors pkg/api/spawn.go::SpawnResult */
194
+ /**
195
+ * Mirrors pkg/api/spawn.go::SpawnResult. The row is `pending` from its insert until
196
+ * the agent reports in (Claude Code's SessionStart), then `waiting`.
197
+ */
151
198
  export interface SpawnResult {
152
199
  /** The id the new Spawn is tracked under. */
153
200
  claude_instance_id: string;
201
+ /**
202
+ * What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
203
+ * written. `"skipped"`: pre-trust was off for this launch because the caller passed
204
+ * `no_pre_trust`; nothing was attempted. `"failed"`: pre-trust was attempted and the
205
+ * entry was not written (the `.claude.json` file is missing, or could not be read,
206
+ * parsed or written); the agent may stop at Claude Code's folder-trust prompt.
207
+ * A pre-trust failure never fails the spawn.
208
+ */
209
+ pre_trust: "ok" | "skipped" | "failed";
154
210
  }
155
211
  /** Mirrors the `status` CLI verb's --claude-instance-id flag (pkg/api.Client.Status arg). */
156
212
  export interface StatusParams {
@@ -159,8 +215,16 @@ export interface StatusParams {
159
215
  }
160
216
  /** Mirrors pkg/api/status.go::StatusResult */
161
217
  export interface StatusResult {
162
- /** Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing). */
218
+ /**
219
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
220
+ * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
221
+ * reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
222
+ * prompt. A resumed pending row keeps its session id and history; a caller tells it
223
+ * from a fresh one by its non-empty `claude_session_id`, shown by `get`.
224
+ */
163
225
  state: string;
226
+ /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
227
+ launch_started_at?: string | null;
164
228
  }
165
229
  /** Mirrors the `get` CLI verb's --claude-instance-id flag (pkg/api.Client.Get arg). */
166
230
  export interface GetParams {
@@ -171,9 +235,18 @@ export interface GetParams {
171
235
  export interface GetResult {
172
236
  claude_instance_id: string;
173
237
  parent_id: string;
238
+ /**
239
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
240
+ * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
241
+ * reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
242
+ * prompt. A resumed pending row keeps its session id and history; a non-empty
243
+ * `claude_session_id` tells it from a fresh one.
244
+ */
174
245
  state: string;
175
246
  cwd: string;
176
247
  tmux_session_name: string;
248
+ /** The tmux socket the row's launch uses; omitted for a row from before this release. */
249
+ tmux_socket?: string | null;
177
250
  claude_args: string[];
178
251
  relay_mode: string;
179
252
  jsonl_path: string;
@@ -185,9 +258,24 @@ export interface GetResult {
185
258
  last_seen_at: string;
186
259
  /** Set when state moves to ended; omitted while live. */
187
260
  ended_at?: string | null;
188
- /** RFC3339 timestamp of the first sweep that could not verify this live row's liveness; omitted/null when never unverified. */
261
+ /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
262
+ launch_started_at?: string | null;
263
+ /**
264
+ * RFC3339 timestamp of the first sweep that left this live row unverified;
265
+ * kept while later sweeps change `liveness_note`. Cleared together with
266
+ * `liveness_note` when a sweep finds the agent process alive; omitted/null
267
+ * while not unverified.
268
+ */
189
269
  liveness_unverified_since?: string | null;
190
- /** Human-readable reason liveness could not be verified; omitted/null when never unverified. */
270
+ /**
271
+ * Reason token of the latest sweep that left this live row unverified (its
272
+ * agent process could not be checked and tmux did not settle it), for
273
+ * example `process_not_seen_session_present`,
274
+ * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
275
+ * or `provenance_conflict`; overwritten when the reason changes. Cleared
276
+ * together with `liveness_unverified_since` when a sweep finds the agent
277
+ * process alive; omitted/null while not unverified.
278
+ */
191
279
  liveness_note?: string | null;
192
280
  /** Open permission request; present only when state=check_permission with an undecided row. */
193
281
  permission_request?: PermissionRequestInfo | null;
@@ -196,11 +284,17 @@ export interface GetResult {
196
284
  export interface SendKeysParams {
197
285
  /** Id of the Spawn whose pane will receive the text. */
198
286
  claude_instance_id: string;
199
- /** Text to deliver to the pane. CR bytes stripped; LF preserved; Enter appended. */
287
+ /**
288
+ * Text to deliver to the pane. CR bytes stripped; LF preserved; Enter
289
+ * appended. Empty text sends Enter only: it submits what is already typed,
290
+ * such as a text a failed sendKeys left unsubmitted.
291
+ */
200
292
  text: string;
201
293
  /**
202
- * When true, also permit send-keys on a pending Spawn (pre-SessionStart
203
- * use case). ended/missing Spawns are still rejected even with this flag.
294
+ * When true, also allows a pending row: a launch (spawn, reuse or resume)
295
+ * whose agent has not reported in yet. Keys are delivered only to a
296
+ * session started by the row's current launch. ended and missing rows are
297
+ * still rejected.
204
298
  */
205
299
  allow_pending?: boolean;
206
300
  }
@@ -227,13 +321,15 @@ export interface ReadPaneResult {
227
321
  /** Captured pane text. */
228
322
  pane: string;
229
323
  }
230
- /** Mirrors pkg/api.KillParams (json tags). */
324
+ /** Mirrors pkg/api.KillParams. */
231
325
  export interface KillParams {
232
326
  /** Id of the Spawn to kill. */
233
327
  claude_instance_id: string;
234
328
  }
235
- /** Mirrors pkg/api/kill.go::KillResult (empty; reserved for future fields). */
329
+ /** Mirrors pkg/api/kill.go::KillResult (json tags). */
236
330
  export interface KillResult {
331
+ /** True exactly when a pane kill or a session kill was sent. */
332
+ kill_sent: boolean;
237
333
  }
238
334
  /** Mirrors pkg/api.DecideParams (json tags). */
239
335
  export interface DecideParams {
@@ -275,31 +371,66 @@ export interface GetPermissionResult {
275
371
  }
276
372
  /** Mirrors pkg/api.ResumeParams (json tags). */
277
373
  export interface ResumeParams {
278
- /** Id of the terminated Spawn to resurrect. */
374
+ /** Id of the finished (ended or missing) row to resume. */
279
375
  claude_instance_id: string;
280
376
  }
281
- /** Mirrors pkg/api/resume.go::ResumeResult */
377
+ /**
378
+ * Mirrors pkg/api/resume.go::ResumeResult. Resume moved the row to `pending`, keeping
379
+ * its session id and history, until the agent reports in (Claude Code's SessionStart),
380
+ * then `waiting`.
381
+ */
282
382
  export interface ResumeResult {
283
- /** Same id that was passed in (preserved across resurrection). */
383
+ /** Same id that was passed in (resume preserves it). */
284
384
  claude_instance_id: string;
385
+ /**
386
+ * What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
387
+ * written. `"skipped"`: pre-trust was off for this launch because the row records that
388
+ * the spawn that began its life turned it off (`no_pre_trust`); nothing was attempted.
389
+ * `"failed"`: pre-trust was attempted and the entry was not written (the `.claude.json`
390
+ * file is missing, or could not be read, parsed or written); the agent may stop at
391
+ * Claude Code's folder-trust prompt. A pre-trust failure never fails the resume.
392
+ */
393
+ pre_trust: "ok" | "skipped" | "failed";
285
394
  }
286
- /** Mirrors the `find-missing` CLI verb's --timeout flag (pkg/api.Client.FindMissing ctx deadline). */
395
+ /** Params for the `find-missing` verb, which takes no CLI flags. */
287
396
  export interface FindMissingParams {
288
- /** Optional deadline for the OS probe sweep (milliseconds). 0/omitted = no deadline. */
397
+ /**
398
+ * Accepted but not sent: the `find-missing` CLI verb takes no flags, so
399
+ * this value has no effect. The call is bounded by the Client's
400
+ * `callTimeoutMs` like every other verb.
401
+ */
289
402
  timeout_ms?: number;
290
403
  }
291
404
  /** Mirrors pkg/api/find_missing.go::FindMissingResult */
292
405
  export interface FindMissingResult {
293
- /** Number of rows transitioned to missing on this sweep. */
406
+ /**
407
+ * Number of rows this sweep marked `missing` (the length of `ids`). Zero is
408
+ * a normal result when nothing needed marking.
409
+ */
294
410
  count: number;
295
- /** Sorted ids of rows transitioned to missing. */
296
- ids: string[];
297
411
  /**
298
- * Number of live rows left untouched this sweep because their liveness
299
- * could not be established (an unknown verdict, e.g. a permission wall).
412
+ * Sorted ids of rows this sweep marked `missing`, on process or tmux
413
+ * evidence: rows whose agent process (the SessionStart one or the recorded
414
+ * pane's) is dead, and rows whose process could not be checked and tmux
415
+ * found no session or pane of their current launch; a pending row only past
416
+ * the pending grace period. A row whose guarded write found it changed or
417
+ * gone, or failed, is in neither list. `missing` is the sweep's judgement
418
+ * on the evidence available to it, not proof that the agent has exited.
419
+ * Never null; [] when none.
300
420
  */
421
+ ids: string[];
422
+ /** Number of live rows this sweep left unverified (the length of `unverified_ids`). */
301
423
  unverified: number;
302
- /** Sorted ids of rows left untouched as unverified. Non-nil; [] when none. */
424
+ /**
425
+ * Sorted ids of live rows this sweep left unverified with a liveness note,
426
+ * whether it wrote the note or found it already current: rows whose agent
427
+ * process could not be checked and which tmux did not mark, for example
428
+ * because their own session is present, tmux could not tell or was
429
+ * unavailable, or tmux was not called. Never a pending row inside the
430
+ * pending grace period. A row whose guarded write found it changed or gone,
431
+ * or failed, and a row whose note was cleared, is in neither list. Never
432
+ * null; [] when none.
433
+ */
303
434
  unverified_ids: string[];
304
435
  }
305
436
  /** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
@@ -312,20 +443,36 @@ export interface ExpireParams {
312
443
  }
313
444
  /** Mirrors pkg/api/expire.go::ExpireResult */
314
445
  export interface ExpireResult {
315
- /** Number of terminal rows removed. */
446
+ /**
447
+ * Number of rows deleted (the length of `ids`): rows deleted after tmux
448
+ * showed no session of the agent (Gone) and its recorded process was not
449
+ * seen running. Zero is a legitimate result when no row was deleted.
450
+ */
316
451
  count: number;
317
- /** Sorted ids of rows removed. */
452
+ /**
453
+ * Sorted ids of the rows deleted after tmux showed no session of the agent
454
+ * (Gone) and its recorded process was not seen running, each only while
455
+ * the row was unchanged since expire examined it. Never null; `[]` when
456
+ * none.
457
+ */
318
458
  ids: string[];
319
- }
320
- /** Mirrors the `delete` CLI verb's --claude-instance-id flag(s) (pkg/api.Client.Delete arg). */
321
- export interface DeleteParams {
322
- /** Id(s) to delete. */
323
- claude_instance_id: string[];
324
- }
325
- /** Mirrors pkg/api/delete.go::DeleteResult */
326
- export interface DeleteResult {
327
- /** Per-id outcome: "ok" on success, err_name on failure. */
328
- results: Record<string, string>;
459
+ /**
460
+ * Number of selected rows kept rather than deleted (the length of
461
+ * `kept_ids`), for example because the agent's process or a session of the
462
+ * agent (its own, or a leftover of an earlier launch) may still run, tmux
463
+ * could not be checked or answered from a different server, the run's tmux
464
+ * time budget (`sweep_budget_seconds`) was spent, or the row changed after
465
+ * it was examined.
466
+ */
467
+ kept: number;
468
+ /**
469
+ * Sorted ids of the selected rows kept rather than deleted, each reported
470
+ * with its reason in the trail (`ad.expire.kept`). tmux problems and a
471
+ * failed delete of one row never fail the run: the row is kept. A failed
472
+ * read of the selected rows fails the run. A row another caller removed
473
+ * first is in neither list. Never null; `[]` when none.
474
+ */
475
+ kept_ids: string[];
329
476
  }
330
477
  /** Mirrors pkg/api.MakeTemplateParams (json tags). */
331
478
  export interface MakeTemplateParams {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.10.0",
3
+ "version": "0.11.1",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],
@@ -1,16 +0,0 @@
1
- /**
2
- * expandTilde resolves a leading `~` or `~/` to the user's home directory.
3
- *
4
- * Resolution order:
5
- * 1. `process.env.HOME` if set and non-empty.
6
- * 2. `os.homedir()` from node:os as fallback.
7
- *
8
- * Behaviour by input:
9
- * - `""` → `""` (empty string unchanged)
10
- * - `"~"` → `"/home/user"` (bare tilde → home directory)
11
- * - `"~/foo"` → `"/home/user/foo"` (tilde-prefix → home + rest)
12
- * - `"/abs/path"` → `"/abs/path"` (absolute path unchanged)
13
- * - `"relative/path"` → `"relative/path"` (relative path unchanged)
14
- * - `"foo~bar"` → `"foo~bar"` (tilde not at start → unchanged)
15
- */
16
- export declare function expandTilde(p: string): string;