agent-director 0.15.0 → 0.16.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
@@ -119,6 +119,10 @@ Cursor reports `"failed"` for unsupported pre-trust or `"skipped"` for its saved
119
119
  opt-out, never a validated `"ok"`; see
120
120
  [Cursor launch settings](../../docs/settings.md#cursor-launch-settings).
121
121
 
122
+ `idle_screen_timeout_seconds` gives the row its own `idle_screen` timeout in
123
+ whole seconds (`0`, `null` or omitted for none); its range and lifecycle are
124
+ in [Configuration](../../docs/configuration.md#idle-screen-timeout-state).
125
+
122
126
  For all agents, same-agent reuse retains current-life session history and subagent records;
123
127
  switching agents starts another life, including when switching back.
124
128
  `resume` continues only the recorded agent's latest reported session and
@@ -149,10 +153,27 @@ console.log(result.state);
149
153
 
150
154
  `StatusResult`, `GetResult` and each `ListRow` expose
151
155
  `family_state: "working" | "waiting"`, separately from `state`.
152
- [Usage](../../docs/usage.md#family-state) defines membership and raw
156
+ [Usage](../../docs/usage.md#family-state) defines membership and
153
157
  aggregation; the [caller contract](../../docs/caller-contract.md#family-reporting-limits)
154
158
  defines reporting limits.
155
159
 
160
+ `state` is a `string` and can be `"needs_intelligence"` or `"idle_screen"`.
161
+ Then `StatusResult` and `GetResult` carry `since` and that state's detail:
162
+ `request_token` and `tool_name` for `"needs_intelligence"`, or
163
+ `unchanged_minutes` for `"idle_screen"`; `StatusResult` also carries
164
+ `tmux_session_name`, and each `ListRow` carries `state`, no detail. A key that
165
+ does not apply is absent from the result, never `null`, so test for presence
166
+ (`result.since !== undefined`). Every `StatusResult`, `GetResult` and
167
+ `ListRow` carries `idle_screen_availability` (`IdleScreenAvailability`:
168
+ `"available"` for Claude and Codex, `"unavailable"` for Cursor).
169
+ The [caller contract](../../docs/caller-contract.md#needs-intelligence-and-idle-screen-rows)
170
+ defines the states, fields, omissions and detection.
171
+
172
+ `GetResult` and each `ListRow` carry `state_changed_at: string`, when the raw
173
+ state last changed; `StatusResult` does not. The
174
+ [caller contract](../../docs/caller-contract.md#state-change-time) defines it
175
+ and how it differs from `last_seen_at`, the settled `state` and `since`.
176
+
156
177
  `status`, `get` and `list` use `[state] settle_ms` in the CLI's
157
178
  `~/.config/agent-director/config.toml` for [independent state and family
158
179
  settling](../../docs/configuration.md#settle-time-state). Verbs that act on a
@@ -170,6 +191,8 @@ for (const spawn of result.spawns) {
170
191
  ```
171
192
 
172
193
  Each row, like `get`'s result, carries `agent` (`"claude"`, `"codex"` or `"cursor"`), the agent the row runs.
194
+ A `state` filter of `"needs_intelligence"` or `"idle_screen"` is matched on
195
+ the displayed state, before any `limit`.
173
196
 
174
197
  ### listSubagents
175
198
 
@@ -617,7 +640,7 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
617
640
  | Error | When it fires |
618
641
  |---|---|
619
642
  | `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
620
- | `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). 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). |
643
+ | `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). 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`, `features.hooks` or its alias `features.codex_hooks`, `--disable hooks` or `--disable codex_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). |
621
644
  | `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"`, `"codex"` or `"cursor"`), or put one in the template. |
622
645
  | `ErrAgentInvalid` | `agent` is none of `"claude"`, `"codex"` or `"cursor"` (the value is case-sensitive); nothing is written. |
623
646
  | `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. |
package/dist/index.d.ts CHANGED
@@ -10,6 +10,6 @@ ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after val
10
10
  ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrAgentMissing, ErrAgentInvalid, ErrAgentArgsMismatch, ErrPermissionsUnsupported, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSubmissionUnconfirmed, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrTemplateAgentMissing, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrPaneChanged, ErrPaneAnswerInProgress, ErrClaimTooSoon, ErrDialogMaybeOpen, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrStoreBusy, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, ErrSchemaMismatch, ErrSchemaMigrationRequired, ErrOldLayout, ErrUnknownVerb, ErrJSONMarshal, ErrTrailWrite, ErrInternal, } from "./errors.js";
11
11
  export type { CheckedLocation, UnreachableReason } from "./errors.js";
12
12
  export type { ClientOptions, Logger } from "./types.js";
13
- export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, } from "./types.js";
13
+ export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, IdleScreenAvailability, } from "./types.js";
14
14
  export type { PauseTimeoutDetails, RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
15
15
  export type { SpawnParams, SpawnResult, StatusParams, StatusResult, ContextReading, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, SubagentRecord, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
package/dist/index.js CHANGED
@@ -1020,6 +1020,9 @@ function buildSpawn(p) {
1020
1020
  f.push("--no-pre-trust");
1021
1021
  if (p.reuse_finished === true)
1022
1022
  f.push("--reuse-finished");
1023
+ const timeout = p.idle_screen_timeout_seconds;
1024
+ if (timeout !== undefined && timeout !== null && timeout !== 0)
1025
+ f.push("--idle-screen-timeout-seconds", String(timeout));
1023
1026
  if (p.label) {
1024
1027
  for (const lv of p.label)
1025
1028
  f.push("--label", lv);
@@ -1,12 +1,9 @@
1
1
  /**
2
2
  * platformResolve.ts — Bun runtime-version guard.
3
3
  *
4
- * The vendored-binary resolution logic that used to live here is gone as of
5
- * b.ue3 (Stream A). Discovery is now run by src/internal/discovery.ts
6
- * against the system install (HOME → PATH). The only piece this file still
7
- * owns is the Bun-runtime-version check, fired at the top of every
8
- * Client.create() and resolveSystemBinary() call before any filesystem stat
9
- * (SR-7.7).
4
+ * Checks the Bun runtime version at the top of every Client.create() and
5
+ * resolveSystemBinary() call, before any filesystem stat (SR-7.7). Binary
6
+ * discovery lives in src/internal/discovery.ts.
10
7
  *
11
8
  * Internal — not re-exported from src/index.ts.
12
9
  */
@@ -23,11 +23,6 @@
23
23
  * - ErrCallerCwdUnreachable — caller's process.cwd() is gone at construction (b.cot).
24
24
  * - ErrSystemInstallDisappeared — binary gone at verb-dispatch time, after valid construction (b.xht).
25
25
  *
26
- * Removed in b.ue3 (vendored-binary surface dropped):
27
- * - ErrUnsupportedPlatform
28
- * - ErrPlatformPackageMissing
29
- * - ErrCliNotExecutable
30
- *
31
26
  * When adding a new TS-only subclass: add its name here AND add a comment in
32
27
  * src/errors.ts near the subclass cross-referencing this allow-list.
33
28
  */
package/dist/types.d.ts CHANGED
@@ -232,14 +232,23 @@ export interface PermissionRequestInfo extends RequestDelivery {
232
232
  /** The recorded verdict's decision_reason; null when none is recorded. */
233
233
  decision_reason: string | null;
234
234
  }
235
+ /**
236
+ * Whether `idle_screen` can apply to a row's agent: `"available"` for Claude and Codex,
237
+ * `"unavailable"` for Cursor. A capability outcome, never a state.
238
+ */
239
+ export type IdleScreenAvailability = "available" | "unavailable";
235
240
  /** One Spawn row returned by the list verb. */
236
241
  export interface ListRow {
242
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
243
+ idle_screen_availability: IdleScreenAvailability;
237
244
  /** Stable Spawn id. */
238
245
  instance_id: string;
239
246
  /** Parent Spawn id (omitted when launched from a plain shell). */
240
247
  parent_id?: string;
241
248
  /**
242
- * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
249
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
250
+ * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
251
+ * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
243
252
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
244
253
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
245
254
  * prompt. A resumed pending row keeps its session id and history.
@@ -248,15 +257,20 @@ export interface ListRow {
248
257
  * off), this is the settled state: a state a hook wrote shows only once it has held for
249
258
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
250
259
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
251
- * Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
252
- * its live state, which can be newer: a refusal can name a state this field does not show yet.
260
+ * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
261
+ * times settle_ms from the read that commits its candidate; a later read commits the change.
262
+ * Nothing marks a state as late. `family_state` settles independently. Fields such as
263
+ * `state_changed_at` and `permission_requests`, and the verbs that act on the row, follow its
264
+ * live state, which can be newer: a refusal can name a state this field does not show yet.
253
265
  */
254
266
  state: string;
255
267
  /**
256
268
  * Complete stored family: self and live descendants, including through retained terminal
257
- * intermediates. Waiting means every live member is waiting, or no live members remain.
258
- * Uses raw member states and settles once in either direction with `[state] settle_ms`,
259
- * independently of `state`. This report does not establish readiness or task success.
269
+ * intermediates. A live member counts as working while its raw state is not waiting or its
270
+ * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
271
+ * commits. Waiting means no member counts as working, or no live members remain. Settles once
272
+ * in either direction with `[state] settle_ms`, independently of `state`. This report does
273
+ * not establish readiness or task success.
260
274
  */
261
275
  family_state: "working" | "waiting";
262
276
  /** Canonicalized working directory. */
@@ -273,6 +287,15 @@ export interface ListRow {
273
287
  started_at: string;
274
288
  /** Most recent hook UPSERT time (RFC3339). */
275
289
  last_seen_at: string;
290
+ /**
291
+ * When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
292
+ * Soft refreshes and same-state writes leave it; `state` may still show the earlier
293
+ * settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
294
+ * agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
295
+ * or list finds lost reads `missing` at once; this moves when that mark is stored, which
296
+ * can be after the read that first shows `missing`.
297
+ */
298
+ state_changed_at: string;
276
299
  /** Set when state moves to ended (omitted while live). */
277
300
  ended_at?: string | null;
278
301
  /**
@@ -314,8 +337,10 @@ export interface ListRow {
314
337
  * delivery facts; populated only when the row's live state is check_permission, `[]`
315
338
  * otherwise. A row can read waiting, working or ask_user while a request is still open:
316
339
  * follow a tracked request with `getPermission`. Requests are never delayed by
317
- * `[state] settle_ms`, so with it set a row can also read any state (even ended or missing)
318
- * with open requests listed, or check_permission with `[]`, for up to settle_ms.
340
+ * `[state] settle_ms`, so with it set ordinary raw-state settling can also show any state
341
+ * (even ended or missing) with open requests listed, or check_permission with `[]`, for up
342
+ * to settle_ms; entering or leaving `needs_intelligence` or `idle_screen` has no such bound
343
+ * (see `state`).
319
344
  */
320
345
  permission_requests: PermissionRequestInfo[];
321
346
  }
@@ -366,8 +391,9 @@ export interface SpawnParams {
366
391
  * removed tokens appear in `dropped_args`; the agent starts fresh and resumes nothing.
367
392
  * Exact denied long tokens owned as option values always refuse. For codex, a Codex subcommand in
368
393
  * command position, `--remote`, `--remote-auth-token-env`, `-c`/`--config` keys at, above or
369
- * under `hooks`, `tui.disable_paste_burst` or `features.hooks`, and `--disable hooks` are
370
- * refused (`ErrSpawnDeniedFlag`); with `disable_ask_user` on, `--enable
394
+ * under `hooks`, `tui.disable_paste_burst`, `features.hooks` or its alias
395
+ * `features.codex_hooks`, and `--disable hooks` or `codex_hooks` are refused
396
+ * (`ErrSpawnDeniedFlag`); with `disable_ask_user` on, `--enable
371
397
  * default_mode_request_user_input` and the question-tool keys are refused too. agent-director
372
398
  * adds no second `--no-daemon`, `--dangerously-bypass-hook-trust` (pre-trust ok) or
373
399
  * `--enable write_stdin_approval` when the arguments already carry one before any `--`;
@@ -406,6 +432,15 @@ export interface SpawnParams {
406
432
  * `ErrInstanceIdCollision`.
407
433
  */
408
434
  reuse_finished?: boolean;
435
+ /**
436
+ * This row's `idle_screen` timeout in whole seconds, 1 to 9223372036, used by every
437
+ * `status`, `get` and `list` in place of `[state] idle_screen_timeout_seconds`.
438
+ * `0`, `null` or omitted gives no override. A negative, fractional, non-numeric or larger
439
+ * value is refused with `ErrInvalidFlags` before anything is written or launched. Recorded
440
+ * on the row: `resume` keeps it; the next spawn or reuse replaces it, clearing it when that
441
+ * call gives none. Cursor rows keep it, but `idle_screen` is unavailable for them.
442
+ */
443
+ idle_screen_timeout_seconds?: number | null;
409
444
  }
410
445
  /**
411
446
  * The launch result. The row is `pending` from its insert until
@@ -442,10 +477,30 @@ export interface StatusParams {
442
477
  }
443
478
  /** The row's reported lifecycle state. */
444
479
  export interface StatusResult {
480
+ /**
481
+ * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
482
+ * only while `needs_intelligence` or `idle_screen` is displayed.
483
+ */
484
+ since?: string;
485
+ /**
486
+ * The representative unanswered request (earliest qualifying fallback, lexical
487
+ * request-token tie break); only while `needs_intelligence`.
488
+ */
489
+ request_token?: string;
490
+ /** That request's tool; only while `needs_intelligence`. */
491
+ tool_name?: string;
492
+ /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
493
+ unchanged_minutes?: number;
494
+ /** Attach target, present only while `needs_intelligence` or `idle_screen` is displayed. */
495
+ tmux_session_name?: string;
496
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
497
+ idle_screen_availability: IdleScreenAvailability;
445
498
  /** Experimental context estimate for the current session. */
446
499
  context: ContextReading;
447
500
  /**
448
- * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
501
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
502
+ * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
503
+ * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
449
504
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
450
505
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
451
506
  * prompt. A resumed pending row keeps its session id and history; a caller tells it
@@ -455,15 +510,19 @@ export interface StatusResult {
455
510
  * off), this is the settled state: a state a hook wrote shows only once it has held for
456
511
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
457
512
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
513
+ * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
514
+ * times settle_ms from the read that commits its candidate; a later read commits the change.
458
515
  * Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
459
516
  * can be newer: a refusal can name a state status does not show yet.
460
517
  */
461
518
  state: string;
462
519
  /**
463
520
  * Complete stored family: self and live descendants, including through retained terminal
464
- * intermediates. Waiting means every live member is waiting, or no live members remain.
465
- * Uses raw member states and settles once in either direction with `[state] settle_ms`,
466
- * independently of `state`. This report does not establish readiness or task success.
521
+ * intermediates. A live member counts as working while its raw state is not waiting or its
522
+ * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
523
+ * commits. Waiting means no member counts as working, or no live members remain. Settles once
524
+ * in either direction with `[state] settle_ms`, independently of `state`. This report does
525
+ * not establish readiness or task success.
467
526
  */
468
527
  family_state: "working" | "waiting";
469
528
  /**
@@ -499,12 +558,30 @@ export interface GetParams {
499
558
  }
500
559
  /** One tracked agent row, with its current session and request facts. */
501
560
  export interface GetResult {
561
+ /**
562
+ * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
563
+ * only while `needs_intelligence` or `idle_screen` is displayed.
564
+ */
565
+ since?: string;
566
+ /**
567
+ * The representative unanswered request (earliest qualifying fallback, lexical
568
+ * request-token tie break); only while `needs_intelligence`.
569
+ */
570
+ request_token?: string;
571
+ /** That request's tool; only while `needs_intelligence`. */
572
+ tool_name?: string;
573
+ /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
574
+ unchanged_minutes?: number;
575
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
576
+ idle_screen_availability: IdleScreenAvailability;
502
577
  /** Experimental context estimate for the current session. */
503
578
  context: ContextReading;
504
579
  instance_id: string;
505
580
  parent_id: string;
506
581
  /**
507
- * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
582
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
583
+ * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
584
+ * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
508
585
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
509
586
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
510
587
  * prompt. A resumed pending row keeps its session id and history; a non-empty
@@ -514,15 +591,22 @@ export interface GetResult {
514
591
  * off), this is the settled state: a state a hook wrote shows only once it has held for
515
592
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
516
593
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
517
- * Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
518
- * its live state, which can be newer: a refusal can name a state this field does not show yet.
594
+ * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
595
+ * times settle_ms from the read that commits its candidate; a later read commits the change.
596
+ * Nothing marks a state as late. While an exit or direct move settles, `since` and that
597
+ * state's detail keep the previous display's committed values, and `family_state` settles
598
+ * independently. Fields such as `state_changed_at` and `permission_requests`, and the verbs
599
+ * that act on the row, follow its live state, which can be newer: a refusal can name a state
600
+ * this field does not show yet.
519
601
  */
520
602
  state: string;
521
603
  /**
522
604
  * Complete stored family: self and live descendants, including through retained terminal
523
- * intermediates. Waiting means every live member is waiting, or no live members remain.
524
- * Uses raw member states and settles once in either direction with `[state] settle_ms`,
525
- * independently of `state`. This report does not establish readiness or task success.
605
+ * intermediates. A live member counts as working while its raw state is not waiting or its
606
+ * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
607
+ * commits. Waiting means no member counts as working, or no live members remain. Settles once
608
+ * in either direction with `[state] settle_ms`, independently of `state`. This report does
609
+ * not establish readiness or task success.
526
610
  */
527
611
  family_state: "working" | "waiting";
528
612
  cwd: string;
@@ -547,6 +631,15 @@ export interface GetResult {
547
631
  started_at: string;
548
632
  /** Last hook UPSERT time (RFC3339). */
549
633
  last_seen_at: string;
634
+ /**
635
+ * When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
636
+ * Soft refreshes and same-state writes leave it; `state` may still show the earlier
637
+ * settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
638
+ * agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
639
+ * or list finds lost reads `missing` at once; this moves when that mark is stored, which
640
+ * can be after the read that first shows `missing`.
641
+ */
642
+ state_changed_at: string;
550
643
  /** Set when state moves to ended; omitted while live. */
551
644
  ended_at?: string | null;
552
645
  /**
@@ -589,9 +682,10 @@ export interface GetResult {
589
682
  * only when the row's live state is check_permission, `[]` otherwise. A row can read waiting,
590
683
  * working or ask_user while a request is still open: follow a tracked request with
591
684
  * `getPermission`.
592
- * Requests are never delayed by `[state] settle_ms`, so with it set a row can also read any
593
- * state (even ended or missing) with open requests listed, or check_permission with `[]`, for
594
- * up to settle_ms.
685
+ * Requests are never delayed by `[state] settle_ms`, so with it set ordinary raw-state
686
+ * settling can also show any state (even ended or missing) with open requests listed, or
687
+ * check_permission with `[]`, for up to settle_ms; entering or leaving `needs_intelligence`
688
+ * or `idle_screen` has no such bound (see `state`).
595
689
  */
596
690
  permission_requests: PermissionRequestInfo[];
597
691
  /**
@@ -602,7 +696,8 @@ export interface GetResult {
602
696
  * `unproven_since`. While it is not empty, a plain `sendKeys` without `expect_pane_sha256`,
603
697
  * and a `pause`, reject (`ErrDialogMaybeOpen`, or an earlier relay refusal). It follows the
604
698
  * row's live state and is never delayed by `[state] settle_ms`, so with it set it can disagree
605
- * with `state` for up to settle_ms.
699
+ * with `state` for up to settle_ms under ordinary raw-state settling, and without that bound
700
+ * while entering or leaving `needs_intelligence` or `idle_screen` (see `state`).
606
701
  */
607
702
  unproven_requests: PermissionRequestInfo[];
608
703
  }
@@ -1073,8 +1168,9 @@ export interface MakeTemplateResult {
1073
1168
  /** Filters for listing tracked agent rows. */
1074
1169
  export interface ListParams {
1075
1170
  /**
1076
- * Filter by state (multiple values OR together). With `[state] settle_ms` set it matches the
1077
- * settled state each row's `state` shows, before `limit` applies.
1171
+ * Filter by state (multiple values OR together). The filter matches the displayed state,
1172
+ * including `needs_intelligence` and `idle_screen` (a row showing either does not match its
1173
+ * raw state), and is applied before `limit`.
1078
1174
  */
1079
1175
  state?: string[];
1080
1176
  /** Filter by label k=v pairs (multiple entries AND together). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],