owenloop 0.5.1 → 0.5.3

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 (88) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/claude.js +69 -9
  13. package/dist/packages/work/src/harness/codex.js +56 -8
  14. package/dist/packages/work/src/harness/contract.d.ts +65 -1
  15. package/dist/packages/work/src/harness/contract.js +56 -0
  16. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  17. package/dist/packages/work/src/harness/session-store.js +46 -22
  18. package/dist/packages/work/src/hold/mcp.js +9 -2
  19. package/dist/packages/work/src/hub/client.d.ts +7 -1
  20. package/dist/packages/work/src/hub/client.js +1 -0
  21. package/dist/packages/work/src/hub/types.d.ts +71 -3
  22. package/dist/packages/work/src/roles/agent-run.js +8 -9
  23. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  24. package/dist/packages/work/src/roles/hold.js +39 -8
  25. package/dist/packages/work/src/roles/settings.js +18 -6
  26. package/dist/packages/work/src/roles/shift.js +13 -1
  27. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  28. package/dist/packages/work/src/settings/settings.js +69 -22
  29. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  30. package/dist/packages/work/src/shift/logretention.js +407 -0
  31. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  32. package/dist/packages/work/src/shift/logsink.js +98 -0
  33. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  34. package/dist/packages/work/src/shift/loop.js +250 -12
  35. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  36. package/dist/packages/work/src/shift/protocol.js +14 -0
  37. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  38. package/dist/packages/work/src/shift/runtime.js +229 -6
  39. package/dist/packages/work/src/shift/server.d.ts +13 -0
  40. package/dist/packages/work/src/shift/server.js +61 -36
  41. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  42. package/dist/packages/work/src/shift/spawn.js +158 -12
  43. package/dist/packages/work/src/shift/state.d.ts +25 -0
  44. package/dist/packages/work/src/shift/state.js +29 -5
  45. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  46. package/dist/packages/work/src/shift/truncate.js +73 -0
  47. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  48. package/dist/packages/work/src/submit-proof.js +33 -7
  49. package/dist/packages/work/src/submit-value.d.ts +48 -0
  50. package/dist/packages/work/src/submit-value.js +118 -0
  51. package/dist/packages/work/src/usage.d.ts +1 -1
  52. package/dist/packages/work/src/usage.js +11 -0
  53. package/dist/src/bundle/runtime.d.ts +1 -1
  54. package/dist/src/bundle/runtime.js +9 -0
  55. package/dist/src/capabilities.d.ts +93 -0
  56. package/dist/src/capabilities.js +101 -0
  57. package/dist/src/cli.js +37 -11
  58. package/dist/src/crypto/records.d.ts +3 -0
  59. package/dist/src/crypto/records.js +11 -0
  60. package/dist/src/defs.js +192 -4
  61. package/dist/src/engine.d.ts +112 -3
  62. package/dist/src/engine.js +224 -28
  63. package/dist/src/hub.d.ts +27 -11
  64. package/dist/src/hub.js +24 -18
  65. package/dist/src/index.d.ts +3 -1
  66. package/dist/src/index.js +4 -1
  67. package/dist/src/mcp/serve.js +11 -4
  68. package/dist/src/model.d.ts +36 -0
  69. package/dist/src/model.js +46 -0
  70. package/dist/src/schemas/index.d.ts +17 -0
  71. package/dist/src/schemas/order.v1.schema.json +17 -3
  72. package/dist/src/store.d.ts +33 -1
  73. package/dist/src/store.js +57 -4
  74. package/dist/src/types.d.ts +102 -2
  75. package/docs/agent-runner.md +26 -1
  76. package/docs/authoring.md +7 -0
  77. package/docs/bundles.md +103 -3
  78. package/docs/cli.md +127 -9
  79. package/docs/crypto.md +23 -7
  80. package/docs/shift-logs.md +642 -0
  81. package/docs/wire-contracts.md +34 -19
  82. package/package.json +1 -1
  83. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  84. package/plugins/claude-code/plugin/.mcp.json +1 -1
  85. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  86. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  87. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  88. package/dist/packages/work/src/agent/model-policy.js +0 -138
@@ -19,6 +19,20 @@ export const RESPONSE_TRUNCATION_MARKER = '[truncated]';
19
19
  export const MAX_EVENT_QUEUE = 1_000;
20
20
  export const OVERLAP_ERROR = 'whats_next is already parked — one park at a time (cancel it or wait for it to return)';
21
21
  export const NO_DAEMON_SUFFIX = ' — start one with: owenloop shift start <crew…>';
22
+ /**
23
+ * Stamp a body with its envelope. The ONE place the envelope is constructed —
24
+ * every emitter (the loop's `emit()`, the daemon's `ended`, the runtime's worker
25
+ * failures and startup record) routes through here so no consumer can receive a
26
+ * half-stamped record.
27
+ */
28
+ export function stampShiftEvent(body, identity, now) {
29
+ return {
30
+ ...body,
31
+ ts: new Date(now).toISOString(),
32
+ shift: identity.name,
33
+ shiftId: identity.id,
34
+ };
35
+ }
22
36
  export function isShiftError(value) {
23
37
  return typeof value === 'object' && value !== null && typeof value.error === 'string';
24
38
  }
@@ -1,5 +1,15 @@
1
+ import { type ShiftEventBody } from './protocol.ts';
1
2
  import { installSignalHandlers, type SignalHost } from '../roles/signals.ts';
2
3
  export { installSignalHandlers, type SignalHost };
4
+ /**
5
+ * Does this event type reach the SOCKET consumer (a parked `owenloop shift
6
+ * next`), or only `shift.log`?
7
+ *
8
+ * The routing rule as a pure predicate so it can be asserted directly rather
9
+ * than only through a daemon's timing. `consumeEvent` is its one production
10
+ * caller; a `false` here means the record still reaches the file.
11
+ */
12
+ export declare function reachesSocketConsumer(type: ShiftEventBody['type']): boolean;
3
13
  export declare function resolveCap(flagCap: number | undefined, settingsCap: number | undefined): number;
4
14
  export declare function resolveStateDirOverride(flag: string | undefined, env: Record<string, string | undefined>, settingsStateDir: string | undefined): string | undefined;
5
15
  export declare function resolveMaxConcurrentAgents(flagMax: number | undefined, settingsMax: number | undefined): number;
@@ -21,6 +31,10 @@ export interface ParsedArgs {
21
31
  maxAgents?: number;
22
32
  cacheDir?: string;
23
33
  stateDir?: string;
34
+ /** `--log-dir` — where `shift.log` and `<run>.log` are written. */
35
+ logDir?: string;
36
+ /** `--log-max-age` — worker-log retention in milliseconds. `0` reaps eagerly. */
37
+ logMaxAgeMs?: number;
24
38
  error?: string;
25
39
  }
26
40
  /** Parse shift's internal `--flag value` and `--flag=value` forms. */
@@ -15,6 +15,9 @@ import { resolveBearer } from "../credentials/resolve.js";
15
15
  import { loadSettings } from "../settings/settings.js";
16
16
  import { resolveCacheDir } from "../bundle/cache.js";
17
17
  import { createShiftLoop } from "./loop.js";
18
+ import { createShiftLogSink } from "./logsink.js";
19
+ import { prepareShiftLogDir, shiftLogFile } from "./logretention.js";
20
+ import { stampShiftEvent } from "./protocol.js";
18
21
  import { createDefaultSpawner } from "./spawn.js";
19
22
  import { resolveStateDir, ensureStateDir, reconcileInFlight } from "./state.js";
20
23
  import { reconcileActiveSessions, sessionsPath } from "../harness/session-store.js";
@@ -29,6 +32,73 @@ const DEFAULT_CAP = 3;
29
32
  const DEFAULT_POLL_MS = 5_000;
30
33
  const DEFAULT_MAX_AGENTS = 4;
31
34
  const DEFAULT_PRESENCE_MS = 60_000;
35
+ /**
36
+ * Record types written to the LOG FILE but never delivered over the socket.
37
+ *
38
+ * The split is not "important vs unimportant" — it is what each consumer is.
39
+ * A record about a UNIT OF WORK THAT MOVED (`dispatched`, `reaped`, `failed`,
40
+ * `order-dropped`, `bundle-miss`, `ended`, `gate`) tells a socket client
41
+ * something it cannot otherwise learn, so it goes to both sinks. Everything
42
+ * else is about the SHIFT'S OWN CONDITION, and that is different on each side:
43
+ *
44
+ * - On the SOCKET it is redundant or harmful. Every `ShiftCapacity` response
45
+ * already carries live `cap`, `free`, and `running`, so `capacity` and
46
+ * `parked` restate on the wire what the response states anyway — while
47
+ * queueing ANY record instantly satisfies a parked `owenloop shift next`,
48
+ * which must BLOCK until there is work to report. That is the bug this set
49
+ * exists to prevent: a shift that is merely full, merely idle, or merely
50
+ * unable to reach the hub would wake every attending terminal with news of
51
+ * nothing having happened.
52
+ * - In the FILE it is the only record of that condition. The file has no
53
+ * response envelope, so without these records a reader cannot tell an idle
54
+ * shift (no orders offered) from a saturated one (orders offered, no slots)
55
+ * from a stranded one (hub unreachable, so nothing was ever offered).
56
+ *
57
+ * `hub-error` IS IN THIS SET, AND THE REASON IS BOTH HALVES ABOVE.
58
+ *
59
+ * A FAILED HUB CALL IS NOT A UNIT OF WORK MOVING. Nothing was dispatched,
60
+ * reaped, or dropped — the shift failed to ask. So the "a socket client cannot
61
+ * learn it otherwise" justification for both-sinks does not apply, and the
62
+ * blocking contract of `shift next` does.
63
+ *
64
+ * The volume makes it a correctness problem rather than a style one, because
65
+ * `hub-error` is LEVEL-TRIGGERED and cannot self-limit. `noteServerBackoff`
66
+ * (`loop.ts`) sets a backoff only for a `HubError` with `status === 429`; an
67
+ * unreachable hub (ECONNREFUSED, DNS failure, timeout, HTTP 500) sets none, so
68
+ * the loop emits one `hub-error` per poll tick for as long as the outage lasts
69
+ * — about 720/hour per workflow at the 5s default. The socket queue holds
70
+ * `MAX_EVENT_QUEUE` (1000) records and evicts the OLDEST, so roughly 83 minutes
71
+ * of outage would evict every `dispatched`, `failed`, and `reaped` record a
72
+ * parked client actually needs, and every `owenloop shift next` during the
73
+ * outage would return instantly with a record that is not work.
74
+ *
75
+ * `shift.log` is append-only and unbounded, so it still keeps every attempt for
76
+ * an operator to count and time. Whether the FILE should ALSO collapse a long
77
+ * outage into fewer records is a separate, open question (idea
78
+ * W99TXHD9jqwpymifl-5-C) — frequency and routing are independent concerns, and
79
+ * this set is the one that decides routing.
80
+ *
81
+ * `event-queue-overflow` never reaches `consumeEvent` at all — `server.ts`
82
+ * hands it straight to the log sink through `onSynthesized`, because the queue
83
+ * is what overflowed. It is listed here so the category is stated in one place.
84
+ */
85
+ const FILE_ONLY_EVENTS = new Set([
86
+ 'parked',
87
+ 'capacity',
88
+ 'hub-error',
89
+ 'event-queue-overflow',
90
+ ]);
91
+ /**
92
+ * Does this event type reach the SOCKET consumer (a parked `owenloop shift
93
+ * next`), or only `shift.log`?
94
+ *
95
+ * The routing rule as a pure predicate so it can be asserted directly rather
96
+ * than only through a daemon's timing. `consumeEvent` is its one production
97
+ * caller; a `false` here means the record still reaches the file.
98
+ */
99
+ export function reachesSocketConsumer(type) {
100
+ return !FILE_ONLY_EVENTS.has(type);
101
+ }
32
102
  export function resolveCap(flagCap, settingsCap) {
33
103
  return flagCap ?? settingsCap ?? DEFAULT_CAP;
34
104
  }
@@ -81,6 +151,8 @@ export function parseArgs(args) {
81
151
  case '--workflow':
82
152
  case '--poll-interval':
83
153
  case '--cache-dir':
154
+ case '--log-dir':
155
+ case '--log-max-age':
84
156
  case '--state-dir': {
85
157
  const r = takeValue(a, i);
86
158
  if ('error' in r)
@@ -104,6 +176,14 @@ export function parseArgs(args) {
104
176
  parsed.cacheDir = r.value;
105
177
  else if (name === '--state-dir')
106
178
  parsed.stateDir = r.value;
179
+ else if (name === '--log-dir')
180
+ parsed.logDir = r.value;
181
+ else if (name === '--log-max-age') {
182
+ const n = intFlag(r.value, '--log-max-age');
183
+ if (typeof n !== 'number')
184
+ return { error: n.error };
185
+ parsed.logMaxAgeMs = n;
186
+ }
107
187
  else if (name === '--cap') {
108
188
  const n = intFlag(r.value, '--cap');
109
189
  if (typeof n !== 'number')
@@ -133,7 +213,8 @@ export function parseArgs(args) {
133
213
  function usage() {
134
214
  process.stderr.write('usage: owenloop work shift [--origin <url>] [--as <account>] [--name <n>] [--serve-crews a,b] [--cap <n>]\n' +
135
215
  ' [--workflow <id>] [--poll-interval <ms>] [--once]\n' +
136
- ' [--max-agents <n>] [--cache-dir <p>] [--state-dir <p>]\n');
216
+ ' [--max-agents <n>] [--cache-dir <p>] [--state-dir <p>]\n' +
217
+ ' [--log-dir <p>] [--log-max-age <ms>]\n');
137
218
  }
138
219
  function errMsg(err) {
139
220
  return err instanceof Error ? err.message : String(err);
@@ -219,6 +300,37 @@ export async function runShiftRuntime(parsed, options = {}) {
219
300
  process.stderr.write(`${roleLabel}: session reconcile failed (continuing): ${errMsg(err)}\n`);
220
301
  }
221
302
  }
303
+ // ── ON-DISK LOGGING ──
304
+ //
305
+ // Prepared AFTER `ensureStateDir` because the log directory DEFAULTS to the
306
+ // state directory, and BEFORE the spawner because every dispatch needs the
307
+ // destination.
308
+ //
309
+ // `prepareShiftLogDir` resolves the directory, creates it, claims it for this
310
+ // shift's state directory, and sweeps aged-out worker logs — and degrades to
311
+ // "less logging" rather than failing the shift at every one of those steps.
312
+ // Its branches are unit-tested directly; what THIS site owns is the wiring:
313
+ // which flags, settings and environment reach it, and that a `ready: false`
314
+ // result withholds both the sink and the spawner's log directory.
315
+ const prepared = prepareShiftLogDir({
316
+ flagDir: parsed.logDir,
317
+ flagMaxAgeMs: parsed.logMaxAgeMs,
318
+ env,
319
+ settingsLogDir: settings.shiftLogDir,
320
+ settingsMaxAgeMs: settings.shiftLogMaxAgeMs,
321
+ stateDir,
322
+ now: Date.now(),
323
+ err: (line) => process.stderr.write(`${line}\n`),
324
+ label: roleLabel,
325
+ });
326
+ const logDir = prepared.dir;
327
+ const logDirReady = prepared.ready;
328
+ const logSink = logDirReady
329
+ ? createShiftLogSink({
330
+ path: shiftLogFile(logDir),
331
+ err: (line) => process.stderr.write(`${line}\n`),
332
+ })
333
+ : undefined;
222
334
  const cap = resolveCap(parsed.cap, settings.dispatchCap);
223
335
  const maxConcurrentAgents = resolveMaxConcurrentAgents(parsed.maxAgents, settings.maxConcurrentAgents);
224
336
  const workRoot = resolveWorkRoot(env, settings.workRoot, cacheDir);
@@ -250,8 +362,65 @@ export async function runShiftRuntime(parsed, options = {}) {
250
362
  const startedAt = now();
251
363
  const name = resolveShiftName(parsed.name, { shiftId });
252
364
  let daemon;
365
+ /**
366
+ * `loop` is constructed BELOW this function, so it is captured by reference
367
+ * rather than value — exactly as `daemon` is, and for the same reason. Both
368
+ * are safe because nothing calls `reportWorkerFailure` until a spawned child
369
+ * exits, which cannot happen before construction finishes.
370
+ *
371
+ * A one-field holder rather than a bare `let`: `let loopRef; loopRef = loop;`
372
+ * is a single write in the same scope as the declaration, which is exactly
373
+ * the shape `prefer-const` rejects. The field write is not a rebinding, so
374
+ * the holder can be `const`.
375
+ */
376
+ const loopRef = { current: undefined };
377
+ /**
378
+ * Attach the `{ts, shift, shiftId}` envelope. Reads the shift's name LIVE from
379
+ * the loop rather than closing over the startup `name`, because `clock_in` can
380
+ * rename a shift mid-run and a record must carry the name in force when it was
381
+ * produced. Before the loop exists there is nothing to dispatch and therefore
382
+ * nothing to stamp, so the fallback to `name` is unreachable in practice and
383
+ * still correct if it is ever reached.
384
+ */
385
+ const stamp = (body) => stampShiftEvent(body, { name: loopRef.current?.getShift().name ?? name, id: shiftId }, now());
386
+ /**
387
+ * THE ONE PLACE a shift event fans out to its consumers: the socket daemon
388
+ * (live, ephemeral, only in daemon mode) and the on-disk log (durable, always
389
+ * when a log directory resolved).
390
+ *
391
+ * Each consumer is wrapped SEPARATELY. A daemon whose FIFO throws must not
392
+ * cost the file its record, and a full disk must not cost a parked client its
393
+ * event. Neither failure may reach the loop, which is why nothing rethrows.
394
+ *
395
+ * The two consumers do NOT receive the same set: `FILE_ONLY_EVENTS` reaches
396
+ * the file only. Routing is decided HERE rather than at each emit site so an
397
+ * emitter never has to know how many sinks exist.
398
+ */
399
+ const consumeEvent = (event) => {
400
+ if (daemonMode && reachesSocketConsumer(event.type)) {
401
+ try {
402
+ daemon?.onEvent(event);
403
+ }
404
+ catch (err) {
405
+ process.stderr.write(`${roleLabel}: shift event queue failed: ${errMsg(err)} (continuing)\n`);
406
+ }
407
+ }
408
+ // `createShiftLogSink.write` already swallows and reports its own failures;
409
+ // this guard covers a throw from anywhere else in the call.
410
+ try {
411
+ logSink?.write(event);
412
+ }
413
+ catch (err) {
414
+ process.stderr.write(`${roleLabel}: shift event sink failed: ${errMsg(err)} (continuing)\n`);
415
+ }
416
+ };
253
417
  const reportWorkerFailure = (failure) => {
254
- const event = {
418
+ // A worker failure is detected by the SPAWNER's `exit`/`error` listener, not
419
+ // inside the loop's sweep, so it never passes through the loop's `emit()`.
420
+ // It is stamped here for the same reason `ended` is stamped in `server.ts`:
421
+ // every record on the wire and in the file carries the same envelope, with
422
+ // no exceptions a consumer would have to special-case.
423
+ const event = stamp({
255
424
  type: 'failed',
256
425
  workflow: failure.workflow,
257
426
  run: failure.run,
@@ -262,11 +431,21 @@ export async function runShiftRuntime(parsed, options = {}) {
262
431
  exitStatus: failure.exitStatus,
263
432
  signal: failure.signal,
264
433
  message: failure.message,
265
- };
266
- daemon?.onEvent(event);
434
+ });
435
+ consumeEvent(event);
267
436
  process.stderr.write(`${roleLabel}: worker failure ${JSON.stringify(event)}\n`);
437
+ // The third consumer, and the one that changes behaviour: charge the
438
+ // failure against the step's dispatch brake so a step that fails the same
439
+ // way forever is re-dispatched on a backoff instead of once per poll.
440
+ loopRef.current?.noteWorkerFailure(failure);
268
441
  };
269
- const spawner = createDefaultSpawner(origin, account, undefined, shiftId, reportWorkerFailure);
442
+ const spawner = createDefaultSpawner(origin, account, undefined, shiftId, reportWorkerFailure,
443
+ // `undefined` when the log directory could not be created, which is what
444
+ // makes `buildSpawnPlan` emit no `logFile` and the worker launch with its
445
+ // output discarded exactly as it did before this change.
446
+ logDirReady
447
+ ? { dir: logDir, err: (line) => process.stderr.write(`${line}\n`) }
448
+ : undefined);
270
449
  const pollIntervalMs = parsed.pollIntervalMs ?? DEFAULT_POLL_MS;
271
450
  const loop = createShiftLoop({
272
451
  hub,
@@ -276,7 +455,10 @@ export async function runShiftRuntime(parsed, options = {}) {
276
455
  monotonicNow,
277
456
  out: (line) => process.stdout.write(`${line}\n`),
278
457
  err: (line) => process.stderr.write(`${line}\n`),
279
- ...(daemonMode ? { onEvent: (event) => daemon?.onEvent(event) } : {}),
458
+ // Previously daemon-mode only, because the socket daemon was the only
459
+ // consumer. The file sink is a second consumer that exists in BOTH modes, so
460
+ // the loop now emits whenever either consumer is present.
461
+ ...(daemonMode || logSink !== undefined ? { onEvent: consumeEvent } : {}),
280
462
  cacheDir,
281
463
  stateDir,
282
464
  cap,
@@ -294,6 +476,39 @@ export async function runShiftRuntime(parsed, options = {}) {
294
476
  ...(parsed.workflow !== undefined ? { workflow: parsed.workflow } : {}),
295
477
  ...(parsed.once === true ? { once: true } : {}),
296
478
  });
479
+ // Close the loop on `reportWorkerFailure`'s forward reference. Assigned
480
+ // immediately after construction, long before any child can exit.
481
+ loopRef.current = loop;
482
+ /**
483
+ * The first record in a shift's log: what this process is, where it is, and
484
+ * what it will serve. `shift.log` is read on a machine, days later, by someone
485
+ * who has only the file — so the file must be SELF-DESCRIBING. Every later
486
+ * record identifies the shift by name and id alone; this one is what those
487
+ * names resolve to.
488
+ *
489
+ * Written by `runtime.ts` rather than the loop because the loop knows its cap
490
+ * and crews but not the origin it was pointed at, the host, or the launch
491
+ * directory. Suppressed under `--once`, matching the console `parked as …`
492
+ * line — a one-shot drain is not a parked shift.
493
+ *
494
+ * FILE-ONLY, via `FILE_ONLY_EVENTS` — this goes through `consumeEvent` like
495
+ * every other record, and `consumeEvent` withholds it from the socket. A
496
+ * startup record sitting in the daemon's FIFO would make the first `next`
497
+ * after every start return instantly with a record about the shift itself,
498
+ * breaking the contract that an idle `next` BLOCKS until there is work to
499
+ * report; `packages/work/test/shift-blocking-acceptance.test.ts` asserts that
500
+ * blocking behaviour directly.
501
+ */
502
+ const emitParked = () => {
503
+ consumeEvent(stamp({
504
+ type: 'parked',
505
+ origin,
506
+ cap,
507
+ serveCrews: parsed.serveCrews ?? [],
508
+ hostname: hostname(),
509
+ cwd: process.cwd(),
510
+ }));
511
+ };
297
512
  if (daemonMode) {
298
513
  daemon = createShiftDaemon({
299
514
  socketPath: options.socketPath ?? join(stateDir, 'shift.sock'),
@@ -304,6 +519,12 @@ export async function runShiftRuntime(parsed, options = {}) {
304
519
  startedAt,
305
520
  shiftId,
306
521
  err: (line) => process.stderr.write(`${line}\n`),
522
+ // The daemon's self-made records (`event-queue-overflow`, `ended`) go
523
+ // STRAIGHT to the file, never back through `consumeEvent` — `consumeEvent`
524
+ // feeds `daemon.onEvent`, and the daemon has already put each of these in
525
+ // its own queue. For `event-queue-overflow` that routing is load-bearing
526
+ // rather than merely tidy: its queue is the thing that just overflowed.
527
+ ...(logSink !== undefined ? { onSynthesized: (event) => logSink.write(event) } : {}),
307
528
  });
308
529
  installSignalHandlers(daemon, process, (line) => process.stderr.write(`${line}\n`), {
309
530
  role: 'shift',
@@ -312,12 +533,14 @@ export async function runShiftRuntime(parsed, options = {}) {
312
533
  });
313
534
  if (parsed.once !== true) {
314
535
  process.stdout.write(`owenloop shift: parked as '${name}' @ ${origin} (cap ${cap})\n`);
536
+ emitParked();
315
537
  }
316
538
  return daemon.run();
317
539
  }
318
540
  installSignalHandlers(loop, process, (line) => process.stderr.write(`${line}\n`));
319
541
  if (parsed.once !== true) {
320
542
  process.stdout.write(`owenloop work shift: parked as '${name}' @ ${origin} (cap ${cap})\n`);
543
+ emitParked();
321
544
  }
322
545
  return loop.run();
323
546
  }
@@ -10,6 +10,19 @@ export interface ShiftDaemonOptions {
10
10
  startedAt: number;
11
11
  shiftId?: string;
12
12
  err: (line: string) => void;
13
+ /**
14
+ * Called with each already-stamped event this daemon SYNTHESIZES rather than
15
+ * receives through `onEvent` — today `event-queue-overflow` and `ended`.
16
+ *
17
+ * These two are the only shift events that never pass through `emit()` in
18
+ * `loop.ts`, so they are the only ones a second consumer would otherwise never
19
+ * see. In `runtime.ts` this callback is the on-disk log sink, which is what
20
+ * makes the file and the socket carry the same record set.
21
+ *
22
+ * The callback must write somewhere that is NOT this daemon's queue. For
23
+ * `event-queue-overflow` that is load-bearing: the queue is what overflowed.
24
+ */
25
+ onSynthesized?: (event: ShiftEvent) => void;
13
26
  }
14
27
  export interface ShiftDaemon {
15
28
  run(): Promise<number>;
@@ -8,52 +8,25 @@
8
8
  */
9
9
  import { chmodSync, lstatSync, mkdirSync, renameSync, unlinkSync, } from 'node:fs';
10
10
  import { createServer, createConnection } from 'node:net';
11
- import { MAX_EVENT_QUEUE, MAX_REQUEST_LINE_BYTES, MAX_RESPONSE_LINE_BYTES, OVERLAP_ERROR, RESPONSE_TRUNCATION_MARKER, } from "./protocol.js";
11
+ import { MAX_EVENT_QUEUE, MAX_REQUEST_LINE_BYTES, MAX_RESPONSE_LINE_BYTES, OVERLAP_ERROR, stampShiftEvent, } from "./protocol.js";
12
+ import { truncateEventToBytes } from "./truncate.js";
12
13
  const REQUEST_IDLE_TIMEOUT_MS = 5_000;
13
14
  const SHUTDOWN_GRACE_MS = 500;
14
15
  function serializedResponseBytes(response) {
15
16
  return Buffer.byteLength(`${JSON.stringify(response)}\n`, 'utf8');
16
17
  }
17
- function truncateUtf8(value, maxBytes) {
18
- if (Buffer.byteLength(value, 'utf8') <= maxBytes)
19
- return value;
20
- const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
21
- if (maxBytes <= markerBytes)
22
- return RESPONSE_TRUNCATION_MARKER;
23
- let prefix = Buffer.from(value, 'utf8').subarray(0, maxBytes - markerBytes).toString('utf8');
24
- while (Buffer.byteLength(prefix, 'utf8') > maxBytes - markerBytes)
25
- prefix = prefix.slice(0, -1);
26
- return `${prefix}${RESPONSE_TRUNCATION_MARKER}`;
27
- }
28
18
  /**
29
19
  * A single event can be larger than the response ceiling. It is delivered once
30
20
  * with its string fields shortened and an explicit marker instead of blocking
31
21
  * every later event in the FIFO forever.
22
+ *
23
+ * The algorithm lives in `truncate.ts` and is SHARED with the on-disk log sink,
24
+ * so the file's line ceiling and the wire's are one rule with one
25
+ * implementation. Only the byte accounting differs, and that is what the
26
+ * callback supplies: here, a whole response envelope carrying this one event.
32
27
  */
33
28
  function truncateEventForResponse(event, envelope) {
34
- const candidate = { ...event };
35
- const stringKeys = Object.keys(candidate).filter((key) => typeof candidate[key] === 'string' && key !== 'type');
36
- const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
37
- while (serializedResponseBytes({ ...envelope, events: [candidate] }) > MAX_RESPONSE_LINE_BYTES) {
38
- const key = stringKeys
39
- .filter((name) => candidate[name] !== RESPONSE_TRUNCATION_MARKER)
40
- .sort((left, right) => Buffer.byteLength(String(candidate[right]), 'utf8') - Buffer.byteLength(String(candidate[left]), 'utf8'))[0];
41
- if (key === undefined)
42
- break;
43
- const value = String(candidate[key]);
44
- const currentBytes = Buffer.byteLength(value, 'utf8');
45
- const targetBytes = Math.max(markerBytes, Math.floor(currentBytes / 2));
46
- const shortened = truncateUtf8(value, targetBytes);
47
- candidate[key] = shortened === value ? RESPONSE_TRUNCATION_MARKER : shortened;
48
- }
49
- // The current event union has a fixed envelope plus only string fields. The
50
- // marker-only form is a final backstop if a future event shape needs more
51
- // reduction than the progressive shortening above provided.
52
- if (serializedResponseBytes({ ...envelope, events: [candidate] }) > MAX_RESPONSE_LINE_BYTES) {
53
- for (const key of stringKeys)
54
- candidate[key] = RESPONSE_TRUNCATION_MARKER;
55
- }
56
- return candidate;
29
+ return truncateEventToBytes(event, MAX_RESPONSE_LINE_BYTES, (candidate) => serializedResponseBytes({ ...envelope, events: [candidate] }));
57
30
  }
58
31
  function fileIdentity(stat) {
59
32
  return { dev: stat.dev, ino: stat.ino, ctimeMs: stat.ctimeMs };
@@ -282,6 +255,27 @@ export function createShiftDaemon(opts) {
282
255
  const connections = new Set();
283
256
  const shutdownSockets = new Set();
284
257
  const events = [];
258
+ /**
259
+ * How many events the FIFO has evicted since this daemon started, and the
260
+ * cumulative count at which the NEXT overflow record is written.
261
+ *
262
+ * Reporting every eviction is not an option: an unattended shift — no client
263
+ * ever calls `next`, so nothing ever drains the queue — evicts one event per
264
+ * event forever, and a per-eviction record would roughly double the volume of
265
+ * a file this change does not rotate.
266
+ *
267
+ * Reporting only the first eviction is not an option either: that record says
268
+ * `dropped: 1` and is never corrected, so the operator reading the file learns
269
+ * that loss STARTED and never learns its size.
270
+ *
271
+ * So: report at each power of ten (1, 10, 100, 1000, …). At most ~7 records
272
+ * for any run a real machine can produce, the first arrives immediately, and
273
+ * every record carries a current cumulative total.
274
+ */
275
+ let dropped = 0;
276
+ let nextOverflowReport = 1;
277
+ /** Attach the `{ts, shift, shiftId}` envelope this daemon is responsible for. */
278
+ const stamp = (body) => stampShiftEvent(body, { name: opts.loop.getShift().name, id: opts.shiftId ?? '' }, opts.now());
285
279
  const capacity = () => {
286
280
  const cap = opts.loop.getCap();
287
281
  const free = opts.loop.freeCapacity();
@@ -333,6 +327,20 @@ export function createShiftDaemon(opts) {
333
327
  if (events.length >= MAX_EVENT_QUEUE) {
334
328
  events.shift();
335
329
  opts.err(`shift event queue overflow — dropping oldest event`);
330
+ dropped += 1;
331
+ if (dropped === nextOverflowReport) {
332
+ nextOverflowReport *= 10;
333
+ // DIRECT to the caller's sink — never enqueue(). enqueue() feeds the
334
+ // very queue that just overflowed, so an overflow event routed through
335
+ // it would evict another event, overflow again, and recurse under
336
+ // exactly the load that produced the overflow.
337
+ try {
338
+ opts.onSynthesized?.(stamp({ type: 'event-queue-overflow', dropped }));
339
+ }
340
+ catch (e) {
341
+ opts.err(`shift event sink failed: ${e instanceof Error ? e.message : String(e)} (continuing)`);
342
+ }
343
+ }
336
344
  }
337
345
  events.push(event);
338
346
  if (parked !== undefined)
@@ -462,7 +470,24 @@ export function createShiftDaemon(opts) {
462
470
  if (reason === 'end') {
463
471
  if (parked !== undefined)
464
472
  shutdownSockets.add(parked.socket);
465
- enqueue({ type: 'ended' });
473
+ // `ended` is synthesized here rather than received from the loop, so it is
474
+ // one of the two events `emit()` in loop.ts never stamps. Stamp it once
475
+ // and hand the SAME record to both consumers, so the socket and the file
476
+ // agree on its `ts` down to the millisecond.
477
+ //
478
+ // Note the narrow meaning, which `docs/shift-logs.md` states for readers
479
+ // of the file: `ended` is written only for `reason === 'end'` — an
480
+ // operator ran `owenloop shift end`. A signal or a loop failure ends the
481
+ // process without one, so a `shift.log` with no trailing `ended` record
482
+ // describes a shift that stopped some other way, or is still running.
483
+ const ended = stamp({ type: 'ended' });
484
+ enqueue(ended);
485
+ try {
486
+ opts.onSynthesized?.(ended);
487
+ }
488
+ catch (e) {
489
+ opts.err(`shift event sink failed: ${e instanceof Error ? e.message : String(e)} (continuing)`);
490
+ }
466
491
  }
467
492
  else if (parked !== undefined) {
468
493
  // A signal or unexpected loop exit does not synthesize an `ended` event,
@@ -24,6 +24,10 @@ export interface SpawnSpec {
24
24
  * Optional safe lifecycle-reporting label for an `agent-run` child. This field
25
25
  * never becomes `--harness`; the child resolves the authoritative harness from
26
26
  * CLI/environment/verified runtime definition precedence.
27
+ *
28
+ * It is ONE INPUT to the reported label, not the label itself, and it is the
29
+ * LOWER-ranked one: `reportedHarnessId` puts the child's `OWENLOOP_HARNESS`
30
+ * above it, because the child does.
27
31
  */
28
32
  harness?: string;
29
33
  /** Closed start gate created by the durable Shift reservation. */
@@ -43,9 +47,22 @@ export interface SpawnResult {
43
47
  }
44
48
  /** The spawn seam. Injected; faked in tests. */
45
49
  export type Spawner = (spec: SpawnSpec) => SpawnResult;
50
+ /**
51
+ * Where a detached worker's own stdout and stderr are appended, when the shift
52
+ * has a log directory. `dir` absent ⇒ workers stay `stdio: ['ignore','ignore',
53
+ * 'ignore']`, exactly as before this option existed.
54
+ */
55
+ export interface WorkerLogOptions {
56
+ /** The resolved log directory. `<dir>/<run>.log` is the destination. */
57
+ dir: string;
58
+ /** One-time failure report sink for a log that could not be opened. */
59
+ err?: (line: string) => void;
60
+ }
46
61
  /** Safe, bounded metadata emitted when a detached worker fails. Detached
47
- * worker stderr is not attached to Shift: agent-run output is untrusted, and a
48
- * parent-owned pipe can kill either worker with EPIPE after Shift exits. */
62
+ * worker stderr is not attached to Shift as a PIPE: agent-run output is
63
+ * untrusted, and a parent-owned pipe can kill either worker with EPIPE after
64
+ * Shift exits. It is appended to a per-run FILE instead — see
65
+ * `createDefaultSpawner`. */
49
66
  export interface WorkerFailure {
50
67
  workflow: string;
51
68
  run: string;
@@ -58,15 +75,65 @@ export interface WorkerFailure {
58
75
  message: string;
59
76
  }
60
77
  export type WorkerFailureReporter = (failure: WorkerFailure) => void;
78
+ /**
79
+ * The harness id to REPORT on an agent-run worker failure — a best-effort
80
+ * mirror of the id the CHILD resolved, never an independent decision.
81
+ *
82
+ * It mirrors `resolveAdapter` in `roles/agent-run.ts`, minus the `--harness`
83
+ * rank the Shift never emits:
84
+ *
85
+ * 1. `OWENLOOP_HARNESS` when the variable is SET. Set-but-blank is not a
86
+ * fall-through: the child refuses that config outright and names it
87
+ * `<empty OWENLOOP_HARNESS>`, so the failure event says the same thing.
88
+ * 2. `spec.harness` — the prepared-cache step's `harness` field — when it is
89
+ * a non-empty string. An empty string counts as absent, matching the
90
+ * child.
91
+ * 3. Otherwise the child took the first REGISTERED adapter. This process
92
+ * cannot name it: the Shift is a neutral dispatcher and never imports the
93
+ * adapter composition root, so its own registry is empty and asking it
94
+ * would answer `undefined`. Report the placeholder instead.
95
+ *
96
+ * WHY THE ORDER MATTERS. It used to read `spec.harness ?? OWENLOOP_HARNESS`,
97
+ * which is the child's precedence INVERTED. An operator who pinned
98
+ * `OWENLOOP_HARNESS` on a shift whose cached step also named a harness got a
99
+ * failure event naming the harness that did NOT run — the single most
100
+ * misleading field in the record, since the harness is the first thing an
101
+ * operator reaches for when a worker dies.
102
+ *
103
+ * BEST-EFFORT IS DELIBERATE at rank 2. A modern agent order carries no
104
+ * `spec.harness` at all (the child reads the verified, order-pinned step), so
105
+ * rank 2 only ever fires on the legacy cache path. The alternative — the Shift
106
+ * verifying the order digest itself purely to label a failure — would duplicate
107
+ * the child's whole resolution for a diagnostic string.
108
+ *
109
+ * `env` is the environment the CHILD is spawned with (`plan.options.env`), not
110
+ * this process's — they differ, and the child's is the one that decided.
111
+ */
112
+ export declare function reportedHarnessId(spec: Pick<SpawnSpec, 'harness'>, env: NodeJS.ProcessEnv): string;
113
+ /**
114
+ * The stdio topology of a detached worker.
115
+ *
116
+ * Slot 0 is always `'ignore'`: a worker reads nothing. Slots 1 and 2 are either
117
+ * both `'ignore'` (no log destination resolved, or opening it failed) or both
118
+ * the SAME descriptor number — one file opened once and handed to stdout and
119
+ * stderr together, which is exactly shell `2>&1`.
120
+ */
121
+ export type WorkerStdio = ['ignore', 'ignore', 'ignore'] | ['ignore', number, number];
61
122
  /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
62
123
  export interface SpawnPlan {
63
124
  command: string;
64
125
  args: string[];
65
126
  options: {
66
127
  detached: true;
67
- stdio: ['ignore', 'ignore', 'ignore'];
128
+ stdio: WorkerStdio;
68
129
  env: NodeJS.ProcessEnv;
69
130
  };
131
+ /**
132
+ * Absolute path this worker's stdout and stderr should be appended to, when a
133
+ * log directory is configured. A PATH, never a descriptor: `buildSpawnPlan`
134
+ * stays pure, and `createDefaultSpawner` does the opening.
135
+ */
136
+ logFile?: string;
70
137
  }
71
138
  /**
72
139
  * Build the argv + options for a detached
@@ -96,8 +163,14 @@ export interface SpawnPlan {
96
163
  * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
97
164
  * step, registered default). The Shift command has no operator-facing harness
98
165
  * flag, so there is no legitimate CLI override for this seam to carry.
166
+ *
167
+ * `logDir` (trailing, after `shiftId`, for the same reason) adds the worker's
168
+ * log DESTINATION to the plan as `<logDir>/<run>.log`. The plan still carries
169
+ * `stdio: ['ignore','ignore','ignore']`: opening the file is I/O, this function
170
+ * is pure, and `createDefaultSpawner` substitutes the descriptors. Omitted ⇒ no
171
+ * `logFile` key at all, and the plan is byte-identical to the pre-logging shape.
99
172
  */
100
- export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string): SpawnPlan;
173
+ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string, logDir?: string): SpawnPlan;
101
174
  /**
102
175
  * The default detached spawner. Captures the resolved hub `origin`, the
103
176
  * resolved `account`, the packaged bin path, and the dispatching Shift's
@@ -106,4 +179,4 @@ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account:
106
179
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
107
180
  * — can be supplied positionally.
108
181
  */
109
- export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter): Spawner;
182
+ export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter, logging?: WorkerLogOptions): Spawner;