agl 42.2.2 → 43.0.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.
Files changed (179) hide show
  1. package/changelog.md +24 -0
  2. package/dist_serve/bundle.js +6697 -5287
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +29 -29
  5. package/dist_serve/bundle.js.third-party-notices.txt +29 -29
  6. package/dist_serve/third-party-notices.md +597 -8
  7. package/dist_ts/00_commitinfo_data.js +1 -1
  8. package/dist_ts/aglapi/aglapisurface.document.js +114 -16
  9. package/dist_ts/aglapi/interfaces.d.ts +30 -0
  10. package/dist_ts/aglapi/interfaces.js +7 -1
  11. package/dist_ts/classes.authstore.d.ts +7 -0
  12. package/dist_ts/classes.authstore.js +12 -1
  13. package/dist_ts/classes.browserpainttransport.d.ts +2 -2
  14. package/dist_ts/classes.browserpainttransport.js +9 -8
  15. package/dist_ts/classes.browserresourcehost.js +30 -20
  16. package/dist_ts/classes.cli.js +10 -1
  17. package/dist_ts/classes.controller.d.ts +41 -11
  18. package/dist_ts/classes.controller.js +232 -52
  19. package/dist_ts/classes.harnessoperationmanager.d.ts +44 -0
  20. package/dist_ts/classes.harnessoperationmanager.js +15 -10
  21. package/dist_ts/classes.mcpclient.d.ts +5 -0
  22. package/dist_ts/classes.mcpclient.js +15 -3
  23. package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -0
  24. package/dist_ts/classes.mcpcontrollerhost.js +17 -3
  25. package/dist_ts/classes.mcptools.d.ts +4 -3
  26. package/dist_ts/classes.mcptools.js +20 -1
  27. package/dist_ts/classes.mcpvalidation.js +4 -1
  28. package/dist_ts/classes.ticketstore.d.ts +71 -3
  29. package/dist_ts/classes.ticketstore.js +299 -12
  30. package/dist_ts/classes.validation.d.ts +2 -0
  31. package/dist_ts/classes.validation.js +27 -5
  32. package/dist_ts/driver/classes.directreports.d.ts +23 -3
  33. package/dist_ts/driver/classes.directreports.js +59 -2
  34. package/dist_ts/driver/classes.drivereventrelay.js +3 -2
  35. package/dist_ts/driver/functions.driverinstructions.d.ts +1 -1
  36. package/dist_ts/driver/functions.driverinstructions.js +12 -3
  37. package/dist_ts/driver/functions.drivertools.d.ts +4 -0
  38. package/dist_ts/driver/functions.drivertools.js +8 -2
  39. package/dist_ts/fleet/classes.boardpump.d.ts +53 -3
  40. package/dist_ts/fleet/classes.boardpump.js +237 -32
  41. package/dist_ts/fleet/classes.claudeworkers.d.ts +10 -3
  42. package/dist_ts/fleet/classes.claudeworkers.js +43 -19
  43. package/dist_ts/fleet/classes.codexworkers.d.ts +5 -3
  44. package/dist_ts/fleet/classes.codexworkers.js +26 -9
  45. package/dist_ts/fleet/classes.deploymonitor.d.ts +253 -0
  46. package/dist_ts/fleet/classes.deploymonitor.js +821 -0
  47. package/dist_ts/fleet/classes.gitfacts.d.ts +61 -0
  48. package/dist_ts/fleet/classes.gitfacts.js +125 -0
  49. package/dist_ts/fleet/classes.releasereconciler.d.ts +51 -0
  50. package/dist_ts/fleet/classes.releasereconciler.js +101 -0
  51. package/dist_ts/fleet/classes.service.d.ts +13 -1
  52. package/dist_ts/fleet/classes.service.js +76 -7
  53. package/dist_ts/fleet/classes.ticketeffects.d.ts +13 -0
  54. package/dist_ts/fleet/classes.ticketeffects.js +42 -8
  55. package/dist_ts/fleet/classes.workers.d.ts +10 -3
  56. package/dist_ts/fleet/classes.workers.js +18 -3
  57. package/dist_ts/fleet/functions.controllerbuild.d.ts +23 -0
  58. package/dist_ts/fleet/functions.controllerbuild.js +75 -0
  59. package/dist_ts/fleet/functions.deployprobes.d.ts +39 -0
  60. package/dist_ts/fleet/functions.deployprobes.js +82 -0
  61. package/dist_ts/fleet/functions.deployvalidation.d.ts +27 -0
  62. package/dist_ts/fleet/functions.deployvalidation.js +43 -0
  63. package/dist_ts/fleet/functions.release.d.ts +2 -1
  64. package/dist_ts/fleet/functions.release.js +32 -5
  65. package/dist_ts/fleet/functions.releasefacts.d.ts +42 -0
  66. package/dist_ts/fleet/functions.releasefacts.js +46 -0
  67. package/dist_ts/fleet/functions.validation.d.ts +3 -3
  68. package/dist_ts/fleet/functions.validation.js +4 -7
  69. package/dist_ts/fleet/functions.watchprobes.js +7 -9
  70. package/dist_ts/fleet/functions.workervalidation.js +4 -3
  71. package/dist_ts/fleet/interfaces.workers.d.ts +30 -3
  72. package/dist_ts/fleet/interfaces.workers.js +14 -1
  73. package/dist_ts/functions.deploycli.d.ts +36 -0
  74. package/dist_ts/functions.deploycli.js +157 -0
  75. package/dist_ts/functions.mcpdeploytools.d.ts +13 -0
  76. package/dist_ts/functions.mcpdeploytools.js +16 -0
  77. package/dist_ts/functions.mcptickettools.d.ts +54 -0
  78. package/dist_ts/functions.mcptickettools.js +8 -7
  79. package/dist_ts/functions.ticketautolabels.d.ts +2 -0
  80. package/dist_ts/functions.ticketautolabels.js +9 -3
  81. package/dist_ts/functions.ticketcli.d.ts +16 -2
  82. package/dist_ts/functions.ticketcli.js +105 -27
  83. package/dist_ts/functions.ticketvalidation.d.ts +55 -0
  84. package/dist_ts/functions.ticketvalidation.js +26 -8
  85. package/dist_ts_interfaces/deployments.d.ts +241 -0
  86. package/dist_ts_interfaces/deployments.js +5 -6
  87. package/dist_ts_interfaces/fleet.d.ts +12 -0
  88. package/dist_ts_interfaces/fleetworkers.d.ts +21 -1
  89. package/dist_ts_interfaces/functions.fleetversion.d.ts +4 -0
  90. package/dist_ts_interfaces/functions.fleetversion.js +25 -0
  91. package/dist_ts_interfaces/interfaces.d.ts +4 -2
  92. package/dist_ts_interfaces/interfaces.js +4 -2
  93. package/dist_ts_interfaces/mcprequests.d.ts +3 -2
  94. package/dist_ts_interfaces/mcprequests.js +3 -1
  95. package/dist_ts_interfaces/requests.d.ts +3 -2
  96. package/dist_ts_interfaces/requests.directreports.d.ts +58 -6
  97. package/dist_ts_interfaces/requests.js +1 -1
  98. package/dist_ts_interfaces/requests.tickets.d.ts +25 -5
  99. package/dist_ts_interfaces/requests.tickets.js +2 -2
  100. package/dist_ts_interfaces/tickets.d.ts +71 -6
  101. package/dist_ts_interfaces/tickets.js +34 -6
  102. package/dist_ts_migration/classes.documentmigrationrunner.d.ts +7 -0
  103. package/dist_ts_migration/classes.documentmigrationrunner.js +14 -1
  104. package/dist_ts_migration/index.d.ts +2 -0
  105. package/dist_ts_migration/index.js +3 -1
  106. package/dist_ts_migration/v41_ticketclosedcolumn.d.ts +20 -0
  107. package/dist_ts_migration/v41_ticketclosedcolumn.js +118 -0
  108. package/dist_ts_migration/v41_ticketlinkrepos.d.ts +24 -0
  109. package/dist_ts_migration/v41_ticketlinkrepos.js +101 -0
  110. package/package.json +6 -2
  111. package/readme.md +308 -36
  112. package/third-party-notices.md +597 -8
  113. package/ts/00_commitinfo_data.ts +1 -1
  114. package/ts/aglapi/aglapisurface.document.ts +113 -15
  115. package/ts/aglapi/interfaces.ts +6 -0
  116. package/ts/classes.authstore.ts +13 -0
  117. package/ts/classes.browserpainttransport.ts +8 -7
  118. package/ts/classes.browserresourcehost.ts +38 -14
  119. package/ts/classes.cli.ts +9 -0
  120. package/ts/classes.controller.ts +244 -61
  121. package/ts/classes.harnessoperationmanager.ts +20 -14
  122. package/ts/classes.mcpclient.ts +17 -2
  123. package/ts/classes.mcpcontrollerhost.ts +18 -2
  124. package/ts/classes.mcptools.ts +21 -2
  125. package/ts/classes.mcpvalidation.ts +2 -0
  126. package/ts/classes.ticketstore.ts +312 -13
  127. package/ts/classes.validation.ts +28 -4
  128. package/ts/driver/classes.directreports.ts +58 -3
  129. package/ts/driver/classes.drivereventrelay.ts +2 -1
  130. package/ts/driver/functions.driverinstructions.ts +11 -2
  131. package/ts/driver/functions.drivertools.ts +10 -2
  132. package/ts/fleet/classes.boardpump.ts +235 -28
  133. package/ts/fleet/classes.claudeworkers.ts +36 -15
  134. package/ts/fleet/classes.codexworkers.ts +24 -7
  135. package/ts/fleet/classes.deploymonitor.ts +854 -0
  136. package/ts/fleet/classes.gitfacts.ts +135 -0
  137. package/ts/fleet/classes.releasereconciler.ts +103 -0
  138. package/ts/fleet/classes.service.ts +81 -8
  139. package/ts/fleet/classes.ticketeffects.ts +38 -6
  140. package/ts/fleet/classes.workers.ts +19 -5
  141. package/ts/fleet/functions.controllerbuild.ts +84 -0
  142. package/ts/fleet/functions.deployprobes.ts +84 -0
  143. package/ts/fleet/functions.deployvalidation.ts +50 -0
  144. package/ts/fleet/functions.release.ts +32 -3
  145. package/ts/fleet/functions.releasefacts.ts +74 -0
  146. package/ts/fleet/functions.validation.ts +3 -6
  147. package/ts/fleet/functions.watchprobes.ts +6 -8
  148. package/ts/fleet/functions.workervalidation.ts +3 -2
  149. package/ts/fleet/interfaces.workers.ts +23 -3
  150. package/ts/functions.deploycli.ts +156 -0
  151. package/ts/functions.mcpdeploytools.ts +18 -0
  152. package/ts/functions.mcptickettools.ts +7 -6
  153. package/ts/functions.ticketautolabels.ts +10 -2
  154. package/ts/functions.ticketcli.ts +100 -24
  155. package/ts/functions.ticketvalidation.ts +26 -7
  156. package/ts_interfaces/deployments.ts +194 -0
  157. package/ts_interfaces/fleet.ts +17 -2
  158. package/ts_interfaces/fleetworkers.ts +20 -0
  159. package/ts_interfaces/functions.fleetversion.ts +20 -0
  160. package/ts_interfaces/interfaces.ts +3 -1
  161. package/ts_interfaces/mcprequests.ts +3 -0
  162. package/ts_interfaces/requests.directreports.ts +52 -8
  163. package/ts_interfaces/requests.tickets.ts +20 -4
  164. package/ts_interfaces/requests.ts +6 -1
  165. package/ts_interfaces/tickets.ts +53 -6
  166. package/ts_migration/classes.documentmigrationrunner.ts +15 -0
  167. package/ts_migration/index.ts +2 -0
  168. package/ts_migration/v41_ticketclosedcolumn.ts +106 -0
  169. package/ts_migration/v41_ticketlinkrepos.ts +91 -0
  170. package/ts_web/00_commitinfo_data.ts +1 -1
  171. package/ts_web/elements.deployments.ts +1066 -0
  172. package/ts_web/elements.directreport.ts +2 -2
  173. package/ts_web/elements.directreportsession.ts +5 -5
  174. package/ts_web/elements.harnesscontrollerapp.ts +179 -13
  175. package/ts_web/elements.makedirectreport.ts +444 -0
  176. package/ts_web/elements.nativesession.ts +29 -1
  177. package/ts_web/elements.ticketboard.ts +74 -18
  178. package/ts_web/functions.deployments.ts +231 -0
  179. package/ts_web/functions.sessionchat.ts +2 -0
@@ -7,7 +7,7 @@ export const defaultDriverInstructions = `# You are the AGL driver on this host
7
7
  You keep the owner's board true and the work moving. The owner talks to you through the Driver button. Your direct reports drive the projects: you appoint them, route between them, relay the owner's answers and keep the board current. You act as the verified driver: ticket changes you make carry the driver role.
8
8
 
9
9
  ## Direct reports
10
- - A direct report is a full-authority project driver: it owns one or more board projects (or a cross-project initiative) and drives them on its own. It dispatches its own workers, lands, releases and deploys within its subject, and reports to you.
10
+ - A direct report is a full-authority project driver: it owns one or more board projects (or a cross-project initiative) and drives them on its own. It dispatches its own workers, lands, releases and deploys within its subject, and reports to you. A deploy stall on a report's subject goes to that report.
11
11
  - Never gate a direct report. Do not hold its landings, releases or deploys for your approval, and do not do its work for it. Its workers are its own: do not steer or stop them.
12
12
  - Appoint a running fleet worker with directreport_appoint, or adopt a session with directreport_adopt. A Claude Code session is adopted with a relaunch: its owner stops it first, and the fleet resumes it under its own control so it calls AGL with a verified identity. Never adopt a session that still runs, and never stop one to adopt it. Retire a report with directreport_retire.
13
13
  - directreport_list is your digest: each report's status, newest \`result:\` line and open owner questions. Read a report's recent conversation with directreport_read, and message it with directreport_message, which steers a fleet worker through its driver ticket and gives a Codex thread an agent message from "Driver"; steering a turn another Codex client runs needs the turnId directreport_read returned. Batch what you have for one report into one message.
@@ -18,7 +18,9 @@ You keep the owner's board true and the work moving. The owner talks to you thro
18
18
 
19
19
  ## The board is the queue
20
20
  - Every owner request becomes a ticket, with the owner's words as its source. Split large requests into an epic with tasks, and put each on the project of the report that owns it.
21
- - A landing links the branch and full sha and moves the ticket to landed; a release links package and version and moves it to released. Reports go onto the ticket as comments.
21
+ - Fleet links the evidence: a landing links the branch and full sha and moves the ticket to landed. A release is a tag on the remote: AGL links and releases every landed ticket the first remote tag holding its landing contains, whoever cut the tag. Do not link releases by hand. Reports go onto the ticket as comments.
22
+ - A planned release is a ticket with a release plan (ticket_update releasePlan: the repository as org/name and, optionally, the version); it shows as planned until it is released. A hotfix is a release plan on an urgent ticket, without a version: gitzone picks the version from what landed. fleet_release for that ticket checks the plans, and refuses while its work is not on main.
23
+ - A bug is found in a version (ticket_link affects REPO@VERSION). Link its fix in the repository it was found in, even when the fix is a dependency bump there: AGL tells where a fix runs from the commit that landed in that repository. You may remove a wrong affects link (ticket_unlink); code and release links are the owner's.
22
24
  - Keep the board true: a ticket's column says where its work really is.
23
25
 
24
26
  ## Routing
@@ -36,6 +38,13 @@ You keep the owner's board true and the work moving. The owner talks to you thro
36
38
  - Releases and pushes of your own lanes are yours to do. Your own deploys happen only when the owner says so.
37
39
  - Never restart, stop or upgrade the running AGL controller or proxy.
38
40
 
41
+ ## Deployments
42
+ - What runs where is deploy_status, never your notes or memory. release_status says what a repository's next release would ship.
43
+ - Every deploy needs the owner's word, given on a deploy plan: a ticket whose deployPlan names the target and the release. AGL asks the owner on it (deploy now, in the next window, or hold) and closes the ticket once the target runs the release. The board pump plans one for a target that runs behind a release out for a day; you may plan one yourself (ticket_create or ticket_update deployPlan). Never deploy what waits for the owner's answer or is held.
44
+ - A plan assigned to a direct report is that report's subject: it deploys, and the owner's answer reaches it; route the pump's notices about it to that report. An unassigned plan is yours to deploy.
45
+ - When a deploy may run is the target's (deploy_status deployWhen): any time; only inside a maintenance window planned for it; or, for the AGL controller, when no session is busy. "Deploy now" is the owner's word to deploy at once, outside a window too. "In the next window" waits for the target's next window the owner gave: propose one when none is (a ticket with a maintenanceWindow: from, to, targets), which asks the owner and counts once approved. Only the owner answers a deploy plan's or a window's question. The controller is deployed with agl upgrade, which keeps its own owner gate.
46
+ - After any deploy, run deploy_probe for the target.
47
+
39
48
  ## Root causes
40
49
  - Fix every defect in the component that owns it. Never let a consumer compensate for an upstream defect with a workaround.
41
50
  - A workaround is unfinished work: do not report a lane done while one remains.
@@ -2,6 +2,8 @@ import * as plugins from '../plugins.js';
2
2
  import { fleetToolDefinitions } from '../functions.mcpfleettools.js';
3
3
  import { fleetWorkerToolDefinitions } from '../functions.mcpfleetworkertools.js';
4
4
  import { ticketToolDefinitions } from '../functions.mcptickettools.js';
5
+ import { deployToolDefinitions } from '../functions.mcpdeploytools.js';
6
+ import type { TFleetDeployOperation } from '../../ts_interfaces/deployments.js';
5
7
  import { ticketInputSchemas } from '../functions.ticketvalidation.js';
6
8
  import type { TFleetWorkerAction } from '../../ts_interfaces/fleetworkers.js';
7
9
  import type { TTicketOperation } from '../../ts_interfaces/tickets.js';
@@ -12,7 +14,8 @@ export type TDriverToolRoute =
12
14
  | { kind: 'worker'; action: TFleetWorkerAction }
13
15
  | { kind: 'ticket'; operation: TTicketOperation }
14
16
  | { kind: 'notes'; operation: 'read' | 'update' }
15
- | { kind: 'directreport'; operation: TDriverDirectReportOperation };
17
+ | { kind: 'directreport'; operation: TDriverDirectReportOperation }
18
+ | { kind: 'deploy'; operation: TFleetDeployOperation };
16
19
  export type TDriverDirectReportOperation = 'list' | 'appoint' | 'adopt' | 'retire' | 'read' | 'message';
17
20
 
18
21
  export interface IDriverToolDefinition {
@@ -28,7 +31,7 @@ export interface IDriverToolDefinition {
28
31
  * Observing a job or the event stream polls state that changes outside the turn, so a repeated call
29
32
  * must run again instead of returning the turn's earlier answer.
30
33
  */
31
- const pollingToolNames: ReadonlySet<string> = new Set(['fleet_status', 'fleet_worker_status', 'fleet_watch']);
34
+ const pollingToolNames: ReadonlySet<string> = new Set(['fleet_status', 'fleet_worker_status', 'fleet_watch', 'deploy_status', 'deploy_history', 'release_status']);
32
35
 
33
36
  /** A direct report's conversation is read in bundles, the newest first in reverse. */
34
37
  export const driverDirectReportReadDefaultLimit = 10;
@@ -111,6 +114,11 @@ export const driverToolDefinitions: readonly IDriverToolDefinition[] = [
111
114
  readOnly: definitionArg.readOnly && !pollingToolNames.has(definitionArg.name),
112
115
  route: { kind: 'worker', action: definitionArg.action },
113
116
  })),
117
+ ...deployToolDefinitions.map((definitionArg): IDriverToolDefinition => ({
118
+ name: definitionArg.name, description: definitionArg.description, inputSchema: definitionArg.inputSchema,
119
+ readOnly: definitionArg.readOnly && !pollingToolNames.has(definitionArg.name),
120
+ route: { kind: 'deploy', operation: definitionArg.operation },
121
+ })),
114
122
  ...ticketToolDefinitions.map((definitionArg): IDriverToolDefinition => ({
115
123
  name: definitionArg.name, description: definitionArg.description, inputSchema: definitionArg.inputSchema,
116
124
  readOnly: definitionArg.readOnly, route: { kind: 'ticket', operation: definitionArg.operation },
@@ -2,16 +2,20 @@ import * as plugins from '../plugins.js';
2
2
  import { ticketDoneColumns, type ITicket, type ITicketActivity, type ITicketActor, type ITicketComment, type ITicketPerson, type ITicketQuestion,
3
3
  type TTicketColumn } from '../../ts_interfaces/tickets.js';
4
4
  import type { ITicketHistory } from '../classes.ticketstore.js';
5
- import type { IFleetBoardPumpConfiguration, IFleetUnboundDriver } from '../../ts_interfaces/fleet.js';
5
+ import type { IFleetBoardPumpConfiguration, IFleetRepository, IFleetUnboundDriver } from '../../ts_interfaces/fleet.js';
6
+ import type { IFleetDeployPlan, IFleetDeployStatus, IFleetDeployTargetStatus } from '../../ts_interfaces/deployments.js';
6
7
  import type { IFleetEvent } from '../../ts_interfaces/fleetworkers.js';
7
8
  import type { IControllerFleetWorkerView } from '../../ts_interfaces/index.js';
8
9
  import type { FleetTicketEffects, IFleetTicketEffectDocument } from './classes.ticketeffects.js';
9
10
  import { quoteAgentMessageHeaderText } from '../functions.agentmessage.js';
10
11
  import { unboundDriverLines } from './functions.unbounddrivers.js';
12
+ import { compareFleetVersions, findFleetRepository, fleetRepositorySlug } from './functions.releasefacts.js';
11
13
 
12
14
  /** Who the board pump's ticket comments name. Its changes reach the driver, never the assignee's session. */
13
15
  export const boardPumpActor: ITicketActor = { id: 'agl:board-pump', name: 'AGL board pump', role: 'driver' };
14
16
  export const boardPumpDefaults = { enabled: true, intervalMinutes: 5, landedAfterHours: 24 } as const;
17
+ /** Hours a deploy target may run a version older than its repository's newest release before the pump tells the driver. */
18
+ export const boardPumpDeployAfterHours = 24;
15
19
  /** The hand label that parks an in-progress ticket without a worker on purpose. */
16
20
  export const boardPumpWaitingLabel = 'waiting';
17
21
 
@@ -27,6 +31,16 @@ export interface IBoardPumpHost {
27
31
  publish(eventArg: Omit<IFleetEvent, 'id' | 'occurredAt'>, ownerArg: string): void;
28
32
  /** The Claude Code background jobs that look like drivers and that no worker binds; a comment notice names them. */
29
33
  unboundDrivers(): Promise<{ drivers: IFleetUnboundDriver[]; errors: string[] }>;
34
+ /** What each deploy target runs; absent while deployments are not observed. */
35
+ deployStatus?(): Promise<IFleetDeployStatus>;
36
+ /** The repositories fleet discovery knows, so landed tickets group by repository however their links name it. */
37
+ repositories?(): Promise<IFleetRepository[]>;
38
+ /**
39
+ * Plans the deploy of a target that runs behind a release (AGL-909): a ticket on the target's board project with a
40
+ * deploy plan, which asks the owner; assigned to the direct report whose projects hold that project, else to nobody
41
+ * (the driver deploys). Resolves with the ticket.
42
+ */
43
+ planDeploy?(requestArg: { target: IFleetDeployTargetStatus; version: string; title: string; description: string }): Promise<ITicket>;
30
44
  effects: FleetTicketEffects;
31
45
  }
32
46
 
@@ -34,6 +48,14 @@ export interface IBoardPumpOptions {
34
48
  now?: () => number;
35
49
  }
36
50
 
51
+
52
+ /** A ticket that rests in landed past the release threshold; the pump tells of these per repository. */
53
+ interface IBoardPumpLanded {
54
+ ticket: ITicket;
55
+ entered: { id: string; at: string };
56
+ repos: string[];
57
+ }
58
+
37
59
  /** A stall the pump found: what it would tell, under which durable key. */
38
60
  interface IBoardPumpStall {
39
61
  ticket: ITicket;
@@ -109,7 +131,8 @@ const answerText = (questionArg: ITicketQuestion): string => {
109
131
  /**
110
132
  * Keeps the board moving. Every interval it reads the board and the owner's fleet workers and finds tickets that stalled:
111
133
  * in progress without a live worker, needs input with its questions answered, ready and not picked up, and landed past
112
- * the release threshold. A condition must hold for one full interval before the pump acts. It then tells the driver
134
+ * the release threshold (told of per repository), and deploy targets that run a version older than a release out for
135
+ * more than a day. A condition must hold for one full interval before the pump acts. It then tells the driver
113
136
  * once per ticket state, durably: an attributed ticket comment under an idempotency key that survives a controller
114
137
  * restart, and a `ticket.stalled` fleet event the driver relay carries. An answer goes to the ticket's live worker
115
138
  * instead when there is one. The pump never starts work and never answers a question.
@@ -125,6 +148,8 @@ export class BoardPump {
125
148
  private running?: Promise<void>;
126
149
  /** The configuration changed during a pass, so another pass follows at once with it. */
127
150
  private changed = false;
151
+ /** The stall keys the pass in progress saw, so a sighting that stops holding is forgotten. */
152
+ private seenKeys = new Set<string>();
128
153
  /** The facts of each ticket at the revision they were read at; a ticket gone from the board is forgotten. */
129
154
  private readonly facts = new Map<string, IBoardPumpTicketFacts>();
130
155
 
@@ -165,54 +190,215 @@ export class BoardPump {
165
190
  const intervalMs = configuration.intervalMinutes * 60_000;
166
191
  if (!scope || !configuration.enabled) { this.sightings.clear(); return intervalMs; }
167
192
  const now = this.now();
168
- const tickets = (await this.host.tickets()).filter((ticketArg) => !ticketDoneColumns.includes(ticketArg.columnId));
193
+ const board = await this.host.tickets();
194
+ const tickets = board.filter((ticketArg) => !ticketDoneColumns.includes(ticketArg.columnId));
169
195
  const workers = tickets.length ? await this.host.workers(scope.owner) : [];
170
196
  const listed = new Set(tickets.map((ticketArg) => ticketArg.key));
171
197
  for (const key of this.facts.keys()) if (!listed.has(key)) this.facts.delete(key);
172
- const seen = new Set<string>();
198
+ const seen = this.seenKeys = new Set<string>();
199
+ const consider = async (stallArg: IBoardPumpStall): Promise<void> => {
200
+ seen.add(stallArg.key);
201
+ if (this.settled.has(stallArg.key)) return;
202
+ const firstSeen = this.sightings.get(stallArg.key);
203
+ if (firstSeen === undefined) this.sightings.set(stallArg.key, now);
204
+ if (firstSeen === undefined || now - firstSeen < intervalMs) return;
205
+ if (await this.act(scope.owner, stallArg)) this.settled.add(stallArg.key);
206
+ };
207
+ const landed: IBoardPumpLanded[] = [];
173
208
  for (const ticket of tickets) {
174
209
  this.abort.signal.throwIfAborted();
175
210
  // One ticket's failure leaves the others to this pass and itself to the next.
176
211
  try {
177
- for (const stall of await this.inspect(ticket, workers, configuration.landedAfterHours, now)) {
178
- seen.add(stall.key);
179
- if (this.settled.has(stall.key)) continue;
180
- const firstSeen = this.sightings.get(stall.key);
181
- if (firstSeen === undefined) this.sightings.set(stall.key, now);
182
- if (firstSeen === undefined || now - firstSeen < intervalMs) continue;
183
- if (await this.act(scope.owner, stall)) this.settled.add(stall.key);
184
- }
212
+ const inspected = await this.inspect(ticket, workers, configuration.landedAfterHours, now);
213
+ if (inspected.landed) landed.push(inspected.landed);
214
+ for (const stall of inspected.stalls) await consider(stall);
185
215
  } catch (errorArg) {
186
216
  if (this.abort.signal.aborted) throw errorArg;
187
217
  console.error(`The board pump could not act on ${ticket.key}.`, errorArg);
188
218
  }
189
219
  }
220
+ const repositories = landed.length && this.host.repositories ? await this.host.repositories().catch((errorArg: unknown) => {
221
+ console.error('The board pump could not read the fleet repositories.', errorArg);
222
+ return [];
223
+ }) : [];
224
+ for (const stall of [...this.landedStalls(landed, configuration.landedAfterHours, repositories), ...await this.deployStalls(board, now, intervalMs, scope.owner)]) {
225
+ this.abort.signal.throwIfAborted();
226
+ try { await consider(stall); }
227
+ catch (errorArg) {
228
+ if (this.abort.signal.aborted) throw errorArg;
229
+ console.error(`The board pump could not act on ${stall.ticket.key}.`, errorArg);
230
+ }
231
+ }
190
232
  for (const key of this.sightings.keys()) if (!seen.has(key)) this.sightings.delete(key);
191
233
  for (const key of this.settled) if (!seen.has(key)) this.settled.delete(key);
192
234
  return intervalMs;
193
235
  }
194
236
 
195
- /** The stalls of one ticket: its column's, and a comment no driver or assignee followed while no live worker holds it. */
237
+ /**
238
+ * One notice per repository for the tickets resting in landed past the threshold, on the ticket that landed first: a
239
+ * release of the repository links and releases every landed ticket it contains. A ticket that names no repository
240
+ * keeps a notice of its own. A ticket landing in the group changes its state, so the repository is named again.
241
+ */
242
+ private landedStalls(landedArg: IBoardPumpLanded[], landedAfterHoursArg: number, repositoriesArg: IFleetRepository[]): IBoardPumpStall[] {
243
+ const groups = new Map<string, IBoardPumpLanded[]>();
244
+ // One group per repository however a link names it: its fleet id, `org/name` or a checkout path.
245
+ const named = (repoArg: string) => { const repo = findFleetRepository(repositoriesArg, repoArg); return repo ? fleetRepositorySlug(repo) : repoArg; };
246
+ for (const entry of landedArg) {
247
+ for (const repo of entry.repos.length ? [...new Set(entry.repos.map(named))] : [`ticket:${entry.ticket.key}`]) groups.set(repo, [...groups.get(repo) ?? [], entry]);
248
+ }
249
+ return [...groups.entries()].map(([repo, entries]) => {
250
+ const sorted = [...entries].sort((leftArg, rightArg) => leftArg.entered.at.localeCompare(rightArg.entered.at)
251
+ || leftArg.ticket.key.localeCompare(rightArg.ticket.key, 'en', { numeric: true }));
252
+ const first = sorted[0]!;
253
+ const key = `board-pump:${first.ticket.key}:landed:${plugins.crypto.createHash('sha256')
254
+ .update(JSON.stringify([repo, ...sorted.map((entryArg) => [entryArg.ticket.key, entryArg.entered.id])])).digest('hex').slice(0, 32)}`;
255
+ if (repo.startsWith('ticket:')) {
256
+ return { ticket: first.ticket, column: 'landed' as const, key,
257
+ notice: `${this.header(first.ticket)} landed at ${first.entered.at} and has not been released for ${landedAfterHoursArg} hours. Propose its release: `
258
+ + `fleet_release with the repository it landed in and ticketKey ${first.ticket.key}.` };
259
+ }
260
+ const lines = sorted.map((entryArg) => `- ${entryArg.ticket.key} ${quoted(entryArg.ticket.title)}, landed at ${entryArg.entered.at}`).join('\n');
261
+ return { ticket: first.ticket, column: 'landed' as const, key,
262
+ notice: `${quoted(repo)} has ${sorted.length} ticket${sorted.length === 1 ? '' : 's'} that landed and ha${sorted.length === 1 ? 's' : 've'} not been released for `
263
+ + `${landedAfterHoursArg} hours:\n${lines}\n\nPropose the release of ${quoted(repo)}: fleet_release (repo ${quoted(repo)}, ticketKey ${first.ticket.key}). `
264
+ + 'The release links and releases every landed ticket of the repository it contains.' };
265
+ });
266
+ }
267
+
268
+ /**
269
+ * The deploys the board waits for (AGL-909). A target that runs behind a release out for more than a day, without a
270
+ * deploy plan for it, gets one: a ticket that asks the owner whether to deploy it now, in the next maintenance window
271
+ * or to hold. The owner's answer covers its version only, so a newer release gets a plan of its own; while a plan's
272
+ * question waits, no other is asked. A plan the owner answered is told to the driver when it is due: a go to deploy
273
+ * now that a day has not fulfilled, the window it was queued into once it opens (or that none is planned), and for
274
+ * the AGL controller the moment no session is busy. A version the target was rolled back from is not proposed again,
275
+ * and neither is a target and version any ticket planned already, done ones included: a plan closed before it was
276
+ * fulfilled counts as a hold, whoever closed it.
277
+ */
278
+ private async deployStalls(boardArg: ITicket[], nowArg: number, intervalMsArg: number, ownerArg: string): Promise<IBoardPumpStall[]> {
279
+ if (!this.host.deployStatus) return [];
280
+ let status: IFleetDeployStatus;
281
+ try { status = await this.host.deployStatus(); }
282
+ catch (errorArg) {
283
+ if (this.abort.signal.aborted) throw errorArg;
284
+ console.error('The board pump could not read the deploy status.', errorArg);
285
+ return [];
286
+ }
287
+ const stalls: IBoardPumpStall[] = [];
288
+ for (const target of status.targets) stalls.push(...this.hotfixStalls(target, boardArg));
289
+ for (const target of status.targets) {
290
+ const { running, latest } = target;
291
+ const plan = target.deployPlans[0];
292
+ if (plan) {
293
+ const ticket = boardArg.find((ticketArg) => ticketArg.key === plan.key);
294
+ const stall = ticket ? this.deployPlanStall(target, plan, ticket, nowArg) : undefined;
295
+ if (stall) stalls.push(stall);
296
+ if (plan.go === 'waiting' || !latest || compareFleetVersions(latest.version, plan.version) <= 0) continue;
297
+ }
298
+ if (!running || !latest || !target.notRunning.releases.some((releaseArg) => releaseArg.version === latest.version)) continue;
299
+ // A version the target was rolled back from is not proposed again; a newer release is.
300
+ if (running.rolledBack && running.previousVersion && compareFleetVersions(latest.version, running.previousVersion) <= 0) continue;
301
+ const releasedAt = latest.taggedAt ?? running.since;
302
+ if (Date.parse(releasedAt) + boardPumpDeployAfterHours * 3_600_000 > nowArg) continue;
303
+ if (boardArg.some((ticketArg) => ticketArg.deployPlan?.target === target.target.id && ticketArg.deployPlan.version === latest.version)) continue;
304
+ await this.planDeploy(target, latest.version, releasedAt, nowArg, intervalMsArg, ownerArg);
305
+ }
306
+ return stalls;
307
+ }
308
+
309
+ /** Plans a deploy once its condition held for one interval; the plan's question reaches the owner on the board. */
310
+ private async planDeploy(targetArg: IFleetDeployTargetStatus, versionArg: string, releasedAtArg: string, nowArg: number, intervalMsArg: number,
311
+ ownerArg: string): Promise<void> {
312
+ if (!this.host.planDeploy) return;
313
+ const key = `board-pump:deploy-plan:${targetArg.target.id}:${versionArg}`;
314
+ this.seenKeys.add(key);
315
+ const firstSeen = this.sightings.get(key);
316
+ if (firstSeen === undefined) this.sightings.set(key, nowArg);
317
+ if (firstSeen === undefined || nowArg - firstSeen < intervalMsArg) return;
318
+ const name = targetArg.target.name ?? targetArg.target.id;
319
+ const running = targetArg.running!;
320
+ const tickets = targetArg.notRunning.tickets.slice(0, 20).map((ticketArg) => `- ${ticketArg.key} ${ticketArg.title} (${ticketArg.version})`).join('\n');
321
+ const when = targetArg.deployWhen === 'idle' ? 'It is upgraded when no session is busy.'
322
+ : targetArg.deployWhen === 'window' ? 'Its deploys need a maintenance window.' : 'It may be deployed at any time.';
323
+ const description = `${targetArg.repository ?? targetArg.target.repo} ${versionArg} was released at ${releasedAtArg}, and ${name}`
324
+ + `${targetArg.target.environment ? ` (${targetArg.target.environment})` : ''} still runs ${running.version}, as its probe answered.`
325
+ + `${tickets ? ` It does not run these tickets yet:\n${tickets}\n` : ' '}`
326
+ + `${targetArg.openBugs.length ? `Open bugs on ${running.version}: ${targetArg.openBugs.map((bugArg) => bugArg.key).join(', ')}. ` : ''}`
327
+ + `${targetArg.target.deploys ? `How it deploys: ${targetArg.target.deploys} ` : ''}${when}\n\n`
328
+ + `The question below asks the owner whether to deploy it now, in the next window, or to hold. AGL closes this ticket once ${name} runs ${versionArg} or newer.`;
329
+ try {
330
+ const ticket = await this.host.planDeploy({ target: targetArg, version: versionArg, title: `Deploy ${name} ${versionArg}`, description });
331
+ this.host.publish({ kind: 'ticket.stalled', ticketKey: ticket.key, status: ticket.columnId,
332
+ text: `AGL planned the deploy of ${name} ${versionArg}: ${ticket.key} asks the owner whether to deploy it now, in the next window, or to hold. `
333
+ + `${name} runs ${running.version}; ${versionArg} was released at ${releasedAtArg}.${ticket.assignee ? ` It is assigned to ${ticket.assignee.name}, who deploys it.` : ''}` },
334
+ ownerArg);
335
+ } catch (errorArg) {
336
+ if (this.abort.signal.aborted) throw errorArg;
337
+ console.error(`The board pump could not plan the deploy of ${targetArg.target.id} ${versionArg}.`, errorArg);
338
+ }
339
+ }
340
+
341
+ /** A deploy plan the owner answered, when it is due; nothing while it waits for the owner or is held. */
342
+ private deployPlanStall(targetArg: IFleetDeployTargetStatus, planArg: IFleetDeployPlan, ticketArg: ITicket, nowArg: number): IBoardPumpStall | undefined {
343
+ const name = targetArg.target.name ?? targetArg.target.id;
344
+ const running = targetArg.running?.version ?? 'nothing observed';
345
+ const after = ` After the deploy, run deploy_probe (targetId ${targetArg.target.id}); AGL closes ${planArg.key} once ${name} runs ${planArg.version}.`;
346
+ const stall = (stateArg: string, noticeArg: string): IBoardPumpStall => ({ ticket: ticketArg, column: ticketArg.columnId,
347
+ key: `board-pump:${planArg.key}:deploy:${plugins.crypto.createHash('sha256').update(JSON.stringify([planArg.questionId, stateArg])).digest('hex').slice(0, 32)}`,
348
+ notice: `${this.header(ticketArg)}: ${noticeArg}` });
349
+ if (planArg.go === 'now' && planArg.answeredAt && Date.parse(planArg.answeredAt) + boardPumpDeployAfterHours * 3_600_000 <= nowArg) {
350
+ return stall(`now:${planArg.answeredAt}`, `the owner said to deploy ${name} ${planArg.version} now at ${planArg.answeredAt}, more than `
351
+ + `${boardPumpDeployAfterHours} hours ago, and it still runs ${running}. Deploy it, or tell the owner what stops it.${after}`);
352
+ }
353
+ if (planArg.go === 'window' && planArg.window?.state === 'active') {
354
+ return stall(`window:${planArg.window.key}`, `the maintenance window ${planArg.window.key} for ${name} is open until ${planArg.window.to}, and the owner `
355
+ + `queued the deploy of ${planArg.version} into the next window. Deploy it now, inside the window.${after}`);
356
+ }
357
+ if (planArg.go === 'window' && !planArg.window) {
358
+ return stall('window:none', `the owner queued the deploy of ${name} ${planArg.version} into the next maintenance window, and none the owner gave `
359
+ + `is planned for ${targetArg.target.id}. Propose one: a ticket with a maintenanceWindow (from, to, targets [${targetArg.target.id}]), which `
360
+ + 'asks the owner and counts once approved.');
361
+ }
362
+ if (planArg.go === 'idle' && targetArg.busySessions === 0) {
363
+ return stall('idle', `no session is busy, and the owner said to upgrade ${name} to ${planArg.version} when none is. Run agl upgrade now; `
364
+ + `it keeps its own owner gate.${after}`);
365
+ }
366
+ return undefined;
367
+ }
368
+
369
+ /**
370
+ * The stalls of one ticket: its column's, and a comment no driver or assignee followed while no live worker holds it.
371
+ * A ticket resting in landed is told of with its repository's others.
372
+ */
196
373
  private async inspect(ticketArg: ITicket, workersArg: IControllerFleetWorkerView[], landedAfterHoursArg: number,
197
- nowArg: number): Promise<IBoardPumpStall[]> {
374
+ nowArg: number): Promise<{ stalls: IBoardPumpStall[]; landed?: IBoardPumpLanded }> {
198
375
  const column = ticketArg.columnId;
199
376
  const assigned = ticketArg.assignee?.sessionId;
200
377
  const bound = workersArg.filter((viewArg) => viewArg.worker.ticketKey === ticketArg.key || assigned !== undefined && sessionOf(viewArg) === assigned)
201
378
  .sort((leftArg, rightArg) => leftArg.worker.updatedAt.localeCompare(rightArg.worker.updatedAt));
202
379
  const live = bound.filter(isLive);
203
- // A deploy plan or a maintenance window a later release planned waits for the owner's go or for its time, not for a worker.
380
+ // A deploy plan or a maintenance window waits for the owner's go or for its time, not for a worker: the deploy checks tell of those.
204
381
  const watched = watchedColumns.has(column) && !ticketArg.deployPlan && !ticketArg.maintenanceWindow
205
382
  && !(column === 'in_progress' && (ticketArg.labels.includes(boardPumpWaitingLabel) || live.length > 0));
206
383
  const comments = !ticketDoneColumns.includes(column) && !live.length;
207
- if (!watched && !comments) return [];
384
+ if (!watched && !comments) return { stalls: [] };
208
385
  const facts = await this.factsOf(ticketArg);
209
- if (facts.ticket.columnId !== column) return [];
386
+ if (facts.ticket.columnId !== column) return { stalls: [] };
210
387
  const stalls: IBoardPumpStall[] = [];
211
- const stall = watched ? this.columnStall(facts, bound, live, landedAfterHoursArg, nowArg) : undefined;
212
- if (stall) stalls.push(stall);
388
+ let landed: IBoardPumpLanded | undefined;
389
+ if (watched && column === 'landed') {
390
+ const { ticket, entered } = facts;
391
+ if (Date.parse(entered.at) + landedAfterHoursArg * 3_600_000 <= nowArg) {
392
+ landed = { ticket, entered, repos: [...new Set(ticket.links.flatMap((linkArg) => (
393
+ linkArg.kind === 'branch' || linkArg.kind === 'commit' ? [linkArg.repo] : [])))] };
394
+ }
395
+ } else {
396
+ const stall = watched ? this.columnStall(facts, bound, live) : undefined;
397
+ if (stall) stalls.push(stall);
398
+ }
213
399
  const comment = comments ? this.commentStall(facts, bound) : undefined;
214
400
  if (comment) stalls.push(comment);
215
- return stalls;
401
+ return { stalls, ...(landed ? { landed } : {}) };
216
402
  }
217
403
 
218
404
  /** The ticket's facts, read again only when its revision is not the one they were read at. */
@@ -247,8 +433,8 @@ export class BoardPump {
247
433
  + 'Claude Code background jobs that look like drivers and that no fleet worker binds:' };
248
434
  }
249
435
 
250
- private columnStall({ ticket, entered, questions }: IBoardPumpTicketFacts, bound: IControllerFleetWorkerView[], live: IControllerFleetWorkerView[],
251
- landedAfterHoursArg: number, nowArg: number): IBoardPumpStall | undefined {
436
+ private columnStall({ ticket, entered, questions }: IBoardPumpTicketFacts, bound: IControllerFleetWorkerView[],
437
+ live: IControllerFleetWorkerView[]): IBoardPumpStall | undefined {
252
438
  const column = ticket.columnId;
253
439
  const assigned = ticket.assignee?.sessionId;
254
440
  const header = this.header(ticket);
@@ -284,12 +470,33 @@ export class BoardPump {
284
470
  return { ticket, column, key: key([]),
285
471
  notice: `${header} has been in ready since ${entered.at} and nobody picked it up. Start a worker for it or move it.` };
286
472
  }
287
- if (Date.parse(entered.at) + landedAfterHoursArg * 3_600_000 > nowArg) return undefined;
288
- const repos = [...new Set(ticket.links.flatMap((linkArg) => linkArg.kind === 'branch' ? [linkArg.repo] : []))];
289
- return { ticket, column, key: key([]),
290
- notice: `${header} landed at ${entered.at} and has not been released for ${landedAfterHoursArg} hours. Propose its release: `
291
- + (repos.length ? repos.map((repoArg) => `fleet_release (repo ${quoted(repoArg)}, ticketKey ${ticket.key})`).join(', ')
292
- : `fleet_release with the repository it landed in and ticketKey ${ticket.key}`) + '.' };
473
+ return undefined;
474
+ }
475
+
476
+ /**
477
+ * A hotfix proposal (AGL-913): an urgent bug found in the version a target runs, whose fix landed but does not run
478
+ * there, and that no release plan covers yet. A hotfix is an urgent release plan off main: releasing ships main as it is.
479
+ */
480
+ private hotfixStalls(targetArg: IFleetDeployTargetStatus, boardArg: ITicket[]): IBoardPumpStall[] {
481
+ const { running } = targetArg;
482
+ if (!running) return [];
483
+ const stalls: IBoardPumpStall[] = [];
484
+ for (const bug of targetArg.openBugs) {
485
+ if (bug.priority !== 'urgent' || !bug.fixLandedSha) continue;
486
+ const ticket = boardArg.find((ticketArg) => ticketArg.key === bug.key);
487
+ if (!ticket || ticket.releasePlan) continue;
488
+ const repo = targetArg.repository ?? targetArg.target.repo;
489
+ const name = targetArg.target.name ?? targetArg.target.id;
490
+ stalls.push({ ticket, column: ticket.columnId,
491
+ key: `board-pump:${bug.key}:hotfix:${plugins.crypto.createHash('sha256')
492
+ .update(JSON.stringify([targetArg.target.id, running.version, bug.fixLandedSha])).digest('hex').slice(0, 32)}`,
493
+ notice: `${this.header(ticket)} is urgent and was found in ${repo} ${bug.foundIn}, which ${quoted(name)} (deploy target `
494
+ + `${targetArg.target.id}) runs. Its fix landed as ${bug.fixLandedSha.slice(0, 12)}`
495
+ + (bug.fixedIn ? ` and is released in ${bug.fixedIn}, which ${quoted(name)} does not run.` : ' and is in no release yet.')
496
+ + ` Propose a hotfix: plan it with ticket_update (releasePlan { repo ${quoted(repo)} }, no version: gitzone picks it from what landed) on this urgent ticket,`
497
+ + ' then release it with fleet_release and deploy it. A hotfix releases main as it is, with everything else that landed.' });
498
+ }
499
+ return stalls;
293
500
  }
294
501
 
295
502
  /** Acts on a stall once; resolves true when its notice is applied on the ticket. */
@@ -1,10 +1,10 @@
1
1
  import * as plugins from '../plugins.js';
2
2
  import { resolveControllerTerminalAgentTranscript } from '../functions.terminalagents.js';
3
3
  import { fleetWorkerPath, resolveClaudeWorkerExecutable } from '../functions.workerprocessproof.js';
4
- import type { IFleetWorker, IFleetWorkerProfile, IFleetWorkerReport, IFleetWorkerAbsenceProof, IFleetWorkerSessionProof, IFleetWorkerRebindProof } from '../../ts_interfaces/fleetworkers.js';
4
+ import type { IFleetWorker, IFleetWorkerProfile, IFleetWorkerReport, IFleetRelaunchBlocker, IFleetWorkerAbsenceProof, IFleetWorkerSessionProof, IFleetWorkerRebindProof } from '../../ts_interfaces/fleetworkers.js';
5
5
  import { controllerSessionFeedExcerpt, type IControllerMessageBundle } from '../../ts_interfaces/index.js';
6
6
  import { claudePage, claudeTranscript } from '../classes.claudeprojection.js';
7
- import { FleetDispatchError, boundedFleetReport, fleetMessageDigest, fleetReportMarker, type IFleetWorkerBackend, type IFleetNativeEvent, type IFleetNativeAgent, type IFleetNativeSession, type IFleetNativePage } from './interfaces.workers.js';
7
+ import { FleetDispatchError, FleetNativeTurnError, boundedFleetReport, fleetMessageDigest, fleetReportMarker, type IFleetWorkerBackend, type IFleetNativeEvent, type IFleetNativeAgent, type IFleetNativeSession, type IFleetNativePage, type IFleetNativeSendTurn, type IFleetNativeSendReceipt } from './interfaces.workers.js';
8
8
  import { runFleetWorkerCommand, type IFleetWorkerCommand, type TFleetWorkerRunner } from './classes.workercommand.js';
9
9
  import { sanitizeFailureText } from '../functions.failuredescription.js';
10
10
  import type { FleetWorkerLaunches } from './classes.workerlaunches.js';
@@ -295,7 +295,7 @@ export class FleetClaudeWorkers implements IFleetWorkerBackend {
295
295
  }
296
296
  if (!trusted) throw new Error(`Claude workspace not trusted. ${instruction}`);
297
297
  }
298
- private async supported(worker: IFleetWorker, profile: IFleetWorkerProfile, starting = false): Promise<void> {
298
+ private async supported(worker: Pick<IFleetWorker, 'cwd'>, profile: IFleetWorkerProfile, starting = false): Promise<void> {
299
299
  await this.supportedExecutable(profile, worker.cwd);
300
300
  if (starting) await this.trustedWorkspace(profile, worker.cwd);
301
301
  }
@@ -553,6 +553,31 @@ export class FleetClaudeWorkers implements IFleetWorkerBackend {
553
553
  throw new FleetDispatchError(error instanceof Error ? error.message : 'Claude start outcome is unknown.', true, { cause: error });
554
554
  }
555
555
  }
556
+ /**
557
+ * Why a relaunch of the session `nativeId` in `worker`'s directory would be refused now, read-only, or what the
558
+ * relaunch continues from: the profile home's fresh inventory, the session in it and its saved conversation. The
559
+ * relaunch and its preflight both run it, so they refuse alike.
560
+ */
561
+ private async relaunchState(worker: Pick<IFleetWorker, 'cwd'>, profile: IFleetWorkerProfile, nativeId: string): Promise<{ blocker: IFleetRelaunchBlocker }
562
+ | { before: TClaudeAgent[]; original: TClaudeAgent; baseline: { records: Record<string, unknown>[]; end: number; path?: string } }> {
563
+ if (!plugins.z.string().uuid().safeParse(nativeId).success) return { blocker: { code: 'invalidId', message: 'A Claude session is relaunched by its full session id.' } };
564
+ try { await this.supported(worker, profile, true); }
565
+ catch (error) { return { blocker: { code: 'unsupported', message: error instanceof Error ? error.message : 'Claude cannot start in this directory.' } }; }
566
+ const before = await this.agents(worker, profile), found = before.find((entry) => entry.sessionId === nativeId);
567
+ if (!found) return { blocker: { code: 'notInInventory', message: `Claude session ${nativeId} is not in the inventory of this profile's Claude home; AGL cannot prove it is not running.` } };
568
+ if (live(found) || found.state === 'working') {
569
+ return { blocker: { code: live(found) ? 'running' : 'working', ...(found.pid ? { pid: found.pid } : {}),
570
+ message: `Claude session ${nativeId} is still running outside the fleet${found.pid ? ` (pid ${found.pid})` : ''}. Its owner stops it first${found.id ? ` (\`claude stop ${found.id}\`, or exits it)` : ' (exits it)'}; the adopt never stops a session it does not manage.` } };
571
+ }
572
+ if (found.kind === 'background' && !found.id) return { blocker: { code: 'noAgentId', message: 'Claude background session has no agent id.' } };
573
+ const baseline = await this.transcript({ ...worker, nativeId }, profile);
574
+ if (!baseline.path || !baseline.records.some((entry) => typeof entry.uuid === 'string')) return { blocker: { code: 'noTranscript', message: 'Claude session has no readable saved conversation.' } };
575
+ return { before, original: found, baseline };
576
+ }
577
+ public async relaunchBlocker(cwd: string, profile: IFleetWorkerProfile, nativeId: string): Promise<IFleetRelaunchBlocker | undefined> {
578
+ const state = await this.relaunchState({ cwd }, profile, nativeId);
579
+ return 'blocker' in state ? state.blocker : undefined;
580
+ }
556
581
  /**
557
582
  * Resumes the settled session `nativeId` as `worker`, under the worker's own options and caller overlay. Claude
558
583
  * continues a background job's session as a copy under a new id, its saved options staying with the original, and
@@ -562,18 +587,10 @@ export class FleetClaudeWorkers implements IFleetWorkerBackend {
562
587
  public async relaunch(worker: IFleetWorker, profile: IFleetWorkerProfile, nativeId: string, prompt: string, bind: (id: string) => Promise<void>): Promise<void> {
563
588
  let before: TClaudeAgent[], original: TClaudeAgent, baseline: { records: Record<string, unknown>[]; end: number; path?: string }, overlay: string | undefined;
564
589
  try {
565
- if (!plugins.z.string().uuid().safeParse(nativeId).success) throw new Error('A Claude session is relaunched by its full session id.');
566
590
  if (Buffer.byteLength(prompt) > 96 * 1024) throw new Error('Claude relaunch prompt plus preamble exceeds 96 KiB.');
567
- await this.supported(worker, profile, true); before = await this.agents(worker, profile);
568
- const found = before.find((entry) => entry.sessionId === nativeId);
569
- if (!found) throw new Error(`Claude session ${nativeId} is not in the inventory of this profile's Claude home; AGL cannot prove it is not running.`);
570
- if (live(found) || found.state === 'working') {
571
- throw new Error(`Claude session ${nativeId} is still running outside the fleet${found.pid ? ` (pid ${found.pid})` : ''}. Its owner stops it first${found.id ? ` (\`claude stop ${found.id}\`, or exits it)` : ' (exits it)'}; the adopt never stops a session it does not manage.`);
572
- }
573
- if (found.kind === 'background' && !found.id) throw new Error('Claude background session has no agent id.');
574
- original = found;
575
- baseline = await this.transcript({ ...worker, nativeId }, profile);
576
- if (!baseline.path || !baseline.records.some((entry) => typeof entry.uuid === 'string')) throw new Error('Claude session has no readable saved conversation.');
591
+ const state = await this.relaunchState(worker, profile, nativeId);
592
+ if ('blocker' in state) throw new Error(state.blocker.message);
593
+ ({ before, original, baseline } = state);
577
594
  overlay = await this.callers?.prepareClaude(worker);
578
595
  }
579
596
  catch (error) { throw new FleetDispatchError(error instanceof Error ? error.message : 'Claude relaunch preflight failed.', false, { cause: error }); }
@@ -702,7 +719,10 @@ export class FleetClaudeWorkers implements IFleetWorkerBackend {
702
719
  * stopped) and with a readable conversation, is woken; anything else, and a message Claude Code would read as one of
703
720
  * its options, is refused before dispatch. Claude Code does not report when the woken turn ends, so `settled` never runs.
704
721
  */
705
- public async nativeSend(session: IFleetNativeSession, text: string, _settled: () => void): Promise<void> {
722
+ public async nativeSend(session: IFleetNativeSession, text: string, _settled: () => void, turn?: IFleetNativeSendTurn): Promise<IFleetNativeSendReceipt> {
723
+ if (turn?.expectedTurnId !== undefined || turn?.agentMessage) {
724
+ throw new FleetNativeTurnError("delivery_unsupported", "Claude Code background jobs do not support guarded native turn delivery.");
725
+ }
706
726
  const profile = { home: session.home };
707
727
  let original: TClaudeAgent;
708
728
  try {
@@ -724,6 +744,7 @@ export class FleetClaudeWorkers implements IFleetWorkerBackend {
724
744
  catch (error) {
725
745
  throw new FleetDispatchError(`Claude Code acknowledged the wake of background job ${original.id}, but its state is not confirmed: ${error instanceof Error ? error.message : 'unknown failure.'} Inspect it before sending again.`, true, { cause: error });
726
746
  }
747
+ return { steered: false };
727
748
  }
728
749
  public async send(messages: Array<{ worker: IFleetWorker; profile: IFleetWorkerProfile; text: string }>): Promise<void> {
729
750
  const groups = new Map<string, Array<{ worker: IFleetWorker; profile: IFleetWorkerProfile; text: string; to: string; mode: string; offset: number }>>();
@@ -6,7 +6,7 @@ import type { IFleetWorker, IFleetWorkerProfile, IFleetWorkerReport } from '../.
6
6
  import { controllerSessionFeedExcerpt } from '../../ts_interfaces/sessionfeed.js';
7
7
  import type { IControllerMessageBundle, IControllerPermission, IControllerQuestion, TControllerPermissionReply } from '../../ts_interfaces/index.js';
8
8
  import type { FleetWorkerLaunches, IFleetCodexCallerRuntime } from './classes.workerlaunches.js';
9
- import { FleetDispatchError, fleetReportMarker, boundedFleetReport, type IFleetWorkerBackend, type IFleetNativeEvent, type IFleetNativeThread, type IFleetNativeSession, type IFleetNativePage } from './interfaces.workers.js';
9
+ import { FleetDispatchError, FleetNativeTurnError, fleetReportMarker, boundedFleetReport, type IFleetWorkerBackend, type IFleetNativeEvent, type IFleetNativeThread, type IFleetNativeSession, type IFleetNativePage, type IFleetNativeSendTurn, type IFleetNativeSendReceipt } from './interfaces.workers.js';
10
10
 
11
11
  interface ICodexObservation { turns: Set<string>; items: Map<string, string>; status?: IFleetWorkerReport['status']; excerpt?: string }
12
12
  export interface IFleetCodexConnection { supervisor: CodexSupervisor; adapter: CodexClientAdapter }
@@ -166,23 +166,34 @@ export class FleetCodexWorkers implements IFleetWorkerBackend {
166
166
  /**
167
167
  * Steers the thread's running turn, AGL's own or another client's, or starts a turn; `settled` runs once the turn
168
168
  * that took the text ended. A steer of another client's turn proves that only when the turn ended before Codex took
169
- * the input; otherwise `settled` never runs.
169
+ * the input; otherwise `settled` never runs. `turn` refuses a running turn the caller did not name before anything is
170
+ * sent; the steer itself proves the turn again on the server.
170
171
  */
171
172
  private async deliver(adapter: CodexClientAdapter, id: string, text: string, model: Parameters<CodexClientAdapter['startTurn']>[3],
172
- prepare: () => Promise<void>, settled: () => void = () => {}): Promise<void> {
173
+ prepare: () => Promise<void>, settled: () => void = () => {}, turn: IFleetNativeSendTurn = {}): Promise<IFleetNativeSendReceipt> {
173
174
  const turns = await this.turns(adapter, id);
174
175
  const running = turns[0]?.status === 'inProgress' ? turns[0] : undefined;
176
+ if (turn.expectedTurnId !== undefined && !running) throw new FleetNativeTurnError('turn_ended', 'The Codex turn this message was to steer has ended; nothing was sent.');
175
177
  await prepare();
176
178
  const clientId = plugins.crypto.randomUUID(); let arm: () => void;
177
179
  if (running) {
178
180
  const turnId = codexString(running.id), activity = await adapter.refreshActivity(id, this.signal);
181
+ if (turn.expectedTurnId !== undefined && turn.expectedTurnId !== turnId) {
182
+ throw new FleetNativeTurnError('concurrent_change', 'Another Codex turn than the expected one runs; read the session again.');
183
+ }
184
+ if (turn.agentMessage && turn.expectedTurnId === undefined && activity.writer !== 'agl') {
185
+ throw new FleetNativeTurnError('delivery_unsupported', 'Steering a turn another Codex client runs requires expectedTurnId, the turn the last read reported.');
186
+ }
179
187
  arm = await this.dispatch(() => activity.writer === 'agl'
180
188
  ? adapter.steer(id, text, clientId, () => {}, () => {}, turnId, this.signal, () => settled())
181
189
  : adapter.steerObservedTurn(id, text, clientId, turnId, () => {}, (_outcome, _turnId, terminal) => { if (terminal) settled(); }, this.signal));
182
- } else {
183
- arm = await this.dispatch(() => adapter.startTurn(id, text, clientId, model, async () => {}, settled, this.signal));
190
+ arm();
191
+ return { steered: true, turnId };
184
192
  }
193
+ arm = await this.dispatch(() => adapter.startTurn(id, text, clientId, model, async () => {}, settled, this.signal));
185
194
  arm();
195
+ const started = adapter.activitySummary(id).turnId;
196
+ return { steered: false, ...(started === undefined ? {} : { turnId: started }) };
186
197
  }
187
198
  public async stop(worker: IFleetWorker, _profile: IFleetWorkerProfile): Promise<void> {
188
199
  const adapter = await this.scoped(worker), turns = await this.turns(adapter, worker.nativeId!);
@@ -211,9 +222,15 @@ export class FleetCodexWorkers implements IFleetWorkerBackend {
211
222
  return { bundles: page.bundles, earlier: page.nextCursor !== undefined || page.truncated === true, ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }) };
212
223
  }
213
224
  /** Sends to a thread outside the fleet through the shared server that owns it; the thread keeps its own model. */
214
- public async nativeSend(session: IFleetNativeSession, text: string, settled: () => void): Promise<void> {
225
+ public async nativeSend(session: IFleetNativeSession, text: string, settled: () => void, turn?: IFleetNativeSendTurn): Promise<IFleetNativeSendReceipt> {
226
+ const adapter = await this.scoped(session);
227
+ return await this.deliver(adapter, session.nativeId, text, undefined, async () => {}, settled, turn);
228
+ }
229
+ public async nativeTurn(session: IFleetNativeSession): Promise<string | undefined> {
215
230
  const adapter = await this.scoped(session);
216
- await this.deliver(adapter, session.nativeId, text, undefined, async () => {}, settled);
231
+ const result = await adapter.request('thread/turns/list', { threadId: session.nativeId, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' }, this.signal);
232
+ const latest = codexArray(result.data, 1).map(codexRecord)[0];
233
+ return latest?.status === 'inProgress' ? codexString(latest.id) : undefined;
217
234
  }
218
235
  /** The requests of turns this connection runs in the thread that wait for an answer. */
219
236
  public async nativeAttention(session: IFleetNativeSession): Promise<{ permissions: IControllerPermission[]; questions: IControllerQuestion[] }> {