@sporhq/spor 0.29.1 → 0.29.3

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

package/.codex-plugin/plugin.json

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

@@ -338,6 +338,13 @@ commits. Output `{ "status": "captured|pending", "node_ids": [...],
 text fit no schema (or failed validation twice) and was preserved as a
 `cap-…` capture-pending node — ingestion-quality failures never lose text.
 Only an unreachable ingestion model is an error (`ingestion_unavailable`).
+An optional `auto_write_id` additionally rides the result when the capture
+landed on a mistyped ELABORATE target via the flag-gated near-miss fold
+(`SPOR_GARDENER_AUTO_WRITE`, task-spor-capture-near-miss-ledger-and-undo) — a
+merged capture-pending close or a body-append elaboration onto the matched
+node, either way written through the gardener's reversible auto-write class
+rather than a bare status/body edit. It is the ledger id `undo_auto_write`
+takes to reverse that specific write; absent when no near-miss fold fired.
 
 ### `show_queue`
 
@@ -418,10 +425,14 @@ queue tool for hosts (and turns) that just need the answer.
 
 File a question the graph could not answer. Input `{ "text": "<the
 question>", "title"?: "<short title>", "mentions"?: ["<node id>", ...],
-"project"?: "<slug>" }` (routing considers `mentions` first). The question
-becomes a durable node, deterministically routed to the steward of the closest
-relevant node (unrouted if none matches), and joins the decision queue until
-answered. Answer by writing a node with an `answers` edge to the question.
+"project"?: "<slug>", "to"?: "<person node id>" }` (routing considers
+`mentions` first, unless `to` is given). The question becomes a durable node,
+deterministically routed to the steward of the closest relevant node (unrouted
+if none matches), and joins the decision queue until answered. `to` names a
+person node to route to directly, ahead of every inferred signal
+(`routed_by: "explicit"`); it must name an existing person node, and naming
+the asker themselves falls through to ordinary routing with a warning instead
+of a dead-end. Answer by writing a node with an `answers` edge to the question.
 
 By default the question's project is derived from its relevance neighborhood
 (its `mentions`, then the compiler's picks), falling back to the asker's home
@@ -522,6 +533,40 @@ rendered digest/briefing hides. The tool returns the changed nodes as data;
 the model writes the prose summary (no LLM on this path). It is the MCP twin of
 `GET /v1/changes` (§3), sharing one core so the two surfaces never drift.
 
+### `list_auto_writes`
+
+Read-only view into the gardener's REVERSIBLE AUTO-WRITE ledger
+(dec-spor-gardener-reversible-auto-write-class): every write the gardener (or
+the capture near-miss fold, task-spor-capture-near-miss-ledger-and-undo) made
+on its own at high confidence under the per-org `SPOR_GARDENER_AUTO_WRITE`
+flag, newest first. Input `{ "days"?, "limit"?, "node"? }` (`node` filters to
+one subject/target id) → `{ "enabled", "via",
+"days", "since", "count", "total", "auto_writes": [{id, ts, event: "apply",
+kind, node, verdict_id, judgment, confidence, undone}] }` (no `generated_at`
+— that's REST-only, below). `enabled` echoes the flag so an empty ledger
+reads differently from an unarmed gardener; `undone` is the reversal record
+(`{id, ts, by, via}`) or `null` while the write stands. The MCP twin of
+`GET /v1/gardener/auto-writes` (§3).
+
+### `undo_auto_write`
+
+The mechanical undo of one or more gardener auto-writes by their ledger id
+(from `list_auto_writes`) — same batch contract as finding remediation: one
+`id` or `ids`, per-item outcomes, one item's refusal never blocks the rest.
+Input `{ "id"?, "ids"? }` → `{ "status": "undone", "results": [...], "count",
+"undone", "skipped", "failed" }`, each result `{ok, auto_write_id, kind,
+node?, status?: "undone"|"already_undone", undo_id?, code?, message?,
+details?}`. `already_undone` is the idempotent re-run of an undo already
+applied; a refusal (`not_in_place` — the node changed by hand or by a later
+auto-write since; `not_found`; `not_reversible` — a ledger kind this server
+has no undo registered for) leaves the node untouched. A `body_append` undo
+(the capture near-miss fold's elaboration append) additionally re-files the
+stripped text as a fresh `cap-…` capture-pending node instead of discarding
+it, so an undo never drops a capture from triage — its id rides back as
+`refiled` on that item; if the re-file itself fails, the undo still lands and
+a line naming the ledger entry rides back in `warnings` instead. The MCP twin
+of `POST /v1/gardener/auto-writes/undo` (§3).
+
 ### `analytics`
 
 Work-flow analytics over the team graph — the created-vs-completed view a
@@ -593,7 +638,7 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | Endpoint | Typical caller | Semantics |
 |---|---|---|
 | `GET /v1/status` | session-start, monitoring | `{node_count, projects: {...}, head, uptime, metrics}`; doubles as the health check. Graph counts/projects are the viewer-visible projection. `?titles=1` adds viewer-visible `titles: [{id, type, project, title}]` — the one-round-trip graph index the distiller dedups against |
-| `GET /v1/schema` | `spor schema`, agents introspecting the contract | the live schema registry as data (task-spor-schema-introspection-surface; server half task-spor-server-schema-endpoint): `{default_edge_weight, node_types: [{type, description, prefix, always_on, traversable, capturable, queueable, non_resolving, terminal, inert, inert_inherited, vocabulary, completion, resolver_required, resolution, hooks, schema_id, schema_version, source}], edge_types: [{type, description, weight, weight_default, inverse_label, aliases, capturable, hooks, ...}], queue_policy, policies, registers, stale_overrides, alias_collisions}` — the seed pack MERGED with graph-resident `type: schema` overrides, each entry tagged by `source` (`seed`/`graph`/`native`) and the active schema node's id+version. `?code=1` embeds each hook's source under `code: {name: src}` (omitted by default to keep the response lean). The registry IS the contract (norm-cc-registry-is-contract); this read surface closes the failure mode of agents reverse-engineering it from `lib/seed/` files (which miss resident overrides). `vocabulary`/`completion`/`resolver_required` are the declarative completion policy (task-spor-registry-declarative-terminal-status-policy): the closed status enum a type's `validate()` gates on, its single SUCCESS terminal value (`null` when the type's terminal values are several distinct outcomes rather than one success, i.e. no mechanical close exists), and whether that value also needs a live resolving decision/artifact. They DECLARE what the hooks enforce — a reader (the gardener's finding remedies) names the right terminal status from here instead of hand-mirroring hook source. `resolution` is the per-type ATTESTATION path (issue-spor-offline-check-get-hook-resolution-proxy): `edge` — this type's completion is attested only by a live inbound resolving edge — or `status` — its own terminal status retires it — or `null` when the schema declares neither, which is a resident schema authored before the key existed (a reader falls back to the legacy proxy, `hooks` containing `get`) rather than a graph asserting either answer. A client verifying a dispatched run's outcome reads this, never the `hooks` array. The REST/MCP twin of the `spor schema` CLI: all three render one `graph.registry.snapshot()` so they never drift |
+| `GET /v1/schema` | `spor schema`, agents introspecting the contract | the live schema registry as data (task-spor-schema-introspection-surface; server half task-spor-server-schema-endpoint): `{default_edge_weight, node_types: [{type, description, prefix, always_on, traversable, capturable, queueable, non_resolving, terminal, inert, inert_inherited, vocabulary, completion, resolver_required, resolver_types, resolution, hooks, schema_id, schema_version, source}], edge_types: [{type, description, weight, weight_default, inverse_label, aliases, capturable, hooks, ...}], queue_policy, policies, registers, stale_overrides, alias_collisions}` — the seed pack MERGED with graph-resident `type: schema` overrides, each entry tagged by `source` (`seed`/`graph`/`native`) and the active schema node's id+version. `?code=1` embeds each hook's source under `code: {name: src}` (omitted by default to keep the response lean). The registry IS the contract (norm-cc-registry-is-contract); this read surface closes the failure mode of agents reverse-engineering it from `lib/seed/` files (which miss resident overrides). `vocabulary`/`completion`/`resolver_required` are the declarative completion policy (task-spor-registry-declarative-terminal-status-policy): the closed status enum a type's `validate()` gates on, its single SUCCESS terminal value (`null` when the type's terminal values are several distinct outcomes rather than one success, i.e. no mechanical close exists), and whether that value also needs a live resolving decision/artifact (`resolver_types`: which node types count as that resolver, `[]` when undeclared). They DECLARE what the hooks enforce — a reader (the gardener's finding remedies) names the right terminal status from here instead of hand-mirroring hook source. `resolution` is the per-type ATTESTATION path (issue-spor-offline-check-get-hook-resolution-proxy): `edge` — this type's completion is attested only by a live inbound resolving edge — or `status` — its own terminal status retires it — or `null` when the schema declares neither, which is a resident schema authored before the key existed (a reader falls back to the legacy proxy, `hooks` containing `get`) rather than a graph asserting either answer. A client verifying a dispatched run's outcome reads this, never the `hooks` array. The REST/MCP twin of the `spor schema` CLI: all three render one `graph.registry.snapshot()` so they never drift |
 | `GET /v1/me` | `spor whoami`/`status`, onboarding | identity echo for the bearer token → `{person, name, email, bound, is_admin, org}`. `bound:false` means the token authenticates but maps to **no person node** (legacy/OAuth, or minted before the node existed), so routed questions and the personal queue will be empty — the client warns on it (the silent identity-degradation signal). `is_admin` reflects the `stewards→root` edge that gates the token-admin surface. `org` is the slug this tenant routes to (`SPOR_ORG`/legacy `SUBSTRATE_ORG`, else `"local"`); it lets a client key its `(issuer, org)` credential store for an **opaque** `spor_oat_`/`spor_pat_` token that carries no readable `org` claim — the client falls back to it after `--org` and the JWT `org` claim (task-spor-frontdoor-me-org-echo). A connector JWT's `org` claim is enforced equal to this echo |
 | `GET /v1/me/org-choices` | `spor auth list` (live membership refresh) | re-queries the IdP's *current* org membership for the held credential's subject and returns `{org_choices: [{slug, label, default?}], source: "idp"\|"bound"}` — `source:"idp"` is a true live enumeration (orgs added/removed since the last login surface without re-authenticating); `source:"bound"` means a single org-scoped token the server couldn't expand (no enumeration). The client treats only `source:"idp"` as live and **fails open** to its cached tenant listing on anything else — `source:"bound"`, a `502 {error.code:"membership_requery_failed"}` (IdP unreachable), a `404` (older server without the endpoint), or any transport/parse error (task-spor-cli-auth-list-live-membership-requery; server half task-spor-frontdoor-held-credential-membership-requery) |
 | `GET /v1/me/tokens` | `spor token list` | list the caller's OWN personal access tokens → `{tokens: [{hash_prefix, person, label, name, email, created, expires, expired, last_used}], count}` — caller-scoped (only their person-bound PATs; agent session tokens excluded), never plaintext, never full hashes. `403 forbidden` if the bearer maps to **no person node** (you need a bound identity to own a PAT). The self-serve, no-admin twin of `GET /v1/admin/tokens` below (task-spor-app-me-tokens-self-serve) |
@@ -605,7 +650,7 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | `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 |
+| `POST /v1/nodes` | `spor put-node` (one node, or a `--dir`/multi-document batch), 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. (`spor put-node`'s LOCAL-mode batch differs: it validates the whole batch against one temp graph and writes nothing if any entry is invalid; its remote mode is this per-entry route) |
 | `POST /v1/nodes/{id}/edges` `{type, to, attrs?}` | scripts, mechanical writers | `add_edge` semantics (§1): normalize/flip, dedupe, append — no revision echo. Optional `attrs` adds trailing flat edge attributes (e.g. a per-assignment `profile:` override); re-adding the same edge with different attrs upserts the set. Adding a review-outcome edge (`reviewed-by`/`changes-requested-by`/`review-requested`) flips a sibling review edge to the same person in place — the one-call submit-review primitive |
 | `DELETE /v1/nodes/{id}/edges` `{type, to}` | scripts, mechanical writers | `remove_edge` semantics (§1): the withdrawal twin of the POST above — drop one typed edge by `{type, to}`, normalize/flip exactly as `add_edge` (an inverse form removes the canonical edge on the *other* node and echoes its id), no revision echo. A missing edge is an idempotent `skipped`. For *withdrawing* a relationship the review flip can't express — a pulled review request, a dismissed review |
 | `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) |
@@ -622,15 +667,18 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | `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 |
 | `POST /v1/nodes/{id}/elaborations` `{text, note?, date?}` | scripts, mechanical writers filing into a running log | the deterministic elaboration append: the same fold the capture ELABORATE outcome lands through, minus the model — the server appends a dated `> elaboration (date): note` block to the node's body, following the `art-<stem>-<n>` continuation chain to its live tail and, when that tail is at the 8KB body cap, rolling the next continuation part itself and folding there (dec-spor-capture-fold-auto-spill-continuation) → `{status, id, revision, warnings, spilled_from?}`. `id` is where the text LANDED (a continuation when it spilled), `status` the underlying put's token (`updated` in place / `created` on a spill); `200` in place, `201` with `spilled_from` naming the full part when a spill rolled. `date` is `YYYY-MM-DD` (defaults to today); a blank `text` is `422`; a missing target `404`; an elaboration too large for even an empty part is `body_full`. No idempotency of its own — a re-sent elaboration appends again, so a caller that must land exactly once scans the family first (`scripts/harvest-file-datapoints.js` dedups by tenant + window) |
 | `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`) |
+| (client-side, no route) | `spor reconcile-landed` CLI verb; the `spor work` integration stage after a land; the orchestrator merge step | **landed-work detection** (task-spor-landing-detect-shipped-resolver-draft): the client, where the checkouts are, scans a code repo for commits REACHABLE FROM the trunk ref (`git merge-base --is-ancestor <sha> <ref>` — a commit that exists only on a branch never counts) that name an open task/issue via a `Spor:`/`Substrate:` trailer or a `commits:` stamp for that repo, and for each writes (`POST /v1/nodes`, `if_exists: skip`, deterministic ids — a re-run files nothing new) an UNLINKED draft resolver `art-shipped-<id>` (`status: in-review`, `commits:` the landed shas, a `mentions` edge — never `resolves`) plus a finding `find-shipped-on-main-<id>` (`relates-to` the item and the draft) naming the sha(s), the repo and the reachability check. Terminal status is never flipped by a scan; `spor reconcile-landed --confirm <finding ids…>` is the batch confirm (per id: draft → `merged`, `add_edge resolves`, the item's completion status via `/v1/nodes/{id}/status`, the finding → `resolved`; one failure never aborts the rest). Range: `--since <ref>` (`<ref>..tip`) or `--last N` (default 200); `--ref` (default the first of main/master/origin/main/origin/master), `--dir`, `--dry-run`, `--json`. The finding kind `shipped-on-main` is not a gardener kind, so a gardener sweep neither resolves nor re-opens it. Remote mode judges liveness against `GET /v1/export` |
 | `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). `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/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). An additive `auto_write_id` rides the response when a flag-gated near-miss fold (`SPOR_GARDENER_AUTO_WRITE`, task-spor-capture-near-miss-ledger-and-undo) auto-wrote a merged capture-pending close or a body-append elaboration in place of filing to triage — the ledger id `POST /v1/gardener/auto-writes/undo` takes to reverse it; absent when no near-miss fold fired |
 | `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?, project_warning?, 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). A `project` token that matches no repo, grouping, or project stamp on any resident node is still `200` with empty `items` — it rides back as the additive `project_warning` string (the same field and wording shape as `/v1/analytics`; absent when the scope is known, even if legitimately empty), the remote twin of local `spor next`'s projectKnown() check: remote `spor next`, `spor work`, and `spor dispatch --from-queue` print it verbatim on stderr and strip it from the envelope so `--json` matches local (norm-spor-cli-mode-parity, task-spor-remote-next-print-project-warning). `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) |
+| `GET /v1/queue?project=&assignee=&type=&exclude_type=&readiness=&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, counts_by_readiness?, muted?, dormant?, questions, asked, findings, pending, reviews, policy?, project_warning?, 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). A `project` token that matches no repo, grouping, or project stamp on any resident node is still `200` with empty `items` — it rides back as the additive `project_warning` string (the same field and wording shape as `/v1/analytics`; absent when the scope is known, even if legitimately empty), the remote twin of local `spor next`'s projectKnown() check: remote `spor next`, `spor work`, and `spor dispatch --from-queue` print it verbatim on stderr and strip it from the envelope so `--json` matches local (norm-spor-cli-mode-parity, task-spor-remote-next-print-project-warning). `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). `readiness=` (comma-separated, repeatable; `agent`\|`human`\|`untriaged`) is the agent-readiness twin — a hard scope filter on the derived classification (dec-spor-agent-readiness-derived-classification, QUEUE.md "Agent-readiness"); an unknown value is `422 invalid_node`. `counts_by_readiness` (`{agent, human, untriaged}`) rides the envelope whenever the graph carries readiness signal or a `readiness=` facet was asked for — the remote twin of local `spor next`'s readiness lead line, forwarded by remote `spor next --readiness` (task-spor-queue-remote-readiness-ignored). **This body is the canonical queue envelope** (task-spor-local-remote-single-renderer-conformance): every field except the per-viewer routing lists and the stamp (`awaiting_you`/`questions`/`asked`/`findings`/`pending`/`reviews`/`generated_at`, `SERVER_ONLY_QUEUE_FIELDS`) is shaped by the client kernel's `shapeQueueEnvelope`/`queueAggregates` (lib/kernel/queue.js) and the warning by `unknownProjectWarning` (lib/kernel/graph.js); local `spor next --json` emits the same envelope over a local graph, both modes render it through ONE `renderReport` (lib/queue.js), and test/mode-parity.test.js diffs the two against a stub of this route |
 | `GET /v1/analytics?project=&type=&weeks=&top=&aging=&format=` | remote `spor analytics`, the `analytics` MCP tool | work-flow analytics — the SERVER twin of the local-only `spor analytics` consumer, for a remote/Cowork teammate with no local graph repo to fold (task-spor-server-analytics-surface): created-vs-completed weekly cohorts, throughput, cycle-time median/p90, current WIP by node type, and the oldest-open bottlenecks, computed by the pure analytics kernel over the resident graph + a HEAD-keyed status-transition fold. **Completion is a node's status-TRANSITION time** (when it entered its final terminal run, from git content history), never `updated_at`, so a later edge append can't corrupt the "completed last week" signal (dec-spor-git-derived-timestamps). Default returns the machine (JSON) report `{window, weekly, totals, throughput, cycleTimeDays, wip, bottlenecks, coverage}`; `?format=text` renders the human report. `project` resolves through the shared up-resolution like `/v1/queue` (bare repo slug → grouping union; `repo-<slug>`/`proj-<slug>` id pins) — a zero-match scope rides back as the additive `project_warning` field (text mode prefixes a `# ` line). `type=` (comma-separated, repeatable) restricts node types; `weeks`/`top`/`aging` shape the window (clamped 1–52 / 1–100 / 1–365). A bad slug/type is `422`. The remote arm of `spor analytics` fetches the JSON and renders it with the SAME `renderReport` the local consumer uses, so remote and local output match (norm-spor-cli-mode-parity, task-spor-analytics-remote-cli-dispatch) |
 | `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/questions` `{text, title?, mentions?, project?, to?}` | ask_question's REST twin | file a question node; `to` (a person node id) routes it there directly, ahead of every inferred signal — an unknown or non-person id is `400`, and naming the asker themselves falls through to ordinary routing with a warning instead of a dead-end. Absent `to`, routing is deterministic over the mentioned nodes' live claim holder, `assigned` edge, then author, then an explicit `stewards` edge, then a one-hop neighbor of those, then a text-derived steward walk, then (skipping a person-direct asker throughout) the tenant-owner fallback — unrouted if nothing matches → 201 `{status, id, project, routed_to, via, routed_by, asker, revision, warnings}`. `routed_by` names which signal won (`explicit`\|`steward`\|`claim`\|`assigned`\|`author`\|`owner`, `null` if unrouted); `warnings` carries a line when the owner fallback fired, the question is genuinely unrouted, or an explicit `to` named the asker themselves. `GET /v1/status`'s `capabilities.ask_question_explicit_to` advertises this field — `spor ask --to <person-id>` sends it there when present, else falls back to the pre-capability leading-mention nudge. `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/gardener/auto-writes?days=&limit=&node=` | `list_auto_writes`'s REST twin; audit review | the gardener's reversible auto-write ledger → `{ok, enabled, via, days, since, count, total, auto_writes: [...], generated_at}`, newest first (`days` default 7 max 365, `limit` default 200 max 1000, `node` filters to one subject/target id); see `list_auto_writes` (§2) for the entry shape |
+| `POST /v1/gardener/auto-writes/undo` `{id}` or `{ids}` | `undo_auto_write`'s REST twin | reverse one or a bounded batch of auto-writes by ledger id → `{ok, status, results, count, undone, skipped, failed}`; see `undo_auto_write` (§2) for the per-item result shape, including the `body_append` undo's additive `refiled` (the id of the capture-pending node the stripped text was re-filed under) and `warnings` (non-empty only when that re-file itself failed) |
 | `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 |
@@ -746,13 +794,11 @@ anything with a token.
   /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. For the opt-in native launch (`spor dispatch --bg`,
-  `claude --bg` ignores `--session-id`) the launcher reads it from `claude agents
-  --json`. A **supervised**-harness dispatch (Claude Code by default, Codex,
-  OpenCode, GitHub Copilot CLI) follows
-  the same late-bind contract from its own supervisor process instead: it reads
-  the session id out of the run's supervised JSONL log rather than
-  `claude agents --json` — Claude Code off the `session_id` every stream-json
+  is always the actual run. Every dispatch is **supervised** (Claude Code,
+  Codex, OpenCode, GitHub Copilot CLI; the native `spor dispatch --bg` launch,
+  which read the session from `claude agents --json`, is retired), so the
+  supervisor process binds it: it reads the session id out of the run's
+  supervised JSONL log — Claude Code off the `session_id` every stream-json
   event carries (first on its `system`/`init` event), Codex off its
   `thread.started` event, OpenCode off
   the `sessionID` every event carries, Copilot off the `sessionId` on its
@@ -881,11 +927,15 @@ as if the graph is empty" (§6).
 A `429 rate_limited` response SHOULD carry a `Retry-After` header (delay
 seconds or an HTTP-date); clients honor it, otherwise backing off
 exponentially, capped, before retrying. Mechanical writers
-(drain-outbox, distill) classify `401`, `400`, `413`, and `422` as
-**permanent** — a revoked token will not un-revoke, so these are
+(drain-outbox, distill) classify `401`/`403`, `400`, `413`, and `422` as
+**permanent** (one shared classifier, `classifyHttpFailure` in
+`scripts/engines/util.js`, which session-start also reads its banner from) — a revoked token will not un-revoke, so these are
 dead-lettered to `outbox/dead/` with a loud `journal/remote.log` line
 rather than re-POSTed forever; `429` and `5xx` stay transient and are
-retried with backoff.
+retried with backoff. Before a `401`/`403` is read as permanent, a writer
+whose tenant carries a `refresh_token` refreshes it once and retries the
+POST (`curlWithRefresh`, the same refresh the CLI does, §6.2) — an expired
+short-lived token is not a revoked one.
 
 `GET /v1/export` response headers: `x-substrate-head` carries the graph
 commit, `x-substrate-node-count` the entry count (plus `x-substrate-auth-files`
@@ -1055,11 +1105,40 @@ machine-local — never committed, always in the shared-graph `.gitignore`):
   refuse like any other verb, since acting on the active tenant is exactly the
   hazard. An `--org` given an **empty** value (an unset shell variable, in
   either the `--org ""` or the dangling `--org` spelling) refuses everywhere,
-  acquisition included: it is malformed input, not "use the default". The
-  ambient selectors (`SPOR_ORG`, the repo `org:` marker) still fall
-  through — they also ride the fail-open hook engines.
+  acquisition included: it is malformed input, not "use the default".
+- **Unknown ambient org refuses too.** `SPOR_ORG` and a repo `.spor` `org:`
+  marker naming an org with no stored credential refuse exactly like `--org`
+  (issue-spor-ambient-org-selector-silent-fallback): the CLI exits 1 naming the
+  selector and the stored orgs (acquisition invocations exempt), and the hook
+  engines inject nothing and write nothing to EITHER graph — no remote call and
+  no fall-through to the local graph home — journaling a warning to
+  `journal/remote.log`. Under an explicit `mode: local`/`off` no tenant is
+  consulted, so a stray ambient org is moot there. `spor config explain` shows
+  which selector chose (or refused) the tenant.
+- **A repo `server` gets only a credential recorded for it.** A committed repo
+  `.spor.json` may set `server` (how a repo points contributors at a team
+  server), but the flat `token` is never repo-sourced — it was recorded beside
+  the server the user/global config names. When the repo layer wins `server`
+  (legacy flat path, or an ambient org satisfied by it), that token is sent only
+  if its recorded server equals the repo's; otherwise a store credential
+  recorded for exactly that server is used, else the cascade refuses
+  (`server-mismatch`, naming both servers) the same way an unknown ambient org
+  does (dec-spor-repo-server-key-requires-matching-credential). `spor auth
+  login` is exempt and defaults to the repo's server — signing in there is the
+  cure, and that credential is stored for that server only, not as the store
+  default (which would move every other repo onto it). A repo `server` with no credential on hand at all resolves tokenless.
 - **Refresh.** A 401/403 on a tenant carrying a `refresh_token` transparently
   refreshes against its issuer (`grant_type=refresh_token`) and retries once.
+  Only the store tenant's OWN bearer carries one: an explicit `SPOR_TOKEN` /
+  `--token` that is not the stored `access_token` for that server — a
+  dispatched agent's scoped token under the person's HOME is exactly this
+  shape — resolves with no `refresh_token`, no store `key`, and its own JWT
+  `org` claim, so an agent's 401 is never retried as the person
+  (issue-spor-agent-token-scope-escalation-via-refresh-and-store-default).
+  For the same reason `spor dispatch` exports `SPOR_SERVER` beside the
+  agent-scoped `SPOR_TOKEN` to every remote-mode harness child: without the
+  server the child's cascade never reads the env token and selects the store
+  default — the person — instead.
 - **Byte-identical.** With no credential store and only a flat
   `server`+`token` or `SPOR_*` env set, every resolved value equals the prior
   single-tenant behavior (norm-cc-byte-identical-refactor).

package/GRAPH.md

@@ -68,7 +68,19 @@ Rules:
   it writes (`capture` marks nodes drafted by the ingestion path, QUEUE.md
   §2.3; `gardener` marks sweep findings, §6); any payload-supplied value is
   discarded. Both are simple `key: value` scalars. Locally written nodes may
-  omit them.
+  omit them. `author` means the most recent writer, not the original one — it
+  is restamped on every write the server makes to a node (a `put_node`
+  update, `add_edge`, `set_status`, or `claim` alike).
+- `created_by` is optional and, where present, immutable: the server stamps
+  `created_by: Name <email>` from the verified identity the first time a node
+  is written (CREATE only) and carries it forward unchanged on every later
+  write to that node, discarding any payload-supplied value
+  (dec-spor-node-created-by-write-once). It is the write-once counterpart to
+  `author`/`authored_via` above — read `created_by` for who originated a
+  node, `author` for who last touched it. Nodes written before this field
+  shipped, or written locally, may lack it; an operator-run backfill in the
+  private server repo (`server/backfill-created-by.js`) fills it in from each
+  node file's first commit.
 - Edges may point at ids that don't exist yet; the compiler skips them. Don't
   delete an edge just because the target is missing — it marks a node worth
   creating. An edge may also carry extra flat attributes after `to:` —
@@ -340,7 +352,10 @@ keys say, as registry data, what the hooks below enforce: `status.vocabulary`
 the full set *including* the give-up outcomes `abandoned`/`superseded`/
 `rejected`), and `status.resolver_required` (whether reaching that value also
 demands a live resolving `decision`/`artifact`, the completion-resolver
-invariant). **Declaring them gates nothing** — the hooks are still the only
+invariant), with `status.resolver_types` naming WHICH node types count as that
+resolver (task/issue: `["decision", "artifact"]`; only legal beside
+`resolver_required: true`; read as `registry.resolverTypes(type)`,
+task-spor-registry-sole-terminal-status-source). **Declaring them gates nothing** — the hooks are still the only
 write door, and this is exactly why they are not a field list or an enforced
 enum. They exist so a READER can name the right terminal status without
 parsing hook source: the gardener's finding remedies used to keep hand-written
@@ -379,9 +394,11 @@ above, **declaring it gates nothing** — it tells a reader what the hooks
 already do.
 
 Otherwise there is **no declarative field list and no status enum.** Custom fields are free-form: any flat frontmatter key the
-regex parser accepts (simple `key: value` scalars, YAML-folded multi-line
-values, `pin:`/`exclude:` inline lists, `- {type: X, to: Y}` edges — and nothing
-fancier) is carried verbatim on the node. What a field MUST contain, and which
+regex parser (`lib/kernel/frontmatter.js`, the one node-file grammar) accepts
+(simple `key: value` scalars, YAML-folded multi-line values, the allowlisted
+list keys as `[a, b]` inline or block lists, `- {type: X, to: Y}` flow-form or
+`- type: X` / `to: Y` block-form edges — and nothing fancier) is carried
+verbatim on the node. What a field MUST contain, and which
 status changes are legal, are enforced **in attached code** — two pure functions
 the server runs on the write path:
 
@@ -929,6 +946,14 @@ edges:
   optional `@YYYY-MM-DD` expiry) is per-viewer presentation only: the queue
   hides those items for this person and reports how many it hid; they stay live
   and visible to everyone else (QUEUE.md §4).
+- **`covers_tests`** (flat inline list of repo-relative test file paths) on a
+  flake issue — or the task that fixes one — declares which tests that flake
+  covers; the gate pipeline stamps it on every `issue-flake-*` it files. Its
+  twin **`failing_tests`** is written by the gate pipeline on a `task-gate-*`
+  escalation: the test files a command gate's refusal failed in. Once every
+  failing test of a refusal is covered by a FIXED node (a live resolver, or
+  `done`/`resolved`), `spor work --regate-flakes` re-gates the run unattended
+  and retires the escalation only on a pass (WORKERS.md §10.7).
 - **`roles`** (flat inline list, e.g. `roles: [reviewer, maintainer]`) is the
   qualification register the org-defined policy layer reads. A scoped `policy`
   node's gate counts approvals from persons holding a named role — the
@@ -975,8 +1000,7 @@ server-side (issue-cc-onboarding-email-mismatch-silent-degradation).
 ### Agents (person-owned principals)
 
 An `agent` node (prefix `agent-`) is a person's automation principal — the
-durable identity of a dispatched Claude Code run (a supervised `claude -p`, or
-an opt-in `claude --bg` session)
+durable identity of a dispatched Claude Code run (a supervised `claude -p`)
 (dec-spor-agent-identity-nodes). It generalizes the workflow-run principal: a
 dispatched session is just another principal kind owned by a person, so work it
 creates reads "agent **on behalf of** person" rather than person-direct.
@@ -1061,6 +1085,11 @@ date: 2026-06-18
   `mcp` is merged into the strict `--mcp-config` dispatch writes, so the agent's
   toolset is exactly the profile plus the agent-spor server, nothing ambient
   (dec-spor-session-identity-active-record).
+- `model_family:` (optional) names the canonical model family (`gpt-5`,
+  `claude`, …). It is not a satisfiability field; it is what a review gate's
+  `fallback_profile` is judged independent of the implementer on — an unknown
+  or equal family refuses the fallback
+  (dec-spor-reviewer-reset-pause-budget-and-provenance).
 - **The graph names the harness; the MACHINE binds what that name runs**
   (task-spor-dispatch-declarative-custom-harness). `harness:` may name a
   launcher the client ships no in-code adapter for — a team's modified build,

package/QUEUE.md

@@ -563,13 +563,12 @@ plain-actionable `do` base upgrades: the triage dispositions
 overridden by readiness. The envelope gains `counts_by_readiness` ({agent, human, untriaged},
 present only when there is readiness signal or a readiness facet was asked
 for) — the headline "how much of my queue can an agent take right now?" A
-**readiness filter** (`rankQueue({readiness})`, a class or array; today on the
-kernel opt and the local CLI's `--readiness`, comma-separated — the `GET
-/v1/queue?readiness=` param, `show_queue {readiness}`, and remote `spor next
---readiness` forwarding land with the server render-surfaces slice,
-task-spor-queue-readiness-render-surfaces) narrows the queue to a class as a
-hard scope like `project`/`type` (schema-approval items, outside the
-classification, are excluded). A graph with no readiness data is byte-identical to before — no
+**readiness filter** (`rankQueue({readiness})`, a class or array — the
+kernel opt, the local CLI's `--readiness`, the `GET /v1/queue?readiness=`
+param, `show_queue {readiness}`, and remote `spor next --readiness`, all
+comma-separated) narrows the queue to a class as a hard scope like
+`project`/`type` (schema-approval items, outside the classification, are
+excluded); an unknown value is rejected rather than silently dropped. A graph with no readiness data is byte-identical to before — no
 fields, no clause, no count. Hard triage gaps recorded during a make-ready pass
 become explicit `blocks` edges (which correctly remove the item until
 answered); readiness handles the soft/derived side.

package/README.md

@@ -321,8 +321,8 @@ attestation paths — the resolving edge, and the terminal own-status a
 status-only type is retired by — are judged, and a target that either path finds
 unfinished takes the same file-then-hand-back route, whichever one judged it.
 What does cost it is a posture where nothing could be verified at all: a
-native-background run (`spor dispatch --bg`, the opt-in `claude --bg` launch), a
-free-text dispatch with no target node, and a graph that could not be reached are
+legacy native-background run record (from the retired `spor dispatch --bg`
+launch), a free-text dispatch with no target node, and a graph that could not be reached are
 classified best-effort and marked `terminal_enforced: false` — an unenforced run
 can never read `resolved`. Local mode is not excluded: it has no server door to
 file a report or hand a lease back through, but it does have a graph, so a local
@@ -384,15 +384,13 @@ is what keeps two workers off one node, so a loop always takes it. Stopping
 (`SIGINT`/`SIGTERM`, or `--once`/`--max`) stops picking up new work; runs
 already in flight are detached, keep going, and self-report through `spor runs`.
 
-A native-background run (`claude --bg`, reached only through `spor dispatch
---bg` or a standing `dispatch.claudeLaunchMode: native-background`) is the weak
-spot, for the same reason its outcome is unenforced: its termination is not
-deterministically observable, so a slot is freed from the harness's own
-live-agent listing. If that listing cannot be read, the slot stays held and the
-worker says so; `--run-max` (default 24 hours) is the backstop that stops
-following such a run. A supervised harness — Claude Code by default, Codex,
-OpenCode, Copilot CLI, or a declared one — has none of this, which is why the
-worker never passes `--bg`.
+Every run is supervised — Claude Code, Codex, OpenCode, Copilot CLI, or a
+declared harness — so a slot frees when the run's own supervisor closes its
+record; `--run-max` (default 24 hours) is the backstop that stops following a
+run that never goes terminal. (The native `claude --bg` launch, whose ending
+could only be inferred by scraping `claude agents --json` and the session
+transcript, is retired; a legacy record from it is judged from the record alone
+and closed an hour after its launch.)
 
 Run it as a service and read it back:
 
@@ -473,13 +471,12 @@ By default, `spor dispatch` launches a Claude Code agent in headless print mode
 prompt goes in on stdin, the run's session id and final report are read off its
 event stream, the run record goes terminal when the process does, and the
 terminal-state contract judges the outcome like any other supervised harness.
-Pass `--bg` (or set `dispatch.claudeLaunchMode: native-background` in your user
-config) to launch the native background session instead (`claude --bg`) — the
-attachable, interactive form (`claude attach`), at the cost of an unenforced
-outcome and no report channel. Both are `spor dispatch`'s alone: `spor work`
-launches every run supervised (its runs must be followed, judged and gated),
-and a worker started under a standing `native-background` says so once on
-stderr rather than silently ignoring it. To dispatch under a different coding-agent CLI —
+This is the only launch mode: the native background session (`spor dispatch
+--bg`, `claude --bg`) is retired — its outcome could only be inferred by
+scraping `claude agents --json` and the session transcript, which shifted with
+every Claude Code release. `--bg` is now refused (run `claude --bg` yourself
+for an attachable session), and a leftover `dispatch.claudeLaunchMode:
+native-background` is ignored with a warning. To dispatch under a different coding-agent CLI —
 Codex, OpenCode, and GitHub Copilot CLI are also supported — resolve a
 **profile**: a node that bundles a harness, model, and toolset.
 

package/agents/backfill.md

@@ -27,7 +27,15 @@ Method:
    rejected unless its resolving `decision`/`artifact` already exists on the
    graph (the completion-resolver gate, GRAPH.md), so emit each resolver BEFORE
    the terminal node it resolves, or build the node open→resolve→done. Local
-   file writes (the default below) are ungated and order-free.
+   file writes (the default below) are ungated and order-free. To push many
+   nodes to a remote graph, write them to a directory and submit them in ONE
+   call — `spor put-node --dir <dir> --if-exists skip` — not one `put-node`
+   per node: it batches the POSTs, orders resolvers ahead of the nodes they
+   resolve for you, prints a created/skipped/error line per node (so a re-run
+   is auditable — remote entries land or fail one by one, so a partial batch
+   is fixed by re-running with `--if-exists skip`; a local batch is
+   all-or-nothing and writes nothing if any entry is invalid), and stamps a `priority: p1|p2|p3` in a new node's frontmatter
+   the way `spor priority` would, so priorities need no second pass.
 2. Aggregate, don't transcribe. One node per durable fact: a decision with its
    why, an issue with its full resolution lineage (found → fixed-in → verified),
    a spec with its current status. NEVER one node per commit; collapse

package/bin/spor-hook.js

@@ -77,6 +77,35 @@ function normalize(payload, host) {
   return payload;
 }
 
+// True (after journaling a warning to remote.log) when the cascade REFUSED to
+// resolve a tenant — see Config.tenantError(). Every hook then no-ops.
+function tenantRefused(cfg) {
+  const te = cfg.tenantError();
+  if (!te) return false;
+  try {
+    // Throttled to one line an hour: a refused repo refuses EVERY hook call
+    // (each tool call fires post-tool), and one line says it all.
+    const journal = path.join(u.graphHome(), "journal");
+    u.ensureDir(journal);
+    const stamp = path.join(journal, "tenant-refused.stamp");
+    let last = 0;
+    try {
+      last = fs.statSync(stamp).mtimeMs;
+    } catch {
+      /* first refusal */
+    }
+    if (Date.now() - last < 3600000) return true;
+    fs.writeFileSync(stamp, "");
+    const log = u.makeLogger(path.join(journal, "remote.log"), "config: ");
+    if (te.kind === "server-mismatch") log(`${require("../lib/config.js").describeTenantRefusal(te)} — hook skipped; run 'spor auth login' for that server or override it`);
+    else if (te.kind === "agent-org" || te.kind === "agent-no-token") log(`${require("../lib/config.js").describeTenantRefusal(te)} — hook skipped; an agent run never selects the person's stored credential`);
+    else log(`org '${te.org}' (from ${te.origin}) has no stored credential — hook skipped; run 'spor auth login --org ${te.org}' or fix the selector`);
+  } catch {
+    /* logging must never break fail-open */
+  }
+  return true;
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   const event = argv.shift() ?? "";
@@ -112,7 +141,8 @@ async function main() {
     const ci = args.indexOf("--cwd");
     if (ci >= 0 && args[ci + 1]) amdCwd = args[ci + 1];
     else if (payload && payload.cwd) amdCwd = payload.cwd;
-    if (!u.useConfig({ cwd: amdCwd }).enabled()) return;
+    const amdCfg = u.useConfig({ cwd: amdCwd });
+    if (!amdCfg.enabled() || tenantRefused(amdCfg)) return;
     await agentsMd(payload, args);
     return;
   }
@@ -177,6 +207,13 @@ async function main() {
     return;
   }
 
+  // A bound org this box holds no credential for (SPOR_ORG, a repo `.spor`
+  // org: marker) is a REFUSAL, not a hint (issue-spor-ambient-org-selector-
+  // silent-fallback): inject nothing and write nothing to EITHER graph — the
+  // null tenant would otherwise resolve LOCAL mode and quietly distill into the
+  // personal graph home. Journaled, since a hook can only fail silently.
+  if (tenantRefused(cfg)) return;
+
   // Debounced distill: spool the payload and hand off to a per-session
   // watcher (one at a time — the lock holds the watcher's pid; stale locks
   // from a dead watcher are reclaimed). The watcher fires after quiesce.
@@ -194,7 +231,7 @@ async function main() {
     // live claim on a false positive would silently strand active work.
     payload.spor_debounced = true;
     try {
-      fs.writeFileSync(pendingFile, JSON.stringify(payload));
+      u.writeSpoolFile(pendingFile, JSON.stringify(payload));
     } catch {
       return;
     }