owenloop 0.5.7 → 0.5.8

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 (65) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +3 -6
  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 +39 -25
  6. package/dist/packages/work/src/agent/loop.js +102 -50
  7. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  8. package/dist/packages/work/src/exec/loop.js +37 -15
  9. package/dist/packages/work/src/harness/child-env.js +4 -5
  10. package/dist/packages/work/src/harness/codex.js +3 -4
  11. package/dist/packages/work/src/harness/session-store.d.ts +63 -3
  12. package/dist/packages/work/src/harness/session-store.js +104 -9
  13. package/dist/packages/work/src/hub/types.d.ts +3 -3
  14. package/dist/packages/work/src/roles/agent-run.js +48 -42
  15. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  16. package/dist/packages/work/src/roles/sessions.js +9 -2
  17. package/dist/packages/work/src/roles/settings.js +1 -1
  18. package/dist/packages/work/src/settings/roster.d.ts +21 -0
  19. package/dist/packages/work/src/settings/roster.js +80 -0
  20. package/dist/packages/work/src/settings/settings.d.ts +12 -24
  21. package/dist/packages/work/src/settings/settings.js +17 -35
  22. package/dist/packages/work/src/shift/runtime.js +2 -10
  23. package/dist/packages/work/src/shift/spawn.d.ts +6 -53
  24. package/dist/packages/work/src/shift/spawn.js +28 -66
  25. package/dist/packages/work/src/usage.d.ts +1 -1
  26. package/dist/packages/work/src/usage.js +3 -4
  27. package/dist/src/capabilities.d.ts +44 -0
  28. package/dist/src/capabilities.js +38 -0
  29. package/dist/src/cli.d.ts +1 -0
  30. package/dist/src/cli.js +460 -5
  31. package/dist/src/config-dir.d.ts +13 -18
  32. package/dist/src/config-dir.js +15 -23
  33. package/dist/src/credentials.d.ts +1 -1
  34. package/dist/src/credentials.js +1 -1
  35. package/dist/src/crypto/records.d.ts +1 -0
  36. package/dist/src/crypto/records.js +6 -0
  37. package/dist/src/crypto/trust-roots.d.ts +2 -2
  38. package/dist/src/crypto/trust-roots.js +2 -2
  39. package/dist/src/engine.d.ts +14 -0
  40. package/dist/src/engine.js +21 -13
  41. package/dist/src/global-config.d.ts +4 -7
  42. package/dist/src/global-config.js +4 -7
  43. package/dist/src/hub.d.ts +207 -5
  44. package/dist/src/hub.js +263 -3
  45. package/dist/src/index.d.ts +2 -2
  46. package/dist/src/index.js +1 -1
  47. package/dist/src/schemas/index.d.ts +8 -0
  48. package/dist/src/schemas/order.v1.schema.json +6 -1
  49. package/dist/src/store/pre-commit-verifier.js +1 -1
  50. package/dist/src/types.d.ts +24 -4
  51. package/dist/src/work-settings.d.ts +2 -4
  52. package/dist/src/work-settings.js +2 -4
  53. package/docs/agent-runner.md +2 -2
  54. package/docs/bundles.md +3 -1
  55. package/docs/cli.md +295 -101
  56. package/docs/crypto.md +14 -14
  57. package/docs/routing.md +607 -0
  58. package/docs/shift-logs.md +22 -6
  59. package/package.json +1 -1
  60. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  61. package/plugins/claude-code/plugin/.mcp.json +1 -1
  62. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  63. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  64. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  65. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
@@ -62,9 +62,9 @@ import { createApprovalRequester } from "./approvals.js";
62
62
  import { createLeaseLoop } from "../lease/loop.js";
63
63
  import { isResumeUnavailable } from "../harness/contract.js";
64
64
  import { preflightStepPermissions } from "../harness/permissions.js";
65
- import { orderId } from "../harness/session-store.js";
65
+ import { orderId, } from "../harness/session-store.js";
66
66
  import { buildOwenloopMcp, renderBrief, renderRejection, renderReplayBrief, } from "./brief.js";
67
- import { resolveCapabilityModel, } from "./capability-model.js";
67
+ import { resolveCapabilityCandidates, selectCandidate, } from "./capability-model.js";
68
68
  /** Default confirm-phase cadence: one `get_order` per second. */
69
69
  export const DEFAULT_CONFIRM_INTERVAL_MS = 1_000;
70
70
  /** Default confirm-phase bound: give the hub 15s to show the submit's outcome. */
@@ -124,12 +124,48 @@ function briefOwes(packet) {
124
124
  * abstract rung with no meaning left, and reading it as a model id would put a
125
125
  * literal `strong` on the wire to a vendor.
126
126
  */
127
- export function resolveOrderRouting(packet, map) {
127
+ export function resolveOrderRouting(packet, rosters, stepHarness, isAvailable) {
128
128
  const capabilities = packet.capabilities ?? [];
129
129
  if (capabilities.length === 0)
130
130
  return { kind: 'unrouted' };
131
- const resolution = map === undefined ? undefined : resolveCapabilityModel(map, capabilities);
132
- return resolution === undefined ? { kind: 'refused', capabilities } : { kind: 'resolved', resolution };
131
+ let firstHarnessPolicy;
132
+ for (const roster of rosters ?? []) {
133
+ // Preserve arbitrary capability names through the boundary between the
134
+ // provenance-bearing merged roster and the candidate-only selector.
135
+ const candidateRows = Object.create(null);
136
+ for (const capability of Object.keys(roster)) {
137
+ if (!Object.prototype.hasOwnProperty.call(roster, capability))
138
+ continue;
139
+ candidateRows[capability] = roster[capability].candidates;
140
+ }
141
+ const candidates = resolveCapabilityCandidates(candidateRows, capabilities);
142
+ if (candidates === undefined)
143
+ continue;
144
+ const outcome = selectCandidate(candidates.candidates, stepHarness, isAvailable);
145
+ if (outcome.kind === 'selected') {
146
+ return {
147
+ kind: 'resolved',
148
+ capability: candidates.capability,
149
+ match: candidates.match,
150
+ harness: outcome.candidate.harness,
151
+ model: outcome.candidate.model,
152
+ effort: outcome.candidate.effort,
153
+ };
154
+ }
155
+ if (outcome.kind === 'harness-policy' && firstHarnessPolicy === undefined) {
156
+ firstHarnessPolicy = { offered: outcome.offered, stepHarness };
157
+ }
158
+ }
159
+ if (firstHarnessPolicy !== undefined) {
160
+ return {
161
+ kind: 'refused',
162
+ capabilities,
163
+ reason: 'harness-policy',
164
+ offered: firstHarnessPolicy.offered,
165
+ ...(firstHarnessPolicy.stepHarness !== undefined ? { stepHarness: firstHarnessPolicy.stepHarness } : {}),
166
+ };
167
+ }
168
+ return { kind: 'refused', capabilities, reason: 'unresolvable-capability' };
133
169
  }
134
170
  /**
135
171
  * Poll `get_order` at `intervalMs` for at most `graceMs`, answering ONE
@@ -184,6 +220,10 @@ export function createAgentRunLoop(opts) {
184
220
  let sessionRef;
185
221
  let adapterId = '';
186
222
  let stepName = '';
223
+ /** `OrderPacket.key`, set beside `stepName` when the packet arrives. Typed
224
+ * `undefined`-until-known rather than defaulted to `''`, because `''` is the
225
+ * REAL key of an unfanned step and must not double as "not known yet". */
226
+ let stepKey;
187
227
  let attempt = 1;
188
228
  let createdAt = 0;
189
229
  let recordCwd = opts.cwd;
@@ -229,6 +269,12 @@ export function createAgentRunLoop(opts) {
229
269
  workflow,
230
270
  run: runId,
231
271
  step: stepName,
272
+ // Written whenever the packet is known — which, given the guard above, is
273
+ // always. The conditional spread exists so the field is OMITTED rather
274
+ // than forged if that ever stops being true: an absent `key` means "cannot
275
+ // be attributed to a task" and costs a cold start, while a wrong `key`
276
+ // would hand a worker another task's session.
277
+ ...(stepKey !== undefined ? { key: stepKey } : {}),
232
278
  order,
233
279
  attempt,
234
280
  harness: sessionRef?.harness ?? adapterId,
@@ -337,21 +383,21 @@ export function createAgentRunLoop(opts) {
337
383
  * An `unrouted` order is not reported at all: the payload's `capability` is
338
384
  * required and non-empty on the hub side, and there is no capability to name.
339
385
  */
340
- async function reportResolution(routing, harness) {
386
+ async function reportResolution(routing) {
341
387
  if (routing.kind === 'unrouted')
342
388
  return;
343
389
  const payload = routing.kind === 'resolved'
344
390
  ? {
345
- capability: routing.resolution.capability,
346
- match: routing.resolution.match,
347
- model: routing.resolution.model,
348
- effort: routing.resolution.effort,
349
- harness,
391
+ capability: routing.capability,
392
+ match: routing.match,
393
+ model: routing.model,
394
+ effort: routing.effort,
395
+ harness: routing.harness,
350
396
  }
351
397
  : // The refusal names the capability the order was OFFERED under — the
352
398
  // first one — because that is the row an operator has to add. Model
353
399
  // and effort are absent: nothing was selected.
354
- { capability: routing.capabilities[0] ?? '', match: 'refused', harness };
400
+ { capability: routing.capabilities[0] ?? '', match: 'refused' };
355
401
  try {
356
402
  await opts.hub.reportResolution({ workflow, run: runId, resolution: payload });
357
403
  }
@@ -412,6 +458,7 @@ export function createAgentRunLoop(opts) {
412
458
  }
413
459
  }
414
460
  stepName = packet.step;
461
+ stepKey = packet.key;
415
462
  recordCwd = packet.workdir ?? opts.cwd;
416
463
  // MACHINE POLICY. The operator who started this shift named the directories
417
464
  // work may happen in (`owenloop shift start --work-root`, or
@@ -454,7 +501,26 @@ export function createAgentRunLoop(opts) {
454
501
  /** `material` is a `let`, so its null-narrowing does not survive into the
455
502
  * closures below. This const carries the narrowing across. */
456
503
  const step = material;
457
- const resolution = opts.resolveAdapter(step.harness);
504
+ // ---- ROUTING: select a roster candidate before resolving an adapter ----
505
+ //
506
+ // Phase 1's crew order is interim. Phase 2 replaces these locally supplied
507
+ // rosters with crew stamps the hub puts on each offer.
508
+ const routing = resolveOrderRouting(packet, opts.rosters, step.harness, opts.harnessAvailable);
509
+ await reportResolution(routing);
510
+ if (routing.kind === 'refused') {
511
+ if (routing.reason === 'harness-policy') {
512
+ opts.err(`owenloop work agent-run: step '${packet.step}' declares harness '${routing.stepHarness ?? ''}', ` +
513
+ `but its roster candidates offer [${(routing.offered ?? []).join(', ')}] — releasing`);
514
+ return releaseWith('incompatible-harness-policy', 'incompatible-harness-policy');
515
+ }
516
+ opts.err(`owenloop work agent-run: no crew roster row for ${order} — the order's capabilities ` +
517
+ `[${routing.capabilities.join(', ')}] match neither an exact row nor a bare name row in 'roster'. ` +
518
+ `Add a candidate array for one of them and restart the shift. Releasing — this shift will not pick ` +
519
+ `a model it was not told to use.`);
520
+ return releaseWith('unresolvable-capability', 'unresolvable-capability');
521
+ }
522
+ const chosenHarnessId = routing.kind === 'resolved' ? routing.harness : undefined;
523
+ const resolution = opts.resolveAdapter(chosenHarnessId, step.harness);
458
524
  adapterId = resolution.id;
459
525
  if (resolution.adapter === undefined) {
460
526
  const known = resolution.registered.length > 0 ? resolution.registered.join(', ') : '<none>';
@@ -465,27 +531,24 @@ export function createAgentRunLoop(opts) {
465
531
  /** The same object as `adapter`, but narrowed — the module-scope `adapter`
466
532
  * stays `HarnessAdapter | undefined` for `teardown`/`stop`. */
467
533
  const active = resolution.adapter;
468
- attempt = opts.nextAttempt(workflow, runId, packet.step);
534
+ /** This firing's engine task. Built once, from the packet, and used for both
535
+ * the attempt count and the Phase 4 resume lookup so the two can never
536
+ * disagree about which history they are reading. */
537
+ const task = { workflow, step: packet.step, key: packet.key };
538
+ attempt = opts.nextAttempt(task);
469
539
  const spec = {
470
540
  workflow,
471
541
  run: runId,
472
542
  origin: opts.origin,
473
543
  account: opts.account,
474
544
  ...(opts.shiftId !== undefined ? { shiftId: opts.shiftId } : {}),
475
- // Straight from the packet, not from settings: the modifier is the hub's
476
- // statement about the RUN, and a shift has no say in it.
477
545
  ...(packet.modifier !== undefined ? { modifier: packet.modifier } : {}),
478
546
  ...(packet.escalated === true ? { escalated: true } : {}),
479
547
  owes: briefOwes(packet),
480
548
  };
481
- // Permissions arrive PRE-NORMALIZED in the spec. `prepare` ran
482
- // `normalizeStepPermissions` over the step's `x.harness` options at cache
483
- // time, so this loop never looks inside an extension bag and never has a bag
484
- // key — vendor-keyed lookup does not exist in neutral code any more.
485
549
  const permissions = step.permissions;
486
550
  // Mandatory final-boundary preflight. Common checks run first, followed by
487
- // the selected adapter's exact capability check. A refusal starts neither a
488
- // cold session nor a resumed provider process; the held claim is released.
551
+ // the selected adapter's exact capability check.
489
552
  const policyIssues = [
490
553
  ...preflightStepPermissions(permissions),
491
554
  ...active.preflight(permissions),
@@ -497,35 +560,13 @@ export function createAgentRunLoop(opts) {
497
560
  }
498
561
  return releaseWith('incompatible-harness-policy', 'incompatible-harness-policy');
499
562
  }
500
- // ---- ROUTING: which model serves this order, and telling the hub --------
501
- //
502
- // DELIBERATELY THE LAST GATE BEFORE DISPATCH, and deliberately AFTER every
503
- // launch gate above (misroute, consumed verification, step spec, adapter,
504
- // harness policy). Plan §3: the launch gates block on a malformed order
505
- // before model selection is even attempted, so a refusal never has to be
506
- // explained in terms of a model the order was never going to reach.
507
- const routing = resolveOrderRouting(packet, opts.capabilityModels);
508
- // Plan §6: the record must exist BEFORE tokens are spent, which is why this
509
- // is a dedicated verb and not a field on the next heartbeat. It is reported
510
- // on the refusal path too — a refusal is a true observation of what this
511
- // shift resolved, and the whole point of the report is that the hub can say
512
- // why an order did or did not run.
513
- await reportResolution(routing, resolution.id);
514
- if (routing.kind === 'refused') {
515
- opts.err(`owenloop work agent-run: no settings row for ${order} — the order's capabilities ` +
516
- `[${routing.capabilities.join(', ')}] match neither an exact row nor a bare name row in ` +
517
- `'capabilityModels'. Add a row for one of them (a bare row such as ` +
518
- `'${routing.capabilities[0]?.split(':')[0] ?? ''}' covers every modifier) and restart the shift. ` +
519
- `Releasing — this shift will not pick a model it was not told to use.`);
520
- return releaseWith('unresolvable-capability', 'unresolvable-capability');
521
- }
522
563
  if (routing.kind === 'unrouted') {
523
- opts.err(`owenloop work agent-run: ${order} carries no capabilities, so no settings row applies — ` +
524
- `running on '${resolution.id}''s own default model.`);
564
+ opts.err(`owenloop work agent-run: ${order} carries no capabilities, so no crew roster row applies — ` +
565
+ `running on '${resolution.id}'s own default model.`);
525
566
  }
526
567
  else {
527
- opts.out(`owenloop work agent-run: ${order} resolved '${routing.resolution.capability}' ` +
528
- `(${routing.resolution.match} row) → ${routing.resolution.model} at ${routing.resolution.effort}`);
568
+ opts.out(`owenloop work agent-run: ${order} resolved '${routing.capability}' (${routing.match} row) → ` +
569
+ `${routing.harness}/${routing.model} at ${routing.effort}`);
529
570
  }
530
571
  // ---- PHASE 4: resume or cold replay? -----------------------------------
531
572
  //
@@ -533,7 +574,7 @@ export function createAgentRunLoop(opts) {
533
574
  // resume preconditions. `renderRejection` reads `packet.owes[].reasons`
534
575
  // filtered to `at > prev.deliveredReasonAt` — the packet's `owes` IS the set
535
576
  // of paths being re-armed, so no extra path filter is needed here.
536
- const prev = opts.latestSession?.(workflow, runId, packet.step) ?? null;
577
+ const prev = opts.latestSession?.(task) ?? null;
537
578
  const dirExists = opts.dirExists ?? existsSync;
538
579
  const delta = renderRejection({
539
580
  packet,
@@ -553,6 +594,14 @@ export function createAgentRunLoop(opts) {
553
594
  // dirExists(prev.cwd) a reaped work dir invalidates the session
554
595
  // delta.message !== '' nothing new to say — a resume that says
555
596
  // nothing spends a turn communicating nothing
597
+ //
598
+ // ON `prev.cwd === recordCwd` NOW THAT `prev` CAN ACTUALLY BE FOUND. An order
599
+ // carrying an explicit `packet.workdir` names the same directory on every
600
+ // firing, so this passes and the resume happens. An order with no `workdir`
601
+ // falls back to `<workRoot>/<workflow>/<run>` (see `agent/workdir.ts`), which
602
+ // moves with the run id — so this declines and the firing starts cold. That
603
+ // is the guard doing its job, not a leftover: the previous session's files
604
+ // genuinely are in a directory this firing is not working in.
556
605
  const resumable = prev !== null &&
557
606
  prev.token !== '' &&
558
607
  prev.harness === resolution.id &&
@@ -604,8 +653,11 @@ export function createAgentRunLoop(opts) {
604
653
  run: opts.run,
605
654
  onEvent: (e) => opts.out(`owenloop work agent-run: approval ${e.kind} — ${e.text}`),
606
655
  });
656
+ // A resolved crew-roster candidate wins over the step's authored harness,
657
+ // model, and effort. The harness was already selected above; these values
658
+ // keep the established rule for the adapter start arguments.
607
659
  const resolvedModel = routing.kind === 'resolved'
608
- ? { model: routing.resolution.model, effort: routing.resolution.effort }
660
+ ? { model: routing.model, effort: routing.effort }
609
661
  : undefined;
610
662
  const deliverArgs = {
611
663
  cwd: recordCwd,
@@ -62,9 +62,9 @@ export interface FetchedStep {
62
62
  * LIFTED by `validateFetchedDef` from `x.harness.id`, or from a top-level
63
63
  * `harness` key when the def carries one (top-level WINS — forward compat for
64
64
  * an owenloop grammar that promotes the field). Declaration only: nothing
65
- * validates the id here; `src/roles/agent-run.ts` resolves it, ranking BELOW
66
- * `--harness` and `OWENLOOP_HARNESS`, and fails honestly when the id names no
67
- * registered adapter.
65
+ * validates the id here; `src/roles/agent-run.ts` uses it after a selected
66
+ * roster candidate and an explicit `--harness`, and fails honestly when the
67
+ * id names no registered adapter.
68
68
  */
69
69
  harness?: string;
70
70
  /**
@@ -302,8 +302,8 @@ export function createExecLoop(opts) {
302
302
  return 'continue';
303
303
  }
304
304
  /**
305
- * Relay the child's own output to this process's stderr when the command did
306
- * not succeed.
305
+ * Relay the child's own output unconditionally: to this process's stdout
306
+ * when the command succeeds, and stderr otherwise.
307
307
  *
308
308
  * ## Why this exists
309
309
  *
@@ -322,26 +322,48 @@ export function createExecLoop(opts) {
322
322
  * schema-rejected — with no trace of what the child said. Reproducing the
323
323
  * script by hand outside the engine was the only way to see its stderr.
324
324
  *
325
- * `outputTail` is already capped at 4 KiB by the runner, so this cannot flood
326
- * a log. Each line is prefixed so the child's words are never mistaken for
327
- * exec's own.
325
+ * The success half matters because a non-judge command step has no exit-code
326
+ * failure channel: a deferral is expressed as exit 0 and no payload.
327
+ * `merge-gate` does exactly that on its `cadence: 2m` re-offer. Before this
328
+ * relay, every deferral produced three identical log lines and no reason; the
329
+ * measured 40-minute case is recorded in `src/config-dir.ts:19-26`.
330
+ *
331
+ * Silence is printed rather than skipped because "this gate printed nothing"
332
+ * is itself the diagnosis, and an absent line is indistinguishable from the
333
+ * bug this relay fixes.
334
+ *
335
+ * `outputTail` is capped at 4 KiB by the runner (`runner.ts:40`), and a
336
+ * delivery run has roughly eleven command steps, so the worst case is about
337
+ * 44 KiB per run. That cap is why no volume knob exists: a knob would let a
338
+ * machine silently reintroduce this exact bug. Each line is prefixed so the
339
+ * child's words are never mistaken for exec's own.
328
340
  */
329
341
  function relayChildOutput(result, step) {
330
- if (result.exitCode === 0 && result.error === undefined)
331
- return;
332
- const how = result.error !== undefined
333
- ? `could not be run (${result.error})`
334
- : result.signal !== undefined
335
- ? `was killed by ${result.signal}`
336
- : `exited ${result.exitCode}`;
337
- opts.err(`owenloop work exec: the command for step '${step}' ${how}; its last output follows`);
342
+ const succeeded = result.exitCode === 0 && result.error === undefined;
343
+ // TWO CHANNELS ON PURPOSE, and this is not tidiness to be refactored away.
344
+ // `opts.err` is the channel a reader treats as trouble; routing a green
345
+ // step's routine output there would make every successful step look like a
346
+ // problem. A successful command's output is a RECORD, a failed one's is a
347
+ // DIAGNOSIS. Do not unify them.
348
+ const write = succeeded ? opts.out : opts.err;
349
+ if (succeeded) {
350
+ write(`owenloop work exec: the command for step '${step}' succeeded; its output follows`);
351
+ }
352
+ else {
353
+ const how = result.error !== undefined
354
+ ? `could not be run (${result.error})`
355
+ : result.signal !== undefined
356
+ ? `was killed by ${result.signal}`
357
+ : `exited ${result.exitCode}`;
358
+ write(`owenloop work exec: the command for step '${step}' ${how}; its last output follows`);
359
+ }
338
360
  const tail = result.outputTail.replace(/\n+$/, '');
339
361
  if (tail === '') {
340
- opts.err(' (the command produced no output)');
362
+ write(' (the command produced no output)');
341
363
  return;
342
364
  }
343
365
  for (const line of tail.split('\n'))
344
- opts.err(` | ${line}`);
366
+ write(` | ${line}`);
345
367
  }
346
368
  /** Build the receipt and submit it to every owed path. */
347
369
  async function submitReceipt(result, order, resolvedCommand) {
@@ -110,11 +110,10 @@ export const ADMITTED_OWENLOOP_KEYS = new Set([
110
110
  'OWENLOOP_SESSION',
111
111
  // `owenloopConfigDir` — src/config-dir.ts. Scopes owenloop's OWN config
112
112
  // directory (`settings.json`, `credentials.json`, `allowed_signers`) without
113
- // touching `XDG_CONFIG_HOME`, which the rest of the operator's toolchain also
114
- // reads. A path, not credential material — but the credential FILE backend
115
- // resolves under it (`readStoredCredential` → `configDir` → src/hub.ts), so a
116
- // mount that does not see this variable falls back to `XDG_CONFIG_HOME` and
117
- // reads a DIFFERENT credential store than the shift that spawned it.
113
+ // touching the rest of the operator's toolchain. A path, not credential
114
+ // material — but the credential file backend resolves under it
115
+ // (`readStoredCredential` → `configDir` → src/hub.ts), so a mount that does
116
+ // not see this variable reads a different credential store than its shift.
118
117
  'OWENLOOP_CONFIG_DIR',
119
118
  ]);
120
119
  /** The namespace this filter governs. Nothing outside it is ever touched. */
@@ -266,10 +266,9 @@ function isPlainMap(v) {
266
266
  const MOUNT_ENV_KEEP = ['HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME'];
267
267
  /**
268
268
  * `OWENLOOP_CONFIG_DIR` rides the `OWENLOOP_*` allowlist below rather than this
269
- * list, but it belongs to the same job: without it a mount whose parent scoped
270
- * owenloop's config with `OWENLOOP_CONFIG_DIR` would fall back to
271
- * `XDG_CONFIG_HOME` and read a DIFFERENT settings file than the shift that
272
- * spawned it.
269
+ * list, but it belongs to the same job: without it a mount whose parent uses an
270
+ * explicit configuration root would instead use its inherited HOME-rooted
271
+ * settings directory.
273
272
  */
274
273
  /**
275
274
  * The environment for the owenloop mount, forwarded from THIS process.
@@ -11,6 +11,22 @@ export interface SessionRecord {
11
11
  * contract lists it and Phase 6's `owenloop work sessions` display prints it.
12
12
  * ALWAYS build it with `orderId()` so the two can never drift. */
13
13
  order: string;
14
+ /**
15
+ * `OrderPacket.key` — the fan-out key of the engine task this firing served.
16
+ *
17
+ * WHY IT IS HERE, AND WHY IT IS OPTIONAL. `run` identifies ONE FIRING and is
18
+ * minted fresh every time the engine claims the step, so `(workflow, run,
19
+ * step)` can never name the same work twice. `(workflow, step, key)` is the
20
+ * engine's own task identity — the `UNIQUE (workflow, step, key)` on its
21
+ * `task` table — and is the only triple here that survives a re-offer. See
22
+ * `latestForTask`.
23
+ *
24
+ * OPTIONAL because every row written before this field existed lacks it. Such
25
+ * a row is never attributed to a task (`latestForTask` skips it) rather than
26
+ * being guessed at. `''` is a REAL key — an unfanned step — so the absence
27
+ * must be tested as `undefined`, never as falsy.
28
+ */
29
+ key?: string;
14
30
  attempt: number;
15
31
  /** Adapter id (`HarnessSessionRef.harness`). */
16
32
  harness: string;
@@ -86,11 +102,55 @@ export declare function orderId(workflow: string, run: string): string;
86
102
  */
87
103
  export declare function readSessions(file: string, opts?: SessionStoreOptions): SessionRecord[];
88
104
  /**
89
- * The newest record for `(workflow, run, step)`, or `null` when the file is
90
- * missing or holds no match. Scans forward and keeps the LAST match (last-wins).
91
- * Side-effect-free — it never writes, never compacts, and never throws.
105
+ * The newest record for `(workflow, run, step)` — that is, for ONE FIRING of one
106
+ * step — or `null` when the file is missing or holds no match. Scans forward and
107
+ * keeps the LAST match (last-wins). Side-effect-free: it never writes, never
108
+ * compacts, and never throws.
109
+ *
110
+ * ── THIS IS THE PER-FIRING LOOKUP. IT CANNOT FIND A PREVIOUS FIRING. ─────────
111
+ *
112
+ * The hub mints a fresh `run` id every time it claims a step. Two firings of the
113
+ * same step therefore NEVER share a `run`, so this function can only ever return
114
+ * a record written during the very firing that is asking. Use it for questions
115
+ * that really are about one firing — "did THIS firing already take a work dir?",
116
+ * "which sessions belong to the run I am tearing down?" — and never to ask "has
117
+ * this step run before?". That second question is `latestForTask`.
92
118
  */
93
119
  export declare function latestFor(file: string, workflow: string, run: string, step: string): SessionRecord | null;
120
+ /**
121
+ * The engine's own identity for a unit of work: one STEP of one WORKFLOW at one
122
+ * fan-out KEY. The hub enforces `UNIQUE (workflow, step, key)` on its task table,
123
+ * which is what makes this triple stable across re-offers where `run` is not.
124
+ */
125
+ export interface SessionTaskRef {
126
+ workflow: string;
127
+ step: string;
128
+ /** `OrderPacket.key`. `''` for a step that does not fan out — a real value,
129
+ * not a missing one. */
130
+ key: string;
131
+ }
132
+ /**
133
+ * The newest record for an engine TASK — the last session recorded for this
134
+ * step at this key, no matter which firing wrote it — or `null` when there is
135
+ * none. Last-wins, side-effect-free, same as `latestFor`.
136
+ *
137
+ * ── WHY THIS EXISTS ALONGSIDE `latestFor` ────────────────────────────────────
138
+ *
139
+ * `latestFor` keys on `run`, which the hub re-mints per firing, so it answers
140
+ * "what happened during THIS firing?". Resume needs the opposite question: "did
141
+ * a previous firing of this same step leave a session I can re-enter?" Only
142
+ * `(workflow, step, key)` survives long enough to answer that.
143
+ *
144
+ * ── WHY A ROW WITHOUT `key` NEVER MATCHES ────────────────────────────────────
145
+ *
146
+ * Rows written before `key` existed carry no task identity at all. Guessing one
147
+ * — treating absent as `''`, say — would attribute an unfanned row and a fanned
148
+ * row to the same task and hand a worker someone else's session. Skipping them
149
+ * costs only a cold start on the first firing after upgrade, which is the safe
150
+ * direction to be wrong in. The test is `=== undefined`, because `''` is a real
151
+ * key that must match.
152
+ */
153
+ export declare function latestForTask(file: string, task: SessionTaskRef): SessionRecord | null;
94
154
  /**
95
155
  * Rewrite `file` with only the last record per `(workflow, run, step)`,
96
156
  * preserving FIRST-SEEN key order, via temp file + rename. Corrupt lines are
@@ -84,10 +84,12 @@ function isNonEmptyString(v) {
84
84
  * The non-empty-string fields `isSessionRecord` requires, in the order it checks
85
85
  * them. Declared once and kept stable so a record failing several checks always
86
86
  * reports the SAME field, which keeps the skip message deterministic.
87
- * `status` is not here — its check is a membership test, not a string test — and
88
- * is applied after these, preserving the original check order.
87
+ *
88
+ * `token` is NOT here — see `firstInvalidSessionRecordField`. `status` is not
89
+ * here either: its check is a membership test, not a string test, and is applied
90
+ * after these, preserving the original check order.
89
91
  */
90
- const SESSION_RECORD_STRING_FIELDS = ['workflow', 'run', 'step', 'harness', 'token'];
92
+ const SESSION_RECORD_STRING_FIELDS = ['workflow', 'run', 'step', 'harness'];
91
93
  /**
92
94
  * Name of the first field of `v` that fails the `SessionRecord` schema, or
93
95
  * `null` when the record is valid. `'<root>'` means `v` is not a plain object at
@@ -97,9 +99,43 @@ const SESSION_RECORD_STRING_FIELDS = ['workflow', 'run', 'step', 'harness', 'tok
97
99
  * in terms of this function, so the accept/reject decision and the reported
98
100
  * field name can never drift apart.
99
101
  *
100
- * Checks exactly the fields whose absence would make the record unusable for a
101
- * resume: the three key fields plus the harness and token it exists to carry,
102
- * and a `status` inside the four literals. Everything else is carried verbatim.
102
+ * Checks exactly the fields whose absence would make the record unusable: the
103
+ * three key fields, the harness that says which vendor the row belongs to, a
104
+ * `token` that is a string, and a `status` inside the four literals. Everything
105
+ * else is carried verbatim.
106
+ *
107
+ * ── WHY AN EMPTY `token` IS VALID, THOUGH IT ONCE WAS NOT ────────────────────
108
+ *
109
+ * `token` must be a STRING, but it may be EMPTY. The writer produces an empty
110
+ * one deliberately: `agent/loop.ts` appends a record before the harness emits
111
+ * its `started` event, so that a harness which dies on launch still leaves proof
112
+ * the attempt existed and died. Its own comment says so. Requiring the token to
113
+ * be non-empty here threw exactly those records away — the reader discarded the
114
+ * evidence the writer went out of its way to leave.
115
+ *
116
+ * The cost was not only the lost rows. Every such line was reported on stdout as
117
+ * `field "token" failed schema check`, once per reading process. On this machine
118
+ * that was ~94 lines printed by each of three shifts on every boot: ~280 warning
119
+ * lines about records that were behaving exactly as designed, drowning the
120
+ * warnings that meant something.
121
+ *
122
+ * Nothing downstream is harmed by admitting them, because every consumer already
123
+ * expected the empty case and guarded for it BEFORE this change:
124
+ * - `agent/loop.ts` requires `prev.token !== ''` to resume, with a comment
125
+ * naming this exact case ("the record predates its `started` event").
126
+ * - `roles/sessions.ts` renders no resume command for one.
127
+ * - `shouldRetireSession` reads `pid`/owner/`status` and never the token.
128
+ *
129
+ * The guard in the loop is in fact PROOF of the intent: it is unreachable code
130
+ * unless records with an empty token can be read back.
131
+ *
132
+ * ── WHY `key` IS CHECKED ONLY WHEN PRESENT ───────────────────────────────────
133
+ *
134
+ * `key` was added after rows already existed, so ABSENT is legal and means "this
135
+ * row predates the field". PRESENT-BUT-NOT-A-STRING is not legal: it would be a
136
+ * row nobody wrote, and `latestForTask` would silently mis-key it. `''` is a
137
+ * perfectly good key — it is what an unfanned step carries — so emptiness is
138
+ * never the test here.
103
139
  */
104
140
  function firstInvalidSessionRecordField(v) {
105
141
  if (typeof v !== 'object' || v === null || Array.isArray(v))
@@ -109,6 +145,13 @@ function firstInvalidSessionRecordField(v) {
109
145
  if (!isNonEmptyString(r[field]))
110
146
  return field;
111
147
  }
148
+ // Checked after `harness` and before `status`, which is where it sat when it
149
+ // was a non-empty check, so a record failing several fields still reports the
150
+ // same one it always did.
151
+ if (typeof r['token'] !== 'string')
152
+ return 'token';
153
+ if (r['key'] !== undefined && typeof r['key'] !== 'string')
154
+ return 'key';
112
155
  if (typeof r['status'] !== 'string' || !STATUSES.has(r['status']))
113
156
  return 'status';
114
157
  return null;
@@ -286,6 +329,11 @@ export function readSessions(file, opts = {}) {
286
329
  // debugging after a file-integrity problem that did not exist. The second
287
330
  // pass runs only on this failure branch, so valid records pay nothing.
288
331
  // The field NAME only, never its value — `token` is credential-shaped.
332
+ //
333
+ // Those empty-`token` records are no longer invalid at all — the schema
334
+ // admits them now (see `firstInvalidSessionRecordField`). Reaching this
335
+ // branch therefore means something genuinely wrong with the record, which
336
+ // is what makes the line worth printing.
289
337
  const badField = firstInvalidSessionRecordField(parsed) ?? '<unknown>';
290
338
  warn(`owenloop work sessions: skipping invalid record at ${file}:${i + 1}: field "${badField}" failed schema check`);
291
339
  continue;
@@ -295,9 +343,19 @@ export function readSessions(file, opts = {}) {
295
343
  return out;
296
344
  }
297
345
  /**
298
- * The newest record for `(workflow, run, step)`, or `null` when the file is
299
- * missing or holds no match. Scans forward and keeps the LAST match (last-wins).
300
- * Side-effect-free — it never writes, never compacts, and never throws.
346
+ * The newest record for `(workflow, run, step)` — that is, for ONE FIRING of one
347
+ * step — or `null` when the file is missing or holds no match. Scans forward and
348
+ * keeps the LAST match (last-wins). Side-effect-free: it never writes, never
349
+ * compacts, and never throws.
350
+ *
351
+ * ── THIS IS THE PER-FIRING LOOKUP. IT CANNOT FIND A PREVIOUS FIRING. ─────────
352
+ *
353
+ * The hub mints a fresh `run` id every time it claims a step. Two firings of the
354
+ * same step therefore NEVER share a `run`, so this function can only ever return
355
+ * a record written during the very firing that is asking. Use it for questions
356
+ * that really are about one firing — "did THIS firing already take a work dir?",
357
+ * "which sessions belong to the run I am tearing down?" — and never to ask "has
358
+ * this step run before?". That second question is `latestForTask`.
301
359
  */
302
360
  export function latestFor(file, workflow, run, step) {
303
361
  const want = keyOf(workflow, run, step);
@@ -308,6 +366,43 @@ export function latestFor(file, workflow, run, step) {
308
366
  }
309
367
  return best;
310
368
  }
369
+ /** Identity of an engine TASK. Same JSON-array encoding as `keyOf`, and for the
370
+ * same reason: no combination of field values can collide into one key. */
371
+ function taskKeyOf(task) {
372
+ return JSON.stringify([task.workflow, task.step, task.key]);
373
+ }
374
+ /**
375
+ * The newest record for an engine TASK — the last session recorded for this
376
+ * step at this key, no matter which firing wrote it — or `null` when there is
377
+ * none. Last-wins, side-effect-free, same as `latestFor`.
378
+ *
379
+ * ── WHY THIS EXISTS ALONGSIDE `latestFor` ────────────────────────────────────
380
+ *
381
+ * `latestFor` keys on `run`, which the hub re-mints per firing, so it answers
382
+ * "what happened during THIS firing?". Resume needs the opposite question: "did
383
+ * a previous firing of this same step leave a session I can re-enter?" Only
384
+ * `(workflow, step, key)` survives long enough to answer that.
385
+ *
386
+ * ── WHY A ROW WITHOUT `key` NEVER MATCHES ────────────────────────────────────
387
+ *
388
+ * Rows written before `key` existed carry no task identity at all. Guessing one
389
+ * — treating absent as `''`, say — would attribute an unfanned row and a fanned
390
+ * row to the same task and hand a worker someone else's session. Skipping them
391
+ * costs only a cold start on the first firing after upgrade, which is the safe
392
+ * direction to be wrong in. The test is `=== undefined`, because `''` is a real
393
+ * key that must match.
394
+ */
395
+ export function latestForTask(file, task) {
396
+ const want = taskKeyOf(task);
397
+ let best = null;
398
+ for (const rec of readSessions(file)) {
399
+ if (rec.key === undefined)
400
+ continue;
401
+ if (taskKeyOf({ workflow: rec.workflow, step: rec.step, key: rec.key }) === want)
402
+ best = rec;
403
+ }
404
+ return best;
405
+ }
311
406
  /** The lock shared by append and compaction for one session log. */
312
407
  function writerLockPath(file) {
313
408
  return `${file}.lock`;
@@ -185,9 +185,9 @@ export interface OrderPacket {
185
185
  /**
186
186
  * THE COMPOSED CAPABILITIES this order was offered under, in the step's
187
187
  * authored order — `['build:deep']` for a `build` step on a `deep` run. This
188
- * is the key into the shift's `capabilityModels` map (see
189
- * `src/agent/capability-model.ts`), and therefore what decides which model and
190
- * effort run. Absent from a pre-modifier hub, which is why the worker treats
188
+ * is the key into the shift's merged crew roster (see
189
+ * `src/agent/capability-model.ts`), and therefore what decides which
190
+ * harness, model, and effort run. Absent from a pre-modifier hub, which is why the worker treats
191
191
  * an empty list as "nothing to resolve against" and refuses rather than
192
192
  * guessing.
193
193
  */