owenloop 0.5.1 → 0.5.2

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 (81) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  13. package/dist/packages/work/src/harness/session-store.js +46 -22
  14. package/dist/packages/work/src/hold/mcp.js +9 -2
  15. package/dist/packages/work/src/hub/client.d.ts +7 -1
  16. package/dist/packages/work/src/hub/client.js +1 -0
  17. package/dist/packages/work/src/hub/types.d.ts +71 -3
  18. package/dist/packages/work/src/roles/agent-run.js +8 -9
  19. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  20. package/dist/packages/work/src/roles/hold.js +39 -8
  21. package/dist/packages/work/src/roles/settings.js +18 -6
  22. package/dist/packages/work/src/roles/shift.js +13 -1
  23. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  24. package/dist/packages/work/src/settings/settings.js +69 -22
  25. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  26. package/dist/packages/work/src/shift/logretention.js +407 -0
  27. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  28. package/dist/packages/work/src/shift/logsink.js +98 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  30. package/dist/packages/work/src/shift/loop.js +250 -12
  31. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  32. package/dist/packages/work/src/shift/protocol.js +14 -0
  33. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  34. package/dist/packages/work/src/shift/runtime.js +229 -6
  35. package/dist/packages/work/src/shift/server.d.ts +13 -0
  36. package/dist/packages/work/src/shift/server.js +61 -36
  37. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  38. package/dist/packages/work/src/shift/spawn.js +158 -12
  39. package/dist/packages/work/src/shift/state.d.ts +25 -0
  40. package/dist/packages/work/src/shift/state.js +29 -5
  41. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  42. package/dist/packages/work/src/shift/truncate.js +73 -0
  43. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  44. package/dist/packages/work/src/submit-proof.js +33 -7
  45. package/dist/packages/work/src/submit-value.d.ts +48 -0
  46. package/dist/packages/work/src/submit-value.js +118 -0
  47. package/dist/packages/work/src/usage.d.ts +1 -1
  48. package/dist/packages/work/src/usage.js +11 -0
  49. package/dist/src/capabilities.d.ts +93 -0
  50. package/dist/src/capabilities.js +101 -0
  51. package/dist/src/cli.js +14 -9
  52. package/dist/src/crypto/records.d.ts +3 -0
  53. package/dist/src/crypto/records.js +11 -0
  54. package/dist/src/defs.js +192 -4
  55. package/dist/src/engine.d.ts +112 -3
  56. package/dist/src/engine.js +224 -28
  57. package/dist/src/hub.d.ts +27 -11
  58. package/dist/src/hub.js +24 -18
  59. package/dist/src/index.d.ts +3 -1
  60. package/dist/src/index.js +4 -1
  61. package/dist/src/mcp/serve.js +11 -4
  62. package/dist/src/model.d.ts +36 -0
  63. package/dist/src/model.js +46 -0
  64. package/dist/src/schemas/index.d.ts +17 -0
  65. package/dist/src/schemas/order.v1.schema.json +17 -3
  66. package/dist/src/store.d.ts +33 -1
  67. package/dist/src/store.js +57 -4
  68. package/dist/src/types.d.ts +102 -2
  69. package/docs/authoring.md +7 -0
  70. package/docs/bundles.md +103 -3
  71. package/docs/cli.md +127 -9
  72. package/docs/crypto.md +23 -7
  73. package/docs/shift-logs.md +642 -0
  74. package/docs/wire-contracts.md +34 -19
  75. package/package.json +1 -1
  76. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  77. package/plugins/claude-code/plugin/.mcp.json +1 -1
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  81. package/dist/packages/work/src/agent/model-policy.js +0 -138
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Producer-side mirror of the hub's raw-string submit normalization.
3
+ *
4
+ * WHY THIS EXISTS — the proof-dropping bug it fixes:
5
+ *
6
+ * An agent may hand `submit` a JSON-encoded STRING instead of an object
7
+ * (`'{"prUrl":"…","number":145}'`). The hub accepts that as a documented
8
+ * fallback: `hub-core`'s `submitOutput` runs `normalizeSubmitValue` on it and
9
+ * stores the resulting OBJECT. But because the stored bytes are no longer the
10
+ * bytes the producer signed, the hub cannot claim the signature covers what it
11
+ * stored, so it drops the submission proof outright:
12
+ *
13
+ * const narrowedProof = typeof rawValue === 'string' ? undefined
14
+ * : narrowSubmitProof(proof);
15
+ *
16
+ * The drop is silent on both sides. The producer signed successfully and got no
17
+ * warning; the hub committed the artifact with no proof. A downstream COMMAND
18
+ * step consuming that artifact then refuses it forever (`hardRule: true`), and
19
+ * nothing in either log says why. Observed live: the delivery `pr` artifact
20
+ * committed unproven while `workspace` — produced by an `exec` step, which
21
+ * always submits an object receipt — carried its proof fine.
22
+ *
23
+ * THE FIX: normalize here, before signing and before sending, so the producer
24
+ * signs exactly the object the hub will store and the hub never takes its
25
+ * string branch. This function is a deliberate byte-for-byte mirror of
26
+ * `owenloop-service` `packages/hub-core/src/normalize-submit-value.ts`; the two
27
+ * must agree, because any divergence produces a signature over bytes the hub
28
+ * did not store, which the consumer then rejects.
29
+ *
30
+ * A string this function cannot normalize is passed through UNCHANGED to the
31
+ * hub, which rejects it with `artifact-normalization-failed` exactly as it does
32
+ * today. Refusing locally would invent a failure mode the protocol does not
33
+ * have and would hide the hub's own diagnostic text from the agent.
34
+ */
35
+ const FENCE_RE = /^\s*```(?:json)?\s*\n?([\s\S]*?)\n?```\s*$/;
36
+ /**
37
+ * The value to sign and send for `raw`.
38
+ *
39
+ * Non-string input is returned as-is: only the string fallback triggers the
40
+ * hub's normalization, so only a string can desynchronize signed bytes from
41
+ * stored bytes.
42
+ *
43
+ * A string is repaired the way the hub repairs it — strip a surrounding
44
+ * ```json fence, escape bare control characters inside string literals, parse —
45
+ * and the parsed plain object is returned. Anything that fails to parse, or
46
+ * parses to a non-object (a bare number, an array, `null`), is returned as the
47
+ * original string so the hub renders its own verdict on it.
48
+ */
49
+ export function normalizeSubmitValue(raw) {
50
+ if (typeof raw !== 'string')
51
+ return raw;
52
+ const fenceMatch = FENCE_RE.exec(raw);
53
+ const stripped = fenceMatch ? fenceMatch[1] : raw;
54
+ let parsed;
55
+ try {
56
+ parsed = JSON.parse(stripped);
57
+ }
58
+ catch {
59
+ try {
60
+ parsed = JSON.parse(escapeBareControlCharsInStrings(stripped));
61
+ }
62
+ catch {
63
+ return raw;
64
+ }
65
+ }
66
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
67
+ return raw;
68
+ return parsed;
69
+ }
70
+ /**
71
+ * Escape bare newlines/carriage-returns/tabs that appear INSIDE JSON string
72
+ * literals — the "worker emitted a multi-line string value" failure mode. A
73
+ * single pass tracking whether we are inside a string literal (respecting `\"`
74
+ * escapes) is enough; structural whitespace between tokens is left alone
75
+ * because `JSON.parse` already tolerates it raw.
76
+ */
77
+ function escapeBareControlCharsInStrings(text) {
78
+ let out = '';
79
+ let inString = false;
80
+ let escaped = false;
81
+ for (const ch of text) {
82
+ if (inString) {
83
+ if (escaped) {
84
+ out += ch;
85
+ escaped = false;
86
+ continue;
87
+ }
88
+ if (ch === '\\') {
89
+ out += ch;
90
+ escaped = true;
91
+ continue;
92
+ }
93
+ if (ch === '"') {
94
+ out += ch;
95
+ inString = false;
96
+ continue;
97
+ }
98
+ if (ch === '\n') {
99
+ out += '\\n';
100
+ continue;
101
+ }
102
+ if (ch === '\r') {
103
+ out += '\\r';
104
+ continue;
105
+ }
106
+ if (ch === '\t') {
107
+ out += '\\t';
108
+ continue;
109
+ }
110
+ out += ch;
111
+ continue;
112
+ }
113
+ if (ch === '"')
114
+ inString = true;
115
+ out += ch;
116
+ }
117
+ return out;
118
+ }
@@ -3,4 +3,4 @@
3
3
  * exit 0) and on a dispatch error (to stderr, exit 2). Keeping it in one place
4
4
  * means the help output and the error output never drift apart.
5
5
  */
6
- export declare const USAGE = "owenloop work \u2014 execution-side CLI companion to owenloop\n\nUsage:\n owenloop work hold --order <id> [options] hold an order with a heartbeating lease\n owenloop work exec <order-id> [options] run a command order in a self-leasing loop\n owenloop work agent-run <order-id> [options] host an agent order's step agent in a\n harness, in a self-leasing loop\n owenloop work prepare <workflow> [--origin <url>]\n fetch, cache & normalize step specs\n owenloop work lint <workflow-name | path> lint x.harness option bags in a def\n owenloop work sessions [--all] [--json] list this machine's recorded harness\n sessions and how to re-open them\n owenloop work release --session <id> [options] drain a session's held claims\n owenloop work settings print the resolved settings file\n owenloop work join <code> [--hub <origin>] [--as <account>]\n redeem a join code and store the Scoped\n Identity credential (one-time provisioning)\n\nOptions:\n -h, --help show this help and exit 0\n --version print the owenloop work version and exit 0\n\n root shift options (run as owenloop shift start <crew...> | --all):\n <crew...> serve only these crews (positional, space\n separated); or --all for every crew on the key\n --all serve every crew on the key\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account to read + hand\n to dispatched holds/execs (default 'default')\n --name <n> Shift name (default <hostname>/<cwd>)\n --cap <n> max in-flight exec children (default 3)\n --poll-interval <ms> wake poll cadence (default 5000)\n --once bootstrap wake + one sweep, then exit (demo/e2e)\n --max-agents <n> max in-flight agent-run children, separate from\n --cap (default 4; else settings.maxConcurrentAgents)\n --cache-dir/--state-dir <p> override the resolved dirs\n\n hold options:\n --order <workflow>/<run> the order to hold (or --order <run> --workflow)\n --workflow <wf> required when --order is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account (default\n 'default'; the shift stamps this into born-bound\n holds)\n --session <id> session-holder tag (else env OWENLOOP_SESSION;\n else an anon:<hostname>:<pid> fallback \u2014 a\n holder is always sent)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --ignore-stdin don't final-breath on stdin EOF (detached use)\n --mcp run as a stdio-MCP work-holder: tools get_order /\n submit, lease kept warm underneath (mutually\n exclusive with --ignore-stdin \u2014 stdin is the\n transport)\n\n exec options (usually spawned by shift, not run by hand):\n <workflow>/<run> the command order to run (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n\n agent-run options (spawned by the shift, not run by hand):\n <workflow>/<run> the agent order to host (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --harness <id> which registered harness hosts the step agent\n (else env OWENLOOP_HARNESS, else the step def's\n 'harness' field, else the first registered one)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --submit-grace <ms> after the turn ends, how long to keep asking the\n hub whether the agent's submit landed (default\n 15000). Task completion comes from the HUB, never\n from the harness stream.\n --confirm-interval <ms> poll cadence inside that grace (default 1000)\n\n release options:\n --session <id> session whose claims to drain (else env\n OWENLOOP_SESSION). Agent-held claims re-offer;\n exec-held claims are drain-exempt (B3).\n --origin <url> hub origin (else settings.hubOrigin)\n\n settings (no options in v1):\n prints the resolved settings file path, whether it exists, each known\n knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,\n maxConcurrentAgents, workRoot, workRepo) with its value + provenance,\n and any unrecognized keys.\n settings.dispatchCap/stateDir are the lowest-precedence\n fallbacks for shift's --cap/--state-dir. NO secrets ever\n live in settings \u2014 credentials stay in owenloop's own store.\n\n sessions options:\n --all include 'dead' sessions (hidden by default \u2014\n a dead session can no longer be resumed)\n --json print the raw newest-per-step records, tokens\n included, instead of the table\n --cache-dir <p> override the resolved cache dir\n\n join options:\n --hub <origin> hub to redeem against (else settings.hubOrigin;\n one of the two is REQUIRED \u2014 the code never\n chooses the hub)\n --as <account> credential account to store under (default:\n the Scoped Identity name the hub returns)\n\n shift/hold/exec/prepare/release env:\n credentials come from owenloop's store \u2014 each role reads the\n agent:<account> slot for its origin (never the human slot); a\n missing slot refuses with a runnable 'owenloop login' command.\n OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release\n (default 'default'; shift uses --as, and\n stamps it onto dispatched holds/execs)\n OWENLOOP_TOKEN dev-only bearer override \u2014 when set, used\n verbatim and the store + account are\n bypassed (NOT the primary path)\n OWENLOOP_CACHE_DIR cache root\n OWENLOOP_STATE_DIR shift in-flight state dir\n OWENLOOP_SESSION hold session-holder tag / release drain target\n OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for\n hold/exec/agent-run's --shift (advisory\n only, never for auth/routing/dispatch)\n OWENLOOP_HARNESS agent-run harness id; below --harness, above\n the step def's 'harness' field\n OWENLOOP_WORK_ROOT root for per-RUN agent work dirs\n (<workRoot>/<workflow>/<run>); above\n settings.workRoot, default <cacheDir>/work.\n A hub-supplied OrderPacket.workdir still\n wins, and is never reaped.\n OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from\n as worktrees instead of plain dirs; above\n settings.workRepo, default off\n\n Credentials / accounts:\n owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY\n over owenloop's credential store \u2014 they never write credentials. Each\n role reads the agent:<account> slot for its origin (never the human\n slot); the account defaults to 'default'. 'owenloop work join' is the one\n deliberate provisioning-time writer: it stores the Scoped Identity token a hub\n redeem returns via owenloop's public storeCredential, once, at join time\n \u2014 not a runtime write.\n store / connect an account (run owenloop; owenloop work never writes it):\n owenloop login --hub <origin> --as agent:<account>\n (use --as agent for the default account)\n or provision a fresh box from a hub-issued join code:\n owenloop work join <code> --hub <origin>\n select an account at run time:\n --as <account> on shift / hold\n OWENLOOP_ACCOUNT on exec / prepare / release\n (shift resolves once and threads both channels)\n owenloop work does NOT list stored accounts \u2014 enumerating an origin's accounts\n is an owenloop-side capability; check owenloop for which slots are stored.\n\nExit codes:\n 0 success / help / version / lint clean or warnings-only\n 1 runtime failure (fetch/hub error, cache write) / lint found an error\n 2 usage error (unknown or missing role, missing required arg)\n 3 role not implemented yet (skeleton stub \u2014 lands in a later delivery)\n";
6
+ export declare const USAGE = "owenloop work \u2014 execution-side CLI companion to owenloop\n\nUsage:\n owenloop work hold --order <id> [options] hold an order with a heartbeating lease\n owenloop work exec <order-id> [options] run a command order in a self-leasing loop\n owenloop work agent-run <order-id> [options] host an agent order's step agent in a\n harness, in a self-leasing loop\n owenloop work prepare <workflow> [--origin <url>]\n fetch, cache & normalize step specs\n owenloop work lint <workflow-name | path> lint x.harness option bags in a def\n owenloop work sessions [--all] [--json] list this machine's recorded harness\n sessions and how to re-open them\n owenloop work release --session <id> [options] drain a session's held claims\n owenloop work settings print the resolved settings file\n owenloop work join <code> [--hub <origin>] [--as <account>]\n redeem a join code and store the Scoped\n Identity credential (one-time provisioning)\n\nOptions:\n -h, --help show this help and exit 0\n --version print the owenloop work version and exit 0\n\n root shift options (run as owenloop shift start <crew...> | --all):\n <crew...> serve only these crews (positional, space\n separated); or --all for every crew on the key\n --all serve every crew on the key\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account to read + hand\n to dispatched holds/execs (default 'default')\n --name <n> Shift name (default <hostname>/<cwd>)\n --cap <n> max in-flight exec children (default 3)\n --poll-interval <ms> wake poll cadence (default 5000)\n --once bootstrap wake + one sweep, then exit (demo/e2e)\n --max-agents <n> max in-flight agent-run children, separate from\n --cap (default 4; else settings.maxConcurrentAgents)\n --cache-dir/--state-dir <p> override the resolved dirs\n\n hold options:\n --order <workflow>/<run> the order to hold (or --order <run> --workflow)\n --workflow <wf> required when --order is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account (default\n 'default'; the shift stamps this into born-bound\n holds)\n --session <id> session-holder tag (else env OWENLOOP_SESSION;\n else an anon:<hostname>:<pid> fallback \u2014 a\n holder is always sent)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --ignore-stdin don't final-breath on stdin EOF (detached use)\n --never-release another process holds the claim; stop without\n releasing it (agent-run spawns its --mcp child\n this way \u2014 see hold.ts HOLDER OF RECORD)\n --mcp run as a stdio-MCP work-holder: tools get_order /\n submit, lease kept warm underneath (mutually\n exclusive with --ignore-stdin \u2014 stdin is the\n transport)\n\n exec options (usually spawned by shift, not run by hand):\n <workflow>/<run> the command order to run (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n\n agent-run options (spawned by the shift, not run by hand):\n <workflow>/<run> the agent order to host (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --harness <id> which registered harness hosts the step agent\n (else env OWENLOOP_HARNESS, else the step def's\n 'harness' field, else the first registered one)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --submit-grace <ms> after the turn ends, how long to keep asking the\n hub whether the agent's submit landed (default\n 15000). Task completion comes from the HUB, never\n from the harness stream.\n --confirm-interval <ms> poll cadence inside that grace (default 1000)\n\n release options:\n --session <id> session whose claims to drain (else env\n OWENLOOP_SESSION). Agent-held claims re-offer;\n exec-held claims are drain-exempt (B3).\n --origin <url> hub origin (else settings.hubOrigin)\n\n settings (no options in v1):\n prints the resolved settings file path, whether it exists, each known\n knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,\n maxConcurrentAgents, workRoot, workRepo) with its value + provenance,\n and any unrecognized keys.\n settings.dispatchCap/stateDir are the lowest-precedence\n fallbacks for shift's --cap/--state-dir. NO secrets ever\n live in settings \u2014 credentials stay in owenloop's own store.\n\n sessions options:\n --all include 'dead' sessions (hidden by default \u2014\n a dead session can no longer be resumed)\n --json print the raw newest-per-step records, tokens\n included, instead of the table\n --cache-dir <p> override the resolved cache dir\n\n join options:\n --hub <origin> hub to redeem against (else settings.hubOrigin;\n one of the two is REQUIRED \u2014 the code never\n chooses the hub)\n --as <account> credential account to store under (default:\n the Scoped Identity name the hub returns)\n\n shift/hold/exec/prepare/release env:\n credentials come from owenloop's store \u2014 each role reads the\n agent:<account> slot for its origin (never the human slot); a\n missing slot refuses with a runnable 'owenloop login' command.\n OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release\n (default 'default'; shift uses --as, and\n stamps it onto dispatched holds/execs)\n OWENLOOP_TOKEN dev-only bearer override \u2014 when set, used\n verbatim and the store + account are\n bypassed (NOT the primary path)\n OWENLOOP_CACHE_DIR cache root\n OWENLOOP_STATE_DIR shift in-flight state dir\n OWENLOOP_SHIFT_LOG_DIR dir for the shift's shift.log and each\n worker's <run>.log; below --log-dir, above\n settings.shiftLogDir, default the state dir\n OWENLOOP_SHIFT_LOG_MAX_AGE_MS\n how long a worker's <run>.log is kept, in ms;\n below --log-max-age, above\n settings.shiftLogMaxAgeMs, default 14 days.\n Worker logs only \u2014 shift.log is never reaped\n OWENLOOP_SESSION hold session-holder tag / release drain target\n OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for\n hold/exec/agent-run's --shift (advisory\n only, never for auth/routing/dispatch)\n OWENLOOP_HARNESS agent-run harness id; below --harness, above\n the step def's 'harness' field\n OWENLOOP_WORK_ROOT root for per-RUN agent work dirs\n (<workRoot>/<workflow>/<run>); above\n settings.workRoot, default <cacheDir>/work.\n A hub-supplied OrderPacket.workdir still\n wins, and is never reaped.\n OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from\n as worktrees instead of plain dirs; above\n settings.workRepo, default off\n\n Credentials / accounts:\n owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY\n over owenloop's credential store \u2014 they never write credentials. Each\n role reads the agent:<account> slot for its origin (never the human\n slot); the account defaults to 'default'. 'owenloop work join' is the one\n deliberate provisioning-time writer: it stores the Scoped Identity token a hub\n redeem returns via owenloop's public storeCredential, once, at join time\n \u2014 not a runtime write.\n store / connect an account (run owenloop; owenloop work never writes it):\n owenloop login --hub <origin> --as agent:<account>\n (use --as agent for the default account)\n or provision a fresh box from a hub-issued join code:\n owenloop work join <code> --hub <origin>\n select an account at run time:\n --as <account> on shift / hold\n OWENLOOP_ACCOUNT on exec / prepare / release\n (shift resolves once and threads both channels)\n owenloop work does NOT list stored accounts \u2014 enumerating an origin's accounts\n is an owenloop-side capability; check owenloop for which slots are stored.\n\nExit codes:\n 0 success / help / version / lint clean or warnings-only\n 1 runtime failure (fetch/hub error, cache write) / lint found an error\n 2 usage error (unknown or missing role, missing required arg)\n 3 role not implemented yet (skeleton stub \u2014 lands in a later delivery)\n";
@@ -56,6 +56,9 @@ Options:
56
56
  --jump-tolerance <ms> wall-gap slack before a tick is treated as a
57
57
  clock jump / laptop sleep (default 30000)
58
58
  --ignore-stdin don't final-breath on stdin EOF (detached use)
59
+ --never-release another process holds the claim; stop without
60
+ releasing it (agent-run spawns its --mcp child
61
+ this way — see hold.ts HOLDER OF RECORD)
59
62
  --mcp run as a stdio-MCP work-holder: tools get_order /
60
63
  submit, lease kept warm underneath (mutually
61
64
  exclusive with --ignore-stdin — stdin is the
@@ -132,6 +135,14 @@ Options:
132
135
  bypassed (NOT the primary path)
133
136
  OWENLOOP_CACHE_DIR cache root
134
137
  OWENLOOP_STATE_DIR shift in-flight state dir
138
+ OWENLOOP_SHIFT_LOG_DIR dir for the shift's shift.log and each
139
+ worker's <run>.log; below --log-dir, above
140
+ settings.shiftLogDir, default the state dir
141
+ OWENLOOP_SHIFT_LOG_MAX_AGE_MS
142
+ how long a worker's <run>.log is kept, in ms;
143
+ below --log-max-age, above
144
+ settings.shiftLogMaxAgeMs, default 14 days.
145
+ Worker logs only — shift.log is never reaped
135
146
  OWENLOOP_SESSION hold session-holder tag / release drain target
136
147
  OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for
137
148
  hold/exec/agent-run's --shift (advisory
@@ -0,0 +1,93 @@
1
+ /**
2
+ * Routing capabilities: composition at offer time, and the claim-side match.
3
+ *
4
+ * Three vocabularies meet here and must not be confused:
5
+ *
6
+ * - **Authored capability** — what a def writes on a step (`wise`). Never
7
+ * contains the separator; the parser rejects one that does.
8
+ * - **Modifier** — the ONE plain name a run carries (`deep`). Optional. The
9
+ * engine attaches no meaning, no order and no arithmetic to it.
10
+ * - **Compound capability** — `<authored>:<modifier>` (`wise:deep`), composed
11
+ * by the engine when it builds an order. Only the engine composes it.
12
+ *
13
+ * Nothing here reads the store, the def or the clock. Composition is a pure
14
+ * function of (authored capabilities, modifier); matching is a pure function of
15
+ * (offered capabilities, caller capabilities, per-capability match mode).
16
+ */
17
+ /**
18
+ * The character the engine reserves as the capability/modifier separator.
19
+ *
20
+ * A def author never writes it. `wise:deep` is a value the ENGINE composes at
21
+ * offer time from an authored capability plus the run's modifier, and a crew
22
+ * binding is matched against that composed form. If an author could also write
23
+ * a literal `wise:deep` capability, two different things — an authored name and
24
+ * a composed compound — would be indistinguishable downstream, and the name
25
+ * part of a compound would stop being recoverable by splitting on the first
26
+ * colon. So the position is reserved, and reserving it is enforced in the def
27
+ * parser (`assertAuthoredCapability`).
28
+ */
29
+ export declare const MODIFIER_SEPARATOR = ":";
30
+ /**
31
+ * How a claim is matched against one offered capability.
32
+ *
33
+ * - `'exact'` — the caller must present the offered string literally. Stamped
34
+ * by the hub when at least one crew is bound to the exact compound
35
+ * (Scenario A): the binding exists, so the order belongs to the crews that
36
+ * opted into serving that slice, and a name-part-only crew must not take it.
37
+ * - `'name'` — the caller matches on the name part alone, modifier ignored
38
+ * both sides. Stamped when no binding for the compound exists (Scenario B),
39
+ * and re-stamped when a wait policy degrades an Scenario-A order.
40
+ *
41
+ * The mode is a HUB decision — it depends on `capability_routes`, which the
42
+ * pure engine cannot see. The engine only enforces the mode it is handed, and
43
+ * defaults to `'name'` for any capability the caller says nothing about.
44
+ */
45
+ export type MatchMode = 'exact' | 'name';
46
+ /** The default when a caller supplies no mode for an offered capability. */
47
+ export declare const DEFAULT_MATCH_MODE: MatchMode;
48
+ /**
49
+ * The name part of a capability: everything before the FIRST separator.
50
+ *
51
+ * Split on the first, not the last: an authored name can never contain the
52
+ * separator, so the first occurrence is always the one the engine composed at.
53
+ * A bare capability is its own name part.
54
+ */
55
+ export declare function capabilityName(capability: string): string;
56
+ /**
57
+ * Compose a step's authored capabilities against a run's modifier.
58
+ *
59
+ * No modifier (an unmodified run) returns the authored list unchanged — the
60
+ * order is offered on bare capabilities, exactly as before modifiers existed.
61
+ * An empty authored list stays empty: a capability-silent step has nothing to
62
+ * compose onto, and inventing a lone `:deep` would be meaningless.
63
+ */
64
+ export declare function composeCapabilities(authored: readonly string[] | undefined, modifier: string | undefined): string[];
65
+ /**
66
+ * The claim-side match: may a caller presenting `caller` claim a step offered
67
+ * on `offered`?
68
+ *
69
+ * `caller` distinguishes two states that must not be collapsed:
70
+ *
71
+ * - `undefined` — **no filter presented**. The caller is not claiming as a
72
+ * crew at all (a local operator running `owenloop tick`, a test driver).
73
+ * Everything matches, exactly as before capabilities existed.
74
+ * - `[]` — **a caller that serves nothing**. A crew presenting an empty
75
+ * capability list. This matches only capability-silent steps (case 2).
76
+ *
77
+ * Four cases, kept explicit because they are genuinely different rules:
78
+ *
79
+ * 1. **No filter presented** — always matches. See above.
80
+ * 2. **Capability-silent step** (`offered` empty) — claimable by anyone,
81
+ * including a caller presenting an empty list. Unchanged behavior: a def
82
+ * that authors no capabilities expresses no routing preference.
83
+ * 3. **Empty caller list, capabilities offered** — NO match. This is the A2
84
+ * caller-side change: today an empty list bypasses the filter and can
85
+ * claim every step, including compounds its shift cannot resolve, costing
86
+ * a claim/release cycle per order and able to hot-loop. Such a caller now
87
+ * matches only case 2.
88
+ * 4. **Both non-empty** — match when SOME offered capability is satisfied by
89
+ * SOME caller capability under that offered capability's own mode. The
90
+ * mode is looked up per offered capability, so an order carrying two
91
+ * compounds with different bindings is judged correctly on each.
92
+ */
93
+ export declare function claimMatches(offered: readonly string[], caller: readonly string[] | undefined, modes?: Readonly<Record<string, MatchMode>>): boolean;
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Routing capabilities: composition at offer time, and the claim-side match.
3
+ *
4
+ * Three vocabularies meet here and must not be confused:
5
+ *
6
+ * - **Authored capability** — what a def writes on a step (`wise`). Never
7
+ * contains the separator; the parser rejects one that does.
8
+ * - **Modifier** — the ONE plain name a run carries (`deep`). Optional. The
9
+ * engine attaches no meaning, no order and no arithmetic to it.
10
+ * - **Compound capability** — `<authored>:<modifier>` (`wise:deep`), composed
11
+ * by the engine when it builds an order. Only the engine composes it.
12
+ *
13
+ * Nothing here reads the store, the def or the clock. Composition is a pure
14
+ * function of (authored capabilities, modifier); matching is a pure function of
15
+ * (offered capabilities, caller capabilities, per-capability match mode).
16
+ */
17
+ /**
18
+ * The character the engine reserves as the capability/modifier separator.
19
+ *
20
+ * A def author never writes it. `wise:deep` is a value the ENGINE composes at
21
+ * offer time from an authored capability plus the run's modifier, and a crew
22
+ * binding is matched against that composed form. If an author could also write
23
+ * a literal `wise:deep` capability, two different things — an authored name and
24
+ * a composed compound — would be indistinguishable downstream, and the name
25
+ * part of a compound would stop being recoverable by splitting on the first
26
+ * colon. So the position is reserved, and reserving it is enforced in the def
27
+ * parser (`assertAuthoredCapability`).
28
+ */
29
+ export const MODIFIER_SEPARATOR = ':';
30
+ /** The default when a caller supplies no mode for an offered capability. */
31
+ export const DEFAULT_MATCH_MODE = 'name';
32
+ /**
33
+ * The name part of a capability: everything before the FIRST separator.
34
+ *
35
+ * Split on the first, not the last: an authored name can never contain the
36
+ * separator, so the first occurrence is always the one the engine composed at.
37
+ * A bare capability is its own name part.
38
+ */
39
+ export function capabilityName(capability) {
40
+ const i = capability.indexOf(MODIFIER_SEPARATOR);
41
+ return i === -1 ? capability : capability.slice(0, i);
42
+ }
43
+ /**
44
+ * Compose a step's authored capabilities against a run's modifier.
45
+ *
46
+ * No modifier (an unmodified run) returns the authored list unchanged — the
47
+ * order is offered on bare capabilities, exactly as before modifiers existed.
48
+ * An empty authored list stays empty: a capability-silent step has nothing to
49
+ * compose onto, and inventing a lone `:deep` would be meaningless.
50
+ */
51
+ export function composeCapabilities(authored, modifier) {
52
+ if (authored === undefined || authored.length === 0)
53
+ return [];
54
+ if (modifier === undefined)
55
+ return [...authored];
56
+ return authored.map((c) => `${c}${MODIFIER_SEPARATOR}${modifier}`);
57
+ }
58
+ /** True when one caller capability satisfies one offered capability under `mode`. */
59
+ function matchesOne(offered, caller, mode) {
60
+ return mode === 'exact' ? caller === offered : capabilityName(caller) === capabilityName(offered);
61
+ }
62
+ /**
63
+ * The claim-side match: may a caller presenting `caller` claim a step offered
64
+ * on `offered`?
65
+ *
66
+ * `caller` distinguishes two states that must not be collapsed:
67
+ *
68
+ * - `undefined` — **no filter presented**. The caller is not claiming as a
69
+ * crew at all (a local operator running `owenloop tick`, a test driver).
70
+ * Everything matches, exactly as before capabilities existed.
71
+ * - `[]` — **a caller that serves nothing**. A crew presenting an empty
72
+ * capability list. This matches only capability-silent steps (case 2).
73
+ *
74
+ * Four cases, kept explicit because they are genuinely different rules:
75
+ *
76
+ * 1. **No filter presented** — always matches. See above.
77
+ * 2. **Capability-silent step** (`offered` empty) — claimable by anyone,
78
+ * including a caller presenting an empty list. Unchanged behavior: a def
79
+ * that authors no capabilities expresses no routing preference.
80
+ * 3. **Empty caller list, capabilities offered** — NO match. This is the A2
81
+ * caller-side change: today an empty list bypasses the filter and can
82
+ * claim every step, including compounds its shift cannot resolve, costing
83
+ * a claim/release cycle per order and able to hot-loop. Such a caller now
84
+ * matches only case 2.
85
+ * 4. **Both non-empty** — match when SOME offered capability is satisfied by
86
+ * SOME caller capability under that offered capability's own mode. The
87
+ * mode is looked up per offered capability, so an order carrying two
88
+ * compounds with different bindings is judged correctly on each.
89
+ */
90
+ export function claimMatches(offered, caller, modes = {}) {
91
+ if (caller === undefined)
92
+ return true;
93
+ if (offered.length === 0)
94
+ return true;
95
+ if (caller.length === 0)
96
+ return false;
97
+ return offered.some((o) => {
98
+ const mode = modes[o] ?? DEFAULT_MATCH_MODE;
99
+ return caller.some((c) => matchesOne(o, c, mode));
100
+ });
101
+ }
package/dist/src/cli.js CHANGED
@@ -1562,8 +1562,11 @@ function dispatch(command, io, args) {
1562
1562
  tickOpts.now = now;
1563
1563
  if (flag(args, 'shallow'))
1564
1564
  tickOpts.deep = false;
1565
- // A2: repeatable --capability narrows the claim to steps whose capabilities
1566
- // intersect the caller's; absent = claim everything (today's behavior).
1565
+ // A2: repeatable --capability narrows the claim to steps the caller's
1566
+ // capabilities match. Absent = no filter presented, so a local operator
1567
+ // still claims everything — NOT the same as presenting an empty list,
1568
+ // which is a crew that serves nothing and matches only capability-silent
1569
+ // steps. Only set the key when the operator actually named capabilities.
1567
1570
  const capabilities = all(args, 'capability');
1568
1571
  if (capabilities.length > 0)
1569
1572
  tickOpts.capabilities = capabilities;
@@ -4266,7 +4269,7 @@ async function dispatchAgent(io, args) {
4266
4269
  * bind MANY crews. `capability bind` on an already-bound capability ADDS a crew; it never
4267
4270
  * displaces one already bound. Re-adding the same pair is a normal 200 no-op, so
4268
4271
  * there is no "already bound" rejection to handle and no client-side pre-check —
4269
- * the response says which happened via `alreadyRouted`, and `routedCrewCount`
4272
+ * the response says which happened via `alreadyBound`, and `boundCrewCount`
4270
4273
  * reports how many LIVE crews the capability binds afterwards.
4271
4274
  *
4272
4275
  * **`capability unbind` removes ONE pair**, which is why `<crew>` is required. Removing
@@ -4406,18 +4409,20 @@ async function dispatchCapability(io, args) {
4406
4409
  }
4407
4410
  // The server-echoed capability/crew, not argv: if the hub normalized either,
4408
4411
  // stdout tells the truth about what the hub stored (same precedent as
4409
- // `agent new` printing the server-resolved crews). `alreadyRouted` and
4410
- // `routedCrewCount` carry the HUB's own field names verbatim, so an operator
4412
+ // `agent new` printing the server-resolved crews). `alreadyBound` and
4413
+ // `boundCrewCount` carry the HUB's own field names verbatim, so an operator
4411
4414
  // correlating stdout against the hub's audit log never has to translate.
4415
+ // (They were `alreadyRouted`/`routedCrewCount` here, which the hub never
4416
+ // sends — the claim in this comment was the intent, not the behavior.)
4412
4417
  // `createdBy`/`createdAt` are validated but not printed — `capability list` is
4413
4418
  // where a row's provenance belongs.
4414
4419
  print(io, {
4415
4420
  ok: true,
4416
4421
  hub: origin,
4417
- capability: added.route.capability,
4418
- crew: added.route.crewName,
4419
- alreadyRouted: added.alreadyRouted,
4420
- routedCrewCount: added.routedCrewCount,
4422
+ capability: added.binding.capability,
4423
+ crew: added.binding.crewName,
4424
+ alreadyBound: added.alreadyBound,
4425
+ boundCrewCount: added.boundCrewCount,
4421
4426
  });
4422
4427
  // No stderr line on `bind`: an add never displaces a crew and never parks a
4423
4428
  // capability, so there is no consequence to warn about.
@@ -287,6 +287,9 @@ export declare const ORDER_FIELDS: {
287
287
  readonly owes: "required";
288
288
  readonly consumesProof: "optional";
289
289
  readonly cause: "optional";
290
+ readonly capabilities: "optional";
291
+ readonly modifier: "optional";
292
+ readonly escalated: "optional";
290
293
  };
291
294
  /** Indexed access pins the already-emitted nested Order shape without cloning it. */
292
295
  export declare const ORDER_OWED_FIELDS: {
@@ -128,6 +128,17 @@ export const ORDER_FIELDS = {
128
128
  owes: 'required',
129
129
  consumesProof: 'optional',
130
130
  cause: 'optional',
131
+ // Routing snapshot of the offer this order was claimed from. `capabilities`
132
+ // is the COMPOSED list (authored capability + `:<modifier>` where a modifier
133
+ // applied), `modifier` the value that composed it. Both optional: an
134
+ // unmodified run on a capability-silent step carries neither, so every order
135
+ // emitted before this field existed still validates unchanged.
136
+ capabilities: 'optional',
137
+ modifier: 'optional',
138
+ // Set only when `modifier` is the step's escalation target rather than the
139
+ // run's. Covered by the signature like every other routing field: a claim
140
+ // made on a recovery re-offer must not be replayable as an ordinary one.
141
+ escalated: 'optional',
131
142
  };
132
143
  /** Indexed access pins the already-emitted nested Order shape without cloning it. */
133
144
  export const ORDER_OWED_FIELDS = {