owenloop 0.5.13 → 0.5.15

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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,26 @@ All notable changes to this project are documented here. The format is based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.5.15](https://github.com/typicalday/owenloop/compare/v0.5.14...v0.5.15) (2026-08-21)
8
+
9
+
10
+ ### Bug Fixes
11
+
12
+ * **setup:** resolve the MCP plugin launch through the PATH binary ([#271](https://github.com/typicalday/owenloop/issues/271)) ([ce25164](https://github.com/typicalday/owenloop/commit/ce25164f0397a1c70e62feeea11715fb6fe59823))
13
+ * **work:** answer an approval with a human credential, not an agent one ([#273](https://github.com/typicalday/owenloop/issues/273)) ([6cd5330](https://github.com/typicalday/owenloop/commit/6cd53308c8040f0e0fc4b7303e555104af0d5e57))
14
+
15
+
16
+ ### Performance Improvements
17
+
18
+ * **work:** skip the targeted whats_next for instances the inbox shows unservable ([#277](https://github.com/typicalday/owenloop/issues/277)) ([4b18fe6](https://github.com/typicalday/owenloop/commit/4b18fe6a2b6e272e7d62b797ad6a8a6c452b0046))
19
+
20
+ ## [0.5.14](https://github.com/typicalday/owenloop/compare/v0.5.13...v0.5.14) (2026-08-21)
21
+
22
+
23
+ ### Bug Fixes
24
+
25
+ * **engine:** let a sealed collection be consumed without deadlocking a multi-step def ([#269](https://github.com/typicalday/owenloop/issues/269)) ([e3be862](https://github.com/typicalday/owenloop/commit/e3be8627a227a9e5fc134306e935ec816eafcb00))
26
+
7
27
  ## [0.5.13](https://github.com/typicalday/owenloop/compare/v0.5.12...v0.5.13) (2026-08-21)
8
28
 
9
29
 
package/README.md CHANGED
@@ -226,7 +226,9 @@ A step can emit any number of elements at runtime; a `map` step runs once per
226
226
  element, and a `reduce` step runs once after they're all in (or, with a
227
227
  suffixed reduce, once every element's own per-element output is in). See
228
228
  [`docs/authoring.md`](docs/authoring.md#consume--produce-grammar) and
229
- [`research.yaml`](examples/workflows/research.yaml).
229
+ [`research.yaml`](examples/workflows/research.yaml). A rejected collection
230
+ seal can be re-emitted and resealed; rejected members are recovered by an
231
+ authorized retract, as described in the authoring guide.
230
232
 
231
233
  ### Composition — `include:` and `calls:`
232
234
 
@@ -534,9 +536,13 @@ setup only prints the `OWENLOOP_ACCOUNT=<name>` instruction. Setup probes and,
534
536
  when needed, converges the bundled `owenloop` plugins for Claude Code and Codex.
535
537
  Plugin convergence is non-fatal; a missing harness or failed plugin command does
536
538
  not fail setup. A second run with the expected plugin version already installed
537
- performs no plugin writes. `owenloop doctor` is the read-only counterpart: it
538
- checks both harness plugin states, reports version skew, and prints a `✓`/`✗`
539
- line with the remedy. See
539
+ performs no plugin writes when its effective MCP launch is verified safe.
540
+ `owenloop doctor` is the read-only counterpart: it checks both harness plugin
541
+ states, including the effective `owenloop mcp` command and arguments, Codex's
542
+ `PATH` pass-through, and PATH availability. It reports same-version absolute or
543
+ worktree launch declarations as drift, but does not treat a plugin's absolute
544
+ marketplace or cache location as a launch verdict. A known unsafe declaration is
545
+ repaired by the existing non-fatal `owenloop setup` convergence flow. See
540
546
  [`setup`](docs/cli.md#setup--onboard-a-machine) and
541
547
  [`doctor`](docs/cli.md#doctor--check-a-machines-install) in `docs/cli.md`.
542
548
 
@@ -1,14 +1,16 @@
1
1
  /**
2
- * Credential read seam. owenloop reads hub credentials through owenloop's
3
- * store ONLY — it never writes, prints, or stores credentials itself, and it
4
- * never reads the keychain or `credentials.json` formats directly.
2
+ * Credential read seam for agent runtime roles. owenloop reads hub credentials
3
+ * through owenloop's store ONLY — it never prints credentials or reads the
4
+ * keychain or `credentials.json` formats directly.
5
5
  *
6
6
  * The live wiring is against owenloop 0.4.0's `readStoredCredential`
7
- * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). owenloop reads
8
- * ONLY the `agent:<account>` slots — never the `human` slot — so a human-only
9
- * origin reads as absent (`null`), which the roles surface as a clean refuse.
10
- * `Credential` is re-exported from owenloop below so this seam and the store
11
- * speak the exact same union.
7
+ * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). That reader
8
+ * addresses ONLY `agent:<account>` slots — never `human` — so a human-only
9
+ * origin reads as absent (`null`) on agent paths. Human decision resolution
10
+ * uses the root `ensureFreshOAuth` surface after its explicit `human` read;
11
+ * an expiring OAuth credential can therefore persist its locked rotation.
12
+ * `Credential` is re-exported below so this seam and the store speak the same
13
+ * union.
12
14
  */
13
15
  /** The root package's stored-credential union (agent / oauth / oauth-pasted). */
14
16
  export type { Credential } from '../../../../src/hub.ts';
@@ -1,14 +1,16 @@
1
1
  /**
2
- * Credential read seam. owenloop reads hub credentials through owenloop's
3
- * store ONLY — it never writes, prints, or stores credentials itself, and it
4
- * never reads the keychain or `credentials.json` formats directly.
2
+ * Credential read seam for agent runtime roles. owenloop reads hub credentials
3
+ * through owenloop's store ONLY — it never prints credentials or reads the
4
+ * keychain or `credentials.json` formats directly.
5
5
  *
6
6
  * The live wiring is against owenloop 0.4.0's `readStoredCredential`
7
- * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). owenloop reads
8
- * ONLY the `agent:<account>` slots — never the `human` slot — so a human-only
9
- * origin reads as absent (`null`), which the roles surface as a clean refuse.
10
- * `Credential` is re-exported from owenloop below so this seam and the store
11
- * speak the exact same union.
7
+ * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). That reader
8
+ * addresses ONLY `agent:<account>` slots — never `human` — so a human-only
9
+ * origin reads as absent (`null`) on agent paths. Human decision resolution
10
+ * uses the root `ensureFreshOAuth` surface after its explicit `human` read;
11
+ * an expiring OAuth credential can therefore persist its locked rotation.
12
+ * `Credential` is re-exported below so this seam and the store speak the same
13
+ * union.
12
14
  */
13
15
  /**
14
16
  * In-memory reader seeded from a `Record<origin, Credential>`. Lives in `src`
@@ -1,3 +1,4 @@
1
+ import type { CredentialIO } from '../../../../src/index.ts';
1
2
  export type BearerResult = {
2
3
  ok: true;
3
4
  token: string;
@@ -6,14 +7,22 @@ export type BearerResult = {
6
7
  code: number;
7
8
  message: string;
8
9
  };
10
+ export type ResolveBearerArgs = {
11
+ origin: string;
12
+ account: string;
13
+ env: Record<string, string | undefined>;
14
+ principal?: 'agent';
15
+ } | {
16
+ origin: string;
17
+ env: Record<string, string | undefined>;
18
+ principal: 'human';
19
+ account?: never;
20
+ credentialIo?: Omit<CredentialIO, 'env'>;
21
+ };
9
22
  /**
10
23
  * The owenloop `--as <slot>` argument for an account: `agent` for the default
11
24
  * account, `agent:<account>` otherwise. Grounded from owenloop's `--as`
12
25
  * semantics (`human` | `agent` | `agent:<account>`).
13
26
  */
14
27
  export declare function slotArg(account: string): string;
15
- export declare function resolveBearer(args: {
16
- origin: string;
17
- account: string;
18
- env: Record<string, string | undefined>;
19
- }): Promise<BearerResult>;
28
+ export declare function resolveBearer(args: ResolveBearerArgs): Promise<BearerResult>;
@@ -1,7 +1,9 @@
1
1
  /**
2
- * The ONE place the bearer-token resolution / refuse / dev-override logic lives,
3
- * so all five roles share identical precedence instead of re-deriving it:
2
+ * The ONE place the bearer-token resolution / refusal logic lives. Agent
3
+ * runtime roles share one precedence here; human-only decisions use their own
4
+ * explicit credential boundary rather than re-deriving either path.
4
5
  *
6
+ * Agent mode:
5
7
  * 1. `OWENLOOP_TOKEN` (trimmed, non-empty) — an EXPLICIT dev-only override.
6
8
  * When set, it is used verbatim and the store + account are skipped.
7
9
  * 2. Otherwise read the `agent:<account>` slot from owenloop's store:
@@ -11,12 +13,21 @@
11
13
  * - a THROW → error (code 1): a genuine read failure (bad origin /
12
14
  * external-command failure), surfaced with its message.
13
15
  *
16
+ * Human mode reads ONLY the `human` slot. It deliberately does not honor the
17
+ * principal-ambiguous dev override or an agent account: callers use it for
18
+ * human-only hub verbs and must either supply a human credential or refuse
19
+ * locally with an actionable login command. A stored human OAuth credential may
20
+ * refresh and persist its rotation through the root package's shared lock; this
21
+ * resolver never mints, logs, or otherwise exposes credentials.
22
+ *
14
23
  * The refuse (code 2) is a refuse-to-start precondition, mirroring the old
15
- * "no token" exit code, so existing exit-code assertions stay valid — only the
16
- * message text changes. owenloop stays read-only w.r.t. credentials.
24
+ * "no token" exit code, so existing exit-code assertions stay valid. Agent
25
+ * mode is read-only; human decision mode may persist a rotation of a credential
26
+ * the user already stored.
17
27
  */
18
28
  import { OwenloopCredentialReader } from "./owenloop.js";
19
29
  import { credentialToToken } from "./reader.js";
30
+ import { ensureFreshOAuth, readStoredCredential } from "../../../../src/index.js";
20
31
  /**
21
32
  * The owenloop `--as <slot>` argument for an account: `agent` for the default
22
33
  * account, `agent:<account>` otherwise. Grounded from owenloop's `--as`
@@ -26,7 +37,42 @@ export function slotArg(account) {
26
37
  return account === 'default' ? 'agent' : `agent:${account}`;
27
38
  }
28
39
  export async function resolveBearer(args) {
29
- const { origin, account, env } = args;
40
+ const { origin, env } = args;
41
+ if (args.principal === 'human') {
42
+ const io = { env, ...args.credentialIo };
43
+ let cred;
44
+ try {
45
+ cred = readStoredCredential(origin, { principal: 'human', env: io.env, keychain: io.keychain });
46
+ }
47
+ catch (err) {
48
+ const detail = err instanceof Error ? err.message : String(err);
49
+ return {
50
+ ok: false,
51
+ code: 1,
52
+ message: `human credential read failed for ${origin}: ${detail}`,
53
+ };
54
+ }
55
+ if (cred === null) {
56
+ return {
57
+ ok: false,
58
+ code: 2,
59
+ message: `no human credential for ${origin} — run: owenloop login --hub ${origin} --as human`,
60
+ };
61
+ }
62
+ try {
63
+ const fresh = await ensureFreshOAuth(io, origin, { principal: 'human' }, cred);
64
+ return { ok: true, token: credentialToToken(fresh) };
65
+ }
66
+ catch (err) {
67
+ const detail = err instanceof Error ? err.message : String(err);
68
+ return {
69
+ ok: false,
70
+ code: 1,
71
+ message: `human credential refresh failed for ${origin}: ${detail}`,
72
+ };
73
+ }
74
+ }
75
+ const { account } = args;
30
76
  // 1. Dev-only override: explicit OWENLOOP_TOKEN bypasses the store + account.
31
77
  const override = env['OWENLOOP_TOKEN']?.trim();
32
78
  if (override !== undefined && override !== '') {
@@ -31,23 +31,25 @@
31
31
  * whole point of the list.
32
32
  *
33
33
  * COMMANDS
34
- * owenloop work approvals [--json] every approval a worker is blocked on
35
- * owenloop work approvals approve <wf>/<run> <tool-use-id> [--note <text>]
36
- * owenloop work approvals deny <wf>/<run> <tool-use-id> [--note <text>]
34
+ * owenloop work approvals [--origin <url>] [--json] every approval a worker is blocked on
35
+ * owenloop work approvals approve <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]
36
+ * owenloop work approvals deny <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]
37
37
  *
38
38
  * The decision is a positional VERB rather than an `--approve` flag, because a
39
39
  * flag that grants a dangerous command is one typo away from being omitted, and
40
40
  * an omitted flag has to mean something. A verb cannot be omitted.
41
41
  *
42
- * Origin and bearer resolve exactly as in `release`: `--origin` → settings
43
- * `hubOrigin`, and the `agent:<account>` credential slot for `OWENLOOP_ACCOUNT`
44
- * (default `default`). The hub refuses `answer_approval` to an agent token by
45
- * design — this verb is for a person's key.
42
+ * Origin resolves as in `release`: `--origin` → settings `hubOrigin`.
43
+ * Listing reads the `agent:<account>` credential slot selected by
44
+ * `OWENLOOP_ACCOUNT` (default `default`). Approve and deny always read the
45
+ * stored `human` slot because the hub correctly reserves `answer_approval`
46
+ * for a person's key.
46
47
  *
47
48
  * Exit codes: 0 on success (including an empty list) · 1 on a hub/network error
48
49
  * · 2 on a usage error.
49
50
  */
50
51
  import { type HubClient } from '../hub/client.ts';
52
+ import { type BearerResult, type ResolveBearerArgs } from '../credentials/resolve.ts';
51
53
  type Action = 'list' | 'approve' | 'deny';
52
54
  interface ParsedArgs {
53
55
  action: Action;
@@ -71,6 +73,7 @@ export interface RunDeps {
71
73
  err?: (line: string) => void;
72
74
  env?: Record<string, string | undefined>;
73
75
  now?: () => number;
76
+ resolveBearer?: (args: ResolveBearerArgs) => Promise<BearerResult>;
74
77
  }
75
78
  export declare function run(args: string[], deps?: RunDeps): Promise<number>;
76
79
  export {};
@@ -31,18 +31,19 @@
31
31
  * whole point of the list.
32
32
  *
33
33
  * COMMANDS
34
- * owenloop work approvals [--json] every approval a worker is blocked on
35
- * owenloop work approvals approve <wf>/<run> <tool-use-id> [--note <text>]
36
- * owenloop work approvals deny <wf>/<run> <tool-use-id> [--note <text>]
34
+ * owenloop work approvals [--origin <url>] [--json] every approval a worker is blocked on
35
+ * owenloop work approvals approve <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]
36
+ * owenloop work approvals deny <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]
37
37
  *
38
38
  * The decision is a positional VERB rather than an `--approve` flag, because a
39
39
  * flag that grants a dangerous command is one typo away from being omitted, and
40
40
  * an omitted flag has to mean something. A verb cannot be omitted.
41
41
  *
42
- * Origin and bearer resolve exactly as in `release`: `--origin` → settings
43
- * `hubOrigin`, and the `agent:<account>` credential slot for `OWENLOOP_ACCOUNT`
44
- * (default `default`). The hub refuses `answer_approval` to an agent token by
45
- * design — this verb is for a person's key.
42
+ * Origin resolves as in `release`: `--origin` → settings `hubOrigin`.
43
+ * Listing reads the `agent:<account>` credential slot selected by
44
+ * `OWENLOOP_ACCOUNT` (default `default`). Approve and deny always read the
45
+ * stored `human` slot because the hub correctly reserves `answer_approval`
46
+ * for a person's key.
46
47
  *
47
48
  * Exit codes: 0 on success (including an empty list) · 1 on a hub/network error
48
49
  * · 2 on a usage error.
@@ -112,9 +113,9 @@ export function splitOrder(order) {
112
113
  return { workflow: order.slice(0, slash), run: order.slice(slash + 1) };
113
114
  }
114
115
  function usage(err) {
115
- err('usage: owenloop work approvals [--json]');
116
- err(' owenloop work approvals approve <workflow>/<run> <tool-use-id> [--note <text>]');
117
- err(' owenloop work approvals deny <workflow>/<run> <tool-use-id> [--note <text>]');
116
+ err('usage: owenloop work approvals [--origin <url>] [--json]');
117
+ err(' owenloop work approvals approve <workflow>/<run> <tool-use-id> [--origin <url>] [--note <text>]');
118
+ err(' owenloop work approvals deny <workflow>/<run> <tool-use-id> [--origin <url>] [--note <text>]');
118
119
  }
119
120
  function errMsg(err) {
120
121
  return err instanceof Error ? err.message : String(err);
@@ -172,8 +173,10 @@ export async function run(args, deps = {}) {
172
173
  err('owenloop work approvals: no hub origin — pass --origin <url> or set hubOrigin in settings');
173
174
  return 2;
174
175
  }
175
- const account = env['OWENLOOP_ACCOUNT'] ?? 'default';
176
- const bearer = await resolveBearer({ origin, account, env });
176
+ const bearerArgs = parsed.action === 'list'
177
+ ? { principal: 'agent', origin, account: env['OWENLOOP_ACCOUNT'] ?? 'default', env }
178
+ : { principal: 'human', origin, env };
179
+ const bearer = await (deps.resolveBearer ?? resolveBearer)(bearerArgs);
177
180
  if (!bearer.ok) {
178
181
  err(`owenloop work approvals: ${bearer.message}`);
179
182
  return bearer.code;
@@ -736,15 +736,17 @@ export function createShiftLoop(opts) {
736
736
  ...live.filter((r) => r.kind === 'agent-run').map((r) => r.run),
737
737
  ...reserved.filter((r) => r.childKind === 'agent-run').map((r) => r.run),
738
738
  ]);
739
- // Resolve which instances to poll.
739
+ // Resolve which instances to poll. Fleet candidates retain their source
740
+ // inbox row so only a proven zero may avoid a targeted observation. An
741
+ // explicit workflow has no inbox row and must always receive one.
740
742
  let instances;
741
743
  if (opts.workflow !== undefined) {
742
- instances = [opts.workflow];
744
+ instances = [{ workflow: opts.workflow }];
743
745
  }
744
746
  else {
745
747
  try {
746
748
  const inbox = await opts.hub.whatsNext({ serve_capabilities: [...serveCapabilities] });
747
- instances = (inbox.instances ?? []).map((i) => i.workflow);
749
+ instances = (inbox.instances ?? []).map((inbox) => ({ workflow: inbox.workflow, inbox }));
748
750
  }
749
751
  catch (e) {
750
752
  noteServerBackoff(e);
@@ -797,13 +799,19 @@ export function createShiftLoop(opts) {
797
799
  releasedForCapacity = true;
798
800
  }
799
801
  };
800
- for (const wf of instances) {
802
+ for (const candidate of instances) {
803
+ const wf = candidate.workflow;
801
804
  // Skipping means no targeted hub observation happened: leave this
802
805
  // workflow out of `polled`/`openRuns` so the work-directory reaper never
803
806
  // mistakes damping for an empty response. The inbox call and other
804
807
  // workflows remain eligible.
805
808
  if (workflowCapacityCooldownActive(wf, remaining, agentRoom))
806
809
  continue;
810
+ // Only a numeric zero is authoritative enough to skip. Missing or
811
+ // malformed wire data deliberately falls through to the targeted call.
812
+ // This runs after the cooldown check so a newly ready cooldown is cleared.
813
+ if (candidate.inbox?.eligible === 0)
814
+ continue;
807
815
  let res;
808
816
  const requestStartedAt = monotonicNow();
809
817
  try {
@@ -3,4 +3,4 @@
3
3
  * exit 0) and on a dispatch error (to stderr, exit 2). Keeping it in one place
4
4
  * means the help output and the error output never drift apart.
5
5
  */
6
- export declare const USAGE = "owenloop work \u2014 execution-side CLI companion to owenloop\n\nUsage:\n owenloop work hold --order <id> [options] hold an order with a heartbeating lease\n owenloop work exec <order-id> [options] run a command order in a self-leasing loop\n owenloop work agent-run <order-id> [options] host an agent order's step agent in a\n harness, in a self-leasing loop\n owenloop work prepare <workflow> [--origin <url>]\n fetch, cache & normalize step specs\n owenloop work lint <workflow-name | path> lint x.harness option bags in a def\n owenloop work sessions [--all] [--json] list this machine's recorded harness\n sessions and how to re-open them\n owenloop work approvals [--json] every tool call a worker is blocked on\n RIGHT NOW, waiting for a person\n owenloop work approvals approve|deny <wf>/<run> <tool-use-id> [--note <text>]\n answer one; the answer goes back to the\n still-blocked call, not to a later attempt\n owenloop work release --session <id> [options] drain a session's held claims\n owenloop work settings print the resolved settings file\n owenloop work join <code> [--hub <origin>] [--as <account>]\n redeem a join code and store the Scoped\n Identity credential (one-time provisioning)\n\nOptions:\n -h, --help show this help and exit 0\n --version print the owenloop work version and exit 0\n\n root shift options (run as owenloop shift start <crew...> | --all):\n <crew...> serve only these crews (positional, space\n separated); or --all for every crew on the key\n --all serve every crew on the key\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account to read + hand\n to dispatched holds/execs (default 'default')\n --name <n> Shift name (default <hostname>/<cwd>)\n --cap <n> max in-flight exec children (default 3)\n --poll-interval <ms> wake poll cadence (default 5000)\n --once bootstrap wake + one sweep, then exit (demo/e2e)\n --max-agents <n> max in-flight agent-run children, separate from\n --cap (default 4; else settings.maxConcurrentAgents)\n\t\t--exec-reserve <n> slots inside --cap that agent-run children may\n\t\t\t\t\tnot occupy, so exec orders always have room\n\t\t\t\t\t(default 1; else settings.execReserve; 0 disables)\n --local-queue-hold <ms> retain an undispatchable claim locally before\n\t\t\t\t\treturning it to the hub (default 0; else\n\t\t\t\t\tsettings.localQueueHoldMs; capped at 90000)\n --cache-dir/--state-dir <p> override the resolved dirs\n\n hold options:\n --order <workflow>/<run> the order to hold (or --order <run> --workflow)\n --workflow <wf> required when --order is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --as <account> Scoped Identity credential account (default\n 'default'; the shift stamps this into born-bound\n holds)\n --session <id> session-holder tag (else env OWENLOOP_SESSION;\n else an anon:<hostname>:<pid> fallback \u2014 a\n holder is always sent)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --ignore-stdin don't final-breath on stdin EOF (detached use)\n --never-release another process holds the claim; stop without\n releasing it (agent-run spawns its --mcp child\n this way \u2014 see hold.ts HOLDER OF RECORD)\n --mcp run as a stdio-MCP work-holder: tools get_order /\n submit, lease kept warm underneath (mutually\n exclusive with --ignore-stdin \u2014 stdin is the\n transport)\n\n exec options (usually spawned by shift, not run by hand):\n <workflow>/<run> the command order to run (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n\n agent-run options (spawned by the shift, not run by hand):\n <workflow>/<run> the agent order to host (positional order-id;\n or a bare <run> plus --workflow <wf>)\n --workflow <wf> required when the order-id is a bare run id\n --origin <url> hub origin (else settings.hubOrigin)\n --harness <id> which registered harness hosts the step agent\n (below a selected roster candidate; else the\n step def's 'harness' field, then the first\n registered one)\n --shift <id> dispatching Shift's self-declared id (else\n env OWENLOOP_SHIFT_ID); advisory only\n --heartbeat-interval <ms> lease renew cadence (default 60000)\n --jump-tolerance <ms> wall-gap slack before a tick is treated as a\n clock jump / laptop sleep (default 30000)\n --submit-grace <ms> after the turn ends, how long to keep asking the\n hub whether the agent's submit landed (default\n 15000). Task completion comes from the HUB, never\n from the harness stream.\n --confirm-interval <ms> poll cadence inside that grace (default 1000)\n\n release options:\n --session <id> session whose claims to drain (else env\n OWENLOOP_SESSION). Agent-held claims re-offer;\n exec-held claims are drain-exempt (B3).\n --origin <url> hub origin (else settings.hubOrigin)\n\n settings (no options in v1):\n prints the resolved settings file path, whether it exists, each known\n knob (hubOrigin, cacheDir, stateDir, dispatchCap, commandRouting,\n maxConcurrentAgents, execReserve, localQueueHoldMs, workRoot, workRepo) with its value + provenance,\n and any unrecognized keys.\n settings.dispatchCap/stateDir are the lowest-precedence\n fallbacks for shift's --cap/--state-dir. NO secrets ever\n live in settings \u2014 credentials stay in owenloop's own store.\n\n sessions options:\n --all include 'dead' sessions (hidden by default \u2014\n a dead session can no longer be resumed)\n --json print the raw newest-per-step records, tokens\n included, instead of the table\n --cache-dir <p> override the resolved cache dir\n\n join options:\n --hub <origin> hub to redeem against (else settings.hubOrigin;\n one of the two is REQUIRED \u2014 the code never\n chooses the hub)\n --as <account> credential account to store under (default:\n the Scoped Identity name the hub returns)\n\n shift/hold/exec/prepare/release env:\n credentials come from owenloop's store \u2014 each role reads the\n agent:<account> slot for its origin (never the human slot); a\n missing slot refuses with a runnable 'owenloop login' command.\n OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release\n (default 'default'; shift uses --as, and\n stamps it onto dispatched holds/execs)\n OWENLOOP_TOKEN dev-only bearer override \u2014 when set, used\n verbatim and the store + account are\n bypassed (NOT the primary path)\n OWENLOOP_CACHE_DIR cache root\n OWENLOOP_STATE_DIR shift in-flight state dir\n OWENLOOP_SHIFT_LOG_DIR dir for the shift's shift.log and each\n worker's <run>.log; below --log-dir, above\n settings.shiftLogDir, default the state dir\n OWENLOOP_SHIFT_LOG_MAX_AGE_MS\n how long a worker's <run>.log is kept, in ms;\n below --log-max-age, above\n settings.shiftLogMaxAgeMs, default 14 days.\n Worker logs only \u2014 shift.log is never reaped\n OWENLOOP_SESSION hold session-holder tag / release drain target\n OWENLOOP_SHIFT_ID dispatching Shift's self-declared id for\n hold/exec/agent-run's --shift (advisory\n only, never for auth/routing/dispatch)\n OWENLOOP_WORK_ROOT root for per-RUN agent work dirs\n (<workRoot>/<workflow>/<run>); above\n settings.workRoot, default <cacheDir>/work.\n A hub-supplied OrderPacket.workdir still\n wins, and is never reaped.\n OWENLOOP_WORK_REPO local git repo to cut per-run work dirs from\n as worktrees instead of plain dirs; above\n settings.workRepo, default off\n\n Credentials / accounts:\n owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY\n over owenloop's credential store \u2014 they never write credentials. Each\n role reads the agent:<account> slot for its origin (never the human\n slot); the account defaults to 'default'. 'owenloop work join' is the one\n deliberate provisioning-time writer: it stores the Scoped Identity token a hub\n redeem returns via owenloop's public storeCredential, once, at join time\n \u2014 not a runtime write.\n store / connect an account (run owenloop; owenloop work never writes it):\n owenloop login --hub <origin> --as agent:<account>\n (use --as agent for the default account)\n or provision a fresh box from a hub-issued join code:\n owenloop work join <code> --hub <origin>\n select an account at run time:\n --as <account> on shift / hold\n OWENLOOP_ACCOUNT on exec / prepare / release\n (shift resolves once and threads both channels)\n owenloop work does NOT list stored accounts \u2014 enumerating an origin's accounts\n is an owenloop-side capability; check owenloop for which slots are stored.\n\nExit codes:\n 0 success / help / version / lint clean or warnings-only\n 1 runtime failure (fetch/hub error, cache write) / lint found an error\n 2 usage error (unknown or missing role, missing required arg)\n 3 role not implemented yet (skeleton stub \u2014 lands in a later delivery)\n";
6
+ export declare const USAGE: string;
@@ -15,9 +15,11 @@ Usage:
15
15
  owenloop work lint <workflow-name | path> lint x.harness option bags in a def
16
16
  owenloop work sessions [--all] [--json] list this machine's recorded harness
17
17
  sessions and how to re-open them
18
- owenloop work approvals [--json] every tool call a worker is blocked on
18
+ owenloop work approvals [--origin <url>] [--json]
19
+ ${' '.repeat(41)}every tool call a worker is blocked on
19
20
  RIGHT NOW, waiting for a person
20
- owenloop work approvals approve|deny <wf>/<run> <tool-use-id> [--note <text>]
21
+ owenloop work approvals approve <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]
22
+ owenloop work approvals deny <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]
21
23
  answer one; the answer goes back to the
22
24
  still-blocked call, not to a later attempt
23
25
  owenloop work release --session <id> [options] drain a session's held claims
@@ -128,6 +130,15 @@ Options:
128
130
  included, instead of the table
129
131
  --cache-dir <p> override the resolved cache dir
130
132
 
133
+ approvals options:
134
+ --origin <url> hub origin (else settings.hubOrigin)
135
+ --json print pending approval rows as JSON (list only)
136
+ --note <text> attach an operator note (approve / deny only)
137
+ credentials list reads the agent:<account> slot selected by
138
+ ${' '.repeat(33)}OWENLOOP_ACCOUNT (default 'default'); approve
139
+ ${' '.repeat(33)}and deny read the stored human slot instead
140
+ missing human credential run: owenloop login --hub <origin> --as human
141
+
131
142
  join options:
132
143
  --hub <origin> hub to redeem against (else settings.hubOrigin;
133
144
  one of the two is REQUIRED — the code never
@@ -135,16 +146,23 @@ Options:
135
146
  --as <account> credential account to store under (default:
136
147
  the Scoped Identity name the hub returns)
137
148
 
138
- shift/hold/exec/prepare/release env:
149
+ shift/hold/exec/prepare/release and approvals-list env:
139
150
  credentials come from owenloop's store — each role reads the
140
151
  agent:<account> slot for its origin (never the human slot); a
141
152
  missing slot refuses with a runnable 'owenloop login' command.
153
+ ${' '.repeat(15)}approvals approve/deny ignore OWENLOOP_ACCOUNT and OWENLOOP_TOKEN,
154
+ ${' '.repeat(15)}never mint or log credentials, and refuse with 'owenloop login
155
+ ${' '.repeat(15)}--hub <origin> --as human' when the human slot is absent. An
156
+ ${' '.repeat(15)}expiring stored human OAuth credential may refresh and persist its
157
+ ${' '.repeat(15)}rotation through owenloop's shared credential lock.
142
158
  OWENLOOP_ACCOUNT Scoped Identity account for exec/prepare/release
143
- (default 'default'; shift uses --as, and
144
- stamps it onto dispatched holds/execs)
159
+ ${' '.repeat(38)}and approvals list (default 'default';
160
+ ${' '.repeat(38)}shift uses --as, and stamps it onto
161
+ ${' '.repeat(38)}dispatched holds/execs)
145
162
  OWENLOOP_TOKEN dev-only bearer override — when set, used
146
163
  verbatim and the store + account are
147
- bypassed (NOT the primary path)
164
+ ${' '.repeat(38)}bypassed (NOT the primary path; never for
165
+ ${' '.repeat(38)}approvals approve/deny)
148
166
  OWENLOOP_CACHE_DIR cache root
149
167
  OWENLOOP_STATE_DIR shift in-flight state dir
150
168
  OWENLOOP_SHIFT_LOG_DIR dir for the shift's shift.log and each
@@ -169,13 +187,18 @@ Options:
169
187
  settings.workRepo, default off
170
188
 
171
189
  Credentials / accounts:
172
- owenloop work's RUNTIME roles (shift/hold/exec/prepare/release) are READ-ONLY
173
- over owenloop's credential store — they never write credentials. Each
174
- role reads the agent:<account> slot for its origin (never the human
175
- slot); the account defaults to 'default'. 'owenloop work join' is the one
176
- deliberate provisioning-time writer: it stores the Scoped Identity token a hub
177
- redeem returns via owenloop's public storeCredential, once, at join time
178
- — not a runtime write.
190
+ owenloop work's RUNTIME roles (shift/hold/exec/prepare/release and
191
+ approvals list) are READ-ONLY over owenloop's credential store — they
192
+ never write credentials. Each reads the agent:<account> slot for its
193
+ origin (never the human slot); the account defaults to 'default'.
194
+ Approval decisions require the stored human slot rather than an agent
195
+ slot. They never mint or log credentials, but an expiring stored OAuth
196
+ credential may refresh and persist its rotation under the shared lock; if
197
+ the human slot is absent, run:
198
+ ${' '.repeat(8)}owenloop login --hub <origin> --as human
199
+ 'owenloop work join' is the one deliberate provisioning-time writer: it
200
+ stores the Scoped Identity token a hub redeem returns via owenloop's public
201
+ storeCredential, once, at join time — not a runtime write.
179
202
  store / connect an account (run owenloop; owenloop work never writes it):
180
203
  owenloop login --hub <origin> --as agent:<account>
181
204
  (use --as agent for the default account)
@@ -183,7 +206,7 @@ Options:
183
206
  owenloop work join <code> --hub <origin>
184
207
  select an account at run time:
185
208
  --as <account> on shift / hold
186
- OWENLOOP_ACCOUNT on exec / prepare / release
209
+ ${' '.repeat(10)}OWENLOOP_ACCOUNT on exec / prepare / release / approvals list
187
210
  (shift resolves once and threads both channels)
188
211
  owenloop work does NOT list stored accounts — enumerating an origin's accounts
189
212
  is an owenloop-side capability; check owenloop for which slots are stored.
package/dist/src/cli.d.ts CHANGED
@@ -210,6 +210,7 @@ export interface HarnessPluginState {
210
210
  installed: boolean;
211
211
  installedVersion: string | null;
212
212
  cliVersion: string | null;
213
+ mcpLaunch: McpLaunchState | null;
213
214
  }
214
215
  /**
215
216
  * Resolve a bundled marketplace root from either the source tree (`src/cli.ts`)
@@ -217,6 +218,11 @@ export interface HarnessPluginState {
217
218
  * package from producing a path that the harness cannot consume.
218
219
  */
219
220
  export declare function resolveBundledMarketplaceRoot(harness: HarnessId): string | null;
221
+ type McpLaunchStatus = 'path' | 'unsafe' | 'unknown';
222
+ interface McpLaunchState {
223
+ status: McpLaunchStatus;
224
+ detail: string;
225
+ }
220
226
  /**
221
227
  * Async entry point that adds network I/O for `add` and the hub commands on top
222
228
  * of the otherwise fully-synchronous engine/CLI (see the doc comment on
package/dist/src/cli.js CHANGED
@@ -7358,17 +7358,93 @@ function firstOutputLine(value) {
7358
7358
  const line = value.split(/\r?\n/, 1)[0]?.trim() ?? '';
7359
7359
  return line === '' ? null : line;
7360
7360
  }
7361
- function parsePluginList(stdout, harness) {
7361
+ function unknownMcpLaunch(detail) {
7362
+ return { status: 'unknown', detail };
7363
+ }
7364
+ /**
7365
+ * Describe an untrusted plugin launch without echoing manifest values. Plugin
7366
+ * manifests are local user-controlled input, so command/argument strings can
7367
+ * carry credentials even when the declaration is invalid.
7368
+ */
7369
+ function describeMcpLaunch(command, args) {
7370
+ const commandShape = command === 'owenloop'
7371
+ ? '"owenloop"'
7372
+ : command === 'node'
7373
+ ? '"node"'
7374
+ : isAbsolute(command)
7375
+ ? 'an absolute command'
7376
+ : 'a non-owenloop command';
7377
+ const argsShape = args.length === 1 && args[0] === 'mcp'
7378
+ ? 'exactly the "mcp" argument'
7379
+ : args[0] === 'mcp'
7380
+ ? `"mcp" plus ${args.length - 1} additional argument(s)`
7381
+ : `${args.length} argument(s) not exactly "mcp"`;
7382
+ return `declares ${commandShape} with ${argsShape}; expected "owenloop" with exactly "mcp" via PATH`;
7383
+ }
7384
+ function classifyMcpLaunch(server, harness, env) {
7385
+ const declaration = recordOf(server);
7386
+ if (declaration === null)
7387
+ return unknownMcpLaunch('the owenloop MCP declaration is missing or malformed');
7388
+ const command = declaration.command;
7389
+ const args = declaration.args;
7390
+ if (typeof command !== 'string' || !Array.isArray(args) || !args.every((arg) => typeof arg === 'string')) {
7391
+ return unknownMcpLaunch('the owenloop MCP command or arguments are missing or malformed');
7392
+ }
7393
+ if (command !== 'owenloop' || args.length !== 1 || args[0] !== 'mcp') {
7394
+ return { status: 'unsafe', detail: describeMcpLaunch(command, args) };
7395
+ }
7396
+ if (harness === 'codex') {
7397
+ const envVars = declaration.env_vars;
7398
+ if (!Array.isArray(envVars) || !envVars.includes('PATH')) {
7399
+ return { status: 'unsafe', detail: 'declares "owenloop" "mcp" but does not pass PATH to the MCP subprocess' };
7400
+ }
7401
+ }
7402
+ if (!commandOnPath(env, 'owenloop')) {
7403
+ return { status: 'unsafe', detail: 'declares "owenloop" "mcp" but owenloop is not executable on PATH' };
7404
+ }
7405
+ return { status: 'path', detail: 'MCP resolves as owenloop mcp via PATH' };
7406
+ }
7407
+ function mcpLaunchFromManifest(pluginRoot, harness, env, rootName) {
7408
+ if (typeof pluginRoot !== 'string' || pluginRoot.trim() === '') {
7409
+ return unknownMcpLaunch(`${rootName} was not reported by the harness`);
7410
+ }
7411
+ try {
7412
+ const manifest = recordOf(JSON.parse(readFileSync(join(pluginRoot, '.mcp.json'), 'utf8')));
7413
+ const servers = recordOf(manifest?.mcpServers);
7414
+ if (servers === null || !Object.hasOwn(servers, 'owenloop')) {
7415
+ return unknownMcpLaunch(`${rootName}/.mcp.json does not declare mcpServers.owenloop`);
7416
+ }
7417
+ return classifyMcpLaunch(servers.owenloop, harness, env);
7418
+ }
7419
+ catch {
7420
+ return unknownMcpLaunch(`could not read ${rootName}/.mcp.json`);
7421
+ }
7422
+ }
7423
+ function mcpLaunchFromPluginEntry(entry, harness, env) {
7424
+ if (harness === 'claude-code') {
7425
+ if (Object.hasOwn(entry, 'mcpServers')) {
7426
+ const servers = recordOf(entry.mcpServers);
7427
+ if (servers === null)
7428
+ return unknownMcpLaunch('the inline mcpServers data is malformed');
7429
+ if (Object.hasOwn(servers, 'owenloop'))
7430
+ return classifyMcpLaunch(servers.owenloop, harness, env);
7431
+ }
7432
+ return mcpLaunchFromManifest(entry.installPath, harness, env, 'installPath');
7433
+ }
7434
+ const source = recordOf(entry.source);
7435
+ return mcpLaunchFromManifest(source?.path, harness, env, 'source.path');
7436
+ }
7437
+ function parsePluginList(stdout, harness, env) {
7362
7438
  let parsed;
7363
7439
  try {
7364
7440
  parsed = JSON.parse(stdout);
7365
7441
  }
7366
7442
  catch {
7367
- return { known: false, installed: false, installedVersion: null };
7443
+ return { known: false, installed: false, installedVersion: null, mcpLaunch: null };
7368
7444
  }
7369
7445
  if (harness === 'claude-code') {
7370
7446
  if (!Array.isArray(parsed))
7371
- return { known: false, installed: false, installedVersion: null };
7447
+ return { known: false, installed: false, installedVersion: null, mcpLaunch: null };
7372
7448
  const entry = parsed.find((item) => {
7373
7449
  const row = recordOf(item);
7374
7450
  if (row === null)
@@ -7377,12 +7453,18 @@ function parsePluginList(stdout, harness) {
7377
7453
  return id === PLUGIN_SELECTOR || id.split('@', 1)[0] === 'owenloop';
7378
7454
  });
7379
7455
  return entry === undefined
7380
- ? { known: true, installed: false, installedVersion: null }
7381
- : { known: true, installed: true, installedVersion: normalizedPluginVersion(entry.version) };
7456
+ ? { known: true, installed: false, installedVersion: null, mcpLaunch: null }
7457
+ : {
7458
+ known: true,
7459
+ installed: true,
7460
+ installedVersion: normalizedPluginVersion(entry.version),
7461
+ mcpLaunch: mcpLaunchFromPluginEntry(entry, harness, env),
7462
+ };
7382
7463
  }
7383
7464
  const root = recordOf(parsed);
7384
- if (root === null || !Array.isArray(root.installed))
7385
- return { known: false, installed: false, installedVersion: null };
7465
+ if (root === null || !Array.isArray(root.installed)) {
7466
+ return { known: false, installed: false, installedVersion: null, mcpLaunch: null };
7467
+ }
7386
7468
  const entry = root.installed.find((item) => {
7387
7469
  const row = recordOf(item);
7388
7470
  if (row === null || row.installed !== true)
@@ -7391,8 +7473,13 @@ function parsePluginList(stdout, harness) {
7391
7473
  (row.name === 'owenloop' && row.marketplaceName === 'owenloop'));
7392
7474
  });
7393
7475
  return entry === undefined
7394
- ? { known: true, installed: false, installedVersion: null }
7395
- : { known: true, installed: true, installedVersion: normalizedPluginVersion(entry.version) };
7476
+ ? { known: true, installed: false, installedVersion: null, mcpLaunch: null }
7477
+ : {
7478
+ known: true,
7479
+ installed: true,
7480
+ installedVersion: normalizedPluginVersion(entry.version),
7481
+ mcpLaunch: mcpLaunchFromPluginEntry(entry, harness, env),
7482
+ };
7396
7483
  }
7397
7484
  function probeCliVersion(run, cliName) {
7398
7485
  try {
@@ -7410,24 +7497,35 @@ function probePlugin(io) {
7410
7497
  const config = HARNESS_CONFIGS[id];
7411
7498
  const cliFound = commandOnPath(io.env, config.cliName);
7412
7499
  if (!cliFound) {
7413
- return { id, cliName: config.cliName, cliFound: false, installed: false, installedVersion: null, cliVersion: null };
7500
+ return {
7501
+ id,
7502
+ cliName: config.cliName,
7503
+ cliFound: false,
7504
+ installed: false,
7505
+ installedVersion: null,
7506
+ cliVersion: null,
7507
+ mcpLaunch: null,
7508
+ };
7414
7509
  }
7415
7510
  let installed = false;
7416
7511
  let installedVersion = null;
7512
+ let mcpLaunch = null;
7417
7513
  try {
7418
7514
  const result = run(config.cliName, ['plugin', 'list', '--json']);
7419
7515
  if (result.status === 0) {
7420
- const parsed = parsePluginList(result.stdout, id);
7516
+ const parsed = parsePluginList(result.stdout, id, io.env);
7421
7517
  // A successful command with malformed output cannot establish presence.
7422
7518
  // Treat it as not installed, matching the non-zero-exit path below.
7423
7519
  installed = parsed.known ? parsed.installed : false;
7424
7520
  installedVersion = parsed.installedVersion;
7521
+ mcpLaunch = parsed.mcpLaunch;
7425
7522
  }
7426
7523
  }
7427
7524
  catch {
7428
7525
  // A failed probe cannot establish presence; the ACT remains PATH-gated.
7429
7526
  installed = false;
7430
7527
  installedVersion = null;
7528
+ mcpLaunch = null;
7431
7529
  }
7432
7530
  return {
7433
7531
  id,
@@ -7436,6 +7534,7 @@ function probePlugin(io) {
7436
7534
  installed,
7437
7535
  installedVersion,
7438
7536
  cliVersion: probeCliVersion(run, config.cliName),
7537
+ mcpLaunch,
7439
7538
  };
7440
7539
  });
7441
7540
  }
@@ -7531,7 +7630,7 @@ function installPluginStep(io, state) {
7531
7630
  }
7532
7631
  const expectedVersion = packageVersion().trim();
7533
7632
  const currentVersion = state.installedVersion?.trim() ?? null;
7534
- if (state.installed && currentVersion === expectedVersion) {
7633
+ if (state.installed && currentVersion === expectedVersion && state.mcpLaunch?.status !== 'unsafe') {
7535
7634
  return { action: 'skipped', detail: `owenloop ${currentVersion} already current` };
7536
7635
  }
7537
7636
  const root = resolvedMarketplaceRoot(io, state.id);
@@ -8191,14 +8290,29 @@ async function runDoctor(io, origin) {
8191
8290
  const cliVersion = pluginState.cliVersion ?? 'unknown';
8192
8291
  record(`plugin (${pluginState.id})`, false, `not installed — ${pluginRemedy(pluginState.id, root)} · ${config.cliName} ${cliVersion}`, PLUGIN_CHECK_FATAL);
8193
8292
  }
8194
- else if (pluginState.installedVersion === null) {
8195
- record(`plugin (${pluginState.id})`, true, `owenloop version unknown · ${config.cliName} ${pluginState.cliVersion ?? 'unknown'}`, PLUGIN_CHECK_FATAL);
8196
- }
8197
- else if (pluginState.installedVersion === packageVersion().trim()) {
8198
- record(`plugin (${pluginState.id})`, true, `owenloop ${pluginState.installedVersion} · ${config.cliName} ${pluginState.cliVersion ?? 'unknown'}`, PLUGIN_CHECK_FATAL);
8199
- }
8200
8293
  else {
8201
- record(`plugin (${pluginState.id})`, false, `owenloop ${pluginState.installedVersion} but CLI is ${packageVersion().trim()} — run owenloop setup · ${config.cliName} ${pluginState.cliVersion ?? 'unknown'}`, PLUGIN_CHECK_FATAL);
8294
+ const launch = pluginState.mcpLaunch ?? unknownMcpLaunch('the effective MCP launch was not reported');
8295
+ const expectedVersion = packageVersion().trim();
8296
+ const findings = [];
8297
+ if (launch.status === 'unsafe') {
8298
+ findings.push(`MCP launch drift: ${launch.detail} — run owenloop setup`);
8299
+ }
8300
+ else if (launch.status === 'unknown') {
8301
+ findings.push(`MCP launch unverifiable: ${launch.detail} — run owenloop setup`);
8302
+ }
8303
+ if (pluginState.installedVersion !== null && pluginState.installedVersion !== expectedVersion) {
8304
+ findings.push(`owenloop ${pluginState.installedVersion} but CLI is ${expectedVersion} — run owenloop setup`);
8305
+ }
8306
+ const cliVersion = `${config.cliName} ${pluginState.cliVersion ?? 'unknown'}`;
8307
+ if (findings.length > 0) {
8308
+ record(`plugin (${pluginState.id})`, false, `${findings.join(' · ')} · ${cliVersion}`, PLUGIN_CHECK_FATAL);
8309
+ }
8310
+ else if (pluginState.installedVersion === null) {
8311
+ record(`plugin (${pluginState.id})`, true, `owenloop version unknown · ${launch.detail} · ${cliVersion}`, PLUGIN_CHECK_FATAL);
8312
+ }
8313
+ else {
8314
+ record(`plugin (${pluginState.id})`, true, `owenloop ${pluginState.installedVersion} · ${launch.detail} · ${cliVersion}`, PLUGIN_CHECK_FATAL);
8315
+ }
8202
8316
  }
8203
8317
  }
8204
8318
  return { ok: coreOk, checks };
package/dist/src/model.js CHANGED
@@ -654,6 +654,52 @@ export function memberRetractFirings(def, arts) {
654
654
  }
655
655
  return firings;
656
656
  }
657
+ /**
658
+ * Return the bare collection member that would be terminally removed by
659
+ * retracting an indexed debt. A bare member maps to itself; a suffixed map
660
+ * child maps back to its bare member, whose retraction cascades to that child.
661
+ * Non-indexed debts, including collection seals, have no member-retract
662
+ * recovery path.
663
+ */
664
+ function retractableMemberPath(path) {
665
+ const element = parseElement(path);
666
+ return element ? elementPath(element.stem, element.index) : undefined;
667
+ }
668
+ /** Whether a modeled authority retraction can clear this stalled debt. */
669
+ function retractClearsDebt(path, retractFirings) {
670
+ const memberPath = retractableMemberPath(path);
671
+ return memberPath !== undefined && retractFirings.some((firing) => firing.outputs[0] === memberPath);
672
+ }
673
+ /**
674
+ * A remaining output of the stalled debt's own producer or of an upstream
675
+ * producer is not unrelated-line progress. One worker may separately commit
676
+ * singleton and collection outputs, but that does not make a downstream
677
+ * schema-stalled sibling output `stuck`.
678
+ */
679
+ function progressMovesAnotherBranch(def, path, arts, progressFirings) {
680
+ const producer = arts.get(path)?.producer;
681
+ if (producer === undefined)
682
+ return progressFirings.length > 0;
683
+ const sameLine = new Set([producer]);
684
+ const pending = [producer];
685
+ while (pending.length > 0) {
686
+ const stepName = pending.pop();
687
+ const step = def.steps.find((candidate) => candidate.name === stepName);
688
+ if (!step)
689
+ continue;
690
+ for (const consume of step.consumes) {
691
+ for (const candidate of def.steps) {
692
+ if (!candidate.produces.some((produce) => produce.stem === consume.stem))
693
+ continue;
694
+ if (!sameLine.has(candidate.name)) {
695
+ sameLine.add(candidate.name);
696
+ pending.push(candidate.name);
697
+ }
698
+ }
699
+ }
700
+ }
701
+ return progressFirings.some((firing) => !sameLine.has(firing.step));
702
+ }
657
703
  /**
658
704
  * Every firing eligible *right now* — inputs satisfied AND an owed/rejected
659
705
  * output to discharge. This is the scheduling gate (§11.4): necessary, not
@@ -1995,8 +2041,12 @@ function eligibleOutcomes(def, arts, firing) {
1995
2041
  const el = parseElement(outPath);
1996
2042
  const isMember = !!el && el.suffix === '';
1997
2043
  const outcomes = [];
1998
- if (stem && !el) {
1999
- // collection producer (plain step with collection output) — emit-seal path
2044
+ // A mixed producer commits its singleton outputs separately before it emits
2045
+ // and seals its collection. `plainOutputs()` intentionally orders those
2046
+ // singletons before the seal, so only the seal is the collection verb; the
2047
+ // runtime still permits a consumer to judgment-reject that green seal.
2048
+ if (stem && !el && outPath === sealPath(stem)) {
2049
+ // collection producer's actual seal output — emit-seal path
2000
2050
  outcomes.push('emit-seal');
2001
2051
  return outcomes;
2002
2052
  }
@@ -2407,7 +2457,11 @@ export function modelCheck(def, opts = {}) {
2407
2457
  // a worker firing. It is separate from eligibleFirings so a rejected map
2408
2458
  // input still has the later retract move the runtime permits.
2409
2459
  const retractFirings = memberRetractFirings(def, node.arts);
2410
- const firings = [...status.eligible, ...callsFirings, ...retractFirings];
2460
+ // Member retractions remain real successor transitions, including in the
2461
+ // zero-move branch below. They are recovery authority actions, though, not
2462
+ // ordinary worker/calls progress on another branch for `stuck` reporting.
2463
+ const progressFirings = [...status.eligible, ...callsFirings];
2464
+ const firings = [...progressFirings, ...retractFirings];
2411
2465
  // Non-done state with no eligible firings: classify by recomputing
2412
2466
  // eligibility as if every freeze/stall were lifted and idle time had
2413
2467
  // elapsed. If retry or time would make a producer eligible, this is an
@@ -2424,11 +2478,15 @@ export function modelCheck(def, opts = {}) {
2424
2478
  }
2425
2479
  continue;
2426
2480
  }
2427
- // The state HAS eligible firings (the line can still move). If a brake tripped
2428
- // on some *other* branch, record it as an informational stuck state. A no-moves
2429
- // stall state never reaches here (it `continue`d above), so no state is ever
2430
- // listed in both `stuck` and `stallStates`/`deadlocks`.
2431
- if (status.debts.some((d) => d.stalled)) {
2481
+ // A state is stuck only if ordinary work (or a machine child discharge) can
2482
+ // still progress while another debt is irrecoverably stalled. A retract-only
2483
+ // transition is intentionally explored but is authority recovery, not
2484
+ // unrelated-branch progress; likewise a stalled indexed debt that an
2485
+ // authorized member retract clears is recoverable rather than stranded.
2486
+ // A no-moves state never reaches here, so it is never also a stall/deadlock.
2487
+ if (status.debts.some((debt) => debt.stalled
2488
+ && !retractClearsDebt(debt.path, retractFirings)
2489
+ && progressMovesAnotherBranch(def, debt.path, node.arts, progressFirings))) {
2432
2490
  report.stuck.push({ path: node.path });
2433
2491
  }
2434
2492
  // Respect maxDepth
package/docs/authoring.md CHANGED
@@ -894,6 +894,13 @@ suffixed reduce (`src[*].child`) can fan in on a map's per-element output
894
894
  instead of the bare elements. See [`research.yaml`](../examples/workflows/research.yaml)
895
895
  for a runnable example.
896
896
 
897
+ Recovery is deliberate: a consumer of `src[*]` can judgment-reject a green
898
+ seal, re-offering the producer to emit more items and seal again. If a bare
899
+ member itself is rejected, it is not regenerated at that index; a consumer
900
+ authorized by its consume edge should `retract` it instead, which also removes
901
+ its indexed children. See [the collection design](design.md#11-collections)
902
+ for the lifecycle details.
903
+
897
904
  ## Artifact values are JSON, and secrets don't belong in them
898
905
 
899
906
  An artifact's `value` is always a JSON object (`Record<string, unknown>`,
package/docs/cli.md CHANGED
@@ -323,6 +323,15 @@ Untargeted inbox polling and sibling workflows continue, but command work in a
323
323
  cooled workflow can wait until its cooldown expires. This shift-local damper
324
324
  is separate from `--local-queue-hold` and from server `Retry-After` backoff.
325
325
 
326
+ **Fleet inbox filtering.** In org-wide mode, after the untargeted inbox
327
+ response, the shift skips a workflow only when its `eligible` value is exactly
328
+ the number `0`; missing, malformed, or nonzero values still receive a targeted
329
+ `whats_next` call. An explicit `--workflow` always receives its targeted call.
330
+ An inbox-only skip is not counted as a successful targeted observation, so it
331
+ cannot by itself make the work-directory reaper scan or remove that workflow's
332
+ directories. Work that becomes eligible after the inbox snapshot is picked up
333
+ on a later poll.
334
+
326
335
  **On-disk logs.** A running shift appends its dispatch record to
327
336
  `<log-dir>/shift.log` as JSON Lines, and gives each dispatched worker's stdout
328
337
  and stderr their own `<log-dir>/<run>.log`. Both files outlive the shift
@@ -654,11 +663,24 @@ The execution settings file is `<config>/settings.json` (see
654
663
  | `prepare <workflow> [--origin <url>]` | fetch, cache, and normalize step specs |
655
664
  | `lint <workflow-name \| path>` | lint `x.harness` option bags in a workflow definition |
656
665
  | `sessions [--all] [--json]` | list recorded harness sessions and how to reopen them |
666
+ | `approvals [--origin <url>] [--json]` | list every tool call a worker is currently blocked on, waiting for a person |
667
+ | `approvals approve <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]` | approve one still-pending tool call; the answer returns to that blocked call |
668
+ | `approvals deny <wf>/<run> <tool-use-id> [--origin <url>] [--note <text>]` | deny one still-pending tool call; the answer returns to that blocked call |
657
669
  | `release --session <id> [options]` | drain a session's held claims |
658
670
  | `settings` | print the resolved execution settings file |
659
671
  | `join <code> [--hub <origin>] [--as <account>]` | redeem a join code and store the Scoped Identity credential |
660
672
  | `util modifier-init --default <value>` | print the requested modifier from `OWENLOOP_FEEDBACK`, else `OWENLOOP_MODIFIER`, else the required default |
661
673
 
674
+ `work approvals` distinguishes a worker that is still running and waiting on a
675
+ tool decision from a pending input gate or an `ask` that ends the current run.
676
+ Listing uses the agent credential selected by `OWENLOOP_ACCOUNT` (default
677
+ `default`). `approve` and `deny` always use the stored `human` credential,
678
+ ignore `OWENLOOP_ACCOUNT` and `OWENLOOP_TOKEN`, and require
679
+ `owenloop login --hub <origin> --as human` when that slot is absent. They never
680
+ mint or log credentials. If the stored human credential is an expiring OAuth
681
+ credential, the decision path may refresh it and persist a rotated token under
682
+ the shared credential lock before answering the hub.
683
+
662
684
  ### `util modifier-init`
663
685
 
664
686
  `owenloop util modifier-init --default <value>` is a deterministic helper for
@@ -2718,7 +2740,8 @@ The plugin step probes and, when needed, converges the bundled `owenloop` plugin
2718
2740
  for each available harness: Claude Code and Codex. Plugin convergence is
2719
2741
  non-fatal and setup continues when a harness is missing, the bundled marketplace
2720
2742
  root is unavailable, or a plugin command fails. A second run with the expected
2721
- plugin version already installed performs no plugin writes. The steps:
2743
+ plugin version already installed performs no plugin writes when its effective
2744
+ MCP launch is verified safe. The steps:
2722
2745
 
2723
2746
  1. **inspect** — read-only report of what's already present (human credential,
2724
2747
  execution settings, `claude` and `codex` on PATH, agent slots). No writes.
@@ -2745,16 +2768,23 @@ plugin version already installed performs no plugin writes. The steps:
2745
2768
  it reports that file as skipped and leaves its bytes untouched. If setup does
2746
2769
  not know any crews for the identity, it records a non-fatal noted result.
2747
2770
  7. **plugin** — probe and converge the bundled `owenloop` plugin separately
2748
- for Claude Code and Codex. When the installed plugin is missing or its
2749
- version differs from the CLI package, setup adds the bundled marketplace
2750
- when needed and installs or updates the plugin. Claude Code uses
2771
+ for Claude Code and Codex. Setup verifies the installed MCP declaration
2772
+ itself: it must run exactly `owenloop mcp` through `PATH`; Codex must also
2773
+ pass `PATH` through to that subprocess, and the current environment must
2774
+ resolve an executable `owenloop`. When the installed plugin is missing, its
2775
+ version differs from the CLI package, or its launch is known unsafe, setup
2776
+ adds the bundled marketplace when needed and installs or updates the plugin.
2777
+ Claude Code uses
2751
2778
  `claude plugin install` for a fresh install and `claude plugin update` for
2752
2779
  an existing plugin. Codex uses `codex plugin add owenloop@owenloop` for both
2753
2780
  fresh installs and upgrades; setup does not call
2754
2781
  `codex plugin marketplace upgrade`, which applies only to Git marketplaces.
2755
2782
  **Non-fatal:** a missing harness or failed convergence is reported as
2756
- `noted` and never fails setup. If the bundled marketplace root is
2757
- unavailable, setup prints manual commands instead.
2783
+ `noted` and never fails setup. Unverifiable launch metadata is reported by
2784
+ doctor but does not cause repeated setup writes. An absolute marketplace,
2785
+ cache, install, or source location is not unsafe by itself—the effective
2786
+ command and arguments determine the verdict. If the bundled marketplace root
2787
+ is unavailable, setup prints manual commands instead.
2758
2788
  8. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
2759
2789
  the same surfaces, whose result becomes setup's exit code.
2760
2790
 
@@ -2938,15 +2968,25 @@ The checks, in order:
2938
2968
  | 3 | agent slot | an `agent:<name>` credential is stored | yes |
2939
2969
  | 4 | agent plane | that agent credential verifies live against the hub | yes |
2940
2970
  | 5 | execution settings | the settings file's `hubOrigin` matches this hub | yes |
2941
- | 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is installed at the package version | **no** (rendered only) |
2942
- | 7 | plugin (codex) | the Codex `owenloop` plugin is installed at the package version | **no** (rendered only) |
2971
+ | 6 | plugin (claude-code) | the Claude Code `owenloop` plugin is at the package version and its effective launch resolves as `owenloop mcp` through PATH | **no** (rendered only) |
2972
+ | 7 | plugin (codex) | the Codex `owenloop` plugin is at the package version, launches `owenloop mcp` through PATH, and passes PATH through | **no** (rendered only) |
2943
2973
 
2944
2974
  The plugin checks also report the detected harness CLI version. An installed
2945
2975
  plugin whose version cannot be parsed is reported as `version unknown` and is
2946
2976
  not treated as a failure. A parsed plugin version that differs from the
2947
2977
  package version is reported as version skew with the remedy `run owenloop
2948
- setup`. A missing harness reports that the harness is not on `PATH`; a missing
2949
- plugin reports the harness-specific marketplace and install command.
2978
+ setup`. Doctor also reads each installed plugin's effective MCP declaration:
2979
+ an absolute or worktree command, alternate arguments, missing Codex PATH
2980
+ pass-through, or a missing executable `owenloop` on PATH is launch drift even
2981
+ when versions currently match. Missing or malformed launch metadata is rendered
2982
+ as explicitly unverifiable rather than guessed safe. Absolute marketplace,
2983
+ cache, install, and source paths are harness storage locations and are not by
2984
+ themselves launch drift. A missing harness reports that the harness is not on
2985
+ `PATH`; a missing plugin reports the harness-specific marketplace and install
2986
+ command. Unsafe declarations are summarized by command shape and argument
2987
+ count; doctor does not echo manifest values, which may contain credentials.
2988
+ `owenloop setup` repairs a known unsafe declaration through its existing
2989
+ non-fatal convergence flow.
2950
2990
 
2951
2991
  Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
2952
2992
  <origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
@@ -2977,8 +3017,11 @@ error telling you to run `owenloop login --hub <origin>` in a terminal and retry
2977
3017
  ### Plugin/CLI version alignment
2978
3018
 
2979
3019
  The shipped Claude Code and Codex plugins launch `owenloop mcp` from `PATH` and
2980
- carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`. The MCP
2981
- server compares that expected version with its own package version on every
3020
+ carry the plugin version in `.mcp.json` as `OWENLOOP_PLUGIN_VERSION`; Codex also
3021
+ explicitly passes `PATH` through to the subprocess. Doctor verifies that
3022
+ effective installed launch shape as well as version equality, so a same-version
3023
+ absolute or worktree launch declaration is reported as drift. The MCP server
3024
+ still compares that expected version with its own package version on every
2982
3025
  recognized `tools/call`. The comparison is strict equality: a mismatch returns
2983
3026
  a tool error that names both versions and says `Run: owenloop setup`. The
2984
3027
  server does not reject the MCP startup handshake, so the diagnostic reaches the
package/docs/design.md CHANGED
@@ -231,6 +231,13 @@ order-independent — re-running `settle()` on a healthy graph yields no ops.
231
231
  - **§11.8** — the forward cascade (above).
232
232
  - **§11.9** — the three reject kinds (above): judgment, validation (§19), structural.
233
233
 
234
+ A green seal is a normal artifact for authority purposes: a consumer of
235
+ `src[*]` may judgment-reject it. That reopens the collection producer, which
236
+ may emit additional members and seal again; `emit` only refuses while the seal
237
+ is currently green. A judgment-rejected bare member is different: its index is
238
+ not rebuilt, so an authorized consumer `retract`s it to remove it from the
239
+ surviving set. Retraction cascades to indexed map children.
240
+
234
241
  ## §12 Concurrency
235
242
 
236
243
  - **§12.1 versions** — each artifact carries a monotonic version; a green bumps it.
@@ -1043,6 +1050,14 @@ read-only context never grants member-retract authority. Applying it terminally
1043
1050
  retracts the member and lets the normal cascade retract its indexed map
1044
1051
  children, removing them from a reduce's surviving-member set.
1045
1052
 
1053
+ Retract transitions remain in the reachability graph, including when they are
1054
+ the only move that prevents a deadlock. They do not, by themselves, make a
1055
+ stalled debt an unrelated-branch `stuck` state: a retract-only state is
1056
+ authority recovery, and an indexed stalled debt clearable by an authorized
1057
+ member retract is recoverable rather than stranded. Ordinary worker progress
1058
+ on another branch can still report `stuck`; scalar parallel-workflow controls
1059
+ remain subject to that finding.
1060
+
1046
1061
  **Stall states vs true deadlocks.** A reachable, non-done state with zero
1047
1062
  available transitions is classified into exactly ONE of two mutually exclusive
1048
1063
  buckets, by recomputing eligibility with every freeze lifted and with an
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.13",
3
+ "version": "0.5.15",
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.13",
3
+ "version": "0.5.15",
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.13"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.15"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.13",
3
+ "version": "0.5.15",
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.13"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.15"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",