@sporhq/spor 0.23.0 → 0.24.0

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.23.0",
+  "version": "0.24.0",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spor",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "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

@@ -526,9 +526,21 @@ own. **MCP-only — no REST twin.**
 Plain HTTPS + JSON, bearer auth on every route, versioned under `/v1/`. Each
 endpoint is the REST twin of a core call:
 
+All graph-derived reads are viewer-scoped by the server's graph-native FGA
+closure (`task-spor-graph-native-fga-read-visibility-filter`). Visibility comes
+from graph relations—area stewardship/membership, direct assignment/routing/
+review, authorship/initiator/asker, and agent ownership—not project claims or an
+admin bit copied into the token. `stewards -> org-root` is the graph-wide read
+relation. Hidden direct ids deliberately use the ordinary `404 not_found` shape;
+list/search/queue/digest/lens/MCP surfaces omit them before ranking or rendering.
+An edge whose target is invisible is absent from adjacency, returned
+frontmatter, raw node markdown, history text, and node exports, so it cannot act
+as an id/title/body oracle. An authenticated token with no resolvable person or
+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. `?titles=1` adds `titles: [{id, type, project, title}]` — the one-round-trip graph index the distiller dedups against |
+| `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/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) |
@@ -537,7 +549,7 @@ endpoint is the REST twin of a core call:
 | `DELETE /v1/me/tokens/{hash-prefix}` | `spor token revoke` | revoke one of the caller's OWN PATs by hash prefix → `{revoked, hash_prefix, oauth_grants_revoked}`; a prefix that isn't one of the caller's is `404` (never another person's token). `403` if unbound. Shares the admin revoke's OAuth-grant cascade-completeness invariant (issue-cc-pat-revoke-cascades-all-oauth-grants) |
 | `GET /v1/briefing/{project}` | session-start | read the `brief-<project>` node → `{found, version, body, project_brief?, graph_status}`. The slug resolves through project-node aliases (GRAPH.md "Project identity nodes") before lookup. A BARE repo slug also rides up to its home-project grouping: the grouping's `brief-<grouping>` node returns alongside as `project_brief` (the product context spanning sibling repos), matching the shared up-resolution (dec-spor-queue-slug-resolves-to-grouping); passing the repo NODE id (`repo-<slug>`) is the escape hatch that returns only the repo brief, no `project_brief`. Optional `?fp=root:<sha>,remote:<host/path>,...` carries the repo's fingerprints: the server learns them onto the owning project node, and an unknown slug with a known fingerprint files an alias proposal in the queue |
 | `POST /v1/digest` `{query, root?, project?, min_sim?}` | prompt-context, /spor:brief | digest-mode compile → `{found, text}`; `found: false` is a successful empty result. `root` is the structural-walk twin of `query` (the two are mutually exclusive; `root` wins, an unknown id is `422`). Optional `project` is the session slug: the server scopes the compile to it — the same-project relevance boost, the grouping union, and the `always_on` norm `applies_to_*` ride-along — resolving the slug through project-node aliases/groupings inside compile (dec-spor-queue-slug-resolves-to-grouping), exactly as `/v1/queue` does. A bad slug is `422`; **omitting `project` runs the digest project-blind (byte-identical to before)**, so older clients that send only `{query}` are unaffected |
-| `GET /v1/nodes/{id}` | /spor:brief | `get_node` semantics; the node's active schema may attach read-time enrichment via a `get(node, ctx)` hook (GRAPH.md) — the seed `question`/`issue`/`task`/`incident` schemas attach `resolution`: a live inbound resolves/answers edge carrying the resolver's `summary`/`title` and a `lagging` flag (set when it contradicts a still-open status, clear when the node is already terminal, e.g. an answered question pointing at its answer). Open gardener findings about the node ride along as `open_findings`, and a node marked stale by an inbound supersedes edge as `superseded_by`. All enrichment is additive top-level keys; ignore unknown ones. Reserved: a top-level `inert` boolean — this node's status evaluated against the FULL type-aware queue-liveness-dead partition, including graph-resident schema overrides a graph-less client can't see (issue-spor-type-blind-terminal-status-fallbacks). The graph-less client callers that need it (`bin/spor.js` `dispatchResolutionReason`, `distill.js` `sessionEndLease`) already read it opportunistically when present and fall back to an offline seed-registry check otherwise, but no server response emits the key yet — implementing it server-side is separate, tracked work |
+| `GET /v1/nodes/{id}` | /spor:brief | `get_node` semantics; hidden and absent ids both return `404 not_found`. The node's active schema may attach read-time enrichment via a `get(node, ctx)` hook (GRAPH.md) — the seed `question`/`issue`/`task`/`incident` schemas attach `resolution`: a live **visible** inbound resolves/answers edge carrying the resolver's `summary`/`title` and a `lagging` flag (set when it contradicts a still-open status, clear when the node is already terminal, e.g. an answered question pointing at its answer). Open visible gardener findings about the node ride along as `open_findings`, and a node marked stale by a visible inbound supersedes edge as `superseded_by`. Returned `raw`/`frontmatter.edges` redact invisible edge targets. All enrichment is additive top-level keys; ignore unknown ones. Reserved: a top-level `inert` boolean — this node's status evaluated against the FULL type-aware queue-liveness-dead partition, including graph-resident schema overrides a graph-less client can't see (issue-spor-type-blind-terminal-status-fallbacks). The graph-less client callers that need it (`bin/spor.js` `dispatchResolutionReason`, `distill.js` `sessionEndLease`) already read it opportunistically when present and fall back to an offline seed-registry check otherwise, but no server response emits the key yet — implementing it server-side is separate, tracked work |
 | `GET /v1/nodes/{id}/history?limit=N` | `spor history <id>`, the `node_history` MCP tool | per-node commit lineage — a `git log` projection over `nodes/{id}.md` → `{id, head, count, history: [{sha, short, actor, actor_name, actor_email, date, message, internal, person}]}`, newest first. Each revision is labeled `internal:true` for a server-internal write (boot reconcile / migration, `server@spor.invalid`) vs. a real actor, and mapped to its `person` node by author email. Deliberately NOT `git log --follow` (node files share heavy frontmatter boilerplate, so similarity-based rename detection crosses node boundaries — dec-spor-node-history-git-log-projection). `limit` defaults to 50, max 200. The frontmatter `author` re-stamps to the LAST editor on every write, so this is the only durable record of the full chain of editors. A node with no commit history (unknown id) is `404`; a bad id is `422`. The `spor history <id>` CLI verb is the shell front-door (remote reads this; local mode runs the same projection over the graph home) |
 | `GET /v1/nodes/{id}/history/{sha}` | `spor history <id> <sha>`, `node_history` (sha mode) | one revision's detail, the expensive half gated behind an explicit per-sha fetch → the history record for that commit plus `{change, patch, content}`: the change type (`A`/`M`/`D`/`R`), the patch this commit introduced to the node file, and the full node content at that revision (`null` when the commit deleted it). The `sha` must be one from the node's own history — a sha that didn't touch the node, or an unresolvable sha, is `404`; a malformed sha is `422` |
 | `POST /v1/nodes` | `spor put-node`, drain-outbox, mechanical writers | `put_node` semantics, batch: `{nodes: [...], if_exists: "skip"}` (entries may be raw strings or `{node, if_exists, revision}`) → `{results: [...]}`, 207 when any entry failed. Entries are applied **sequentially** and each is fully validated before the next — including the completion-resolver gate that runs on create (GRAPH.md "the resolver gate") — so a born-terminal node (`done` task / `resolved` issue) must have its resolving `decision`/`artifact` EARLIER in the same batch (**resolver-first ordering**; the batch does not defer the gate to end-of-batch, dec-spor-batch-create-gate-resolver-first-ordering). The 207 is partial-success: entries already applied before a later entry's failure are not rolled back |
@@ -566,7 +578,7 @@ endpoint is the REST twin of a core call:
 | `GET /v1/lens/{id}/render?format=html\|text\|json` | browsers, teammates without a checkout | run a lens OR workspace node and render its view tree (html default, plain text, or the raw tree as json). Read-only — no action forms; writes stay with `/v1/nodes` and the MCP tools. Auth is the caller's bearer header OR a signed read-only **render ticket** for shared links (browser links can't carry an Authorization header): `?ticket=<blob>` is accepted once and exchanged via a 302 for an HttpOnly `spor_render_ticket` cookie (kept out of URLs, logs, and view-to-view hrefs). The ticket binds `$viewer` to the recorded sharer and the render shows a "Viewing as &lt;sharer&gt;" banner. The former `?token=<PAT>` sharing path is **removed** — a shared link can never carry a write-capable credential |
 | `POST /v1/lens/{id}/ticket` `{expires?}` | sharing a view; `spor share` | mint a signed, expiring, read-only render ticket for the lens/workspace, recording the authenticated caller as the sharer → `{ticket, url, lens_id, sharer_person_id, exp}`. `expires` is `<N>d` or an ISO date (default `7d`, max `30d`); the caller must be bound to a person node (else `422 no_person`). The ticket carries no write scope and is honored only on the render route (directly, or via the app host's ticket exchange below). The minted `url` depends on host role: an MCP-only host (`SPOR_HOST_ROLE=mcp`) with `SPOR_APP_URL` set mints an **absolute** `${SPOR_APP_URL}/views/{id}?ticket=...` — the app host's own render page, since the MCP host itself 404s on HTML renders; unset, it falls back to today's relative shape; every other role keeps its existing `oauth.baseUrl(request.raw)`-based absolute `/v1/lens/{id}/render?ticket=...`. On the app host, `GET /views/{id}` accepts that `?ticket=` exactly once: it is exchanged via a 302 into an HttpOnly `spor_render_ticket` cookie (stripped from the URL, kept out of logs and view-to-view hrefs) and replayed to api as the credential on the render fetch — but a **live app-host session outranks the ticket**: if the visitor is already signed in, their own session is used and the ticket cookie is ignored, so a shared link can never pin a signed-in user's view to the sharer's `$viewer`. The `spor share <lens-id> [--expires <Nd>]` CLI verb is the shell front-door (remote-only — tickets are minted and signed server-side); it prints the shareable link ready to paste, `--json` for the raw envelope |
 | `POST /v1/merge` `{nodes: [...], mode?: "plan"\|"apply", id_map?: {...}, trust_attached_code?: bool, force?: bool}` | admin promoting one graph into another — pilot-to-org, or a local dogfood graph into a hosted tenant | bring another graph's exported node files (`nodes`: an array of raw node markdown strings) into this one without the failure mode of the naive `GET /v1/export \| POST /v1/nodes --if-exists skip` — silently DROPPING every colliding node while imported edges that pointed at it re-bind to this graph's unrelated same-named node (ordinal id schemes like `cap-<date>-<n>` collide across any two independently started graphs). **Admin-gated** (stewards→root, else `403 forbidden`): `mode:"apply"` writes through the same trusted bulk-import door the server uses internally, which preserves each incoming node's original attribution (a merge moves history, it does not re-author it) and skips the `transitions()`/policy gates (content validation still runs per node; create-only, one deferred commit). Every incoming node classifies as **imported** (id unknown here), **deduped** (id collides, content identical — attribution-blind, this graph's copy wins), **remapped** (id collides, content differs, and the id's final dash-segment is all-digits/*ordinal* — rewritten to `<id>-<sha256(content)[:7]>`, with every reference to the old id across the incoming batch rewritten to match), or **conflict** (id collides with different content and a *semantic* id; a `person` node's email already bound to a different id; or a `schema`/`workflow`/`workflow-run` node or a `stewards`-to-this-graph's-root edge — none of these ever merge silently). Conflicts are reported for manual triage and never written; the schema/workflow class is the one skippable via `trust_attached_code: true` (only for a whole graph you own). `mode:"plan"` (the default) runs the same classification and validation and returns the report without writing anything; `mode:"apply"` **refuses with `409 conflict`** (nothing written) whenever the plan still carries conflicts or validation errors, unless `force: true` — which imports the clean subset and knowingly leaves any reference to a skipped id unresolved. `id_map` (`{"old-id": "new-id"}`) seeds cross-id rewrites; feed a plan's own `id_map` back into the next request when a graph is too large for one batch (plan every batch first to build the complete map, then apply each). Response: `{mode, counts: {incoming, imported, deduped, remapped, conflicts, errors}, imported, deduped, remapped, conflicts, errors, id_map, results?, generated_at}` — `imported`/`deduped`/`remapped`/`conflicts` are arrays of `{id, new_id?, title?, reason?}`; `errors` is `{id, index?, errors: [...]}` (unparseable/invalid entries); `results` (apply mode only) carries the import door's per-entry write verdicts. Deterministic and idempotent — re-running an identical merge dedups everything the first run imported, safe after a partial failure. Called directly today (bearer admin token + `curl`); a CLI wrapper defaulting to plan mode is tracked separately (task-spor-cli-merge-verb) |
-| `GET /v1/export` | bootstrap/offline; `spor export` | ustar tarball of `nodes/` for seeding a local read replica (`?gzip=1` compresses); see §5 for the response headers. `curl … \| tar x` reproduces `nodes/` byte-for-byte. `?history=1` instead streams a `git bundle --all` of the repo (`application/x-git-bundle`, full commit provenance, the customer data-exit path — `git clone <bundle> graph`); `?auth=1` ALSO bundles `auth/*.json` so a disaster restore reproduces the credential set (admin-gated: stewards-root → `403` otherwise). The `spor export [--gzip] [--history\|--auth] [--out <file>]` CLI verb is the shell front-door (remote downloads this; `--gzip`/`--out` also build the same `nodes/` tarball locally, while `--history`/`--auth` are remote-only) |
+| `GET /v1/export` | bootstrap/offline; `spor export` | ustar tarball of the viewer-visible `nodes/` projection for seeding a local read replica (`?gzip=1` compresses); invisible files and cross-boundary edge lines are omitted. For a root steward this reproduces `nodes/` byte-for-byte. See §5 for response headers. `?history=1` instead streams an inherently unfilterable `git bundle --all` of the repo (`application/x-git-bundle`, full commit provenance, the customer data-exit path — `git clone <bundle> graph`) and is therefore admin-gated (`stewards`→root → `403` otherwise). `?auth=1` ALSO bundles `auth/*.json` so a disaster restore reproduces the credential set and has the same admin gate. The `spor export [--gzip] [--history\|--auth] [--out <file>]` CLI verb is the shell front-door (remote downloads this; `--gzip`/`--out` also build the same `nodes/` tarball locally, while `--history`/`--auth` are remote-only) |
 | `GET /v1/admin/people` | tenant-admin console; offboarding / audit | list every person **subject** → `{people: [{id, name, email, roles, is_admin, status, tokens, active_tokens, last_used}], count}`. `is_admin` reflects the `stewards→root` edge (§4, the same per-person check the admin gate itself runs); `tokens`/`active_tokens`/`last_used` summarize the subject's PATs from the same store `GET /v1/admin/tokens` below lists. `status` is the node's own frontmatter status, stamped `active` at creation — offboarding (below) revokes access without touching it, so it is not an offboarded/active signal today. Admin-only (§4) |
 | `POST /v1/admin/people` `{name, email, id?, roles?, invite?, connection_id?, org?}` | onboarding; the on-box `mint-person.js` CLI, the tenant-admin console | create the canonical person **subject** a PAT or provider callback binds to (task-spor-pilot-person-node-onboarding) — `POST /v1/admin/tokens` below and a provider (IdP) callback both refuse to conjure one, so this is the deliberate step onboarding a new teammate needs FIRST → 201 `{id, name, email, roles, revision, org_invitation?}`. `name`/`email` are required, single-line, ≤200 chars; `id` defaults to an opaque, deterministic email-hash when omitted (never the mutable display name) and must be a `person-<slug>` kebab id; `roles` is an optional array of ≤20 kebab-case role slugs. No `stewards` edge is written — a regular teammate is not an admin (grant that separately, §4). `invite:true` additionally issues a WorkOS Organization invitation for the same email (`connection_id` disambiguates when more than one WorkOS connection is configured; `org` pins the invitation's org, and is honored only on an unbound/self-host server — on a server already bound to one org (the hosted default), a supplied `org` that disagrees with it is `403 forbidden` rather than silently corrected, and omitting it just pins to the bound org) — the invite shape is validated up front so a bad arg never leaves a half-done onboarding, but an invitation failure never rolls back the created person: `org_invitation: {status: "issued"|"failed", ...}` reports either outcome. Admin-only, same `stewards→root` gate as `/v1/admin/tokens`. `409` on a colliding id; `422` invalid |
 | `DELETE /v1/admin/people/{id}` | offboarding | **offboard** a member: revoke every PAT and OAuth grant bound to the subject (the same cascade a directory deprovision runs) → `{offboarded, tokens_revoked, oauth_grants_revoked}`. Does **not** delete the person node — it stays the canonical subject every attribution reference points at, so removal here means "revoke access", not "erase the record". Self-offboarding is refused (`422`) so an admin can't lock themselves out; a malformed or non-`person-` id is also `422` (checked before lookup). Admin-only (§4); `404` unknown id |

package/bin/spor.js

@@ -22,7 +22,7 @@ const os = require("os");
 const path = require("path");
 const https = require("https");
 const crypto = require("crypto");
-const { spawnSync } = require("child_process");
+const { spawn, spawnSync } = require("child_process");
 const { parseArgs } = require("util");
 
 const ROOT = path.resolve(__dirname, "..");
@@ -31,6 +31,8 @@ const remote = require(path.join(ROOT, "lib", "remote.js"));
 const auth = require(path.join(ROOT, "lib", "auth.js"));
 const u = require(path.join(ROOT, "scripts", "engines", "util.js"));
 const { gitSpawn } = require(path.join(ROOT, "lib", "shell", "git-exec.js"));
+const dispatchRuns = require(path.join(ROOT, "lib", "shell", "agent-dispatch-runner.js"));
+const dispatchHarnesses = require(path.join(ROOT, "lib", "shell", "dispatch-harnesses.js"));
 const sat = require(path.join(ROOT, "lib", "kernel", "satisfiability.js"));
 // Resolution truth (lib/kernel/resolution.js): a node is "done" when it carries a
 // TERMINAL status OR a live inbound resolves/answers edge — the same partition the
@@ -386,7 +388,7 @@ async function cmdNext(cfg, args) {
     }
     if (needAgents) {
       const q = r.json || {};
-      const { items, hidden } = annotateInFlight(q.items || [], dispatchedAgents(), hideDispatched);
+      const { items, hidden } = annotateInFlight(q.items || [], dispatchedAgents(cfg), hideDispatched);
       q.items = items;
       if (typeof q.count === "number") q.count = Math.max(0, q.count - hidden);
       // --hide-dispatched shrinks .items below whatever fetchQueuePaged assembled,
@@ -418,7 +420,7 @@ async function cmdNext(cfg, args) {
   // Default path: byte-identical passthrough (no agent cross-reference). Only the
   // --json / --hide-dispatched view captures queue.js's result to annotate it.
   if (!needAgents) return passthrough("queue.js", localArgs);
-  return nextLocalInFlight(localArgs, { wantJson, hideDispatched });
+  return nextLocalInFlight(cfg, localArgs, { wantJson, hideDispatched });
 }
 
 // Local in-flight surface (task-spor-cli-in-flight-surface). The default local
@@ -429,7 +431,7 @@ async function cmdNext(cfg, args) {
 // surfaces; an unparseable stdout falls back to forwarding it verbatim, so an
 // error path is never swallowed. The flags are presentation-only — strip them
 // before handing argv to queue.js (which doesn't know them) and force --json.
-function nextLocalInFlight(localArgs, { wantJson, hideDispatched }) {
+function nextLocalInFlight(cfg, localArgs, { wantJson, hideDispatched }) {
   const passArgs = localArgs.filter((a) => a !== "--json" && a !== "--hide-dispatched");
   passArgs.push("--json");
   const r = spawnSync(process.execPath, [path.join(ROOT, "lib", "queue.js"), ...passArgs], {
@@ -444,7 +446,7 @@ function nextLocalInFlight(localArgs, { wantJson, hideDispatched }) {
     if (r.stdout) process.stdout.write(r.stdout); // forward queue.js's own output
     return status;
   }
-  const { items, hidden } = annotateInFlight(q.items || [], dispatchedAgents(), hideDispatched);
+  const { items, hidden } = annotateInFlight(q.items || [], dispatchedAgents(cfg), hideDispatched);
   q.items = items;
   if (typeof q.count === "number") q.count = Math.max(0, q.count - hidden);
   if (hideDispatched) q.hidden_dispatched = hidden;
@@ -488,27 +490,43 @@ function renderQueueLocalText(q, hidden = 0) {
 // (every item then reads in_flight:false). SPOR_FAKE_AGENTS_JSON injects canned
 // output for tests, mirroring SPOR_FAKE_MCP_LIST; all claude shell-outs route
 // through claudeCmd() so an SPOR_CLAUDE_CMD stub works too.
-function dispatchedAgents() {
+function dispatchedAgents(cfg) {
   try {
-    let text = process.env.SPOR_FAKE_AGENTS_JSON;
-    if (text == null) {
-      const cmd = claudeCmd();
-      if (cmd === "claude" && !hasCmd("claude")) return new Map();
-      const r = spawnPortableSync(cmd, ["agents", "--json"], { encoding: "utf8", timeout: 5000 });
-      if (r.status !== 0 || !r.stdout) return new Map();
-      text = r.stdout;
-    }
-    const arr = JSON.parse(text);
-    if (!Array.isArray(arr)) return new Map();
     const map = new Map();
-    for (const a of arr) {
-      if (!a || a.kind !== "background" || typeof a.name !== "string") continue;
-      if (a.state === "done") continue; // finished — not in flight
-      const list = map.get(a.name) || [];
-      // sessionId + startedAt ride along for post-launch session capture
-      // (dec-spor-dispatch-bg-session-late-bind); the dup-guard ignores them.
-      list.push({ id: a.id, name: a.name, state: a.state, status: a.status, cwd: a.cwd, sessionId: a.sessionId, startedAt: a.startedAt });
-      map.set(a.name, list);
+    const add = (name, summary) => {
+      const list = map.get(name) || [];
+      list.push(summary);
+      map.set(name, list);
+    };
+    const home = cfg && typeof cfg.userConfigHome === "function" ? cfg.userConfigHome() : u.userConfigHome();
+    for (const adapter of dispatchHarnesses.harnesses()) {
+      const discovery = adapter.activeDiscovery || {};
+      if (discovery.kind === "run-records") {
+        for (const a of dispatchRuns.activeRuns(home)) {
+          if (a && a.harness === adapter.id && typeof a.name === "string") add(a.name, a);
+        }
+        continue;
+      }
+      if (discovery.kind !== "cli-json") continue;
+      let text = process.env.SPOR_FAKE_AGENTS_JSON;
+      if (text == null) {
+        const cmd = adapter.command();
+        if (cmd === "claude" && !hasCmd(cmd)) continue;
+        const r = spawnPortableSync(cmd, discovery.args, { encoding: "utf8", timeout: 5000 });
+        if (r.status !== 0 || !r.stdout) continue;
+        text = r.stdout;
+      }
+      let arr;
+      try { arr = JSON.parse(text); } catch { continue; }
+      if (!Array.isArray(arr)) continue;
+      for (const a of arr) {
+        if (!a || a.kind !== "background" || typeof a.name !== "string") continue;
+        if (a.state === "done") continue;
+        add(a.name, {
+          id: a.id, name: a.name, harness: adapter.id, state: a.state,
+          status: a.status, cwd: a.cwd, sessionId: a.sessionId, startedAt: a.startedAt,
+        });
+      }
     }
     return map;
   } catch {
@@ -524,9 +542,11 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // + `cwd` + `startedAt` — the reliable capture path. Match on cwd (the strong
 // signal — we just launched there), then on name when given, then pick the NEWEST
 // (the run we just started). Returns the sessionId or null.
-function newestDispatchedSession(name, dir) {
+function newestDispatchedSession(cfg, name, dir) {
   const all = [];
-  for (const arr of dispatchedAgents().values()) for (const a of arr) all.push(a);
+  for (const arr of dispatchedAgents(cfg).values()) {
+    for (const a of arr) if (!a.harness || a.harness === "claude-code") all.push(a);
+  }
   let cands = all.filter((a) => a.sessionId && (!dir || a.cwd === dir));
   if (name) {
     const named = cands.filter((a) => a.name === name);
@@ -540,10 +560,10 @@ function newestDispatchedSession(name, dir) {
 // Capture the launched run's session, polling briefly while the daemon registers
 // it. SPOR_SESSION_ID pins it (tests/reproducibility) and short-circuits the poll.
 // Returns the sessionId or null (fail-open — the caller degrades to session-null).
-async function captureDispatchSession(name, dir, pinned) {
+async function captureDispatchSession(cfg, name, dir, pinned) {
   if (pinned) return pinned;
   for (let i = 0; i < 6; i++) {
-    const sid = newestDispatchedSession(name, dir);
+    const sid = newestDispatchedSession(cfg, name, dir);
     if (sid) return sid;
     await sleep(300);
   }
@@ -5534,13 +5554,13 @@ function homeDir() {
 // The Claude Code binary, overridable for tests (a stub fed via SPOR_CLAUDE_CMD,
 // same lever 'spor dispatch' uses). All claude shell-outs route through here.
 function claudeCmd() {
-  return process.env.SPOR_CLAUDE_CMD || "claude";
+  return dispatchHarnesses.getHarness("claude-code").command();
 }
 
 // The Codex CLI binary, overridable for tests. Codex owns plugin install state,
 // so all plugin shell-outs route through this seam instead of writing its cache.
 function codexCmd() {
-  return process.env.SPOR_CODEX_CMD || "codex";
+  return dispatchHarnesses.getHarness("codex").command();
 }
 
 function spawnPortableSync(cmd, args, opts = {}) {
@@ -6584,7 +6604,7 @@ function dispatchReadinessCheck(cfg, node) {
 // assigned->agent edge `profile:` attribute > that agent's default uses-profile.
 // Returns null when NO profile resolves (no assignment, no profile nodes yet) —
 // the common case, leaving dispatch byte-identical. Otherwise
-// { id, source, found, verdict }: an explicitly-named --profile that can't be
+// { id, source, found, profile, verdict }: an explicitly-named --profile that can't be
 // loaded sets found:false (a hard error the caller reports); an INFERRED profile
 // that can't be loaded returns null (fail-open — never block on a dangling edge).
 async function resolveDispatchProfile(cfg, { profileFlag, nodeRaw, identityAgent }) {
@@ -6661,7 +6681,7 @@ async function resolveDispatchProfile(cfg, { profileFlag, nodeRaw, identityAgent
     /* probe is best-effort; match against what the cascade already holds */
   }
   const machine = sat.effectiveCapabilities(probed ? { ...rawCap, probed } : rawCap);
-  return { id, source, found: true, verdict: sat.satisfies(machine, profile) };
+  return { id, source, found: true, profile, verdict: sat.satisfies(machine, profile) };
 }
 
 // Compile a briefing: a node id -> its neighborhood; free text -> a digest.
@@ -6764,7 +6784,7 @@ async function topQueueItem(cfg, slug) {
   items = items.filter((it) => it.suggest !== "triage");
   if (!items.length) return null;
   // Skip items already in flight on this machine; advance to the first free one.
-  const { items: free, hidden } = annotateInFlight(items, dispatchedAgents(), true);
+  const { items: free, hidden } = annotateInFlight(items, dispatchedAgents(cfg), true);
   if (hidden && free.length) {
     err(`from-queue: skipped ${hidden} item(s) already in flight on this machine; picking ${free[0].id}`);
   }
@@ -7210,6 +7230,94 @@ function sweepStaleMcpConfigs(dir) {
   }
 }
 
+const DISPATCH_RUNNER = path.join(ROOT, "lib", "shell", "agent-dispatch-runner.js");
+
+function writePrivate(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const fd = fs.openSync(file, "wx", 0o600);
+  try {
+    fs.writeSync(fd, text);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+async function launchSupervisedHarness(cfg, {
+  adapter, command, args, cwd, name, nodeId, prompt, server, childToken, mcpToken, bindToken,
+  renewToken, renewNode,
+}) {
+  const runId = crypto.randomUUID();
+  const p = dispatchRuns.runPaths(cfg.userConfigHome(), runId);
+  const runArgs = args.map((a) => a === "__SPOR_REPORT_PATH__" ? p.report : a);
+  const now = new Date().toISOString();
+  const record = {
+    run_id: runId,
+    node_id: nodeId || null,
+    name,
+    harness: adapter.id,
+    state: "launching",
+    cwd,
+    created_at: now,
+    log_path: p.log,
+    report_path: p.report,
+  };
+  writePrivate(p.prompt, prompt);
+  writePrivate(p.job, JSON.stringify({
+    run_id: runId,
+    harness: adapter.id,
+    command,
+    args: runArgs,
+    cwd,
+    record_path: p.record,
+    prompt_path: p.prompt,
+    log_path: p.log,
+    report_path: p.report,
+    server: server || null,
+    renew_node: renewNode || null,
+  }, null, 2) + "\n");
+  dispatchRuns.atomicJson(p.record, record);
+
+  const runnerEnv = u.gitEnv();
+  for (const key of [
+    "SPOR_DISPATCH_CHILD_TOKEN", "SPOR_DISPATCH_MCP_TOKEN",
+    "SPOR_DISPATCH_BIND_TOKEN", "SPOR_DISPATCH_RENEW_TOKEN",
+  ]) delete runnerEnv[key];
+  if (childToken) runnerEnv.SPOR_DISPATCH_CHILD_TOKEN = childToken;
+  if (mcpToken) runnerEnv.SPOR_DISPATCH_MCP_TOKEN = mcpToken;
+  if (bindToken) runnerEnv.SPOR_DISPATCH_BIND_TOKEN = bindToken;
+  if (renewToken) runnerEnv.SPOR_DISPATCH_RENEW_TOKEN = renewToken;
+  let child;
+  let spawnError = null;
+  try {
+    child = spawn(process.execPath, [DISPATCH_RUNNER, p.job], {
+      detached: true,
+      stdio: "ignore",
+      env: runnerEnv,
+      windowsHide: true,
+    });
+    child.on("error", (e) => { spawnError = e; });
+    child.unref();
+    if (child.pid) dispatchRuns.atomicJson(p.record, { ...record, runner_pid: child.pid });
+  } catch (e) {
+    spawnError = e;
+  }
+
+  for (let i = 0; i < 20 && !spawnError; i++) {
+    const state = dispatchRuns.readJson(p.record);
+    if (state && state.state === "failed_launch") {
+      return { ok: false, error: state.error || `${adapter.label} process failed to launch`, runId, paths: p };
+    }
+    if (state && state.state !== "launching") return { ok: true, state, runId, paths: p };
+    await sleep(50);
+  }
+  if (spawnError) {
+    for (const f of [p.job, p.prompt]) try { fs.unlinkSync(f); } catch {}
+    return { ok: false, error: spawnError.message, runId, paths: p };
+  }
+  const state = dispatchRuns.readJson(p.record) || record;
+  return { ok: true, state, runId, paths: p };
+}
+
 async function cmdDispatch(cfg, { values, positionals: pos }) {
   const dryRun = !!(values.print || values["dry-run"]);
   const full = !!values.full;
@@ -7221,6 +7329,8 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   const dirOpt = values.dir || null;
   const model = values.model || null;
   const permMode = values["permission-mode"] || null;
+  const sandbox = values.sandbox || null;
+  const approvalPolicy = values["approval-policy"] || null;
   const agent = values.agent || null; // claude --agent (harness agent DEFINITION)
   const asAgent = values.as || null; // Spor agent IDENTITY override for dispatch.agent
   // A user-supplied prompt template (task-spor-dispatch-user-prompt-templates):
@@ -7456,7 +7566,7 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   // mode only (mirrors the auto-claim's scope), in BOTH local and remote (it's a
   // local agent read, independent of the graph backend). claude absent / a stale
   // exit / unparseable output => empty => no guard (fail-open); --force overrides.
-  const inFlight = nodeId && !backfill ? dispatchedAgents().get(name) || [] : [];
+  const inFlight = nodeId && !backfill ? dispatchedAgents(cfg).get(name) || [] : [];
 
   // Session identity (dec-spor-dispatch-bg-session-late-bind). `claude --bg`
   // IGNORES `--session-id` and self-allocates its own run session (verified — it
@@ -7548,15 +7658,37 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     return 1;
   }
   const unsatisfiable = !!(profileCheck && profileCheck.verdict && !profileCheck.verdict.ok);
-
-  const claudeBin = claudeCmd();
-  const claudeArgs = ["--bg"];
-  if (name) claudeArgs.push("--name", name);
-  if (model) claudeArgs.push("--model", model);
-  if (permMode) claudeArgs.push("--permission-mode", permMode);
-  if (agent) claudeArgs.push("--agent", agent);
+  const profileRuntime = (profileCheck && profileCheck.profile) || {};
+  const harness = profileRuntime.harness || "claude-code";
+  const harnessAdapter = dispatchHarnesses.getHarness(harness);
+  const effectiveModel = model || profileRuntime.model || null;
+  const harnessBin = harnessAdapter ? harnessAdapter.command() : null;
   // NB: no `--session-id` — `claude --bg` ignores it (warns) and manages its own
   // session; we capture the real one post-launch (dec-spor-dispatch-bg-session-late-bind).
+  const previewArgs = harnessAdapter ? harnessAdapter.buildArgs({
+    name,
+    model: effectiveModel,
+    permissionMode: permMode,
+    agent,
+    sandbox: sandbox || "workspace-write",
+    approvalPolicy: approvalPolicy || "never",
+    reportPath: "__SPOR_REPORT_PATH__",
+    sporMcp: null,
+  }) : [];
+  const supportedHarness = !!harnessAdapter;
+  if (!supportedHarness && !dryRun) {
+    err(`cannot dispatch ${nodeId || name}: profile ${profileCheck && profileCheck.id ? profileCheck.id : "(unknown)"} selects unsupported harness '${harness}'.`);
+    err(`  this client has adapters for ${dispatchHarnesses.harnesses().map((a) => a.id).join(", ")}; the assignment is unchanged.`);
+    return 1;
+  }
+  const invalidHarnessOptions = harnessAdapter && harnessAdapter.validateOptions({
+    permissionMode: permMode, agent, sandbox, approvalPolicy,
+  });
+  if (invalidHarnessOptions) {
+    err(invalidHarnessOptions.message);
+    err(`  ${invalidHarnessOptions.hint}`);
+    return 1;
+  }
 
   if (dryRun) {
     out(`dir:    ${res.dir}  (slug: ${res.slug}, via ${res.source})`);
@@ -7574,7 +7706,8 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
       out(`onboard: ${steps.join("; ")}`);
     }
     out(`brief:  ${brief ? `${brief.length} bytes` : "(none — graph had nothing relevant, or --no-brief/--backfill)"}`);
-    out(`session: ${pinnedSession || "(allocated by claude --bg at launch, bound after)"}`);
+    if (profileCheck) out(`harness: ${harness} (profile ${profileCheck.id})`);
+    out(`session: ${pinnedSession || (harnessAdapter ? harnessAdapter.sessionPreview : "(unsupported harness)")}`);
     // Identity preview: what the real dispatch would do for agent-scoping. The
     // token mint + 0600 mcp-config are SIDE EFFECTS, so --print only describes
     // them (it writes nothing and makes no network call here). Local mode and an
@@ -7582,7 +7715,11 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     // session line, which is additive and always present now.
     if (identityAgent) {
       const src = asAgent ? " (via --as)" : "";
-      out(`agent:  ${identityAgent}${src} (would mint a session-deferred agent-scoped token + write a 0600 --mcp-config, add --strict-mcp-config, then bind the run session after launch)`);
+      out(
+        harnessAdapter && harnessAdapter.identityMode === "env-mcp"
+          ? `agent:  ${identityAgent}${src} (would mint a session-deferred agent token, inject it through env-backed Spor MCP config, then bind the Codex thread after launch)`
+          : `agent:  ${identityAgent}${src} (would mint a session-deferred agent-scoped token + write a 0600 --mcp-config, add --strict-mcp-config, then bind the run session after launch)`
+      );
     } else if (cfg.mode() === "remote") {
       out(`agent:  (none configured — 'spor agent use agent-<machine>' or --as to attribute as agent-on-behalf-of; dispatching person-scoped)`);
     }
@@ -7631,7 +7768,10 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
       out(`claim:  ${noClaim ? "(--no-claim — lease not established)" : `would establish a lease on ${nodeId} at launch (session bound from the run after launch)`}`);
     }
     if (template != null) out(`template: ${path.resolve(templateOpt)}`);
-    out(`run:    ${claudeBin} ${claudeArgs.map(shellQuote).join(" ")} <prompt>`);
+    if (!supportedHarness) out(`run:    (unsupported harness '${harness}')`);
+    else if (harnessAdapter.launchMode === "supervised-jsonl") {
+      out(`run:    ${harnessBin} ${previewArgs.map((a) => a === "__SPOR_REPORT_PATH__" ? "<report-path>" : shellQuote(a)).join(" ")}  # prompt on stdin`);
+    } else out(`run:    ${harnessBin} ${previewArgs.map(shellQuote).join(" ")} <prompt>`);
     out(`\n--- prompt ---\n${prompt}`);
     return 0;
   }
@@ -7693,8 +7833,9 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   u.registerRepo(cfg.userConfigHome(), res.slug, res.dir);
   if (backfill) out(`registered ${res.slug} → ${res.dir}; launching the backfill agent…`);
 
-  if (claudeBin === "claude" && !hasCmd("claude")) {
-    err("claude CLI not on PATH — install Claude Code, then re-run (or 'spor dispatch … --print' to see the prompt).");
+  const defaultHarnessBin = harnessAdapter.command({});
+  if (harnessBin === defaultHarnessBin && !hasCmd(defaultHarnessBin)) {
+    err(`${harnessAdapter.missingBinary}, then re-run (or 'spor dispatch … --print' to see the prompt).`);
     return 1;
   }
 
@@ -7710,6 +7851,7 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   // back to the prior person-scoped dispatch with a clear line. Remote + a
   // configured agent only; local/unconfigured dispatch is byte-identical.
   let agentToken = null;
+  let agentMcpFile = null;
   if (identityAgent) {
     // Always session-DEFERRED — the run session is bound after launch (below),
     // even when SPOR_SESSION_ID pins it (the pin feeds the capture, not the mint),
@@ -7717,8 +7859,9 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     const mint = await mintAgentToken(cfg, { agent: identityAgent });
     if (mint.ok) {
       agentToken = mint.token;
-      const mcpFile = writeDispatchMcpConfig(cfg, { token: mint.token, key: mcpKey });
-      claudeArgs.push("--mcp-config", mcpFile, "--strict-mcp-config");
+      if (harnessAdapter.identityMode === "mcp-file") {
+        agentMcpFile = writeDispatchMcpConfig(cfg, { token: mint.token, key: mcpKey });
+      }
       out(`agent:  ${identityAgent} (writes attributed agent-on-behalf-of-you; run session bound after launch)`);
     } else if (mint.absent) {
       err(`warning: this server can't mint agent-scoped session tokens yet — dispatching person-scoped.`);
@@ -7813,14 +7956,61 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     out(`worktree: ${wt.dir} (branch ${wt.branch}${wt.reused ? ", reused" : ""}${wt.setupRan ? "; setup ran" : ""})`);
   }
 
-  claudeArgs.push(prompt);
+  if (harnessAdapter.launchMode === "supervised-jsonl") {
+    const personToken = cfg.mode() === "remote" ? remote.token(cfg) : "";
+    const mcpToken = agentToken || personToken;
+    const wantsSporMcp = harnessAdapter.identityMode === "env-mcp" && cfg.mode() === "remote" && (
+      !!identityAgent || (Array.isArray(profileRuntime.mcp) && profileRuntime.mcp.includes("spor"))
+    );
+    const args = harnessAdapter.buildArgs({
+      model: effectiveModel,
+      sandbox: sandbox || "workspace-write",
+      approvalPolicy: approvalPolicy || "never",
+      reportPath: "__SPOR_REPORT_PATH__",
+      sporMcp: wantsSporMcp && mcpToken ? { url: `${remote.base(cfg)}/mcp` } : null,
+    });
+    const launched = await launchSupervisedHarness(cfg, {
+      adapter: harnessAdapter,
+      command: harnessBin,
+      args,
+      cwd: launchDir,
+      name,
+      nodeId,
+      prompt,
+      server: cfg.mode() === "remote" ? remote.base(cfg) : null,
+      childToken: agentToken,
+      mcpToken: wantsSporMcp ? mcpToken : null,
+      bindToken: agentToken,
+      renewToken: agentToken || personToken,
+      renewNode: nodeId && !backfill && !noClaim ? nodeId : null,
+    });
+    if (!launched.ok) {
+      err(`could not launch ${harnessBin}: ${launched.error}`);
+      await releaseClaimOnAbort();
+      return 1;
+    }
+    out(`run:     ${launched.runId} (${harnessAdapter.label} supervisor ${launched.state.state || "launching"})`);
+    out(`log:     ${launched.paths.log}`);
+    out(`report:  ${launched.paths.report}`);
+    if (launched.state.session_id) out(`session: ${launched.state.session_id}`);
+    return 0;
+  }
+
+  const nativeArgs = harnessAdapter.buildArgs({
+    name,
+    model: effectiveModel,
+    permissionMode: permMode,
+    agent,
+    mcpConfig: agentMcpFile,
+    prompt,
+  });
   // The agent's git must follow launchDir (its worktree, or the target checkout),
   // so hand it an env scrubbed of the git location vars — an ambient GIT_DIR
   // would otherwise point every commit it makes at the LAUNCHER's repo
   // (issue-spor-dispatch-worktree-wrong-repo-location).
-  const r = spawnPortableSync(claudeBin, claudeArgs, { cwd: launchDir, stdio: "inherit", env: u.gitEnv() });
+  const r = spawnPortableSync(harnessBin, nativeArgs, { cwd: launchDir, stdio: "inherit", env: u.gitEnv() });
   if (r.error) {
-    err(`could not launch ${claudeBin}: ${r.error.message}`);
+    err(`could not launch ${harnessBin}: ${r.error.message}`);
     await releaseClaimOnAbort();
     return 1;
   }
@@ -7837,7 +8027,7 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   // claimed node).
   const wantBind = cfg.mode() === "remote" && (agentToken || (nodeId && !backfill && !noClaim));
   if (wantBind) {
-    const realSession = await captureDispatchSession(name, launchDir, pinnedSession);
+    const realSession = await captureDispatchSession(cfg, name, launchDir, pinnedSession);
     if (realSession) {
       if (agentToken) {
         const b = await bindAgentSession(cfg, agentToken, realSession);
@@ -8943,7 +9133,7 @@ const COMMANDS = {
     run: (cfg, args) => cmdToken(cfg, args),
   },
   agent: {
-    group: "Dispatch (Claude Code background agents)", parse: "raw", args: "create <label> [--owner <id>] [--pubkey <fp>] | list | use <agent-id> | token <agent-id> [list|revoke <prefix>]",
+    group: "Dispatch (background agents)", parse: "raw", args: "create <label> [--owner <id>] [--pubkey <fp>] | list | use <agent-id> | token <agent-id> [list|revoke <prefix>]",
     summary: "person-owned automation principals (dispatch identity, standing PATs)",
     help:
       "Create and list agents — first-class `type: agent` nodes owned by a person\n" +
@@ -9815,11 +10005,13 @@ const COMMANDS = {
 
   // --- Dispatch ---
   dispatch: {
-    group: "Dispatch (Claude Code background agents)", parse: "strict", args: '"<task>" | <node-id>', aliases: ["bg"],
-    summary: "compile a briefing + launch 'claude --bg' in the repo",
+    group: "Dispatch (background agents)", parse: "strict", args: '"<task>" | <node-id>', aliases: ["bg"],
+    summary: "compile a briefing + launch the profile-selected harness",
     help:
-      "Compile a briefing for a task and launch a Claude Code background agent in the\n" +
-      "right repo. Give free-text, a <node-id>, --node <id>, --from-queue (the top\n" +
+      "Compile a briefing for a task and launch a background agent in the right repo.\n" +
+      "A resolved profile selects its harness (claude-code or codex); with no profile,\n" +
+      "dispatch preserves the legacy Claude Code path. Give free-text, a <node-id>,\n" +
+      "--node <id>, --from-queue (the top\n" +
       "ranked item NOT already in flight on this machine), or --backfill (the\n" +
       "unattended init + enable + launch-/spor:backfill primitive; first-time setup\n" +
       "goes through the /spor:onboard skill instead). The target dir is the\n" +
@@ -9861,11 +10053,13 @@ const COMMANDS = {
       node: { type: "string", value: "id", desc: "dispatch a specific node id" },
       slug: { type: "string", value: "slug", desc: "target project slug (cross-repo resolution)" },
       as: { type: "string", value: "agent-id", desc: "Spor agent IDENTITY to run as (overrides dispatch.agent; remote-only)" },
-      model: { type: "string", value: "M", desc: "claude --model" },
+      model: { type: "string", value: "M", desc: "harness model override (otherwise profile.model)" },
       "permission-mode": { type: "string", value: "P", desc: "claude --permission-mode" },
+      sandbox: { type: "string", value: "S", desc: "codex exec --sandbox (default: workspace-write)" },
+      "approval-policy": { type: "string", value: "P", desc: "codex exec --ask-for-approval (default: never)" },
       agent: { type: "string", value: "A", desc: "claude --agent (harness agent DEFINITION — NOT the Spor identity; see --as)" },
       profile: { type: "string", value: "profile-id", desc: "profile to run under; checked against this machine's capabilities (overrides the assigned/default profile)" },
-      name: { type: "string", value: "N", desc: "claude --name (session name)" },
+      name: { type: "string", value: "N", desc: "dispatch run name (passed to Claude; tracked locally for Codex)" },
       template: { type: "string", value: "F", desc: "prompt template file (placeholders above)" },
       full: { type: "boolean", desc: "full briefing instead of the digest" },
       "no-brief": { type: "boolean", desc: "raw task prompt, no briefing block" },
@@ -9882,7 +10076,7 @@ const COMMANDS = {
     run: (cfg, p) => cmdDispatch(cfg, p),
   },
   repos: {
-    group: "Dispatch (Claude Code background agents)", parse: "raw",
+    group: "Dispatch (background agents)", parse: "raw",
     args: "[list | add <slug> <path> | rm <slug> | tags | tag <slug> [tag...] | untag <slug> [tag...]]",
     summary: "the local dispatch slug->dir map, plus repo-identity tags in the graph",
     help:
@@ -9904,7 +10098,7 @@ const COMMANDS = {
     run: (cfg, args) => cmdRepos(cfg, args),
   },
   capabilities: {
-    group: "Dispatch (Claude Code background agents)", parse: "raw", aliases: ["caps", "profiles"],
+    group: "Dispatch (background agents)", parse: "raw", aliases: ["caps", "profiles"],
     args: "[list [--json] | show <agent-id> | probe | publish | hosts <profile-id> | set <axis> <v...> | allow-mcp <m...> | deny <profile-id...> | clear]",
     summary: "this machine's dispatch capability map (profile satisfiability)",
     help:
@@ -9974,7 +10168,7 @@ const GROUP_ORDER = [
   "Team admin (remote, admin token)",
   "Graph",
   "Repo scoping",
-  "Dispatch (Claude Code background agents)",
+  "Dispatch (background agents)",
   "Other",
 ];
 

package/lib/shell/agent-dispatch-runner.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+"use strict";
+
+// Supervise one foreground coding-agent CLI outside the short-lived
+// `spor dispatch` process. Harness-specific event interpretation lives in the
+// adapter registry; this runner only manages process, journal, and late binding.
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+const { getHarness } = require("./dispatch-harnesses.js");
+const { whichSync } = require("../../scripts/engines/util.js");
+
+function dispatchRunDir(home) {
+  return path.join(home, "journal", "dispatch");
+}
+
+function runPaths(home, runId) {
+  const dir = dispatchRunDir(home);
+  return {
+    dir,
+    record: path.join(dir, `${runId}.run.json`),
+    job: path.join(dir, `${runId}.job.json`),
+    prompt: path.join(dir, `${runId}.prompt`),
+    log: path.join(dir, `${runId}.log`),
+    report: path.join(dir, `${runId}.report.md`),
+  };
+}
+
+function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function summarizeRun(r) {
+  return {
+    id: r.run_id,
+    run_id: r.run_id,
+    name: r.name,
+    node: r.node_id || null,
+    harness: r.harness,
+    state: r.state,
+    status: r.state === "running" || r.state === "launching" ? "busy" : r.state,
+    cwd: r.cwd,
+    pid: r.child_pid || r.runner_pid || null,
+    sessionId: r.session_id || null,
+    startedAt: r.started_at ? Date.parse(r.started_at) : null,
+    log_path: r.log_path,
+    report_path: r.report_path,
+  };
+}
+
+// Active supervised runs for same-machine guards and queue annotation. Confirm
+// the supervisor PID so a hard-killed runner cannot leave a false positive.
+function activeRuns(home, env = process.env) {
+  if (env.SPOR_FAKE_DISPATCH_RUNS_JSON != null) {
+    try {
+      const xs = JSON.parse(env.SPOR_FAKE_DISPATCH_RUNS_JSON);
+      return Array.isArray(xs) ? xs : [];
+    } catch {
+      return [];
+    }
+  }
+  const dir = dispatchRunDir(home);
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".run.json"));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const file of files) {
+    const r = readJson(path.join(dir, file));
+    if (!r || !["launching", "running"].includes(r.state)) continue;
+    if (!pidAlive(r.runner_pid)) continue;
+    out.push(summarizeRun(r));
+  }
+  return out;
+}
+
+function portableSpawn(cmd, args, opts, runtime = {}) {
+  const platform = runtime.platform || process.platform;
+  const spawnImpl = runtime.spawn || spawn;
+  if (platform !== "win32") return spawnImpl(cmd, args, opts);
+  // npm exposes command shims as .cmd files on Windows. Resolve through PATH +
+  // PATHEXT before deciding how to launch, matching the synchronous CLI path.
+  const resolved = (runtime.which || whichSync)(cmd) || cmd;
+  if (!/\.(?:cmd|bat)$/i.test(resolved)) return spawnImpl(resolved, args, opts);
+  const env = (opts && opts.env) || process.env;
+  return spawnImpl(env.ComSpec || process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", resolved, ...args], opts);
+}
+
+function finishWritable(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.writableFinished || stream.destroyed) return resolve();
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      stream.off("finish", done);
+      stream.off("close", done);
+      stream.off("error", done);
+      resolve();
+    };
+    stream.once("finish", done);
+    stream.once("close", done);
+    stream.once("error", done);
+    stream.end();
+  });
+}
+
+async function post(url, token, body) {
+  if (!url || !token) return false;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 3000);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function runJob(jobFile) {
+  const job = readJson(jobFile);
+  if (!job || !job.record_path || !job.prompt_path) return 2;
+  const adapter = getHarness(job.harness);
+  if (!adapter || adapter.launchMode !== "supervised-jsonl") return 2;
+  let record = readJson(job.record_path) || {};
+  const update = (patch) => {
+    record = { ...record, ...patch };
+    atomicJson(job.record_path, record);
+  };
+
+  let prompt = "";
+  try {
+    prompt = fs.readFileSync(job.prompt_path, "utf8");
+  } catch (e) {
+    update({ state: "failed_launch", finished_at: new Date().toISOString(), error: `could not read prompt: ${e.message}` });
+    return 2;
+  }
+  for (const p of [jobFile, job.prompt_path]) {
+    try { fs.unlinkSync(p); } catch {}
+  }
+
+  fs.mkdirSync(path.dirname(job.log_path), { recursive: true });
+  const log = fs.createWriteStream(job.log_path, { flags: "a", mode: 0o600 });
+  let logError = null;
+  log.on("error", (error) => { logError = error; });
+  const childEnv = { ...process.env };
+  const childToken = process.env.SPOR_DISPATCH_CHILD_TOKEN || "";
+  delete childEnv.SPOR_DISPATCH_CHILD_TOKEN;
+  delete childEnv.SPOR_DISPATCH_BIND_TOKEN;
+  delete childEnv.SPOR_DISPATCH_RENEW_TOKEN;
+  if (childToken) {
+    // Never leave the broader person credential available under either the
+    // canonical or legacy compatibility spelling in an agent-scoped run.
+    delete childEnv.SPOR_TOKEN;
+    delete childEnv.SUBSTRATE_TOKEN;
+    childEnv.SPOR_TOKEN = childToken;
+    childEnv.SUBSTRATE_TOKEN = childToken;
+  }
+
+  let child;
+  try {
+    child = portableSpawn(job.command, job.args, {
+      cwd: job.cwd,
+      env: childEnv,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+  } catch (e) {
+    update({ state: "failed_launch", finished_at: new Date().toISOString(), error: e.message });
+    await finishWritable(log);
+    return 2;
+  }
+
+  let launched = false;
+  let childError = null;
+  let stdinError = null;
+  let pending = "";
+  let bindPromise = Promise.resolve();
+  let sawSession = false;
+
+  const bindSession = (session) => {
+    if (sawSession || !session) return;
+    sawSession = true;
+    update({ session_id: session });
+    bindPromise = (async () => {
+      const base = String(job.server || "").replace(/\/+$/, "");
+      const bindToken = process.env.SPOR_DISPATCH_BIND_TOKEN || "";
+      const renewToken = process.env.SPOR_DISPATCH_RENEW_TOKEN || bindToken;
+      if (bindToken) await post(`${base}/v1/agents/session`, bindToken, { session });
+      if (job.renew_node && renewToken) {
+        await post(`${base}/v1/nodes/${encodeURIComponent(job.renew_node)}/renew`, renewToken, { session });
+      }
+    })();
+  };
+
+  const parseLines = (chunk) => {
+    pending += chunk;
+    const lines = pending.split("\n");
+    pending = lines.pop() || "";
+    for (const line of lines) {
+      try {
+        const event = JSON.parse(line);
+        const session = typeof adapter.sessionFromEvent === "function" ? adapter.sessionFromEvent(event) : null;
+        if (session) bindSession(session);
+      } catch {
+        // JSONL is preserved verbatim even when an adapter does not recognize it.
+      }
+    }
+  };
+
+  // A child can reject args/config/auth before reading a large prompt. Writable
+  // pipe failures must be observed before end(prompt), otherwise EPIPE crashes
+  // this detached supervisor and leaves a permanently-running journal record.
+  child.stdin.on("error", (error) => { stdinError = error; });
+
+  child.once("spawn", () => {
+    launched = true;
+    update({
+      state: "running",
+      runner_pid: process.pid,
+      child_pid: child.pid,
+      started_at: new Date().toISOString(),
+    });
+    try {
+      child.stdin.end(prompt);
+    } catch (error) {
+      stdinError = error;
+      child.stdin.destroy();
+    }
+  });
+  child.stdout.on("data", (buf) => {
+    const text = buf.toString("utf8");
+    log.write(text);
+    parseLines(text);
+  });
+  child.stderr.on("data", (buf) => log.write(buf));
+
+  return new Promise((resolve) => {
+    child.on("error", (error) => { childError = error; });
+    child.on("close", async (code, signal) => {
+      if (pending) parseLines("\n");
+      await bindPromise;
+      // `close` follows stdout/stderr closure; now finish the journal stream so
+      // every parsed event is durable before the terminal run record is visible.
+      await finishWritable(log);
+      const failure = childError || stdinError || logError;
+      const succeeded = launched && code === 0 && !failure;
+      update({
+        state: launched ? (succeeded ? "done" : "failed") : "failed_launch",
+        exit_code: Number.isInteger(code) ? code : null,
+        signal: signal || null,
+        finished_at: new Date().toISOString(),
+        ...(failure ? { error: failure.message } : {}),
+      });
+      resolve(launched ? (succeeded ? 0 : (code || 1)) : 2);
+    });
+  });
+}
+
+if (require.main === module) {
+  runJob(process.argv[2]).then((code) => { process.exitCode = code; }).catch(() => { process.exitCode = 2; });
+}
+
+module.exports = { dispatchRunDir, runPaths, atomicJson, readJson, activeRuns, summarizeRun, portableSpawn, runJob };

package/lib/shell/dispatch-harnesses.js

@@ -0,0 +1,96 @@
+"use strict";
+
+// Coding-agent CLI adapters for `spor dispatch`. Keep harness-specific argv,
+// validation, session-event parsing, and discovery declarations here; the CLI
+// owns the common briefing/profile/claim/worktree/supervision lifecycle.
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function claudeArgs({ name, model, permissionMode, agent, mcpConfig, prompt }) {
+  const args = ["--bg"];
+  if (name) args.push("--name", name);
+  if (model) args.push("--model", model);
+  if (permissionMode) args.push("--permission-mode", permissionMode);
+  if (agent) args.push("--agent", agent);
+  if (mcpConfig) args.push("--mcp-config", mcpConfig, "--strict-mcp-config");
+  if (prompt != null) args.push(prompt);
+  return args;
+}
+
+function codexArgs({ model, sandbox, approvalPolicy, reportPath, sporMcp }) {
+  const args = [
+    "--ask-for-approval", approvalPolicy || "never",
+    "exec",
+    "--json",
+    "--sandbox", sandbox || "workspace-write",
+    "--output-last-message", reportPath,
+  ];
+  if (model) args.push("--model", model);
+  if (sporMcp && sporMcp.url) {
+    args.push(
+      "--config", `mcp_servers.spor.url=${tomlString(sporMcp.url)}`,
+      "--config", `mcp_servers.spor.bearer_token_env_var=${tomlString("SPOR_DISPATCH_MCP_TOKEN")}`,
+      "--config", "mcp_servers.spor.required=true"
+    );
+  }
+  // stdin carries the compiled prompt so it never appears in argv or process
+  // listings. The generic supervisor replaces the report placeholder.
+  args.push("-");
+  return args;
+}
+
+const ADAPTERS = Object.freeze({
+  "claude-code": Object.freeze({
+    id: "claude-code",
+    label: "Claude Code",
+    launchMode: "native-background",
+    identityMode: "mcp-file",
+    command: (env = process.env) => env.SPOR_CLAUDE_CMD || "claude",
+    activeDiscovery: Object.freeze({ kind: "cli-json", args: ["agents", "--json"] }),
+    buildArgs: claudeArgs,
+    validateOptions({ sandbox, approvalPolicy }) {
+      if (!sandbox && !approvalPolicy) return null;
+      const flag = sandbox ? "--sandbox" : "--approval-policy";
+      return {
+        message: `cannot use ${flag} with a Claude Code dispatch — that flag is Codex-specific.`,
+        hint: "use --permission-mode for Claude Code.",
+      };
+    },
+    sessionPreview: "(allocated by claude --bg at launch, bound after)",
+    missingBinary: "claude CLI not on PATH — install Claude Code",
+  }),
+  codex: Object.freeze({
+    id: "codex",
+    label: "Codex",
+    launchMode: "supervised-jsonl",
+    identityMode: "env-mcp",
+    command: (env = process.env) => env.SPOR_CODEX_CMD || "codex",
+    activeDiscovery: Object.freeze({ kind: "run-records" }),
+    buildArgs: codexArgs,
+    validateOptions({ permissionMode, agent }) {
+      if (!permissionMode && !agent) return null;
+      const flag = permissionMode ? "--permission-mode" : "--agent";
+      return {
+        message: `cannot use ${flag} with a Codex dispatch — that flag is Claude Code-specific.`,
+        hint: "Codex runs unattended with --sandbox workspace-write --approval-policy never by default; override those Codex flags explicitly if needed.",
+      };
+    },
+    sessionFromEvent(event) {
+      return event && event.type === "thread.started" ? event.thread_id || null : null;
+    },
+    sessionPreview: "(read from codex exec thread.started, bound by supervisor)",
+    missingBinary: "codex CLI not on PATH — install Codex",
+  }),
+});
+
+function getHarness(id) {
+  return ADAPTERS[id] || null;
+}
+
+function harnesses() {
+  return Object.values(ADAPTERS);
+}
+
+module.exports = { getHarness, harnesses };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
   "license": "Apache-2.0",
   "author": "Anthony Allen",
@@ -49,6 +49,7 @@
     "release": "node scripts/release.js",
     "test": "node --require ./test/helpers/tmp-cleanup.js --test test/*.test.js",
     "test:e2e": "node --require ./test/helpers/tmp-cleanup.js --test test/e2e-claude.test.js",
+    "test:e2e:codex": "node --require ./test/helpers/tmp-cleanup.js --test test/e2e-codex-dispatch.test.js",
     "conformance": "node conformance/runner.js"
   },
   "engines": {