@phren/cli 0.3.11 → 0.3.13

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 (182) hide show
  1. package/dist/bridge/account-usage.d.ts +124 -0
  2. package/dist/bridge/account-usage.js +258 -0
  3. package/dist/bridge/agent-hook-stores.d.ts +3 -0
  4. package/dist/bridge/agent-hook-stores.js +5 -0
  5. package/dist/bridge/agent-hooks.d.ts +162 -5
  6. package/dist/bridge/agent-hooks.js +682 -49
  7. package/dist/bridge/approval-summary.d.ts +16 -0
  8. package/dist/bridge/approval-summary.js +133 -0
  9. package/dist/bridge/authority-command.d.ts +20 -0
  10. package/dist/bridge/authority-command.js +120 -0
  11. package/dist/bridge/authority.d.ts +223 -0
  12. package/dist/bridge/authority.js +231 -0
  13. package/dist/bridge/claude-account-setup.d.ts +14 -0
  14. package/dist/bridge/claude-account-setup.js +69 -0
  15. package/dist/bridge/claude-accounts.d.ts +49 -0
  16. package/dist/bridge/claude-accounts.js +195 -0
  17. package/dist/bridge/code-routes.js +2 -2
  18. package/dist/bridge/codex-app-server.d.ts +144 -0
  19. package/dist/bridge/codex-app-server.js +319 -0
  20. package/dist/bridge/codex-auth-refresh.d.ts +33 -0
  21. package/dist/bridge/codex-auth-refresh.js +71 -0
  22. package/dist/bridge/codex-hook-trust.d.ts +27 -0
  23. package/dist/bridge/codex-hook-trust.js +237 -0
  24. package/dist/bridge/codex-question-reply.d.ts +16 -0
  25. package/dist/bridge/codex-question-reply.js +57 -0
  26. package/dist/bridge/codex-review-mode.d.ts +10 -0
  27. package/dist/bridge/codex-review-mode.js +74 -0
  28. package/dist/bridge/codex-servers.d.ts +217 -0
  29. package/dist/bridge/codex-servers.js +636 -0
  30. package/dist/bridge/command.js +97 -4
  31. package/dist/bridge/computer-identity.d.ts +75 -0
  32. package/dist/bridge/computer-identity.js +166 -0
  33. package/dist/bridge/conductor-group.d.ts +91 -8
  34. package/dist/bridge/conductor-group.js +105 -9
  35. package/dist/bridge/conductor-role.d.ts +94 -0
  36. package/dist/bridge/conductor-role.js +176 -0
  37. package/dist/bridge/conductor-sets.d.ts +20 -0
  38. package/dist/bridge/conductor-sets.js +59 -0
  39. package/dist/bridge/dispatch-command.d.ts +3 -0
  40. package/dist/bridge/dispatch-command.js +82 -12
  41. package/dist/bridge/dispatch-returns.d.ts +128 -19
  42. package/dist/bridge/dispatch-returns.js +371 -54
  43. package/dist/bridge/dispatch.d.ts +128 -3
  44. package/dist/bridge/dispatch.js +303 -42
  45. package/dist/bridge/fanouts.d.ts +7 -1
  46. package/dist/bridge/fanouts.js +39 -4
  47. package/dist/bridge/folder-trust.d.ts +56 -0
  48. package/dist/bridge/folder-trust.js +195 -0
  49. package/dist/bridge/grants.d.ts +22 -1
  50. package/dist/bridge/grants.js +57 -9
  51. package/dist/bridge/hand-off-queue.d.ts +74 -0
  52. package/dist/bridge/hand-off-queue.js +235 -0
  53. package/dist/bridge/hand-off.d.ts +30 -10
  54. package/dist/bridge/hand-off.js +79 -46
  55. package/dist/bridge/harness-status.d.ts +11 -0
  56. package/dist/bridge/harness-status.js +32 -0
  57. package/dist/bridge/harnesses.d.ts +39 -0
  58. package/dist/bridge/harnesses.js +65 -0
  59. package/dist/bridge/health.d.ts +2 -0
  60. package/dist/bridge/health.js +1 -1
  61. package/dist/bridge/herdr.d.ts +11 -2
  62. package/dist/bridge/herdr.js +98 -23
  63. package/dist/bridge/hook-fast.d.ts +4 -0
  64. package/dist/bridge/hook-fast.js +68 -0
  65. package/dist/bridge/install.d.ts +16 -1
  66. package/dist/bridge/install.js +102 -21
  67. package/dist/bridge/launch-brief.d.ts +96 -0
  68. package/dist/bridge/launch-brief.js +164 -0
  69. package/dist/bridge/model-switch.d.ts +3 -0
  70. package/dist/bridge/model-switch.js +17 -1
  71. package/dist/bridge/models.d.ts +8 -4
  72. package/dist/bridge/models.js +24 -8
  73. package/dist/bridge/mux-wire.d.ts +9 -0
  74. package/dist/bridge/mux-wire.js +19 -0
  75. package/dist/bridge/opencode-pane-server.d.ts +113 -0
  76. package/dist/bridge/opencode-pane-server.js +332 -0
  77. package/dist/bridge/opencode-panes.d.ts +111 -0
  78. package/dist/bridge/opencode-panes.js +295 -0
  79. package/dist/bridge/pane-accounts.d.ts +8 -0
  80. package/dist/bridge/pane-accounts.js +46 -0
  81. package/dist/bridge/pane-status.d.ts +12 -0
  82. package/dist/bridge/pane-status.js +50 -1
  83. package/dist/bridge/prompt-startup.d.ts +5 -0
  84. package/dist/bridge/prompt-startup.js +24 -0
  85. package/dist/bridge/protocol.d.ts +5 -0
  86. package/dist/bridge/protocol.js +4 -0
  87. package/dist/bridge/push.d.ts +11 -4
  88. package/dist/bridge/push.js +27 -4
  89. package/dist/bridge/questions.d.ts +37 -2
  90. package/dist/bridge/questions.js +158 -15
  91. package/dist/bridge/resources.d.ts +9 -3
  92. package/dist/bridge/resources.js +24 -8
  93. package/dist/bridge/schedule-format.d.ts +2 -0
  94. package/dist/bridge/schedule-format.js +3 -0
  95. package/dist/bridge/schedule-launch.d.ts +2 -1
  96. package/dist/bridge/schedule-launch.js +27 -53
  97. package/dist/bridge/schedule-watch.d.ts +24 -1
  98. package/dist/bridge/schedule-watch.js +89 -2
  99. package/dist/bridge/server-launch.d.ts +22 -5
  100. package/dist/bridge/server-launch.js +238 -32
  101. package/dist/bridge/server-overview.d.ts +10 -3
  102. package/dist/bridge/server-overview.js +32 -15
  103. package/dist/bridge/server-pane-routes.d.ts +3 -0
  104. package/dist/bridge/server-pane-routes.js +150 -18
  105. package/dist/bridge/server-routes.d.ts +11 -0
  106. package/dist/bridge/server-routes.js +214 -36
  107. package/dist/bridge/server-stream.d.ts +2 -0
  108. package/dist/bridge/server-stream.js +22 -8
  109. package/dist/bridge/server.d.ts +6 -1
  110. package/dist/bridge/server.js +58 -13
  111. package/dist/bridge/session-activity.d.ts +93 -0
  112. package/dist/bridge/session-activity.js +139 -0
  113. package/dist/bridge/session-rename.d.ts +48 -0
  114. package/dist/bridge/session-rename.js +190 -0
  115. package/dist/bridge/session-servers.js +2 -2
  116. package/dist/bridge/settings-switch.d.ts +60 -0
  117. package/dist/bridge/settings-switch.js +287 -0
  118. package/dist/bridge/speech-voice.d.ts +55 -0
  119. package/dist/bridge/speech-voice.js +132 -0
  120. package/dist/bridge/speech.d.ts +70 -11
  121. package/dist/bridge/speech.js +169 -41
  122. package/dist/bridge/stalls.d.ts +22 -0
  123. package/dist/bridge/stalls.js +57 -0
  124. package/dist/bridge/sudo.d.ts +209 -0
  125. package/dist/bridge/sudo.js +501 -0
  126. package/dist/bridge/terminal-herdr.js +9 -3
  127. package/dist/bridge/terminal-tmux.d.ts +15 -3
  128. package/dist/bridge/terminal-tmux.js +103 -13
  129. package/dist/bridge/terminal.d.ts +27 -4
  130. package/dist/bridge/terminal.js +8 -1
  131. package/dist/bridge/transcript-claude.d.ts +4 -0
  132. package/dist/bridge/transcript-claude.js +186 -16
  133. package/dist/bridge/transcript-codex.d.ts +0 -2
  134. package/dist/bridge/transcript-codex.js +29 -4
  135. package/dist/bridge/transcript-preview.d.ts +1 -0
  136. package/dist/bridge/transcript-preview.js +24 -4
  137. package/dist/bridge/transcripts.d.ts +15 -2
  138. package/dist/bridge/transcripts.js +47 -16
  139. package/dist/bridge/turn-records.d.ts +85 -0
  140. package/dist/bridge/turn-records.js +143 -0
  141. package/dist/bridge/uploads.d.ts +3 -0
  142. package/dist/bridge/uploads.js +14 -0
  143. package/dist/bridge/usage.d.ts +56 -10
  144. package/dist/bridge/usage.js +190 -45
  145. package/dist/bridge-hook.mjs +27975 -20636
  146. package/dist/cli/claude-unmanaged.d.ts +12 -0
  147. package/dist/cli/claude-unmanaged.js +105 -0
  148. package/dist/cli/schedules.js +2 -1
  149. package/dist/cli/session-start.js +10 -1
  150. package/dist/cli/session-stop.js +9 -1
  151. package/dist/cli-registry.js +31 -6
  152. package/dist/data/task-receipts.d.ts +19 -0
  153. package/dist/data/task-receipts.js +68 -0
  154. package/dist/data/tasks.js +4 -1
  155. package/dist/generated/memory-ui-graph.browser.js +63 -63
  156. package/dist/graph-core/model.js +24 -3
  157. package/dist/graph-core/types.d.ts +4 -1
  158. package/dist/graph-core/types.js +1 -0
  159. package/dist/init/init-preset.js +7 -3
  160. package/dist/init/init-uninstall.js +2 -11
  161. package/dist/init/teardown.d.ts +3 -0
  162. package/dist/init/teardown.js +47 -0
  163. package/dist/link/context.js +21 -9
  164. package/dist/mcp/plugin-mode.js +1 -1
  165. package/dist/memory-ui-graph.runtime.js +63 -63
  166. package/dist/modules/code-package.d.ts +1 -0
  167. package/dist/modules/code-package.js +36 -7
  168. package/dist/modules/registry.js +17 -16
  169. package/dist/profile-store.d.ts +6 -0
  170. package/dist/profile-store.js +25 -1
  171. package/dist/shell/graph/glyphs.js +4 -0
  172. package/dist/shell/graph/graph-view.js +2 -0
  173. package/dist/status.js +7 -1
  174. package/dist/sync/task-claim.js +3 -2
  175. package/dist/task/lifecycle.js +25 -4
  176. package/dist/test-global-setup.js +5 -0
  177. package/dist/tools/dispatch.js +52 -4
  178. package/dist/tools/tasks.js +10 -1
  179. package/package.json +1 -1
  180. package/plugins/opencode/phren-transcript.js +87 -4
  181. package/starter/global/AGENTS.md +4 -0
  182. package/starter/global/skills/conductor/SKILL.md +51 -4
@@ -1,4 +1,5 @@
1
1
  // Installed by Phren Hook and replaced on every update. Copy it under another name to customize.
2
+ import { execFileSync } from "node:child_process";
2
3
  import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
3
4
  import { homedir } from "node:os";
4
5
  import path from "node:path";
@@ -16,6 +17,9 @@ const STOP_REASONS = { stop: "end_turn", "tool-calls": "tool_use", length: "max_
16
17
  const OPENCODE_SESSION = /^ses_[0-9A-Za-z]{1,64}$/;
17
18
  const APPROVAL_POLL_MS = 200;
18
19
  const APPROVAL_DEADLINE_MS = 50_000;
20
+ // An ask relayed from its event blocks nothing: the TUI keeps its own prompt,
21
+ // so the phone's card can wait as long as the ask does.
22
+ const RELAYED_DEADLINE_MS = 30 * 60_000;
19
23
 
20
24
  function storeRoot() {
21
25
  if (PHREN_STORE && !PHREN_STORE.startsWith("__")) return PHREN_STORE;
@@ -116,6 +120,26 @@ function sleep(ms) {
116
120
  return new Promise(resolve => setTimeout(resolve, ms));
117
121
  }
118
122
 
123
+ /** Started by Phren Hook with a port of its own (`opencode --port N`, with
124
+ * PHREN_OPENCODE_PORT=N and a server password in its environment): the Hook
125
+ * lists and answers this process's permission asks over its HTTP API, so no
126
+ * request file is written for them. The port must be on this process's own
127
+ * command line, so an OpenCode started by hand in the same shell keeps the
128
+ * file path. Plugins run in a worker whose `process.argv` is the worker's,
129
+ * so the command line comes from `ps`, once. */
130
+ let served;
131
+ function servedByHook() {
132
+ if (served !== undefined) return served;
133
+ const port = text(process.env.PHREN_OPENCODE_PORT);
134
+ served = false;
135
+ if (!/^\d{1,5}$/.test(port) || !text(process.env.OPENCODE_SERVER_PASSWORD)) return served;
136
+ try {
137
+ const command = execFileSync("ps", ["-ww", "-o", "command=", "-p", String(process.pid)], { encoding: "utf8", timeout: 2_000 });
138
+ served = new RegExp(`(?:^|\\s)--port(?:\\s+|=)${port}(?:\\s|$)`).test(command.trim());
139
+ } catch {}
140
+ return served;
141
+ }
142
+
119
143
  function setStatus(output, status) {
120
144
  if (output && typeof output === "object") output.status = status;
121
145
  }
@@ -229,7 +253,9 @@ function writePidBinding(sessionID) {
229
253
  * whose terminal does not watch its agents (tmux); Herdr has its own. */
230
254
  const statusFile = () => path.join(storeRoot(), ".runtime", "sessions", `opencode-status-${process.pid}.json`);
231
255
 
232
- export const PhrenTranscriptPlugin = async () => {
256
+ export const PhrenTranscriptPlugin = async input => {
257
+ // The process's own API, bound to its in-process server (no port needed).
258
+ const client = input?.client;
233
259
  const sessions = new Map();
234
260
  // Subagent sessions run inside the same process; the pane shows their parent.
235
261
  const children = new Set();
@@ -239,14 +265,22 @@ export const PhrenTranscriptPlugin = async () => {
239
265
  let recordedStatus;
240
266
  // Permission asks still open, by id: while any is, the process is blocked.
241
267
  const asking = new Set();
268
+ // The session's last turn: when it went busy, and when it went idle after
269
+ // that. Dispatch returns read these as the turn's start and Stop.
270
+ let turn = {};
242
271
  const recordStatus = (status, sessionID) => {
243
272
  // A fan-out worker runs headless, in no pane.
244
273
  if (process.env.PHREN_FANOUT_JOB) return;
245
274
  const next = asking.size && status === "working" ? "blocked" : status;
246
275
  if (next === recordedStatus) return;
247
276
  try {
277
+ const at = new Date().toISOString();
278
+ if (sessionID && turn.session !== sessionID) turn = { session: sessionID };
279
+ if (next !== "idle" && (recordedStatus === undefined || recordedStatus === "idle")) { turn.busyAt = at; delete turn.idleAt; }
280
+ else if (next === "idle" && turn.busyAt) turn.idleAt = at;
248
281
  mkdirSync(path.dirname(statusFile()), { recursive: true });
249
- writeJsonAtomic(statusFile(), { status: next, ...(sessionID ? { session: sessionID } : {}), at: new Date().toISOString() });
282
+ writeJsonAtomic(statusFile(), { status: next, ...(sessionID ? { session: sessionID } : {}), at,
283
+ ...(turn.session === sessionID && turn.busyAt ? { busyAt: turn.busyAt } : {}), ...(turn.session === sessionID && turn.idleAt ? { idleAt: turn.idleAt } : {}) });
250
284
  recordedStatus = next;
251
285
  } catch {}
252
286
  };
@@ -254,6 +288,51 @@ export const PhrenTranscriptPlugin = async () => {
254
288
  const timers = new Map();
255
289
  const written = new Map();
256
290
  const pendingApprovals = new Set();
291
+ // Asks the permission.ask hook took (OpenCode before 1.18), and asks relayed
292
+ // from their event, by id; `done` once the terminal answered one.
293
+ const hookAsks = new Set();
294
+ const relayed = new Map();
295
+
296
+ /** OpenCode 1.18 never calls the permission.ask hook: its TUI draws the ask
297
+ * from the `permission.asked` event. For an OpenCode started by hand the ask
298
+ * goes to the phone through the same request file, and the phone's answer
299
+ * is replied through this process's own API. Whichever answers first wins;
300
+ * an answer in the terminal (`permission.replied`) withdraws the card. */
301
+ const relayAsk = async ask => {
302
+ const id = text(ask?.id), sessionID = text(ask?.sessionID);
303
+ if (process.env.PHREN_FANOUT_JOB || !id || hookAsks.has(id) || relayed.has(id) || !OPENCODE_SESSION.test(sessionID)
304
+ || typeof client?.postSessionIdPermissionsPermissionId !== "function" || servedByHook() || pendingApprovals.has(sessionID)) return;
305
+ const shown = { type: text(ask.permission) || text(ask.type), pattern: Array.isArray(ask.patterns) ? ask.patterns : ask.pattern,
306
+ metadata: ask.metadata, title: ask.title };
307
+ const state = { done: false };
308
+ relayed.set(id, state); pendingApprovals.add(sessionID);
309
+ const { request, answer } = approvalPaths(sessionID);
310
+ try {
311
+ mkdirSync(approvalDirectory(), { recursive: true });
312
+ removeFile(answer);
313
+ const created = Date.now();
314
+ writeJsonAtomic(request, { id, sessionID, type: shown.type || "action",
315
+ title: text(shown.title) || `Allow ${shown.type || "action"}?`, message: permissionMessage(shown),
316
+ createdAt: new Date(created).toISOString(), expiresAt: new Date(created + RELAYED_DEADLINE_MS).toISOString() });
317
+ let decision;
318
+ while (!state.done && Date.now() < created + RELAYED_DEADLINE_MS) {
319
+ await sleep(APPROVAL_POLL_MS);
320
+ try {
321
+ const info = lstatSync(answer);
322
+ if (!info.isFile() || info.size > 65_536) continue;
323
+ const value = JSON.parse(readFileSync(answer, "utf8"));
324
+ if (value && value.id === id && (value.decision === "approve" || value.decision === "deny")) { decision = value.decision; break; }
325
+ } catch {}
326
+ }
327
+ if (decision && !state.done) {
328
+ await client.postSessionIdPermissionsPermissionId({ path: { id: sessionID, permissionID: id },
329
+ body: { response: decision === "approve" ? "once" : "reject" } });
330
+ }
331
+ } catch {} finally {
332
+ removeFile(answer); removeFile(request);
333
+ pendingApprovals.delete(sessionID); relayed.delete(id);
334
+ }
335
+ };
257
336
 
258
337
  const sessionState = sessionID => {
259
338
  let state = sessions.get(sessionID);
@@ -346,10 +425,10 @@ export const PhrenTranscriptPlugin = async () => {
346
425
  // The ask blocks the process until it is answered: here from the
347
426
  // phone, or in the terminal (permission.replied below).
348
427
  const askId = text(input?.id);
349
- if (askId) { asking.add(askId); recordStatus("blocked", text(input?.sessionID)); }
428
+ if (askId) { hookAsks.add(askId); asking.add(askId); recordStatus("blocked", text(input?.sessionID)); }
350
429
  try {
351
430
  const sessionID = text(input?.sessionID), id = text(input?.id);
352
- if (!OPENCODE_SESSION.test(sessionID) || !id) { setStatus(output, "ask"); return; }
431
+ if (!OPENCODE_SESSION.test(sessionID) || !id || servedByHook()) { setStatus(output, "ask"); return; }
353
432
  // A second request for this session belongs in the terminal until
354
433
  // the existing phone request has finished.
355
434
  if (pendingApprovals.has(sessionID)) { setStatus(output, "ask"); return; }
@@ -382,6 +461,7 @@ export const PhrenTranscriptPlugin = async () => {
382
461
  if (pendingSession) pendingApprovals.delete(pendingSession);
383
462
  // Answered from the phone: back to work. Otherwise the terminal asks.
384
463
  if (askId && (decision === "approve" || decision === "deny")) { asking.delete(askId); recordStatus("working", pendingSession); }
464
+ if (askId) hookAsks.delete(askId);
385
465
  }
386
466
  },
387
467
  event: async ({ event }) => {
@@ -394,9 +474,12 @@ export const PhrenTranscriptPlugin = async () => {
394
474
  if (event?.type === "permission.updated" || event?.type === "permission.asked") {
395
475
  const id = permissionId(properties);
396
476
  if (id) { asking.add(id); recordStatus("blocked", text(sessionID)); }
477
+ if (event.type === "permission.asked") void relayAsk(properties).catch(() => {});
397
478
  } else if (event?.type === "permission.replied") {
398
479
  const id = permissionId(properties);
399
480
  if (id) asking.delete(id); else asking.clear();
481
+ const relay = id && relayed.get(id);
482
+ if (relay) relay.done = true;
400
483
  recordStatus("working", text(sessionID));
401
484
  }
402
485
  if (!OPENCODE_SESSION.test(text(sessionID))) return;
@@ -30,6 +30,10 @@ Worth saving: decisions and why, pitfalls with the fix, patterns that worked, me
30
30
 
31
31
  Every agent follows these rules, and tells phren about non-obvious findings before handing work back.
32
32
 
33
+ ## sudo
34
+
35
+ With no terminal, run `sudo -A <command>` (or `phren sudo <command>`): the owner types the password on their phone. Plain `sudo` fails there. Never ask for, store or echo the password.
36
+
33
37
  ## Where things are
34
38
 
35
39
  `~/.phren` (or `$PHREN_PATH`) is a git repo: `global/` for everything-everywhere, `<project>/` for each project's AGENTS.md, findings, tasks and skills, `profiles/` and `machines.yaml` for which projects belong on which machine. `phren doctor` explains anything that is off. If the MCP server is not running, phren still injects context through hooks; the CLI (`phren search`, `phren add-finding`) does the rest.
@@ -27,10 +27,19 @@ Your tools, use these instead of exploring the CLI or the Hook's files:
27
27
  but have no Hook link here: say they were not checked, never that nothing is
28
28
  running there.
29
29
  - `hand_off`: send a prompt to one of those sessions.
30
+ - `account_usage` (CLI `phren dispatch usage`): every computer's agent usage
31
+ merged by account (each Claude login, Codex, OpenCode Go and the rest): percent
32
+ left on each window, when it resets, whether the numbers are fresh, and the
33
+ computers where it is signed in. In core use
34
+ `phren_admin(action: "account_usage")`.
35
+ - `hand_off`: send a prompt to one of those sessions. A busy session queues it
36
+ durably in its Hook. Keep its `deliveryId`; `queued` means waiting, `delivered`
37
+ means confirmed. Check with `hand_off(target|session, computer?, deliveryId,
38
+ status:true)` and no text. Never resend with a new id because it is busy.
30
39
  - `dispatch`: start a new worker on a computer (or `anywhere`).
31
40
  - `dispatch_returns` (CLI `phren dispatch returns`): what your workers sent
32
41
  back since you last asked: done with the final reply, needs-you with the
33
- question, failed with the error (a usage limit), blocked, or gone. Reading them marks them read. In core use
42
+ question, stalled with an unchanged screen and transcript, failed with the error (a usage limit), blocked, or gone. Reading them marks them read. In core use
34
43
  `phren_admin(action: "dispatch_returns")`.
35
44
  - `phren dispatch status`: receipts of what you dispatched.
36
45
  - `get_tasks`, `get_project_summary`, `search_knowledge`: the store's memory.
@@ -76,6 +85,9 @@ file ownership; give each remote lead a base revision, acceptance checks, local
76
85
  fanout limit, report time and integration instructions. Every brief repeats the
77
86
  owner's repository constraints, including any prohibition on commits, pushes,
78
87
  branches or particular tests. Dispatch never expands the owner's authorization.
88
+ A worker that needs root runs `sudo -A <command>`: its launch sets
89
+ `SUDO_ASKPASS`, and the owner approves the exact command and types the
90
+ password on the phone. Plain `sudo` fails without a terminal.
79
91
 
80
92
  You are the one conductor for this computer and every computer linked with
81
93
  it; a second conductor in the group is refused at launch. Conductors on
@@ -100,14 +112,40 @@ run` or `codex exec`, a launch script, nohup) has no manifest, so the phone and
100
112
  you cannot see, resume or review it. Workers that exist only as processes do
101
113
  not count as dispatched.
102
114
 
115
+ Check `account_usage` before you dispatch, once per batch. The one hard rule:
116
+ never dispatch to an account that is `exhausted` (a window at 100%, or
117
+ refusing requests), until its `availableIn` passes. Low quota is information,
118
+ not a reason to steer away: `nearLimit` (under 20% left) is still usable, and
119
+ the owner often wants quota used up before it resets, so an account with quota
120
+ left that resets soon is a good pick; use it before it resets. For Claude, pass
121
+ the `account` id the row's `computers` list gives for the computer you pick. A
122
+ `stale` row's numbers may be out of date, and a window marked `reset` has
123
+ rolled over with no new number yet: say so rather than quoting them. Name the
124
+ choice in the dispatch line, such as "Desk has the parser checks on Codex,
125
+ using its last 15% before the week resets tomorrow." When every account is
126
+ exhausted, tell the owner before dispatching. The owner's explicit choice of
127
+ harness or account always wins. Usage on `unreachable` and `notLinked`
128
+ computers is unknown, not zero.
129
+
103
130
  Prefer handing work to a session that already owns the project and is idle or
104
131
  doing related work; call `hand_off` in full or `phren_admin(action: "hand_off",
105
132
  computer?, target|session, text)` in core. Otherwise dispatch a new worker.
106
133
  Write one short line either way. Call `dispatch` in full or
107
- `phren_admin(action: "dispatch", computer, project, harness, model?, prompt, label)`
134
+ `phren_admin(action: "dispatch", computer, project, harness, model?, effort?, permissionMode?, prompt, label)`
108
135
  in core. The CLI equivalent is `phren dispatch <computer|anywhere> <project>
109
- --harness <harness> --label <label> --prompt <brief> [--model <model>]`.
110
- `anywhere` chooses the connected computer with the fewest working agents. Place
136
+ --harness <harness> --label <label> --prompt <brief> [--model <model>] [--effort <effort>]
137
+ [--permission-mode supervised|auto-edits|auto|full-access]`. `permissionMode` sets how the
138
+ worker starts (Claude and Codex only).
139
+ For release work (merge, publish, deploy, app-store, github-admin), read the
140
+ owner's release authority policy first with `authority` in full or
141
+ `phren_admin(action: "authority", project)` in core (CLI: `phren authority show
142
+ <project>`), quote its `line` in the brief, and list the actions in
143
+ `releaseActions`. An ask-first action is refused until the owner confirms it:
144
+ ask them, and never confirm or change the policy yourself. The policy only
145
+ restricts; when a worker's own harness still refuses release work, only the
146
+ owner's own harness settings can allow it.
147
+ `anywhere` chooses the connected computer with the fewest working agents, and
148
+ skips one whose account for that harness is exhausted. Place
111
149
  briefs sequentially, respecting busy/rate-limit responses. Keep their dispatch
112
150
  IDs. Do not send local filesystem paths as remote project names.
113
151
 
@@ -120,6 +158,11 @@ also call it whenever you want the current state; do not poll it in a loop, and
120
158
  do not read remote transcripts by hand to learn whether a worker finished. Tell
121
159
  the owner a return time as an expectation, not a promise.
122
160
 
161
+ A return with an `approval` is a permission request a worker is waiting on.
162
+ Answer it with `dispatch_approve` when it is plainly what the brief asked for;
163
+ deny when unsure and ask the owner. Standing grants already answer `dispatch`
164
+ and `hand_off` requests they cover.
165
+
123
166
  For a `needs-you` return, surface the worker's question in the owner's chat
124
167
  with its choices as the worker wrote them; do not rewrite or answer it for the
125
168
  owner unless the owner already decided. Send the answer back with `hand_off`
@@ -129,6 +172,10 @@ permission prompt: say so and point the owner to the phone or the terminal. A
129
172
  owner before giving its work to another agent. A `done` reply is the worker's
130
173
  own account; check its evidence before saying tests passed or work merged.
131
174
 
175
+ A `stalled` return or `live_sessions` row with `stalled:true` means both the
176
+ screen and transcript have stopped changing while working. Check it and report
177
+ what is known; do not launch a duplicate or interrupt it just because of the flag.
178
+
132
179
  An uncertain delivery is never retried automatically. Inspect its known target
133
180
  or status before deciding with the owner whether a replacement is needed. Keep
134
181
  unavailable workers visible instead of giving their work to another agent