@phren/cli 0.3.45 → 0.3.47

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 (75) hide show
  1. package/dist/bridge/agent-hook-asks.d.ts +34 -0
  2. package/dist/bridge/agent-hook-asks.js +72 -0
  3. package/dist/bridge/agent-hook-callback.d.ts +22 -0
  4. package/dist/bridge/agent-hook-callback.js +114 -0
  5. package/dist/bridge/agent-hooks.d.ts +7 -74
  6. package/dist/bridge/agent-hooks.js +22 -186
  7. package/dist/bridge/claude-question-dialog.d.ts +6 -0
  8. package/dist/bridge/claude-question-dialog.js +29 -7
  9. package/dist/bridge/codex-app-server.d.ts +5 -0
  10. package/dist/bridge/codex-app-server.js +15 -0
  11. package/dist/bridge/codex-auth-refresh.d.ts +7 -0
  12. package/dist/bridge/codex-auth-refresh.js +22 -0
  13. package/dist/bridge/dispatch-command.js +7 -1
  14. package/dist/bridge/file-write.js +3 -1
  15. package/dist/bridge/git-host-auth.d.ts +6 -0
  16. package/dist/bridge/git-host-auth.js +45 -0
  17. package/dist/bridge/git-publish.d.ts +1 -1
  18. package/dist/bridge/git-publish.js +75 -8
  19. package/dist/bridge/git-review.js +23 -2
  20. package/dist/bridge/git-write-policy.d.ts +13 -0
  21. package/dist/bridge/git-write-policy.js +39 -0
  22. package/dist/bridge/git.d.ts +5 -1
  23. package/dist/bridge/git.js +103 -8
  24. package/dist/bridge/health.d.ts +1 -0
  25. package/dist/bridge/health.js +8 -5
  26. package/dist/bridge/lookup-cache.d.ts +17 -0
  27. package/dist/bridge/lookup-cache.js +70 -0
  28. package/dist/bridge/memory-store.js +40 -14
  29. package/dist/bridge/pair.js +4 -0
  30. package/dist/bridge/peers.js +36 -0
  31. package/dist/bridge/projects.d.ts +14 -0
  32. package/dist/bridge/projects.js +48 -1
  33. package/dist/bridge/prompt-deliveries.d.ts +38 -3
  34. package/dist/bridge/prompt-deliveries.js +196 -36
  35. package/dist/bridge/schedule-format.d.ts +7 -0
  36. package/dist/bridge/schedule-format.js +73 -2
  37. package/dist/bridge/schedule-problems.js +4 -0
  38. package/dist/bridge/schedule-update.d.ts +6 -0
  39. package/dist/bridge/schedule-update.js +63 -0
  40. package/dist/bridge/schedules.js +16 -4
  41. package/dist/bridge/scoped-gateway.d.ts +1 -0
  42. package/dist/bridge/scoped-gateway.js +10 -1
  43. package/dist/bridge/server-launch.js +6 -2
  44. package/dist/bridge/server-pane-routes.d.ts +4 -2
  45. package/dist/bridge/server-pane-routes.js +8 -2
  46. package/dist/bridge/server-routes.js +14 -4
  47. package/dist/bridge/session-servers.js +3 -0
  48. package/dist/bridge/{codex-thread-origin.d.ts → thread-origin.d.ts} +8 -0
  49. package/dist/bridge/{codex-thread-origin.js → thread-origin.js} +24 -6
  50. package/dist/bridge/usage.d.ts +4 -0
  51. package/dist/bridge/usage.js +22 -8
  52. package/dist/bridge-hook.mjs +1420 -553
  53. package/dist/cli/actions.js +4 -0
  54. package/dist/cli/namespaces-tasks.js +19 -5
  55. package/dist/cli/ops.d.ts +1 -1
  56. package/dist/cli/ops.js +2 -2
  57. package/dist/cli/schedules.js +16 -9
  58. package/dist/content/summarize.js +46 -6
  59. package/dist/content/validate.d.ts +3 -1
  60. package/dist/content/validate.js +33 -4
  61. package/dist/data/access.d.ts +8 -1
  62. package/dist/data/access.js +27 -9
  63. package/dist/data/notes.d.ts +2 -0
  64. package/dist/data/notes.js +2 -1
  65. package/dist/entrypoint.js +2 -1
  66. package/dist/generated/memory-ui-graph.browser.js +1 -1
  67. package/dist/governance/locks.js +17 -1
  68. package/dist/governance/policy.js +37 -23
  69. package/dist/mcp/profile.js +23 -4
  70. package/dist/memory-ui-graph.runtime.js +1 -1
  71. package/dist/modules/registry.js +2 -2
  72. package/dist/sync/conflict-resolve.d.ts +1 -1
  73. package/dist/sync/conflict-resolve.js +91 -8
  74. package/dist/task/lifecycle.js +5 -3
  75. package/package.json +1 -1
@@ -2,6 +2,11 @@ import { type Json } from "./protocol.js";
2
2
  /** Nested reads share one deadline. Abort and reap outstanding Git processes on
3
3
  * expiry or failure; never leave a timed-out request running its command chain. */
4
4
  export declare function withGitReadDeadline<T>(read: () => Promise<T>): Promise<T>;
5
+ /** Run provider work outside a completed route's local Git budget. Each local
6
+ * Git call retains its own timeout, while forge requests use provider limits. */
7
+ export declare function withoutGitReadDeadline<T>(read: () => Promise<T>): Promise<T>;
8
+ /** A background lookup owns its deadline even after the requesting route ends. */
9
+ export declare function withIndependentGitReadDeadline<T>(read: () => Promise<T>): Promise<T>;
5
10
  /** Bind Git to the selected checkout, even when Hook inherited another Git
6
11
  * process's repository/index environment. Keep user config (including excludes). */
7
12
  export declare function checkoutGitEnv(): NodeJS.ProcessEnv;
@@ -17,13 +22,22 @@ export declare function repositoryDiff(cwd: string, touched?: unknown[], allowed
17
22
  * worktree's through its `.git` file), found without spawning git. */
18
23
  export declare function headFile(cwd: string): Promise<string | undefined>;
19
24
  export declare function repositoryBranch(cwd: string): Promise<string | undefined>;
25
+ /** `unverified`: the owner could not be checked against the live socket table, so no session may be handed this server. */
20
26
  export interface LocalServer {
21
27
  name: string;
22
28
  port: number;
23
29
  origin: string;
24
30
  process?: string;
25
31
  pid?: number;
32
+ unverified?: true;
26
33
  }
34
+ /** The web servers listening here. A cached listener is checked against the live socket table
35
+ * before it is returned: if the process that held its address and port no longer listens there
36
+ * (it stopped, or closed the socket and kept running), the port may already belong to another
37
+ * session's server, and attributing it to the old owner would open that session's preview on the
38
+ * wrong app. Such a result drops the entry and refreshes the cache. */
27
39
  export declare function webServers(): Promise<LocalServer[]>;
40
+ /** The key `addListener` files a server under: its host with the port always spelled out (a URL's host drops the default one). */
41
+ export declare function listenerKey(server: Pick<LocalServer, "origin" | "port">): string;
28
42
  /** Launch only in real local directories under home or a locator candidate. */
29
43
  export declare function launchDirectory(raw: unknown, activity?: Json[], located?: Iterable<string>): Promise<string>;
@@ -10,6 +10,7 @@ import path from "node:path";
10
10
  import { phrenStoreRoot } from "./transcripts.js";
11
11
  import { locateProject } from "./locate.js";
12
12
  import { BridgeError } from "./protocol.js";
13
+ import { LookupCache } from "./lookup-cache.js";
13
14
  import { countGit } from "./metrics.js";
14
15
  const exec = promisify(execFile);
15
16
  const gitReadBudget = new AsyncLocalStorage();
@@ -44,6 +45,15 @@ export async function withGitReadDeadline(read) {
44
45
  await Promise.allSettled([...budget.pending]);
45
46
  }
46
47
  }
48
+ /** Run provider work outside a completed route's local Git budget. Each local
49
+ * Git call retains its own timeout, while forge requests use provider limits. */
50
+ export function withoutGitReadDeadline(read) {
51
+ return gitReadBudget.exit(read);
52
+ }
53
+ /** A background lookup owns its deadline even after the requesting route ends. */
54
+ export function withIndependentGitReadDeadline(read) {
55
+ return gitReadBudget.exit(() => withGitReadDeadline(read));
56
+ }
47
57
  /** Bind Git to the selected checkout, even when Hook inherited another Git
48
58
  * process's repository/index environment. Keep user config (including excludes). */
49
59
  export function checkoutGitEnv() {
@@ -331,8 +341,10 @@ function probe(port, host) {
331
341
  let settled = false;
332
342
  const finish = (value) => { if (!settled) {
333
343
  settled = true;
344
+ clearTimeout(deadline);
334
345
  resolve(value);
335
346
  } };
347
+ const deadline = setTimeout(() => { finish(null); req.destroy(); }, 1200);
336
348
  const req = request({ hostname: host, port, path: "/", method: "GET", timeout: 1200, headers: { Host: `localhost:${port}` } }, res => {
337
349
  let body = "";
338
350
  res.on("data", data => { body += data.toString(); if (body.length > 32_768)
@@ -391,7 +403,35 @@ async function listenersFromSs(ports) {
391
403
  addListener(ports, local.slice(0, split), Number(local.slice(split + 1)), owner?.[1], owner ? Number(owner[2]) : undefined);
392
404
  }
393
405
  }
406
+ const serversCache = new LookupCache(10_000, 300_000, 1, () => true, 20_000);
407
+ /** When each cached listing's socket-table read began: the listing is only as fresh as that, however long probing took. */
408
+ const scanStarted = new WeakMap();
409
+ /** A cached listener is trusted this long after its scan; the socket table is read again after that. */
410
+ const LISTENER_TRUST_MS = 1_000;
411
+ /** The web servers listening here. A cached listener is checked against the live socket table
412
+ * before it is returned: if the process that held its address and port no longer listens there
413
+ * (it stopped, or closed the socket and kept running), the port may already belong to another
414
+ * session's server, and attributing it to the old owner would open that session's preview on the
415
+ * wrong app. Such a result drops the entry and refreshes the cache. */
394
416
  export async function webServers() {
417
+ const servers = await serversCache.get("listeners", scanWebServers);
418
+ if (!servers.some(server => server.pid !== undefined) || Date.now() - (scanStarted.get(servers) ?? 0) < LISTENER_TRUST_MS)
419
+ return servers;
420
+ const live = await readListeners().catch(() => undefined);
421
+ // The table could not be read (ss timed out, no lsof): ownership cannot be verified, so none is claimed.
422
+ if (!live)
423
+ return servers.map(({ pid: _pid, ...server }) => ({ ...server, unverified: true }));
424
+ const kept = servers.filter(server => server.pid === undefined || live.get(listenerKey(server))?.pid === server.pid);
425
+ if (kept.length !== servers.length)
426
+ serversCache.invalidate(() => true);
427
+ return kept;
428
+ }
429
+ /** The key `addListener` files a server under: its host with the port always spelled out (a URL's host drops the default one). */
430
+ export function listenerKey(server) {
431
+ return `${server.origin.includes("[::1]") ? "[::1]" : "127.0.0.1"}:${server.port}`;
432
+ }
433
+ /** The listening sockets (address:port to owner), without probing any of them. */
434
+ async function readListeners() {
395
435
  const ports = new Map();
396
436
  // Prefer ss on Linux and lsof elsewhere; try the other if the first is missing.
397
437
  const readers = process.platform === "linux" ? [listenersFromSs, listenersFromLsof] : [listenersFromLsof, listenersFromSs];
@@ -408,6 +448,11 @@ export async function webServers() {
408
448
  }
409
449
  if (lastError && ports.size === 0)
410
450
  throw new BridgeError(503, "No socket listing tool found: install lsof (or iproute2's ss on Linux).");
451
+ return ports;
452
+ }
453
+ async function scanWebServers() {
454
+ const started = Date.now();
455
+ const ports = await readListeners();
411
456
  // Probe well-known ports first so a browser's dozens of ephemeral listeners
412
457
  // cannot push a dev server on :3000 past the cap.
413
458
  const candidates = [...ports.values()]
@@ -421,7 +466,9 @@ export async function webServers() {
421
466
  found.push({ ...server, name });
422
467
  }));
423
468
  }
424
- return found.sort((a, b) => a.port - b.port);
469
+ const listing = found.sort((a, b) => a.port - b.port);
470
+ scanStarted.set(listing, started);
471
+ return listing;
425
472
  }
426
473
  /** Launch only in real local directories under home or a locator candidate. */
427
474
  export async function launchDirectory(raw, activity = [], located = []) {
@@ -4,6 +4,11 @@ export type DeliveryOutcome = "delivered" | "pending";
4
4
  * pane and held by the agent until its turn ends. `failed` carries a reason
5
5
  * and may still turn `delivered` if the agent takes it late. */
6
6
  export type DeliveryState = "queued" | "delivered" | "failed";
7
+ /** A transcript row carrying a message's words: its byte offset, and whether the agent fires UserPromptSubmit for it (a user row does; a mid-turn queue removal does not). */
8
+ export interface TranscriptEntry {
9
+ offset: number;
10
+ hook: boolean;
11
+ }
7
12
  export type TrackedState = DeliveryState | "unknown";
8
13
  export interface DeliveryStatus {
9
14
  state: TrackedState;
@@ -36,12 +41,18 @@ export declare class PromptDeliveries {
36
41
  private records;
37
42
  private waiters;
38
43
  private writing;
44
+ /** Panes (server, pane, agent) that sent a UserPromptSubmit or Stop since the Hook started. */
45
+ private hookPanes;
46
+ private paneKey;
47
+ private static open;
48
+ /** Open, or failed with its own hook's claim still waiting for its row (a late delivery). */
49
+ private static claimable;
39
50
  constructor(file?: string | undefined, now?: () => number, landed?: (record: {
40
51
  source: Provider;
41
52
  session: string;
42
53
  hash: string;
43
54
  at: number;
44
- }) => Promise<boolean>);
55
+ }) => Promise<TranscriptEntry[]>);
45
56
  private samePane;
46
57
  private byId;
47
58
  private prune;
@@ -84,8 +95,23 @@ export declare class PromptDeliveries {
84
95
  /** Conversation `target` just submitted `prompt`. Its own record wins, then
85
96
  * the oldest open one in the same pane: the agent kept the text across a
86
97
  * conversation change, and the conversation now in the pane is where it
87
- * went. A prompt nothing matches was typed locally. Never refused. */
88
- submitted(target: Target, prompt: string): void;
98
+ * went. A prompt nothing matches was typed locally. Never refused.
99
+ * For Claude the transcript is consulted first and the submission claims
100
+ * the earliest unclaimed user row with these words, through the same
101
+ * `settle` and the same table of claimed entries the idle check uses: a
102
+ * callback for a row already claimed (the idle check settled it, the hook
103
+ * came late) settles nothing more. */
104
+ submitted(target: Target, prompt: string): Promise<void>;
105
+ /** Marks `record` delivered, with the transcript entry that settled it when known. */
106
+ private settle;
107
+ /** Whether the transcript shows the agent took `record`'s message, claiming the entry it settled with.
108
+ * An entry settles one message: the table of records' `entry` offsets (per conversation) is the only
109
+ * state, so neither this path nor the hook's can settle two messages with one turn. A user row is a
110
+ * turn start whose UserPromptSubmit hook settles the message itself, so while the agent works only a
111
+ * mid-turn queue removal (no hook fires for it) settles from the transcript; once the agent is idle
112
+ * (`working` false) a user row settles too, for a hook that never came. Of several identical open
113
+ * messages the oldest take the entries. `pass` carries the entries still unclaimed within one observe. */
114
+ private taken;
89
115
  /** A turn in `target`'s pane ended: the agent now takes held input or never will. */
90
116
  stopped(target: Target): void;
91
117
  /** Called on the Hook's activity tick with a server's panes. A message
@@ -94,6 +120,15 @@ export declare class PromptDeliveries {
94
120
  * transcript shows it after all). */
95
121
  observe(server: string, panes: Json[]): Promise<void>;
96
122
  }
123
+ /** The byte offsets of the user rows with these words that reached the conversation's transcript
124
+ * after the message was typed: the agent took it without its hook saying so
125
+ * (a mid-turn steer). Reads at most the last 512 KiB. */
126
+ /** The byte offsets (in the file, `start` being the buffer's own offset) of the rows in `buffer`
127
+ * whose user text has `record`'s words, newest first. One offset per row. */
128
+ export declare function matchingOffsets(buffer: Buffer, start: number, record: {
129
+ hash: string;
130
+ at: number;
131
+ }): TranscriptEntry[];
97
132
  /** A transcript row's user-typed text: Claude's user rows, Codex's
98
133
  * user_message events and user response items. */
99
134
  export declare function userTexts(row: Json): string[];
@@ -11,6 +11,10 @@ export const DELIVERY_RETENTION_MS = 24 * 3_600_000;
11
11
  * idle this long without taking it has dropped it. */
12
12
  export const DELIVERY_GIVE_UP_MS = 30_000;
13
13
  const MAX_RECORDS = 512;
14
+ /** How often a message still held by a working agent is looked for in its transcript. */
15
+ const LANDED_CHECK_MS = 3_000;
16
+ /** The transcript scan starts this long before a message was typed (clock skew), so entries up to this far back may belong to an earlier message. */
17
+ const ENTRY_SLACK_MS = 5_000;
14
18
  /** What the agent hands its UserPromptSubmit hook is the terminal's pasted
15
19
  * form of what Phren typed; compare the words, not the wrapping. Claude Code
16
20
  * also takes each attached picture's path line out of the text and puts an
@@ -27,6 +31,8 @@ const recordSchema = z.object({
27
31
  server: z.string().min(1).max(200), pane: z.string().min(1).max(200), source: provider, session: z.string().min(1).max(200),
28
32
  terminal: z.string().max(200).optional(), state: z.enum(["typed", "queued", "delivered", "failed"]),
29
33
  reason: z.string().max(500).optional(), at: z.number(), settledAt: z.number().optional(), stoppedAt: z.number().optional(),
34
+ /** The transcript entry (byte offset) that settled it, so no other message claims the same one. */
35
+ entry: z.number().optional(),
30
36
  }).strict();
31
37
  /** One message per record, bound to the pane it was typed into (server, pane,
32
38
  * agent kind), not to the conversation: a Codex thread or a Claude /clear can
@@ -41,7 +47,13 @@ export class PromptDeliveries {
41
47
  records = [];
42
48
  waiters = new Map();
43
49
  writing = Promise.resolve();
44
- constructor(file, now = Date.now, landed = transcriptHas) {
50
+ /** Panes (server, pane, agent) that sent a UserPromptSubmit or Stop since the Hook started. */
51
+ hookPanes = new Set();
52
+ paneKey(target) { return [target.server, target.pane, target.source].join("|"); }
53
+ static open(record) { return record.state === "typed" || record.state === "queued"; }
54
+ /** Open, or failed with its own hook's claim still waiting for its row (a late delivery). */
55
+ static claimable(record) { return PromptDeliveries.open(record) || (record.state === "failed" && !!record.hookClaim); }
56
+ constructor(file, now = Date.now, landed = transcriptEntries) {
45
57
  this.file = file;
46
58
  this.now = now;
47
59
  this.landed = landed;
@@ -72,7 +84,8 @@ export class PromptDeliveries {
72
84
  save() {
73
85
  if (!this.file)
74
86
  return;
75
- const rows = this.records.filter(record => record.id).map(({ idleSince: _, ...row }) => row);
87
+ // A record without a phone id is kept once it claimed a transcript row, so after a restart that row is not offered to another message.
88
+ const rows = this.records.filter(record => record.id || record.entry !== undefined).map(({ idleSince: _, checkedAt: __, hookClaim: ___, seenRow: ____, ...row }) => row);
76
89
  const file = this.file;
77
90
  this.writing = this.writing.then(() => atomicInPrivateDir(file, { records: rows })).catch(() => undefined);
78
91
  }
@@ -206,26 +219,133 @@ export class PromptDeliveries {
206
219
  /** Conversation `target` just submitted `prompt`. Its own record wins, then
207
220
  * the oldest open one in the same pane: the agent kept the text across a
208
221
  * conversation change, and the conversation now in the pane is where it
209
- * went. A prompt nothing matches was typed locally. Never refused. */
210
- submitted(target, prompt) {
222
+ * went. A prompt nothing matches was typed locally. Never refused.
223
+ * For Claude the transcript is consulted first and the submission claims
224
+ * the earliest unclaimed user row with these words, through the same
225
+ * `settle` and the same table of claimed entries the idle check uses: a
226
+ * callback for a row already claimed (the idle check settled it, the hook
227
+ * came late) settles nothing more. */
228
+ async submitted(target, prompt) {
211
229
  const hash = promptHash(prompt);
212
- const open = this.records.filter(record => record.hash === hash && this.samePane(record, target) && record.state !== "delivered");
213
- const record = open.find(entry => entry.session === target.session) ?? open[0];
230
+ this.hookPanes.add(this.paneKey(target));
231
+ const pick = () => {
232
+ const open = this.records.filter(record => record.hash === hash && this.samePane(record, target) && record.state !== "delivered");
233
+ return open.find(entry => entry.session === target.session) ?? open[0];
234
+ };
235
+ let record = pick();
214
236
  if (!record)
215
237
  return;
238
+ let entry;
239
+ if (target.source === "claude") {
240
+ // A hook settles a message only by claiming a row for it: rows all claimed by earlier messages is a
241
+ // callback for a turn already accounted for. No row yet (not written or not readable, or a transcript
242
+ // that cannot be read) settles nothing now: the claim waits on the record for its row to appear.
243
+ let rows;
244
+ try {
245
+ rows = (await this.landed({ source: target.source, session: target.session, hash, at: record.at })).filter(row => row.hook);
246
+ }
247
+ catch {
248
+ rows = undefined;
249
+ }
250
+ record = pick();
251
+ if (!record)
252
+ return;
253
+ // Claims are per conversation: another conversation's rows can sit at the same byte offset.
254
+ const claimed = new Set(this.records.filter(other => other.hash === hash && this.samePane(other, target) && other.session === target.session && other.entry !== undefined).map(other => other.entry));
255
+ // A transcript that cannot be read settles on the hook's word, unless a message with these words already
256
+ // claimed a row in this conversation: the callback may be that message's, late, so it waits for a row.
257
+ if (!rows && !claimed.size) {
258
+ this.settle(record, undefined, target.session);
259
+ this.save();
260
+ return;
261
+ }
262
+ // The claim is looked for in the conversation that made it (it may have replaced the one the message was typed for).
263
+ if (!rows?.length) {
264
+ record.hookClaim = true;
265
+ record.session = target.session;
266
+ return;
267
+ }
268
+ const free = rows.filter(row => !claimed.has(row.offset)).sort((a, b) => a.offset - b.offset)[0];
269
+ if (!free)
270
+ return;
271
+ entry = free.offset;
272
+ }
273
+ this.settle(record, entry, target.session);
274
+ this.save();
275
+ }
276
+ /** Marks `record` delivered, with the transcript entry that settled it when known. */
277
+ settle(record, entry, session) {
216
278
  record.state = "delivered";
217
- record.session = target.session;
218
279
  record.settledAt = this.now();
219
280
  delete record.reason;
220
- this.save();
281
+ delete record.hookClaim;
282
+ delete record.seenRow;
283
+ if (session)
284
+ record.session = session;
285
+ if (entry !== undefined)
286
+ record.entry = entry;
221
287
  this.release(record, "delivered");
222
288
  }
289
+ /** Whether the transcript shows the agent took `record`'s message, claiming the entry it settled with.
290
+ * An entry settles one message: the table of records' `entry` offsets (per conversation) is the only
291
+ * state, so neither this path nor the hook's can settle two messages with one turn. A user row is a
292
+ * turn start whose UserPromptSubmit hook settles the message itself, so while the agent works only a
293
+ * mid-turn queue removal (no hook fires for it) settles from the transcript; once the agent is idle
294
+ * (`working` false) a user row settles too, for a hook that never came. Of several identical open
295
+ * messages the oldest take the entries. `pass` carries the entries still unclaimed within one observe. */
296
+ async taken(record, pass, working = false) {
297
+ // Only Claude's transcript says which entry a message settled with; Codex keeps the any-match check.
298
+ if (record.source !== "claude")
299
+ return (await this.landed(record).catch(() => [])).length > 0;
300
+ const same = (other) => other.hash === record.hash && other.server === record.server && other.pane === record.pane && other.session === record.session;
301
+ const open = this.records.filter(other => same(other) && PromptDeliveries.claimable(other)).sort((a, b) => a.at - b.at);
302
+ if (open[0] !== record)
303
+ return false;
304
+ const key = [record.hash, record.server, record.pane, record.session, working].join("|");
305
+ let free = pass.get(key);
306
+ if (!free) {
307
+ const found = (await this.landed(record).catch(() => [])).sort((a, b) => a.offset - b.offset);
308
+ const used = new Set(this.records.filter(other => same(other) && other.entry !== undefined).map(other => other.entry));
309
+ // A message the agent's hook settled took a user row without recording it (a transcript it could not read):
310
+ // the oldest user rows are theirs, whether the agent works or not.
311
+ let hooked = this.records.filter(other => same(other) && other.state === "delivered" && other.entry === undefined && (other.settledAt ?? 0) >= record.at - ENTRY_SLACK_MS).length;
312
+ const unclaimed = found.filter(entry => !used.has(entry.offset)).filter(entry => !(entry.hook && hooked-- > 0));
313
+ if (working) {
314
+ // A user row is its hook's to settle, unless that hook already came (before the row could be read), or
315
+ // the pane sends no callbacks at all: then a row two checks in a row saw unclaimed settles it.
316
+ const row = unclaimed.find(entry => entry.hook);
317
+ const hookless = !this.hookPanes.has(this.paneKey(record));
318
+ const own = row && (record.hookClaim || (hookless && record.seenRow === row.offset));
319
+ if (row && hookless && !own)
320
+ record.seenRow = row.offset;
321
+ free = unclaimed.filter(entry => !entry.hook || (own && entry === row));
322
+ }
323
+ else
324
+ free = unclaimed;
325
+ }
326
+ // The record may have settled (its hook claimed a row) while the transcript was read.
327
+ if (!PromptDeliveries.claimable(record))
328
+ return false;
329
+ const entry = free.shift();
330
+ pass.set(key, free);
331
+ if (entry === undefined)
332
+ return false;
333
+ record.entry = entry.offset;
334
+ return true;
335
+ }
223
336
  /** A turn in `target`'s pane ended: the agent now takes held input or never will. */
224
337
  stopped(target) {
225
338
  const at = this.now();
339
+ this.hookPanes.add(this.paneKey(target));
340
+ let marked = false;
226
341
  for (const record of this.records)
227
- if (this.samePane(record, target) && (record.state === "typed" || record.state === "queued") && record.at < at)
342
+ if (this.samePane(record, target) && (record.state === "typed" || record.state === "queued") && record.at < at) {
228
343
  record.stoppedAt = at;
344
+ marked = true;
345
+ }
346
+ // Persisted: after a restart an idle pane's message is still failed or settled by its Stop.
347
+ if (marked)
348
+ this.save();
229
349
  }
230
350
  /** Called on the Hook's activity tick with a server's panes. A message
231
351
  * still held fails loudly when its pane closed, its agent restarted, or the
@@ -234,18 +354,32 @@ export class PromptDeliveries {
234
354
  async observe(server, panes) {
235
355
  const now = this.now();
236
356
  let changed = false;
357
+ const pass = new Map();
237
358
  for (const record of this.records) {
238
- if (record.server !== server || (record.state !== "typed" && record.state !== "queued"))
359
+ if (record.server !== server)
360
+ continue;
361
+ // A failed message whose own hook came late, before its row: settled when the row appears.
362
+ if (record.state === "failed" && record.hookClaim) {
363
+ if (record.source === "claude" && (record.checkedAt === undefined || now - record.checkedAt >= LANDED_CHECK_MS)) {
364
+ record.checkedAt = now;
365
+ if (await this.taken(record, pass, true)) {
366
+ this.settle(record);
367
+ changed = true;
368
+ }
369
+ }
370
+ continue;
371
+ }
372
+ if (record.state !== "typed" && record.state !== "queued")
239
373
  continue;
240
374
  const pane = panes.find(entry => entry.pane_id === record.pane);
241
375
  if (!pane || (record.terminal && pane.terminal_id !== record.terminal) || (pane.agent && pane.agent !== record.source)) {
242
- if (await this.landed(record).catch(() => false)) {
243
- record.state = "delivered";
244
- record.settledAt = now;
376
+ if (await this.taken(record, pass)) {
377
+ this.settle(record);
245
378
  changed = true;
246
- this.release(record, "delivered");
247
379
  continue;
248
380
  }
381
+ if (!PromptDeliveries.open(record))
382
+ continue;
249
383
  record.state = "failed";
250
384
  record.settledAt = now;
251
385
  changed = true;
@@ -254,18 +388,28 @@ export class PromptDeliveries {
254
388
  }
255
389
  if (!["idle", "done"].includes(String(pane.agent_status))) {
256
390
  record.idleSince = undefined;
391
+ // A message the agent took into its running turn (Claude's mid-turn steer) never reaches
392
+ // its UserPromptSubmit hook; its transcript is the only place that says so.
393
+ if (record.source === "claude" && (record.checkedAt === undefined || now - record.checkedAt >= LANDED_CHECK_MS)) {
394
+ record.checkedAt = now;
395
+ if (await this.taken(record, pass, true)) {
396
+ this.settle(record);
397
+ changed = true;
398
+ }
399
+ }
257
400
  continue;
258
401
  }
259
402
  record.idleSince ??= now;
260
403
  if (record.stoppedAt === undefined || now - Math.max(record.idleSince, record.stoppedAt) < DELIVERY_GIVE_UP_MS)
261
404
  continue;
262
- if (await this.landed(record).catch(() => false)) {
263
- record.state = "delivered";
264
- record.settledAt = now;
405
+ if (await this.taken(record, pass)) {
406
+ this.settle(record);
265
407
  changed = true;
266
- this.release(record, "delivered");
267
408
  continue;
268
409
  }
410
+ // Settled delivered by its hook while the transcript was read: never downgraded.
411
+ if (!PromptDeliveries.open(record))
412
+ continue;
269
413
  record.state = "failed";
270
414
  record.settledAt = now;
271
415
  changed = true;
@@ -275,30 +419,40 @@ export class PromptDeliveries {
275
419
  this.save();
276
420
  }
277
421
  }
278
- /** Whether a user row with these words reached the conversation's transcript
422
+ /** The byte offsets of the user rows with these words that reached the conversation's transcript
279
423
  * after the message was typed: the agent took it without its hook saying so
280
424
  * (a mid-turn steer). Reads at most the last 512 KiB. */
281
- async function transcriptHas(record) {
425
+ /** The byte offsets (in the file, `start` being the buffer's own offset) of the rows in `buffer`
426
+ * whose user text has `record`'s words, newest first. One offset per row. */
427
+ export function matchingOffsets(buffer, start, record) {
428
+ const entries = [];
429
+ const lines = buffer.toString("utf8").split("\n");
430
+ let offset = start + buffer.length;
431
+ for (let index = lines.length - 1; index >= 0; index--) {
432
+ const line = lines[index];
433
+ offset -= Buffer.byteLength(line) + (index < lines.length - 1 ? 1 : 0);
434
+ let row;
435
+ try {
436
+ row = object(JSON.parse(line));
437
+ }
438
+ catch {
439
+ continue;
440
+ }
441
+ const stamp = Date.parse(String(row.timestamp ?? ""));
442
+ if (Number.isFinite(stamp) && stamp < record.at - 5_000)
443
+ break;
444
+ // One entry per row, even when its content repeats the words.
445
+ if (userTexts(row).some(text => promptHash(text) === record.hash))
446
+ entries.push({ offset, hook: row.type === "user" });
447
+ }
448
+ return entries;
449
+ }
450
+ async function transcriptEntries(record) {
282
451
  const file = await open(await transcriptPath(record.source, record.session), "r");
283
452
  try {
284
453
  const size = (await file.stat()).size, start = Math.max(0, size - 524_288), buffer = Buffer.alloc(size - start);
285
454
  await file.read(buffer, 0, buffer.length, start);
286
- for (const line of buffer.toString("utf8").split("\n").reverse()) {
287
- let row;
288
- try {
289
- row = object(JSON.parse(line));
290
- }
291
- catch {
292
- continue;
293
- }
294
- const stamp = Date.parse(String(row.timestamp ?? ""));
295
- if (Number.isFinite(stamp) && stamp < record.at - 5_000)
296
- break;
297
- for (const text of userTexts(row))
298
- if (promptHash(text) === record.hash)
299
- return true;
300
- }
301
- return false;
455
+ return matchingOffsets(buffer, start, record);
302
456
  }
303
457
  finally {
304
458
  await file.close();
@@ -318,6 +472,12 @@ export function userTexts(row) {
318
472
  };
319
473
  if (row.type === "user" && !row.isMeta)
320
474
  blocks(object(row.message).content);
475
+ // Claude Code takes a message typed mid-turn out of its queue into the running turn:
476
+ // `enqueue` when typed, then `remove` (not `dequeue`, which starts a turn of its own) with the same words.
477
+ // A `remove` also drops input without the agent seeing it (reason "cleared_on_cancel"): only these reasons mean it was taken.
478
+ if (row.type === "queue-operation" && row.operation === "remove" && typeof row.content === "string"
479
+ && (row.reason === "absorbed_mid_turn" || row.reason === "delivered_to_agent"))
480
+ texts.push(row.content);
321
481
  const payload = object(row.payload);
322
482
  if (payload.type === "user_message" && typeof payload.message === "string")
323
483
  texts.push(payload.message);
@@ -114,7 +114,14 @@ export declare const runningStatuses: Set<"blocked" | "failed" | "finished" | "l
114
114
  export declare function intervalMilliseconds(value: string): number;
115
115
  export declare function parseSchedule(value: unknown): Schedule;
116
116
  export declare function readScheduleDocument(projectDir: string): Promise<ScheduleDocument>;
117
+ /** Synchronous I/O for writers sharing a lock with synchronous store routes. */
118
+ export declare function readScheduleDocumentSync(projectDir: string): ScheduleDocument;
119
+ /** Hold `<project>/schedules.yaml.lock` (one holder per file, in this process and
120
+ * across processes) for one read, check and write, so two edits never
121
+ * overwrite each other. */
122
+ export declare function withScheduleLock<T>(projectDir: string, work: () => T | Promise<T>): Promise<T>;
117
123
  export declare function writeScheduleDocument(projectDir: string, schedules: Schedule[], original?: Record<string, unknown>): Promise<void>;
124
+ export declare function writeScheduleDocumentSync(projectDir: string, schedules: Schedule[], original?: Record<string, unknown>): void;
118
125
  export declare function canonicalComputer(value: string): string;
119
126
  export declare function computerMatches(wanted: string, current: string): boolean;
120
127
  export declare function scheduleNotifications(schedule: Schedule): Set<ScheduleNotify>;
@@ -1,10 +1,12 @@
1
1
  import { randomBytes } from "node:crypto";
2
2
  import { readFile } from "node:fs/promises";
3
+ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
3
4
  import path from "node:path";
4
5
  import * as yaml from "js-yaml";
5
6
  import { z } from "zod";
6
7
  import { atomicInPrivateDir, bridgeRoot, object } from "./protocol.js";
7
8
  import { isValidProjectName } from "../utils-paths.js";
9
+ import { tryFileLock } from "../governance/locks.js";
8
10
  import { isAccountSlug } from "./claude-accounts.js";
9
11
  /** The schedules.yaml store: the schedule and run record shapes, validation,
10
12
  * the five timing forms evaluated in local time, and the run history file. */
@@ -102,6 +104,22 @@ export async function readScheduleDocument(projectDir) {
102
104
  return { document: { version: 1 }, schedules: [] };
103
105
  throw error;
104
106
  }
107
+ return parseScheduleDocument(text);
108
+ }
109
+ /** Synchronous I/O for writers sharing a lock with synchronous store routes. */
110
+ export function readScheduleDocumentSync(projectDir) {
111
+ let text;
112
+ try {
113
+ text = readFileSync(schedulePath(projectDir), "utf8");
114
+ }
115
+ catch (error) {
116
+ if (error.code === "ENOENT")
117
+ return { document: { version: 1 }, schedules: [] };
118
+ throw error;
119
+ }
120
+ return parseScheduleDocument(text);
121
+ }
122
+ function parseScheduleDocument(text) {
105
123
  const document = object(yaml.load(text, { schema: yaml.CORE_SCHEMA }));
106
124
  if (document.version !== 1)
107
125
  throw new Error("schedules.yaml must have version: 1.");
@@ -114,12 +132,65 @@ export async function readScheduleDocument(projectDir) {
114
132
  throw new Error("Schedule IDs must be unique within a project.");
115
133
  return { document, schedules };
116
134
  }
135
+ const scheduleQueues = new Map();
136
+ const SCHEDULE_LOCK_WAIT_MS = 5_000;
137
+ /** Hold `<project>/schedules.yaml.lock` (one holder per file, in this process and
138
+ * across processes) for one read, check and write, so two edits never
139
+ * overwrite each other. */
140
+ export async function withScheduleLock(projectDir, work) {
141
+ const file = path.resolve(schedulePath(projectDir));
142
+ const previous = scheduleQueues.get(file) ?? Promise.resolve();
143
+ const next = previous.catch(() => undefined).then(async () => {
144
+ const deadline = Date.now() + SCHEDULE_LOCK_WAIT_MS;
145
+ let release = tryFileLock(file);
146
+ while (!release) {
147
+ if (Date.now() >= deadline)
148
+ throw new Error("schedules.yaml is being changed elsewhere. Try again.");
149
+ await new Promise(resolve => setTimeout(resolve, 50));
150
+ release = tryFileLock(file);
151
+ }
152
+ try {
153
+ const result = work();
154
+ // A synchronous writer must release before yielding: a store route
155
+ // waiting synchronously on this lock otherwise stalls its owner too.
156
+ return result instanceof Promise ? await result : result;
157
+ }
158
+ finally {
159
+ release();
160
+ }
161
+ });
162
+ scheduleQueues.set(file, next);
163
+ try {
164
+ return await next;
165
+ }
166
+ finally {
167
+ if (scheduleQueues.get(file) === next)
168
+ scheduleQueues.delete(file);
169
+ }
170
+ }
117
171
  export async function writeScheduleDocument(projectDir, schedules, original = { version: 1 }) {
172
+ await atomicInPrivateDir(schedulePath(projectDir), serializeScheduleDocument(schedules, original));
173
+ }
174
+ export function writeScheduleDocumentSync(projectDir, schedules, original = { version: 1 }) {
175
+ const text = serializeScheduleDocument(schedules, original), file = schedulePath(projectDir);
176
+ mkdirSync(projectDir, { recursive: true, mode: 0o700 });
177
+ const temporary = `${file}.${randomBytes(8).toString("hex")}.tmp`;
178
+ try {
179
+ writeFileSync(temporary, text, { mode: 0o600, flag: "wx" });
180
+ renameSync(temporary, file);
181
+ }
182
+ finally {
183
+ try {
184
+ unlinkSync(temporary);
185
+ }
186
+ catch { /* already renamed or not created */ }
187
+ }
188
+ }
189
+ function serializeScheduleDocument(schedules, original) {
118
190
  if (schedules.length > MAX_SCHEDULES)
119
191
  throw new Error(`A project can have at most ${MAX_SCHEDULES} schedules.`);
120
192
  schedules.forEach(parseSchedule);
121
- const text = yaml.dump({ ...original, version: 1, schedules }, { lineWidth: 1000, noRefs: true, sortKeys: false });
122
- await atomicInPrivateDir(schedulePath(projectDir), text);
193
+ return yaml.dump({ ...original, version: 1, schedules }, { lineWidth: 1000, noRefs: true, sortKeys: false });
123
194
  }
124
195
  export function canonicalComputer(value) {
125
196
  const normalized = value.trim().toLowerCase();