owenloop 0.5.4 → 0.5.5

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 (37) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/dist/packages/work/src/agent/brief.js +57 -1
  3. package/dist/packages/work/src/agent/loop.d.ts +10 -1
  4. package/dist/packages/work/src/agent/loop.js +25 -0
  5. package/dist/packages/work/src/agent/workdir.d.ts +22 -0
  6. package/dist/packages/work/src/agent/workdir.js +80 -0
  7. package/dist/packages/work/src/exec/loop.d.ts +13 -1
  8. package/dist/packages/work/src/exec/loop.js +31 -0
  9. package/dist/packages/work/src/harness/claude.js +7 -1
  10. package/dist/packages/work/src/hold/mcp.d.ts +11 -2
  11. package/dist/packages/work/src/hold/mcp.js +69 -2
  12. package/dist/packages/work/src/hub/client.d.ts +8 -1
  13. package/dist/packages/work/src/hub/client.js +1 -0
  14. package/dist/packages/work/src/hub/types.d.ts +29 -0
  15. package/dist/packages/work/src/roles/agent-run.js +9 -1
  16. package/dist/packages/work/src/roles/exec.js +9 -0
  17. package/dist/packages/work/src/roles/shift.js +9 -1
  18. package/dist/packages/work/src/settings/settings.d.ts +20 -1
  19. package/dist/packages/work/src/settings/settings.js +23 -1
  20. package/dist/packages/work/src/shift/runtime.d.ts +7 -0
  21. package/dist/packages/work/src/shift/runtime.js +29 -4
  22. package/dist/packages/work/src/shift/spawn.d.ts +12 -2
  23. package/dist/packages/work/src/shift/spawn.js +16 -3
  24. package/dist/src/cli.js +54 -1
  25. package/dist/src/engine.d.ts +46 -1
  26. package/dist/src/engine.js +72 -0
  27. package/dist/src/index.d.ts +1 -1
  28. package/dist/src/index.js +1 -1
  29. package/dist/src/model.d.ts +29 -5
  30. package/dist/src/model.js +63 -14
  31. package/dist/src/types.d.ts +8 -2
  32. package/docs/cli.md +34 -0
  33. package/package.json +1 -1
  34. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  35. package/plugins/claude-code/plugin/.mcp.json +1 -1
  36. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  37. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
@@ -15,6 +15,7 @@ function usage() {
15
15
  ' [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]\n' +
16
16
  ' [--cache-dir <p>] [--state-dir <p>]\n' +
17
17
  ' [--log-dir <p>] [--log-max-age <ms>]\n' +
18
+ ' [--work-root <dir>]... restrict this shift to these directories\n' +
18
19
  ' owenloop shift next [--wait <seconds>] [--state-dir <p>]\n' +
19
20
  ' owenloop shift status [--state-dir <p>]\n' +
20
21
  ' owenloop shift end [--state-dir <p>]\n');
@@ -30,7 +31,7 @@ function parseStartArgs(args) {
30
31
  const parsed = { crews: [] };
31
32
  const valueFlags = new Set([
32
33
  '--origin', '--as', '--name', '--cap', '--max-agents', '--poll-interval',
33
- '--cache-dir', '--state-dir', '--log-dir', '--log-max-age',
34
+ '--cache-dir', '--state-dir', '--log-dir', '--log-max-age', '--work-root',
34
35
  ]);
35
36
  for (let i = 0; i < args.length; i++) {
36
37
  const raw = args[i];
@@ -87,6 +88,13 @@ function parseStartArgs(args) {
87
88
  return { crews: parsed.crews, error: n };
88
89
  parsed.pollIntervalMs = n;
89
90
  }
91
+ else if (name === '--work-root') {
92
+ // REPEATABLE — one directory per occurrence. See `ParsedArgs.workRoots`
93
+ // in `src/shift/runtime.ts` for why this accumulates instead of taking
94
+ // a separated list, and `src/agent/workdir.ts` for how this differs
95
+ // from the singular `workRoot` setting.
96
+ (parsed.workRoots ??= []).push(value);
97
+ }
90
98
  continue;
91
99
  }
92
100
  if (raw.startsWith('-'))
@@ -99,6 +99,25 @@ export interface Settings {
99
99
  * of the MACHINE running the shift, not of the workflow.
100
100
  */
101
101
  workRepo?: string;
102
+ /**
103
+ * The directories a shift on THIS machine may accept as an order's working
104
+ * directory. Absolute paths; a directory permits itself and everything under
105
+ * it.
106
+ *
107
+ * NOT `workRoot` (above) UNDER A DIFFERENT NAME. `workRoot` is a directory
108
+ * owenloop writes per-run subdirectories INTO. This is a list of directories
109
+ * a HUB-SUPPLIED `OrderPacket.workdir` is allowed to name. See
110
+ * `src/agent/workdir.ts` for the side-by-side table and the full rationale.
111
+ *
112
+ * UNSET OR EMPTY MEANS NO RESTRICTION, which is what every shift running
113
+ * today does. Default-closed would refuse work on upgrade, silently, on
114
+ * machines whose operator never asked for a boundary.
115
+ *
116
+ * Overridden by `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (PATH-style, `:`-separated)
117
+ * and by `owenloop shift start --work-root <dir>` (repeatable). The override
118
+ * REPLACES this list; it does not extend it.
119
+ */
120
+ allowedWorkdirRoots?: string[];
102
121
  /**
103
122
  * How THIS machine serves each capability: a flat map from capability to
104
123
  * `{model, effort}`, keyed by the composed capability (`wise:deep`) or by the
@@ -113,7 +132,7 @@ export interface Settings {
113
132
  capabilityModels?: Record<string, CapabilityModelRow>;
114
133
  }
115
134
  /** The known settings keys, in the order `owenloop work settings` prints them. */
116
- export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "shiftLogDir", "shiftLogMaxAgeMs", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "workRoot", "workRepo", "capabilityModels"];
135
+ export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "shiftLogDir", "shiftLogMaxAgeMs", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "workRoot", "workRepo", "allowedWorkdirRoots", "capabilityModels"];
117
136
  /**
118
137
  * Keys owenloop still RECOGNIZES but no longer acts on. Each one produces a
119
138
  * warning naming what replaced it, and is excluded from `unrecognized` so the
@@ -13,7 +13,7 @@
13
13
  * own store (the CredentialReader seam) — there is deliberately no token knob.
14
14
  */
15
15
  import { existsSync, readFileSync } from 'node:fs';
16
- import { join } from 'node:path';
16
+ import { isAbsolute, join } from 'node:path';
17
17
  import { owenloopConfigDir } from "../../../../src/config-dir.js";
18
18
  import { validateCapabilityModels } from "../agent/capability-model.js";
19
19
  /** The known settings keys, in the order `owenloop work settings` prints them. */
@@ -30,6 +30,7 @@ export const KNOWN_SETTINGS_KEYS = [
30
30
  'maxConcurrentAgents',
31
31
  'workRoot',
32
32
  'workRepo',
33
+ 'allowedWorkdirRoots',
33
34
  'capabilityModels',
34
35
  ];
35
36
  /**
@@ -114,6 +115,27 @@ export function validateSettings(raw, path) {
114
115
  `Depth now rides on the capability's modifier suffix, not on a tier rung.`);
115
116
  }
116
117
  }
118
+ if ('allowedWorkdirRoots' in obj) {
119
+ // ABSOLUTE PATHS ONLY, and that is the one rule worth a hard error rather
120
+ // than a warning. A relative entry would resolve against whatever directory
121
+ // the shift process happened to start in — the very "wherever the shift was
122
+ // launched" assumption this key exists to remove — so a boundary written
123
+ // relatively would move with the launch directory and permit a different
124
+ // set of paths on every start.
125
+ const v = obj['allowedWorkdirRoots'];
126
+ if (!Array.isArray(v) || v.some((entry) => typeof entry !== 'string')) {
127
+ throw bad('allowedWorkdirRoots', 'an array of absolute directory paths', v);
128
+ }
129
+ for (const entry of v) {
130
+ if (entry.trim() === '') {
131
+ throw bad('allowedWorkdirRoots', 'an array of NON-EMPTY absolute directory paths', v);
132
+ }
133
+ if (!isAbsolute(entry)) {
134
+ throw new Error(`invalid settings file at ${path}: 'allowedWorkdirRoots' entry ${JSON.stringify(entry)} must be an ` +
135
+ `absolute path — a relative root would resolve against whatever directory the shift was launched in`);
136
+ }
137
+ }
138
+ }
117
139
  if ('capabilityModels' in obj) {
118
140
  const v = obj['capabilityModels'];
119
141
  if (typeof v !== 'object' || v === null || Array.isArray(v)) {
@@ -35,6 +35,13 @@ export interface ParsedArgs {
35
35
  logDir?: string;
36
36
  /** `--log-max-age` — worker-log retention in milliseconds. `0` reaps eagerly. */
37
37
  logMaxAgeMs?: number;
38
+ /**
39
+ * `--work-root <dir>` — REPEATABLE. Each occurrence adds one directory the
40
+ * shift may accept as an order's working directory; passing none leaves the
41
+ * shift unrestricted. Distinct from `settings.workRoot` (singular), which is
42
+ * where owenloop CREATES per-run directories — see `src/agent/workdir.ts`.
43
+ */
44
+ workRoots?: string[];
38
45
  error?: string;
39
46
  }
40
47
  /** Parse shift's internal `--flag value` and `--flag=value` forms. */
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import { randomUUID } from 'node:crypto';
10
10
  import { hostname } from 'node:os';
11
- import { basename, join } from 'node:path';
11
+ import { basename, join, resolve } from 'node:path';
12
12
  import { performance } from 'node:perf_hooks';
13
13
  import { createHubClient } from "../hub/client.js";
14
14
  import { resolveBearer } from "../credentials/resolve.js";
@@ -21,7 +21,7 @@ import { stampShiftEvent } from "./protocol.js";
21
21
  import { createDefaultSpawner } from "./spawn.js";
22
22
  import { resolveStateDir, ensureStateDir, reconcileInFlight } from "./state.js";
23
23
  import { reconcileActiveSessions, sessionsPath } from "../harness/session-store.js";
24
- import { resolveWorkRepo, resolveWorkRoot } from "../agent/workdir.js";
24
+ import { resolveAllowedWorkdirRoots, resolveWorkRepo, resolveWorkRoot, } from "../agent/workdir.js";
25
25
  import { installSignalHandlers } from "../roles/signals.js";
26
26
  import { createShiftDaemon } from "./server.js";
27
27
  import { createBundleIngestor, createStoreInstructionSource, globalStoreRoot, } from "../../../../src/store/index.js";
@@ -153,6 +153,7 @@ export function parseArgs(args) {
153
153
  case '--cache-dir':
154
154
  case '--log-dir':
155
155
  case '--log-max-age':
156
+ case '--work-root':
156
157
  case '--state-dir': {
157
158
  const r = takeValue(a, i);
158
159
  if ('error' in r)
@@ -202,6 +203,13 @@ export function parseArgs(args) {
202
203
  return { error: n.error };
203
204
  parsed.pollIntervalMs = n;
204
205
  }
206
+ else if (name === '--work-root') {
207
+ // ACCUMULATES rather than overwrites — one directory per occurrence
208
+ // is what makes a multi-project boundary expressible at all. A shift
209
+ // that may work in two projects needs two roots, and there is no
210
+ // separator that is safe inside a path on every platform.
211
+ (parsed.workRoots ??= []).push(r.value);
212
+ }
205
213
  break;
206
214
  }
207
215
  default:
@@ -214,7 +222,7 @@ function usage() {
214
222
  process.stderr.write('usage: owenloop work shift [--origin <url>] [--as <account>] [--name <n>] [--serve-crews a,b] [--cap <n>]\n' +
215
223
  ' [--workflow <id>] [--poll-interval <ms>] [--once]\n' +
216
224
  ' [--max-agents <n>] [--cache-dir <p>] [--state-dir <p>]\n' +
217
- ' [--log-dir <p>] [--log-max-age <ms>]\n');
225
+ ' [--log-dir <p>] [--log-max-age <ms>] [--work-root <dir>]...\n');
218
226
  }
219
227
  function errMsg(err) {
220
228
  return err instanceof Error ? err.message : String(err);
@@ -335,6 +343,23 @@ export async function runShiftRuntime(parsed, options = {}) {
335
343
  const maxConcurrentAgents = resolveMaxConcurrentAgents(parsed.maxAgents, settings.maxConcurrentAgents);
336
344
  const workRoot = resolveWorkRoot(env, settings.workRoot, cacheDir);
337
345
  const workRepo = resolveWorkRepo(env, settings.workRepo);
346
+ /**
347
+ * The operator's filesystem boundary, resolved once here so the loop receives
348
+ * an already-absolute list and does no precedence work of its own.
349
+ *
350
+ * Precedence is `--work-root` (repeatable) > `OWENLOOP_ALLOWED_WORKDIR_ROOTS`
351
+ * > `settings.allowedWorkdirRoots` > none. Each rung REPLACES the one below
352
+ * rather than adding to it: a narrowing control that could only ever widen
353
+ * would not be a safety control at all.
354
+ *
355
+ * Relative entries resolve against THIS process's cwd, which is where the
356
+ * operator typed the flag. `settings.allowedWorkdirRoots` cannot be relative
357
+ * — `validateSettings` rejects that at load, because a stored boundary that
358
+ * moves with the launch directory is the exact failure this key removes.
359
+ */
360
+ const allowedWorkdirRoots = parsed.workRoots !== undefined && parsed.workRoots.length > 0
361
+ ? parsed.workRoots.map((entry) => resolve(process.cwd(), entry))
362
+ : resolveAllowedWorkdirRoots(env, settings.allowedWorkdirRoots, process.cwd());
338
363
  const hub = createHubClient({ origin, getToken: async () => token });
339
364
  const now = () => Date.now();
340
365
  const monotonicNow = () => performance.now();
@@ -445,7 +470,7 @@ export async function runShiftRuntime(parsed, options = {}) {
445
470
  // output discarded exactly as it did before this change.
446
471
  logDirReady
447
472
  ? { dir: logDir, err: (line) => process.stderr.write(`${line}\n`) }
448
- : undefined);
473
+ : undefined, allowedWorkdirRoots);
449
474
  const pollIntervalMs = parsed.pollIntervalMs ?? DEFAULT_POLL_MS;
450
475
  const loop = createShiftLoop({
451
476
  hub,
@@ -164,13 +164,23 @@ export interface SpawnPlan {
164
164
  * step, registered default). The Shift command has no operator-facing harness
165
165
  * flag, so there is no legitimate CLI override for this seam to carry.
166
166
  *
167
+ * `allowedWorkdirRoots` (trailing, for the same reason) rides the child's spawn
168
+ * env as `OWENLOOP_ALLOWED_WORKDIR_ROOTS`, a `:`-separated list — the same
169
+ * "spawn env is the contract" shape as `OWENLOOP_ACCOUNT`, and for the same
170
+ * reason: neither `owenloop work exec` nor `owenloop work agent-run` has an
171
+ * operator-facing flag for it. It carries the roots the SHIFT resolved, so an
172
+ * operator's `owenloop shift start --work-root` reaches a detached child that
173
+ * would otherwise only see the settings file. Empty or omitted sets no variable
174
+ * at all, so the child falls through to its own settings-file resolution and
175
+ * the plan stays byte-identical to the pre-policy shape.
176
+ *
167
177
  * `logDir` (trailing, after `shiftId`, for the same reason) adds the worker's
168
178
  * log DESTINATION to the plan as `<logDir>/<run>.log`. The plan still carries
169
179
  * `stdio: ['ignore','ignore','ignore']`: opening the file is I/O, this function
170
180
  * is pure, and `createDefaultSpawner` substitutes the descriptors. Omitted ⇒ no
171
181
  * `logFile` key at all, and the plan is byte-identical to the pre-logging shape.
172
182
  */
173
- export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string, logDir?: string): SpawnPlan;
183
+ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string, logDir?: string, allowedWorkdirRoots?: string[]): SpawnPlan;
174
184
  /**
175
185
  * The default detached spawner. Captures the resolved hub `origin`, the
176
186
  * resolved `account`, the packaged bin path, and the dispatching Shift's
@@ -179,4 +189,4 @@ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account:
179
189
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
180
190
  * — can be supplied positionally.
181
191
  */
182
- export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter, logging?: WorkerLogOptions): Spawner;
192
+ export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter, logging?: WorkerLogOptions, allowedWorkdirRoots?: string[]): Spawner;
@@ -134,13 +134,23 @@ export function reportedHarnessId(spec, env) {
134
134
  * step, registered default). The Shift command has no operator-facing harness
135
135
  * flag, so there is no legitimate CLI override for this seam to carry.
136
136
  *
137
+ * `allowedWorkdirRoots` (trailing, for the same reason) rides the child's spawn
138
+ * env as `OWENLOOP_ALLOWED_WORKDIR_ROOTS`, a `:`-separated list — the same
139
+ * "spawn env is the contract" shape as `OWENLOOP_ACCOUNT`, and for the same
140
+ * reason: neither `owenloop work exec` nor `owenloop work agent-run` has an
141
+ * operator-facing flag for it. It carries the roots the SHIFT resolved, so an
142
+ * operator's `owenloop shift start --work-root` reaches a detached child that
143
+ * would otherwise only see the settings file. Empty or omitted sets no variable
144
+ * at all, so the child falls through to its own settings-file resolution and
145
+ * the plan stays byte-identical to the pre-policy shape.
146
+ *
137
147
  * `logDir` (trailing, after `shiftId`, for the same reason) adds the worker's
138
148
  * log DESTINATION to the plan as `<logDir>/<run>.log`. The plan still carries
139
149
  * `stdio: ['ignore','ignore','ignore']`: opening the file is I/O, this function
140
150
  * is pure, and `createDefaultSpawner` substitutes the descriptors. Omitted ⇒ no
141
151
  * `logFile` key at all, and the plan is byte-identical to the pre-logging shape.
142
152
  */
143
- export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId, logDir) {
153
+ export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId, logDir, allowedWorkdirRoots) {
144
154
  const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
145
155
  return {
146
156
  command: execPath,
@@ -160,6 +170,9 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
160
170
  ...process.env,
161
171
  OWENLOOP_ACCOUNT: account,
162
172
  ...(spec.startGate !== undefined ? { OWENLOOP_START_GATE: spec.startGate } : {}),
173
+ ...(allowedWorkdirRoots !== undefined && allowedWorkdirRoots.length > 0
174
+ ? { OWENLOOP_ALLOWED_WORKDIR_ROOTS: allowedWorkdirRoots.join(':') }
175
+ : {}),
163
176
  },
164
177
  },
165
178
  ...(logDir !== undefined && logDir !== '' ? { logFile: runLogFile(logDir, spec.run) } : {}),
@@ -173,7 +186,7 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
173
186
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
174
187
  * — can be supplied positionally.
175
188
  */
176
- export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure, logging) {
189
+ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure, logging, allowedWorkdirRoots) {
177
190
  // ONE report per shift, not one per dispatch. Every condition that stops a
178
191
  // worker log from opening — a full disk, a read-only log directory, an
179
192
  // operator deleting it underneath a running shift — PERSISTS across the
@@ -189,7 +202,7 @@ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopB
189
202
  logging?.err?.(line);
190
203
  };
191
204
  return (spec) => {
192
- const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId, logging?.dir);
205
+ const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId, logging?.dir, allowedWorkdirRoots);
193
206
  // Open the log ONCE and hand the SAME descriptor to slots 1 and 2. Opening
194
207
  // it twice would create two independent file offsets, and the two streams
195
208
  // would overwrite each other's bytes — silent corruption no unit test on the
package/dist/src/cli.js CHANGED
@@ -1171,7 +1171,9 @@ ${' '.repeat(41)}the loaded def has drifted from the version the instance is pin
1171
1171
  reject <wf> <path> --by <author> --text <msg>
1172
1172
  retract <wf> <path> --by <author> --text <msg>
1173
1173
  skip <wf> <path> --by <author> --text <msg>
1174
- retry <wf> <path> [--by <author>] [--text <guidance>] clear a §6 stall
1174
+ retry <wf> <path> [--by <author>] [--text <guidance>] clear a §6 stall, or ANSWER an ask
1175
+ ask <wf> <path> <question> [--by <author>] hold an owed artifact on a question for a human
1176
+ inbox every held question across all instances, with its answer command
1175
1177
  heartbeat <wf> <run> [--now <ms>] touch liveness timestamp on an open run
1176
1178
  close <wf> <run> [--outcome ok|no_work|failed|skipped] [--summary s]
1177
1179
  delete <wf> [--recursive] refuse if children exist unless --recursive (cascades)
@@ -1254,6 +1256,8 @@ export const COMMAND_OPTIONS = new Map([
1254
1256
  ['retract', cmdOpts('by', 'text')],
1255
1257
  ['skip', cmdOpts('by', 'text')],
1256
1258
  ['retry', cmdOpts('by', 'text')],
1259
+ ['ask', cmdOpts('by', 'question')],
1260
+ ['inbox', cmdOpts()],
1257
1261
  ['close', cmdOpts('outcome', 'summary')],
1258
1262
  ['heartbeat', cmdOpts('now')],
1259
1263
  ['delete', cmdOpts('recursive')],
@@ -1874,6 +1878,55 @@ function dispatch(command, io, args) {
1874
1878
  print(io, { ok: true, action: 'retry', path });
1875
1879
  return 0;
1876
1880
  }
1881
+ case 'ask': {
1882
+ // The escalation verb: the producing step stops and asks a human about
1883
+ // the artifact IT owes. The answer is a plain `retry --text "<answer>"`
1884
+ // — deliberately no `answer` verb, because `retry` already appends a
1885
+ // structural reason, which is exactly what clears the hold and delivers
1886
+ // the text to the next attempt.
1887
+ const wf = need(args, 1, 'workflow');
1888
+ const path = need(args, 2, 'path');
1889
+ const question = need(args, 3, 'question');
1890
+ engine.ask(wf, path, last(args, 'by') ?? 'human', question);
1891
+ print(io, { ok: true, action: 'ask', path, question });
1892
+ return 0;
1893
+ }
1894
+ case 'inbox': {
1895
+ // THE OPERATOR SURFACE for `ask`. Without it the channel is write-only:
1896
+ // a step can raise a question and nothing ever displays it, which is
1897
+ // the exact failure this whole change exists to end. Reads the LOCAL db
1898
+ // across every instance (no workflow argument) because a person asking
1899
+ // "is anything waiting on me?" does not know which instance to name.
1900
+ //
1901
+ // Each row carries the ready-to-paste release command, because the
1902
+ // answer path (`retry --text`) is not guessable from the question.
1903
+ const rows = [];
1904
+ for (const w of store.listWorkflows()) {
1905
+ let st;
1906
+ try {
1907
+ st = engine.status(w.id);
1908
+ }
1909
+ catch {
1910
+ // An instance whose def no longer resolves cannot be asked about;
1911
+ // skip it rather than aborting the sweep (same stance as `--all`).
1912
+ continue;
1913
+ }
1914
+ for (const d of st.debts) {
1915
+ if (d.question === undefined)
1916
+ continue;
1917
+ rows.push({
1918
+ workflow: w.id,
1919
+ def: w.def,
1920
+ title: w.title ?? null,
1921
+ path: d.path,
1922
+ question: d.question,
1923
+ answer: `owenloop retry ${w.id} ${d.path} --text "<your answer>"`,
1924
+ });
1925
+ }
1926
+ }
1927
+ print(io, rows);
1928
+ return 0;
1929
+ }
1877
1930
  case 'close': {
1878
1931
  const wf = need(args, 1, 'workflow');
1879
1932
  const run = need(args, 2, 'run');
@@ -218,7 +218,7 @@ export type EngineEvent = {
218
218
  workflow: string;
219
219
  run?: string;
220
220
  path: string;
221
- action: 'green' | 'emit' | 'seal' | 'reject' | 'retract' | 'skip' | 'retry' | 'provide';
221
+ action: 'green' | 'emit' | 'seal' | 'reject' | 'retract' | 'skip' | 'retry' | 'provide' | 'ask';
222
222
  outcome?: CommitResult['outcome'] | EmitResult['outcome'];
223
223
  } | {
224
224
  type: 'closed';
@@ -777,12 +777,57 @@ export declare class Engine {
777
777
  retract(workflow: string, path: string, by: Author, text: string): void;
778
778
  /** A producer skips its own owed output on a dead branch (§16.1 routing). */
779
779
  skip(workflow: string, path: string, by: Author, text: string): void;
780
+ /**
781
+ * ESCALATION: a producing step stops and asks a human, instead of guessing.
782
+ *
783
+ * WHY THIS IS A SEPARATE VERB AND NOT A FLAVOUR OF `reject`. `reject` is a
784
+ * *verdict on a built version* — it refuses any artifact that is not `green`
785
+ * or `submitted` (see the guard in `reject()`), because bumping
786
+ * `judgmentRejects` on a never-built `owed` artifact would burn stall budget
787
+ * with zero build attempts and silently freeze the producer. `ask` targets
788
+ * exactly that state: the artifact the asking step still OWES and has decided
789
+ * it cannot honestly build. Different precondition, different counter policy,
790
+ * different author — so, a different method.
791
+ *
792
+ * WHAT IT CLOSES. Before this verb a step agent that could not proceed had two
793
+ * options, and both were observed damaging real runs:
794
+ * 1. Submit something it did not believe. The artifact greens and every
795
+ * downstream step builds on a fabrication.
796
+ * 2. End its turn without submitting. The task re-arms, a fresh worker
797
+ * starts from the same missing information, and the step retries until
798
+ * it hits the stall cap — burning budget to relearn the same blocker.
799
+ * Neither ever reaches a person. `ask` is the third option.
800
+ *
801
+ * MECHANICS. The artifact moves `owed` → `rejected` with a trailing reason of
802
+ * kind `'question'`. `isHeld` (model.ts) recognises that kind, so `frozen()`
803
+ * is true and the engine stops re-arming the producer — no retry storm. NO
804
+ * counter moves: `judgmentRejects` and `schemaRejects` are untouched, because
805
+ * a question is not a failed attempt and must not consume stall budget.
806
+ *
807
+ * THE ANSWER IS `retry`. There is deliberately no `answer` verb. A human runs
808
+ * `owenloop retry <workflow> <path> --text "<answer>"`, which appends a
809
+ * `'structural'` reason — clearing held-ness automatically, since `isHeld`
810
+ * reads only the LAST entry — re-arms the artifact to `owed`, and leaves the
811
+ * answer sitting on the reason thread that the next fresh worker reads in its
812
+ * order. Two ways into held, one way out.
813
+ *
814
+ * AUTHORITY. Not `assertAuthority`: that follows the CONSUME edge (who may
815
+ * invalidate someone else's work), and this is the opposite direction — the
816
+ * producer speaking about its own debt. So the rule is that `by` must be the
817
+ * artifact's own producer (or `human`/`engine`).
818
+ */
819
+ ask(workflow: string, path: string, by: Author, question: string): void;
780
820
  /**
781
821
  * Human stall-clearing lever (§6): reset an artifact's judgment-reject count
782
822
  * and re-arm it to `owed`, optionally appending a line of guiding context that
783
823
  * rides to the next producer on the order's `owes` thread. This is how a
784
824
  * stalled (capped-out) artifact gets unstuck and steered, rather than thrashing
785
825
  * forever or being abandoned. For a stuck collection member, `retract` instead.
826
+ *
827
+ * This is ALSO the answer path for `ask` above — `retry --text "<answer>"`
828
+ * appends a `'structural'` reason, which clears held-ness and delivers the
829
+ * answer to the next worker on the same thread. There is no separate
830
+ * `answer` verb by design.
786
831
  */
787
832
  retry(workflow: string, path: string, by?: Author, text?: string): void;
788
833
  /** Close a run (audit/budget) and release its lease so the task can re-arm. */
@@ -2096,12 +2096,84 @@ export class Engine {
2096
2096
  this.fire({ type: 'commit', workflow, path, action: 'skip' });
2097
2097
  this.fireSettled(workflow);
2098
2098
  }
2099
+ /**
2100
+ * ESCALATION: a producing step stops and asks a human, instead of guessing.
2101
+ *
2102
+ * WHY THIS IS A SEPARATE VERB AND NOT A FLAVOUR OF `reject`. `reject` is a
2103
+ * *verdict on a built version* — it refuses any artifact that is not `green`
2104
+ * or `submitted` (see the guard in `reject()`), because bumping
2105
+ * `judgmentRejects` on a never-built `owed` artifact would burn stall budget
2106
+ * with zero build attempts and silently freeze the producer. `ask` targets
2107
+ * exactly that state: the artifact the asking step still OWES and has decided
2108
+ * it cannot honestly build. Different precondition, different counter policy,
2109
+ * different author — so, a different method.
2110
+ *
2111
+ * WHAT IT CLOSES. Before this verb a step agent that could not proceed had two
2112
+ * options, and both were observed damaging real runs:
2113
+ * 1. Submit something it did not believe. The artifact greens and every
2114
+ * downstream step builds on a fabrication.
2115
+ * 2. End its turn without submitting. The task re-arms, a fresh worker
2116
+ * starts from the same missing information, and the step retries until
2117
+ * it hits the stall cap — burning budget to relearn the same blocker.
2118
+ * Neither ever reaches a person. `ask` is the third option.
2119
+ *
2120
+ * MECHANICS. The artifact moves `owed` → `rejected` with a trailing reason of
2121
+ * kind `'question'`. `isHeld` (model.ts) recognises that kind, so `frozen()`
2122
+ * is true and the engine stops re-arming the producer — no retry storm. NO
2123
+ * counter moves: `judgmentRejects` and `schemaRejects` are untouched, because
2124
+ * a question is not a failed attempt and must not consume stall budget.
2125
+ *
2126
+ * THE ANSWER IS `retry`. There is deliberately no `answer` verb. A human runs
2127
+ * `owenloop retry <workflow> <path> --text "<answer>"`, which appends a
2128
+ * `'structural'` reason — clearing held-ness automatically, since `isHeld`
2129
+ * reads only the LAST entry — re-arms the artifact to `owed`, and leaves the
2130
+ * answer sitting on the reason thread that the next fresh worker reads in its
2131
+ * order. Two ways into held, one way out.
2132
+ *
2133
+ * AUTHORITY. Not `assertAuthority`: that follows the CONSUME edge (who may
2134
+ * invalidate someone else's work), and this is the opposite direction — the
2135
+ * producer speaking about its own debt. So the rule is that `by` must be the
2136
+ * artifact's own producer (or `human`/`engine`).
2137
+ */
2138
+ ask(workflow, path, by, question) {
2139
+ const def = this.defFor(workflow);
2140
+ this.store.tx(() => {
2141
+ const art = this.store.getArtifact(workflow, path);
2142
+ if (!art)
2143
+ throw new Error(`cannot ask about unknown artifact: ${path}`);
2144
+ if (by !== 'human' && by !== 'engine' && art.producer !== by) {
2145
+ throw new Error(`${by} has no authority to ask about ${path} (it is produced by '${art.producer}'). ` +
2146
+ `\`ask\` is the producer speaking about its own debt; to send someone else's work back, use \`reject\`.`);
2147
+ }
2148
+ // A question is only meaningful about work not yet delivered. On a
2149
+ // `green`/`submitted` artifact the honest move is `reject` (there is a
2150
+ // version to have an opinion about); on `retracted`/`skipped` there is no
2151
+ // live debt left to answer.
2152
+ if (art.acceptance !== 'owed' && art.acceptance !== 'rejected') {
2153
+ throw new Error(`cannot ask about '${path}' in state '${art.acceptance}': ` +
2154
+ `\`ask\` records a blocker on work still owed (owed|rejected)`);
2155
+ }
2156
+ this.store.putArtifact({
2157
+ ...art,
2158
+ acceptance: 'rejected',
2159
+ reasons: [...art.reasons, reason('ask', 'question', by, question, art.version)],
2160
+ });
2161
+ this.settle(workflow, def);
2162
+ });
2163
+ this.fire({ type: 'commit', workflow, path, action: 'ask' });
2164
+ this.fireSettled(workflow);
2165
+ }
2099
2166
  /**
2100
2167
  * Human stall-clearing lever (§6): reset an artifact's judgment-reject count
2101
2168
  * and re-arm it to `owed`, optionally appending a line of guiding context that
2102
2169
  * rides to the next producer on the order's `owes` thread. This is how a
2103
2170
  * stalled (capped-out) artifact gets unstuck and steered, rather than thrashing
2104
2171
  * forever or being abandoned. For a stuck collection member, `retract` instead.
2172
+ *
2173
+ * This is ALSO the answer path for `ask` above — `retry --text "<answer>"`
2174
+ * appends a `'structural'` reason, which clears held-ness and delivers the
2175
+ * answer to the next worker on the same thread. There is no separate
2176
+ * `answer` verb by design.
2105
2177
  */
2106
2178
  retry(workflow, path, by = 'human', text = 'retry: stall cleared') {
2107
2179
  const def = this.defFor(workflow);
@@ -35,7 +35,7 @@ export { DEF_POLICY_RANK, POLICY_FLOOR_PRESETS, artifactPolicyMinimum, floorDefP
35
35
  export type { PolicyFloorGap, PolicyFloorMergeResult, PolicyFloorVerdict, VerifyPolicyFloorInput, VerifyPolicyFloorOptions, } from './crypto/index.ts';
36
36
  export { ORIGIN_SOURCE_RANK, OriginRulesError, evaluateOriginRule, matchOriginRule, parseOriginRules, } from './crypto/index.ts';
37
37
  export type { OriginPolicy, OriginRuleEvaluation, OriginRuleMatch, OriginRuleValue, OriginRules, } from './crypto/index.ts';
38
- export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isStalled, modelCheck, workflowStatus, } from './model.ts';
38
+ export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isHeld, isStalled, modelCheck, openQuestion, workflowStatus, } from './model.ts';
39
39
  export type { ArtifactMap, Blocker, Firing, TimeFacts, WorkflowStatus } from './model.ts';
40
40
  export { parseConsume, parseProduce, } from './paths.ts';
41
41
  export { assertValidSchema, summarizeIssues, validateValue } from './schema.ts';
package/dist/src/index.js CHANGED
@@ -30,7 +30,7 @@ export { DSSE_SSH_NAMESPACE, DSSE_VERSION, DSSE_RECORD_PAYLOAD_TYPES, DsseEnvelo
30
30
  export { DEF_POLICY_RANK, POLICY_FLOOR_PRESETS, artifactPolicyMinimum, floorDefPolicyMinimum, mergePolicyFloorWithLocal, originRulesMinimum, policyFloorGaps, stricterDefPolicy, verifyPolicyFloorRecord, } from "./crypto/index.js";
31
31
  // ---- WP-E2a origin execution policy ----
32
32
  export { ORIGIN_SOURCE_RANK, OriginRulesError, evaluateOriginRule, matchOriginRule, parseOriginRules, } from "./crypto/index.js";
33
- export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isStalled, modelCheck, workflowStatus, } from "./model.js";
33
+ export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isHeld, isStalled, modelCheck, openQuestion, workflowStatus, } from "./model.js";
34
34
  export { parseConsume, parseProduce, } from "./paths.js";
35
35
  export { assertValidSchema, summarizeIssues, validateValue } from "./schema.js";
36
36
  export { enrollmentGrantSchema, orderSchema, originSchema, policyFloorSchema, publicationSchema, RECORD_SCHEMAS, revocationSchema, SCHEMA_BY_PAYLOAD_TYPE, submissionSchema, WIRE_SCHEMAS, } from "./schemas/index.js";
@@ -128,12 +128,28 @@ export declare function isStalled(a: ArtifactData | undefined, cap: number): boo
128
128
  */
129
129
  export declare function isSchemaStalled(a: ArtifactData | undefined, cap: number): boolean;
130
130
  /**
131
- * True if the artifact is held (non-idempotent escalate) — rejected-and-held,
132
- * producer not auto-eligible to re-fire. Detected by the last reasons entry
133
- * having kind='invalidated-irreversible'. A retry call appends a 'structural'
134
- * entry, which clears the held condition automatically.
131
+ * True if the artifact is held — rejected-and-held, producer not auto-eligible
132
+ * to re-fire. Detected by the last reasons entry having a holding kind. A retry
133
+ * call appends a 'structural' entry, which clears the held condition
134
+ * automatically, so `retry --text '<answer>'` is the release for both kinds.
135
+ *
136
+ * TWO WAYS IN, ONE WAY OUT.
137
+ * - `invalidated-irreversible`: the engine held it because an input moved under
138
+ * a non-idempotent producer.
139
+ * - `question`: the producing STEP held it, via `Engine.ask`, because it could
140
+ * not proceed honestly and needs a human. Without this second kind an agent
141
+ * has no way to stop: its only alternatives are to submit something it does
142
+ * not believe (which greens and silently poisons every downstream step) or to
143
+ * end its turn without submitting (which re-arms the step into a retry storm
144
+ * whose every worker fails identically). Both were observed in production.
135
145
  */
136
146
  export declare function isHeld(a: ArtifactData | undefined): boolean;
147
+ /**
148
+ * The open question on a held artifact, if it is held by `ask`. Returns the
149
+ * question text so an operator-facing read can print WHAT is being asked
150
+ * instead of only that something is stuck — the whole point of the channel.
151
+ */
152
+ export declare function openQuestion(a: ArtifactData | undefined): string | undefined;
137
153
  /**
138
154
  * §7 escalation trigger: has this artifact been judgment-rejected at least
139
155
  * `after` times in the CURRENT rejection episode?
@@ -293,10 +309,18 @@ export interface WorkflowStatus {
293
309
  debts: Array<{
294
310
  path: string;
295
311
  acceptance: Acceptance;
296
- kind: 'judgment' | 'structural' | 'validation' | 'unbuilt' | 'invalidated-irreversible';
312
+ kind: 'judgment' | 'structural' | 'validation' | 'unbuilt' | 'invalidated-irreversible' | 'question';
297
313
  /** §6/§18/held: rejected past its producer's cap, or held — the engine won't re-arm it */
298
314
  stalled: boolean;
299
315
  reason?: string;
316
+ /**
317
+ * The open question, when `kind === 'question'` — the producing step called
318
+ * `Engine.ask` and stopped waiting on a human. Same string as `reason`,
319
+ * surfaced under its own name so an operator-facing reader can filter for
320
+ * "what is waiting on ME" without pattern-matching a kind. Absent on every
321
+ * other debt shape.
322
+ */
323
+ question?: string;
300
324
  /**
301
325
  * Consecutive trailing `failed` runs for this debt's producer (crash-step
302
326
  * signal). Enriched by `engine.status()` from the run log — `workflowStatus`