@phren/cli 0.3.10 → 0.3.12

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 (184) hide show
  1. package/dist/bridge/agent-hook-stores.d.ts +3 -0
  2. package/dist/bridge/agent-hook-stores.js +5 -0
  3. package/dist/bridge/agent-hooks.d.ts +159 -5
  4. package/dist/bridge/agent-hooks.js +663 -49
  5. package/dist/bridge/approval-summary.d.ts +16 -0
  6. package/dist/bridge/approval-summary.js +133 -0
  7. package/dist/bridge/authority-command.d.ts +20 -0
  8. package/dist/bridge/authority-command.js +120 -0
  9. package/dist/bridge/authority.d.ts +223 -0
  10. package/dist/bridge/authority.js +231 -0
  11. package/dist/bridge/claude-account-setup.d.ts +14 -0
  12. package/dist/bridge/claude-account-setup.js +69 -0
  13. package/dist/bridge/claude-accounts.d.ts +49 -0
  14. package/dist/bridge/claude-accounts.js +195 -0
  15. package/dist/bridge/code-routes.js +2 -2
  16. package/dist/bridge/codex-app-server.d.ts +144 -0
  17. package/dist/bridge/codex-app-server.js +319 -0
  18. package/dist/bridge/codex-auth-refresh.d.ts +33 -0
  19. package/dist/bridge/codex-auth-refresh.js +71 -0
  20. package/dist/bridge/codex-question-reply.d.ts +16 -0
  21. package/dist/bridge/codex-question-reply.js +57 -0
  22. package/dist/bridge/codex-review-mode.d.ts +10 -0
  23. package/dist/bridge/codex-review-mode.js +74 -0
  24. package/dist/bridge/codex-servers.d.ts +217 -0
  25. package/dist/bridge/codex-servers.js +636 -0
  26. package/dist/bridge/command.js +94 -4
  27. package/dist/bridge/computer-identity.d.ts +75 -0
  28. package/dist/bridge/computer-identity.js +166 -0
  29. package/dist/bridge/conductor-group.d.ts +91 -8
  30. package/dist/bridge/conductor-group.js +105 -9
  31. package/dist/bridge/conductor-role.d.ts +94 -0
  32. package/dist/bridge/conductor-role.js +176 -0
  33. package/dist/bridge/conductor-sets.d.ts +20 -0
  34. package/dist/bridge/conductor-sets.js +59 -0
  35. package/dist/bridge/dispatch-command.d.ts +3 -0
  36. package/dist/bridge/dispatch-command.js +75 -11
  37. package/dist/bridge/dispatch-returns.d.ts +123 -19
  38. package/dist/bridge/dispatch-returns.js +357 -50
  39. package/dist/bridge/dispatch.d.ts +103 -2
  40. package/dist/bridge/dispatch.js +272 -40
  41. package/dist/bridge/fanout-messages.js +2 -2
  42. package/dist/bridge/fanouts.d.ts +7 -1
  43. package/dist/bridge/fanouts.js +40 -5
  44. package/dist/bridge/folder-trust.d.ts +56 -0
  45. package/dist/bridge/folder-trust.js +195 -0
  46. package/dist/bridge/grants.d.ts +22 -1
  47. package/dist/bridge/grants.js +57 -9
  48. package/dist/bridge/hand-off.d.ts +21 -9
  49. package/dist/bridge/hand-off.js +58 -45
  50. package/dist/bridge/harness-status.d.ts +11 -0
  51. package/dist/bridge/harness-status.js +32 -0
  52. package/dist/bridge/harnesses.d.ts +39 -0
  53. package/dist/bridge/harnesses.js +65 -0
  54. package/dist/bridge/health.d.ts +2 -0
  55. package/dist/bridge/health.js +1 -1
  56. package/dist/bridge/herdr.d.ts +11 -2
  57. package/dist/bridge/herdr.js +98 -23
  58. package/dist/bridge/hook-fast.d.ts +4 -0
  59. package/dist/bridge/hook-fast.js +68 -0
  60. package/dist/bridge/install.d.ts +16 -1
  61. package/dist/bridge/install.js +88 -21
  62. package/dist/bridge/launch-brief.d.ts +96 -0
  63. package/dist/bridge/launch-brief.js +164 -0
  64. package/dist/bridge/model-switch.d.ts +3 -0
  65. package/dist/bridge/model-switch.js +17 -1
  66. package/dist/bridge/models.d.ts +8 -4
  67. package/dist/bridge/models.js +24 -8
  68. package/dist/bridge/mux-wire.d.ts +9 -0
  69. package/dist/bridge/mux-wire.js +19 -0
  70. package/dist/bridge/opencode-pane-server.d.ts +113 -0
  71. package/dist/bridge/opencode-pane-server.js +332 -0
  72. package/dist/bridge/opencode-panes.d.ts +111 -0
  73. package/dist/bridge/opencode-panes.js +295 -0
  74. package/dist/bridge/pane-accounts.d.ts +8 -0
  75. package/dist/bridge/pane-accounts.js +46 -0
  76. package/dist/bridge/prompt-startup.d.ts +5 -0
  77. package/dist/bridge/prompt-startup.js +24 -0
  78. package/dist/bridge/protocol.d.ts +5 -0
  79. package/dist/bridge/protocol.js +4 -0
  80. package/dist/bridge/push.d.ts +5 -4
  81. package/dist/bridge/push.js +6 -4
  82. package/dist/bridge/questions.d.ts +37 -2
  83. package/dist/bridge/questions.js +158 -15
  84. package/dist/bridge/resources.d.ts +125 -0
  85. package/dist/bridge/resources.js +314 -0
  86. package/dist/bridge/schedule-format.d.ts +2 -0
  87. package/dist/bridge/schedule-format.js +3 -0
  88. package/dist/bridge/schedule-launch.d.ts +2 -1
  89. package/dist/bridge/schedule-launch.js +23 -53
  90. package/dist/bridge/schedule-watch.d.ts +10 -1
  91. package/dist/bridge/schedule-watch.js +54 -2
  92. package/dist/bridge/server-launch.d.ts +22 -5
  93. package/dist/bridge/server-launch.js +225 -29
  94. package/dist/bridge/server-overview.d.ts +8 -2
  95. package/dist/bridge/server-overview.js +26 -5
  96. package/dist/bridge/server-pane-routes.d.ts +2 -0
  97. package/dist/bridge/server-pane-routes.js +145 -15
  98. package/dist/bridge/server-routes.d.ts +11 -1
  99. package/dist/bridge/server-routes.js +195 -36
  100. package/dist/bridge/server-stream.d.ts +2 -0
  101. package/dist/bridge/server-stream.js +22 -8
  102. package/dist/bridge/server.d.ts +6 -1
  103. package/dist/bridge/server.js +47 -12
  104. package/dist/bridge/session-activity.d.ts +81 -0
  105. package/dist/bridge/session-activity.js +117 -0
  106. package/dist/bridge/session-rename.d.ts +48 -0
  107. package/dist/bridge/session-rename.js +190 -0
  108. package/dist/bridge/session-servers.js +2 -2
  109. package/dist/bridge/settings-switch.d.ts +60 -0
  110. package/dist/bridge/settings-switch.js +287 -0
  111. package/dist/bridge/speech-voice.d.ts +55 -0
  112. package/dist/bridge/speech-voice.js +132 -0
  113. package/dist/bridge/speech.d.ts +70 -11
  114. package/dist/bridge/speech.js +169 -41
  115. package/dist/bridge/terminal-herdr.js +9 -3
  116. package/dist/bridge/terminal-tmux.d.ts +3 -3
  117. package/dist/bridge/terminal-tmux.js +24 -9
  118. package/dist/bridge/terminal.d.ts +27 -4
  119. package/dist/bridge/terminal.js +8 -1
  120. package/dist/bridge/transcript-claude.js +62 -12
  121. package/dist/bridge/transcript-codex.d.ts +0 -2
  122. package/dist/bridge/transcript-codex.js +29 -4
  123. package/dist/bridge/transcript-preview.d.ts +1 -0
  124. package/dist/bridge/transcript-preview.js +24 -4
  125. package/dist/bridge/transcripts.d.ts +15 -2
  126. package/dist/bridge/transcripts.js +47 -16
  127. package/dist/bridge/turn-records.d.ts +85 -0
  128. package/dist/bridge/turn-records.js +143 -0
  129. package/dist/bridge/uploads.d.ts +3 -0
  130. package/dist/bridge/uploads.js +14 -0
  131. package/dist/bridge/usage.d.ts +73 -28
  132. package/dist/bridge/usage.js +313 -340
  133. package/dist/bridge-hook.mjs +24624 -18450
  134. package/dist/cli/claude-unmanaged.d.ts +12 -0
  135. package/dist/cli/claude-unmanaged.js +105 -0
  136. package/dist/cli/schedules.js +2 -1
  137. package/dist/cli/session-start.js +10 -1
  138. package/dist/cli/session-stop.js +9 -1
  139. package/dist/cli-registry.d.ts +2 -0
  140. package/dist/cli-registry.js +37 -5
  141. package/dist/computers/command.d.ts +6 -0
  142. package/dist/computers/command.js +152 -0
  143. package/dist/computers/mcp.d.ts +1 -0
  144. package/dist/computers/mcp.js +97 -0
  145. package/dist/computers/read.d.ts +85 -0
  146. package/dist/computers/read.js +177 -0
  147. package/dist/data/task-receipts.d.ts +19 -0
  148. package/dist/data/task-receipts.js +68 -0
  149. package/dist/data/tasks.js +4 -1
  150. package/dist/entrypoint.js +10 -0
  151. package/dist/fanout/adapters/claude.js +15 -2
  152. package/dist/fanout/adapters/types.d.ts +6 -0
  153. package/dist/fanout/launcher.d.ts +5 -1
  154. package/dist/fanout/launcher.js +34 -3
  155. package/dist/fanout/picker.js +3 -2
  156. package/dist/fanout/usage.js +1 -1
  157. package/dist/generated/memory-ui-graph.browser.js +63 -63
  158. package/dist/graph-core/model.js +24 -3
  159. package/dist/graph-core/types.d.ts +4 -1
  160. package/dist/graph-core/types.js +1 -0
  161. package/dist/init/init-preset.js +7 -3
  162. package/dist/init/init-uninstall.js +2 -11
  163. package/dist/init/teardown.d.ts +3 -0
  164. package/dist/init/teardown.js +47 -0
  165. package/dist/link/context.js +21 -9
  166. package/dist/mcp/plugin-mode.js +1 -1
  167. package/dist/memory-ui-graph.runtime.js +63 -63
  168. package/dist/modules/code-package.d.ts +1 -0
  169. package/dist/modules/code-package.js +36 -7
  170. package/dist/modules/registry.js +14 -13
  171. package/dist/profile-store.d.ts +6 -0
  172. package/dist/profile-store.js +25 -1
  173. package/dist/shell/graph/glyphs.js +4 -0
  174. package/dist/shell/graph/graph-view.js +2 -0
  175. package/dist/status.js +7 -1
  176. package/dist/sync/task-claim.js +3 -2
  177. package/dist/task/lifecycle.js +25 -4
  178. package/dist/test-global-setup.js +5 -0
  179. package/dist/tools/dispatch.js +35 -2
  180. package/dist/tools/tasks.js +10 -1
  181. package/package.json +1 -1
  182. package/plugins/opencode/phren-transcript.js +87 -4
  183. package/starter/global/skills/conductor/SKILL.md +17 -2
  184. package/starter/global/skills/fanout/SKILL.md +3 -0
@@ -1,6 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import { type DispatchHost } from "./dispatch-hosts.js";
3
3
  import { type Json, type Provider, type Target } from "./protocol.js";
4
+ import { type BriefArrival } from "./launch-brief.js";
4
5
  export declare const projectName: z.ZodString;
5
6
  export declare const dispatchSchema: z.ZodObject<{
6
7
  computer: z.ZodUnion<readonly [z.ZodLiteral<"anywhere">, z.ZodString]>;
@@ -11,6 +12,28 @@ export declare const dispatchSchema: z.ZodObject<{
11
12
  opencode: "opencode";
12
13
  }>;
13
14
  model: z.ZodOptional<z.ZodString>;
15
+ effort: z.ZodOptional<z.ZodEnum<{
16
+ high: "high";
17
+ low: "low";
18
+ max: "max";
19
+ medium: "medium";
20
+ minimal: "minimal";
21
+ xhigh: "xhigh";
22
+ }>>;
23
+ account: z.ZodOptional<z.ZodString>;
24
+ permissionMode: z.ZodOptional<z.ZodEnum<{
25
+ auto: "auto";
26
+ "auto-edits": "auto-edits";
27
+ "full-access": "full-access";
28
+ supervised: "supervised";
29
+ }>>;
30
+ releaseActions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
31
+ "app-store": "app-store";
32
+ deploy: "deploy";
33
+ "github-admin": "github-admin";
34
+ merge: "merge";
35
+ publish: "publish";
36
+ }>>>;
14
37
  prompt: z.ZodString;
15
38
  label: z.ZodString;
16
39
  parent: z.ZodOptional<z.ZodObject<{
@@ -59,6 +82,28 @@ declare const receiptSchema: z.ZodObject<{
59
82
  opencode: "opencode";
60
83
  }>;
61
84
  model: z.ZodOptional<z.ZodString>;
85
+ effort: z.ZodOptional<z.ZodEnum<{
86
+ high: "high";
87
+ low: "low";
88
+ max: "max";
89
+ medium: "medium";
90
+ minimal: "minimal";
91
+ xhigh: "xhigh";
92
+ }>>;
93
+ account: z.ZodOptional<z.ZodString>;
94
+ permissionMode: z.ZodOptional<z.ZodEnum<{
95
+ auto: "auto";
96
+ "auto-edits": "auto-edits";
97
+ "full-access": "full-access";
98
+ supervised: "supervised";
99
+ }>>;
100
+ releaseActions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
101
+ "app-store": "app-store";
102
+ deploy: "deploy";
103
+ "github-admin": "github-admin";
104
+ merge: "merge";
105
+ publish: "publish";
106
+ }>>>;
62
107
  label: z.ZodString;
63
108
  parent: z.ZodOptional<z.ZodObject<{
64
109
  provider: z.ZodEnum<{
@@ -125,7 +170,13 @@ declare const receiptSchema: z.ZodObject<{
125
170
  startingToken: z.ZodString;
126
171
  }, z.core.$strip>]>>;
127
172
  error: z.ZodOptional<z.ZodString>;
173
+ brief: z.ZodOptional<z.ZodEnum<{
174
+ launch: "launch";
175
+ typed: "typed";
176
+ }>>;
128
177
  granted: z.ZodOptional<z.ZodString>;
178
+ authority: z.ZodOptional<z.ZodString>;
179
+ authorityConfirmed: z.ZodOptional<z.ZodString>;
129
180
  skipped: z.ZodOptional<z.ZodArray<z.ZodObject<{
130
181
  computer: z.ZodString;
131
182
  reason: z.ZodString;
@@ -156,6 +207,8 @@ declare const receiptSchema: z.ZodObject<{
156
207
  since: z.ZodString;
157
208
  checkedAt: z.ZodString;
158
209
  sawWorking: z.ZodBoolean;
210
+ background: z.ZodOptional<z.ZodNumber>;
211
+ waitingSince: z.ZodOptional<z.ZodString>;
159
212
  }, z.core.$strict>>;
160
213
  returned: z.ZodOptional<z.ZodObject<{
161
214
  state: z.ZodEnum<{
@@ -173,10 +226,44 @@ declare const receiptSchema: z.ZodObject<{
173
226
  turn: z.ZodOptional<z.ZodString>;
174
227
  read: z.ZodBoolean;
175
228
  notifiedAt: z.ZodOptional<z.ZodString>;
229
+ background: z.ZodOptional<z.ZodNumber>;
230
+ waited: z.ZodOptional<z.ZodNumber>;
231
+ }, z.core.$strict>>;
232
+ approval: z.ZodOptional<z.ZodObject<{
233
+ actionId: z.ZodString;
234
+ tool: z.ZodString;
235
+ title: z.ZodOptional<z.ZodString>;
236
+ request: z.ZodOptional<z.ZodString>;
237
+ requestKind: z.ZodOptional<z.ZodEnum<{
238
+ command: "command";
239
+ edit: "edit";
240
+ other: "other";
241
+ question: "question";
242
+ tool: "tool";
243
+ }>>;
244
+ terminal: z.ZodOptional<z.ZodBoolean>;
245
+ conductor: z.ZodOptional<z.ZodObject<{
246
+ action: z.ZodEnum<{
247
+ dispatch: "dispatch";
248
+ hand_off: "hand_off";
249
+ }>;
250
+ project: z.ZodOptional<z.ZodString>;
251
+ computer: z.ZodOptional<z.ZodString>;
252
+ }, z.core.$strict>>;
253
+ expiresAt: z.ZodOptional<z.ZodString>;
254
+ at: z.ZodString;
255
+ pushed: z.ZodOptional<z.ZodBoolean>;
176
256
  }, z.core.$strict>>;
177
257
  }, z.core.$strict>;
178
258
  export type Receipt = z.infer<typeof receiptSchema>;
179
- export declare function dispatchProjectDirectory(project: unknown): Promise<string>;
259
+ /**
260
+ * The project's folder on this computer. The store syncs between computers,
261
+ * so its shared `sourcePath` is often another machine's folder: this
262
+ * machine's `sourcePaths` entry wins, as everywhere else in phren. With
263
+ * neither here, a git checkout named after the project in a usual project
264
+ * root is taken (the owner's layout is `~/Projects/<name>` on every computer).
265
+ */
266
+ export declare function dispatchProjectDirectory(project: unknown, home?: string): Promise<string>;
180
267
  /**
181
268
  * Change one settled receipt: read it, let `change` edit it, and write it back
182
269
  * when `change` returns true. Updates run one at a time in this process, and a
@@ -186,6 +273,9 @@ export declare function updateReceipt(receiptID: string, change: (receipt: Recei
186
273
  /** One bounded line for a log or a receipt: a Bridge message, an errno code, or the error's first line. */
187
274
  export declare function failureReason(error: unknown): string;
188
275
  export declare function dispatchStatus(): Promise<Receipt[]>;
276
+ /** What the worker's own hooks reported for a brief that went with its
277
+ * launch, or undefined when the receiving Hook has no such brief. */
278
+ export declare function arrivalOf(peer: Pick<DispatchHost, "request">, id: string): Promise<BriefArrival | undefined>;
189
279
  export interface DispatchIdentity {
190
280
  computerID: string;
191
281
  validateParentTarget: (target: Target) => Promise<unknown>;
@@ -198,13 +288,24 @@ export interface DispatchIdentity {
198
288
  export declare class DispatchService {
199
289
  private readonly identity?;
200
290
  private readonly local;
291
+ private readonly settleIntervalMs;
201
292
  private active;
202
293
  /** `local` is this computer as a dispatch destination (its own Hook's
203
294
  * socket); tests replace it so they never reach a real Hook. */
204
- constructor(identity?: DispatchIdentity | undefined, local?: () => DispatchHost);
295
+ constructor(identity?: DispatchIdentity | undefined, local?: () => DispatchHost, settleIntervalMs?: number);
205
296
  /** `originValue` is the local pane the request came from, as its agent's
206
297
  * Herdr variables name it; a pane without a running agent is left out. */
207
298
  dispatch(input: unknown, originValue?: unknown): Promise<Json>;
299
+ /**
300
+ * A brief that went with the launch: wait for the worker's hook to confirm
301
+ * it by dispatch id. A startup screen (folder trust, sign-in) holds the
302
+ * prompt until the owner answers it, and the harness then submits it by
303
+ * itself, so that is not a failure. Neither confirmed nor held reads
304
+ * uncertain, and the returns loop keeps asking.
305
+ */
306
+ private confirmLaunched;
307
+ /** The query a conductor's dispatch sends with each capacity probe; undefined for any other caller. */
308
+ private conductorCaller;
208
309
  private origin;
209
310
  }
210
311
  export {};
@@ -3,14 +3,23 @@ import { lstat, mkdir, readFile, readdir, realpath, stat } from "node:fs/promise
3
3
  import path from "node:path";
4
4
  import { z } from "zod";
5
5
  import { logger } from "../logger.js";
6
- import { readProjectConfig } from "../project-config.js";
6
+ import { homeDir } from "../home-paths.js";
7
+ import { getMachineName } from "../machine-identity.js";
8
+ import { getProjectSourcePath } from "../project-config.js";
7
9
  import { computerName } from "./computers.js";
8
10
  import { dispatchParentSchema, validateDispatchParent } from "./dispatch-tree.js";
9
- import { grantLabel, listGrants, matchGrant } from "./grants.js";
11
+ import { findGrant, grantLabel, permissionModeAllowed, DEFAULT_MAX_PERMISSION_MODE } from "./grants.js";
12
+ import { checkAgentDispatch, projectAuthority, readAuthority, RELEASE_ACTIONS, releaseAction } from "./authority.js";
10
13
  import { hookPeers } from "./peers.js";
14
+ import { callerQuery, localCaller, oneWayHint } from "./conductor-group.js";
15
+ import { recordedConductor } from "./conductor-role.js";
16
+ import { linkedComputer } from "./computer-identity.js";
11
17
  import { isLocalComputer, localHost, peerHost } from "./dispatch-hosts.js";
12
- import { atomic, BridgeError, bridgeRoot, id, PROTOCOL, provider, serverName, startingTargetSchema, targetSchema } from "./protocol.js";
18
+ import { atomic, BridgeError, bridgeRoot, id, launchEfforts, PERMISSION_MODES, PROTOCOL, provider, serverName, startingTargetSchema, targetSchema } from "./protocol.js";
13
19
  import { phrenStoreRoot } from "./transcripts.js";
20
+ import { isAccountSlug } from "./claude-accounts.js";
21
+ import { hasUsable } from "./harnesses.js";
22
+ import { arrivalSchema } from "./launch-brief.js";
14
23
  const text = (max) => z.string().min(1).max(max).refine(value => !!value.trim() && !/[\x00-\x1f\x7f]/.test(value));
15
24
  export const projectName = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/);
16
25
  export const dispatchSchema = z.object({
@@ -18,6 +27,12 @@ export const dispatchSchema = z.object({
18
27
  project: projectName.describe("Project slug registered on the receiving computer."),
19
28
  harness: z.enum(["codex", "claude", "opencode"]).describe("Agent harness on the receiving computer."),
20
29
  model: text(200).optional().describe("Explicit model, otherwise the remote harness default."),
30
+ effort: z.enum(launchEfforts).optional().describe("Reasoning effort for the worker (minimal, low, medium, high, xhigh, max), otherwise the harness default."),
31
+ account: z.string().refine(isAccountSlug, "Account must be default or a lowercase slug.").optional()
32
+ .describe("Claude account id to run the worker under (default, or a slug from `phren bridge accounts`). anywhere only picks computers where that account is signed in; a named computer without it fails."),
33
+ permissionMode: z.enum(PERMISSION_MODES).optional().describe("Permission mode the worker starts in: supervised, auto-edits, auto or full-access (Claude and Codex only); otherwise the receiving computer's own default."),
34
+ releaseActions: z.array(releaseAction).min(1).max(RELEASE_ACTIONS.length).optional()
35
+ .describe("Release-type actions the brief asks the worker to do (merge, publish, deploy, app-store, github-admin). Ask-first projects refuse them from an agent unless the owner confirmed."),
21
36
  prompt: z.string().min(1).max(32768).refine(value => !/[\x00-\x08\x0b-\x1f\x7f]/.test(value)).describe("Worker brief, at most 32768 characters."),
22
37
  label: text(200).describe("Short task label."),
23
38
  parent: dispatchParentSchema.optional().describe("Explicit local conversation parent for work-tree attachment."),
@@ -33,34 +48,66 @@ const receiptSchema = dispatchSchema.omit({ prompt: true }).extend({
33
48
  computerId: z.string().uuid().optional(),
34
49
  state: z.enum(["launching", "sending", "accepted", "uncertain", "failed"]),
35
50
  target: remoteTarget.optional(), error: z.string().max(500).optional(),
51
+ brief: z.enum(["launch", "typed"]).optional()
52
+ .describe("How the brief reached the worker: as its first prompt at launch (confirmed by the worker's hook), or typed into its pane."),
36
53
  granted: z.string().max(200).optional().describe("Scope of the conductor grant that allowed this call."),
54
+ authority: z.string().max(600).optional().describe("The release authority policy's line for this project, as a conductor quotes it."),
55
+ authorityConfirmed: z.string().datetime().optional().describe("When the owner confirmed the ask-first release actions this agent dispatch used."),
37
56
  skipped: z.array(z.object({ computer: computerName, reason: z.string().max(200) }).strict()).max(32).optional()
38
57
  .describe("Computers left out of anywhere placement, with the reason each could not report capacity."),
39
58
  origin: originPaneSchema.extend({ agent: provider, terminal: z.string().min(1).max(200) }).strict().optional()
40
59
  .describe("The local agent pane that placed this dispatch; return notices go there."),
41
- worker: z.object({ state: z.enum(workerStates), since: timestamp, checkedAt: timestamp, sawWorking: z.boolean() }).strict().optional()
60
+ worker: z.object({ state: z.enum(workerStates), since: timestamp, checkedAt: timestamp, sawWorking: z.boolean(),
61
+ background: z.number().int().min(0).max(999).optional().describe("The most background tasks seen running while the worker was working."),
62
+ waitingSince: timestamp.optional().describe("When the dispatching Hook first saw the worker's finished turn waiting on background tasks; bounds that wait.") }).strict().optional()
42
63
  .describe("The worker pane's last observed state."),
43
64
  returned: z.object({
44
65
  state: z.enum(["done", "needs-you", "failed", "blocked", "gone"]), at: timestamp,
45
66
  reply: z.string().max(4000).optional(), error: z.string().max(500).optional(), truncated: z.boolean().optional(), question: z.string().max(200).optional(),
46
67
  turn: z.string().regex(/^[a-f0-9]{16}$/).optional(), read: z.boolean(), notifiedAt: timestamp.optional(),
68
+ background: z.number().int().min(1).max(999).optional().describe("Background tasks the worker left running when it was counted done."),
69
+ waited: z.number().int().min(1).max(999).optional().describe("The most background tasks the worker waited on before it finished."),
47
70
  }).strict().optional().describe("The latest return: the worker finished, needs the owner, failed, is blocked or is gone."),
71
+ approval: z.object({
72
+ actionId: z.string().min(1).max(200), tool: z.string().max(200), title: z.string().max(200).optional(), request: z.string().max(500).optional(),
73
+ requestKind: z.enum(["command", "tool", "edit", "question", "other"]).optional(), terminal: z.boolean().optional(),
74
+ conductor: z.object({ action: z.enum(["dispatch", "hand_off"]), project: z.string().max(200).optional(), computer: z.string().max(200).optional() }).strict().optional(),
75
+ expiresAt: z.string().max(40).optional(), at: timestamp, pushed: z.boolean().optional(),
76
+ }).strict().optional().describe("A permission request the worker is waiting on, forwarded by its Hook; answer it with dispatch_approve."),
48
77
  });
49
- export async function dispatchProjectDirectory(project) {
50
- const name = projectName.parse(project);
51
- const source = readProjectConfig(phrenStoreRoot(), name).sourcePath;
78
+ /** Where a checkout usually sits when the store names none for this computer. */
79
+ const CHECKOUT_ROOTS = ["Projects", "projects", "Sites", "Code", "code", "dev", "src", "repos"];
80
+ async function directoryAt(source) {
52
81
  if (typeof source !== "string" || !path.isAbsolute(source) || /[\x00-\x1f\x7f]/.test(source))
53
- throw new BridgeError(404, "Project has no absolute sourcePath on this computer.");
82
+ return undefined;
54
83
  const directory = await realpath(source).catch(() => undefined);
55
- if (!directory || !(await stat(directory)).isDirectory())
56
- throw new BridgeError(404, "Project is not on this computer.");
57
- return directory;
84
+ return directory && (await stat(directory)).isDirectory() ? directory : undefined;
85
+ }
86
+ /**
87
+ * The project's folder on this computer. The store syncs between computers,
88
+ * so its shared `sourcePath` is often another machine's folder: this
89
+ * machine's `sourcePaths` entry wins, as everywhere else in phren. With
90
+ * neither here, a git checkout named after the project in a usual project
91
+ * root is taken (the owner's layout is `~/Projects/<name>` on every computer).
92
+ */
93
+ export async function dispatchProjectDirectory(project, home = homeDir()) {
94
+ const name = projectName.parse(project);
95
+ const configured = await directoryAt(getProjectSourcePath(phrenStoreRoot(), name));
96
+ if (configured)
97
+ return configured;
98
+ for (const root of [...(process.env.PROJECTS_DIR ? [process.env.PROJECTS_DIR] : []), ...CHECKOUT_ROOTS.map(folder => path.join(home, folder))]) {
99
+ const checkout = await directoryAt(path.join(root, name));
100
+ if (checkout && await stat(path.join(checkout, ".git")).catch(() => undefined))
101
+ return checkout;
102
+ }
103
+ throw new BridgeError(404, `Project ${name} is not on this computer: the store names no folder for ${getMachineName()} that exists here, and there is no ~/Projects/${name} checkout.`);
58
104
  }
59
105
  async function save(receipt) {
60
106
  const root = path.join(bridgeRoot(), "dispatches");
61
107
  await mkdir(root, { recursive: true, mode: 0o700 });
62
108
  await atomic(path.join(root, `${receipt.id}.json`), receipt);
63
109
  }
110
+ const IGNORED_MODE = "The receiving Hook is older and ignored permissionMode; the worker runs in that computer's default mode. Update its Hook.";
64
111
  const MAX_RECEIPT_BYTES = 65_536;
65
112
  let receiptUpdates = Promise.resolve();
66
113
  /**
@@ -125,39 +172,71 @@ export async function dispatchStatus() {
125
172
  }
126
173
  return receipts.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
127
174
  }
128
- async function capacity(host) {
129
- const value = await host.request("/v1/dispatch/capacity");
175
+ /** `caller` (a conductor's name and host key) asks a peer whether it links this computer back:
176
+ * `outside` is a peer in another set, which a conductor does not dispatch to. */
177
+ async function capacity(host, caller) {
178
+ const value = await host.request(caller && !host.local ? `/v1/dispatch/capacity?${caller}` : "/v1/dispatch/capacity");
130
179
  const result = z.object({ product: z.literal("phren-hook"), protocol: z.literal(PROTOCOL), working: z.number().int().nonnegative(),
131
- servers: z.array(z.string()), computer: z.object({ id: z.string().uuid() }).passthrough() }).parse(value);
180
+ servers: z.array(z.string()), computer: z.object({ id: z.string().uuid() }).passthrough(),
181
+ // Missing from an older Hook, or when its inventory was not ready in time: unknown, not unavailable.
182
+ harnesses: z.array(z.object({ source: z.string(), installed: z.boolean(), usable: z.boolean(), reason: z.string().optional(),
183
+ accounts: z.array(z.object({ id: z.string(), usable: z.boolean(), reason: z.string().optional() }).passthrough()).optional() }).passthrough()).optional(),
184
+ knowsCaller: z.boolean().optional() }).parse(value);
132
185
  // This computer places on whichever Herdr server its own Hook runs.
133
186
  if (host.local && !result.servers.includes(host.server) && result.servers[0])
134
187
  host.server = result.servers[0];
135
188
  if (!result.servers.includes(host.server))
136
189
  throw new BridgeError(503, "Herdr is not running on the selected computer. Headless dispatch is not installed yet.");
137
- return { working: result.working, computerId: result.computer.id };
190
+ return { working: result.working, computerId: result.computer.id, ...(result.harnesses ? { harnesses: result.harnesses } : {}),
191
+ ...(caller && result.knowsCaller === false ? { outside: true } : {}) };
192
+ }
193
+ /** Why a computer cannot run this dispatch's harness and account, or undefined when it can or cannot yet be told.
194
+ * `unknown` (no `harnesses`) only counts against a computer when a non-default account was asked for. */
195
+ function unusable(data, harnesses, strictUnknown) {
196
+ if (!harnesses)
197
+ return strictUnknown && data.account && data.account !== "default" ? "Its Hook does not report harnesses or accounts (update it)." : undefined;
198
+ const availability = hasUsable({ harnesses }, data.harness, data.account);
199
+ return availability.ok ? undefined : availability.reason;
138
200
  }
139
201
  /**
140
202
  * A freshly started agent may not have written its session yet when the launch
141
- * returns, so the launch carries no target. Ask the remote pane for its session
142
- * for a few seconds before giving up; the pane ids from the launch are enough
143
- * to find it.
203
+ * returns, so the launch carries no target. Ask the remote pane for a few
204
+ * seconds; the pane ids from the launch are enough to find it. Until its first
205
+ * prompt a new Codex or Claude has no conversation at all, only a starting
206
+ * binding, and that is the target its brief goes to (as the phone's first
207
+ * message does). `status` is the pane's last status when neither appeared.
144
208
  */
145
- async function settledTarget(peer, launched, harness) {
209
+ async function settledTarget(peer, launched, harness, intervalMs = 1_000) {
146
210
  const workspace = launched.workspaceId, tab = launched.tabId, pane = launched.paneId;
147
211
  if (typeof workspace !== "string" || typeof tab !== "string" || typeof pane !== "string")
148
- return undefined;
212
+ return {};
213
+ let status;
149
214
  for (let attempt = 0; attempt < 15; attempt++) {
150
- await new Promise(resolve => setTimeout(resolve, 1_000));
215
+ await new Promise(resolve => setTimeout(resolve, intervalMs));
151
216
  try {
152
217
  const result = await peer.request(`/v1/workspaces/panes?server=${encodeURIComponent(peer.server)}&groupId=${encodeURIComponent(workspace)}&childId=${encodeURIComponent(tab)}`);
153
218
  const found = (Array.isArray(result.panes) ? result.panes : []).find((p) => p && typeof p === "object" && p.id === pane);
219
+ if (typeof found?.agentStatus === "string")
220
+ status = found.agentStatus;
221
+ const binding = { server: peer.server, workspace, tab, pane, source: harness };
154
222
  const session = found?.sessionId;
155
223
  if (typeof session === "string" && session)
156
- return { server: peer.server, workspace, tab, pane, source: harness, session };
224
+ return { target: { ...binding, session } };
225
+ if (found?.starting === true && typeof found.startingToken === "string")
226
+ return { target: { ...binding, starting: true, startingToken: found.startingToken } };
157
227
  }
158
228
  catch { /* The pane list can lag the launch; try again. */ }
159
229
  }
160
- return undefined;
230
+ return { status };
231
+ }
232
+ /** The new agent is holding a screen of its own before it takes any prompt:
233
+ * Claude's folder trust or a sign-in. Only the owner answers those. */
234
+ class StartupScreen extends Error {
235
+ status;
236
+ constructor(status) {
237
+ super(`The agent is ${status} on a startup screen.`);
238
+ this.status = status;
239
+ }
161
240
  }
162
241
  /**
163
242
  * Sends the brief. A fresh agent can read `unknown` to Herdr for a while (long
@@ -166,10 +245,11 @@ async function settledTarget(peer, launched, harness) {
166
245
  * unclassified; a pane that is blocked or waiting really needs its terminal,
167
246
  * and that refusal stands.
168
247
  */
169
- async function sendBrief(peer, target, text) {
248
+ async function sendBrief(peer, target, text, deliveryId) {
170
249
  for (let attempt = 0;; attempt++) {
250
+ // One delivery id for every attempt: the receiving Hook types it once.
171
251
  try {
172
- return await peer.request("/v1/prompt", { target, text });
252
+ return await peer.request("/v1/prompt", { target, text, deliveryId });
173
253
  }
174
254
  catch (error) {
175
255
  const unsettled = error instanceof BridgeError && error.status === 409 && /needs input in the terminal first/.test(error.message);
@@ -178,26 +258,61 @@ async function sendBrief(peer, target, text) {
178
258
  const panes = await peer.request(`/v1/workspaces/panes?server=${encodeURIComponent(peer.server)}&groupId=${encodeURIComponent(String(target.workspace))}&childId=${encodeURIComponent(String(target.tab))}`).catch(() => undefined);
179
259
  const pane = (Array.isArray(panes?.panes) ? panes.panes : []).find((p) => p && typeof p === "object" && p.id === target.pane);
180
260
  const status = pane?.agentStatus;
261
+ // Nothing was typed: the refusal came before any text reached the pane.
181
262
  if (typeof status === "string" && ["blocked", "waiting"].includes(status))
182
- throw error;
263
+ throw new StartupScreen(status);
183
264
  await new Promise(resolve => setTimeout(resolve, 1_000));
184
265
  }
185
266
  }
186
267
  }
268
+ /** What the worker's own hooks reported for a brief that went with its
269
+ * launch, or undefined when the receiving Hook has no such brief. */
270
+ export async function arrivalOf(peer, id) {
271
+ const answer = await peer.request(`/v1/dispatch/arrival?id=${encodeURIComponent(id)}`);
272
+ const arrival = answer.arrival === null ? undefined : arrivalSchema.parse(answer.arrival);
273
+ return arrival;
274
+ }
275
+ /**
276
+ * A brief that went with the launch is the new agent's first prompt; its
277
+ * UserPromptSubmit hook echoes the dispatch id when the harness submits it.
278
+ * Waits for that echo, and returns the conversation it named.
279
+ */
280
+ async function awaitArrival(peer, id, intervalMs) {
281
+ let last = {};
282
+ for (let attempt = 0; attempt < ARRIVAL_ATTEMPTS; attempt++) {
283
+ await new Promise(resolve => setTimeout(resolve, intervalMs));
284
+ last = await arrivalOf(peer, id).catch(() => undefined) ?? last;
285
+ if (last.accepted)
286
+ break;
287
+ }
288
+ return last;
289
+ }
290
+ /** Claude and Codex take a few seconds to start, load their MCP servers and submit the prompt. */
291
+ const ARRIVAL_ATTEMPTS = 30;
292
+ /** The pane's status as the remote Hook lists it now. */
293
+ async function paneStatus(peer, launched) {
294
+ const panes = await peer.request(`/v1/workspaces/panes?server=${encodeURIComponent(peer.server)}&groupId=${encodeURIComponent(String(launched.workspaceId))}&childId=${encodeURIComponent(String(launched.tabId))}`).catch(() => undefined);
295
+ const pane = (Array.isArray(panes?.panes) ? panes.panes : []).find((p) => p && typeof p === "object" && p.id === launched.paneId);
296
+ return typeof pane?.agentStatus === "string" ? pane.agentStatus : undefined;
297
+ }
187
298
  export class DispatchService {
188
299
  identity;
189
300
  local;
301
+ settleIntervalMs;
190
302
  active = false;
191
303
  /** `local` is this computer as a dispatch destination (its own Hook's
192
304
  * socket); tests replace it so they never reach a real Hook. */
193
- constructor(identity, local = () => localHost()) {
305
+ constructor(identity, local = () => localHost(), settleIntervalMs = 1_000) {
194
306
  this.identity = identity;
195
307
  this.local = local;
308
+ this.settleIntervalMs = settleIntervalMs;
196
309
  }
197
310
  /** `originValue` is the local pane the request came from, as its agent's
198
311
  * Herdr variables name it; a pane without a running agent is left out. */
199
312
  async dispatch(input, originValue) {
200
313
  const data = dispatchSchema.parse(input);
314
+ if (data.permissionMode && data.harness === "opencode")
315
+ throw new BridgeError(400, "OpenCode takes its permissions from its own config; permissionMode is for Claude and Codex workers.");
201
316
  if (this.active)
202
317
  throw new BridgeError(429, "A dispatch is already being placed. Try again after its receipt arrives.");
203
318
  this.active = true;
@@ -212,17 +327,23 @@ export class DispatchService {
212
327
  // This computer needs no hooks.yaml entry, so a missing file only
213
328
  // matters when the dispatch names another computer.
214
329
  const here = this.local();
215
- const toLocal = data.computer !== "anywhere" && isLocalComputer(data.computer, here.names);
330
+ // An alias or hostname (`Mac`, `Squids-Mac-mini.local`) names the same computer as its hooks.yaml name.
331
+ const named = data.computer === "anywhere" || isLocalComputer(data.computer, here.names) ? undefined : await linkedComputer(data.computer).catch(() => undefined);
332
+ const toLocal = data.computer !== "anywhere" && (isLocalComputer(data.computer, here.names) || (named !== undefined && "local" in named));
333
+ const peerName = named && "peer" in named ? named.peer : data.computer;
216
334
  const enrolled = await hookPeers().catch(error => { if (toLocal || data.computer === "anywhere")
217
335
  return []; throw error; });
336
+ // A conductor dispatches only within its set: each peer says whether it links this computer back.
337
+ const caller = await this.conductorCaller(originValue);
218
338
  const peers = [...enrolled.map(candidate => peerHost(candidate)), here];
219
339
  let peer;
220
340
  let remoteComputerID;
221
341
  const skipped = [];
342
+ let incapable = false;
222
343
  if (data.computer === "anywhere") {
223
344
  const available = await Promise.all(peers.map(async (candidate) => {
224
345
  try {
225
- return { peer: candidate, ...await capacity(candidate) };
346
+ return { peer: candidate, ...await capacity(candidate, caller) };
226
347
  }
227
348
  catch (error) {
228
349
  // A peer that cannot report capacity sits out this placement, and the receipt says why.
@@ -231,42 +352,109 @@ export class DispatchService {
231
352
  }
232
353
  }));
233
354
  skipped.sort((a, b) => a.computer.localeCompare(b.computer));
234
- const selected = available.filter((item) => !!item)
355
+ const capable = available.filter((item) => !!item).filter(item => {
356
+ if (item.outside) {
357
+ skipped.push({ computer: item.peer.name, reason: oneWayHint(item.peer.name) });
358
+ return false;
359
+ }
360
+ const reason = unusable(data, item.harnesses, true);
361
+ if (reason)
362
+ incapable = true;
363
+ if (reason)
364
+ skipped.push({ computer: item.peer.name, reason: reason.slice(0, 200) });
365
+ return !reason;
366
+ });
367
+ skipped.sort((a, b) => a.computer.localeCompare(b.computer));
368
+ const selected = capable
235
369
  .sort((a, b) => a.working - b.working || a.peer.name.localeCompare(b.peer.name))[0];
236
370
  peer = selected?.peer;
237
371
  remoteComputerID = selected?.computerId;
238
372
  if (!peer)
239
- throw new BridgeError(503, "No enrolled computer with a running Herdr is connected.", skipped.length ? { skipped } : undefined);
373
+ throw new BridgeError(503, incapable ? `No enrolled computer with a running Herdr can run ${data.harness}${data.account ? ` account ${data.account}` : ""}.` : "No enrolled computer with a running Herdr is connected.", skipped.length ? { skipped } : undefined);
240
374
  }
241
375
  else {
242
- peer = toLocal ? peers.find(candidate => candidate.local) : peers.find(candidate => !candidate.local && candidate.name === data.computer);
376
+ peer = toLocal ? peers.find(candidate => candidate.local) : peers.find(candidate => !candidate.local && candidate.name === peerName);
243
377
  if (!peer)
244
378
  throw new BridgeError(404, "Unknown computer. Add its verified connection to hooks.yaml.");
245
- remoteComputerID = (await capacity(peer)).computerId;
379
+ const reported = await capacity(peer, caller);
380
+ if (reported.outside)
381
+ throw new BridgeError(409, `${peer.name} is not in this conductor's set. ${oneWayHint(peer.name)}`, { code: "outside_set" });
382
+ remoteComputerID = reported.computerId;
383
+ // A Hook that reports what it can run is believed. An older one that does not is left to answer the launch
384
+ // itself, except for a non-default account: it would ignore `account` and launch under its default login.
385
+ const reason = unusable(data, reported.harnesses, true);
386
+ if (reason)
387
+ throw new BridgeError(409, `${peer.name} cannot run ${data.harness}${data.account ? ` account ${data.account}` : ""}: ${reason}`);
388
+ }
389
+ const grant = await findGrant({ action: "dispatch", project: data.project, computer: peer.name });
390
+ // An agent (a call that names its pane) may start a worker only up to its grant's
391
+ // permission ceiling; the owner, calling from the phone or the CLI without a pane, is not capped.
392
+ const agent = originPaneSchema.safeParse(originValue).success;
393
+ if (data.permissionMode && agent && !permissionModeAllowed(data.permissionMode, grant)) {
394
+ throw new BridgeError(403, `No standing grant lets an agent start a worker in ${data.permissionMode} on ${peer.name}. Add maxPermissionMode: ${data.permissionMode} to a grant in conductor.yaml, or dispatch it yourself.`);
246
395
  }
247
- const grant = matchGrant(await listGrants(), { action: "dispatch", project: data.project, computer: peer.name });
396
+ // The owner's release authority policy binds an agent's dispatch (and may
397
+ // lower its mode); the owner's own dispatch only carries the policy's line.
398
+ const checked = agent ? await checkAgentDispatch(data, grant?.maxPermissionMode ?? DEFAULT_MAX_PERMISSION_MODE) : undefined;
399
+ if (checked?.permissionMode)
400
+ data.permissionMode = checked.permissionMode;
401
+ const authority = checked?.authority ?? await readAuthority().then(policy => projectAuthority(policy, data.project)).catch(() => undefined);
248
402
  const origin = await this.origin(originValue);
249
403
  // Prompts are sent over the pipe, never stored in the dispatch ledger.
250
404
  const { prompt, ...metadata } = data;
251
405
  const receipt = { ...metadata, computer: peer.name, computerId: remoteComputerID, id: randomUUID(),
252
406
  createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), state: "launching",
253
- ...(grant ? { granted: grantLabel(grant) } : {}), ...(skipped.length ? { skipped } : {}), ...(origin ? { origin } : {}) };
407
+ ...(grant ? { granted: grantLabel(grant) } : {}), ...(authority?.listed ? { authority: authority.line.slice(0, 600) } : {}),
408
+ ...(checked?.confirmation ? { authorityConfirmed: checked.confirmation.confirmedAt } : {}),
409
+ ...(skipped.length ? { skipped } : {}), ...(origin ? { origin } : {}) };
254
410
  await save(receipt);
255
411
  try {
256
- const launched = await peer.request(`/v1/workspaces/launch?server=${encodeURIComponent(peer.server)}`, { project: data.project, kind: data.harness, model: data.model, label: data.label });
257
- const target = remoteTarget.parse(launched.target ?? await settledTarget(peer, launched, data.harness));
412
+ // The brief goes with the launch: a Hook that can start the harness
413
+ // with it says so, and any other types it below.
414
+ const launched = await peer.request(`/v1/workspaces/launch?server=${encodeURIComponent(peer.server)}`, { project: data.project, kind: data.harness, model: data.model, ...(data.effort ? { effort: data.effort } : {}), ...(data.account ? { account: data.account } : {}), ...(data.permissionMode ? { permissionMode: data.permissionMode } : {}), label: data.label, brief: { id: receipt.id, text: prompt } });
415
+ // An older Hook ignores the field and starts the worker in its own default mode.
416
+ const ignored = data.permissionMode && launched.permissionMode !== data.permissionMode ? IGNORED_MODE : undefined;
417
+ if (launched.briefLaunched === true) {
418
+ receipt.brief = "launch";
419
+ await this.confirmLaunched(peer, receipt, launched);
420
+ if (ignored)
421
+ receipt.error = [receipt.error, ignored].filter(Boolean).join(" ").slice(0, 500);
422
+ receipt.updatedAt = new Date().toISOString();
423
+ await save(receipt);
424
+ return { ok: receipt.state === "accepted", ...receipt };
425
+ }
426
+ receipt.brief = "typed";
427
+ const settled = launched.target ? { target: launched.target } : await settledTarget(peer, launched, data.harness, this.settleIntervalMs);
428
+ if (!settled.target) {
429
+ if (["blocked", "waiting"].includes(String(settled.status ?? launched.agentStatus)))
430
+ throw new StartupScreen(String(settled.status ?? launched.agentStatus));
431
+ throw new BridgeError(504, `${data.harness} started in the new "${data.label}" pane on ${peer.name} but never showed a conversation or a starting pane (last status ${settled.status ?? "unknown"}), so the brief was not sent. The pane is still open.`);
432
+ }
433
+ const target = remoteTarget.parse(settled.target);
258
434
  if (target.source !== data.harness || target.server !== peer.server)
259
435
  throw new BridgeError(502, "The remote Hook returned a different launch target.");
260
436
  receipt.target = target;
261
437
  receipt.state = "sending";
262
438
  receipt.updatedAt = new Date().toISOString();
263
439
  await save(receipt);
264
- const result = await sendBrief(peer, receipt.target, prompt);
440
+ const result = await sendBrief(peer, receipt.target, prompt, `dispatch-${receipt.id}`);
265
441
  receipt.state = result.ok === true && result.deliveryUncertain !== true ? "accepted" : "uncertain";
442
+ if (ignored)
443
+ receipt.error = ignored;
266
444
  }
267
445
  catch (error) {
268
- receipt.state = receipt.state === "launching" && error instanceof BridgeError && [400, 404, 429].includes(error.status) ? "failed" : "uncertain";
269
- receipt.error = error instanceof BridgeError ? error.message.slice(0, 500) : "Remote delivery was not confirmed. Inspect this dispatch before retrying.";
446
+ if (error instanceof StartupScreen) {
447
+ // Known, not uncertain: the brief never reached the pane. Say where
448
+ // the owner answers, and let the returns loop tell the conductor once.
449
+ const question = `${data.harness} in "${data.label}" on ${peer.name} is waiting on a startup screen (folder trust or sign-in).`.slice(0, 200);
450
+ receipt.state = "failed";
451
+ receipt.error = `${question} The brief was not sent. Answer that screen in the pane (the phone can), then hand the brief off to the new session.`.slice(0, 500);
452
+ receipt.returned = { state: "needs-you", at: new Date().toISOString(), question, read: false };
453
+ }
454
+ else {
455
+ receipt.state = receipt.state === "launching" && error instanceof BridgeError && [400, 404, 429, 504].includes(error.status) ? "failed" : "uncertain";
456
+ receipt.error = error instanceof BridgeError ? error.message.slice(0, 500) : "Remote delivery was not confirmed. Inspect this dispatch before retrying.";
457
+ }
270
458
  }
271
459
  receipt.updatedAt = new Date().toISOString();
272
460
  await save(receipt);
@@ -276,6 +464,50 @@ export class DispatchService {
276
464
  this.active = false;
277
465
  }
278
466
  }
467
+ /**
468
+ * A brief that went with the launch: wait for the worker's hook to confirm
469
+ * it by dispatch id. A startup screen (folder trust, sign-in) holds the
470
+ * prompt until the owner answers it, and the harness then submits it by
471
+ * itself, so that is not a failure. Neither confirmed nor held reads
472
+ * uncertain, and the returns loop keeps asking.
473
+ */
474
+ async confirmLaunched(peer, receipt, launched) {
475
+ const known = remoteTarget.safeParse(launched.target);
476
+ if (known.success && known.data.source === receipt.harness && known.data.server === peer.server)
477
+ receipt.target = known.data;
478
+ receipt.state = "sending";
479
+ receipt.updatedAt = new Date().toISOString();
480
+ await save(receipt);
481
+ const held = (status) => ["blocked", "waiting"].includes(String(status));
482
+ const arrival = held(launched.agentStatus) ? await arrivalOf(peer, receipt.id).catch(() => undefined) ?? {}
483
+ : await awaitArrival(peer, receipt.id, this.settleIntervalMs);
484
+ const named = arrival.accepted?.target ?? arrival.started?.target;
485
+ if (named && named.source === receipt.harness && named.server === peer.server)
486
+ receipt.target = named;
487
+ if (arrival.accepted) {
488
+ receipt.state = "accepted";
489
+ return;
490
+ }
491
+ const status = held(launched.agentStatus) ? String(launched.agentStatus) : await paneStatus(peer, launched);
492
+ receipt.state = "uncertain";
493
+ if (held(status)) {
494
+ const question = `${receipt.harness} in "${receipt.label}" on ${receipt.computer} is waiting on a startup screen (folder trust or sign-in).`.slice(0, 200);
495
+ receipt.error = `${question} The brief is queued as its first prompt and starts once that screen is answered in the pane (the phone can).`.slice(0, 500);
496
+ receipt.returned = { state: "needs-you", at: new Date().toISOString(), question, read: false };
497
+ return;
498
+ }
499
+ receipt.error = `${receipt.harness} started with the brief on ${receipt.computer} but has not confirmed it yet (last status ${status ?? "unknown"}). The Hook keeps checking.`.slice(0, 500);
500
+ }
501
+ /** The query a conductor's dispatch sends with each capacity probe; undefined for any other caller. */
502
+ async conductorCaller(value) {
503
+ const pane = originPaneSchema.safeParse(value);
504
+ if (!pane.success)
505
+ return undefined;
506
+ const conductor = await recordedConductor().catch(() => undefined);
507
+ if (!conductor || conductor.server !== pane.data.server || conductor.pane !== pane.data.pane)
508
+ return undefined;
509
+ return callerQuery(await localCaller());
510
+ }
279
511
  async origin(value) {
280
512
  const pane = originPaneSchema.safeParse(value);
281
513
  if (!pane.success || !this.identity?.originAgent)