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
@@ -297,6 +297,7 @@ export function startReservedChild(stateDir, record) {
297
297
  /** Cancel a gated child and remove the matching reservation/record. */
298
298
  export function cancelReservedChild(stateDir, reservation) {
299
299
  const path = gateFile(stateDir, reservation.token);
300
+ let removed = false;
300
301
  try {
301
302
  signalGate(path, 'cancel', true);
302
303
  }
@@ -309,22 +310,29 @@ export function cancelReservedChild(stateDir, reservation) {
309
310
  const matchesFinalized = current !== undefined &&
310
311
  !isReservation(current) &&
311
312
  current.gateToken === reservation.token;
312
- if (matchesReservation || matchesFinalized)
313
+ if (matchesReservation || matchesFinalized) {
313
314
  durableRemove(recordFile(stateDir, reservation.run));
315
+ removed = true;
316
+ }
314
317
  }
318
+ return removed;
315
319
  }
316
320
  /**
317
321
  * Delete one run's in-flight state. A still-gated reservation or finalized child
318
322
  * is cancelled first so an external run-ended signal cannot leave a worker gate
319
323
  * behind that later opens without a capacity record.
320
324
  */
321
- export function removeChildRecord(stateDir, run) {
325
+ export function removeChildRecord(stateDir, run, options) {
322
326
  const path = recordFile(stateDir, run);
323
327
  const current = readOneStateRecord(path);
324
- if (current !== undefined && isReservation(current)) {
325
- cancelReservedChild(stateDir, current);
326
- return;
327
- }
328
+ if (current === undefined)
329
+ return false;
330
+ // A late exit report must never remove a record written by a re-dispatch of
331
+ // the same run. Reservations have no pid, so they are likewise newer owners.
332
+ if (options?.pid !== undefined && (isReservation(current) || current.pid !== options.pid))
333
+ return false;
334
+ if (current !== undefined && isReservation(current))
335
+ return cancelReservedChild(stateDir, current);
328
336
  if (current?.gateToken !== undefined) {
329
337
  const gatePath = gateFile(stateDir, current.gateToken);
330
338
  try {
@@ -335,6 +343,7 @@ export function removeChildRecord(stateDir, run) {
335
343
  }
336
344
  }
337
345
  durableRemove(path);
346
+ return true;
338
347
  }
339
348
  export const defaultIsAlive = (pid) => {
340
349
  if (!Number.isInteger(pid) || pid <= 0)
@@ -347,6 +356,27 @@ export const defaultIsAlive = (pid) => {
347
356
  return error.code !== 'ESRCH';
348
357
  }
349
358
  };
359
+ /**
360
+ * Open and clear a persisted child's start gate only if the record is still
361
+ * the same PID and gate-token pair the reconciler observed. A re-dispatch can
362
+ * replace either identity between an unlocked observation and this settlement;
363
+ * in that case it owns the record and nothing is changed.
364
+ */
365
+ export function settleChildGate(stateDir, record) {
366
+ if (record.gateToken === undefined)
367
+ return record;
368
+ const current = readOneStateRecord(recordFile(stateDir, record.run));
369
+ if (current === undefined ||
370
+ isReservation(current) ||
371
+ current.pid !== record.pid ||
372
+ current.gateToken !== record.gateToken)
373
+ return undefined;
374
+ signalGate(gateFile(stateDir, current.gateToken), 'start', true);
375
+ const settled = { ...current };
376
+ delete settled.gateToken;
377
+ writeStateRecord(stateDir, settled);
378
+ return settled;
379
+ }
350
380
  /**
351
381
  * Reconcile live children and durable reservations. Fresh reservations count as
352
382
  * occupied capacity. An expired reservation is cancelled before its record is
@@ -377,23 +407,23 @@ export function reconcileInFlight(stateDir, arg) {
377
407
  reserved.push(record);
378
408
  continue;
379
409
  }
380
- cancelReservedChild(stateDir, record);
381
- abandoned.push(record);
410
+ const removed = options.removeAbandonedReservation?.(record) ?? cancelReservedChild(stateDir, record);
411
+ if (removed)
412
+ abandoned.push(record);
382
413
  continue;
383
414
  }
384
415
  if (!isAlive(record.pid)) {
385
- removeChildRecord(stateDir, record.run);
386
- reaped.push(record);
416
+ const removed = options.removeDeadChild?.(record) ?? removeChildRecord(stateDir, record.run, { pid: record.pid });
417
+ if (removed)
418
+ reaped.push(record);
387
419
  continue;
388
420
  }
389
421
  if (record.gateToken !== undefined) {
390
422
  // A restart after PID persistence but before the parent opened the gate can
391
423
  // safely finish the handoff: the durable PID record is the prerequisite.
392
- signalGate(gateFile(stateDir, record.gateToken), 'start', true);
393
- const settled = { ...record };
394
- delete settled.gateToken;
395
- writeStateRecord(stateDir, settled);
396
- live.push(settled);
424
+ const settled = options.settleLiveChild === undefined ? settleChildGate(stateDir, record) : options.settleLiveChild(record);
425
+ if (settled !== undefined)
426
+ live.push(settled);
397
427
  }
398
428
  else {
399
429
  live.push(record);
@@ -3,4 +3,4 @@
3
3
  * exit 0) and on a dispatch error (to stderr, exit 2). Keeping it in one place
4
4
  * means the help output and the error output never drift apart.
5
5
  */
6
- export declare const USAGE = "owenloop work \u2014 execution-side CLI companion to owenloop\n\nUsage:\n owenloop work hold --order <id> [options] hold an order with a heartbeating lease\n owenloop work exec <order-id> [options] run a command order in a self-leasing loop\n owenloop work agent-run <order-id> [options] host an agent order's step agent in a\n harness, in a self-leasing loop\n owenloop work prepare <workflow> [--origin <url>]\n fetch, cache & normalize step specs\n owenloop work lint <workflow-name | path> lint x.harness option bags in a def\n owenloop work sessions [--all] [--json] list this machine's recorded harness\n sessions and how to re-open them\n owenloop work approvals [--json] every tool call a worker is blocked on\n RIGHT NOW, waiting for a person\n owenloop work approvals approve|deny <wf>/<run> <tool-use-id> [--note <text>]\n answer one; the answer goes back to the\n still-blocked call, not to a later attempt\n owenloop work release --session <id> [options] drain a session's held claims\n owenloop work settings print the resolved settings file\n owenloop work join <code> [--hub <origin>] [--as <account>]\n redeem a join code and store the Scoped\n Identity credential (one-time provisioning)\n\nOptions:\n -h, --help show this help and exit 0\n --version print the owenloop work version and exit 0\n\n root shift options (run as owenloop shift start <crew...> | --all):\n <crew...> serve only these crews (positional, space\n separated); or --all for every crew on the key\n --all serve every crew on the key\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account to read + hand\n to dispatched holds/execs (default 'default')\n --name <n> Shift name (default <hostname>/<cwd>)\n --cap <n> max in-flight exec children (default 3)\n --poll-interval <ms> wake poll cadence (default 5000)\n --once bootstrap wake + one sweep, then exit (demo/e2e)\n --max-agents <n> max in-flight agent-run children, separate from\n --cap (default 4; else settings.maxConcurrentAgents)\n --cache-dir/--state-dir <p> override the resolved dirs\n\n hold options:\n --order <workflow>/<run> the order to hold (or --order <run> --workflow)\n --workflow <wf> required when --order is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account (default\n 'default'; the shift stamps this into born-bound\n holds)\n --session <id> session-holder tag (else env OWENLOOP_SESSION;\n else an anon:<hostname>:<pid> fallback \u2014 a\n holder is always sent)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --ignore-stdin don't final-breath on stdin EOF (detached use)\n --never-release another process holds the claim; stop without\n releasing it (agent-run spawns its --mcp child\n this way \u2014 see hold.ts HOLDER OF RECORD)\n --mcp run as a stdio-MCP work-holder: tools get_order /\n submit, lease kept warm underneath (mutually\n exclusive with --ignore-stdin \u2014 stdin is the\n transport)\n\n exec options (usually spawned by shift, not run by hand):\n <workflow>/<run> the command order to run (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n\n agent-run options (spawned by the shift, not run by hand):\n <workflow>/<run> the agent order to host (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --harness <id> which registered harness hosts the step agent\n (else env OWENLOOP_HARNESS, else the step def's\n 'harness' field, else the first registered one)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --submit-grace <ms> after the turn ends, how long to keep asking the\n hub whether the agent's submit landed (default\n 15000). Task completion comes from the HUB, never\n from the harness stream.\n --confirm-interval <ms> poll cadence inside that grace (default 1000)\n\n release options:\n --session <id> session whose claims to drain (else env\n OWENLOOP_SESSION). Agent-held claims re-offer;\n exec-held claims are drain-exempt (B3).\n --origin <url> hub origin (else settings.hubOrigin)\n\n settings (no options in v1):\n prints the resolved settings file path, whether it exists, each known\n knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,\n maxConcurrentAgents, workRoot, workRepo) with its value + provenance,\n and any unrecognized keys.\n settings.dispatchCap/stateDir are the lowest-precedence\n fallbacks for shift's --cap/--state-dir. NO secrets ever\n live in settings \u2014 credentials stay in owenloop's own store.\n\n sessions options:\n --all include 'dead' sessions (hidden by default \u2014\n a dead session can no longer be resumed)\n --json print the raw newest-per-step records, tokens\n included, instead of the table\n --cache-dir <p> override the resolved cache dir\n\n join options:\n --hub <origin> hub to redeem against (else settings.hubOrigin;\n one of the two is REQUIRED \u2014 the code never\n chooses the hub)\n --as <account> credential account to store under (default:\n the Scoped Identity name the hub returns)\n\n shift/hold/exec/prepare/release env:\n credentials come from owenloop's store \u2014 each role reads the\n agent:<account> slot for its origin (never the human slot); a\n missing slot refuses with a runnable 'owenloop login' command.\n OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release\n (default 'default'; shift uses --as, and\n stamps it onto dispatched holds/execs)\n OWENLOOP_TOKEN dev-only bearer override \u2014 when set, used\n verbatim and the store + account are\n bypassed (NOT the primary path)\n OWENLOOP_CACHE_DIR cache root\n OWENLOOP_STATE_DIR shift in-flight state dir\n OWENLOOP_SHIFT_LOG_DIR dir for the shift's shift.log and each\n worker's <run>.log; below --log-dir, above\n settings.shiftLogDir, default the state dir\n OWENLOOP_SHIFT_LOG_MAX_AGE_MS\n how long a worker's <run>.log is kept, in ms;\n below --log-max-age, above\n settings.shiftLogMaxAgeMs, default 14 days.\n Worker logs only \u2014 shift.log is never reaped\n OWENLOOP_SESSION hold session-holder tag / release drain target\n OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for\n hold/exec/agent-run's --shift (advisory\n only, never for auth/routing/dispatch)\n OWENLOOP_HARNESS agent-run harness id; below --harness, above\n the step def's 'harness' field\n OWENLOOP_WORK_ROOT root for per-RUN agent work dirs\n (<workRoot>/<workflow>/<run>); above\n settings.workRoot, default <cacheDir>/work.\n A hub-supplied OrderPacket.workdir still\n wins, and is never reaped.\n OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from\n as worktrees instead of plain dirs; above\n settings.workRepo, default off\n\n Credentials / accounts:\n owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY\n over owenloop's credential store \u2014 they never write credentials. Each\n role reads the agent:<account> slot for its origin (never the human\n slot); the account defaults to 'default'. 'owenloop work join' is the one\n deliberate provisioning-time writer: it stores the Scoped Identity token a hub\n redeem returns via owenloop's public storeCredential, once, at join time\n \u2014 not a runtime write.\n store / connect an account (run owenloop; owenloop work never writes it):\n owenloop login --hub <origin> --as agent:<account>\n (use --as agent for the default account)\n or provision a fresh box from a hub-issued join code:\n owenloop work join <code> --hub <origin>\n select an account at run time:\n --as <account> on shift / hold\n OWENLOOP_ACCOUNT on exec / prepare / release\n (shift resolves once and threads both channels)\n owenloop work does NOT list stored accounts \u2014 enumerating an origin's accounts\n is an owenloop-side capability; check owenloop for which slots are stored.\n\nExit codes:\n 0 success / help / version / lint clean or warnings-only\n 1 runtime failure (fetch/hub error, cache write) / lint found an error\n 2 usage error (unknown or missing role, missing required arg)\n 3 role not implemented yet (skeleton stub \u2014 lands in a later delivery)\n";
6
+ export declare const USAGE = "owenloop work \u2014 execution-side CLI companion to owenloop\n\nUsage:\n owenloop work hold --order <id> [options] hold an order with a heartbeating lease\n owenloop work exec <order-id> [options] run a command order in a self-leasing loop\n owenloop work agent-run <order-id> [options] host an agent order's step agent in a\n harness, in a self-leasing loop\n owenloop work prepare <workflow> [--origin <url>]\n fetch, cache & normalize step specs\n owenloop work lint <workflow-name | path> lint x.harness option bags in a def\n owenloop work sessions [--all] [--json] list this machine's recorded harness\n sessions and how to re-open them\n owenloop work approvals [--json] every tool call a worker is blocked on\n RIGHT NOW, waiting for a person\n owenloop work approvals approve|deny <wf>/<run> <tool-use-id> [--note <text>]\n answer one; the answer goes back to the\n still-blocked call, not to a later attempt\n owenloop work release --session <id> [options] drain a session's held claims\n owenloop work settings print the resolved settings file\n owenloop work join <code> [--hub <origin>] [--as <account>]\n redeem a join code and store the Scoped\n Identity credential (one-time provisioning)\n\nOptions:\n -h, --help show this help and exit 0\n --version print the owenloop work version and exit 0\n\n root shift options (run as owenloop shift start <crew...> | --all):\n <crew...> serve only these crews (positional, space\n separated); or --all for every crew on the key\n --all serve every crew on the key\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account to read + hand\n to dispatched holds/execs (default 'default')\n --name <n> Shift name (default <hostname>/<cwd>)\n --cap <n> max in-flight exec children (default 3)\n --poll-interval <ms> wake poll cadence (default 5000)\n --once bootstrap wake + one sweep, then exit (demo/e2e)\n --max-agents <n> max in-flight agent-run children, separate from\n --cap (default 4; else settings.maxConcurrentAgents)\n\t\t--exec-reserve <n> slots inside --cap that agent-run children may\n\t\t\t\t\tnot occupy, so exec orders always have room\n\t\t\t\t\t(default 1; else settings.execReserve; 0 disables)\n --local-queue-hold <ms> retain an undispatchable claim locally before\n\t\t\t\t\treturning it to the hub (default 0; else\n\t\t\t\t\tsettings.localQueueHoldMs; capped at 90000)\n --cache-dir/--state-dir <p> override the resolved dirs\n\n hold options:\n --order <workflow>/<run> the order to hold (or --order <run> --workflow)\n --workflow <wf> required when --order is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account (default\n 'default'; the shift stamps this into born-bound\n holds)\n --session <id> session-holder tag (else env OWENLOOP_SESSION;\n else an anon:<hostname>:<pid> fallback \u2014 a\n holder is always sent)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --ignore-stdin don't final-breath on stdin EOF (detached use)\n --never-release another process holds the claim; stop without\n releasing it (agent-run spawns its --mcp child\n this way \u2014 see hold.ts HOLDER OF RECORD)\n --mcp run as a stdio-MCP work-holder: tools get_order /\n submit, lease kept warm underneath (mutually\n exclusive with --ignore-stdin \u2014 stdin is the\n transport)\n\n exec options (usually spawned by shift, not run by hand):\n <workflow>/<run> the command order to run (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n\n agent-run options (spawned by the shift, not run by hand):\n <workflow>/<run> the agent order to host (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --harness <id> which registered harness hosts the step agent\n (below a selected roster candidate; else the\n step def's 'harness' field, then the first\n registered one)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --submit-grace <ms> after the turn ends, how long to keep asking the\n hub whether the agent's submit landed (default\n 15000). Task completion comes from the HUB, never\n from the harness stream.\n --confirm-interval <ms> poll cadence inside that grace (default 1000)\n\n release options:\n --session <id> session whose claims to drain (else env\n OWENLOOP_SESSION). Agent-held claims re-offer;\n exec-held claims are drain-exempt (B3).\n --origin <url> hub origin (else settings.hubOrigin)\n\n settings (no options in v1):\n prints the resolved settings file path, whether it exists, each known\n knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,\n maxConcurrentAgents, execReserve, localQueueHoldMs, workRoot, workRepo) with its value + provenance,\n and any unrecognized keys.\n settings.dispatchCap/stateDir are the lowest-precedence\n fallbacks for shift's --cap/--state-dir. NO secrets ever\n live in settings \u2014 credentials stay in owenloop's own store.\n\n sessions options:\n --all include 'dead' sessions (hidden by default \u2014\n a dead session can no longer be resumed)\n --json print the raw newest-per-step records, tokens\n included, instead of the table\n --cache-dir <p> override the resolved cache dir\n\n join options:\n --hub <origin> hub to redeem against (else settings.hubOrigin;\n one of the two is REQUIRED \u2014 the code never\n chooses the hub)\n --as <account> credential account to store under (default:\n the Scoped Identity name the hub returns)\n\n shift/hold/exec/prepare/release env:\n credentials come from owenloop's store \u2014 each role reads the\n agent:<account> slot for its origin (never the human slot); a\n missing slot refuses with a runnable 'owenloop login' command.\n OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release\n (default 'default'; shift uses --as, and\n stamps it onto dispatched holds/execs)\n OWENLOOP_TOKEN dev-only bearer override \u2014 when set, used\n verbatim and the store + account are\n bypassed (NOT the primary path)\n OWENLOOP_CACHE_DIR cache root\n OWENLOOP_STATE_DIR shift in-flight state dir\n OWENLOOP_SHIFT_LOG_DIR dir for the shift's shift.log and each\n worker's <run>.log; below --log-dir, above\n settings.shiftLogDir, default the state dir\n OWENLOOP_SHIFT_LOG_MAX_AGE_MS\n how long a worker's <run>.log is kept, in ms;\n below --log-max-age, above\n settings.shiftLogMaxAgeMs, default 14 days.\n Worker logs only \u2014 shift.log is never reaped\n OWENLOOP_SESSION hold session-holder tag / release drain target\n OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for\n hold/exec/agent-run's --shift (advisory\n only, never for auth/routing/dispatch)\n OWENLOOP_WORK_ROOT root for per-RUN agent work dirs\n (<workRoot>/<workflow>/<run>); above\n settings.workRoot, default <cacheDir>/work.\n A hub-supplied OrderPacket.workdir still\n wins, and is never reaped.\n OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from\n as worktrees instead of plain dirs; above\n settings.workRepo, default off\n\n Credentials / accounts:\n owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY\n over owenloop's credential store \u2014 they never write credentials. Each\n role reads the agent:<account> slot for its origin (never the human\n slot); the account defaults to 'default'. 'owenloop work join' is the one\n deliberate provisioning-time writer: it stores the Scoped Identity token a hub\n redeem returns via owenloop's public storeCredential, once, at join time\n \u2014 not a runtime write.\n store / connect an account (run owenloop; owenloop work never writes it):\n owenloop login --hub <origin> --as agent:<account>\n (use --as agent for the default account)\n or provision a fresh box from a hub-issued join code:\n owenloop work join <code> --hub <origin>\n select an account at run time:\n --as <account> on shift / hold\n OWENLOOP_ACCOUNT on exec / prepare / release\n (shift resolves once and threads both channels)\n owenloop work does NOT list stored accounts \u2014 enumerating an origin's accounts\n is an owenloop-side capability; check owenloop for which slots are stored.\n\nExit codes:\n 0 success / help / version / lint clean or warnings-only\n 1 runtime failure (fetch/hub error, cache write) / lint found an error\n 2 usage error (unknown or missing role, missing required arg)\n 3 role not implemented yet (skeleton stub \u2014 lands in a later delivery)\n";
@@ -43,6 +43,12 @@ Options:
43
43
  --once bootstrap wake + one sweep, then exit (demo/e2e)
44
44
  --max-agents <n> max in-flight agent-run children, separate from
45
45
  --cap (default 4; else settings.maxConcurrentAgents)
46
+ --exec-reserve <n> slots inside --cap that agent-run children may
47
+ not occupy, so exec orders always have room
48
+ (default 1; else settings.execReserve; 0 disables)
49
+ --local-queue-hold <ms> retain an undispatchable claim locally before
50
+ returning it to the hub (default 0; else
51
+ settings.localQueueHoldMs; capped at 90000)
46
52
  --cache-dir/--state-dir <p> override the resolved dirs
47
53
 
48
54
  hold options:
@@ -86,8 +92,9 @@ Options:
86
92
  --workflow <wf> required when the order-id is a bare run id
87
93
  --origin <url> hub origin (else settings.hubOrigin)
88
94
  --harness <id> which registered harness hosts the step agent
89
- (else env OWENLOOP_HARNESS, else the step def's
90
- 'harness' field, else the first registered one)
95
+ (below a selected roster candidate; else the
96
+ step def's 'harness' field, then the first
97
+ registered one)
91
98
  --shift <id> dispatching Shift's self-declared id (else
92
99
  env OWENLOOP_SHIFT_ID); advisory only
93
100
  --heartbeat-interval <ms> lease renew cadence (default 60000)
@@ -108,7 +115,7 @@ Options:
108
115
  settings (no options in v1):
109
116
  prints the resolved settings file path, whether it exists, each known
110
117
  knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,
111
- maxConcurrentAgents, workRoot, workRepo) with its value + provenance,
118
+ maxConcurrentAgents, execReserve, localQueueHoldMs, workRoot, workRepo) with its value + provenance,
112
119
  and any unrecognized keys.
113
120
  settings.dispatchCap/stateDir are the lowest-precedence
114
121
  fallbacks for shift's --cap/--state-dir. NO secrets ever
@@ -152,8 +159,6 @@ Options:
152
159
  OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for
153
160
  hold/exec/agent-run's --shift (advisory
154
161
  only, never for auth/routing/dispatch)
155
- OWENLOOP_HARNESS agent-run harness id; below --harness, above
156
- the step def's 'harness' field
157
162
  OWENLOOP_WORK_ROOT root for per-RUN agent work dirs
158
163
  (<workRoot>/<workflow>/<run>); above
159
164
  settings.workRoot, default <cacheDir>/work.
@@ -0,0 +1,7 @@
1
+ /** Resolve requested feedback first, then the order modifier hint, then default. */
2
+ export declare function resolveModifierInit(args: string[], env?: Record<string, string | undefined>): {
3
+ value?: string;
4
+ error?: string;
5
+ usage?: true;
6
+ };
7
+ export declare function runModifierInit(args: string[], env?: Record<string, string | undefined>): number;
@@ -0,0 +1,73 @@
1
+ import { readFileSync } from 'node:fs';
2
+ function usage(message) {
3
+ process.stderr.write(`owenloop util modifier-init: ${message}\n`);
4
+ process.stderr.write('usage: owenloop util modifier-init --default <value>\n');
5
+ return 2;
6
+ }
7
+ function feedbackRequested(env) {
8
+ const inline = env['OWENLOOP_FEEDBACK'];
9
+ const file = env['OWENLOOP_FEEDBACK_FILE'];
10
+ let raw;
11
+ if (inline !== undefined)
12
+ raw = inline;
13
+ else if (file !== undefined)
14
+ raw = readFileSync(file, 'utf8');
15
+ if (raw === undefined)
16
+ return undefined;
17
+ const feedback = JSON.parse(raw);
18
+ if (!Array.isArray(feedback))
19
+ throw new Error('OWENLOOP_FEEDBACK must be a JSON feedback array');
20
+ let newest;
21
+ let position = 0;
22
+ for (const owed of feedback) {
23
+ if (!Array.isArray(owed.reasons))
24
+ continue;
25
+ const rejection = [...owed.reasons].reverse().find((reason) => reason.action === 'reject');
26
+ position++;
27
+ if (typeof rejection?.requested !== 'string')
28
+ continue;
29
+ const at = typeof rejection.at === 'number' ? rejection.at : Number.NEGATIVE_INFINITY;
30
+ if (newest === undefined
31
+ || at > newest.at
32
+ || (at === newest.at && position > newest.position)) {
33
+ newest = { requested: rejection.requested, at, position };
34
+ }
35
+ }
36
+ return newest?.requested;
37
+ }
38
+ /** Resolve requested feedback first, then the order modifier hint, then default. */
39
+ export function resolveModifierInit(args, env = process.env) {
40
+ let fallback;
41
+ for (let i = 0; i < args.length; i++) {
42
+ const arg = args[i];
43
+ if (arg !== '--default')
44
+ return { error: `unknown argument '${arg}'`, usage: true };
45
+ if (fallback !== undefined)
46
+ return { error: '--default may only be specified once', usage: true };
47
+ fallback = args[++i];
48
+ if (fallback === undefined)
49
+ return { error: 'missing value for --default', usage: true };
50
+ }
51
+ if (fallback === undefined)
52
+ return { error: 'missing required option: --default', usage: true };
53
+ try {
54
+ const value = feedbackRequested(env) ?? env['OWENLOOP_MODIFIER'] ?? fallback;
55
+ if (value === '' || /\s/.test(value))
56
+ return { error: 'resolved modifier must be a single word' };
57
+ return { value };
58
+ }
59
+ catch (e) {
60
+ return { error: e instanceof Error ? e.message : String(e) };
61
+ }
62
+ }
63
+ export function runModifierInit(args, env = process.env) {
64
+ const result = resolveModifierInit(args, env);
65
+ if (result.error !== undefined) {
66
+ if (result.usage)
67
+ return usage(result.error);
68
+ process.stderr.write(`owenloop util modifier-init: ${result.error}\n`);
69
+ return 3;
70
+ }
71
+ process.stdout.write(`${result.value}\n`);
72
+ return 0;
73
+ }
@@ -30,10 +30,15 @@ export declare const BUNDLE_GZIP_LEVEL = 9;
30
30
  */
31
31
  export declare function buildCanonicalTar(files: CanonicalFile[], limits?: TarLimits): Buffer;
32
32
  /**
33
- * Gzip `tar` with fixed options and a normalized header: no FEXTRA/FNAME/
34
- * FCOMMENT, mtime bytes zeroed, OS byte forced to 0. Node's zlib reports
35
- * OS 19 on Darwin and embeds the clock in mtime by default — patch both so
36
- * the output is byte-identical across platforms and times.
33
+ * Gzip `tar` with fixed options and controlled header ranges: magic (bytes
34
+ * 0-1), CM (2), FLG (3), MTIME (4-7), and OS (9). No FEXTRA/FNAME/FCOMMENT
35
+ * fields are emitted. Node's zlib reports OS 19 on Darwin and embeds the clock
36
+ * in mtime by default, so patch bytes 4-7 and 9 to fixed values. XFL (byte 8)
37
+ * is supplied by zlib and deliberately left unnormalized.
38
+ *
39
+ * The compressed DEFLATE payload is not normalized: linked zlib builds can
40
+ * emit different valid streams for the same input. Bundle identity is the
41
+ * SHA-256 digest of the uncompressed canonical tar.
37
42
  */
38
43
  export declare function gzipDeterministic(tar: Uint8Array): Buffer;
39
44
  /** A file collected from a bundle source tree. */
@@ -146,10 +146,15 @@ export function buildCanonicalTar(files, limits = DEFAULT_TAR_LIMITS) {
146
146
  return tar;
147
147
  }
148
148
  /**
149
- * Gzip `tar` with fixed options and a normalized header: no FEXTRA/FNAME/
150
- * FCOMMENT, mtime bytes zeroed, OS byte forced to 0. Node's zlib reports
151
- * OS 19 on Darwin and embeds the clock in mtime by default — patch both so
152
- * the output is byte-identical across platforms and times.
149
+ * Gzip `tar` with fixed options and controlled header ranges: magic (bytes
150
+ * 0-1), CM (2), FLG (3), MTIME (4-7), and OS (9). No FEXTRA/FNAME/FCOMMENT
151
+ * fields are emitted. Node's zlib reports OS 19 on Darwin and embeds the clock
152
+ * in mtime by default, so patch bytes 4-7 and 9 to fixed values. XFL (byte 8)
153
+ * is supplied by zlib and deliberately left unnormalized.
154
+ *
155
+ * The compressed DEFLATE payload is not normalized: linked zlib builds can
156
+ * emit different valid streams for the same input. Bundle identity is the
157
+ * SHA-256 digest of the uncompressed canonical tar.
153
158
  */
154
159
  export function gzipDeterministic(tar) {
155
160
  const gz = gzipSync(Buffer.from(tar), { level: BUNDLE_GZIP_LEVEL });
@@ -62,6 +62,56 @@ export declare function capabilityName(capability: string): string;
62
62
  * compose onto, and inventing a lone `:deep` would be meaningless.
63
63
  */
64
64
  export declare function composeCapabilities(authored: readonly string[] | undefined, modifier: string | undefined): string[];
65
+ /**
66
+ * A reroute decision the caller has already made, keyed by the composed
67
+ * capability the engine would otherwise offer.
68
+ *
69
+ * `{ 'build:express': 'build:standard' }` means: when this offer composes to
70
+ * `build:express`, offer `build:standard` instead. The engine attaches no
71
+ * meaning to either side and performs no lookup — it substitutes the string it
72
+ * is handed, exactly like `matchModes`, and for the same reason: deciding a
73
+ * reroute requires reading `capability_routes`, which the pure engine has never
74
+ * seen.
75
+ *
76
+ * SINGLE HOP, BY CONTRACT. A rewrite target is never itself looked up in the
77
+ * map. A caller with a multi-step rule chain resolves the whole chain and hands
78
+ * the engine the final answer, so a cycle is impossible here rather than merely
79
+ * bounded.
80
+ */
81
+ export type CapabilityRewrites = Readonly<Record<string, string>>;
82
+ /**
83
+ * Crews matched per SERVED capability, supplied by the caller that owns the
84
+ * routing table. Keys are post-reroute capability strings; values are crew
85
+ * names in match order. Hub → worker; unrelated to `serve_crews`.
86
+ */
87
+ export type CrewStamps = Readonly<Record<string, readonly string[]>>;
88
+ /**
89
+ * Substitute a caller's reroute decisions into a composed offer.
90
+ *
91
+ * Returns the offer to use plus — only when something actually changed — the
92
+ * list it replaced. The two are kept as SEPARATE fields rather than folded into
93
+ * one, because a rerouted order has two different true answers to "which
94
+ * capability is this?": the one being served (`offered`, which is what a shift
95
+ * resolves its model against) and the one that was asked for (`reroutedFrom`,
96
+ * which is what an operator wrote in the def). Collapsing them would make an
97
+ * order's routing history unrecoverable.
98
+ *
99
+ * Duplicates are removed FROM A REWRITTEN OFFER: two authored capabilities may
100
+ * reroute onto the same target, and an offer listing it twice would
101
+ * double-count in nothing but would read as a mistake.
102
+ *
103
+ * An offer no rule touched is returned VERBATIM, duplicates included. A step
104
+ * may author `capabilities: ['a', 'a']` — `defs.ts` validates each entry but
105
+ * never checks for duplicates — and `composeCapabilities` preserves that
106
+ * multiplicity, so deduplicating an untouched offer would change the stamped
107
+ * `order.capabilities` for a caller that supplied no rewrites at all. Dedup is
108
+ * a consequence of rerouting, not a tidy-up applied on the way past: with no
109
+ * applicable rule, this function returns byte-for-byte what it was handed.
110
+ */
111
+ export declare function applyCapabilityRewrites(offered: readonly string[], rewrites: CapabilityRewrites): {
112
+ offered: string[];
113
+ reroutedFrom?: string[];
114
+ };
65
115
  /**
66
116
  * The claim-side match: may a caller presenting `caller` claim a step offered
67
117
  * on `offered`?
@@ -55,6 +55,44 @@ export function composeCapabilities(authored, modifier) {
55
55
  return [...authored];
56
56
  return authored.map((c) => `${c}${MODIFIER_SEPARATOR}${modifier}`);
57
57
  }
58
+ /**
59
+ * Substitute a caller's reroute decisions into a composed offer.
60
+ *
61
+ * Returns the offer to use plus — only when something actually changed — the
62
+ * list it replaced. The two are kept as SEPARATE fields rather than folded into
63
+ * one, because a rerouted order has two different true answers to "which
64
+ * capability is this?": the one being served (`offered`, which is what a shift
65
+ * resolves its model against) and the one that was asked for (`reroutedFrom`,
66
+ * which is what an operator wrote in the def). Collapsing them would make an
67
+ * order's routing history unrecoverable.
68
+ *
69
+ * Duplicates are removed FROM A REWRITTEN OFFER: two authored capabilities may
70
+ * reroute onto the same target, and an offer listing it twice would
71
+ * double-count in nothing but would read as a mistake.
72
+ *
73
+ * An offer no rule touched is returned VERBATIM, duplicates included. A step
74
+ * may author `capabilities: ['a', 'a']` — `defs.ts` validates each entry but
75
+ * never checks for duplicates — and `composeCapabilities` preserves that
76
+ * multiplicity, so deduplicating an untouched offer would change the stamped
77
+ * `order.capabilities` for a caller that supplied no rewrites at all. Dedup is
78
+ * a consequence of rerouting, not a tidy-up applied on the way past: with no
79
+ * applicable rule, this function returns byte-for-byte what it was handed.
80
+ */
81
+ export function applyCapabilityRewrites(offered, rewrites) {
82
+ if (offered.length === 0)
83
+ return { offered: [] };
84
+ let changed = false;
85
+ const out = [];
86
+ for (const c of offered) {
87
+ const target = rewrites[c];
88
+ const next = target ?? c;
89
+ if (target !== undefined && target !== c)
90
+ changed = true;
91
+ if (!out.includes(next))
92
+ out.push(next);
93
+ }
94
+ return changed ? { offered: out, reroutedFrom: [...offered] } : { offered: [...offered] };
95
+ }
58
96
  /** True when one caller capability satisfies one offered capability under `mode`. */
59
97
  function matchesOne(offered, caller, mode) {
60
98
  return mode === 'exact' ? caller === offered : capabilityName(caller) === capabilityName(offered);
package/dist/src/cli.d.ts CHANGED
@@ -37,6 +37,7 @@ import { PrincipalKeyManager } from './crypto/keys.ts';
37
37
  import type { LineStream } from './mcp/server.ts';
38
38
  import type { BundleIngestor, PreCommitVerifier } from './store/index.ts';
39
39
  import type { AgentIdentitySummary, Keychain } from './hub.ts';
40
+ import '../packages/work/src/harnesses.ts';
40
41
  export type { Keychain } from './hub.ts';
41
42
  export type HarnessId = 'claude-code' | 'codex';
42
43
  export interface CliIO {
@@ -107,7 +108,7 @@ export interface CliIO {
107
108
  /** Optional resolver override for hermetic tests of a missing bundled marketplace. */
108
109
  resolveBundledMarketplaceRoot?: (harness: HarnessId) => string | null;
109
110
  /**
110
- * The principal signing-key manager for `setup`'s `[4/7] signing keys` step.
111
+ * The principal signing-key manager for `setup`'s `[4/8] signing keys` step.
111
112
  * Injectable so setup tests never reach the developer's real `ssh-keygen`,
112
113
  * Keychain, libsecret, SSH agent, or `$HOME` (`makeFakePrincipalKeys` in
113
114
  * test/hubkit.ts). Default: a real `PrincipalKeyManager` over `io.env`.
@@ -168,6 +169,19 @@ export type AddSource = {
168
169
  * the reason), and a URL is classified by scheme alone.
169
170
  */
170
171
  export declare function classifyAddSource(spec: string): AddSource;
172
+ export interface CrewRosterInstallOptions {
173
+ /** Test seam for a temporary-name collision before target installation. */
174
+ tempName?: () => string;
175
+ /** Test seam for a short/failed temporary write after the file was created. */
176
+ writeTemp?: (path: string, contents: string) => void;
177
+ }
178
+ /**
179
+ * Install a fully-written strongest-layer roster without replacing an
180
+ * operator's file. Only EEXIST from the final exclusive link is interpreted
181
+ * as an existing target; failures creating its parent or temporary file stay
182
+ * failures instead of being misreported as a harmless skip.
183
+ */
184
+ export declare function installCrewRosterIfAbsent(path: string, contents: string, options?: CrewRosterInstallOptions): 'created' | 'existing';
171
185
  /**
172
186
  * Coerce a raw string (a hostname) into a valid agent account name, or `''` when
173
187
  * nothing usable survives. Lowercase; drop every character outside the account