agl 43.3.0 → 43.3.2

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.
Files changed (80) hide show
  1. package/changelog.md +19 -0
  2. package/dist_serve/bundle.js +2 -2
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_ts/00_commitinfo_data.js +1 -1
  5. package/dist_ts/classes.authstore.d.ts +7 -0
  6. package/dist_ts/classes.authstore.js +9 -1
  7. package/dist_ts/classes.claudeharness.d.ts +13 -2
  8. package/dist_ts/classes.claudeharness.js +12 -5
  9. package/dist_ts/classes.controller.d.ts +38 -10
  10. package/dist_ts/classes.controller.js +160 -91
  11. package/dist_ts/classes.flexservice.d.ts +12 -1
  12. package/dist_ts/classes.flexservice.js +44 -13
  13. package/dist_ts/classes.flexstore.d.ts +20 -0
  14. package/dist_ts/classes.flexstore.js +30 -1
  15. package/dist_ts/classes.mcpcontrollerhost.js +4 -1
  16. package/dist_ts/classes.mcptools.js +6 -1
  17. package/dist_ts/classes.nativesessions.d.ts +12 -0
  18. package/dist_ts/classes.nativesessions.js +1 -1
  19. package/dist_ts/classes.workercallers.js +4 -2
  20. package/dist_ts/driver/classes.directreports.js +19 -19
  21. package/dist_ts/driver/classes.directreportstore.d.ts +8 -1
  22. package/dist_ts/driver/classes.directreportstore.js +20 -10
  23. package/dist_ts/fleet/classes.workers.d.ts +16 -0
  24. package/dist_ts/fleet/classes.workers.js +73 -39
  25. package/dist_ts/fleet/classes.workerstore.js +14 -8
  26. package/dist_ts/fleet/functions.workervalidation.js +10 -3
  27. package/dist_ts/fleet/interfaces.workers.d.ts +6 -2
  28. package/dist_ts/fleet/interfaces.workers.js +8 -4
  29. package/dist_ts/functions.deviceapi.d.ts +50 -3
  30. package/dist_ts/functions.deviceapi.js +174 -7
  31. package/dist_ts/functions.exactpersistence.d.ts +3 -0
  32. package/dist_ts/functions.exactpersistence.js +4 -0
  33. package/dist_ts/functions.mcpfleetworkertools.js +2 -2
  34. package/dist_ts/functions.ticketactor.d.ts +17 -1
  35. package/dist_ts/functions.ticketactor.js +55 -15
  36. package/dist_ts/interfaces.flexipc.d.ts +17 -9
  37. package/dist_ts/interfaces.flexipc.js +19 -20
  38. package/dist_ts_interfaces/devices.d.ts +17 -4
  39. package/dist_ts_interfaces/devices.js +1 -1
  40. package/dist_ts_interfaces/fleetworkers.d.ts +32 -7
  41. package/dist_ts_interfaces/fleetworkers.js +19 -8
  42. package/dist_ts_interfaces/workercallers.d.ts +2 -0
  43. package/dist_ts_migration/classes.documentmigrationrunner.d.ts +14 -0
  44. package/dist_ts_migration/classes.documentmigrationrunner.js +20 -1
  45. package/dist_ts_migration/index.d.ts +1 -0
  46. package/dist_ts_migration/index.js +2 -1
  47. package/dist_ts_migration/v43_ticketactornames.d.ts +32 -0
  48. package/dist_ts_migration/v43_ticketactornames.js +236 -0
  49. package/package.json +5 -5
  50. package/readme.md +35 -4
  51. package/ts/00_commitinfo_data.ts +1 -1
  52. package/ts/classes.authstore.ts +10 -0
  53. package/ts/classes.claudeharness.ts +18 -4
  54. package/ts/classes.controller.ts +169 -96
  55. package/ts/classes.flexservice.ts +57 -14
  56. package/ts/classes.flexstore.ts +40 -0
  57. package/ts/classes.mcpcontrollerhost.ts +3 -0
  58. package/ts/classes.mcptools.ts +5 -0
  59. package/ts/classes.nativesessions.ts +13 -0
  60. package/ts/classes.workercallers.ts +3 -1
  61. package/ts/driver/classes.directreports.ts +18 -18
  62. package/ts/driver/classes.directreportstore.ts +20 -9
  63. package/ts/fleet/classes.workers.ts +66 -39
  64. package/ts/fleet/classes.workerstore.ts +11 -7
  65. package/ts/fleet/functions.workervalidation.ts +7 -2
  66. package/ts/fleet/interfaces.workers.ts +6 -2
  67. package/ts/functions.deviceapi.ts +227 -6
  68. package/ts/functions.exactpersistence.ts +5 -0
  69. package/ts/functions.mcpfleetworkertools.ts +1 -1
  70. package/ts/functions.ticketactor.ts +58 -14
  71. package/ts/interfaces.flexipc.ts +43 -27
  72. package/ts_interfaces/devices.schema.json +5 -2
  73. package/ts_interfaces/devices.ts +20 -4
  74. package/ts_interfaces/fleetworkers.ts +33 -7
  75. package/ts_interfaces/workercallers.ts +2 -0
  76. package/ts_migration/classes.documentmigrationrunner.ts +21 -0
  77. package/ts_migration/index.ts +1 -0
  78. package/ts_migration/v43_ticketactornames.ts +225 -0
  79. package/ts_web/00_commitinfo_data.ts +1 -1
  80. package/ts_web/elements.fleetworker.ts +4 -2
package/readme.md CHANGED
@@ -68,7 +68,7 @@ OpenCode is automatically recovered only after AGL observes the exact owned chil
68
68
 
69
69
  At startup, AGL can reclaim a detached OpenCode listener left by an earlier controller only when its launch metadata records that controller's PID and Linux process start time and that exact owner is no longer live. This works whether Linux reparents the orphan to PID 1, user systemd or a container subreaper. The listener must still match AGL's private runtime directory, user, executable, arguments and verified process group. New launches receive fresh `AGL_OPENCODE_OWNER_IDENTITY` metadata, never an inherited value. A live owner or missing, unreadable, malformed or inconsistent metadata prevents recovery; unmarked listeners from older releases require manual cleanup rather than guessed ownership.
70
70
 
71
- Each Flex project has its own request queue in the Flex child, so a slow request of one project never holds another project's requests. When a request is cancelled — a browser tab that reloads or closes cancels its in-flight reads — the child answers at once: a request still waiting in its project's queue leaves the queue without starting, and a running read is answered as cancelled and stops holding the queue while it finishes in the background. A running write is always carried to its end, and a child that does not settle a cancelled request within two seconds is still stopped and replaced, with the request that missed the grace named in the controller log. Each child generation holds its Flex writer leases under a writer identity of its own. Once AGL has confirmed that a generation's whole process group has exited, the next generation takes over that generation's leases at once, fenced by a higher epoch, instead of waiting 30 seconds for them to expire; a lease whose writer is not proven gone still protects it until it expires. A child that fails to start reports its cause, which the controller log names.
71
+ Each Flex project has its own request queue in the Flex child, so a slow request of one project never holds another project's requests. When a request is cancelled — a browser tab that reloads or closes cancels its in-flight reads — the child answers at once: a request still waiting in its project's queue leaves the queue without starting, and a running read is answered as cancelled and stops holding the queue while it finishes in the background. A running write is always carried to its end, and a child that does not settle a cancelled request within two seconds is still stopped and replaced, with the request that missed the grace named in the controller log. Each child generation holds its Flex writer leases under a writer identity of its own. Once AGL has confirmed that a generation's whole process group has exited, the next generation takes over that generation's leases at once, fenced by a higher epoch, instead of waiting 30 seconds for them to expire; a lease whose writer is not proven gone still protects it until it expires. A child that fails to start reports its cause, which the controller log names. Reconciling a project's session identities when a child starts reads only the project's metadata, never its sessions' histories, so a project with a long history does not hold a new child. Each time the child loads a project's sessions it writes one line to the controller log, `Flex project load: {…}`, with the project, the outcome (`loaded`, `failed` or `aborted`), the number of sessions, the snapshots and bytes read from the database and the time spent parsing them, and the time spent reading the store, hydrating agent sessions and repairing them, and the total.
72
72
 
73
73
  The browser receives normalized AGL data. It never receives the OpenCode server password, provider credentials, private database descriptors, raw provider responses, or Flex private snapshots.
74
74
 
@@ -1767,6 +1767,31 @@ returns every full record unpaged, as `agl fleet worker list` and the private re
1767
1767
  default. `fleet_worker_get` (`name` or `id`) returns one worker's full record, archived ones
1768
1768
  included, with the native status, turn outcome and start, native wait and excerpt the controller
1769
1769
  last observed.
1770
+
1771
+ The fleet's own refusals carry a code (AGL-1670), as a tool's error (`FLEET_UNAVAILABLE` when the
1772
+ fleet is closing or holds 512 jobs) or as a failed job's `errorCode` beside its `error`:
1773
+ `fleet_unavailable` (the fleet admits no job now; try again later), `worker_fenced` (the worker's
1774
+ dispatch fence stands in the way: an unresolved, running or lost dispatch, a reconfirmation
1775
+ without its saved ticket comment, a fence or record another job changed, or no native session
1776
+ yet; read the worker before acting again), `worker_archived`, `ticket_mismatch` (the worker is
1777
+ bound to another ticket), `worker_conflict` (the name is taken, the session is bound already, the
1778
+ harness has no relaunch, the profile is not configured, or the session cannot be adopted as that
1779
+ identity; change the request) and `worker_not_found` (the owner has no worker of that name). A failed job without `errorCode` failed with a harness's or another
1780
+ dependency's own text, which `error` keeps as it was for the driver and the CLI; the Driver view
1781
+ and a device show that failure only as "The controller operation failed." with the failure
1782
+ journal's reference.
1783
+
1784
+ A failed job also says whether what it dispatched may have reached a native session (AGL-1691),
1785
+ as `errorOutcome`, which only a failed job carries: `refused` when nothing can have, because the
1786
+ job failed before its first dispatch with a refusal (the fleet's own, or a native-message session
1787
+ it may not wake) or its dispatch proved it sent nothing; `unknown` otherwise, a steer that may
1788
+ have been delivered, a stop that may have stopped, and every failure without that proof, the
1789
+ fleet's own refusal after a dispatch (a fence that changed while it ran) included. A job of
1790
+ unknown outcome is never repeated on its own: read the worker (`fleet_worker_get`) first.
1791
+ `fleet_worker_job_wait`, `fleet_worker_status` and the driver tools return the job with it; a
1792
+ failed job without it, from an older controller, is `unknown`. The Driver view shows such a steer
1793
+ as "The steer's outcome is unknown" and keeps the draft, and a device's direct report message
1794
+ reads `outcome_unknown`.
1770
1795
  Worker mutations and reports require a ticket key; mismatched associations refuse before
1771
1796
  native effects. Refresh and moves retain the ticket and the associating driver's attribution.
1772
1797
  Existing unassociated bindings remain readable and may be explicitly adopted after proving
@@ -2435,7 +2460,12 @@ All ten CLI actions accept `--port` and `--json`; `agl ticket --help` documents
2435
2460
  options. The running controller is required. `update` and `assign` require `--expected-revision`
2436
2461
  from the ticket the editor read; neither command fetches a newer revision before saving.
2437
2462
  `assign --clear` unassigns. Session names
2438
- are display-only; a worker's activity always carries the registry-derived actor.
2463
+ are display-only; a worker's activity always carries the registry-derived actor. A ticket names
2464
+ that actor by its role, never by its session id: the owner's active direct report its session is,
2465
+ else its fleet worker's name, else its harness's label (`Claude Code session`, `Codex session`,
2466
+ `OpenCode session`, `Flex session`); the shared OpenCode runtime is `OpenCode`. Tickets an
2467
+ earlier release stored under a session id take the harness's label once, at the first start of
2468
+ this release (migration `v43_ticketactornames`).
2439
2469
 
2440
2470
  The CLI (and an `agl mcp` server holding the local-owner capability) writes as the `driver`
2441
2471
  role, named after the OS user. A write also records the Claude Code session the CLI runs inside
@@ -3794,9 +3824,10 @@ The device API is its own contract, separate from the browser's: `ts_interfaces/
3794
3824
  - A message from a device is a direct message (it queues behind a running turn), never the browser's shared draft. A native session AGL does not write to (another process runs it, a fleet worker owns it) refuses it, as it refuses the browser.
3795
3825
  - A device answers as the owner on its own authenticated connection, audited as the device. Its Inbox lists the driver's turn and the driver's own prompts without an answer (the driver session is no feed row), and a native wait as information. A child's answer is sent only after the controller proved the child a running direct child of the session, as it does for the browser.
3796
3826
  - The driver is the browser's Driver view on a device: `device.driver.get` answers its status (activity, unread turns, title, the `needs input:` line its last turn ended on, never its project or session), `device.driver.seen` marks its ended turns seen (one unread count for every client), `device.driver.read` pages its transcript as `device.session.read` does and lists its own prompts, which a device shows but does not answer, and `device.driver.send` sends it a direct message. Without a driver session read and send are refused with `driver_absent`: the owner starts the driver in the browser, a device never does.
3797
- - `device.directreports.list` lists the active direct reports as the Driver view does, each by its name, with its session as the feed names it, status, projects, ticket, newest `result:` line, open questions and the fleet workers that report to it (name, harness, status, ticket; no directories or profiles), and whether it takes a message. `device.directreport.message` sends one the owner's message as the Driver view does: a fleet worker report is steered through its ticket and answers `fleet` once the steer succeeded (a failed steer is refused with `direct_report_failed` and the fleet's reason); a Codex thread takes it as the owner's agent message, `steer` into the turn AGL runs or `next-turn`. A turn another Codex client runs is refused with `direct_report_busy` (nothing was sent), a Claude Code session the fleet does not run with `direct_report_failed`, and messages to a report faster than its agent message rate with `rate_limited`. Messages are audited as `session.message` from `Owner` for the device.
3827
+ - `device.directreports.list` lists the active direct reports as the Driver view does, each by its name, with its session as the feed names it, status, projects, ticket, newest `result:` line, open questions and the fleet workers that report to it (name, harness, status, ticket; no directories or profiles), and whether it takes a message. `device.directreport.message` sends one the owner's message as the Driver view does: a fleet worker report is steered through its ticket and answers `fleet` once the steer succeeded (a steer the fleet refused before its dispatch is refused with `direct_report_failed` and the fleet's own text, such as "Worker is archived.", or "The controller operation failed." with the failure journal's reference where a harness's own text failed it; a steer that failed after its dispatch, or whose job does not prove it sent nothing (`errorOutcome` other than `refused`), may have delivered the message and is `outcome_unknown`, "The request may have taken effect. Read again to learn whether it did before sending it again." with the failure journal's reference, which a client never sends again on its own); a Codex thread takes it as the owner's agent message, `steer` into the turn AGL runs or `next-turn`. A turn another Codex client runs is refused with `direct_report_busy` (nothing was sent), a Claude Code session the fleet does not run with `direct_report_failed`, and messages to a report faster than its agent message rate with `rate_limited`. Messages are audited as `session.message` from `Owner` for the device.
3798
3828
  - The Host view is read-only (AGL-824): a device changes nothing on the host (no deploy or deploy probe, account, setting, upgrade or pairing). `device.host.get` answers what runs (`agl`: the AGL release, its start, its public origin, and whether a device reaches it through the gateway AGL keeps its route on, with where that route's sync stands, or through the owner's own reverse proxy; never the gateway's address, the client or the route's target), the device itself as the controller keeps it (`device`: name, model, when it paired and when it last connected; a device neither renames nor unpairs itself), the deploy targets (`deploys`: what each runs and since when, whether its probe answers, its newest release, the released versions it does not run (`undeployed`, newest first), and its planned deploys (`plans`: the ticket, the version, the owner's go and, for one queued into a maintenance window, the window's times); never a probe's address, the owner's notes on how it deploys and what a deploy interrupts, a failed probe's text, a plan's question or who deploys it, and the read runs no probe), the inference proxy's account pools (`pools`: each pool's verdict and room, and its accounts by plan and then the most used first, each only as its plan, state and the usage window it is bound by: no account id, and no order that stands in for one) and the API keys (`apiKeys`: per provider, how many keys are under their monthly spend limit, held at it, without one, or not read, judged by the rule AGL's inference proxy places by; no label, email, id or dollar amount). `deploys`, `pools` and `apiKeys` each answer `ready` or `unavailable` on their own, with the reason (`not_running`, `outdated`, or `failed` with the failure journal's `reference`), and the request still answers the others. `host.changed` (no payload) says when to read it again: the deploy targets, their planned deploys (tickets) or the accounts changed. Usage moves without an event, so a client reads it again when the Host view is opened or refreshed.
3799
- - The shared board on a device is the browser's board (AGL-1637). `device.board.list` answers one column at a time, as the browser shows its cards (the tasks; an epic and a subtask open with `device.ticket.get`), in the column's order, `limit` (1 to 100, default 50) from `offset`, filtered as the browser filters: `text` (1 to 200 characters, in the key, title, description and source words), `project`, `epic` (the epic's own tasks), `assignee` (`{ kind: 'owner' }`, `{ kind: 'unassigned' }` or a session as the feed names it) and an AutoLabel (`openQuestion`, `planned`, `undeployed`). Every column's count under the same filters comes from the same read as the page, with `total`, the projects the board's tickets name, the epics a filter may choose and the board's `revision`: when a later page answers another revision, or `tickets.changed` arrives, a client reads the board again from offset 0. `device.ticket.get` answers a ticket with its description, source words, links and parent, one page of its discussion (comments and questions together in the order they were written, newest page first, at most `limit` of 1 to 50 and 256 KiB, `before` for the next older page), where it runs (`placement`, from the deploy monitor, `unavailable` on its own as a section of `device.host.get` is) and what it plans (`plans`: the release plan, the maintenance window and the deploy plan, with where the window stands and the owner's go while the monitor answers); no history of its other changes, no source attachments, no plan's question and nothing that names who deploys it. People appear by name: the owner as `kind: 'owner'`, never the owner's account, a person's id or a session the feed does not list (the driver's own session included). `device.ticket.comment` (Markdown, at most 64 KiB as the store keeps it), `device.ticket.ask` (text alone, at most 16 KiB, answered with text) and `device.ticket.move` (to the end of a column; "Move to…" stands in for the browser's drag) run the browser board's own function as the owner, audited as `ticket.comment`, `ticket.ask` and `ticket.move` for the device; `device.ticket.answer` answers a question. The controller decides every change: a refusal changes nothing and carries the ticket store's own code (`deviceTicketRefusalCodes`, such as `ticket_review_branch_required` for a move to review without a branch) and its reason. The app then keeps the owner's draft, reads the ticket again and shows the reason; it never sends a refused change again on its own. A change whose outcome AGL cannot tell is refused as `controller_unavailable` for now and stays fenced: the app reads the ticket again before the owner decides (AGL-1670 gives it a code of its own that a client never resends). Creating, editing and assigning tickets stay in the browser.
3829
+ - The shared board on a device is the browser's board (AGL-1637). `device.board.list` answers one column at a time, as the browser shows its cards (the tasks; an epic and a subtask open with `device.ticket.get`), in the column's order, `limit` (1 to 100, default 50) from `offset`, filtered as the browser filters: `text` (1 to 200 characters, in the key, title, description and source words), `project`, `epic` (the epic's own tasks), `assignee` (`{ kind: 'owner' }`, `{ kind: 'unassigned' }` or a session as the feed names it) and an AutoLabel (`openQuestion`, `planned`, `undeployed`). Every column's count under the same filters comes from the same read as the page, with `total`, the projects the board's tickets name, the epics a filter may choose and the board's `revision`: when a later page answers another revision, or `tickets.changed` arrives, a client reads the board again from offset 0. `device.ticket.get` answers a ticket with its description, source words, links and parent, one page of its discussion (comments and questions together in the order they were written, newest page first, at most `limit` of 1 to 50 and 256 KiB, `before` for the next older page), where it runs (`placement`, from the deploy monitor, `unavailable` on its own as a section of `device.host.get` is) and what it plans (`plans`: the release plan, the maintenance window and the deploy plan, with where the window stands and the owner's go while the monitor answers); no history of its other changes, no source attachments, no plan's question and nothing that names who deploys it. People appear by name: the owner as `kind: 'owner'`, never the owner's account, a person's id or a session the feed does not list (the driver's own session included). `device.ticket.comment` (Markdown, at most 64 KiB as the store keeps it), `device.ticket.ask` (text alone, at most 16 KiB, answered with text) and `device.ticket.move` (to the end of a column; "Move to…" stands in for the browser's drag) run the browser board's own function as the owner, audited as `ticket.comment`, `ticket.ask` and `ticket.move` for the device; `device.ticket.answer` answers a question. The controller decides every change: a refusal changes nothing and carries the ticket store's own code (`deviceTicketRefusalCodes`, such as `ticket_review_branch_required` for a move to review without a branch) and its reason. The app then keeps the owner's draft, reads the ticket again and shows the reason; it never sends a refused change again on its own. A change whose outcome AGL cannot tell is refused as `outcome_unknown` and stays fenced: the app reads the ticket again to learn whether it happened before the owner decides, and never sends it again on its own. Creating, editing and assigning tickets stay in the browser.
3830
+ - Every refusal of every device method carries one code of `TDeviceRefusalCode` as `error.data.code` and a message to show, whatever the controller refused it with (AGL-1670): the set is closed, and within a major it only grows. The pairing and the connection: `device_unknown` (forget the pairing), `device_pairing_invalid`, `device_pairing_unavailable`, `device_limit`, `device_already_paired`, `device_proof_invalid`, `device_challenge_invalid` and `device_authentication_required`. What the request names is gone: `session_not_found` (list the feed again), `driver_absent`, and the ticket store's `ticket_not_found` and `ticket_question_not_found`. Nothing was done because something else changed meanwhile, so read again, then decide: `concurrent_change`, `ticket_revision_conflict` and `direct_report_busy`. Refused by a rule, with the reason: `session_read_only` (including a session whose model or stopped message the owner resolves in the browser first), `invalid_request`, `direct_report_failed` and the ticket store's other codes (`deviceTicketRefusalCodes`). Limits: `rate_limited`, final as every refusal, and `operation_limit`. The controller: `controller_unavailable` (not ready: starting, stopping, or a harness or the Flex child not running) and `controller_failed` (a fault, always "The controller operation failed."; `error.data.reference` names the failure journal entry the owner's browser shows, and no message to a device carries a raw cause such as a socket path or a spawn error). `outcome_unknown` means the request may have happened: AGL dispatched it, or may have, and cannot tell whether it took effect. A client never resends it on its own; it keeps the owner's text, reads the session, the driver or the ticket again to learn the outcome, and the owner decides.
3800
3831
  - The controller pushes a device an allowlist of events in their own shape: feed changes, a session's change, its streaming text (snapshots and exact deltas), Inbox changes, the driver's changes (`driver.changed` with its status, also when its transcript or prompts changed, never its streaming text), the direct reports' changes (`directreports.changed`, with no payload, also when fleet workers or tickets changed), the host's changes (`host.changed`, with no payload, when the deploy targets or the accounts changed), the board's changes (`tickets.changed`, with no ticket key and with the board's revision when it moved, followed by `directreports.changed` and `host.changed`, since tickets hold the reports' questions and the planned deploys) and a resynchronization request. Every other event, and every event about a session the feed does not list, stays on the controller. A device that falls behind by 256 events or 4 MiB is resynchronized alone: on `sessions.changed` it lists the feed and reads the open session again, an open Driver view included (the driver's own changes may have folded into it).
3801
3832
  - Through the gateway, a device's WebSocket upgrade carries the public origin as `Origin`, like a browser's (Admission).
3802
3833
 
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: 'agl',
6
- version: '43.3.0',
6
+ version: '43.3.2',
7
7
  description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
8
8
  }
@@ -1618,6 +1618,16 @@ export class SmartDataAuthStore implements IAuthStore, IAuthStoreSessionIdentity
1618
1618
  return await new PostDatabaseDocumentMigrationRunner(this.database).runTicketClosedColumn();
1619
1619
  }
1620
1620
 
1621
+ /** AGL-1686: once, ticket people and actors named by their session id are named by their role; answers the keys it moved. */
1622
+ public async migrateTicketActorNames(): Promise<string[]> {
1623
+ return await new PostDatabaseDocumentMigrationRunner(this.database).runTicketActorNames();
1624
+ }
1625
+
1626
+ /** The ticket migrations of a controller start, in the runner's order; answers what v41 moved and v43 renamed. */
1627
+ public async migrateTicketsAtStart(): Promise<{ closed: string[]; renamed: string[] }> {
1628
+ return await new PostDatabaseDocumentMigrationRunner(this.database).runTicketStart(ticketOwnerPrincipalId(await this.getState()));
1629
+ }
1630
+
1621
1631
  /**
1622
1632
  * AGL-909: once, links and release plans name each repository `resolveArg` resolves as `org/name`; answers the keys it
1623
1633
  * changed. With no repository discovered (`discoveredArg` 0) it waits for a later start.
@@ -38,11 +38,23 @@ export const isClaudeEffort = (valueArg: unknown): valueArg is TClaudeEffort =>
38
38
  */
39
39
  export type TClaudeSteerOutcome = 'taken' | 'interrupted' | 'failed';
40
40
 
41
- /** A message that could not be handed over; `dispatched` says whether it may have reached Claude Code. */
41
+ /**
42
+ * Why Claude Code took no message although nothing failed: `busy`, the conversation is still working; `capacity`, as many
43
+ * Claude Code conversations work as the host runs at once. A sender may try again once it ended.
44
+ */
45
+ export type TClaudeDispatchRefusal = 'busy' | 'capacity';
46
+
47
+ /**
48
+ * A message that could not be handed over; `dispatched` says whether it may have reached Claude Code, and `refusal`
49
+ * names a refusal before dispatch that a busy conversation or host caused.
50
+ */
42
51
  export class ClaudeHarnessDispatchError extends Error {
43
- constructor(messageArg: string, public readonly dispatched: boolean, optionsArg?: ErrorOptions) {
52
+ public readonly refusal?: TClaudeDispatchRefusal;
53
+
54
+ constructor(messageArg: string, public readonly dispatched: boolean, optionsArg?: ErrorOptions & { refusal?: TClaudeDispatchRefusal }) {
44
55
  super(messageArg, optionsArg);
45
56
  this.name = 'ClaudeHarnessDispatchError';
57
+ if (optionsArg?.refusal !== undefined) this.refusal = optionsArg.refusal;
46
58
  }
47
59
  }
48
60
 
@@ -367,7 +379,7 @@ export class ClaudeHarness {
367
379
  const state = this.state(nativeIdArg);
368
380
  if (!isClaudeSessionNativeId(inputArg.uuid)) throw new ClaudeHarnessDispatchError('Invalid Claude Code message id.', false);
369
381
  if (state.turn || this.busy(state)) {
370
- throw new ClaudeHarnessDispatchError('Claude Code is still working in this conversation. Wait for it to finish, or queue the message.', false);
382
+ throw new ClaudeHarnessDispatchError('Claude Code is still working in this conversation. Wait for it to finish, or queue the message.', false, { refusal: 'busy' });
371
383
  }
372
384
  const command = this.command(inputArg.uuid, 'turn', () => inputArg.complete(), inputArg.onUserMessage);
373
385
  state.turn = command;
@@ -814,7 +826,9 @@ export class ClaudeHarness {
814
826
  const idle = [...this.runtimes.values()]
815
827
  .filter((runtime) => !this.busyRuntime(runtime))
816
828
  .sort((left, right) => left.usedAt - right.usedAt)[0];
817
- if (!idle) throw new ClaudeHarnessDispatchError('Too many Claude Code conversations are working at once. Try again when one has finished.', false);
829
+ if (!idle) {
830
+ throw new ClaudeHarnessDispatchError('Too many Claude Code conversations are working at once. Try again when one has finished.', false, { refusal: 'capacity' });
831
+ }
818
832
  this.closeRuntime(idle);
819
833
  }
820
834
  }