@sporhq/spor 0.25.0 → 0.26.1

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "spor",
   "displayName": "Spor Context Compiler",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spor",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
   "author": {
     "name": "Spor",

package/API.md

@@ -578,7 +578,7 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | Endpoint | Typical caller | Semantics |
 |---|---|---|
 | `GET /v1/status` | session-start, monitoring | `{node_count, projects: {...}, head, uptime, metrics}`; doubles as the health check. Graph counts/projects are the viewer-visible projection. `?titles=1` adds viewer-visible `titles: [{id, type, project, title}]` — the one-round-trip graph index the distiller dedups against |
-| `GET /v1/schema` | `spor schema`, agents introspecting the contract | the live schema registry as data (task-spor-schema-introspection-surface; server half task-spor-server-schema-endpoint): `{default_edge_weight, node_types: [{type, description, prefix, always_on, traversable, capturable, queueable, non_resolving, hooks, schema_id, schema_version, source}], edge_types: [{type, description, weight, weight_default, inverse_label, aliases, capturable, hooks, ...}], queue_policy, policies, registers, stale_overrides, alias_collisions}` — the seed pack MERGED with graph-resident `type: schema` overrides, each entry tagged by `source` (`seed`/`graph`/`native`) and the active schema node's id+version. `?code=1` embeds each hook's source under `code: {name: src}` (omitted by default to keep the response lean). The registry IS the contract (norm-cc-registry-is-contract); this read surface closes the failure mode of agents reverse-engineering it from `lib/seed/` files (which miss resident overrides). The REST/MCP twin of the `spor schema` CLI: all three render one `graph.registry.snapshot()` so they never drift |
+| `GET /v1/schema` | `spor schema`, agents introspecting the contract | the live schema registry as data (task-spor-schema-introspection-surface; server half task-spor-server-schema-endpoint): `{default_edge_weight, node_types: [{type, description, prefix, always_on, traversable, capturable, queueable, non_resolving, terminal, inert, inert_inherited, vocabulary, completion, resolver_required, hooks, schema_id, schema_version, source}], edge_types: [{type, description, weight, weight_default, inverse_label, aliases, capturable, hooks, ...}], queue_policy, policies, registers, stale_overrides, alias_collisions}` — the seed pack MERGED with graph-resident `type: schema` overrides, each entry tagged by `source` (`seed`/`graph`/`native`) and the active schema node's id+version. `?code=1` embeds each hook's source under `code: {name: src}` (omitted by default to keep the response lean). The registry IS the contract (norm-cc-registry-is-contract); this read surface closes the failure mode of agents reverse-engineering it from `lib/seed/` files (which miss resident overrides). `vocabulary`/`completion`/`resolver_required` are the declarative completion policy (task-spor-registry-declarative-terminal-status-policy): the closed status enum a type's `validate()` gates on, its single SUCCESS terminal value (`null` when the type's terminal values are several distinct outcomes rather than one success, i.e. no mechanical close exists), and whether that value also needs a live resolving decision/artifact. They DECLARE what the hooks enforce — a reader (the gardener's finding remedies) names the right terminal status from here instead of hand-mirroring hook source. The REST/MCP twin of the `spor schema` CLI: all three render one `graph.registry.snapshot()` so they never drift |
 | `GET /v1/me` | `spor whoami`/`status`, onboarding | identity echo for the bearer token → `{person, name, email, bound, is_admin, org}`. `bound:false` means the token authenticates but maps to **no person node** (legacy/OAuth, or minted before the node existed), so routed questions and the personal queue will be empty — the client warns on it (the silent identity-degradation signal). `is_admin` reflects the `stewards→root` edge that gates the token-admin surface. `org` is the slug this tenant routes to (`SPOR_ORG`/legacy `SUBSTRATE_ORG`, else `"local"`); it lets a client key its `(issuer, org)` credential store for an **opaque** `spor_oat_`/`spor_pat_` token that carries no readable `org` claim — the client falls back to it after `--org` and the JWT `org` claim (task-spor-frontdoor-me-org-echo). A connector JWT's `org` claim is enforced equal to this echo |
 | `GET /v1/me/org-choices` | `spor auth list` (live membership refresh) | re-queries the IdP's *current* org membership for the held credential's subject and returns `{org_choices: [{slug, label, default?}], source: "idp"\|"bound"}` — `source:"idp"` is a true live enumeration (orgs added/removed since the last login surface without re-authenticating); `source:"bound"` means a single org-scoped token the server couldn't expand (no enumeration). The client treats only `source:"idp"` as live and **fails open** to its cached tenant listing on anything else — `source:"bound"`, a `502 {error.code:"membership_requery_failed"}` (IdP unreachable), a `404` (older server without the endpoint), or any transport/parse error (task-spor-cli-auth-list-live-membership-requery; server half task-spor-frontdoor-held-credential-membership-requery) |
 | `GET /v1/me/tokens` | `spor token list` | list the caller's OWN personal access tokens → `{tokens: [{hash_prefix, person, label, name, email, created, expires, expired, last_used}], count}` — caller-scoped (only their person-bound PATs; agent session tokens excluded), never plaintext, never full hashes. `403 forbidden` if the bearer maps to **no person node** (you need a bound identity to own a PAT). The self-serve, no-admin twin of `GET /v1/admin/tokens` below (task-spor-app-me-tokens-self-serve) |
@@ -723,14 +723,21 @@ anything with a token.
   one place an agent token's session is set, write-once. The session can't be
   forged a-priori (it isn't known until the run exists) and can't ride the write
   payload (token-derived, §1), so the binding is always the actual run. A
-  **Codex**-harness dispatch follows the same late-bind contract from its own
-  supervisor process instead: it reads the session id off the `thread.started`
-  event in the run's supervised JSONL log rather than `claude agents --json`,
-  then binds it the same way. Token transport also differs per harness —
-  Claude Code gets a strict `--mcp-config` file, Codex gets the token via an
-  env var its own config references (`--config
-  mcp_servers.spor.bearer_token_env_var=SPOR_DISPATCH_MCP_TOKEN`) — but both
-  land at the same self-serve mint/bind pair above.
+  **supervised**-harness dispatch (Codex, OpenCode, GitHub Copilot CLI) follows
+  the same late-bind contract from its own supervisor process instead: it reads
+  the session id out of the run's supervised JSONL log rather than
+  `claude agents --json` — Codex off its `thread.started` event, OpenCode off
+  the `sessionID` every event carries, Copilot off the `sessionId` on its
+  terminal `result` event (so a Copilot run binds only at exit, still before its
+  record goes terminal) — then binds it the same way. Token transport also
+  differs per harness: Claude Code gets a strict `--mcp-config` file, Codex gets
+  the token via an env var its own config references (`--config
+  mcp_servers.spor.bearer_token_env_var=SPOR_DISPATCH_MCP_TOKEN`), and OpenCode
+  and Copilot — neither of which can be handed an MCP server on the command line
+  without publishing the bearer to argv — get the agent-scoped token as
+  `SPOR_TOKEN` in the run's environment, so the `spor` CLI inside the run is
+  agent-attributed with no injected MCP. All of them land at the same self-serve
+  mint/bind pair above.
 - **OAuth 2.1 for MCP connectors** (Cowork/claude.ai, which cannot carry a
   static bearer token): protected-resource metadata discovery (RFC 9728,
   advertised on the `/mcp` 401 via `WWW-Authenticate`), authorization-server

package/GRAPH.md

@@ -302,8 +302,8 @@ separately, but never shows a complete custom type in one piece.
 
 **The constraint model is procedural, not declarative.** A schema's `json`
 payload declares only *registry knobs* — `node_type`, `prefix`, `queueable`,
-`traversable`, `always_on`, `capturable`, an edge `weight`, and the three status
-partitions: `status.non_resolving` (resolver semantics — whether a node in this
+`traversable`, `always_on`, `capturable`, an edge `weight`, the completion
+policy (below), and the three status partitions: `status.non_resolving` (resolver semantics — whether a node in this
 status retires the targets it points at), `status.terminal` (own-lifecycle
 completion — the statuses in which a node of this type is *done*, unioned with the
 kernel's legacy set and read by work-analytics so a schema-only terminal status
@@ -314,8 +314,33 @@ issue-spor-analytics-completion-ignores-schema-terminal-status), and
 `terminal-status` register below; a schema that declares no `inert` set
 INHERITS its `terminal` set, so only a schema whose two sets genuinely differ
 declares it — the seed decision schema pins `settled` terminal but NOT inert,
-dec-spor-status-inert-third-partition). There is **no
-declarative field list and no status enum.** Custom fields are free-form: any flat frontmatter key the
+dec-spor-status-inert-third-partition).
+
+**The completion policy — declared for readers, still enforced by code**
+(task-spor-registry-declarative-terminal-status-policy). Three further `status`
+keys say, as registry data, what the hooks below enforce: `status.vocabulary`
+(the closed status enum the type's own `validate()` gates membership on),
+`status.completion` (the single SUCCESS terminal value — task `done`, issue
+`resolved`, question `answered` — as distinct from `status.terminal`, which is
+the full set *including* the give-up outcomes `abandoned`/`superseded`/
+`rejected`), and `status.resolver_required` (whether reaching that value also
+demands a live resolving `decision`/`artifact`, the completion-resolver
+invariant). **Declaring them gates nothing** — the hooks are still the only
+write door, and this is exactly why they are not a field list or an enforced
+enum. They exist so a READER can name the right terminal status without
+parsing hook source: the gardener's finding remedies used to keep hand-written
+tables of "task → done, everything else → resolved" and shipped remedies whose
+`set_status` the door then refused
+(issue-spor-gardener-terminal-status-fallback-off-vocab). A type whose terminal
+values are several distinct OUTCOMES rather than one success (decision
+settled/superseded/rejected, artifact merged/released/done, capture-pending
+merged/rejected) declares a `vocabulary` and NO `completion` — that absence is
+the machine-readable form of "there is no mechanical close here". Declaration
+and hook are pinned together by `test/seed-declarative-status-policy.test.js`,
+which drives every seed schema's hooks through the sandbox and fails if the two
+disagree; read the live values with `spor schema <type>`.
+
+Otherwise there is **no declarative field list and no status enum.** Custom fields are free-form: any flat frontmatter key the
 regex parser accepts (simple `key: value` scalars, YAML-folded multi-line
 values, `pin:`/`exclude:` inline lists, `- {type: X, to: Y}` edges — and nothing
 fancier) is carried verbatim on the node. What a field MUST contain, and which
@@ -400,6 +425,20 @@ warns). A schema node goes through the same propose→activate flow it governs
 bump the CalVer and add an `upgrades` chain only when the change is not
 backward-readable.
 
+Rollout-stage schemas the *product* ships ride the **candidate pack**
+(`lib/seed/candidates/`): full schema-node markdown that travels with the npm
+package but never enters the registry until a graph adopts it as a
+graph-resident node — `spor schema candidates` lists each candidate's adoption
+state, `spor schema adopt <id>` writes it through the validated node surface
+(`status: proposed`; `--activate` is the trusted-admin form for solo/local
+graphs), stamping `adopted_from`/`adopted_sha` provenance. Re-running adopt
+after a package upgrade is CalVer-aware and idempotent: a pristine older copy
+(canonical hash — `schema_version` + body — still matching its stamp) upgrades
+in place with its status preserved; a locally modified or unstamped resident
+refuses without `--force`. When a candidate stabilizes it is promoted into the
+seed pack at a release; the resident copy then shadows the seed (the
+stale-override warning above) and should be retired (`status: retired`).
+
 A complete worked example — a `escalation` type with a required `severity`
 field (enforced in `validate`) and an `open → mitigated → closed` status machine
 whose terminal `closed` demands a resolver (enforced in `transitions`):
@@ -1103,9 +1142,12 @@ program keeps rendering. The preference is all-or-nothing at a node — declare
 every member of an umbrella in one write, or the undeclared rest read as
 "blocking but outside the program" rather than silently dropping. It ships as
 a graph-resident schema node (`schema-edge-member-of-program`), not the seed
-pack, so it needs a *different* identity to activate it (the standing
-propose→activate flow above) before writes of this edge type validate; check
-`spor schema member-of-program` for its live status rather than assuming.
+pack — delivered as a packaged candidate (`spor schema adopt
+schema-edge-member-of-program` writes it into a graph that doesn't have it
+yet; see "Resolution and rollout" above) — so it needs activation (a
+*different* identity in team graphs; `--activate` in solo/local ones) before
+writes of this edge type validate; check `spor schema member-of-program` for
+its live status rather than assuming.
 `capturable: false` — the distiller and capture nudge never emit it; only a
 person or an agent working the program explicitly wires membership.
 

package/README.md

@@ -283,8 +283,9 @@ Terminal records age out after `dispatch.runRetentionMs` (default 14 days).
 ### Choosing a harness
 
 By default, `spor dispatch` launches a Claude Code agent (`claude --bg`). To
-dispatch under a different coding-agent CLI — Codex is also supported — resolve
-a **profile**: a node that bundles a harness, model, and toolset.
+dispatch under a different coding-agent CLI — Codex, OpenCode, and GitHub
+Copilot CLI are also supported — resolve a **profile**: a node that bundles a
+harness, model, and toolset.
 
 ```bash
 spor dispatch issue-86 --profile profile-codex-sol
@@ -312,23 +313,53 @@ its dispatches pick a harness without a flag every time; `--profile` on the
 command line always wins over that default.
 
 Before launching anything, dispatch checks whether **this machine** can
-actually run the resolved profile — is the `codex` CLI on PATH, are the right
-MCP servers reachable, and so on (see `spor capabilities`). If it can't,
+actually run the resolved profile — is the harness's CLI reachable, are the
+right MCP servers reachable, and so on (see `spor capabilities`). If it can't,
 dispatch refuses outright rather than silently falling back to Claude Code; in
 team mode it also names any other machine in the fleet that can run it.
 
 Codex-specific flags (`--sandbox`, `--approval-policy`) and Claude-specific
 ones (`--permission-mode`, `--agent`) are mutually exclusive — passing the
 wrong one for the resolved harness is a hard error, so a dispatch can't launch
-half-configured for the wrong CLI.
+half-configured for the wrong CLI. The one exception: `--permission-mode
+bypassPermissions` against a Codex profile has a real Codex equivalent
+("run fully unattended"), so instead of erroring it translates to `--sandbox
+danger-full-access --approval-policy never` (an explicit `--sandbox`/
+`--approval-policy` you also pass wins over that default) and prints a loud
+warning naming the translation — so an orchestrator or script that passes the
+same bypass flag to every dispatch regardless of harness keeps working.
+Every other permission-mode value still hard-errors against Codex.
+
+The harnesses do not all confine a run the same way. Codex dispatch defaults to
+`--sandbox workspace-write`, so its filesystem reach is bounded. OpenCode
+(`--auto`) and GitHub Copilot CLI (`--allow-all --no-ask-user`) have no
+equivalent — a dispatch under either runs with unrestricted tool access,
+because an unattended run has no human to answer a permission prompt. Dispatch
+those into a worktree or a checkout you are willing to have an agent change.
+
+**Naming a launcher explicitly.** A dispatched run does not inherit your
+interactive shell, so a CLI installed under a prefix that only an interactive
+shell sees (a common Homebrew setup) resolves when you check it by hand and
+resolves to nothing when Spor launches it. Point Spor at the binary directly
+rather than relying on `PATH`, in `~/.spor/config.json` — machine-specific, like
+`dispatch.repos`, so it never belongs in a committable `.spor.json`:
+
+```json
+{ "dispatch": { "bin": { "opencode": "/home/linuxbrew/.linuxbrew/bin/opencode" } } }
+```
+
+`SPOR_CLAUDE_CMD` / `SPOR_CODEX_CMD` / `SPOR_OPENCODE_CMD` / `SPOR_COPILOT_CMD`
+override the same thing per harness and win over the config file. An explicit
+launcher is used verbatim and is never quietly swapped for something on `PATH`;
+with none set, the bare name resolves on `PATH` as before.
 
 Claude Code dispatch detaches into Claude Code's own background-agent daemon —
 the launcher exits immediately, and `spor dispatch` can only reconcile what
-happened to it afterwards from the harness's own session transcript. Codex
-dispatch instead runs under a small supervisor Spor itself owns: it launches
-`codex exec` in the background, streams its progress into a private log, and
-captures the run's final message to a report file. At launch it prints where
-everything lives:
+happened to it afterwards from the harness's own session transcript. Every
+other harness instead runs under a small supervisor Spor itself owns: it
+launches the CLI's headless mode in the background, streams its progress into a
+private log, and captures the run's final message to a report file. At launch
+it prints where everything lives:
 
 ```text
 run:     3f9a2c1e-... (Codex supervisor running)
@@ -337,7 +368,7 @@ report:  ~/.spor/journal/dispatch/3f9a2c1e-....report.md
 session: 019f7a51-...
 ```
 
-`log` is the full JSONL progress stream; `report` is Codex's final message —
+`log` is the full JSONL progress stream; `report` is the run's final message —
 the thing to read for "what did it conclude". Both paths, plus the run's
 outcome, are also recorded durably and can be looked up later, same as any
 other dispatch: