owenloop 0.5.25 → 0.5.26

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.
@@ -4,7 +4,7 @@ import { type WorkOrder } from '../hub/types.ts';
4
4
  import type { FetchedStep } from '../bundle/types.ts';
5
5
  import { type ReconcileOptions, type Liveness } from './state.ts';
6
6
  import { sweepWorkDirs as sweepWorkDirsImpl } from '../agent/workdir.ts';
7
- import type { Spawner } from './spawn.ts';
7
+ import type { Spawner, WorkerFailure } from './spawn.ts';
8
8
  import { type ShiftEvent } from './protocol.ts';
9
9
  export interface ShiftLoopOptions {
10
10
  hub: HubClient;
@@ -172,11 +172,18 @@ export interface ShiftLoop {
172
172
  /**
173
173
  * Run-ended reap (metering condition (a)): drop the in-flight record for
174
174
  * `run` NOW, so its slot frees immediately instead of waiting for the next
175
- * reconcile to notice the child exited. The shift's MCP `submit` tool calls
176
- * an internal caller may use this when the hub reports a submit CLOSED the
177
- * run — the one in-process end-of-run signal the shift sees. A run whose closing submit went through
178
- * the child's own mount instead is not a problem: that child exits, and the
179
- * next reconcile's pid probe frees the slot anyway.
175
+ * reconcile to notice the child exited.
176
+ *
177
+ * NOTHING IN `src/` CALLS THIS. It is reachable only from tests. The intended
178
+ * caller was a submit path that told the shift the hub had closed a run, and
179
+ * that wiring was never made, so the slot is always freed the slower way
180
+ * instead: the child exits, and the next reconcile's pid probe frees it.
181
+ *
182
+ * Stated plainly because the gap is invisible from the type — this is on the
183
+ * `ShiftLoop` interface, so it reads as live. Do not reason from its
184
+ * existence about when `runBrakeKey` entries are cleared; in production the
185
+ * per-sweep prune is the only clearer. Wire it or delete it, but do not build
186
+ * a guard on top of it.
180
187
  */
181
188
  noteRunEnded(run: string): void;
182
189
  /**
@@ -203,10 +210,44 @@ export interface ShiftLoop {
203
210
  * A failure for a run this loop never dispatched (a foreign or already-reaped
204
211
  * run) is ignored rather than guessed at: the fan-out key is not on the
205
212
  * failure record, so there is no sound way to pick a brake key for it.
213
+ *
214
+ * ALSO HANDS THE CLAIM BACK, with the failure as the reason. A worker that
215
+ * dies before it submits leaves its order INFLIGHT on the hub with a frozen
216
+ * heartbeat: no alert, no re-offer, and no other shift able to take it,
217
+ * because this shift still holds the claim. Measured once at 34 minutes,
218
+ * indistinguishable from work in progress, until an operator released it by
219
+ * hand. The failure is known here and already named precisely, so the name
220
+ * travels with the release instead of dying in a local log line.
221
+ *
222
+ * The brake-key guard scopes the release to runs THIS shift dispatched and
223
+ * has not yet pruned. It does NOT mean "the run is still open": the only
224
+ * production clearer is the per-sweep prune below, and a child's exit event
225
+ * always beats the next sweep. So this fires for ordinary worker failures
226
+ * too, on top of the specific release the child's own final breath sends.
227
+ *
228
+ * That redundancy is deliberate and it is cheap, because the hub answers a
229
+ * release on an unheld claim by returning BEFORE it normalizes the reason or
230
+ * publishes anything (`verbs/release.ts`: "Only a currently held targeted
231
+ * release gets a diagnostic side effect"). A worker whose own final breath
232
+ * reached the hub therefore costs exactly one no-op request here — it cannot
233
+ * overwrite the reason that worker already recorded.
234
+ *
235
+ * Covering the ordinary exit path is the point, not an accident. The
236
+ * incident this exists for exited 1 with no signal, killed by ENOSPC inside
237
+ * its own error logging, so a predicate keyed on "could not have released
238
+ * for itself" — a signal death, or a spawn that never started — would have
239
+ * missed it entirely. A supervisor cannot tell those apart from outside, so
240
+ * it reports what it saw and lets the hub deduplicate.
241
+ *
242
+ * One narrow race remains, and it is worth taking. `finalBreath` gives up
243
+ * after `RELEASE_CAP_MS` while its request is still in flight; if that
244
+ * request is slow enough for this one to overtake it, the supervisor's
245
+ * account is recorded and the worker's more specific one is dropped as
246
+ * not-held. The reason string names its own provenance so that outcome still
247
+ * reads honestly, and a slightly vaguer alert beats the alternative this
248
+ * replaces, which was no alert at all for 34 minutes.
206
249
  */
207
- noteWorkerFailure(failure: {
208
- run: string;
209
- }): void;
250
+ noteWorkerFailure(failure: WorkerFailure): void;
210
251
  }
211
252
  /** The hub reaps a never-contacted claim after this long. Every client-side
212
253
  * re-offer latency must stay strictly under it. */
@@ -238,9 +279,12 @@ export declare const MAX_PENDING_CANDIDATE_AGE_MS: number;
238
279
  * each other.
239
280
  *
240
281
  * WHAT IS COUNTED, AND WHY IT IS NOT DISPATCHES. The event counted against that
241
- * key is a WORKER FAILURE — a child that exited non-zero, reported into the
242
- * loop through `noteWorkerFailure` — never a dispatch. Counting dispatches
243
- * conflates a storm with legitimate concurrency: the hub can offer several
282
+ * key is a FAILED ATTEMPT TO RUN THE STEP, in either of the two shapes that
283
+ * exist: a child that started and exited non-zero, reported into the loop
284
+ * through `noteWorkerFailure`; or a dispatch that never produced a running
285
+ * child at all, which throws out of `dispatchCandidate` and is charged there.
286
+ * What is NOT counted is a dispatch that succeeds. Counting those would
287
+ * conflate a storm with legitimate concurrency: the hub can offer several
244
288
  * DISTINCT runs of one step in a single sweep, and metering the second through
245
289
  * fifth of those would throttle healthy work. A failure is direct evidence that
246
290
  * running this step again right now is unlikely to help; a dispatch is evidence
@@ -250,4 +294,24 @@ export declare const MAX_PENDING_CANDIDATE_AGE_MS: number;
250
294
  * with zero delay, however many orders arrive for it at once.
251
295
  */
252
296
  export declare const STEP_BRAKE_DELAYS_MS: readonly [2000, 8000, 30000, 60000, 90000];
297
+ /**
298
+ * Treat a failure this long after the previous one as the start of a NEW
299
+ * streak, resetting the count to zero first. Comfortably longer than the
300
+ * longest delay in the table (90s), so a step failing at maximum backoff never
301
+ * decays out of it, while an isolated transient long after an old streak starts
302
+ * again at the shortest delay instead of inheriting a stale penalty.
303
+ */
304
+ export declare const STEP_BRAKE_DECAY_MS = 600000;
305
+ /**
306
+ * Longest release reason this shift will put on the wire, in code points.
307
+ *
308
+ * Mirrors the hub's own `MAX_RELEASE_REASON_CODE_POINTS`, which trims, treats
309
+ * blank as absent, and truncates without splitting a surrogate pair. Clamping
310
+ * on this side too means the reason we send is the reason an operator reads,
311
+ * with no silent server-side shortening in between.
312
+ *
313
+ * Exported so a test can assert the clamp against the constant rather than
314
+ * against a copy of the number, which would drift the day the hub's limit moves.
315
+ */
316
+ export declare const MAX_RELEASE_REASON_POINTS = 1024;
253
317
  export declare function createShiftLoop(opts: ShiftLoopOptions): ShiftLoop;
@@ -144,9 +144,12 @@ const CAPACITY_RELEASE_COOLDOWN_MS = 30_000;
144
144
  * each other.
145
145
  *
146
146
  * WHAT IS COUNTED, AND WHY IT IS NOT DISPATCHES. The event counted against that
147
- * key is a WORKER FAILURE — a child that exited non-zero, reported into the
148
- * loop through `noteWorkerFailure` — never a dispatch. Counting dispatches
149
- * conflates a storm with legitimate concurrency: the hub can offer several
147
+ * key is a FAILED ATTEMPT TO RUN THE STEP, in either of the two shapes that
148
+ * exist: a child that started and exited non-zero, reported into the loop
149
+ * through `noteWorkerFailure`; or a dispatch that never produced a running
150
+ * child at all, which throws out of `dispatchCandidate` and is charged there.
151
+ * What is NOT counted is a dispatch that succeeds. Counting those would
152
+ * conflate a storm with legitimate concurrency: the hub can offer several
150
153
  * DISTINCT runs of one step in a single sweep, and metering the second through
151
154
  * fifth of those would throttle healthy work. A failure is direct evidence that
152
155
  * running this step again right now is unlikely to help; a dispatch is evidence
@@ -163,13 +166,25 @@ export const STEP_BRAKE_DELAYS_MS = [2_000, 8_000, 30_000, 60_000, 90_000];
163
166
  * decays out of it, while an isolated transient long after an old streak starts
164
167
  * again at the shortest delay instead of inheriting a stale penalty.
165
168
  */
166
- const STEP_BRAKE_DECAY_MS = 600_000;
169
+ export const STEP_BRAKE_DECAY_MS = 600_000;
167
170
  /**
168
171
  * Forget a step's brake entry once this long has passed since its window
169
172
  * closed, so the map cannot grow for the life of the shift. Pure housekeeping —
170
173
  * `STEP_BRAKE_DECAY_MS` is what governs behaviour.
171
174
  */
172
175
  const STEP_BRAKE_FORGET_MS = 1_800_000;
176
+ /**
177
+ * Longest release reason this shift will put on the wire, in code points.
178
+ *
179
+ * Mirrors the hub's own `MAX_RELEASE_REASON_CODE_POINTS`, which trims, treats
180
+ * blank as absent, and truncates without splitting a surrogate pair. Clamping
181
+ * on this side too means the reason we send is the reason an operator reads,
182
+ * with no silent server-side shortening in between.
183
+ *
184
+ * Exported so a test can assert the clamp against the constant rather than
185
+ * against a copy of the number, which would drift the day the hub's limit moves.
186
+ */
187
+ export const MAX_RELEASE_REASON_POINTS = 1024;
173
188
  /**
174
189
  * How long to refuse the next dispatch of a step after `count` consecutive
175
190
  * worker failures. `count` is at least 1 at every call site (this is reached
@@ -386,6 +401,60 @@ export function createShiftLoop(opts) {
386
401
  opts.err(`shift event sink failed: ${errMsg(e)} (continuing)`);
387
402
  }
388
403
  }
404
+ /**
405
+ * Bound a release reason to what the hub will actually store.
406
+ *
407
+ * Applied to EVERY reason this supervisor sends, not only the ones that look
408
+ * long. The two senders differ sharply in how bounded they are, which is
409
+ * exactly why the clamp belongs in one shared place rather than at whichever
410
+ * call site looked risky on the day:
411
+ *
412
+ * - `describeWorkerFailure` is provably short. Its longest constructible
413
+ * output is under 100 code points, because every part is generated here or
414
+ * is one of two literals in `spawn.ts`.
415
+ * - The dispatch catch interpolates `errMsg(e)`, which is NOT bounded. A
416
+ * `FileLockTimeoutError` from `acquireDispatchLock` embeds a filesystem
417
+ * path, and a path is bounded only by PATH_MAX.
418
+ *
419
+ * Slices by code point, never by UTF-16 unit, so a clamp cannot halve a
420
+ * surrogate pair and put a lone surrogate on the wire. The hub truncates at
421
+ * `MAX_RELEASE_REASON_CODE_POINTS` too; clamping here as well means the
422
+ * reason we send is the reason an operator reads, with no silent server-side
423
+ * shortening in between.
424
+ */
425
+ const clampReason = (reason) => {
426
+ const points = Array.from(reason);
427
+ return points.length > MAX_RELEASE_REASON_POINTS
428
+ ? points.slice(0, MAX_RELEASE_REASON_POINTS).join('')
429
+ : reason;
430
+ };
431
+ /**
432
+ * The operator-facing account of a dead worker, for the release reason.
433
+ *
434
+ * It names the supervisor explicitly. A worker that fails through its own
435
+ * error path already sends a precise reason of its own, and in a narrow race
436
+ * this account can land first and take the slot the hub keeps for the first
437
+ * observation. Saying who is speaking keeps that outcome readable instead of
438
+ * looking like a worker's own vague self-report.
439
+ *
440
+ * `message` is the SPAWNER'S OWN bounded lifecycle string, never worker
441
+ * output: agent-run stderr is untrusted and is deliberately never quoted back
442
+ * (see `spawn.ts`), and the spawn error object is dropped there rather than
443
+ * interpolated, so no local path reaches the wire.
444
+ *
445
+ * The exit status or signal is what tells an operator which failure this was:
446
+ * a crash, an external kill, or a child that never launched at all. It is the
447
+ * difference between "this step is broken" and "this host is broken", so it
448
+ * travels with the message rather than staying in a local log line.
449
+ */
450
+ const describeWorkerFailure = (failure) => {
451
+ const cause = failure.signal !== null
452
+ ? `signal ${failure.signal}`
453
+ : failure.exitStatus !== null
454
+ ? `exitStatus ${failure.exitStatus}`
455
+ : 'no exit status';
456
+ return clampReason(`shift supervisor: ${failure.kind} ${failure.message} (${cause})`);
457
+ };
389
458
  /**
390
459
  * Hand a claim back so another shift can be offered it immediately. This
391
460
  * deliberately stays off the dispatch critical path; a failed release falls
@@ -445,6 +514,29 @@ export function createShiftLoop(opts) {
445
514
  * monotonic instant the next spawn of that step becomes permitted.
446
515
  */
447
516
  const stepBrake = new Map();
517
+ /**
518
+ * Charge one failure against a step's brake, extending the current streak or
519
+ * starting a new one.
520
+ *
521
+ * Shared by both places a dispatch can die: the worker failing after it
522
+ * started (`noteWorkerFailure`) and the spawn itself failing before it ever
523
+ * did (`dispatchCandidate`'s catch). Both now hand the claim back, and a
524
+ * released claim is re-offered immediately instead of lapsing after the
525
+ * 120s reap — so the brake, not the reap, is what throttles a step that
526
+ * keeps dying. Charging from only one of the two paths would leave the other
527
+ * free-running against the hub.
528
+ */
529
+ const chargeStepBrake = (brakeKey) => {
530
+ const at = monotonicNow();
531
+ const prior = stepBrake.get(brakeKey);
532
+ // A failure long after the previous one starts a NEW streak rather than
533
+ // extending a stale one — see `STEP_BRAKE_DECAY_MS`.
534
+ const priorCount = prior !== undefined && at - prior.failedAt < STEP_BRAKE_DECAY_MS
535
+ ? prior.count
536
+ : 0;
537
+ const count = priorCount + 1;
538
+ stepBrake.set(brakeKey, { count, failedAt: at, nextAllowedAt: at + stepBrakeDelayMs(count) });
539
+ };
448
540
  /**
449
541
  * Brake key of the step each dispatched run belongs to.
450
542
  *
@@ -456,9 +548,11 @@ export function createShiftLoop(opts) {
456
548
  * precedes the child's `exit` event (that fires on a later tick), so a
457
549
  * failure can never arrive before its own entry exists.
458
550
  *
459
- * Entries are removed when the run's failure is noted, when the run ends
460
- * (`noteRunEnded`), and for any run no longer live at sweep time — so this
461
- * map tracks live dispatches only and cannot grow without bound.
551
+ * Entries are removed when the run's failure is noted and, in production,
552
+ * for any run no longer live at sweep time — that prune is what bounds the
553
+ * map. (`noteRunEnded` also clears one, but nothing in `src/` calls it; see
554
+ * its declaration.) So an entry's presence means "this shift dispatched this
555
+ * run and has not pruned it yet", NOT "the run is still open".
462
556
  */
463
557
  const runBrakeKey = new Map();
464
558
  /**
@@ -596,7 +690,40 @@ export function createShiftLoop(opts) {
596
690
  message,
597
691
  });
598
692
  const prefix = c.kind === 'command' ? 'spawn' : 'agent-run spawn';
693
+ // Two different failures reach this one catch, and an operator reading the
694
+ // release reason needs to know which. `cancel` is assigned only after
695
+ // `opts.spawner` returns, so it is the exact witness: undefined means the
696
+ // spawn itself threw and no child ever existed; defined means a child WAS
697
+ // running and something after it threw — the reservation write, the
698
+ // dispatch lock, or `opts.out` on a full disk — and `cancel()` above has
699
+ // just killed it. Calling both "failed" told an operator to look for a
700
+ // fork problem that never happened.
701
+ const startedThenAborted = cancel !== undefined;
599
702
  opts.err(`${prefix} for ${c.workflow}/${c.order.run} failed: ${message}`);
703
+ // Hand the claim back. `whats_next` took it before this function ran, and
704
+ // reaching here means no worker exists to hand it back for itself — either
705
+ // no child was ever started, or `cancel()` has just killed the one that
706
+ // was. Without this the order sits INFLIGHT with a heartbeat that will
707
+ // never tick again, which is the same invisible stall a dead worker
708
+ // leaves.
709
+ //
710
+ // No `WorkerFailure` is ever reported for this path — the spawn never
711
+ // returned, or the child was killed before it could report — so
712
+ // `noteWorkerFailure` cannot cover it.
713
+ //
714
+ // Charge the brake from here too. A released claim is re-offered at once
715
+ // rather than lapsing after the 120s reap, so on a host that cannot fork
716
+ // at all the brake is now the only thing standing between this shift and
717
+ // a claim-fail-release loop against the hub.
718
+ //
719
+ // Drop the run's brake-key mapping first. On the aborted-child arm
720
+ // `runBrakeKey` may already be set, and leaving it would let a later
721
+ // `noteWorkerFailure` for the same run release a second time and charge
722
+ // the brake twice for one logical failure. Nothing depends on the entry
723
+ // once the claim is released, so deleting it is unconditional.
724
+ releaseClaim(c.workflow, c.order.run, clampReason(`shift supervisor: ${prefix} ${startedThenAborted ? 'started then aborted' : 'failed'} — ${message}`));
725
+ runBrakeKey.delete(c.order.run);
726
+ chargeStepBrake(brakeKey);
600
727
  return 'failed';
601
728
  }
602
729
  }
@@ -688,8 +815,18 @@ export function createShiftLoop(opts) {
688
815
  // exited CLEANLY reports no failure, so nothing else would ever remove its
689
816
  // entry. A non-zero exit is charged by `noteWorkerFailure`, which the
690
817
  // child's own `exit` event drives on the next event-loop tick — always well
691
- // before the next sweep, which waits a whole poll interval. If that order
692
- // ever did invert, the cost is one uncharged failure, never a wrong charge.
818
+ // before the next sweep, which waits a whole poll interval.
819
+ //
820
+ // This prune is the only clearer for a run that exits CLEANLY, and is
821
+ // therefore what bounds the map — a failing run is cleared by
822
+ // `noteWorkerFailure`, and an aborted dispatch clears its own entry. That
823
+ // makes the ordering matter more than it used to. `noteWorkerFailure` now also
824
+ // releases the claim, so an inversion here no longer costs one uncharged
825
+ // failure: it costs a claim nobody hands back, which is the stall this
826
+ // release exists to end. `iteration()` closes the window — `reconcile()`
827
+ // snapshots `live` and then awaits `hub.wake`, and a queued `exit` event is
828
+ // delivered during that await, so a child that died before the snapshot has
829
+ // already been charged and one that died after is still inside it.
693
830
  for (const [key, entry] of stepBrake) {
694
831
  if (monotonicNow() - entry.nextAllowedAt > STEP_BRAKE_FORGET_MS)
695
832
  stepBrake.delete(key);
@@ -1012,7 +1149,14 @@ export function createShiftLoop(opts) {
1012
1149
  // 'braked' and 'failed' are deliberately NOT queued into pendingCandidates:
1013
1150
  // both mean this shift is not going to run that order now, and re-queuing a
1014
1151
  // braked candidate would just re-dispatch it on the next drain, defeating
1015
- // the brake. The claim lapses through the hub's pickup window instead.
1152
+ // the brake.
1153
+ //
1154
+ // What happens to the claim differs between the two, and the difference is
1155
+ // the point of this change. A BRAKED candidate was never dispatched, so its
1156
+ // claim lapses through the hub's pickup window — the delay is deliberate,
1157
+ // and shedding it is what the brake is for. A FAILED one hands its claim
1158
+ // back explicitly in `dispatchCandidate`, so it is re-offered at once
1159
+ // instead of sitting INFLIGHT behind a heartbeat that will never tick.
1016
1160
  for (const candidate of candidates) {
1017
1161
  if (discardExpiredCandidate(candidate, false))
1018
1162
  continue;
@@ -1342,21 +1486,10 @@ export function createShiftLoop(opts) {
1342
1486
  noteWorkerFailure: (failure) => {
1343
1487
  const brakeKey = runBrakeKey.get(failure.run);
1344
1488
  if (brakeKey === undefined)
1345
- return; // not ours, or already accounted for
1489
+ return; // not a run this shift still tracks
1346
1490
  runBrakeKey.delete(failure.run);
1347
- const at = monotonicNow();
1348
- const prior = stepBrake.get(brakeKey);
1349
- // A failure long after the previous one starts a NEW streak rather than
1350
- // extending a stale one — see `STEP_BRAKE_DECAY_MS`.
1351
- const priorCount = prior !== undefined && at - prior.failedAt < STEP_BRAKE_DECAY_MS
1352
- ? prior.count
1353
- : 0;
1354
- const count = priorCount + 1;
1355
- stepBrake.set(brakeKey, {
1356
- count,
1357
- failedAt: at,
1358
- nextAllowedAt: at + stepBrakeDelayMs(count),
1359
- });
1491
+ releaseClaim(failure.workflow, failure.run, describeWorkerFailure(failure));
1492
+ chargeStepBrake(brakeKey);
1360
1493
  },
1361
1494
  };
1362
1495
  }
@@ -1,6 +1,6 @@
1
1
  import type { BundleRuntimeRequirements } from './types.ts';
2
2
  /** Runtime features implemented by this Owenloop release. */
3
- export declare const SUPPORTED_RUNTIME_FEATURES: readonly ["harness-policy-enforcement.v1", "native-judge-policy-inheritance.v1", "neutral-approval-modes.v1"];
3
+ export declare const SUPPORTED_RUNTIME_FEATURES: readonly ["harness-policy-enforcement.v1", "native-judge-policy-inheritance.v1", "neutral-approval-modes.v1", "command-payload-file.v1"];
4
4
  export interface RuntimeCompatibilityEnvironment {
5
5
  /** The running Owenloop package version. `0.0.0` is the unavailable-version sentinel. */
6
6
  version: string;
@@ -15,6 +15,19 @@ export const SUPPORTED_RUNTIME_FEATURES = Object.freeze([
15
15
  // than about an old runtime. Requiring the id moves the diagnosis to the
16
16
  // bundle check, before any order is offered.
17
17
  'neutral-approval-modes.v1',
18
+ // A command step may return its payload by writing JSON to the path in
19
+ // `$OWENLOOP_PAYLOAD_FILE` instead of printing an `##owenloop:payload##` line
20
+ // on stdout, which lifts the result ceiling from the 64 KiB stdout marker to
21
+ // the hub's artifact cap. A def whose command writes that file MUST require
22
+ // this id, because a CLI that predates it fails in the worst available way:
23
+ // it leaves the variable unset, and the natural defensive spelling
24
+ // `> "${OWENLOOP_PAYLOAD_FILE:-/dev/null}"` then EXITS ZERO having written the
25
+ // payload to /dev/null. There is no error anywhere — the step submits a
26
+ // receipt with no payload, and the first sign of trouble is a downstream
27
+ // `from: payload.value` bind failing at the hub, one step away from the cause.
28
+ // Requiring the id moves the diagnosis to the bundle check, before any order
29
+ // is offered.
30
+ 'command-payload-file.v1',
18
31
  ]);
19
32
  /** True only for one canonical strict SemVer value, with no prefix, range, or whitespace. */
20
33
  export function isCanonicalSemver(value) {
package/docs/authoring.md CHANGED
@@ -320,6 +320,15 @@ modifier through `OWENLOOP_FEEDBACK`/`OWENLOOP_FEEDBACK_FILE` and
320
320
  steps](bundles.md#consumed-inputs-for-command-steps) for the reader snippet and
321
321
  the omitted-key rule.
322
322
 
323
+ The result travels the same way. A command step's accepted artifact is its whole
324
+ `CommandReceipt`; to put a value of its own inside it — the thing a downstream
325
+ `from: payload.value` bind reads — the command either prints an
326
+ `##owenloop:payload##` marker line on stdout, capped at 64 KiB, or writes the
327
+ same JSON to the path in `OWENLOOP_PAYLOAD_FILE`, capped at 24 MB. A definition
328
+ whose command writes that file must declare the `command-payload-file.v1`
329
+ runtime feature. See [`docs/bundles.md` § Returning a payload from a command
330
+ step](bundles.md#returning-a-payload-from-a-command-step).
331
+
323
332
  ## `capabilities:` — logical capability tags
324
333
 
325
334
  `capabilities:` is an optional list of strings on a step naming what that step
package/docs/bundles.md CHANGED
@@ -107,6 +107,8 @@ This Owenloop release advertises exactly these feature identifiers:
107
107
 
108
108
  - `harness-policy-enforcement.v1`
109
109
  - `native-judge-policy-inheritance.v1`
110
+ - `neutral-approval-modes.v1`
111
+ - `command-payload-file.v1`
110
112
 
111
113
  The running version comes from Owenloop's production `packageVersion()` source. A production build that cannot read a valid package version uses the `0.0.0` sentinel. The sentinel fails every declared `minVersion`, including `minVersion: "0.0.0"`, and the refusal tells the operator to install or upgrade Owenloop. The sentinel may still satisfy a feature-only declaration because feature support is evaluated independently.
112
114
 
@@ -298,6 +300,70 @@ run; only an accepted artifact with a declared bind can do that.
298
300
  An agent prompt can read the same value as `${MODIFIER}`. Unknown placeholders
299
301
  remain unchanged; when an order has no modifier, `${MODIFIER}` remains literal.
300
302
 
303
+ ## Returning a payload from a command step
304
+
305
+ A command step's accepted artifact is its whole `CommandReceipt`. To put a value
306
+ of its own inside that receipt — the thing a downstream `from: payload.value`
307
+ bind reads — a command has two ways to say it, and it must pick exactly one.
308
+
309
+ | Transport | How | Ceiling |
310
+ | --- | --- | --- |
311
+ | stdout marker | print one line beginning `##owenloop:payload## ` followed by JSON | 64 KiB of JSON text (`PAYLOAD_MAX_BYTES`) |
312
+ | payload file | write JSON to the path in `OWENLOOP_PAYLOAD_FILE` | 24 MB (`PAYLOAD_FILE_MAX_BYTES`) |
313
+
314
+ The marker is the older channel and is unchanged. The file exists because the
315
+ marker's ceiling is a *transport* limit on a single stdout line, while the hub
316
+ has always stored an artifact above 64 KiB in object storage up to its own
317
+ 25 MB cap. A result between those two numbers had nowhere to go: the runner
318
+ dropped the marker line and the step submitted a receipt with no payload.
319
+
320
+ `OWENLOOP_PAYLOAD_FILE` is set on **every** command spawn, not only when a
321
+ result is expected to be large, and it is always resolved rather than inherited
322
+ — a shift launched from inside another command step already carries its parent
323
+ order's value, and reading it would attribute one step's result to another. The
324
+ runner creates the private `0700` directory but **not** the file; the command
325
+ creates it, or leaves it absent.
326
+
327
+ ```sh
328
+ # Either of these is a complete producer.
329
+ echo "##owenloop:payload## $(jq -nc '{value:"deep"}')"
330
+ jq -nc '{value:"deep"}' > "$OWENLOOP_PAYLOAD_FILE"
331
+ ```
332
+
333
+ Rules a script can rely on:
334
+
335
+ - **Absent or empty means no payload.** A path that was never written, an empty
336
+ file, and a file holding only whitespace are all read as "this command
337
+ returned nothing", not as an error. That is what lets every existing
338
+ marker-only command keep working with the variable set.
339
+ - **Using both transports is refused by name.** If the file holds anything and a
340
+ marker line was also printed, neither is published: the receipt carries a
341
+ `payloadError` naming the conflict and both byte counts, and no `payload`.
342
+ Two statements of the result are a bug in the command, and picking one of them
343
+ would publish a value the author did not choose.
344
+ - **The reject directive works identically through either transport.** A payload
345
+ of the shape `{"reject":{"path":"...","text":"..."}}` sends the worker's
346
+ reject, from the file exactly as from the marker.
347
+ - **Over the cap is an error, not a truncation.** The size is taken from the
348
+ open descriptor before any bytes are read; over-cap produces a `payloadError`
349
+ naming the size and the cap, and no `payload`.
350
+ - **Anything that is not a regular file is an error.** A directory, a symbolic
351
+ link, or a device at that path produces a `payloadError` rather than being
352
+ read through. Only ENOENT is the ordinary absence.
353
+ - **The file lives only as long as the command.** It is in a private temp
354
+ directory that owenloop removes after the command exits, including when the
355
+ command is killed because the lease was lost. Write it during the run; do not
356
+ stash the path.
357
+
358
+ A definition whose command writes that file **must** declare the
359
+ `command-payload-file.v1` runtime feature. On a CLI that predates it the
360
+ variable is simply unset, and the natural defensive spelling
361
+ `> "${OWENLOOP_PAYLOAD_FILE:-/dev/null}"` then exits zero having written the
362
+ result to `/dev/null`. Nothing reports an error; the first sign of trouble is a
363
+ downstream bind failing at the hub, one step away from the cause. The feature
364
+ declaration moves that diagnosis to the bundle compatibility check, before any
365
+ order is offered.
366
+
301
367
  ## Working directory for command steps
302
368
 
303
369
  An order carries a `workdir` when its step declared `workdir:` or
package/docs/cli.md CHANGED
@@ -739,8 +739,12 @@ be parsed or the resolved value was invalid.
739
739
 
740
740
  The helper prints the selected word as ordinary stdout. A command artifact is
741
741
  submitted as the full `CommandReceipt`; if a workflow binds a field inside a
742
- command payload, the command must emit the `##owenloop:payload##` JSON marker and
743
- the bind must name that field (for example, `from: payload.value`).
742
+ command payload, the command must return that payload and the bind must name
743
+ the field (for example, `from: payload.value`). A command returns a payload
744
+ either by printing an `##owenloop:payload##` JSON marker line, capped at 64 KiB,
745
+ or by writing the JSON to the path in `OWENLOOP_PAYLOAD_FILE`, capped at 24 MB.
746
+ Doing both is refused by name rather than resolved by precedence. See
747
+ [Returning a payload from a command step](bundles.md#returning-a-payload-from-a-command-step).
744
748
 
745
749
  ### `work agent-run` — the only Step Agent dispatcher
746
750
 
package/docs/design.md CHANGED
@@ -1003,9 +1003,15 @@ with code `0`. A nonzero exit sends the worker's `reject` request for
1003
1003
  `order.judge` and submits no receipt. A signal or machinery failure has no
1004
1004
  verdict, so the worker issues neither verb and the reap path re-offers the order.
1005
1005
 
1006
- Command receipts may also carry a bounded JSON payload emitted by a stdout line
1007
- beginning with `##owenloop:payload##`. The last marker line wins, and the 64 KiB
1008
- JSON-text cap protects the runner because the runner does not buffer full stdout.
1006
+ Command receipts may also carry a bounded JSON payload, returned either by a
1007
+ stdout line beginning with `##owenloop:payload##` or by writing the JSON to the
1008
+ path the worker offers in `OWENLOOP_PAYLOAD_FILE`. The last marker line wins,
1009
+ and the marker's 64 KiB JSON-text cap protects the runner because the runner
1010
+ does not buffer full stdout. That cap is a property of the transport rather than
1011
+ of the result, which is why the file exists: it carries up to 24 MB, below the
1012
+ hub's own artifact cap. Returning a payload through both transports in one run
1013
+ is refused by name instead of resolved by precedence, because two statements of
1014
+ the result are an error in the command rather than a choice for the worker.
1009
1015
  A valid plain-step payload reject is delivered BEFORE any owed receipt is
1010
1016
  submitted. The hub refuses a reject from a run whose claim has closed, and a
1011
1017
  step's last owed submit is what closes it — so the reverse order made every
package/docs/routing.md CHANGED
@@ -564,8 +564,9 @@ from the run's stored value again — whatever the last accepted bind left there
564
564
  accepted artifact value is the whole `CommandReceipt`. The short form
565
565
  `bind: modifier` is shorthand for `{to: modifier, from: modifier}`. A
566
566
  `CommandReceipt` has no top-level `modifier` key, so that derived path does
567
- not resolve and the submit is refused. Have the command emit a payload marker —
568
- `##owenloop:payload##{"value":"deep"}` — and bind `from: payload.value`.
567
+ not resolve and the submit is refused. Have the command return a payload —
568
+ either the marker `##owenloop:payload##{"value":"deep"}` on stdout or the same
569
+ JSON written to `$OWENLOOP_PAYLOAD_FILE` — and bind `from: payload.value`.
569
570
 
570
571
  > **Not shipped.** The routing plan also calls for a hub-side routing alert of
571
572
  > kind `modifier-changed`, raised on each sync so an operator sees it. It exists
@@ -379,7 +379,10 @@ implemented at the consuming driver boundary and never delegated to the hub.
379
379
 
380
380
  ## Command payload and worker reject contracts
381
381
 
382
- A command worker may emit one payload marker line on stdout:
382
+ A command worker returns a payload through one of two transports, and the
383
+ receipt records exactly one of `payload` or `payloadError` either way.
384
+
385
+ The first is a marker line on stdout:
383
386
 
384
387
  ```text
385
388
  ##owenloop:payload## {"...json..."}
@@ -390,6 +393,24 @@ beginning of the line. A marker in the middle of a line is not a match. The JSON
390
393
  text after the marker is capped at 64 KiB. A missing marker leaves `payload`
391
394
  out of the `CommandReceipt`; malformed or over-cap JSON produces
392
395
  `payloadError` and no `payload`, while leaving the command exit code unchanged.
396
+
397
+ The second is a file. The worker sets `OWENLOOP_PAYLOAD_FILE` on every command
398
+ spawn to an absolute path inside a private `0700` directory it creates and
399
+ removes around the command's lifetime, and the command may write its JSON there
400
+ instead. The file's size is taken from the open descriptor before any bytes are
401
+ read and is capped at 24 MB, which is below the hub's artifact cap so that a
402
+ payload the worker accepts is one the hub can store. A path that does not exist,
403
+ holds nothing, or holds only whitespace is read as an absent payload — that is
404
+ what keeps a marker-only command working with the variable set. Anything at the
405
+ path that is not a regular file, and any read or parse failure, produces
406
+ `payloadError` and no `payload`. The worker opens the path without following
407
+ symbolic links and without blocking, so a path replaced mid-run cannot stall it.
408
+
409
+ Supplying both transports in one run is a refusal, not a precedence rule: the
410
+ receipt carries a `payloadError` naming the conflict and both byte counts, and
411
+ no `payload`. A definition whose command writes the file must declare the
412
+ `command-payload-file.v1` runtime feature, because an older worker leaves the
413
+ variable unset and the payload is then written nowhere without any error.
393
414
  When the hub supplies authoritative output-version metadata and the driver can
394
415
  sign, the parsed payload is part of the receipt value covered by the DSSE
395
416
  submission proof. Current successful producer command receipts are unsigned
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.25",
3
+ "version": "0.5.26",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.25",
3
+ "version": "0.5.26",
4
4
  "description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
5
5
  "author": {
6
6
  "name": "Typical Day"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.25"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.26"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.25",
3
+ "version": "0.5.26",
4
4
  "description": "Codex plugin for the owenloop workflow engine.",
5
5
  "skills": "./skills/",
6
6
  "mcpServers": "./.mcp.json"
@@ -6,7 +6,7 @@
6
6
  "mcp"
7
7
  ],
8
8
  "env": {
9
- "OWENLOOP_PLUGIN_VERSION": "0.5.25"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.26"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",