@sporhq/spor 0.24.0 → 0.25.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.24.0",
+  "version": "0.25.0",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

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

@@ -36,7 +36,11 @@ graph's git repo. What a client sees:
 - **Validation**: id/filename agreement, kebab-case, type prefix, mandatory
   standalone summary, known node type, `date:` format, edge syntax. Failures
   return the validator's error list verbatim so a calling model can
-  self-correct. Size limits: body ≤ 8KB, summary ≤ 500 chars, ≤ 40 edges.
+  self-correct. Size limits: body ≤ 8KB, summary ≤ 500 chars, ≤ 40 edges. (A
+  node designed to accrete indefinitely — a running-log artifact — hits this
+  wall by construction; GRAPH.md "Accreting running-log artifacts" is the
+  rollover convention for that case, and `spor validate` warns as a node's
+  body nears the cap.)
 - **Edge normalization**: edge types accept canonical names, registry-declared
   **aliases** (renamed in place), and **inverse labels** (the edge read from
   the target's side — `{blocked-by, to: X}` on N is flipped and written to X
@@ -110,6 +114,22 @@ schema may carry a `get(node, ctx)` hook (GRAPH.md) that attaches derived
 context as extra top-level keys — e.g. `resolution` (what answered/resolved
 this node). These are additive; a client ignores keys it does not know.
 
+### `get_nodes`
+
+Batch-hydrate nodes through the same read path as `get_node`. Start with
+`{ "ids": ["task-a", "issue-b", ...] }` (at most 100 ids); repeated ids are
+deduplicated by first occurrence and results preserve that order. Each entry in
+`nodes` carries the same `raw`, parsed `frontmatter`, `revision`, visibility
+filtering, and additive schema/host enrichment as a single read. Hidden and
+absent ids are deliberately indistinguishable and appear only in `missing_ids`.
+
+The response is `{nodes, returned_ids, missing_ids, truncated, next_cursor}` and
+is bounded to 48 KiB without splitting an entry. When `truncated` is true, call
+again with `{ "cursor": "<next_cursor>" }` alone; the opaque, validated cursor
+resumes the original deduplicated order without re-sending ids. The last page
+has `next_cursor: null`. The REST twin is `POST /v1/nodes/batch` with the same
+request and response shapes.
+
 ### `explore_graph`
 
 Browse/map the team graph's **structure** — a bounded neighborhood as plain
@@ -118,7 +138,8 @@ nodes + typed edges, each node carrying truth flags
 neighbors (`more`). Input `{ "root_id"?, "query"?, "depth"?, "limit"? }` → the
 view-tree slice (`view`, `node_ids`) plus a text rendering. Call with **no
 arguments** for the birds-eye programs overview — every umbrella root (any
-node other work `blocks`) with resolution-derived completion %, most complete
+node other work `blocks` or declares a `member-of-program` edge to) with
+resolution-derived completion %, most complete
 first. Pass `root_id` to walk outward from one node (depth 1-2, deterministic,
 no LLM; default depth 1, limit 40 capped at 80); pass `query` instead to seed
 the roots by relevance. The two are mutually exclusive; `root_id` wins when
@@ -249,20 +270,24 @@ when a session ends cleanly with the task advanced but unfinished: the
 heartbeat is dropped, `expires` is re-pointed at a grace-window expiry
 (~2 days, tenant policy — a timestamp, not a graph edge), and the durable
 `assigned` edge is kept (so a steward/capacity view still reads "reserved by
-you"). Input `{ "id": "<task node id you hold a claim on>", "session"? }` →
-`{ "ok": true, "status": "reserved", "lease", "grace_window_ms" }`.
+you"). Input `{ "id": "<task node id>", "session"? }` →
+`{ "ok": true, "status": "reserved", "lease", "expires_in_ms", "grace_window_ms", "reclaimed"? }`.
 `rankQueue` floats a reservation to the top of the owner's queue while
 dropping it from teammates' actionable lists. Within the grace window the
 reservation still counts as a live lease, so the owner claiming, renewing, or
 extending it drops the `reserved` flag and re-establishes a normal Tier-1
 heartbeat lease; once the grace window lapses the entry is gone (full pool,
-everyone) and `renew`/`extend` return `409 lease_lost` same as any lapsed
-lease — only a fresh `claim` picks the task back up. Reserving itself fails
-`409 lease_lost` (naming the current holder) if you do not hold a live claim
-on the node. The client SessionEnd hook
-(task-cc-client-sessionend-reserve-hook) is the intended caller: it holds the
-transcript, so it is the one thing that can tell "advanced but unfinished"
-(→ reserve) from "finished" (→ release) apart.
+everyone). `reserve` no longer requires a live claim to get it back — like
+`renew`/`extend` (dec-spor-lease-auto-reclaim-and-deadline-exposure), it
+AUTO-RECLAIMS an unheld node (never claimed, or your own claim/reservation
+merely lapsed under it) under the SAME call — a real claim, durable
+`assigned` edge included — and the result reports `reclaimed: true`, instead
+of making you `claim` first and reserve second. The one refusal that
+survives is contention: a LIVE lease held by SOMEONE ELSE is never taken, so
+that still fails `409 lease_lost`, naming the current holder. The client
+SessionEnd hook (task-cc-client-sessionend-reserve-hook) is the intended
+caller: it holds the transcript, so it is the one thing that can tell
+"advanced but unfinished" (→ reserve) from "finished" (→ release) apart.
 
 ### `propose_correction`
 
@@ -418,26 +443,38 @@ verbatim.
 
 ### `render_program`
 
-The program/progress view over `blocks` topology — the birds-eye "where do we
-stand" for a large workstream, auto-derived on demand with no lens authoring.
-Input `{ "id": "<root-node-id>", "max_depth"?, "max_nodes"? }` → `{ "found":
-true, "root_id", "progress": {"total", "done", "active", "blocked", "open",
-"pct", "statuses"}, "count", "truncated"?, "view", "node_ids" }`. Given a root
-node (an umbrella task, a milestone — anything other work `blocks`), the
-server walks its gating tree — every node that blocks it, transitively over
-inbound `blocks` edges — and derives each node's bucket from the same truth
-the queue uses: terminal statuses, supersession, and live `resolves`/`answers`
-edges count as **done** (even while the status field lags — the effective
-status then reads `resolved` with a `resolved_by` ride-along); a node gated by
-its own live unresolved blockers is **blocked**; live unblocked work splits
+The program/progress view over program-membership topology — the birds-eye
+"where do we stand" for a large workstream, auto-derived on demand with no
+lens authoring. Input `{ "id": "<root-node-id>", "max_depth"?, "max_nodes"? }`
+→ `{ "found": true, "root_id", "progress": {"total", "done", "active",
+"blocked", "open", "pct", "statuses"}, "count", "truncated"?, "view",
+"node_ids" }`. Given a root node (an umbrella task, a milestone — anything
+other work joins), the server walks its membership tree: **per node**, it
+prefers inbound `member-of-program` edges where any are declared (the
+all-or-nothing preference, dec-spor-program-membership-per-node-preference)
+and falls back to inbound `blocks` edges where none are declared (the
+original blocks-topology inference, unchanged) — so an unmigrated or
+partially migrated program keeps rendering, and a half-migrated umbrella
+never silently shrinks. `member-of-program`
+(dec-spor-program-membership-dedicated-edge-type) is additive with `blocks`
+— `blocks` keeps meaning only gating, `member-of-program` records pure
+topology — and ships as a graph-resident schema node
+(`schema-edge-member-of-program`), pending activation like any resident
+schema; check `spor schema member-of-program` for its live status rather than
+assuming. Each node's bucket then derives from the same truth the queue uses:
+terminal statuses, supersession, and live `resolves`/`answers` edges count as
+**done** (even while the status field lags — the effective status then reads
+`resolved` with a `resolved_by` ride-along); a node gated by its own live
+unresolved `blocks` predecessors is **blocked**; live unblocked work splits
 **active** vs **open**. `view` is the standard view tree (`as: "tree"` with an
 additive `progress` block); the text content is a progress-bar header plus the
-glyphed gating tree. Shared blockers render once and repeat as `repeat: true`
+glyphed gating tree. Shared members render once and repeat as `repeat: true`
 leaves (counted once); `max_depth`/`max_nodes` caps count skipped branches
-into `truncated`, never silently. A root nothing blocks is a successful empty
-result whose prose says how to model the program (add `blocks` edges from the
-gating tasks). Unknown `id` errors with `{ "found": false, "error":
-"unknown_root" }`. The REST twin is `GET /v1/program/{id}` (§3).
+into `truncated`, never silently. A root with no members is a successful
+empty result whose prose says how to model the program (add `member-of-program`
+or `blocks` edges from the member tasks). Unknown `id` errors with `{ "found":
+false, "error": "unknown_root" }`. The REST twin is `GET /v1/program/{id}`
+(§3).
 
 ### `apply_lens_action`
 
@@ -550,6 +587,7 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | `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; 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 |
+| `POST /v1/nodes/batch` `{ids?\|cursor?}` | `get_nodes` | bounded plural `get_node`: start with 1–100 ids, deduplicated by first occurrence; hidden/absent ids appear only in `missing_ids`. Returns `{nodes, returned_ids, missing_ids, truncated, next_cursor}` with the same per-node read enrichment as the single route, capped at 48 KiB without splitting entries. Resume a truncated logical request by sending only its opaque `cursor`; the final page carries `next_cursor: null` |
 | `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 |
@@ -558,15 +596,18 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | `POST /v1/nodes/{id}/status` `{status}` | scripts, mechanical writers | `set_status` semantics (§1): one-scalar update through the `transitions()` gate. Setting a work node to an in-progress status also CLAIMS it (same lease as `/claim` below) |
 | `POST /v1/nodes/{id}/priority` `{priority}` | `spor priority`, queue triage | `set_priority` semantics (§1): one-scalar human-override update — `p1`/`p2`/`p3` or a clearing form (`none`/`clear`/`""`/`p0`). Server-side read-modify-write (no revision), stamping `priority_by`/`priority_at`/`priority_via` for the audit trail (issue-cc-priority-attribution-gap). Unknown value → `invalid_node` with the allowed list |
 | `POST /v1/nodes/{id}/readiness` `{readiness}` | `spor ready`, triage make-ready pass | `set_readiness` semantics (§1): one-scalar agent-readiness override — `agent` or a clearing form (`none`/`clear`/`""`) to demote back to derived. No hand-settable `human` value (always structurally derived, always wins). Server-side read-modify-write (no revision), stamping `readiness_by`/`readiness_at`/`readiness_via`. Unknown value → `invalid_node` with the allowed value |
-| `POST /v1/nodes/{id}/claim` `{session?}` | `claim`/`set_status` MCP tools, `spor claim` CLI, `spor dispatch` | take the heartbeat-renewed lease (dec-cc-task-claim-lease): writes the durable `assigned` edge once, attributes to `$viewer` from the token (never an argument), and creates the ephemeral lease → `{ok, status, lease: {node_id, by, expires, expires_at, session, claimed_at}, edge}`. A live lease held by ANOTHER person is `409 conflict` naming the holder + expiry (re-claiming your OWN live claim just renews it). `session` scopes the heartbeat (omit to leave it person-scoped, so any of the claimer's sessions may renew — what `spor claim` and `spor dispatch` do, since `claude --bg` self-allocates the run session only at launch; dispatch then renews with the real session once it has read it from `claude agents --json`, dec-spor-dispatch-bg-session-late-bind) |
-| `POST /v1/nodes/{id}/renew` `{session?}` | post-tool heartbeat, `renew` MCP tool, `spor renew` CLI, `spor dispatch` | bump the live lease's expiry only — no commit; the heartbeat that keeps a claim from lapsing. A lapsed/stolen lease is `409` (names the current holder). Person-scoped: any of the claimer's sessions may renew; a `session` binds the lease to that run (`spor dispatch` uses this to bind the captured `claude --bg` session post-launch) |
-| `POST /v1/nodes/{id}/extend` `{ms, session?}` | `extend` MCP tool, `spor extend` CLI | manually stretch your live lease by `ms` milliseconds for a known long idle gap → `{ok, status, lease, capped_to_max?, claim_ttl_max_ms?}`. Bounded by the tenant's `claim_ttl_max` policy (a request past the ceiling caps to it, flagged `capped_to_max`); never shortens a lease. `ms` must be a positive number (`spor extend <id> <2h|45m|…>` parses the human duration client-side). A lapsed/stolen lease is `409 lease_lost` naming the holder |
+| `POST /v1/nodes/{id}/claim` `{session?}` | `claim`/`set_status` MCP tools, `spor claim` CLI, `spor dispatch` | take the heartbeat-renewed lease (dec-cc-task-claim-lease): writes the durable `assigned` edge once, attributes to `$viewer` from the token (never an argument), and creates the ephemeral lease → `{ok, status, lease: {node_id, by, expires, expires_at, session, claimed_at}, expires_in_ms, edge}`. `expires_in_ms` is the renewal horizon relative to when the call ran — skew-free against the caller's own clock (dec-spor-lease-auto-reclaim-and-deadline-exposure). A live lease held by ANOTHER person is `409 conflict` naming the holder + expiry (re-claiming your OWN live claim just renews it). `session` scopes the heartbeat (omit to leave it person-scoped, so any of the claimer's sessions may renew — what `spor claim` and `spor dispatch` do, since `claude --bg` self-allocates the run session only at launch; dispatch then renews with the real session once it has read it from `claude agents --json`, dec-spor-dispatch-bg-session-late-bind) |
+| `POST /v1/nodes/{id}/renew` `{session?}` | post-tool heartbeat, `renew` MCP tool, `spor renew` CLI, `spor dispatch` | bump the live lease's expiry — no commit, UNLESS the lease had lapsed: renew then AUTO-RECLAIMS it first, under the same per-node lock (a real claim, durable `assigned` edge included), rather than refusing (dec-spor-lease-auto-reclaim-and-deadline-exposure) → `{ok, status, lease, expires_in_ms, reclaimed?}`, `reclaimed: true` marking a re-established lease apart from an ordinary bump. A LIVE lease held by SOMEONE ELSE is still `409 lease_lost`, naming the current holder. Person-scoped: any of the claimer's sessions may renew; a `session` binds the lease to that run (`spor dispatch` uses this to bind the captured `claude --bg` session post-launch) |
+| `POST /v1/nodes/{id}/extend` `{ms, session?}` | `extend` MCP tool, `spor extend` CLI | manually stretch your live lease by `ms` milliseconds for a known long idle gap, auto-reclaiming first if the lease had lapsed (same discipline as `renew`, reported `reclaimed: true`, dec-spor-lease-auto-reclaim-and-deadline-exposure) → `{ok, status, lease, expires_in_ms, reclaimed?, capped_to_max?, claim_ttl_max_ms?}`. Bounded by the tenant's `claim_ttl_max` policy (a request past the ceiling caps to it, flagged `capped_to_max`); never shortens a lease. `ms` must be a positive number (`spor extend <id> <2h|45m|…>` parses the human duration client-side). A LIVE lease held by SOMEONE ELSE is `409 lease_lost` naming the holder |
 | `POST /v1/nodes/{id}/release` | `release` MCP tool, `spor release` CLI | drop the lease AND retire the durable `assigned` edge, returning the node to the pool. Idempotent (releasing a node you hold no lease on still succeeds, cleaning up any lingering `assigned` edge of yours); releasing a claim someone else holds is `409` naming the holder |
-| `POST /v1/nodes/{id}/reserve` `{session?}` | `reserve` MCP tool, client SessionEnd hook (task-cc-client-sessionend-reserve-hook) | convert your live claim into an owner-exclusive resumption reservation (dec-cc-task-resumption-reservation) when a session ends cleanly with the task advanced but unfinished → `{ok, status: "reserved", lease, grace_window_ms}`. Drops the heartbeat, re-points `expires` at a grace-window expiry (~2 days, tenant policy — a timestamp, not a graph edge), and keeps the durable `assigned` edge so a steward view still reads "reserved by you"; `rankQueue` floats it to the top of the owner's queue while dropping it from teammates' actionable lists until the grace window lapses (full pool, everyone) or the owner claims/renews/extends it within that window (drops the `reserved` flag, back to a normal heartbeat lease). `409 lease_lost` (naming the holder) if you do not hold a live claim |
+| `POST /v1/nodes/{id}/reserve` `{session?}` | `reserve` MCP tool, client SessionEnd hook (task-cc-client-sessionend-reserve-hook) | convert your live claim into an owner-exclusive resumption reservation (dec-cc-task-resumption-reservation) when a session ends cleanly with the task advanced but unfinished, auto-reclaiming first if the node is unheld — never claimed, or your own claim/reservation merely lapsed under it (reported `reclaimed: true`, dec-spor-lease-auto-reclaim-and-deadline-exposure) → `{ok, status: "reserved", lease, expires_in_ms, grace_window_ms, reclaimed?}`. Drops the heartbeat, re-points `expires` at a grace-window expiry (~2 days, tenant policy — a timestamp, not a graph edge), and keeps the durable `assigned` edge so a steward view still reads "reserved by you"; `rankQueue` floats it to the top of the owner's queue while dropping it from teammates' actionable lists until the grace window lapses (full pool, everyone) or the owner claims/renews/extends it within that window (drops the `reserved` flag, back to a normal heartbeat lease). `409 lease_lost` (naming the holder) only when SOMEONE ELSE holds a live claim — the one boundary that still matters |
+| `POST /v1/queue/release` `{session?}` | session-end handoff drain; bulk-lease clients | **`releaseAll`**: release every live claim the caller holds, optionally narrowed to one `session`, in ONE round-trip instead of N sequential `POST /v1/nodes/{id}/release` calls (task-spor-queue-bulk-release-for-handoff-drain). Delegates each drop to the same per-node `release` logic — durable `assigned` edge retirement included — so it only ever enumerates and releases the CALLER's own leases; a node re-claimed by the caller under a different session, or held by someone else, between the enumeration and its turn simply isn't counted as released, never a `409` → `{ok: true, status: "released", released: [ids], count}`. Unlike `claimAll`/`renewAll` below there is no holder mismatch to report, so it carries no `failed` array |
+| `POST /v1/queue/claim` `{ids, session?}` | `spor dispatch` claiming a working set; bulk-lease clients | **`claimAll`**: claim a whole working set in ONE round-trip instead of one `POST /v1/nodes/{id}/claim` per node (task-spor-bulk-claim-renew-apis). `ids` is REQUIRED (unlike `renewAll` below there is nothing to enumerate — a claim creates the lease it would have enumerated), bounded and deduped server-side. Each id runs through the same per-node `claim` logic, so one holder's node losing the race to another claimant lands in `failed` (`already_claimed`, naming the holder) while the rest of the batch still claims — a partial batch is reported, never rolled back → `{ok: true, status: "claimed"\|"partial"\|"refused", count, claimed: [ids], leases: [...], failed: [{node_id, code, message, holder?}], expires_in_ms?}`. `expires_in_ms` is the batch's own renewal horizon — the soonest deadline among the leases that landed, omitted (not nulled) on an empty or wholly-refused batch. `status` reads `"partial"` when some items landed and some didn't, `"refused"` when the whole batch was refused — **`ok: true` only means the call was well-formed; read `failed` for what didn't land, never `ok` alone**. The dispatch nonce and `force` (accepted on the singular `/claim`) are deliberately NOT accepted here — a dispatch tags a single agent launch at a single node, so that stays on the singular door |
+| `POST /v1/queue/renew` `{ids?, session?}` | post-tool heartbeat (batched), `spor dispatch`, bulk-lease clients | **`renewAll`**: the heartbeat for a whole working set in ONE round-trip (task-spor-bulk-claim-renew-apis) — what the client-side claim heartbeat uses instead of one `POST /v1/nodes/{id}/renew` per held node (task-spor-client-heartbeat-bulk-renew), through the **`ids`-omitted arm, with no `session` either** (dec-spor-heartbeat-adopts-blanket-renew-arm): a beat renews the person's whole live working set and never re-acquires what dropped out of it, and it omits `session` because in this arm that field is a FILTER, so sending it would skip the leases claimed outside a session (`spor claim`, `spor dispatch`'s pre-launch claim) and let them lapse mid-session. Two consequences ride with that choice: a beat renews the person's leases in EVERY project (this arm takes no project scope), so a lease nobody releases stops self-healing back into the pool at its TTL while its owner keeps writing anywhere; and since this arm SELECTS on `session` rather than stamping it, a lease's session binding is no longer re-pointed at the last editing session. Two modes, and they differ on auto-reclaim (dec-spor-lease-auto-reclaim-and-deadline-exposure — the ONE exemption, whose intended caller is the heartbeat): **`ids` omitted** enumerates every LIVE Tier-1 lease this caller holds (optionally narrowed to one `session`) and renews them all — the motivating case, one call per heartbeat instead of one per held node — but NEVER reclaims: its contract is "renew what you hold" from a snapshot, so a lease that lapsed (or was taken) lands in `failed` as `lease_lost` and simply drops out of the set, never silently re-acquired; **`ids` supplied** renews exactly that named set (bounded/deduped) with the SAME reclaim semantics as the singular `/renew` — a lapsed lease is auto-reclaimed (a real claim, durable `assigned` edge included), its id lands in `reclaimed`, and only a lease held by someone else still lands in `failed` as `lease_lost` (naming the holder). `session` is forwarded unchanged exactly as the singular `/renew` does — one contested node never costs the whole working set its heartbeat → `{ok: true, status: "renewed"\|"partial"\|"refused", count, renewed: [ids], leases: [...], failed: [...], expires_in_ms?, reclaimed?, skipped_other_session?, skipped_reserved?}`. `expires_in_ms` is the batch's own renewal horizon (soonest deadline among the leases that landed, omitted on an empty/wholly-refused batch); `reclaimed` (explicit-`ids` arm only) lists the ids whose lease had lapsed and was just re-established, so a batch reading "N/N renewed" doesn't hide that one of them was silently taken back off the pool. The two `skipped_*` counts ride ONLY on the enumerate arm: `skipped_other_session` names live leases excluded because they're bound to a different session (a zero renewed count there means "not under this session", not "you hold nothing"), `skipped_reserved` names Tier-2 resumption reservations a blanket heartbeat deliberately leaves parked at their grace-window expiry rather than demoting to a Tier-1 horizon |
 | `POST /v1/nodes/{id}/commits` `{repo, sha}` | post-tool / link-commits | `link_commit`: append `repo@sha` to the node's `commits:` list (kebab-case repo slug, 7–40 lowercase hex, ≤40 commits per node); idempotent, prefix-aware dedup |
 | `GET /v1/commits/{sha}?repo=` | `spor blame`/`commits` CLI verb; sessions doing git archaeology | sha → nodes lookup over the `commits:` fields (≥7 hex, abbreviated or full); each match carries `{repo, sha, id, type, title, summary, status, project}` — blame a line, get the why. The `spor blame <sha> [--repo <slug>]` CLI verb (alias `spor commits <sha>`) wraps this remotely and runs the same lookup over the local graph in local mode (`lib/query.js` `lookupCommit`) |
 | `GET /v1/changes?since=&project=&limit=` | `recent_changes`'s REST twin; audit review | the remote audit trail: a git-log projection over `nodes/` → `{changes: [{id, change, commit, date, committed_by, type, title, authored_via, author}], count, head, since, generated_at}`, newest change per node first. `since` is a 7–40 hex sha (`sha..HEAD`) or a date/relative phrase git understands (`--since`); an unresolvable sha is `422`. `project` scopes to one project's nodes (deletions are omitted when scoped, their project being gone). `limit` bounds nodes returned (default 100, **max 500**). Each entry's `authored_via` is the current machine-vs-human signal (`capture`/`distill`/`gardener` = machine). Lets a remote client review what agents wrote without the whole `/v1/export` tarball |
-| `POST /v1/capture` | distill, /spor:defer | `capture` semantics: `{text, context: {project, project_explicit?, during, blocks?, needed_by?}, source?, idempotency_key?}` → ingestion model + validate + commit → `{status, ids, nodes, summary, warnings}`. `source: "distill"` marks backstop captures in the journal. `idempotency_key` (client-generated; equivalently the `Idempotency-Key` header) guards the whole capture against the timeout-then-server-completes race (issue-cc-capture-transport-idempotency): a key the server has already seen returns the original result instead of re-ingesting, so a client that aborted at its read timeout but landed server-side does NOT double-write when the spooled body is replayed by `spor drain`. The client puts the key in the BODY so the verbatim outbox replay carries it for free (issue-spor-add-cli-duplicate-on-timeout-drain). `context.blocks` (a node id, must exist) and `context.needed_by` (`YYYY-MM-DD`) declare a cross-project dependency (task-cc-xproject-dependency-loop): set `context.project` to the SERVING project and the server attaches a `blocks` edge to the requester + the deadline deterministically (not via the model) onto the primary node. A missing `blocks` target is `404`; a non-date `needed_by` is `422` — both rejected before any model call. `context.project_explicit` (additive boolean, task-spor-thread-explicit-project-flag) distinguishes a user-declared `context.project` from an ambient cwd default: only a literal `false` silences the fold-mismatch warning on a cross-project capture; **absent means explicit** (old-client back-compat, so a pre-flag client keeps today's warn-on-mismatch behavior) |
+| `POST /v1/capture` | distill, /spor:defer | `capture` semantics: `{text, context: {project, project_explicit?, during, blocks?, needed_by?}, source?, idempotency_key?}` → ingestion model + validate + commit → `{status, ids, nodes, summary, warnings}`. `source: "distill"` marks backstop captures in the journal. `idempotency_key` (client-generated; equivalently the `Idempotency-Key` header) guards the whole capture against the timeout-then-server-completes race (issue-cc-capture-transport-idempotency): a key the server has already seen returns the original result instead of re-ingesting, so a client that aborted at its read timeout but landed server-side does NOT double-write when the spooled body is replayed by `spor drain`. The client puts the key in the BODY so the verbatim outbox replay carries it for free (issue-spor-add-cli-duplicate-on-timeout-drain). `spor add --dedupe-key <key>` promotes a CALLER-chosen key into that slot instead of the per-invocation UUID (task-spor-add-dedupe-key-first-class), so a caller that re-files the same logical capture across separate invocations — a cron monitor re-alerting on one onset — dedupes too: within the window the repeat replays and the response carries `idempotent_replay: true`. The key is caller-supplied only, never derived from the text, and must match the server's key grammar (`^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$`) — the client rejects anything else rather than let the server silently run the capture unguarded. `context.blocks` (a node id, must exist) and `context.needed_by` (`YYYY-MM-DD`) declare a cross-project dependency (task-cc-xproject-dependency-loop): set `context.project` to the SERVING project and the server attaches a `blocks` edge to the requester + the deadline deterministically (not via the model) onto the primary node. A missing `blocks` target is `404`; a non-date `needed_by` is `422` — both rejected before any model call. `context.project_explicit` (additive boolean, task-spor-thread-explicit-project-flag) distinguishes a user-declared `context.project` from an ambient cwd default: only a literal `false` silences the fold-mismatch warning on a cross-project capture; **absent means explicit** (old-client back-compat, so a pre-flag client keeps today's warn-on-mismatch behavior) |
 | `POST /v1/distill/report` | distill | sweep telemetry, journal-only (no store mutation): `{facts, captured?, spooled?, rejected?, project?, session?}` → `{status: "reported"}`; zero-fact sweeps report too |
 | `POST /v1/corrections` | /spor:correct | `propose_correction` semantics → 201 `{status, id, revision, warnings}` |
 | `GET /v1/queue?project=&assignee=&type=&exclude_type=&limit=&offset=` | /spor:next, session-start | the ranked decision queue: `{items, count, offset, returned_count, total_count, truncated, next_offset, counts_by_type, counts_by_project, counts_by_suggest, muted?, dormant?, questions, asked, findings, pending, reviews, policy?, generated_at}` — items retired by a live resolves/answers edge are excluded; items hidden by the viewer's `queue_mute` or parked by a future `wake:` date (QUEUE.md §4) are counted, never silently dropped; `questions`/`findings`/`pending` are the routed-to-me-plus-unrouted views for the authenticated identity, `asked` is the questions you filed, and `reviews` is the nodes whose review is requested of you (an open `review-requested` edge to your person node — explicitly targeted, no unrouted fallback). `limit` is the page size (default 20, **max 100**, clamped not rejected) and `offset` skips that many items in the ranked order (default 0); the `counts_*`/`total_count` aggregates always cover the FULL ranked set regardless of the page, so one call answers "how many issues vs tasks" without paging, while `truncated`/`next_offset` let a client walk the rest by re-requesting with `offset=next_offset` until `next_offset` is null. Pagination is offset over a point-in-time ranked slice (the queue re-ranks every call), not a cursor — it resumes the same slice only across an unchanged ranking. `project` resolves through the shared up-resolution (dec-spor-queue-slug-resolves-to-grouping): a bare repo slug unions its home-project grouping's member queues, the repo NODE id (`repo-<slug>`) pins one repo, a grouping id (`proj-<slug>`) is used directly; **omitting `project` is the cross-project firehose** (every repo's queue at once). `assignee=<person-id>` scopes to the work that person carries (their `assigned`/`stewards` edges) — a manager's "who is carrying what"; `assignee=me` binds to the caller (empty if the token maps to no person node). `type=`/`exclude_type=` (comma-separated, repeatable) whitelist/blacklist node types from the ranking (exclude wins on overlap) — a hard scope filter applied before scoring, so the aggregates describe the filtered queue (task-cc-queue-filtering-enhancements) |
@@ -574,7 +615,7 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | `GET /v1/metrics/capture?since=` | the cross-author capture-discipline eval harvest (task-spor-tenant-capture-metrics-export) | capture-discipline aggregates for an **opted-in** deployment — the same kernel the dogfood CLI runs (`lib-engine/kernel/capture-metrics.js`), computed server-side over the resident graph plus the FULL request journal (every rotated `server.log` segment). Three gates stack (dec-spor-tenant-metrics-aggregates-only): the per-machine opt-in env `SPOR_METRICS_EXPORT` (unset → the route 404s, so a never-opted tenant shows no surface), admin auth (stewards→root, 403), and **unconditional redaction** — the body carries counts/rates only: by-identity keys are stable per-tenant pseudonyms (`author-<hash12>`, salted at `cache/metrics-salt` so per-author trends survive across windows), closure entries keep `{edge, latency_days}` but drop node ids, and id lists reduce to `open_count`/`slug_smell_count`. No journal lines, node bodies, or capture prose ever exit. `?since=YYYY-MM-DD` bounds the window (malformed → `422`) |
 | `POST /v1/questions` `{text, title?, mentions?, project?}` | ask_question's REST twin | file a question node; deterministically routed to the steward of the closest relevance-neighborhood node, unrouted if none → 201 `{status, id, project, routed_to, via, asker, revision, warnings}`. `project` is derived from the relevance neighborhood (then the asker's home project) unless an explicit `project` slug overrides it — pass that for a mention-less question (a dispatched agent injects its session project); a malformed slug → 400 |
 | `POST /v1/gardener` | ops cron / on demand; `spor admin gardener` | run a gardener sweep now; findings filed as queue items → `{checked, filed, resolved, skipped, generated_at}` (`filed`/`resolved`/`skipped` are id lists, `checked` a count). The `spor admin gardener [--json]` CLI verb is the shell front-door (remote-only — the server owns the gardener); authenticated but **not** admin-gated server-side today (unlike `/v1/backup`), so any valid team token can trigger it — the verb still surfaces a 403 as an admin-privilege (stewards→root) hint for a deployment that adds the gate |
-| `GET /v1/program/{id}?format=json\|text&depth=&max_nodes=` | program oversight, /spor:brief follow-ups | the program/progress view (`render_program`'s REST twin, one kernel behind both doors): the gating tree of everything that `blocks` `{id}` transitively, with resolution-derived progress (`{progress: {total, done, active, blocked, open, pct, statuses}}` on the view root; done = terminal status / supersession / live resolves-answers edge, exactly the queue's truth). JSON view tree by default, `?format=text` for the terminal rendering; `depth`/`max_nodes` bound expansion and count skipped branches into `truncated`, never silently. 404 for an unknown id |
+| `GET /v1/program/{id}?format=json\|text&depth=&max_nodes=` | program oversight, /spor:brief follow-ups | the program/progress view (`render_program`'s REST twin, one kernel behind both doors): the membership tree of everything gating `{id}`, preferring inbound `member-of-program` edges per node and falling back to inbound `blocks` where none are declared (see `render_program`, §2, for the per-node preference and the pending-activation caveat), with resolution-derived progress (`{progress: {total, done, active, blocked, open, pct, statuses}}` on the view root; done = terminal status / supersession / live resolves-answers edge, exactly the queue's truth). JSON view tree by default, `?format=text` for the terminal rendering; `depth`/`max_nodes` bound expansion and count skipped branches into `truncated`, never silently. 404 for an unknown id |
 | `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) |
@@ -681,7 +722,15 @@ anything with a token.
   from `claude agents --json` and binds it via `POST /v1/agents/session` (§3) — the
   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.
+  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.
 - **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

@@ -97,6 +97,26 @@ Rules:
   work instead of in one person's calendar. Everything else (compiles,
   briefings, edges) sees a dormant node normally.
 - One fact per node. If you're writing "also" a lot, split it.
+- A node file the parser cannot read is **skipped, not fatal**
+  (dec-spor-buildgraph-per-node-fault-isolation). `loadGraph` isolates each
+  file's parse: a fault leaves that node out of the graph entirely — no node,
+  no edges, no search doc, and no registry override if it was a `type: schema`
+  node — and the rest of the graph loads normally, so one corrupt file can't
+  refuse a whole graph's boot. Every skip is named on stderr
+  (`spor: SKIPPED unparseable node file <path>: <why>`) and listed on
+  `graph.skipped`; an edge pointing at a skipped node simply dangles. Treat the
+  warning as corruption to fix, not noise to live with: `spor validate` is the
+  gate, and reports the same files as an **error** (exit 1), naming the
+  offending line — a node the loader drops is missing from every briefing,
+  digest and queue, so a lint that passed would be a lie. Isolation covers
+  malformed FILES only; a bug in the parser itself still throws. The same
+  isolation also covers a file `readdirSync` lists but `readFileSync` then
+  fails to read at all — EACCES, or an ENOENT race against a live graph home
+  the server/gardener writes concurrently
+  (issue-spor-read-graph-files-single-file-abort) — which rides the same
+  `graph.skipped` record under a distinct stderr wording
+  (`spor: SKIPPED unreadable node file <path>: <why>`, since the file never
+  reached the parser).
 
 ## Node types and id prefixes
 
@@ -122,6 +142,48 @@ Rules:
 | project    | `proj-`   | a grouping above repos; owns its member repos via inbound `grouped-under` edges (below) |
 | lens       | `lens-`   | a saved view over the graph — declarative `## query`/`## render` json blocks, an optional sandboxed `## custom` js block, and an optional `## actions` block; `traversable: false` and `capturable: false` (see "Lenses") |
 
+## Accreting running-log artifacts
+
+An `artifact` node is sometimes used as a **running log** — one node a session
+appends a data point to over and over, rather than one fact written once
+(task-cc-dogfood-capture-discipline's `art-cc-capture-discipline-results` is the
+prototype: one entry per dogfood session). That pattern collides with the
+server's per-node body cap (API.md §1: body ≤ 8KB) — the log scales for a
+session or two, then every further append is rejected
+(issue-cc-accreting-log-body-cap-collision). The cap itself stays: it is what
+keeps "one fact per node" true for every OTHER node type, and weakening it for
+one pattern would just move the failure mode elsewhere.
+
+The fix is to let the log **roll over**, not to grow one node forever:
+
+- When a running-log artifact is at or near the cap, start a new artifact node
+  for the next stretch of entries — same subject, new id with an incrementing
+  suffix (`art-cc-capture-discipline-results` → `art-cc-capture-discipline-results-2`
+  → `-3`, …) and a title noting it ("part 2 (2026-07 onward)").
+  `spor validate` warns once a node's body passes ~90% of the cap, specifically
+  so there is still room to make this move before a write is rejected outright
+  — don't wait for the hard failure. (That early warning belongs to `spor
+  validate` — including the SessionEnd distiller's own lint pass, which logs it
+  to `journal/distill.log` — and it is not a per-write gate: `spor add` doesn't
+  check it at all, and the graph-wide lint `spor put-node` runs *before* the
+  write it gates deliberately does not ask for it — nor does the server
+  gardener's sweep — because on a finished node "approaching the cap" is advice
+  nobody can act on. So run `spor validate` periodically on a running log's
+  home graph rather than relying on the write itself to flag it. A body already
+  OVER the cap is a different matter and warns everywhere: the server
+  re-validates on every write, so an
+  over-cap node is frozen until it is split.)
+- Link the new part back to the one it continues with a `derived-from` edge
+  (this node was produced from — i.e. continues — the target), and update the
+  earlier part's summary to say it is superseded/continued so a reader
+  landing on it knows to follow the edge forward.
+- Anything that reads "the log" (a task's `derived-from`/`relates-to` edge, a
+  briefing, a human) should expect a chain of parts, not one node — walk
+  `derived-from` to find the latest.
+
+This is the same shape as any other multi-part document; it just needed
+naming so it stops being reinvented ad hoc per artifact.
+
 ## Completing work needs a durable why (the resolver gate)
 
 A `task` reaching `done`, or an `issue` reaching `resolved`, requires a **live
@@ -1006,6 +1068,7 @@ against a query language, never drafted from a capture or a distilled transcript
 | `decided-in`     | 0.9    | the choice in this node was made in the target   |
 | `resolves`       | 0.9    | this node fixes/closes the target                |
 | `blocks`         | 0.7    | target cannot proceed until this node does       |
+| `member-of-program` | 0.7 | this node is a member of the target program umbrella (inverse `has-program-member`); pure topology, independent of gating; `capturable: false` |
 | `answers`        | 0.7    | this node answers that question (inverse `answered-by`); pulls the answer through the asker's next compile |
 | `assigned`       | 0.5    | work is assigned to this person OR agent (the explicit-routing edge; an agent target may carry a `profile:` per-assignment override) |
 | `reviewed-by`    | 0.5    | this person reviewed and approved the node — counts toward a policy quorum |
@@ -1023,6 +1086,29 @@ against a query language, never drafted from a capture or a distilled transcript
 | `compiled-for`   | —      | briefing → its task/query (provenance only)      |
 | `shaped-by`      | —      | briefing → corrections applied (provenance only) |
 
+`member-of-program` is the dedicated program-membership edge
+(dec-spor-program-membership-dedicated-edge-type), written from the member's
+perspective like `blocks`: `member -> umbrella`. It is **additive with `blocks`,
+never a replacement**: `blocks` keeps meaning only gating (this node gates the
+umbrella's completion), while `member-of-program` records pure topology (this
+node belongs to the program) — a member usually carries both, but a
+non-gating member carries only this edge, and a prerequisite that gates the
+umbrella without being part of its program carries only `blocks`, a
+distinction blocks-topology inference alone could never draw. Readers
+(`render_program`, the gardener's program-completion pass) prefer these edges
+**per node**: at a node with any inbound `member-of-program` edges, those are
+its members; at a node with none, its members are still inferred from inbound
+`blocks` (today's behavior, unchanged), so an unmigrated or partially migrated
+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.
+`capturable: false` — the distiller and capture nudge never emit it; only a
+person or an agent working the program explicitly wires membership.
+
 `answers`, `assigned`, `stewards`, `member-of-org`, and `routed-to` are person-graph
 edges of Tier-2 question routing; they ship in the seed pack and are
 documented under "People, routing, and onboarding" above. `assigned` and
@@ -1080,8 +1166,9 @@ edge schema): **aliases** — same-direction synonyms renamed in place
 `supercedes` → `supersedes`, `approved-by` → `reviewed-by`) — and **inverse
 labels** — the edge read from
 the target's side, flipped onto the target node on write (`blocked-by` →
-`blocks`, `answered-by` → `answers`, `superseded-by` → `supersedes`).
-Hand-written nodes should still use the canonical forms.
+`blocks`, `answered-by` → `answers`, `superseded-by` → `supersedes`,
+`has-program-member` → `member-of-program`). Hand-written nodes should still
+use the canonical forms.
 
 ## Correction nodes
 

package/QUEUE.md

@@ -635,11 +635,38 @@ Two gate checks joined the sweep with the edge-write UX work
 (issue-cc-edge-write-ux-friction):
 
 - **inert-gate** — a `blocks` edge whose source has reached a terminal
-  status while its target is still live. The gate has cleared but the
-  graph still says "blocked": the finding (on the target's side,
-  `find-inert-gate-<source>-<target>`) says the target can proceed — drop
-  the edge or pick up the work. This is the "the blocker was already done"
-  discovery made manually during dogfooding, mechanized.
+  status while its target is still live, claimed by no one, and not itself
+  a *program* (more than one node hanging beneath it in the membership
+  tree `render_program` walks — per node, preferring inbound
+  `member-of-program` edges where any are declared and falling back to
+  inbound `blocks` where none are, dec-spor-program-membership-per-node-preference;
+  `member-of-program` ships as a graph-resident schema node pending
+  activation, so this fallback is today's live behavior). The gate has
+  cleared but the graph still says "blocked": the finding (on the target's
+  side, `find-inert-gate-<source>-<target>`) says the target can proceed —
+  drop the edge or pick up the work. This is the "the blocker was already
+  done" discovery made manually during dogfooding, mechanized. It carries a
+  mechanical `remove_edge` remedy, so a batch `resolve_finding` can drop
+  the stale edge without a human re-deriving the fix
+  (issue-spor-gardener-mechanical-remediation-gap).
+- **gates-cleared** — the same cleared-gate situation, but on a dependent
+  that *heads a program*: every member in its membership tree has landed,
+  nothing live gates it anywhere in that tree, and nobody has claimed it.
+  Firing one inert-gate per membership edge would hand a batch
+  `resolve_finding` a `remove_edge` remedy for edges that are the
+  program's own progress record — `render_program` reads exactly those
+  edges (explicit inbound `member-of-program` per node, or inbound `blocks`
+  where none are declared) to render the gating tree, so mechanically
+  dropping them would silently erase a finished program's membership.
+  Instead the gardener files ONE `find-gates-cleared-<target>` finding on
+  the umbrella itself, naming its members, and deliberately gives it **no
+  remedy**: resolve_finding refuses the kind outright, so closing the
+  umbrella out (a resolver plus a terminal-status flip) or picking up
+  whatever closing work remains is a human judgment call, not a mechanical
+  fix (issue-spor-inert-gate-remedy-destroys-program-topology,
+  dec-spor-finished-program-files-one-non-mechanical-gates-cleared-finding).
+  A program with anything still live anywhere in its tree is suppressed
+  outright — neither finding fires until every level has cleared.
 - **unedged-gate** — a live decision whose body uses gate vocabulary
   (`gate`/`gated`/`blocks`/`blocked`) and literally mentions two or more
   *live, queueable* node ids, none of which are connected to another

package/README.md

@@ -261,6 +261,92 @@ Templates can use placeholders such as:
 dispatched node's own frontmatter fields (blank in free-text or `--backfill`
 dispatch, where there is no target node).
 
+A dispatched agent runs beyond the launcher's own lifetime — a Claude Code
+agent detaches into its own background-agent daemon, a Codex agent into a
+supervisor Spor owns (more on that below) — so `spor dispatch` records every
+run it launches and `spor runs` reports how each one ended:
+
+```bash
+spor runs
+spor runs --node issue-86
+```
+
+Each run resolves to a terminal state — `done`, `failed`, `vanished` (it stopped
+mid-turn, or it ended in a way nothing can be attributed to), or `failed_launch`
+— with the reason, and a class that keeps environment failures such as provider
+credit exhaustion separate from failures of the work itself. A Claude Code run
+that bound a session also carries a pointer to its transcript; a Codex run's
+equivalent evidence is its own log instead. One that never bound a session says
+so rather than borrowing a transcript from whatever else ran in that checkout.
+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.
+
+```bash
+spor dispatch issue-86 --profile profile-codex-sol
+```
+
+A profile looks like this:
+
+```markdown
+---
+id: profile-codex-sol
+type: profile
+title: Codex / gpt-5.6-sol
+summary: Codex harness running gpt-5.6-sol — general-purpose dispatch profile.
+status: active
+harness: codex
+model: gpt-5.6-sol
+mcp: [spor]
+---
+```
+
+Profiles are authored deliberately rather than captured from a transcript —
+write one yourself with `spor put-node`, or reuse one your team has published.
+An `agent` node can also carry a default profile (a `uses-profile` edge), so
+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,
+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.
+
+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:
+
+```text
+run:     3f9a2c1e-... (Codex supervisor running)
+log:     ~/.spor/journal/dispatch/3f9a2c1e-....log
+report:  ~/.spor/journal/dispatch/3f9a2c1e-....report.md
+session: 019f7a51-...
+```
+
+`log` is the full JSONL progress stream; `report` is Codex'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:
+
+```bash
+spor runs --node issue-86            # human-readable: state, why, log path
+spor runs --node issue-86 --json     # add .runs[0].report_path for the final message
+```
+
 ## Local mode
 
 By default, Spor can run entirely on your machine.