owenloop 0.4.0 → 0.4.1

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/docs/cli.md CHANGED
@@ -21,10 +21,22 @@ every command, as above. `--help` on any command (or bare `-h`/`help`)
21
21
  prints this usage and exits 0 without doing any work.
22
22
 
23
23
  Boolean flags (`--force`, `--dry-run`, `--all`, `--open`, `--terminal`,
24
- `--recursive`, `--with-token`, `--shallow`, `--assume-provided`, and the bare
25
- `--now` on `reap`) never take a following value — the next token is always a
26
- positional or the next `--flag`, never consumed as this flag's argument. Use
27
- `--flag=value` (e.g. `--now=<ms>` on `tick`) for flags that do take a value.
24
+ `--recursive`, `--with-token`, `--shallow`, `--assume-provided`,
25
+ `--strict-inputs`, and the bare `--now` on `reap`) never take a following
26
+ value — the next token is always a positional or the next `--flag`, never
27
+ consumed as this flag's argument. Use `--flag=value` (e.g. `--now=<ms>` on
28
+ `tick`) for flags that do take a value.
29
+
30
+ `owenloop check <def>` defaults to treating `seedOwed` inputs as provided
31
+ (`assumeProvided: true`), so a def whose only initial gate is an unprovided
32
+ seeded input no longer reports a false depth-0 `True deadlocks` and doesn't
33
+ exit nonzero for it. `--strict-inputs` opts back out to the previous
34
+ seedOwed-starts-owed behavior, and when that's the def's only blocker also
35
+ prints a one-line hint naming the responsible input(s). `--assume-provided`
36
+ is still accepted (never errors) but is now redundant with the default; if
37
+ both flags are passed, `--strict-inputs` wins. See
38
+ [`docs/design.md` §25](design.md#25-the-model-checker-owenloop-check--scope)
39
+ for the full breakdown.
28
40
 
29
41
  ## Commands
30
42
 
@@ -37,6 +49,10 @@ positional or the next `--flag`, never consumed as this flag's argument. Use
37
49
  | `connect [--hub <url>] [--as <slot>]` | bind this project to a hub (writes `.owenloop/hub.json`) and verify the credential |
38
50
  | `push [<defName>...] [--force] [--dry-run] [--as <slot>]` | publish local workflow defs to the bound hub (idempotent against the hub's own def hashes) |
39
51
  | `logout [--hub <url>] [--as <slot>]` | delete the stored credential for a hub |
52
+ | `agent new <name> [--pools <a,b>] [--hub <url>]` | mint a new agent identity on the hub and store its token in slot `agent:<name>` — the token is never printed — see [Hub](#hub-login--connect--push--logout) |
53
+ | `setup [--hub <url>] [--new-agent <name> \| --replace-agent <name>] [--pools <a,b>]` | converge this machine's install (human login, agent credential, owenwork settings, plugin) in one idempotent pass — see [`setup`](#setup--converge-a-machines-install) |
54
+ | `doctor [--hub <url>]` | read-only check of this machine's owenloop install, one ✓/✗ line per piece — see [`doctor`](#doctor--check-a-machines-install) |
55
+ | `mcp [--hub <url>]` | serve the hub control plane to a local MCP host over stdio — spawned by MCP hosts, not run by humans — see [`mcp`](#mcp--stdio-control-plane-server-for-mcp-hosts) |
40
56
  | `create <def> [--title t] [--provide name=json …] [--param k=v …]` | start an instance; prints `{workflow}` |
41
57
  | `provide <wf> <name> [--value json]` | supply a seeded input after the fact |
42
58
  | `tick <wf> [--now=<ms>] [--shallow] [--label <l>]…` | claim and emit eligible **orders** (the jobs to run); deep by default — also descends into live `calls:` children (`--shallow` = this instance only); repeatable `--label` claims unlabeled steps plus matching-label steps — see below |
@@ -381,6 +397,29 @@ can read (only read) a stored credential through the same backend logic via the
381
397
  package's exported `readStoredCredential` — see
382
398
  [Embedding](embedding.md#whats-exported).
383
399
 
400
+ **Serializing writes (`credentials.lock`).** A store write — a refreshed OAuth
401
+ token, or a `login`/`logout` that stores or deletes a slot — is serialized by a
402
+ lockfile at `credentials.lock`, a sibling of `credentials.json` in the config
403
+ dir (created for the keychain backend too, since the race it closes is
404
+ backend-independent). The concern is a token-refresh race: two owenloop
405
+ processes hitting an expiring OAuth token at once would each POST a refresh and
406
+ each persist, and because refresh tokens rotate, the second write clobbers the
407
+ first with a token whose refresh link is already spent — silently killing the
408
+ credential. Under the lock a process re-reads the slot after acquiring it and,
409
+ if another process already refreshed, **adopts** that fresh token instead of
410
+ refreshing again — one network refresh, one write, no lost token. The lock
411
+ matters only for OAuth refresh and store/delete; read paths and the external-
412
+ command mode (which never writes the local store) do not take it. Staleness is
413
+ liveness-based: a lock held by a dead same-host process is reclaimed at once, an
414
+ unparseable or pid-less lockfile is reclaimed once older than the ~30s TTL, and
415
+ a lock held by a live process is never age-reclaimed. If the lock can't be
416
+ acquired within the wait budget the CLI fails loudly (`another owenloop process
417
+ is using the credential store … — timed out waiting after Ns`) rather than
418
+ refreshing unlocked. Three test knobs override the timings:
419
+ `OWENLOOP_CRED_LOCK_WAIT_MS` (default 45000), `OWENLOOP_CRED_LOCK_STALE_MS`
420
+ (default 30000), and `OWENLOOP_CRED_LOCK_POLL_MS` (default 100). No token value
421
+ ever appears in the lockfile or the timeout message.
422
+
384
423
  **Supplying the credential from your own tooling.** If your secrets live in a
385
424
  secret manager, or you run on a host with no keychain, set
386
425
  `OWENLOOP_CREDENTIAL_COMMAND` to a shell command line that prints a credential.
@@ -493,6 +532,300 @@ Exact-match redirect URIs (no RFC 8252 variable-port allowance) and no
493
532
  device-code grant remain recorded follow-ups on the service, not gaps in the
494
533
  CLI.
495
534
 
535
+ ### `agent new` — mint an agent token into a slot
536
+
537
+ `owenloop agent new <name>` mints a new agent identity on the hub (`POST
538
+ /api/mint_agent_token`, authenticated as your **human** credential) and stores
539
+ the returned `olp_` token in the local credential slot `agent:<name>` — the same
540
+ slot `login --as agent:<name>` writes and `push --as agent:<name>` reads. Use it
541
+ to provision an agent token without pasting one by hand: the mint and the store
542
+ happen in one step, and you never handle the secret.
543
+
544
+ **The token is never printed.** The minted `olp_` token goes process → store
545
+ only — it never appears on stdout, stderr, in an error, or in a log (identity
546
+ model §6, "rule of gates"). The confirmation JSON is built from a whitelist of
547
+ **non-secret** fields only: `hub`, `name`, `slot`, `pools` (the resolved pool
548
+ names), `scopes` (`["work"]`), `storage` (`keychain` | `file`), `agentId` (the
549
+ agent's id), and `tokenId` (a revocation handle). To use the agent afterwards,
550
+ pass `--as agent:<name>` to `connect`/`push`; to revoke it, use its `tokenId`
551
+ on the hub.
552
+
553
+ **Which hub gets minted on (`--hub`).** Resolution is deliberately narrow —
554
+ minting on the wrong org is not undone by a retry:
555
+
556
+ 1. `--hub <origin>` if given (normalized the same way as everywhere else).
557
+ 2. Otherwise the **one** hub your credential *file* stores — if exactly one is
558
+ present, it's used.
559
+ 3. Otherwise the command **exits 2** naming both remedies (pass `--hub`, or log
560
+ in to exactly one hub); when more than one hub is stored their origins are
561
+ listed back so you can pick.
562
+
563
+ Unlike other commands this does **not** fall back to `OWENLOOP_HUB` or the
564
+ built-in default hub — silently defaulting a mint would risk minting on the
565
+ production hub while you're logged into a dev one. Note that hub enumeration is
566
+ **file-store only** (shared with `owenloop mcp`): the keychain and the
567
+ external-command backend cannot list their entries, so on such a machine step 2
568
+ cannot enumerate the store and you must pass `--hub`.
569
+
570
+ **`--pools <a,b>`.** A comma-separated list of pool names the token is granted
571
+ on (trimmed, empties dropped). Omit the flag to let the hub default the token to
572
+ the minter's personal pool; `--pools ""` (or `--pools ,`) is a usage error. Pool
573
+ names are validated by the hub, not the client.
574
+
575
+ **A configured external credential command blocks the mint.** If
576
+ `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
577
+ supplies credentials for the hub, so `agent new` refuses up front (it has
578
+ nowhere to write the minted token); unset the variable to use the local store.
579
+ This check, the name validation, and the empty-`--pools` check all run **before**
580
+ any network call, so a refusal never mints a server-side token first — a mint
581
+ that then failed to store would burn the agent name permanently.
582
+
583
+ **Exit codes.**
584
+
585
+ | code | meaning |
586
+ |---|---|
587
+ | `0` | minted and stored |
588
+ | `1` | generic failure — invalid or already-taken name, pool/shape rejection, network timeout, or a token that minted but couldn't be stored |
589
+ | `2` | the hub couldn't be resolved (no `--hub` and not exactly one stored hub) |
590
+ | `3` | the human credential is missing or irrecoverable — the error names the remedy `owenloop login --hub <origin>` |
591
+
592
+ ## `setup` — converge a machine's install
593
+
594
+ `owenloop setup` is the one-shot onboarding command. It brings a machine to a
595
+ working install by converging six surfaces in order, each a **probe → (skip |
596
+ act)** step — a step acts only when its probe fails, so a second run on an
597
+ already-set-up machine performs **zero writes** (no store mutation, no settings
598
+ write, no browser, no mint/rekey/register POST). The steps:
599
+
600
+ 1. **inspect** — read-only report of what's already present (human credential,
601
+ owenwork settings, `claude` on PATH, agent slots). No writes.
602
+ 2. **human login** — verify the stored **human** credential, or run the same
603
+ loopback-OAuth browser flow as `owenloop login` when none is present or it no
604
+ longer verifies. This is the gate that makes step 3's mint/rekey legal.
605
+ 3. **agent** — find a local `agent:<name>` slot that verifies live against the
606
+ hub and reuse it; otherwise **mint** a new agent identity or **rekey**
607
+ (replace the credential of) an existing one. How the target is chosen is
608
+ [below](#choosing-the-agent-flow-a-vs-flow-b).
609
+ 4. **owenwork settings** — write `hubOrigin` into the owenwork settings file so
610
+ the local worker talks to this hub (skipped when it already matches).
611
+ 5. **plugin** — check whether the Claude Code `owenloop` plugin is installed.
612
+ **Non-fatal:** while the marketplace is unpublished this step only *prints*
613
+ the manual install commands (`claude plugin marketplace add owenloop` then
614
+ `claude plugin install owenloop@owenloop`); it never fails setup.
615
+ 6. **doctor** — a final [`doctor`](#doctor--check-a-machines-install) pass over
616
+ the same surfaces, whose result becomes setup's exit code.
617
+
618
+ Progress lines (the `[n/6]` headers and `✓`/`✗` marks) go to **stderr**; the
619
+ final machine-readable summary — `{ ok, hub, steps, doctor }` — goes to
620
+ **stdout**.
621
+
622
+ ### Choosing the agent (Flow A vs Flow B)
623
+
624
+ When step 3 has to act (no reusable local agent slot), it decides *which* agent
625
+ to connect this machine to:
626
+
627
+ - **Flow A — fresh org (no agent identities on the hub):** setup asks you to
628
+ **name** the agent, prefilled with a sanitized form of the machine hostname.
629
+ The name is a suggestion — any label matching `[A-Za-z0-9][A-Za-z0-9._-]*`
630
+ (1–64 chars) is accepted. It then **mints** that agent.
631
+ - **Flow B — org already has agents (succession):** setup shows the existing
632
+ agents (each with its name, when it was **last active**, and its **pools**)
633
+ and asks whether this is a *new* installation or one that *replaces* an
634
+ existing agent. Choosing **new** mints a fresh agent; choosing **replace**
635
+ **rekeys** the chosen agent — which **revokes that agent's current
636
+ credential**, so if it is still running elsewhere it will be disconnected
637
+ there.
638
+
639
+ **Non-interactive runs must pass a bypass flag.** When stdin is not a TTY (a
640
+ scripted or piped run) and step 3 needs to act, setup will not block on a
641
+ prompt — it errors unless you pre-decide with one of:
642
+
643
+ - `--new-agent <name>` — mint a new agent named `<name>` (skips Flow A's name
644
+ prompt and Flow B's succession prompt).
645
+ - `--replace-agent <name>` — rekey the existing agent named `<name>` (skips the
646
+ succession prompt); errors if no such agent exists on the hub.
647
+
648
+ The two flags are mutually exclusive. `--pools <a,b>` applies **only** to a mint
649
+ (`--new-agent` or a fresh org); combining it with `--replace-agent` is a usage
650
+ error, because rekeying preserves the agent's existing pools (manage those in
651
+ the console).
652
+
653
+ ### Hub resolution differs from `agent new`
654
+
655
+ `setup` (and `doctor`) resolve the target hub like `agent new` with **one**
656
+ deliberate difference: a brand-new machine with **no** stored hub falls back to
657
+ the built-in **default hub** (printing a `targeting <hub>` notice to stderr)
658
+ instead of exiting 2. That is safe here because the mint happens only *after*
659
+ you sign in through that hub's own browser consent, and the target is printed
660
+ first. Resolution order:
661
+
662
+ 1. `--hub <origin>` if given.
663
+ 2. Otherwise the **one** hub your credential *file* stores, if exactly one is
664
+ present.
665
+ 3. More than one stored hub → **exit 2**, listing them so you can pass `--hub`.
666
+ 4. Zero stored hubs (or a keychain/external backend that can't enumerate) →
667
+ the **default hub**, with a printed notice.
668
+
669
+ ### A configured external credential command blocks setup
670
+
671
+ If `OWENLOOP_CREDENTIAL_COMMAND` is set, that command — not the local store —
672
+ supplies this hub's credentials, so setup **refuses up front**, *before any
673
+ browser opens*. Its human-login and agent-mint steps would write keys nobody
674
+ reads; unset the variable to use `owenloop login` and the local store. (This is
675
+ the same guard `agent new` applies, just moved ahead of the OAuth round-trip so
676
+ the flagship command never opens a browser only to fail at the store.)
677
+
678
+ ### After setup
679
+
680
+ If the connected agent account is anything other than `default`, setup prints a
681
+ reminder to run owenwork with `OWENWORK_ACCOUNT=<name>` so the worker reads the
682
+ right slot.
683
+
684
+ **Exit codes.**
685
+
686
+ | code | meaning |
687
+ |---|---|
688
+ | `0` | every step ended skipped/done/noted **and** doctor's core checks (1–5) passed |
689
+ | `1` | setup ran but doctor's core checks did not all pass |
690
+ | non-zero (thrown) | a hard failure — bad flags, unresolvable hub (2), 403 from the hub (setup needs an admin credential to manage agents), a named `--replace-agent` that doesn't exist, or a configured external credential command |
691
+
692
+ ## `doctor` — check a machine's install
693
+
694
+ `owenloop doctor` is the **read-only** diagnostic behind setup's final step. It
695
+ probes the same install surfaces and prints one `✓`/`✗` line per check to
696
+ stderr, plus a `{ ok, hub, checks }` summary to stdout. It performs **no
697
+ configuration writes** — no mint, rekey, slot create/delete, settings write, or
698
+ browser. (The one unavoidable carve-out: verifying the human credential may
699
+ rotate-and-persist an *expiring* human OAuth token, exactly as every authed
700
+ command does — refreshing without persisting would strand the rotated refresh
701
+ token and corrupt the install.)
702
+
703
+ The checks, in order:
704
+
705
+ | # | check | ✓ means | core |
706
+ |---|---|---|---|
707
+ | 1 | human credential | a human credential is stored for this hub | yes |
708
+ | 2 | human plane | that credential verifies live against the hub (`whoami`) | yes |
709
+ | 3 | agent slot | an `agent:<name>` credential is stored | yes |
710
+ | 4 | agent plane | that agent credential verifies live against the hub | yes |
711
+ | 5 | owenwork settings | the settings file's `hubOrigin` matches this hub | yes |
712
+ | 6 | plugin | the Claude Code `owenloop` plugin is installed | **no** (rendered only) |
713
+
714
+ Each `✗` line names its own remedy (`run owenloop setup`, `owenloop login --hub
715
+ <origin>`, re-run setup's Replace, and so on). doctor never short-circuits — a
716
+ machine with no working human credential still renders lines 3–6, degrading
717
+ honestly rather than dropping them.
718
+
719
+ **Exit code.** `0` when the **core** checks (1–5) all pass, `1` otherwise. The
720
+ plugin check (6) is *rendered* but does not affect the exit code while the
721
+ marketplace is unpublished.
722
+
723
+ ## `mcp` — stdio control-plane server for MCP hosts
724
+
725
+ `owenloop mcp` is a long-running server that exposes the hub's **human control
726
+ plane** to a local MCP host (Claude Code, or any client that speaks MCP over
727
+ stdio). This is the `owenloop-cli-mcp` surface: an MCP host spawns it as a
728
+ subprocess — **you do not run it yourself at a prompt**. It reads
729
+ newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
730
+ authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
731
+ JSON-RPC reply on stdout. It runs until stdin closes (EOF), then exits `0`.
732
+
733
+ It authenticates as the logged-in **human**, using the same stored credential
734
+ `login` writes and the same locked OAuth-refresh path the other hub commands
735
+ use. It is never interactive: it never opens a browser and never starts a
736
+ loopback listener. If no human credential is stored, a tool call returns an
737
+ error telling you to run `owenloop login --hub <origin>` in a terminal and retry
738
+ (see [Authentication and secrets](#authentication-and-secrets) below).
739
+
740
+ ### Choosing the hub origin
741
+
742
+ `owenloop mcp` binds to exactly one hub origin, resolved in this order:
743
+
744
+ 1. `--hub <url>` flag.
745
+ 2. `OWENLOOP_HUB` env var.
746
+ 3. If the **file** credential backend holds exactly ONE hub with a valid `human`
747
+ credential, that hub is used.
748
+ 4. Otherwise it exits `2` and prints why to stderr (nothing is written to
749
+ stdout — stdout is the protocol channel).
750
+
751
+ There is **no** silent default-hub fallback: a control-plane server must never
752
+ bind to a hub you did not name. The exit-`2` messages name both remedies:
753
+
754
+ - No hub credentials stored → `run \`owenloop login --hub <origin>\` first, or pass --hub <origin>`.
755
+ - More than one hub stored → the message lists every stored origin and says `pass --hub <origin>`.
756
+ - The credential store cannot be enumerated (macOS Keychain or an external
757
+ credential command) → `pass --hub <origin> (or set OWENLOOP_HUB)`. Only the
758
+ file backend can list stored origins, so on a Keychain-backed machine `mcp`
759
+ effectively requires `--hub` or `OWENLOOP_HUB`.
760
+
761
+ A malformed `--hub`/`OWENLOOP_HUB` value is a normal exit-`1` error, like every
762
+ other command.
763
+
764
+ ### Tools
765
+
766
+ The server exposes 17 baseline tools mirroring the hub's own MCP toolset, plus
767
+ `create_agent`. Each baseline tool's result is the hub REST response as one text
768
+ block; a non-2xx response comes back as an error result.
769
+
770
+ | tool | what it does |
771
+ |---|---|
772
+ | `whats_next` | tick a workflow and get the next work order(s), or the inbox of started instances |
773
+ | `submit` | submit a work order output |
774
+ | `reject_artifact` | send an upstream artifact back to its producer with a reason |
775
+ | `provide_input` | answer a human gate — provide a value for a seeded/owed input |
776
+ | `start_run` | create a new instance from a definition name |
777
+ | `create_workflow` | parse + load a workflow def YAML (the authoring hard gate) |
778
+ | `get_workflow` | fetch one loaded definition |
779
+ | `list_workflows` | names, titles, step counts, and def hash/version of every loaded def |
780
+ | `get_status` | `engine.status` verbatim plus a plain-English rendering |
781
+ | `heartbeat` | touch the liveness timestamp on an open run so it is not reaped mid-step |
782
+ | `get_order` | re-fetch the persisted order packet and lease state for a run you hold |
783
+ | `release` | give back a claim so its order is re-offered without waiting out the reap TTL |
784
+ | `publish_event` | publish an event against a contract, starting one run per matched subscription |
785
+ | `list_subscriptions` | the org's contract subscriptions |
786
+ | `presence_ping` | register/refresh this conductor in the presence registry |
787
+ | `list_conductors` | your principal's registered conductors and their online/offline state |
788
+ | `wake` | cheap "has anything changed since cursor X" pre-check for a polling loop |
789
+ | `create_agent` | create a NEW agent identity and store its credential locally — **never returns the token** |
790
+
791
+ `create_agent {name, pools?}` mints a fresh agent identity on the hub with
792
+ `work` scope, then writes the minted `olp_` token straight to this machine's
793
+ credential store (slot `agent:<name>`). The token is **never** returned in the
794
+ tool result, printed, or logged — the result is `{name, pools, stored: true}`,
795
+ built from scratch. It refuses a name that is already taken (the hub's error
796
+ message is surfaced verbatim; error bodies never carry tokens). If the store
797
+ write fails, the result says so and tells you to revoke/re-key the agent from
798
+ the console.
799
+
800
+ One further tool, `stage_enrollment`, is **conditionally** registered — it
801
+ appears only when the hub advertises the staging endpoint (or when
802
+ `OWENLOOP_MCP_ENROLLMENT=1` forces it on). It returns a join code the new agent
803
+ redeems; a join code is transferred authority, not a credential, so it is safe
804
+ to surface in a tool result. When the endpoint is absent, the tool is hidden
805
+ (fail-closed).
806
+
807
+ ### Authentication and secrets
808
+
809
+ Every tool call re-reads the stored `human` credential, refreshes it through the
810
+ shared locked OAuth path if it is near expiry, and attaches it only as the
811
+ `Authorization` header — the bearer never rides a tool result. Minted agent
812
+ tokens (`create_agent`) are written to the local credential store and **never
813
+ appear in any tool result, stderr line, or log**. If authentication fails
814
+ (missing credential, refresh failure, or a final 401), the tool returns an error
815
+ result whose text names the fix — run `owenloop login --hub <origin>` in a
816
+ terminal — rather than prompting; the server itself never authenticates
817
+ interactively.
818
+
819
+ ### Environment knobs
820
+
821
+ | variable | effect |
822
+ |---|---|
823
+ | `OWENLOOP_HUB` | hub origin when `--hub` is absent (rung 2 of origin resolution) |
824
+ | `OWENLOOP_MCP_ENROLLMENT` | `1` forces `stage_enrollment` on, `0` off; unset = probe the hub |
825
+ | `OWENLOOP_MCP_PROBE_TIMEOUT_MS` | deadline for the `stage_enrollment` capability probe (default `3000`) |
826
+ | `OWENLOOP_HUB_TIMEOUT_MS` | per-request hub timeout (shared with the other hub commands) |
827
+ | `OWENLOOP_CRED_LOCK_WAIT_MS` / `OWENLOOP_CRED_LOCK_POLL_MS` | credential-lock wait/poll knobs (shared) |
828
+
496
829
  ## Hand-driven walkthrough
497
830
 
498
831
  The [`examples/workflows`](../examples/workflows) folder has a workflow per
package/docs/design.md CHANGED
@@ -933,10 +933,71 @@ agents:**
933
933
  ## §25 The model checker (`owenloop check`) — scope
934
934
 
935
935
  `owenloop check <def>` (see `cli.ts` usage) runs a bounded reachability
936
- search over `applyOutcome` transitions in `model.ts`, looking for
937
- deadlocks, stuck artifacts, dead steps, and violations of any declared
938
- invariants. It is a static analysis of a workflow definition's shape, not a
939
- simulation of a running instance.
936
+ search over `applyOutcome` transitions in `model.ts`, looking for stall
937
+ states, true deadlocks, stuck artifacts, dead steps, and violations of any
938
+ declared invariants. It is a static analysis of a workflow definition's
939
+ shape, not a simulation of a running instance.
940
+
941
+ **Stall states vs true deadlocks.** A reachable, non-done state with zero
942
+ eligible firings is classified into exactly ONE of two mutually exclusive
943
+ buckets, by recomputing eligibility as if every freeze were lifted
944
+ (`eligibleFirings(def, arts, undefined, { ignoreFreeze: true })` — "unlimited
945
+ attempts," i.e. what a human `retry` grants):
946
+ - **stall state** (`report.stallStates`) — the recompute yields >= 1 firing:
947
+ the state's ONLY blocker is a frozen/stalled debt — `maxAttempts` reached
948
+ (`isStalled`, §6), `maxSchemaFailures` reached (`isSchemaStalled`, §6/§18),
949
+ or held (`isHeld`, §20). Lifting the freeze re-arms a producer, so the
950
+ line COULD move. This is a by-design human-escalation brake — EXPECTED,
951
+ never a defect, and it never affects the exit code.
952
+ - **true deadlock** (`report.deadlocks`) — the recompute STILL yields zero
953
+ firings: no producer would re-arm even at unlimited attempts. A genuine
954
+ structural dead-end (e.g. a `group:`-blocked or ungreen-input state, or an
955
+ owed input with no producer). This is folded into `hasDefiniteDefect` and
956
+ makes `check` exit nonzero — but only when the search was exhaustive
957
+ (`!report.bounded`), since a tight `--max-collection`/`--max-states` cap
958
+ can otherwise manufacture a spurious no-moves state.
959
+
960
+ The freeze-lift recompute ONLY lifts the `frozen()` guard — it does not
961
+ bypass group-exclusivity (`groupBlockingWinner`), input-green gates, or
962
+ `isDebt`. A state blocked by a group winner or an ungreen input classifies as
963
+ a true deadlock, not a stall state, even if some artifact elsewhere also
964
+ happens to be frozen.
965
+
966
+ Separately, `report.stuck` records reachable states that have a stalled
967
+ debt (`maxAttempts`/`maxSchemaFailures`/held) BUT still have >= 1 eligible
968
+ firing — a brake tripped on one branch while the line can still move on
969
+ another. This is informational only, never a defect on its own, and a
970
+ no-moves state is never listed here (it lands in `stallStates` or
971
+ `deadlocks` instead) — so no single state is ever double-listed across
972
+ `stuck`, `stallStates`, and `deadlocks`.
973
+
974
+ Dead steps — a step name that never appears as a firing in any explored
975
+ transition — are split into two categories with different severity, via a
976
+ static `canEverFire(step, def)` check (`model.ts`) that needs no search
977
+ bounds at all:
978
+ - **structurally dead** (`report.structurallyDeadSteps`) — `canEverFire` is
979
+ false: the step can NEVER fire, regardless of `--max-depth`/
980
+ `--max-states`. This is a genuine wiring defect (e.g. a reduce-mode step
981
+ with no singleton produce to discharge). It is always a *definite*
982
+ finding — bounds-independent by construction — so it is folded into
983
+ `hasDefiniteDefect` and makes `check` exit nonzero, the same way an
984
+ invariant violation does.
985
+ - **unreached within bounds** (`report.unreachedSteps`) — `canEverFire` is
986
+ true: the step CAN fire in principle, but the bounded search didn't reach
987
+ it before exhausting `--max-states`/`--max-depth`. This is informational
988
+ only, a bounds artifact — it does NOT affect the exit code. Raising the
989
+ search bounds may surface the step firing.
990
+
991
+ `canEverFire` is a sound detector of deadness: it only reports a step as
992
+ structurally dead when certain no firing can ever be pushed for it (mirrors
993
+ `eligibleFirings`'s discharge-set logic per step mode); when uncertain it
994
+ defaults to "can fire," so a step is never wrongly flagged as a wiring
995
+ defect. Most structurally-dead shapes are already caught earlier as hard
996
+ errors by `validateDef` (which `check` runs first and throws on) — the
997
+ residual case `canEverFire` exists to catch is a reduce-mode step whose
998
+ `produces:` has zero singleton entries (and no collection produce either,
999
+ so `validateDef`'s reduce check doesn't trip), which reaches `modelCheck`
1000
+ silently dead.
940
1001
 
941
1002
  Two things it deliberately does not model, and why: **born-rejected
942
1003
  commits** — a stale-CAS refusal (§12.2, §24.4) is a refusal, not a state
@@ -950,14 +1011,27 @@ either of these — it answers "is this graph structurally sound," not "can a
950
1011
  human or a stale commit route around a stall." See README's Testing section
951
1012
  for how `owenloop check` fits alongside the test suite.
952
1013
 
953
- The checker also has no runtime `provide` values, so by default a
954
- `seedOwed: true` input starts owed with no transition that can green it —
955
- reported as a false depth-0 deadlock for a def whose inputs the operator
956
- always supplies via `provide` at `create` time. Pass `--assume-provided`
957
- (`assumeProvided` in `CheckOptions` when calling `modelCheck` directly) to
958
- seed those inputs green instead, modeling "the operator already ran
959
- `provide`." It only affects the initial seed — a genuine deadlock reachable
960
- past the inputs is still reported.
1014
+ The checker also has no runtime `provide` values, so a `seedOwed: true`
1015
+ input has no transition that can green it on its own — without seeding it
1016
+ green some other way, it starts owed and can manufacture a false depth-0
1017
+ deadlock for a def whose inputs the operator always supplies via `provide`
1018
+ at `create` time. `CheckOptions.assumeProvided` (library level, when calling
1019
+ `modelCheck` directly) controls this and **defaults to `false`** — that
1020
+ library default is unchanged by the CLI change below, and is what the
1021
+ `modelCheck` unit tests calling it directly still rely on.
1022
+
1023
+ `owenloop check` (the CLI command), however, now defaults to
1024
+ `assumeProvided: true` — seedOwed inputs are seeded green by default,
1025
+ modeling "the operator already ran `provide` at `create`." This dissolves
1026
+ the false depth-0 deadlock for the common case without the flag. Pass
1027
+ `--strict-inputs` to opt back out to the seedOwed-starts-owed behavior; when
1028
+ that's the *sole* reason for an initial-state deadlock, `owenloop check`
1029
+ also prints a one-line hint naming the responsible seedOwed input(s) and
1030
+ pointing at re-running without `--strict-inputs`. `--assume-provided` is
1031
+ still accepted (never errors) but is now redundant with the default; if both
1032
+ `--strict-inputs` and `--assume-provided` are passed, `--strict-inputs` wins.
1033
+ In all cases, seeding only affects the initial seed — a genuine deadlock
1034
+ reachable past the inputs is still reported.
961
1035
 
962
1036
  ## §26 Declarative exclusive produce-groups (`group:`)
963
1037
 
package/docs/embedding.md CHANGED
@@ -262,9 +262,10 @@ all the shared types (`Order`, `CommitResult`, `WorkflowStatus`, `WorkflowDef`,
262
262
  `EngineEvent`, `EngineListener`, …). For most hosts, `createEngine` + the engine methods + the `Order` /
263
263
  `CommitResult` / `WorkflowStatus` types are the whole surface you need.
264
264
 
265
- The index also exports a **read-only credential surface** for hosts that need
266
- to read a stored hub credential through owenloop's own store logic instead of
267
- duplicating it: `readStoredCredential(origin, opts)` returns the `Credential`
265
+ The index also exports a **credential surface** for hosts that need to read,
266
+ write, or refresh a stored hub credential through owenloop's own store logic
267
+ instead of duplicating it. The read entry is `readStoredCredential(origin, opts)`,
268
+ which returns the `Credential`
268
269
  for a hub origin **and slot** (or `null` if none is stored), using the same
269
270
  backend selection as the CLI — macOS Keychain, or the `0600` credentials file
270
271
  elsewhere / with `OWENLOOP_NO_KEYCHAIN=1` (see
@@ -284,8 +285,31 @@ an invalid account name) and `keychainServiceFor` (normalized origin → the
284
285
  keychain service name) let a host address the same slots the CLI does without
285
286
  re-deriving the keying. Slots never fall back to one another: an empty
286
287
  `agent:ci` reads as `null` even when `human` is populated. The function never
287
- logs or echoes the secret, and there is deliberately no write or delete companion on the public
288
- surface — `login`/`logout` remain the only way to store or remove a credential.
288
+ logs or echoes the secret.
289
+
290
+ The write entries let a host store or refresh a credential the same way the CLI
291
+ does, addressing the same slots. All three are **async** and take a `CredentialIO`
292
+ (`{ env, keychain?, fetch? }` — a strict subset of the CLI's own io, so the CLI
293
+ passes its `io` unchanged):
294
+
295
+ - `storeCredential(io, origin, slot, credential)` — writes a credential into a
296
+ slot, merging with the other slots on the same origin (the file backend keeps
297
+ `human` when you write `agent:ci`).
298
+ - `deleteCredential(io, origin, slot)` — removes one slot.
299
+ - `ensureFreshOAuth(io, origin, slot, credential)` — returns the credential if
300
+ it is still fresh (more than 60s from expiry), otherwise refreshes the OAuth
301
+ token over the network and persists the rotated result, returning it.
302
+
303
+ `storeCredential`, `deleteCredential`, and the persist inside `ensureFreshOAuth`
304
+ serialize through the `credentials.lock` file described in
305
+ [where the credential lands](cli.md#hub-login--connect--push--logout): a
306
+ concurrent refresh adopts a token another process already rotated rather than
307
+ double-refreshing and clobbering it. When `OWENLOOP_CREDENTIAL_COMMAND` is set,
308
+ that command owns the credential lifecycle — `storeCredential`/`deleteCredential`
309
+ refuse to write, and `ensureFreshOAuth` refreshes over the network without
310
+ persisting. `login`/`logout` are still the CLI's way to store or remove a
311
+ credential; these exports are the programmatic equivalent for a host embedding
312
+ the engine.
289
313
 
290
314
  One behaviour to handle: when the user has set `OWENLOOP_CREDENTIAL_COMMAND` (an
291
315
  external command that supplies the credential, ahead of both stores — see
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
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",