owenloop 0.5.7 → 0.5.9

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 (111) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +7 -8
  3. package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
  4. package/dist/packages/work/src/agent/capability-model.js +94 -91
  5. package/dist/packages/work/src/agent/loop.d.ts +55 -26
  6. package/dist/packages/work/src/agent/loop.js +144 -50
  7. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +206 -35
  11. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  12. package/dist/packages/work/src/exec/receipt.js +6 -6
  13. package/dist/packages/work/src/harness/child-env.js +4 -5
  14. package/dist/packages/work/src/harness/claude.js +100 -0
  15. package/dist/packages/work/src/harness/codex.js +3 -4
  16. package/dist/packages/work/src/harness/session-store.d.ts +63 -3
  17. package/dist/packages/work/src/harness/session-store.js +104 -9
  18. package/dist/packages/work/src/hub/client.d.ts +19 -4
  19. package/dist/packages/work/src/hub/client.js +7 -3
  20. package/dist/packages/work/src/hub/types.d.ts +87 -3
  21. package/dist/packages/work/src/main.js +1 -0
  22. package/dist/packages/work/src/roles/agent-run.js +46 -43
  23. package/dist/packages/work/src/roles/exec.js +2 -0
  24. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  25. package/dist/packages/work/src/roles/sessions.js +9 -2
  26. package/dist/packages/work/src/roles/settings.js +3 -1
  27. package/dist/packages/work/src/roles/shift.js +14 -2
  28. package/dist/packages/work/src/roles/util.d.ts +1 -0
  29. package/dist/packages/work/src/roles/util.js +10 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  31. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  32. package/dist/packages/work/src/settings/roster.d.ts +105 -0
  33. package/dist/packages/work/src/settings/roster.js +439 -0
  34. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  35. package/dist/packages/work/src/settings/serving.js +79 -0
  36. package/dist/packages/work/src/settings/settings.d.ts +25 -24
  37. package/dist/packages/work/src/settings/settings.js +29 -33
  38. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  39. package/dist/packages/work/src/shift/loop.js +299 -51
  40. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  41. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  42. package/dist/packages/work/src/shift/runtime.js +95 -13
  43. package/dist/packages/work/src/shift/server.js +2 -0
  44. package/dist/packages/work/src/shift/spawn.d.ts +18 -50
  45. package/dist/packages/work/src/shift/spawn.js +30 -65
  46. package/dist/packages/work/src/shift/state.d.ts +29 -2
  47. package/dist/packages/work/src/shift/state.js +45 -15
  48. package/dist/packages/work/src/usage.d.ts +1 -1
  49. package/dist/packages/work/src/usage.js +10 -5
  50. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  51. package/dist/packages/work/src/util/modifier-init.js +73 -0
  52. package/dist/src/bundle/tar.d.ts +9 -4
  53. package/dist/src/bundle/tar.js +9 -4
  54. package/dist/src/capabilities.d.ts +50 -0
  55. package/dist/src/capabilities.js +38 -0
  56. package/dist/src/cli.d.ts +15 -1
  57. package/dist/src/cli.js +1099 -32
  58. package/dist/src/config-dir.d.ts +14 -19
  59. package/dist/src/config-dir.js +16 -24
  60. package/dist/src/credentials.d.ts +1 -1
  61. package/dist/src/credentials.js +1 -1
  62. package/dist/src/crypto/index.d.ts +1 -1
  63. package/dist/src/crypto/index.js +1 -1
  64. package/dist/src/crypto/org-root.d.ts +30 -12
  65. package/dist/src/crypto/org-root.js +162 -14
  66. package/dist/src/crypto/records.d.ts +3 -0
  67. package/dist/src/crypto/records.js +8 -0
  68. package/dist/src/crypto/trust-roots.d.ts +2 -2
  69. package/dist/src/crypto/trust-roots.js +2 -2
  70. package/dist/src/defs.d.ts +6 -1
  71. package/dist/src/defs.js +203 -8
  72. package/dist/src/engine.d.ts +55 -6
  73. package/dist/src/engine.js +172 -22
  74. package/dist/src/global-config.d.ts +4 -7
  75. package/dist/src/global-config.js +4 -7
  76. package/dist/src/hub.d.ts +207 -5
  77. package/dist/src/hub.js +263 -3
  78. package/dist/src/index.d.ts +5 -5
  79. package/dist/src/index.js +3 -3
  80. package/dist/src/mcp/serve.d.ts +22 -0
  81. package/dist/src/mcp/serve.js +88 -8
  82. package/dist/src/model.d.ts +2 -0
  83. package/dist/src/model.js +32 -25
  84. package/dist/src/order-resolver.d.ts +1 -0
  85. package/dist/src/order-resolver.js +8 -1
  86. package/dist/src/schemas/index.d.ts +19 -0
  87. package/dist/src/schemas/order.v1.schema.json +13 -2
  88. package/dist/src/store/pre-commit-verifier.js +1 -1
  89. package/dist/src/store.d.ts +5 -0
  90. package/dist/src/store.js +43 -8
  91. package/dist/src/types.d.ts +64 -7
  92. package/dist/src/work-settings.d.ts +2 -4
  93. package/dist/src/work-settings.js +2 -4
  94. package/docs/agent-runner.md +2 -2
  95. package/docs/authoring.md +90 -2
  96. package/docs/bundles.md +29 -3
  97. package/docs/cli.md +456 -120
  98. package/docs/crypto.md +32 -16
  99. package/docs/design.md +70 -1
  100. package/docs/routing.md +762 -0
  101. package/docs/shift-logs.md +37 -10
  102. package/docs/wire-contracts.md +50 -7
  103. package/examples/workflows/delivery.yaml +31 -14
  104. package/examples/workflows/ship.yaml +10 -2
  105. package/package.json +1 -1
  106. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  107. package/plugins/claude-code/plugin/.mcp.json +1 -1
  108. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  109. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  110. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  111. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
@@ -1,4 +1,6 @@
1
1
  import { type ShiftEventBody } from './protocol.ts';
2
+ import { type Liveness, type Reconciliation } from './state.ts';
3
+ import { type AcquireFileLockOpts } from '../../../../src/lock.ts';
2
4
  import { installSignalHandlers, type SignalHost } from '../roles/signals.ts';
3
5
  export { installSignalHandlers, type SignalHost };
4
6
  /**
@@ -13,6 +15,8 @@ export declare function reachesSocketConsumer(type: ShiftEventBody['type']): boo
13
15
  export declare function resolveCap(flagCap: number | undefined, settingsCap: number | undefined): number;
14
16
  export declare function resolveStateDirOverride(flag: string | undefined, env: Record<string, string | undefined>, settingsStateDir: string | undefined): string | undefined;
15
17
  export declare function resolveMaxConcurrentAgents(flagMax: number | undefined, settingsMax: number | undefined): number;
18
+ export declare function resolveExecReserve(flagReserve: number | undefined, settingsReserve: number | undefined): number;
19
+ export declare function resolveLocalQueueHoldMs(flagHold: number | undefined, settingsHold: number | undefined): number;
16
20
  export declare function resolveShiftName(flagName: string | undefined, opts?: {
17
21
  shiftId?: string;
18
22
  hostname?: string;
@@ -29,6 +33,8 @@ export interface ParsedArgs {
29
33
  pollIntervalMs?: number;
30
34
  once?: boolean;
31
35
  maxAgents?: number;
36
+ execReserve?: number;
37
+ localQueueHoldMs?: number;
32
38
  cacheDir?: string;
33
39
  stateDir?: string;
34
40
  /** `--log-dir` — where `shift.log` and `<run>.log` are written. */
@@ -46,6 +52,15 @@ export interface ParsedArgs {
46
52
  }
47
53
  /** Parse shift's internal `--flag value` and `--flag=value` forms. */
48
54
  export declare function parseArgs(args: string[]): ParsedArgs;
55
+ /**
56
+ * Reconcile startup state under the same per-removal dispatch lock as the live
57
+ * loop. A busy neighbour is recoverable: the first poll-loop iteration retries
58
+ * shortly, whereas failing the entire Shift startup would strand its work.
59
+ */
60
+ export declare function reconcileStartupState(stateDir: string, report: (line: string) => void, options?: {
61
+ dispatchLockOptions?: Pick<AcquireFileLockOpts, 'beforeOpen'>;
62
+ isAlive?: Liveness;
63
+ }): Reconciliation | undefined;
49
64
  export interface ShiftRuntimeOptions {
50
65
  /** Build the Unix-socket shift daemon around the same loop instead of self-driving directly. */
51
66
  daemon?: boolean;
@@ -13,13 +13,16 @@ import { performance } from 'node:perf_hooks';
13
13
  import { createHubClient } from "../hub/client.js";
14
14
  import { resolveBearer } from "../credentials/resolve.js";
15
15
  import { loadSettings } from "../settings/settings.js";
16
+ import { DEFAULT_HUB_ROSTER_SYNC_TIMEOUT_MS, syncHubRosterCache, withHubRosterSyncTimeout } from "../settings/hub-roster-cache.js";
17
+ import { computeServeCapabilities } from "../settings/serving.js";
16
18
  import { resolveCacheDir } from "../bundle/cache.js";
17
- import { createShiftLoop } from "./loop.js";
19
+ import { createLockedRemovalCallbacks, createShiftLoop } from "./loop.js";
18
20
  import { createShiftLogSink } from "./logsink.js";
19
21
  import { prepareShiftLogDir, shiftLogFile } from "./logretention.js";
20
22
  import { stampShiftEvent } from "./protocol.js";
21
23
  import { createDefaultSpawner } from "./spawn.js";
22
24
  import { resolveStateDir, ensureStateDir, reconcileInFlight } from "./state.js";
25
+ import { FileLockTimeoutError } from "../../../../src/lock.js";
23
26
  import { reconcileActiveSessions, sessionsPath } from "../harness/session-store.js";
24
27
  import { resolveAllowedWorkdirRoots, resolveWorkRepo, resolveWorkRoot, } from "../agent/workdir.js";
25
28
  import { installSignalHandlers } from "../roles/signals.js";
@@ -31,7 +34,9 @@ export { installSignalHandlers };
31
34
  const DEFAULT_CAP = 3;
32
35
  const DEFAULT_POLL_MS = 5_000;
33
36
  const DEFAULT_MAX_AGENTS = 4;
37
+ const DEFAULT_EXEC_RESERVE = 1;
34
38
  const DEFAULT_PRESENCE_MS = 60_000;
39
+ const DEFAULT_ROSTER_SYNC_MS = 15 * 60_000;
35
40
  /**
36
41
  * Record types written to the LOG FILE but never delivered over the socket.
37
42
  *
@@ -108,6 +113,12 @@ export function resolveStateDirOverride(flag, env, settingsStateDir) {
108
113
  export function resolveMaxConcurrentAgents(flagMax, settingsMax) {
109
114
  return flagMax ?? settingsMax ?? DEFAULT_MAX_AGENTS;
110
115
  }
116
+ export function resolveExecReserve(flagReserve, settingsReserve) {
117
+ return flagReserve ?? settingsReserve ?? DEFAULT_EXEC_RESERVE;
118
+ }
119
+ export function resolveLocalQueueHoldMs(flagHold, settingsHold) {
120
+ return flagHold ?? settingsHold ?? 0;
121
+ }
111
122
  export function resolveShiftName(flagName, opts = {}) {
112
123
  if (flagName !== undefined && flagName !== '')
113
124
  return flagName;
@@ -148,6 +159,8 @@ export function parseArgs(args) {
148
159
  case '--serve-crews':
149
160
  case '--cap':
150
161
  case '--max-agents':
162
+ case '--exec-reserve':
163
+ case '--local-queue-hold':
151
164
  case '--workflow':
152
165
  case '--poll-interval':
153
166
  case '--cache-dir':
@@ -197,6 +210,18 @@ export function parseArgs(args) {
197
210
  return { error: n.error };
198
211
  parsed.maxAgents = n;
199
212
  }
213
+ else if (name === '--exec-reserve') {
214
+ const n = intFlag(r.value, '--exec-reserve');
215
+ if (typeof n !== 'number')
216
+ return { error: n.error };
217
+ parsed.execReserve = n;
218
+ }
219
+ else if (name === '--local-queue-hold') {
220
+ const n = intFlag(r.value, '--local-queue-hold');
221
+ if (typeof n !== 'number')
222
+ return { error: n.error };
223
+ parsed.localQueueHoldMs = n;
224
+ }
200
225
  else if (name === '--poll-interval') {
201
226
  const n = intFlag(r.value, '--poll-interval');
202
227
  if (typeof n !== 'number')
@@ -221,12 +246,35 @@ export function parseArgs(args) {
221
246
  function usage() {
222
247
  process.stderr.write('usage: owenloop work shift [--origin <url>] [--as <account>] [--name <n>] [--serve-crews a,b] [--cap <n>]\n' +
223
248
  ' [--workflow <id>] [--poll-interval <ms>] [--once]\n' +
224
- ' [--max-agents <n>] [--cache-dir <p>] [--state-dir <p>]\n' +
249
+ ' [--max-agents <n>] [--exec-reserve <n>] [--local-queue-hold <ms>] [--cache-dir <p>] [--state-dir <p>]\n' +
225
250
  ' [--log-dir <p>] [--log-max-age <ms>] [--work-root <dir>]...\n');
226
251
  }
227
252
  function errMsg(err) {
228
253
  return err instanceof Error ? err.message : String(err);
229
254
  }
255
+ /**
256
+ * Reconcile startup state under the same per-removal dispatch lock as the live
257
+ * loop. A busy neighbour is recoverable: the first poll-loop iteration retries
258
+ * shortly, whereas failing the entire Shift startup would strand its work.
259
+ */
260
+ export function reconcileStartupState(stateDir, report, options = {}) {
261
+ try {
262
+ return reconcileInFlight(stateDir, {
263
+ ...(options.isAlive === undefined ? {} : { isAlive: options.isAlive }),
264
+ ...createLockedRemovalCallbacks(stateDir, {
265
+ dispatchLockOptions: options.dispatchLockOptions,
266
+ waitMs: 1_000,
267
+ label: 'owenloop Shift startup reaper',
268
+ }),
269
+ });
270
+ }
271
+ catch (error) {
272
+ if (!(error instanceof FileLockTimeoutError))
273
+ throw error;
274
+ report(`startup dispatch-state reconciliation deferred: ${errMsg(error)} (the poll-loop reconciliation will retry)`);
275
+ return undefined;
276
+ }
277
+ }
230
278
  /** Public Shift daemon transport is a Unix-domain socket on macOS and Linux. */
231
279
  export function assertShiftDaemonPlatform(platform = process.platform) {
232
280
  if (platform === 'win32') {
@@ -306,16 +354,9 @@ export async function runShiftRuntime(parsed, options = {}) {
306
354
  // Reconcile the Shift's own dispatch records for capacity housekeeping. The
307
355
  // session sweep below must use the session row's PID and ownership fields,
308
356
  // not this run-id set, because every Shift on the machine shares the store.
309
- reconcileInFlight(stateDir);
357
+ reconcileStartupState(stateDir, (line) => process.stderr.write(`${roleLabel}: ${line}\n`));
310
358
  try {
311
- const configuredHarness = env['OWENLOOP_HARNESS'];
312
- const retired = reconcileActiveSessions(sessionsPath(cacheDir), {
313
- shiftName: name,
314
- shiftOwner,
315
- ...(configuredHarness !== undefined && configuredHarness.trim() !== ''
316
- ? { harness: configuredHarness }
317
- : {}),
318
- }, Date.now());
359
+ const retired = reconcileActiveSessions(sessionsPath(cacheDir), { shiftName: name, shiftOwner }, Date.now());
319
360
  for (const rec of retired) {
320
361
  process.stderr.write(`${roleLabel}: retired orphaned session ${rec.workflow}/${rec.run} step '${rec.step}' ` +
321
362
  `(harness '${rec.harness}', attempt ${String(rec.attempt ?? 1)}, ` +
@@ -360,6 +401,8 @@ export async function runShiftRuntime(parsed, options = {}) {
360
401
  : undefined;
361
402
  const cap = resolveCap(parsed.cap, settings.dispatchCap);
362
403
  const maxConcurrentAgents = resolveMaxConcurrentAgents(parsed.maxAgents, settings.maxConcurrentAgents);
404
+ const execReserve = resolveExecReserve(parsed.execReserve, settings.execReserve);
405
+ const localQueueHoldMs = resolveLocalQueueHoldMs(parsed.localQueueHoldMs, settings.localQueueHoldMs);
363
406
  const workRoot = resolveWorkRoot(env, settings.workRoot, cacheDir);
364
407
  const workRepo = resolveWorkRepo(env, settings.workRepo);
365
408
  /**
@@ -454,6 +497,18 @@ export async function runShiftRuntime(parsed, options = {}) {
454
497
  process.stderr.write(`${roleLabel}: shift event sink failed: ${errMsg(err)} (continuing)\n`);
455
498
  }
456
499
  };
500
+ // The agent-run child must stay completely offline. Refresh before entering
501
+ // the park loop, but let an unavailable hub degrade to machine layers. The
502
+ // durable error is buffered until after `parked`: a parked shift's first log
503
+ // record is its self-describing identity, even when this refresh fails.
504
+ let startupRosterSyncFailure;
505
+ try {
506
+ await withHubRosterSyncTimeout((signal) => syncHubRosterCache({ client: hub, env, origin, account, signal }));
507
+ }
508
+ catch (error) {
509
+ startupRosterSyncFailure = `roster sync failed at shift start: ${errMsg(error)} (continuing)`;
510
+ process.stderr.write(`${roleLabel}: ${startupRosterSyncFailure}\n`);
511
+ }
457
512
  const reportWorkerFailure = (failure) => {
458
513
  // A worker failure is detected by the SPAWNER's `exit`/`error` listener, not
459
514
  // inside the loop's sweep, so it never passes through the loop's `emit()`.
@@ -466,7 +521,6 @@ export async function runShiftRuntime(parsed, options = {}) {
466
521
  run: failure.run,
467
522
  step: failure.step ?? '(unknown)',
468
523
  kind: failure.kind,
469
- ...(failure.harness !== undefined ? { harness: failure.harness } : {}),
470
524
  executable: failure.executable,
471
525
  exitStatus: failure.exitStatus,
472
526
  signal: failure.signal,
@@ -479,13 +533,16 @@ export async function runShiftRuntime(parsed, options = {}) {
479
533
  // way forever is re-dispatched on a backoff instead of once per poll.
480
534
  loopRef.current?.noteWorkerFailure(failure);
481
535
  };
536
+ const reportWorkerExit = (exit) => {
537
+ loopRef.current?.noteChildExited(exit);
538
+ };
482
539
  const spawner = createDefaultSpawner(origin, account, undefined, shiftId, reportWorkerFailure,
483
540
  // `undefined` when the log directory could not be created, which is what
484
541
  // makes `buildSpawnPlan` emit no `logFile` and the worker launch with its
485
542
  // output discarded exactly as it did before this change.
486
543
  logDirReady
487
544
  ? { dir: logDir, err: (line) => process.stderr.write(`${line}\n`) }
488
- : undefined, allowedWorkdirRoots);
545
+ : undefined, allowedWorkdirRoots, reportWorkerExit);
489
546
  const pollIntervalMs = parsed.pollIntervalMs ?? DEFAULT_POLL_MS;
490
547
  const loop = createShiftLoop({
491
548
  hub,
@@ -509,7 +566,18 @@ export async function runShiftRuntime(parsed, options = {}) {
509
566
  resolveOrderStep,
510
567
  pollIntervalMs,
511
568
  presenceIntervalMs: DEFAULT_PRESENCE_MS,
569
+ rosterSyncIntervalMs: DEFAULT_ROSTER_SYNC_MS,
570
+ rosterSyncTimeoutMs: DEFAULT_HUB_ROSTER_SYNC_TIMEOUT_MS,
571
+ syncRosters: (signal) => syncHubRosterCache({ client: hub, env, origin, account, signal }),
572
+ computeServeCapabilities: (crews) => computeServeCapabilities({
573
+ env,
574
+ crews,
575
+ hub: { origin, account },
576
+ warn: (message) => process.stderr.write(`${roleLabel}: shift: ${message}\n`),
577
+ }),
512
578
  maxConcurrentAgents,
579
+ execReserve,
580
+ localQueueHoldMs,
513
581
  workRoot,
514
582
  ...(workRepo !== undefined ? { workRepo } : {}),
515
583
  shiftId,
@@ -550,6 +618,12 @@ export async function runShiftRuntime(parsed, options = {}) {
550
618
  cwd: process.cwd(),
551
619
  }));
552
620
  };
621
+ const emitStartupRosterSyncFailure = () => {
622
+ if (startupRosterSyncFailure === undefined)
623
+ return;
624
+ consumeEvent(stamp({ type: 'hub-error', op: 'roster_sync', message: startupRosterSyncFailure }));
625
+ startupRosterSyncFailure = undefined;
626
+ };
553
627
  if (daemonMode) {
554
628
  daemon = createShiftDaemon({
555
629
  socketPath: options.socketPath ?? join(stateDir, 'shift.sock'),
@@ -575,6 +649,10 @@ export async function runShiftRuntime(parsed, options = {}) {
575
649
  if (parsed.once !== true) {
576
650
  process.stdout.write(`owenloop shift: parked as '${name}' @ ${origin} (cap ${cap})\n`);
577
651
  emitParked();
652
+ emitStartupRosterSyncFailure();
653
+ }
654
+ else {
655
+ emitStartupRosterSyncFailure();
578
656
  }
579
657
  return daemon.run();
580
658
  }
@@ -582,6 +660,10 @@ export async function runShiftRuntime(parsed, options = {}) {
582
660
  if (parsed.once !== true) {
583
661
  process.stdout.write(`owenloop work shift: parked as '${name}' @ ${origin} (cap ${cap})\n`);
584
662
  emitParked();
663
+ emitStartupRosterSyncFailure();
664
+ }
665
+ else {
666
+ emitStartupRosterSyncFailure();
585
667
  }
586
668
  return loop.run();
587
669
  }
@@ -287,6 +287,7 @@ export function createShiftDaemon(opts) {
287
287
  name: shift.name,
288
288
  serve_crews: shift.serveCrews,
289
289
  ...capacity(),
290
+ agent_ceiling: opts.loop.agentCeiling(),
290
291
  attended_at: opts.loop.getAttendedAt() ?? null,
291
292
  started_at: opts.startedAt,
292
293
  };
@@ -430,6 +431,7 @@ export function createShiftDaemon(opts) {
430
431
  await opts.hub.presencePing({
431
432
  name: shift.name,
432
433
  serve_crews: shift.serveCrews,
434
+ serve_capabilities: opts.loop.getServeCapabilities(),
433
435
  ...(opts.shiftId !== undefined ? { shift_id: opts.shiftId } : {}),
434
436
  started_at: opts.startedAt,
435
437
  // Deliberately omit attended_at. The merged hub contract interprets
@@ -20,16 +20,6 @@ export interface SpawnSpec {
20
20
  * hosts the step agent itself. This is the ONLY agent path.
21
21
  */
22
22
  kind?: 'exec' | 'agent-run';
23
- /**
24
- * Optional safe lifecycle-reporting label for an `agent-run` child. This field
25
- * never becomes `--harness`; the child resolves the authoritative harness from
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.
31
- */
32
- harness?: string;
33
23
  /** Closed start gate created by the durable Shift reservation. */
34
24
  startGate?: string;
35
25
  /** Stable shift name in force when this worker was dispatched. */
@@ -72,7 +62,6 @@ export interface WorkerFailure {
72
62
  run: string;
73
63
  step?: string;
74
64
  kind: 'exec' | 'agent-run';
75
- harness?: string;
76
65
  executable: string;
77
66
  exitStatus: number | null;
78
67
  signal: NodeJS.Signals | null;
@@ -80,40 +69,20 @@ export interface WorkerFailure {
80
69
  }
81
70
  export type WorkerFailureReporter = (failure: WorkerFailure) => void;
82
71
  /**
83
- * The harness id to REPORT on an agent-run worker failure — a best-effort
84
- * mirror of the id the CHILD resolved, never an independent decision.
85
- *
86
- * It mirrors `resolveAdapter` in `roles/agent-run.ts`, minus the `--harness`
87
- * rank the Shift never emits:
88
- *
89
- * 1. `OWENLOOP_HARNESS` when the variable is SET. Set-but-blank is not a
90
- * fall-through: the child refuses that config outright and names it
91
- * `<empty OWENLOOP_HARNESS>`, so the failure event says the same thing.
92
- * 2. `spec.harness` — the prepared-cache step's `harness` field — when it is
93
- * a non-empty string. An empty string counts as absent, matching the
94
- * child.
95
- * 3. Otherwise the child took the first REGISTERED adapter. This process
96
- * cannot name it: the Shift is a neutral dispatcher and never imports the
97
- * adapter composition root, so its own registry is empty and asking it
98
- * would answer `undefined`. Report the placeholder instead.
99
- *
100
- * WHY THE ORDER MATTERS. It used to read `spec.harness ?? OWENLOOP_HARNESS`,
101
- * which is the child's precedence INVERTED. An operator who pinned
102
- * `OWENLOOP_HARNESS` on a shift whose cached step also named a harness got a
103
- * failure event naming the harness that did NOT run — the single most
104
- * misleading field in the record, since the harness is the first thing an
105
- * operator reaches for when a worker dies.
106
- *
107
- * BEST-EFFORT IS DELIBERATE at rank 2. A modern agent order carries no
108
- * `spec.harness` at all (the child reads the verified, order-pinned step), so
109
- * rank 2 only ever fires on the legacy cache path. The alternative — the Shift
110
- * verifying the order digest itself purely to label a failure — would duplicate
111
- * the child's whole resolution for a diagnostic string.
112
- *
113
- * `env` is the environment the CHILD is spawned with (`plan.options.env`), not
114
- * this process's — they differ, and the child's is the one that decided.
72
+ * A dispatched worker process ENDED. Fired for every terminal outcome —
73
+ * a clean exit (including an agent-run that completed mid-turn and exited 0),
74
+ * a nonzero exit, a signal kill, and a failure to spawn. The shift frees the
75
+ * dispatch slot from this, so it must never be conditional on the exit code.
115
76
  */
116
- export declare function reportedHarnessId(spec: Pick<SpawnSpec, 'harness'>, env: NodeJS.ProcessEnv): string;
77
+ export interface WorkerExit {
78
+ workflow: string;
79
+ run: string;
80
+ kind: 'exec' | 'agent-run';
81
+ pid: number;
82
+ exitStatus: number | null;
83
+ signal: NodeJS.Signals | null;
84
+ }
85
+ export type WorkerExitReporter = (exit: WorkerExit) => void;
117
86
  /**
118
87
  * The stdio topology of a detached worker.
119
88
  *
@@ -162,11 +131,10 @@ export interface SpawnPlan {
162
131
  * — is identical for both kinds, so an agent-run child is detached,
163
132
  * stdio-ignored, and account-scoped exactly like an exec child.
164
133
  *
165
- * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
166
- * not an operator override; the `agent-run` child resolves its authoritative
167
- * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
168
- * step, registered default). The Shift command has no operator-facing harness
169
- * flag, so there is no legitimate CLI override for this seam to carry.
134
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch
135
+ * metadata, not an operator override; the `agent-run` child resolves the
136
+ * selected crew-roster harness before its debug flag, verified runtime step,
137
+ * and registered default.
170
138
  *
171
139
  * `allowedWorkdirRoots` (trailing, for the same reason) rides the child's spawn
172
140
  * env as `OWENLOOP_ALLOWED_WORKDIR_ROOTS`, a `:`-separated list — the same
@@ -193,4 +161,4 @@ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account:
193
161
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
194
162
  * — can be supplied positionally.
195
163
  */
196
- export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter, logging?: WorkerLogOptions, allowedWorkdirRoots?: string[]): Spawner;
164
+ export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter, logging?: WorkerLogOptions, allowedWorkdirRoots?: string[], onExit?: WorkerExitReporter): Spawner;
@@ -63,48 +63,6 @@ function openWorkerLog(path, report) {
63
63
  function err(e) {
64
64
  return e instanceof Error ? e.message : String(e);
65
65
  }
66
- /**
67
- * The harness id to REPORT on an agent-run worker failure — a best-effort
68
- * mirror of the id the CHILD resolved, never an independent decision.
69
- *
70
- * It mirrors `resolveAdapter` in `roles/agent-run.ts`, minus the `--harness`
71
- * rank the Shift never emits:
72
- *
73
- * 1. `OWENLOOP_HARNESS` when the variable is SET. Set-but-blank is not a
74
- * fall-through: the child refuses that config outright and names it
75
- * `<empty OWENLOOP_HARNESS>`, so the failure event says the same thing.
76
- * 2. `spec.harness` — the prepared-cache step's `harness` field — when it is
77
- * a non-empty string. An empty string counts as absent, matching the
78
- * child.
79
- * 3. Otherwise the child took the first REGISTERED adapter. This process
80
- * cannot name it: the Shift is a neutral dispatcher and never imports the
81
- * adapter composition root, so its own registry is empty and asking it
82
- * would answer `undefined`. Report the placeholder instead.
83
- *
84
- * WHY THE ORDER MATTERS. It used to read `spec.harness ?? OWENLOOP_HARNESS`,
85
- * which is the child's precedence INVERTED. An operator who pinned
86
- * `OWENLOOP_HARNESS` on a shift whose cached step also named a harness got a
87
- * failure event naming the harness that did NOT run — the single most
88
- * misleading field in the record, since the harness is the first thing an
89
- * operator reaches for when a worker dies.
90
- *
91
- * BEST-EFFORT IS DELIBERATE at rank 2. A modern agent order carries no
92
- * `spec.harness` at all (the child reads the verified, order-pinned step), so
93
- * rank 2 only ever fires on the legacy cache path. The alternative — the Shift
94
- * verifying the order digest itself purely to label a failure — would duplicate
95
- * the child's whole resolution for a diagnostic string.
96
- *
97
- * `env` is the environment the CHILD is spawned with (`plan.options.env`), not
98
- * this process's — they differ, and the child's is the one that decided.
99
- */
100
- export function reportedHarnessId(spec, env) {
101
- const fromEnv = env['OWENLOOP_HARNESS'];
102
- if (fromEnv !== undefined)
103
- return fromEnv.trim() === '' ? '<empty OWENLOOP_HARNESS>' : fromEnv;
104
- if (spec.harness !== undefined && spec.harness !== '')
105
- return spec.harness;
106
- return '<registered default>';
107
- }
108
66
  /**
109
67
  * Build the argv + options for a detached
110
68
  * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
@@ -128,11 +86,10 @@ export function reportedHarnessId(spec, env) {
128
86
  * — is identical for both kinds, so an agent-run child is detached,
129
87
  * stdio-ignored, and account-scoped exactly like an exec child.
130
88
  *
131
- * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
132
- * not an operator override; the `agent-run` child resolves its authoritative
133
- * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
134
- * step, registered default). The Shift command has no operator-facing harness
135
- * flag, so there is no legitimate CLI override for this seam to carry.
89
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch
90
+ * metadata, not an operator override; the `agent-run` child resolves the
91
+ * selected crew-roster harness before its debug flag, verified runtime step,
92
+ * and registered default.
136
93
  *
137
94
  * `allowedWorkdirRoots` (trailing, for the same reason) rides the child's spawn
138
95
  * env as `OWENLOOP_ALLOWED_WORKDIR_ROOTS`, a `:`-separated list — the same
@@ -152,6 +109,17 @@ export function reportedHarnessId(spec, env) {
152
109
  */
153
110
  export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId, logDir, allowedWorkdirRoots) {
154
111
  const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
112
+ const env = { ...process.env };
113
+ env['OWENLOOP_ACCOUNT'] = account;
114
+ if (spec.startGate !== undefined)
115
+ env['OWENLOOP_START_GATE'] = spec.startGate;
116
+ if (spec.shiftName !== undefined && spec.shiftName !== '')
117
+ env['OWENLOOP_SHIFT_NAME'] = spec.shiftName;
118
+ if (spec.shiftOwner !== undefined && spec.shiftOwner !== '')
119
+ env['OWENLOOP_SHIFT_OWNER'] = spec.shiftOwner;
120
+ if (allowedWorkdirRoots !== undefined && allowedWorkdirRoots.length > 0) {
121
+ env['OWENLOOP_ALLOWED_WORKDIR_ROOTS'] = allowedWorkdirRoots.join(':');
122
+ }
155
123
  return {
156
124
  command: execPath,
157
125
  args: [
@@ -166,20 +134,7 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
166
134
  options: {
167
135
  detached: true,
168
136
  stdio: ['ignore', 'ignore', 'ignore'],
169
- env: {
170
- ...process.env,
171
- OWENLOOP_ACCOUNT: account,
172
- ...(spec.startGate !== undefined ? { OWENLOOP_START_GATE: spec.startGate } : {}),
173
- ...(spec.shiftName !== undefined && spec.shiftName !== ''
174
- ? { OWENLOOP_SHIFT_NAME: spec.shiftName }
175
- : {}),
176
- ...(spec.shiftOwner !== undefined && spec.shiftOwner !== ''
177
- ? { OWENLOOP_SHIFT_OWNER: spec.shiftOwner }
178
- : {}),
179
- ...(allowedWorkdirRoots !== undefined && allowedWorkdirRoots.length > 0
180
- ? { OWENLOOP_ALLOWED_WORKDIR_ROOTS: allowedWorkdirRoots.join(':') }
181
- : {}),
182
- },
137
+ env,
183
138
  },
184
139
  ...(logDir !== undefined && logDir !== '' ? { logFile: runLogFile(logDir, spec.run) } : {}),
185
140
  };
@@ -192,7 +147,7 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
192
147
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
193
148
  * — can be supplied positionally.
194
149
  */
195
- export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure, logging, allowedWorkdirRoots) {
150
+ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure, logging, allowedWorkdirRoots, onExit) {
196
151
  // ONE report per shift, not one per dispatch. Every condition that stops a
197
152
  // worker log from opening — a full disk, a read-only log directory, an
198
153
  // operator deleting it underneath a running shift — PERSISTS across the
@@ -242,7 +197,6 @@ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopB
242
197
  }
243
198
  }
244
199
  const kind = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
245
- const harness = kind === 'agent-run' ? reportedHarnessId(spec, plan.options.env) : undefined;
246
200
  // This process is the executable Shift actually launched. The harness may
247
201
  // start its own vendor process later, but reporting or guessing that
248
202
  // executable here would couple the neutral dispatcher to one adapter.
@@ -263,6 +217,7 @@ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopB
263
217
  // discard them before an operator can read them — reading them is the whole
264
218
  // point of `<run>.log`.
265
219
  let failureReported = false;
220
+ let exitReported = false;
266
221
  const report = (exitStatus, signal, message) => {
267
222
  if (failureReported || onFailure === undefined)
268
223
  return;
@@ -272,15 +227,24 @@ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopB
272
227
  run: spec.run,
273
228
  ...(spec.step !== undefined ? { step: spec.step } : {}),
274
229
  kind,
275
- ...(harness !== undefined ? { harness } : {}),
276
230
  executable,
277
231
  exitStatus,
278
232
  signal,
279
233
  message,
280
234
  });
281
235
  };
282
- child.once('error', () => report(null, null, 'worker process failed to start'));
236
+ const reportExit = (exitStatus, signal) => {
237
+ if (exitReported || onExit === undefined || child.pid === undefined)
238
+ return;
239
+ exitReported = true;
240
+ onExit({ workflow: spec.workflow, run: spec.run, kind, pid: child.pid, exitStatus, signal });
241
+ };
242
+ child.once('error', () => {
243
+ report(null, null, 'worker process failed to start');
244
+ reportExit(null, null);
245
+ });
283
246
  child.once('exit', (code, signal) => {
247
+ reportExit(code, signal);
284
248
  if (code === 0)
285
249
  return;
286
250
  report(code, signal, 'worker exited without completing successfully');
@@ -299,6 +263,7 @@ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopB
299
263
  // registered above fires afterwards and emits a SECOND `failed` event —
300
264
  // two daemon events for one dispatch attempt.
301
265
  failureReported = true;
266
+ exitReported = true;
302
267
  throw new Error(`spawn of 'owenloop work ${kind} ${spec.workflow}/${spec.run}' returned no pid`);
303
268
  }
304
269
  const kill = () => {
@@ -74,13 +74,15 @@ export declare function finalizeChildReservation(stateDir: string, reservation:
74
74
  /** Open a child's gate only after the PID-bearing record is durable. */
75
75
  export declare function startReservedChild(stateDir: string, record: ChildRecord): void;
76
76
  /** Cancel a gated child and remove the matching reservation/record. */
77
- export declare function cancelReservedChild(stateDir: string, reservation: ChildReservation): void;
77
+ export declare function cancelReservedChild(stateDir: string, reservation: ChildReservation): boolean;
78
78
  /**
79
79
  * Delete one run's in-flight state. A still-gated reservation or finalized child
80
80
  * is cancelled first so an external run-ended signal cannot leave a worker gate
81
81
  * behind that later opens without a capacity record.
82
82
  */
83
- export declare function removeChildRecord(stateDir: string, run: string): void;
83
+ export declare function removeChildRecord(stateDir: string, run: string, options?: {
84
+ pid?: number;
85
+ }): boolean;
84
86
  export type Liveness = (pid: number) => boolean;
85
87
  export declare const defaultIsAlive: Liveness;
86
88
  export interface Reconciliation {
@@ -93,7 +95,32 @@ export interface ReconcileOptions {
93
95
  isAlive?: Liveness;
94
96
  now?: number;
95
97
  reservationMaxAgeMs?: number;
98
+ /**
99
+ * Called before a stale reservation is removed. The Shift loop uses this to
100
+ * share its dispatch lock with reservation creation; standalone state callers
101
+ * intentionally retain the direct removal default.
102
+ */
103
+ removeAbandonedReservation?: (reservation: ChildReservation) => boolean;
104
+ /**
105
+ * Called before a dead child record is removed. The Shift loop uses this to
106
+ * serialize the read/guard/unlink sequence with a later re-dispatch.
107
+ */
108
+ removeDeadChild?: (record: ChildRecord) => boolean;
109
+ /**
110
+ * Finish a persisted PID record's start-gate handoff. The Shift daemon uses
111
+ * this to serialize the re-read/identity-check/write sequence with a later
112
+ * re-dispatch; standalone state callers intentionally retain the direct
113
+ * settlement default.
114
+ */
115
+ settleLiveChild?: (record: ChildRecord) => ChildRecord | undefined;
96
116
  }
117
+ /**
118
+ * Open and clear a persisted child's start gate only if the record is still
119
+ * the same PID and gate-token pair the reconciler observed. A re-dispatch can
120
+ * replace either identity between an unlocked observation and this settlement;
121
+ * in that case it owns the record and nothing is changed.
122
+ */
123
+ export declare function settleChildGate(stateDir: string, record: ChildRecord): ChildRecord | undefined;
97
124
  /**
98
125
  * Reconcile live children and durable reservations. Fresh reservations count as
99
126
  * occupied capacity. An expired reservation is cancelled before its record is