@sporhq/spor 0.28.0 → 0.29.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.28.0",
+  "version": "0.29.0",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

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

@@ -105,7 +105,8 @@ The compiler over the wire. Input:
 ```
 
 Output: `{ "found": bool, "text": "<digest or full neighborhood>",
-"node_ids": [...], "top_sim": 0.31 }`. `found: false` (gate not met) is a
+"node_ids": [...], "top_sim": 0.31, "intent"?: {...} }` (`intent` is the
+optional server-computed digest-intent verdict — see the `/v1/digest` row in §3). `found: false` (gate not met) is a
 **successful empty result**, not an error.
 
 ### `get_node`
@@ -592,15 +593,15 @@ 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, hooks, schema_id, schema_version, source}], edge_types: [{type, description, weight, weight_default, inverse_label, aliases, capturable, hooks, ...}], queue_policy, policies, registers, stale_overrides, alias_collisions}` — the seed pack MERGED with graph-resident `type: schema` overrides, each entry tagged by `source` (`seed`/`graph`/`native`) and the active schema node's id+version. `?code=1` embeds each hook's source under `code: {name: src}` (omitted by default to keep the response lean). The registry IS the contract (norm-cc-registry-is-contract); this read surface closes the failure mode of agents reverse-engineering it from `lib/seed/` files (which miss resident overrides). `vocabulary`/`completion`/`resolver_required` are the declarative completion policy (task-spor-registry-declarative-terminal-status-policy): the closed status enum a type's `validate()` gates on, its single SUCCESS terminal value (`null` when the type's terminal values are several distinct outcomes rather than one success, i.e. no mechanical close exists), and whether that value also needs a live resolving decision/artifact. They DECLARE what the hooks enforce — a reader (the gardener's finding remedies) names the right terminal status from here instead of hand-mirroring hook source. The REST/MCP twin of the `spor schema` CLI: all three render one `graph.registry.snapshot()` so they never drift |
+| `GET /v1/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/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) |
 | `POST /v1/me/tokens` `{expires?, label?}` | `spor token create` | mint a human-identity `spor_pat_` PAT bound to the CALLER's own person → 201 `{token, hash_prefix, person, name, email, label, expires}`; the plaintext `token` is returned **once**. `expires` is `<N>d` or an ISO date, user-set, defaulting to and **capped at 1 year** (a past date or beyond-cap is `422`, rejected not silently clamped); `label` is an optional ≤200-char note surfaced in the listing. `403` if unbound. The self-serve mint twin of admin `POST /v1/admin/tokens` (which binds someone *else*) |
 | `DELETE /v1/me/tokens/{hash-prefix}` | `spor token revoke` | revoke one of the caller's OWN PATs by hash prefix → `{revoked, hash_prefix, oauth_grants_revoked}`; a prefix that isn't one of the caller's is `404` (never another person's token). `403` if unbound. Shares the admin revoke's OAuth-grant cascade-completeness invariant (issue-cc-pat-revoke-cascades-all-oauth-grants) |
 | `GET /v1/briefing/{project}` | session-start | read the `brief-<project>` node → `{found, version, body, project_brief?, graph_status}`. The slug resolves through project-node aliases (GRAPH.md "Project identity nodes") before lookup. A BARE repo slug also rides up to its home-project grouping: the grouping's `brief-<grouping>` node returns alongside as `project_brief` (the product context spanning sibling repos), matching the shared up-resolution (dec-spor-queue-slug-resolves-to-grouping); passing the repo NODE id (`repo-<slug>`) is the escape hatch that returns only the repo brief, no `project_brief`. Optional `?fp=root:<sha>,remote:<host/path>,...` carries the repo's fingerprints: the server learns them onto the owning project node, and an unknown slug with a known fingerprint files an alias proposal in the queue |
-| `POST /v1/digest` `{query, root?, project?, min_sim?}` | prompt-context, /spor:brief | digest-mode compile → `{found, text}`; `found: false` is a successful empty result. `root` is the structural-walk twin of `query` (the two are mutually exclusive; `root` wins, an unknown id is `422`). Optional `project` is the session slug: the server scopes the compile to it — the same-project relevance boost, the grouping union, and the `always_on` norm `applies_to_*` ride-along — resolving the slug through project-node aliases/groupings inside compile (dec-spor-queue-slug-resolves-to-grouping), exactly as `/v1/queue` does. A bad slug is `422`; **omitting `project` runs the digest project-blind (byte-identical to before)**, so older clients that send only `{query}` are unaffected |
-| `GET /v1/nodes/{id}` | /spor:brief | `get_node` semantics; 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/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. **Digest rerank (task-spor-compile-jev-rerank-stage, per-org opt-in, default OFF, server half task-split-spor-server-eb6de3fca31e):** when the org has opted in, the server scores the candidate pool (cosine top-30 ∪ top structural) with `jev.rerank` and hands the verdicts to `compile()` as `opts.rerankScores` — a `{ [id]: { score, noul } }` map, `score` an ordinal 0-3 (irrelevant / background / directly relevant / required) and `noul` a 0-1 probability that that candidate answers or resolves the query. `compile()` stays pure — it never calls Jev itself, it only reorders the section it already builds under `DIGEST_CAP`: pinned → scored candidates (`noul` desc, `score` secondary, cosine-sim tiebreak) → remaining structural (unscored, original score-desc order) → remaining content (unscored, original sim-desc order) — and reports it back as `meta.rerank: {applied: true, candidates: <n>}` (absent when rerank did not run) for the response's own additive `rerank` summary field to echo. Fail-open: an org that hasn't opted in, local mode (no server to call Jev with), or a call that omits/empties `opts.rerankScores` all render byte-identical to before (norm-cc-byte-identical-refactor). **Optional `intent`** (task-spor-digest-intent-jev-gate / task-split-spor-server-bca885114354): when the org has Jev enabled and the request carries a `query`, the server also returns `intent: {warranted: bool, needs_history: 0–1, digest_helps: 0–1, source: "jev"}` — the digest-intent verdict computed server-side (`warranted` = the deterministic prompt heuristics, then max(noul) ≥ 0.5). It is **absent** whenever it was not computed (Jev disabled/shed/timed out/failed, a `root` walk, an older server): fail-open, never `warranted: false` by default. The prompt-context hook suppresses THIS prompt's digest only on an explicit boolean `warranted: false`, and only when its digest intent gate is on (`digest.async`, a tri-state: explicit `true`/`false`, unset = the client default); an absent or non-boolean field is ignored, and so is one on a `found: false` response (its `digest_helps` judged an empty team digest, not the client's personal-graph merge) |
+| `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` (`bin/spor.js`'s `dispatchDeclineFindingCheck` reads it to refuse re-dispatching a node a prior run DECLINED — task-spor-decline-finding-gates-redispatch — filtering for a live `find-declined-*` entry), 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` |
@@ -611,13 +612,13 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | `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}, 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}/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) Singular renewal returns optional `reclaimed: true` and `reclaimed_after: "release" | "lapse" | "never_held"` when it reacquires the claim; both fields are absent on an ordinary heartbeat. This is the singular `RenewResponse` contract. |
 | `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, 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/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 Bulk renewal uses the separate `RenewAllResponse` contract: optional `reclaimed: string[]` lists reacquired node IDs and `reclaimed_after: Record<node-id, "release" | "lapse" | "never_held">` gives each reason. Both fields are absent if none were reacquired; a blanket heartbeat never reclaims. Select the response type by the request route, not by assuming the singular boolean shape. MCP `renew` follows the same split (`id` selects `SingularRenewResult`; `ids` or `all` selects `BulkRenewResult`). Existing clients can ignore these additive fields. |
 | `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`) |
@@ -651,7 +652,7 @@ agent subject sees no graph content; a coarse read-only/CI flag is not a bypass.
 | `POST /v1/agents/{id}/capabilities` `{harnesses?, reachable_mcp?, skills?, plugins?, deny?}` | `spor capabilities publish`, session-start auto-publish | **publish** this box's machine capabilities to the fleet scheduler (task-spor-remote-fleet-scheduler, dec-spor-machine-profile-satisfiability). The remote twin of the machine-local `dispatch.capabilities` map: the server collapses the body with the SAME `effectiveCapabilities()` the client runs (so a raw `{probed,declared,deny}` map or the already-flat axes both work; also accepts a `{capabilities: {...}}` envelope) and stores it BESIDE the agent node (operational store, not the durable git-tracked node — capabilities are machine-local, probe-refreshed, never committed) → `200 {agent, capabilities, published_at, last_seen, published_by, session?, changed}`. Authorized iff the caller **owns** the agent (its `owned-by` edge) OR is the agent itself (a self-publish under an agent token) — else `403`; `404` unknown agent; `422` a malformed map. A publish stamps both `published_at` (when the CAPS last changed) and `last_seen` (last contact); `last_seen` ALSO advances on the cheap `POST .../heartbeat` below, and the host-match keys staleness off `last_seen` not `published_at`. Beyond the manual verb, `session-start` AUTO-publishes here in remote mode whenever a `dispatch.agent` is configured (task-spor-fleet-capabilities-autopublish-session-start) — bounded + fail-open, so every session refreshes this box's caps and last-contact without a manual call; disable with `SPOR_CAPABILITIES_PUBLISH=0` |
 | `GET /v1/agents/{id}/capabilities` | `spor capabilities show <agent>`, steward fleet view, debugging | read back an agent's published capabilities → `200 {agent, capabilities, published_at, last_seen, published_by, session?}`; `404` if none published. Readable by the **owner**, the **agent itself**, or an **admin** (a stewards→root fleet-capacity view) — else `403`. The CLIENT reader (task-spor-capabilities-read-agent-cli-verb): `spor capabilities show <agent-id>` (`me` = this box's `dispatch.agent`) renders the stored caps + timestamps without raw REST — the read twin of `spor capabilities publish` and the per-agent companion to `spor capabilities hosts`; remote-only, fail-soft |
 | `POST /v1/agents/{id}/heartbeat` | post-tool mid-session liveness tick | **liveness ping** (task-spor-fleet-scheduler-hardening): refresh this box's `last_seen` WITHOUT re-uploading capabilities — the cheap "still here" signal, decoupled from a caps re-publish, so a box that published once and runs for hours stays a live fleet host. The host-match keys staleness off `last_seen`, so a box that keeps heartbeating is never demoted while a genuinely dead one ages out under `max_age` → `200 {agent, capabilities, published_at, last_seen, …}` (the refreshed record). Same owner/self gate as publish — else `403`; `404` unknown agent OR nothing published yet (publish before heartbeat — liveness without caps is meaningless to the scheduler); `422` a malformed agent id. The CLIENT caller (task-spor-fleet-scheduler-client-heartbeat-tick): the `post-tool` hook ticks this in REMOTE mode whenever a `dispatch.agent` is configured (the SAME opt-in as the session-start auto-publish), piggybacking on write-activity but THROTTLED to one ping per `dispatch.heartbeatIntervalMs` (default 5min) — so a long session keeps `last_seen` fresh between session-starts (which today refresh it the expensive way, via a full re-publish) without re-probing. Bounded + fail-open; disable with `SPOR_HEARTBEAT=0` |
-| `GET /v1/profiles/{id}/hosts` `?owner=me\|person-X&max_age=<dur>` | `spor capabilities hosts <profile>`; `spor dispatch` (auto on a FORK B refusal) | **host-match** a `type: profile` against every agent's published capabilities using the SAME pure `satisfies()` matcher the client runs locally → `200 {profile, satisfiable: [{agent, owner, published_at, last_seen, age_seconds}], unsatisfiable: [{agent, owner, published_at, last_seen, age_seconds, reasons}], counts}`. Satisfiable hosts are freshest-first (by `last_seen`); the unsatisfiable carry the matcher's own reasons (the failing atoms), enabling **substitution-free re-routing** — pick a box that satisfies the profile, NEVER substitute a different one (dec-spor-machine-profile-satisfiability FORK B). The CLIENT consumer (task-spor-fleet-scheduler-autoroute-dispatch): `spor capabilities hosts` lists the re-route targets directly, and when `spor dispatch` refuses because THIS box can't satisfy the resolved profile it calls this endpoint and names the satisfiable hosts to re-route to — or, when none satisfy it, escalates to the owner (fail-soft: an unreachable scheduler degrades to a generic hint). **Visibility is steward-scoped** (task-spor-fleet-scheduler-hardening): the whole-fleet view (every member's boxes + caps) is a multi-tenant cross-member disclosure, so an **admin** (stewards→root) sees the whole fleet and may scope to any `owner=person-X`, while an ordinary **member** is scoped to THEIR OWN boxes (default `owner` = the caller's person; an agent token resolves to its owner; `owner=me` is the explicit form) and a member asking for a colleague's `owner=person-X` is `403`. `max_age` (`30m`/`12h`/`7d`/ms) demotes hosts whose `last_seen` is older than it to unsatisfiable (the liveness filter). `404` unknown/non-profile id; `422` bad `max_age`/`owner` |
+| `GET /v1/profiles/{id}/hosts` `?owner=me\|person-X&max_age=<dur>` | `spor capabilities hosts <profile>`; `spor dispatch` (auto on a FORK B refusal) | **host-match** a `type: profile` against every agent's published capabilities using the SAME pure `satisfies()` matcher the client runs locally → `200 {profile, satisfiable: [{agent, owner, published_at, last_seen, age_seconds}], unsatisfiable: [{agent, owner, published_at, last_seen, age_seconds, reasons}], counts}`. Satisfiable hosts are freshest-first (by `last_seen`); the unsatisfiable carry the matcher's own reasons (the failing atoms), enabling **substitution-free re-routing** — pick a box that satisfies the profile, NEVER substitute a different one (dec-spor-machine-profile-satisfiability FORK B). The CLIENT consumer (task-spor-fleet-scheduler-autoroute-dispatch): `spor capabilities hosts` lists the re-route targets directly, and when `spor dispatch` refuses because THIS box can't satisfy the resolved profile it calls this endpoint and names the satisfiable hosts to re-route to — or, when none satisfy it, escalates to the owner (fail-soft: an unreachable scheduler degrades to a generic hint). Its AUTONOMOUS tier (task-spor-fleet-autoroute-auto-tier-consumer, opt-in `spor dispatch --auto-route` / `dispatch.autoRoute`) takes that same host-match and closes the loop with no human step: for a NODE dispatch it hands the item to the freshest satisfying box by writing `assigned -> <host agent>` with the SAME profile pinned as the edge's `profile:` attribute (`POST /v1/nodes/{id}/edges`, §3), so that box's own `spor work` picks it up — routing is explicit assignment (dec-spor-agent-orchestration-layer), so the graph is the handoff and no cross-machine exec channel is involved. It asks `owner=me` so only the caller's OWN boxes are ever routed to (an admin's default whole-fleet view would otherwise hand their work to a colleague's machine), bounds a target's staleness with `dispatch.autoRouteMaxAge` (default `24h`), never routes to the refusing box itself (a stale self-match is skipped), and degrades to the human-tier report on anything it can't act on — no satisfying host (still an escalation), a free-text dispatch with no node to assign, a scheduler outage, or a refused edge write. **Visibility is steward-scoped** (task-spor-fleet-scheduler-hardening): the whole-fleet view (every member's boxes + caps) is a multi-tenant cross-member disclosure, so an **admin** (stewards→root) sees the whole fleet and may scope to any `owner=person-X`, while an ordinary **member** is scoped to THEIR OWN boxes (default `owner` = the caller's person; an agent token resolves to its owner; `owner=me` is the explicit form) and a member asking for a colleague's `owner=person-X` is `403`. `max_age` (`30m`/`12h`/`7d`/ms) demotes hosts whose `last_seen` is older than it to unsatisfiable (the liveness filter). `404` unknown/non-profile id; `422` bad `max_age`/`owner` |
 
 Path parameters (node ids, project slugs) must match
 `^[a-z0-9][a-z0-9-]*$`. Request bodies are capped at 1MB
@@ -670,6 +671,14 @@ anything with a token.
 | `POST /v1/runs/{id}/steps/{sid}/claim` `{iteration?}` | run worker (workers/shim) | claim a ready step → `{run_id, step, lease, state}`; a step that isn't claimable is a 409 |
 | `POST /v1/runs/{id}/steps/{sid}/complete` `{lease, status, result?, log?, iteration?}` | run worker (workers/shim) | report a verdict (`status: succeeded \| failed` only — anything else is 422). An expired/superseded lease is `409 lease_expired`; a same-generation retry that disagrees with the recorded outcome is `409 outcome_conflict` — redo the work under a fresh lease |
 | `GET /v1/runs/{id}` | `spor run status` | full run record: `{run_id, status, project, title, initiator, workflow, workflow_version, lineage, state, revision, timestamps?}` |
+| `POST /v1/executions` `{node_id, factory, gates: [{id, node_id?}], boundary, repo?, machine?, ttl_ms?}` | `spor work` (the factory controller, at the execution hold) | **factory execution state** (task-spor-hosted-factory-execution-state server-side; the CLIENT half is task-spor-client-execution-store-adapter, EXECUTION-STATE.md in spor-server is the contract): open — or idempotently re-read — the execution for a work item under a factory, PINNING the item's, the factory's and each named gate node's revision at open, taking the first lease at **fence 1** → `200 {execution, fence, replayed?}`. The execution id is content-addressed over `(tenant, node_id, factory, pipeline_attempt)` — `exec-<16 hex>` of the NUL-joined tuple — with the tenant derived from the identity (never the body) and the attempt from the item's own settled history, so a retried open lands on the same record (`replayed: true`, the fence echoed only to its owner). A live execution under a DIFFERENT factory is `409 execution_open`; a server with no execution store configured answers `503 unavailable`, and an older server that does not serve the route at all 404s — the client falls back to its machine-local store on either and stamps which store it opened (`impl_claim.store`); a merely UNREACHABLE server is a refusal, never a fallback |
+| `GET /v1/executions?node_id=&stage=&limit=` | `spor executions`, monitors | the tenant's executions, newest-updated first, each with the derived `boundary_reached`/`terminal` → `{executions, count}`. The read half of "a dead worker cannot leave invisible gating slots": every live execution is listed with its owner, lease expiry and stage, renewed or not |
+| `GET /v1/executions/{id}` | `spor executions <exec-id>` | one execution: `spec_version`, the pinned `item`/`factory`/gates, `stage`, every attempt, every gate's verdict, the candidate, the owner `{worker, machine, lease_expires_at, fence}`, `completion {boundary, written_at, resolver}`, `seq`, plus the derived `boundary_reached` and `terminal`. A cross-tenant id is `404`, not `403` |
+| `GET /v1/executions/{id}/events` | `spor executions <exec-id> --events` | the durable ordered event log, oldest first → `{events, count}` — the record of last resort the record is a materialized view of |
+| `POST /v1/executions/{id}/claim` `{takeover?, machine?, ttl_ms?}` | the controller at every pipeline pass (launch, resume, re-gate) | take the lease: a free, expired or same-owner execution is claimable (a same-owner re-claim KEEPS its fence; a different worker's advances it); an unexpired lease held by someone else is `409 already_owned` (or `409 lease_live` with `takeover: true`) and is never stolen. The client treats `already_owned` as the foreign hold H2 refuses, and settles a resumed pipeline `blocked` naming the holder rather than judging an execution it does not own |
+| `POST /v1/executions/{id}/renew` `{fence, ttl_ms?}` | the controller's per-pass heartbeat, and the completion write's ownership check | push the lease out without moving the fence; `409 fence_stale` after a takeover (a fenced-out worker cannot resurrect its lease), `409 lease_expired`/`not_owned` otherwise. The client renews every execution it holds once per `spor work` pass, and CONFIRMS ownership with exactly this call before writing a resolving edge |
+| `POST /v1/executions/{id}/release` `{fence}` | `spor release --execution` | hand the execution back; only the live fence-holder may |
+| `POST /v1/executions/{id}/events` `{fence, event: {type, …, idempotency_key?}}` | the controller, at every §7.3 transition | record one event of the fixed vocabulary (`stage.started`, `stage.observed`, `candidate.submitted`, `gate.started`, `gate.settled`, `rescue.started`, `integration.started`, `integration.settled`, `escalation.filed`, `completion.written`) under the fence → `200 {execution, seq, idempotency_key}`. A key already on the durable log is a no-op `{replayed: true}` — checked BEFORE ownership, so a retry from a fenced-out worker reads "already recorded", not a conflict; a terminal execution answers `409 execution_terminal` to everyone. `422 invalid_event`/`unknown_gate` for an off-vocabulary or off-pinned-list event; `409 candidate_conflict`/`no_candidate`/`gates_unsettled`/`boundary_not_reached` for a transition the record's state refuses. The client stamps the deterministic key on every event it sends (EXECUTION-STATE.md §5's table), spools an undeliverable one to a per-execution OUTBOX (`journal/executions/<tenant>/exec/<id>.outbox.jsonl`) before the attempt, and replays the outbox in order ahead of every later event — so a partition keeps its durable local evidence and replay converges. The server's own enforcement rides beside this door: a `put_node`/`add_edge` that ADDS a `resolves`/`answers` edge into an item whose live execution has not reached its pinned boundary is `409 execution_boundary` (EXECUTION-STATE.md §6.1) |
 
 ## 4. Identity and auth
 
@@ -920,6 +929,19 @@ Failure policy: **fail open, never block** — a hook must never break a
 session; connection refused, timeout, 5xx, and auth failure all collapse to
 "the graph has nothing for you".
 
+**The execution store (task-spor-client-execution-store-adapter).** The factory
+controller's coordination state — one execution per (item, factory, pipeline
+attempt), a fenced lease, an ordered idempotent event log, a pinned completion
+boundary — lives in the SERVER's `/v1/executions` store in remote mode and in a
+shape-compatible machine-local store (`$SPOR_HOME/journal/executions/<tenant>/`,
+the server's own layout and ids, tenant `local`) in personal mode; `spor
+executions` reads either, WORKERS.md §10.15 is the contract. Two knobs:
+`execution.leaseTtlMs` (`SPOR_EXECUTION_TTL`, default 15min, clamped to the
+server's [60s, 8h]) is the lease a claim asks for, `execution.timeoutMs`
+(`SPOR_EXECUTION_TIMEOUT`, default 8s) bounds each round trip. Neither changes a
+factory that declares no `completion: {by: controller}` — a legacy run opens no
+execution.
+
 Because fail-open hides degradation by design — a crashing engine and a
 quiet success look identical, and stranded captures pile up unseen in
 `outbox/dead/` — the client carries three operability surfaces
@@ -971,6 +993,20 @@ Contract:
   `nodes/` and brief `history/` are committed. The SessionEnd distiller leaves
   distilled nodes **uncommitted** (for the human PR flow) instead of
   auto-committing when the graph home is the same git repo as the code repo.
+- **Factory candidate bundles are a THIRD, separate home** — they do not
+  follow this marker binding at all
+  (task-spor-candidate-store-home-vs-shared-graph-home-trap). A factory's
+  `implementation.candidate.bundle_store` defaults to
+  `file://<userConfigHome>/candidates`, i.e. this machine's personal env home,
+  never this marker's shared graph home — binary bundle artifacts have no
+  business riding a shared repo's git flow by default. Its `.gitignore` line
+  is therefore maintained separately, at whichever directory the store
+  actually resolves to (`ensureStoreGitignore` in
+  `lib/shell/candidate-publish.js`), only when that directory is itself a git
+  working tree — so an operator who deliberately declares `bundle_store`
+  *inside* this marker home gets the same hygiene here, and everyone else's
+  personal home gets it there instead, rather than a fixed line landing in
+  whichever home happens to be wrong.
 
 ### 6.2 Multi-tenant credentials (the credential store + tenant selector)
 
@@ -1004,6 +1040,21 @@ machine-local — never committed, always in the shared-graph `.gitignore`):
   `.spor` `org:` marker (committable, nearest-ancestor — the remote-mode sibling
   of the `graph:` binding in §6.1) > store `default` > legacy flat config.json
   `server`+`token` (migrated on read) > local.
+- **Unknown `--org` refuses.** `--org` is the one selector that does not fall
+  through: naming an org with no stored credential is an error (exit 1, the
+  stored orgs listed), not a quiet demotion to the active tenant — which would
+  answer a read from the wrong graph and land a write in it while the operator
+  believes they are scoped elsewhere
+  (issue-spor-cli-unrecognized-org-fallback). Only the credential-**acquiring
+  invocations** are exempt — `spor login`, `spor join`, `spor auth login` —
+  because naming an org you have no credential for **yet** is what those are
+  for; the other `auth` subcommands (`logout`, `switch`, `whoami`, `list`)
+  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.
 - **Refresh.** A 401/403 on a tenant carrying a `refresh_token` transparently
   refreshes against its issuer (`grant_type=refresh_token`) and retries once.
 - **Byte-identical.** With no credential store and only a flat

package/GRAPH.md

@@ -96,6 +96,21 @@ Rules:
   viewer — the renew-the-cert / schedule-the-audit shape, kept with the
   work instead of in one person's calendar. Everything else (compiles,
   briefings, edges) sees a dormant node normally.
+- `execution` / `execution_at` are optional flat scalars a factory worker
+  running under `completion.by: controller` stamps on the work item it is
+  about to implement (the **execution hold**, WORKERS.md §10.13,
+  FACTORY-IMPLEMENTATION-STAGE.md §4.5): `execution: exec-<16 hex>` names the
+  execution, `execution_at` when it was stamped, and a person's release adds
+  `execution_released_by`. While `execution:` is present the item is HELD:
+  `resolutionMap` counts no inbound resolving edge into it and `isLive` reads
+  it live whatever its status says, so a premature `resolves` edge or a
+  hand-flipped `done` retires nothing until the controller's completion write
+  removes the key in the same write as the terminal status. The seed task and
+  issue schemas refuse a completion status on a node still carrying the key,
+  and their `get()` rides `execution_hold` (the id, the stamp, the inert
+  resolvers) instead of `resolution`. A person ends a hold explicitly with
+  `spor release <id> --execution <exec>`; never hand-delete the key on a node a
+  live worker holds.
 - 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
@@ -340,6 +355,29 @@ and hook are pinned together by `test/seed-declarative-status-policy.test.js`,
 which drives every seed schema's hooks through the sandbox and fails if the two
 disagree; read the live values with `spor schema <type>`.
 
+**The attestation path — how completion is verified**
+(issue-spor-offline-check-get-hook-resolution-proxy). A separate top-level
+`resolution` block, one key: `resolution.verified_by`, either `edge` (only a
+live inbound resolving `resolves`/`answers` edge attests this type's
+completion — task, issue, question, incident) or `status` (the node's own
+terminal status retires it — decision, finding, capture-pending, and every
+other type). Remote dispatch's terminal-state verify reads it to decide what
+it is looking for on a finished run (WORKERS.md §7), through
+`registry.isEdgeVerified(type)` locally and the `resolution` key of
+`GET /v1/schema` remotely. It USED to infer the answer from whether the
+schema attached a `get()` hook at all: that verb is the general-purpose
+read-time enrichment hook, so its presence was never evidence about
+resolution, and the first status-retired type to adopt one for anything else
+(a held-note, an execution hold) would have flipped to edge-verified — a run
+that genuinely finished the work then reads as unattested, files a report
+claiming a missing edge that type never has, and hands its lease back. A
+schema declaring neither value still falls back to that proxy, so a resident
+override written before the key existed is honored unchanged; every schema in
+the seed and candidate packs declares one, pinned against its own hook by
+`test/seed-declarative-status-policy.test.js`. Like the completion policy
+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
@@ -458,12 +496,53 @@ beside `gates`, parsed the same fail-closed way — and an optional `rescue`
 block (task-spor-factory-rescue-lane): a strong-model profile the runner
 dispatches at a gate's exhaustion BEFORE any human escalation, to diagnose,
 fix and file factory-improvement tasks, re-running the gates on what it
-commits (WORKERS.md §10.10). Both `gate` and `factory` are
+commits (WORKERS.md §10.10). Two further optional blocks declare the step
+BEFORE the gates, and who writes the outcome of them all
+(dec-spor-factory-implementation-stage-contract): `implementation` is the stage
+that PRODUCES the candidate the gates judge — the one step of the pipeline a
+factory could not describe, its budget the worker's global watchdog and its
+only retry a machine-local cooldown while every judging step was declared data
+— and `completion` says WHO writes the resolving edge that retires the work
+item, and WHEN. The stage routes by PROFILE and by nothing else:
+`command`/`args`/`argv`/`bin`/`exec`/`entrypoint`/`env`/`report`/`session`/
+`launch_mode`/`identity_mode` are refused BY NAME rather than dropped, because
+a graph write must never define what a machine executes
+(dec-spor-declarative-harness-machine-binds-execution) — a bespoke implementer
+is a `dispatch.harness.<id>` declaration on the MACHINE. Beside `profile` it
+declares `instructions` (appended to the worker contract, never replacing it),
+`author_checks` (the command gate ids the implementer runs itself — default
+NONE, since the gate re-runs the suite from the trusted ref regardless and an
+author run of the same suite is duplicate spend), `budget`
+(`run_max_ms`/`run_idle_ms` INHERIT the worker's own ceilings when undeclared,
+`attempts` is the code pool), `retry` (the separate infrastructure pool an
+outage spends instead of the code's) and `candidate` (`require_clean`, and
+`publish: bundle|branch|both` with `bundle_store`/`remote` — a candidate always
+carries a portable reference, so there is deliberately no `none`).
+`completion.by` is `agent` (today's behavior: the implementer writes the edge
+and flips the status) or `controller` (the runner writes both at the boundary,
+so a pending or refused pipeline releases none of the item's dependents — the
+`execution` hold above is what keeps a premature edge inert meanwhile), and it
+defaults to `controller` for a factory whose `implementation` block PARSES,
+`agent` otherwise. `completion.after` is the boundary — `gates` or
+`integration` — defaulting to the LAST stage the factory actually declares so
+it is reachable by construction; naming `integration` with no integration block
+is fatal, since a boundary that can never be reached leaves every item
+unresolved forever. WORKERS.md §10.12-§10.14 documents what runs today (the
+candidate, the execution hold, the controller's completion write, candidate
+publication to a `bundle`/`branch`, and `candidate.require_clean`'s own
+refusal at the pin) and what is parsed and pinned but not yet executed (the
+stage's own dispatch loop). Both `gate` and `factory` are
 `capturable: false` (the distiller never drafts one: a factory changes what a
 worker will accept, so it is written deliberately) and both arrive by adoption
 rather than in the seed, for the same reason. WORKERS.md §10 documents the
 runtime contract; the payload keys are documented on the candidate nodes
-themselves.
+themselves. Every declared count or ms field in a gate/factory payload
+(`cycles`, `reruns`, `timeout_ms`, `poll_ms`, `approval_timeout_ms`,
+`await_ms`, rescue's `attempts`) is parsed through a guarded helper
+(`countOr` in `lib/kernel/gates.js`): a value that isn't
+readable as a number — blank, `null`, `false`, an array, or the wrong type —
+takes the field's documented default rather than silently clamping to the
+floor, while a readable but out-of-range number still clamps.
 
 A complete worked example — a `escalation` type with a required `severity`
 field (enforced in `validate`) and an `open → mitigated → closed` status machine
@@ -713,7 +792,11 @@ edges:
   marker dir) and overrides `SPOR_HOME` in local mode; a contributor with their
   own personal `SPOR_HOME` still inherits the shared graph inside the repo. See
   API.md §6.1 for the full contract (precedence, the generated `.gitignore`, and
-  the distiller's PR-flow behavior).
+  the distiller's PR-flow behavior). A factory's candidate bundle store does
+  **not** follow this binding — it stays machine-local under `userConfigHome()`
+  by default even when a `graph:` binding is active, so the two homes can
+  legitimately differ; API.md §6.1 says where each home's `.gitignore` hygiene
+  actually lands.
 - **Git worktrees** resolve to their main repo, not the worktree directory's
   basename. A linked worktree shares the main repo's root-commit sha and
   remotes, so inferring identity from its (markerless, often throwaway-named)
@@ -983,11 +1066,21 @@ date: 2026-06-18
   launcher the client ships no in-code adapter for — a team's modified build,
   an internal wrapper — in which case the profile still carries nothing but the
   id, and each machine that should run it declares `dispatch.harness.<id>`
-  ({`command`, `args`, `label`, `report`, `session`}) in its own
+  ({`command`, `args`, `label`, `report`, `session`, optional `posture`}) in its own
   `$SPOR_HOME/config.json`. **A graph write must never define what a machine
   executes:** a profile carrying `command`, `args`, `argv`, `bin`, `exec`,
   `entrypoint`, `env`, `report`, `session`, `launch_mode` or `identity_mode` is
-  REFUSED by `spor dispatch`, not honoured and not silently ignored. So an org
+  REFUSED by `spor dispatch`, not honoured and not silently ignored.
+  A declaration may add `posture: "unattended" | "attended" | "read-only"`
+  to describe the permissions behavior of its machine-bound command and args.
+  The declaration grants no permissions and changes no argv; the operator
+  must configure the launcher to enforce the stated posture. Preflight uses
+  the same posture rules as built-in adapters: unattended workers require
+  unattended writes, while `--read-only` requires a read-only launcher.
+  Stricter invocation flags are never silently discarded or widened; foreign
+  harness flags still refuse. Omission preserves the existing operator-bound
+  warning and behavior; unknown values are rejected. The capability probe's
+  `machine.harnesses` shape is unchanged. A team
   can publish a profile naming an unadapted harness and only the boxes whose
   OWNER bound that id will take the work (a machine with no binding fails
   satisfiability below).

package/QUEUE.md

@@ -431,7 +431,11 @@ signals via its schema's `queueSignals()`:
   `get()` hook, which rides a `held` note along on `get_node` (it shares the
   reference-edge narrowing; it has no `front`, so the floor has no twin there).
 - **staleness** — anchors superseded or gone; high staleness suggests
-  closing, not doing.
+  closing, not doing. A node's own outbound `supersedes` edges are excluded
+  from the fraction (numerator and denominator both) — their target is
+  retired by definition, so counting them as rot would permanently inflate
+  staleness for a consolidator node doing exactly what a `supersedes` edge is
+  for (issue-spor-queue-staleness-supersedes-false-positive).
 - **cold_neighbors** — the count of the node's traversable neighbors whose
   git-derived `updated_at` is newer than its own: a node that went cold while its
   neighborhood kept moving ("context moved around it"). Fed by the

package/README.md

@@ -237,6 +237,14 @@ To see what would be launched without starting anything:
 spor dispatch issue-86 --print
 ```
 
+`--print` is a full diagnostic, not just a prompt preview: it runs the same
+resolution path a real dispatch does and reports the **effective tenant and the
+selector that chose it**, the profile and harness, the **write posture**, the
+**candidate workspace and whether it is isolated**, and a `preflight:` verdict
+saying whether an unattended worker would be refused there and why. It performs
+none of a dispatch's side effects — no claim, no child, no worktree, no config
+write — and never echoes a credential.
+
 To provide your own prompt wrapper:
 
 ```bash
@@ -285,30 +293,46 @@ Terminal records age out after `dispatch.runRetentionMs` (default 14 days).
 
 That state describes how the **process** ended. Alongside it every run also
 carries its **outcome** — what the run did to the graph — as exactly one of
-`resolved`, `reported`, or `failed`:
+`resolved`, `reported`, `declined`, or `failed`:
 
 | outcome | meaning |
 |---|---|
-| `resolved` | the graph itself shows a live resolving edge (`resolves`/`answers`) onto the target node. Verified by re-reading the node after the run, never inferred from an exit code and never taken from the agent's own word |
-| `reported` | no resolution, but the agent left a final report. It is filed as an artifact node linked to the target (`relates-to`) and **then** the lease is released, so the item returns to the queue carrying the work instead of vanishing into a dead run. `report_node_id` names the artifact — a filed report always reads `reported`, enforced or not |
-| `failed` | no resolution and no report filed — a launch failure, a crash before any report, an empty one, or a graph that refused the write. `terminal_note` carries the failure note. The lease is released, except where the report could not be filed (see the ordering rule below) or the target was one this runner cannot judge |
+| `resolved` | the graph itself attests completion — a live resolving edge (`resolves`/`answers`) onto the target node, or, for a type retired by its own status rather than by an edge, a status that has reached that type's terminal partition. Verified by re-reading the node after the run, never inferred from an exit code and never taken from the agent's own word |
+| `reported` | no attestation of completion, but the agent left a final report. An enforced run files it as an artifact node linked to the target (`relates-to`) and **then** hands the lease back, so the item returns to the queue carrying the work instead of vanishing into a dead run. `report_node_id` names the artifact — a filed report always reads `reported`, enforced or not; the converse does not hold, since an unenforced `reported` filed nothing |
+| `declined` | the agent declared the ITEM wrong rather than the work unfinished, by making the first line of its final report `DECLINED: <reason>`. An enforced run files the reason as a `finding` on the target, clears the target's `readiness: agent` stamp, and hands the lease back — the item goes to triage, never into a gate. The state is the agent's own declaration, so it stands whether or not those three land: an unenforced decline performs none of them, a finding the graph refuses leaves the lease deliberately held, and a refused readiness clear is recorded rather than fatal |
+| `failed` | no attestation and no report filed — a launch failure, a crash before any report, an empty one, or a graph that refused the write. `terminal_note` carries the failure note. An enforced run hands the lease back, except where the report (or a decline's finding) could not be filed at all — see the ordering rule below |
 
 The ordering is the contract: the report is filed before the lease goes back to
 the pool, so an interrupted run can leave a held lease with the report filed but
 never a released lease with nothing attached.
 
+Those legs are attempts, not postconditions of the outcome: each records its own
+verdict on the run record rather than being implied by the state. `report_node_id`
+/ `finding_node_id` are present only where the artifact actually landed,
+`readiness_cleared` says whether the stamp was cleared, and `lease_released` says
+whether the server *confirmed* the handback — a `false` there is an unconfirmed
+handback, not proof the lease is still held, and the remedy reconciles either way
+(`spor release <id>` is idempotent, and a claim someone else now holds answers
+`409`). WORKERS.md §8 is the field-by-field contract.
+
 Enforcement covers **supervised** launches (Claude Code, Codex, OpenCode, Copilot
-CLI — every built-in) against a team graph, targeting a node type whose
-completion is a resolving edge (`task`, `issue`, `question`, `incident`). A
+CLI — every built-in). A target's TYPE never costs a run its enforcement: both
+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
-local-mode dispatch, a free-text dispatch, a target retired by status instead of
-by an edge, and a run whose graph could not be reached are all classified
-best-effort and marked `terminal_enforced: false` — an unenforced run can never
-read `resolved`, and only an **enforced** `reported` promises a `report_node_id`
-(an unenforced run that merely ended cleanly reads `reported` with no artifact).
-A report is still filed wherever one exists and the graph is reachable, including
-for a target this runner cannot judge — the verdict is scoped, the agent's work
-reaching the graph is not.
+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
+target that reads attested complete is an enforced `resolved`, and only its other
+outcomes are unenforced. A report is still filed wherever one exists and the
+graph is reachable. Filing sits downstream of that verify leg, so a record this
+client writes unenforced today carries no `report_node_id` — but reach for the
+artifact by testing that key's presence, not by testing `terminal_enforced`,
+which is the flag for whether to trust `terminal_state` (WORKERS.md §8 has the
+retained-record case that distinction exists for).
 `spor runs` prints the outcome (tagging `(unenforced)`), the note, and the report
 artifact id; `spor runs --json` carries the same fields on each record.
 
@@ -321,7 +345,7 @@ routed profile, waits for its **terminal state**, and goes round again.
 ```bash
 spor work                                   # work the whole queue, one run at a time
 spor work --project spor --concurrency 2    # two runs in flight, scoped to one project
-spor work --once --print                    # show scope, pacing and candidates; launch nothing
+spor work --once --print                    # tenant, posture, workspace isolation, gate coverage, candidates — launch nothing
 ```
 
 It is pull, not push: nothing schedules a worker, it takes work. That is safe
@@ -336,6 +360,16 @@ It adds no guards of its own. Every launch goes through the same code path as
 this box cannot satisfy (never substituted), a profile that tries to declare
 what to execute, the same-machine duplicate guard, the auto-claim, worktree
 isolation and the terminal-state contract all apply exactly as they do one-shot.
+Two of those guards exist for the unattended case specifically (WORKERS.md §3.1)
+and are checked **before the claim**: the resolved harness must have a
+non-interactive **write posture** — a Claude Code worker with no
+`--permission-mode` is refused rather than launched into a run where every write
+comes back permission-blocked, and preflight never sets a posture for you — and
+the **candidate workspace** must be free of other live writers, which with
+`dispatch.worktree` off means one dispatch at a time per checkout (turn
+`dispatch.worktree` on before running a worker at `--concurrency` above 1). (A
+`dispatch.worktreeSetup` hook does not turn isolation on; declaring one without
+`dispatch.worktree` is diagnosed, not silently honoured by halves.)
 Selection is the same filtered page `--from-queue` picks its one item from,
 minus anything whose derived readiness is `human` — a worker never claims work
 meant for a person — and minus anything already in flight on this machine. An
@@ -412,6 +446,26 @@ nodes. It also maintains one from its own telemetry ("why did the last three
 fail review"), and seeds a test-writer lane when there is no acceptance suite
 to gate on yet. It authors data only; enforcement stays in `spor work`.
 
+A factory that completes items itself (`completion: {by: controller}`) keeps
+its coordination state in an **execution store**: one execution per item and
+pipeline attempt, pinned to the definition it was opened under, leased with a
+fence, moved by an ordered idempotent event log, and completed only at its
+declared boundary. On a team server that store is the server's own
+(`/v1/executions`, where a resolving edge into a held item is refused at the
+door); in personal mode it is a shape-compatible local store under your Spor
+home. `spor executions` reads either:
+
+```bash
+spor executions                      # every execution this box drives
+spor executions --node task-x        # one item's executions
+spor executions exec-4da6d4763543a301 --events
+```
+
+A worker that loses its lease — its box went quiet and another took the
+execution over — never writes the resolving edge on the strength of its local
+state; what it recorded while partitioned is replayed idempotently when it
+reconnects. [WORKERS.md](WORKERS.md) §10.15 has the contract.
+
 ### Choosing a harness
 
 By default, `spor dispatch` launches a Claude Code agent in headless print mode
@@ -465,12 +519,14 @@ 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. The one exception: `--permission-mode
 bypassPermissions` against a Codex profile has a real Codex equivalent
-("run fully unattended"), so instead of erroring it translates to `--sandbox
-danger-full-access --approval-policy never` (an explicit `--sandbox`/
-`--approval-policy` you also pass wins over that default) and prints a loud
+("run fully unattended"), so instead of erroring it translates to exactly
+`--sandbox danger-full-access --approval-policy never` and prints a loud
 warning naming the translation — so an orchestrator or script that passes the
-same bypass flag to every dispatch regardless of harness keeps working.
-Every other permission-mode value still hard-errors against Codex.
+same bypass flag to every dispatch regardless of harness keeps working. The
+translation is fixed: an explicit `--sandbox`/`--approval-policy` beside the
+bypass is a contradiction and is refused, not an override (say the posture in
+Codex flags alone if you want a different one). Every other permission-mode
+value still hard-errors against Codex.
 
 The harnesses do not all confine a run the same way. Codex dispatch defaults to
 `--sandbox workspace-write`, so its filesystem reach is bounded. OpenCode
@@ -866,3 +922,34 @@ Spor is licensed under Apache-2.0. See `LICENSE` and `NOTICE`.
 
 Contributions are welcome under inbound = outbound Apache-2.0.
 
+
+To cancel a factory execution still owned by another worker or machine, use the
+explicit person door:
+
+```sh
+spor release <node-id> --execution <execution-id> --force --reason "Why this execution must stop"
+```
+
+This requires a person credential on a server. Agent credentials cannot use the
+command, including an agent owned by that person. Authorization uses the existing
+tenant graph boundary; it does not introduce a separate project ACL. In local
+mode, the graph home's Git email must bind to a person node and `dispatch.agent`
+must be unset. That local check trusts filesystem/configuration access; it is not
+cryptographic proof of a human at the keyboard.
+
+The command inspects the exact execution, then releases it only if its observed
+state is unchanged. The journal records the person, time, reason, prior owner and
+fence. Late writes from the old worker are refused; release does not mark the
+work complete. The execution acknowledgement precedes graph hold cleanup, and
+cleanup never clears a different execution's hold. No local dispatch record is
+required. If the response is lost or graph cleanup fails, a credential-bound
+cleanup intent stays in `journal/person-force-release` under the user config
+home. Repeat the same explicit command and reason to recover. Receipt recovery
+only reads the authoritative acknowledgement and retries exact graph cleanup;
+it never submits a force release unattended.
+
+Local execution mutations use a filesystem lock across processes. A live writer
+keeps its lock regardless of elapsed time; a verifiably dead process can be
+recovered. Malformed ownership or an abandoned breaker fails closed. Stop all
+local execution writers before manually removing such a lock from the execution
+item index directory; ordinary execution reads never repair or delete it.