@sporhq/spor 0.5.1 → 0.6.0

package/.claude-plugin/plugin.json

@@ -2,6 +2,6 @@
   "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.5.1",
+  "version": "0.6.0",
   "author": { "name": "losthammer" }
 }

package/API.md

@@ -173,16 +173,21 @@ Only an unreachable ingestion model is an error (`ingestion_unavailable`).
 ### `my_queue`
 
 The decision queue (QUEUE.md §4/§5). Input `{ "project"?: "slug",
-"limit"?: 20, "offset"?: 0 }` → `{ "items": [{id, title, type, status,
+"types"?: ["task"], "exclude_types"?: ["capture-pending"], "limit"?: 20,
+"offset"?: 0 }` → `{ "items": [{id, title, type, status,
 priority, score, signals: {blocking, heat, staleness, age_days}, suggest:
 "do|close", why}], "count": N, "offset": 0, "returned_count": N,
 "total_count": N, "truncated": false, "next_offset": null, "questions": []
 }` — queueable live nodes ranked by the default blend, each with a one-line
 *why*. Items already retired by a live inbound resolves/answers edge are
 excluded whatever their status field reads; open gardener findings ride
-along per item as `findings`. Structured output additionally carries
-`view` — the queue projected into the view-tree catalog for the MCP-app
-widget (below).
+along per item as `findings`, capture-pending triage as `pending`, questions
+you asked as `asked`, and nodes whose review is requested of you as `reviews`
+(an open `review-requested` edge to your person node — the reviewer-facing
+twin of `questions`, surfaced through the same per-person routing filter;
+respond by flipping the edge to `reviewed-by` or `changes-requested-by`).
+Structured output additionally carries `view` — the queue projected into the
+view-tree catalog for the MCP-app widget (below).
 
 **Limit and pagination.** `limit` is the page size (default 20, **max
 100** — values above the max are clamped, not rejected); `offset` skips that
@@ -200,6 +205,16 @@ seen twice or skipped once across a re-rank, never a hard error. Walk the
 whole queue by re-calling with `offset = next_offset` until `next_offset` is
 null.
 
+**Node-type filter** (task-cc-queue-filtering-enhancements). `types` keeps only
+those node types in the ranking (a whitelist); `exclude_types` drops them (a
+blacklist). Given both, the include set is narrowed and then the excludes are
+removed from it (exclude wins on overlap). Like `project`/`assignee` this is a
+hard scope filter applied **before** scoring, so a filtered-out node is simply
+out of scope — the `counts_*`/`total_count` aggregates describe the filtered
+queue, not what the firehose hid. The type compared is the type the item
+surfaces as, so `exclude_types: ["schema"]` also hides schema-approval items.
+Omitting both (or passing empty arrays) filters nothing.
+
 ### `ask_question`
 
 File a question the graph could not answer. Input `{ "text": "<the
@@ -280,14 +295,17 @@ endpoint is the REST twin of a core call:
 | `GET /v1/nodes/{id}` | /spor:brief | `get_node` semantics; when a live inbound resolves/answers edge contradicts a still-open status the response carries `resolution`, and open gardener findings about the node ride along as `open_findings` |
 | `POST /v1/nodes` | 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 |
 | `POST /v1/nodes/{id}/edges` `{type, to}` | scripts, mechanical writers | `add_edge` semantics (§1): normalize/flip, dedupe, append — no revision echo |
-| `POST /v1/nodes/{id}/status` `{status}` | scripts, mechanical writers | `set_status` semantics (§1): one-scalar update through the `transitions()` gate |
+| `POST /v1/nodes/{id}/status` `{status}` | scripts, mechanical writers | `set_status` semantics (§1): one-scalar update through the `transitions()` gate. Setting a work node to an in-progress status also CLAIMS it (same lease as `/claim` below) |
+| `POST /v1/nodes/{id}/claim` `{session?}` | `claim`/`set_status` MCP tools, `spor dispatch` | take the heartbeat-renewed lease (dec-cc-task-claim-lease): writes the durable `assigned` edge once, attributes to `$viewer` from the token (never an argument), and creates the ephemeral lease → `{ok, status, lease: {node_id, by, expires, expires_at, session, claimed_at}, edge}`. A live lease held by ANOTHER person is `409 conflict` naming the holder + expiry (re-claiming your OWN live claim just renews it). `session` scopes the heartbeat (omit to leave it person-scoped, so any of the claimer's sessions may renew — what `spor dispatch` does, since the launched agent renews from a different session) |
+| `POST /v1/nodes/{id}/renew` `{session?}` | post-tool heartbeat, `renew` MCP tool | bump the live lease's expiry only — no commit; the heartbeat that keeps a claim from lapsing. A lapsed/stolen lease is `409` (names the current holder). Person-scoped: any of the claimer's sessions may renew |
+| `POST /v1/nodes/{id}/release` | `release` MCP tool | 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}/commits` `{repo, sha}` | post-tool / link-commits | `link_commit`: append `repo@sha` to the node's `commits:` list (kebab-case repo slug, 7–40 lowercase hex, ≤40 commits per node); idempotent, prefix-aware dedup |
 | `GET /v1/commits/{sha}?repo=` | 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 |
 | `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, during, blocks?, needed_by?}, source?}` → ingestion model + validate + commit → `{status, ids, nodes, summary, warnings}`. `source: "distill"` marks backstop captures in the journal. `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 |
 | `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=&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, findings, policy?, generated_at}` — items retired by a live resolves/answers edge are excluded; items hidden by the viewer's `queue_mute` or parked by a future `wake:` date (QUEUE.md §4) are counted, never silently dropped; `questions`/`findings` are the routed-to-me-plus-unrouted views for the authenticated identity. `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. `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) |
+| `GET /v1/queue?project=&assignee=&type=&exclude_type=&limit=&offset=` | /spor:next, session-start | the ranked decision queue: `{items, count, offset, returned_count, total_count, truncated, next_offset, counts_by_type, counts_by_project, counts_by_suggest, muted?, dormant?, questions, asked, findings, pending, reviews, policy?, generated_at}` — items retired by a live resolves/answers edge are excluded; items hidden by the viewer's `queue_mute` or parked by a future `wake:` date (QUEUE.md §4) are counted, never silently dropped; `questions`/`findings`/`pending` are the routed-to-me-plus-unrouted views for the authenticated identity, `asked` is the questions you filed, and `reviews` is the nodes whose review is requested of you (an open `review-requested` edge to your person node — explicitly targeted, no unrouted fallback). `limit` is the page size (default 20, **max 100**, clamped not rejected) and `offset` skips that many items in the ranked order (default 0); the `counts_*`/`total_count` aggregates always cover the FULL ranked set regardless of the page, so one call answers "how many issues vs tasks" without paging, while `truncated`/`next_offset` let a client walk the rest by re-requesting with `offset=next_offset` until `next_offset` is null. Pagination is offset over a point-in-time ranked slice (the queue re-ranks every call), not a cursor — it resumes the same slice only across an unchanged ranking. `project` resolves through the shared up-resolution (dec-spor-queue-slug-resolves-to-grouping): a bare repo slug unions its home-project grouping's member queues, the repo NODE id (`repo-<slug>`) pins one repo, a grouping id (`proj-<slug>`) is used directly; **omitting `project` is the cross-project firehose** (every repo's queue at once). `assignee=<person-id>` scopes to the work that person carries (their `assigned`/`stewards` edges) — a manager's "who is carrying what"; `assignee=me` binds to the caller (empty if the token maps to no person node). `type=`/`exclude_type=` (comma-separated, repeatable) whitelist/blacklist node types from the ranking (exclude wins on overlap) — a hard scope filter applied before scoring, so the aggregates describe the filtered queue (task-cc-queue-filtering-enhancements) |
 | `POST /v1/questions` `{text, title?, mentions?}` | 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, routed_to, via, asker, revision, warnings}` |
 | `POST /v1/gardener` | ops cron / on demand | run a gardener sweep now; findings filed as queue items → `{filed, resolved, ..., generated_at}` |
 | `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 |

package/GRAPH.md

@@ -169,9 +169,13 @@ least two — the definition-of-done quorum gate.
   excluded (the self-approval floor — a policy can't be used to launder it).
   The first concrete rule is the **definition-of-done quorum gate**: a work
   node's `done` transition additionally requires a quorum of approvals from
-  qualified roles. (The `reviewed-by`/`approved-by` edge types and a native
-  review surface ship with review-as-graph-object; the policy kind, scope
-  selection, and the gate AND are landed now.)
+  qualified roles. The `review-requested`/`reviewed-by`/`changes-requested-by`
+  edge types ship in the seed pack (review-as-graph-object); a single edge
+  flips type in place across the review lifecycle, `reviewed-by` is what the
+  quorum counts, and an open `review-requested` edge surfaces the node in the
+  named reviewer's queue. The gate context also carries `view.changes_requested`
+  (the `changes-requested-by` edges, same author-excluded shape) so a policy
+  may block `done` while a qualified reviewer's change request is outstanding.
 - **Policy nodes go through the same proposal/activation flow they govern** —
   a proposed policy is inert until a *different* identity activates it (the
   native floor protects against self-amendment circularity).
@@ -564,11 +568,14 @@ server-side (issue-cc-onboarding-email-mismatch-silent-degradation).
 | `blocks`         | 0.7    | target cannot proceed until this node does       |
 | `answers`        | 0.7    | this node answers that question (inverse `answered-by`); pulls the answer through the asker's next compile |
 | `assigned`       | 0.5    | work is assigned to this person                  |
+| `reviewed-by`    | 0.5    | this person reviewed and approved the node — counts toward a policy quorum |
+| `changes-requested-by` | 0.5 | this person reviewed the node and requested changes — not an approval |
 | `relates-to`     | 0.5    | weak association                                 |
 | `mentions`       | 0.5    | weakest association                              |
 | `stewards`       | 0.4    | this person stewards an area/spec/norm — the Tier-2 question-routing key |
 | `grouped-under`  | 0.3    | this repo's home project grouping (inverse `groups`); structural membership, not work dependency |
 | `routed-to`      | 0.3    | a question routed to this person for answering   |
+| `review-requested` | 0.3  | a review of this node is requested of this person (pending) — surfaces in their queue |
 | `compiled-for`   | —      | briefing → its task/query (provenance only)      |
 | `shaped-by`      | —      | briefing → corrections applied (provenance only) |
 
@@ -579,6 +586,16 @@ documented under "People, routing, and onboarding" above. `assigned` and
 the area they own; `answers` points from any answer node back at the
 `question-` it resolves.
 
+`review-requested`, `reviewed-by`, and `changes-requested-by` are the
+review-as-graph-object edges (a work node → a `person-`): a single edge that
+flips type in place across the review lifecycle — `review-requested` while a
+reviewer's verdict is pending (surfaced into their queue), `reviewed-by` once
+they approve (counted by the definition-of-done quorum gate), or
+`changes-requested-by` once they ask for changes. They are the canonical,
+source-blind record a native review surface and the GitHub adapter both write;
+a review *node* is deferred to when Spor owns the thread
+(dec-spor-definition-of-done-org-policy).
+
 High-weight edges decay slowly across hops; they are what makes structural
 traversal beat similarity search. Prefer one precise high-weight edge over
 three `relates-to`.

package/QUEUE.md

@@ -306,15 +306,25 @@ approvals from qualified roles: `view.approvals` is the node's
 The enabling hook (`view.actor`) shipped with the floor, so this was net-new
 policy-kind work, not core surgery (GRAPH.md "The org-defined policy layer").
 
+**Review as a graph object** (review-as-graph-object, Stage 3) supplies the
+edges the gate counts. The seed pack ships three review-outcome edge types
+(work node → `person`): `review-requested` (a review is pending of that
+person), `reviewed-by` (they approved — what `view.approvals` carries and the
+quorum counts), and `changes-requested-by` (they asked for changes — carried
+separately as `view.changes_requested`, never an approval). A single edge
+flips type in place across the lifecycle. An open `review-requested` edge
+surfaces the node in that reviewer's `my_queue` `reviews` set, through the same
+per-person routing filter questions and findings use — reviewer *selection* at
+request time and quorum *enforcement* at gate time are distinct points.
+
 Still on the layer's roadmap, beyond the quorum gate: the agent-vs-human
 claim-eligibility promoted-set (task-cc-claim-eligibility-policy), the
 queue-blend override absorbed as a `policy` rather than the separate
-`queue-policy` singleton (task-cc-schema-queue-policy-override), the seed
-`reviewed-by`/`approved-by` edge types + a native review surface
-(review-as-graph-object, Stage 3, which supplies the approval edges the quorum
-gate counts), and a fuller governs-traversal that walks the project/path
-hierarchy via `governs`/`governed-by` edges rather than matching the flat
-`governs.{types,projects}` scope.
+`queue-policy` singleton (task-cc-schema-queue-policy-override), the GitHub
+review/merge reflection adapter that writes these same edges from PR events
+(task-spor-github-review-adapter, Stage 4), and a fuller governs-traversal that
+walks the project/path hierarchy via `governs`/`governed-by` edges rather than
+matching the flat `governs.{types,projects}` scope.
 
 ## 3. The capture flow, end to end
 
@@ -442,6 +452,17 @@ The queue is a compile mode, not a new store:
   queues — the intuitive token returns the whole product; the repo NODE id
   (`repo-<slug>`) is the escape hatch back to one repo; an exact grouping id
   (`proj-<slug>`) is used directly; an ungrouped repo falls back to itself.
+  **Omitting `project` entirely is the cross-project firehose** (every repo's
+  queue at once); `/spor:next --all-projects` and `my_queue` / `GET /v1/queue`
+  with no `project` reach it.
+- `includeTypes`/`excludeTypes` (task-cc-queue-filtering-enhancements) whitelist
+  or blacklist node types FROM THE RANKING — `GET /v1/queue?type=&exclude_type=`
+  (comma-separated), `my_queue {types, exclude_types}`, and
+  `spor next --type/--exclude-type`. Given both, the include set is narrowed and
+  then the excludes are removed from it (exclude wins on overlap). Like `project`
+  it is a hard scope applied before scoring (the aggregates describe the filtered
+  queue), it composes with `project`/`assignee`, and the type compared is the one
+  the item surfaces as (so excluding `schema` hides schema-approval items too).
 - Exposed as `GET /v1/queue` (hooks, session-start "open front" line),
   `my_queue` (the registered MCP stub finally does work — and when Tier 2
   routing lands, routed questions and stewarded items join the same queue),

package/README.md

@@ -104,6 +104,14 @@ Spor already knows where that repo lives. Flags pass through to `claude`
 (`--model`, `--permission-mode`, `--agent`, `--name`); `--full` embeds the whole
 neighborhood and `--no-brief` skips the briefing.
 
+**No accidental duplicates.** A node dispatch won't double up on work already
+underway. In remote mode it auto-claims the task's heartbeat lease at launch, so
+dispatching a node a teammate already holds is refused with the holder named
+(`--no-claim` opts out). And in either mode, dispatching a node that already has
+a background agent in flight *on this machine* — each agent is named after its
+node id — is refused too, catching the same-person duplicate the lease's
+idempotent renew can't. `--force` overrides the local guard.
+
 **Your own prompt.** By default the briefing is prepended to a built-in prompt
 shell. Pass `--template <file>` (or set a default path in `dispatch.template`)
 to supply your own prompt instead, with Handlebars-style `{{placeholder}}`

package/bin/spor.js

@@ -242,10 +242,47 @@ async function cmdNext(cfg, args) {
   const pi = args.indexOf("--project");
   const explicit = pi >= 0 && args[pi + 1] ? args[pi + 1] : null;
   const pinned = cfg.get("queue.project", null);
+  // Cross-project scope (task-cc-queue-filtering-enhancements): --all-projects
+  // (alias --all) widens to the whole-graph firehose by dropping the cwd/pinned
+  // default scope. An explicit --project is more specific and still wins.
+  const allProjects = args.includes("--all-projects") || args.includes("--all");
+  // Node-type allow/deny (task-cc-queue-filtering-enhancements): repeatable +
+  // comma-splittable (--type task --type issue, or --type task,issue). Forwarded
+  // to the server as ?type=/?exclude_type= in remote mode; in local mode the raw
+  // flags pass straight through to lib/queue.js, which speaks the same flags.
+  const collectMulti = (name) => {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === `--${name}` && args[i + 1] != null) {
+        out.push(...args[i + 1].split(",").map((s) => s.trim()).filter(Boolean));
+      }
+    }
+    return out;
+  };
+  const inclTypes = collectMulti("type");
+  const exclTypes = collectMulti("exclude-type");
+
+  // In-flight agent surface (task-spor-cli-in-flight-surface). `spor next --json`
+  // stamps each item with an `in_flight` flag by cross-referencing the live
+  // background agents (`claude agents --json`); --hide-dispatched drops the items
+  // that already have one. Both are CLIENT-SIDE presentation: the server's queue
+  // can't see local agents, so this is computed here over either render path. The
+  // cross-reference only runs when one of the two flags asks for it, so the
+  // default queue path stays byte-identical (and never shells out to claude).
+  const wantJson = args.includes("--json");
+  const hideDispatched = args.includes("--hide-dispatched");
+  const needAgents = wantJson || hideDispatched;
 
   if (cfg.mode() === "remote") {
-    const slug = explicit ?? pinned ?? safeSlug();
-    const r = await remote.get(cfg, `/v1/queue?project=${encodeURIComponent(slug)}&limit=10`, { timeoutMs: 6000 });
+    // --all-projects drops the default scope (firehose); an explicit --project
+    // still wins over it. Otherwise fall back to the pinned default, then cwd.
+    const scopeSlug = allProjects && !explicit ? null : (explicit ?? pinned ?? safeSlug());
+    const qs = new URLSearchParams();
+    if (scopeSlug) qs.set("project", scopeSlug);
+    qs.set("limit", "10");
+    if (inclTypes.length) qs.set("type", inclTypes.join(","));
+    if (exclTypes.length) qs.set("exclude_type", exclTypes.join(","));
+    const r = await remote.get(cfg, `/v1/queue?${qs.toString()}`, { timeoutMs: 6000 });
     if (r.transport) {
       err(`offline — could not reach server (${r.error})`);
       return 1;
@@ -258,13 +295,27 @@ async function cmdNext(cfg, args) {
     // unknown-token detection is authoritative only locally (where we hold the
     // graph); remotely we can only observe an empty result for a SCOPED read and
     // softly say so on stderr. The cwd-default firehose (no explicit/pinned scope)
-    // is deliberately not flagged — an empty default queue is normal, not a typo.
-    const scoped = explicit ?? pinned;
+    // and an explicit --all-projects are deliberately not flagged — an empty
+    // result there is normal, not a typo.
+    const scoped = (allProjects && !explicit) ? null : (explicit ?? pinned);
     const count = (r.json && (r.json.count ?? (Array.isArray(r.json.items) ? r.json.items.length : null)));
     if (scoped && count === 0) {
       err(`project '${scoped}' returned an empty queue — check the slug / grouping id (the server scoped to it and found nothing)`);
     }
-    if (args.includes("--json")) {
+    if (needAgents) {
+      const q = r.json || {};
+      const { items, hidden } = annotateInFlight(q.items || [], dispatchedAgents(), hideDispatched);
+      q.items = items;
+      if (typeof q.count === "number") q.count = Math.max(0, q.count - hidden);
+      if (hideDispatched) q.hidden_dispatched = hidden;
+      if (wantJson) {
+        out(JSON.stringify(q));
+        return 0;
+      }
+      renderQueue(q, hidden);
+      return 0;
+    }
+    if (wantJson) {
       out(JSON.stringify(r.json));
       return 0;
     }
@@ -273,22 +324,145 @@ async function cmdNext(cfg, args) {
   }
   // local: byte-identical passthrough. When no --project was given but a default
   // is pinned, inject it so the local read inherits the same default scope as
-  // remote; otherwise pass args untouched (preserving the local->global default —
-  // we never inject safeSlug() locally).
-  const localArgs = !explicit && pinned ? [...args, "--project", pinned] : args;
-  return passthrough("queue.js", localArgs);
+  // remote — UNLESS --all-projects asked for the firehose. Otherwise pass args
+  // untouched (preserving the local->global default — we never inject safeSlug()
+  // locally). --type/--exclude-type ride through; lib/queue.js parses them.
+  const localArgs = (!explicit && pinned && !allProjects) ? [...args, "--project", pinned] : args;
+  // Default path: byte-identical passthrough (no agent cross-reference). Only the
+  // --json / --hide-dispatched view captures queue.js's result to annotate it.
+  if (!needAgents) return passthrough("queue.js", localArgs);
+  return nextLocalInFlight(localArgs, { wantJson, hideDispatched });
+}
+
+// Local in-flight surface (task-spor-cli-in-flight-surface). The default local
+// `next` is a byte-identical passthrough to lib/queue.js; when --json or
+// --hide-dispatched asks for the agent-aware view we run queue.js with --json,
+// capture its ranked result, cross-reference dispatchedAgents(), and re-emit.
+// queue.js's stderr (e.g. the unknown-project note) is inherited so it still
+// surfaces; an unparseable stdout falls back to forwarding it verbatim, so an
+// error path is never swallowed. The flags are presentation-only — strip them
+// before handing argv to queue.js (which doesn't know them) and force --json.
+function nextLocalInFlight(localArgs, { wantJson, hideDispatched }) {
+  const passArgs = localArgs.filter((a) => a !== "--json" && a !== "--hide-dispatched");
+  passArgs.push("--json");
+  const r = spawnSync(process.execPath, [path.join(ROOT, "lib", "queue.js"), ...passArgs], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"],
+  });
+  const status = r.status == null ? 1 : r.status;
+  let q;
+  try {
+    q = JSON.parse(r.stdout);
+  } catch {
+    if (r.stdout) process.stdout.write(r.stdout); // forward queue.js's own output
+    return status;
+  }
+  const { items, hidden } = annotateInFlight(q.items || [], dispatchedAgents(), hideDispatched);
+  q.items = items;
+  if (typeof q.count === "number") q.count = Math.max(0, q.count - hidden);
+  if (hideDispatched) q.hidden_dispatched = hidden;
+  if (wantJson) {
+    out(JSON.stringify(q, null, 2)); // match queue.js --json (pretty, 2-space)
+    return status;
+  }
+  renderQueueLocalText(q, hidden);
+  return status;
+}
+
+// Mirror lib/queue.js's HUMAN render for the local --hide-dispatched text path
+// (the --json path re-emits queue.js's own object, so only this form is
+// reconstructed). Kept byte-identical to queue.js by a conformance test — if
+// queue.js's line format moves, that test fails and both must move together
+// (norm-cc-byte-identical-refactor). count was already decremented by `hidden`,
+// so the "(N more — raise --limit)" overflow math is unaffected by hiding.
+function renderQueueLocalText(q, hidden = 0) {
+  const items = (q && q.items) || [];
+  if (!items.length) out("queue empty — nothing queueable and live");
+  for (const [i, it] of items.entries()) {
+    out(`${i + 1}. [${it.score}] ${it.id} — ${it.title} (${it.type}${it.status ? `, ${it.status}` : ""}${it.suggest === "close" ? ", suggest: close" : ""})`);
+    out(`   ${it.why}`);
+  }
+  if (q.count > items.length) out(`(${q.count - items.length} more — raise --limit)`);
+  if (q.muted > 0) out(`(${q.muted} muted — your queue_mute)`);
+  if (hidden > 0) out(`(${hidden} in-flight hidden — --hide-dispatched)`);
+}
+
+// Active background agents keyed by node id (task-spor-cli-in-flight-surface).
+// `spor dispatch` names each background agent after the node id it works
+// (cmdDispatch: name = name || nodeId), so `claude agents --json` lets the queue
+// CLI mark which items already have an agent in flight — a NO-LLM, parseable
+// cross-reference that needs no model guidance. Returns Map<node-id, agent[]> of
+// the BACKGROUND agents still active (state !== "done"), each summarized to
+// {id, name, state, status, cwd}. FAIL-SOFT by contract (the feature is a pure
+// enhancement): the claude binary absent / a nonzero exit / a timeout /
+// unparseable output all yield an EMPTY map, never an error — so `spor next
+// --json` still works in Cowork and plain-shell contexts where claude is absent
+// (every item then reads in_flight:false). SPOR_FAKE_AGENTS_JSON injects canned
+// output for tests, mirroring SPOR_FAKE_MCP_LIST; all claude shell-outs route
+// through claudeCmd() so an SPOR_CLAUDE_CMD stub works too.
+function dispatchedAgents() {
+  try {
+    let text = process.env.SPOR_FAKE_AGENTS_JSON;
+    if (text == null) {
+      const cmd = claudeCmd();
+      if (cmd === "claude" && !hasCmd("claude")) return new Map();
+      const r = spawnSync(cmd, ["agents", "--json"], { encoding: "utf8", timeout: 5000 });
+      if (r.status !== 0 || !r.stdout) return new Map();
+      text = r.stdout;
+    }
+    const arr = JSON.parse(text);
+    if (!Array.isArray(arr)) return new Map();
+    const map = new Map();
+    for (const a of arr) {
+      if (!a || a.kind !== "background" || typeof a.name !== "string") continue;
+      if (a.state === "done") continue; // finished — not in flight
+      const list = map.get(a.name) || [];
+      list.push({ id: a.id, name: a.name, state: a.state, status: a.status, cwd: a.cwd });
+      map.set(a.name, list);
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+// Stamp items[].in_flight from the dispatched-agent map, optionally dropping the
+// in-flight ones (--hide-dispatched). Every kept item gets an in_flight boolean
+// (so the flag is present on all of them — claude absent => uniformly false);
+// an in-flight item also carries a `dispatched` array of agent summaries.
+// Returns the kept items and the count of hidden ones.
+function annotateInFlight(items, agentMap, hide) {
+  const kept = [];
+  let hidden = 0;
+  for (const it of items || []) {
+    const agents = (it && it.id && agentMap.get(it.id)) || null;
+    const inFlight = !!(agents && agents.length);
+    if (inFlight && hide) {
+      hidden++;
+      continue;
+    }
+    if (it && typeof it === "object") {
+      it.in_flight = inFlight;
+      if (inFlight) it.dispatched = agents;
+    }
+    kept.push(it);
+  }
+  return { items: kept, hidden };
 }
 
-function renderQueue(q) {
+function renderQueue(q, hidden = 0) {
   const items = (q && q.items) || [];
   if (!items.length) {
     out("queue empty — nothing queueable and live");
-    return;
-  }
-  for (const it of items) {
-    out(`${(it.score ?? 0).toFixed ? it.score.toFixed(2) : it.score}  ${it.suggest || "do"}  ${it.id}`);
-    if (it.why) out(`        ${it.why}`);
+  } else {
+    for (const it of items) {
+      out(`${(it.score ?? 0).toFixed ? it.score.toFixed(2) : it.score}  ${it.suggest || "do"}  ${it.id}`);
+      if (it.why) out(`        ${it.why}`);
+    }
   }
+  // Never-silent truncation (task-spor-cli-in-flight-surface): report what
+  // --hide-dispatched removed, the way queue.js surfaces the muted count.
+  if (hidden > 0) out(`(${hidden} in-flight hidden — --hide-dispatched)`);
 }
 
 async function cmdGet(cfg, { positionals }) {
@@ -830,12 +1004,27 @@ function safeSlug() {
 }
 
 // The git toplevel of the cwd, or cwd itself — where repo-scoped files live.
+// Worktree-local on purpose: cmdScope/cmdLink/targetPath write committable
+// files (.spor.json, .spor, repo-scoped hook config) into the user's CURRENT
+// checkout, so a linked worktree keeps its own dir, not the main one.
 function repoRoot() {
   const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
   const top = (r.stdout || "").trim();
   return top || process.cwd();
 }
 
+// The DURABLE repo root for dispatch: like repoRoot(), but inside a linked git
+// worktree it resolves to the MAIN checkout (dirname --git-common-dir), not the
+// ephemeral worktree dir. dispatch persists this dir into the machine-local
+// dispatch.repos slug->path map, so stamping a worktree path would leave a dead
+// mapping the instant the worktree is removed
+// (issue-spor-dispatch-worktree-dir-stamping). This is the same inferenceRoot()
+// session-start already registers with, so the slug (safeSlug -> projectSlug)
+// and the path stay consistent. Byte-identical to repoRoot() outside a worktree.
+function dispatchRoot() {
+  return u.inferenceRoot(process.cwd()) || repoRoot();
+}
+
 // A git invocation inside a given working tree. Captures output so callers can
 // branch on status/stderr; never throws (a missing git binary surfaces as
 // r.error, handled by hasGit() before we get here).
@@ -1584,8 +1773,45 @@ async function topQueueItem(cfg, slug) {
   }
 }
 
+// Auto-claim a dispatched node so its lease is established at dispatch time
+// (task-spor-dispatch-auto-claim), reusing the same claim/renew lease the
+// post-tool heartbeat drives (dec-cc-task-claim-lease, task-cc-claim-nudge-hook).
+// REMOTE-MODE ONLY: a claim is a server-held lease; local mode has no pool or
+// contention (dec-cc-task-claim-lease "Local mode"), so the caller skips it and
+// local dispatch stays byte-identical. No session is bound on purpose — the
+// dispatching CLI session ends immediately, while the launched bg agent (a
+// DIFFERENT session) keeps the lease alive: its post-tool hook renews any
+// in_progress lease the person holds (assignee=me). Leaving the lease
+// person-scoped (session:null) is what lets that cross-session heartbeat work;
+// binding it to this short-lived session would orphan the heartbeat. Returns
+// {ok} on success/idempotent-renew, {conflict, message} when the node is already
+// held (the concurrent-dispatch case this guards), or {error} for any other
+// failure (fail-open: the caller warns and dispatches anyway).
+async function claimDispatch(cfg, nodeId) {
+  const r = await remote.post(cfg, `/v1/nodes/${encodeURIComponent(nodeId)}/claim`, {}, { timeoutMs: 6000 });
+  if (r.ok) return { ok: true, lease: r.json && r.json.lease };
+  // 409 = the node can't be claimed right now — almost always a live lease held
+  // by ANOTHER person (the concurrent-dispatch conflict this feature exists to
+  // catch), occasionally a closed/terminal node. Either way don't launch a
+  // duplicate: surface the server's message (it names holder + expiry for the
+  // lease case) and let the caller abort.
+  if (r.status === 409) {
+    const e = (r.json && r.json.error) || {};
+    return { ok: false, conflict: true, code: e.code || "conflict", message: e.message || "already claimed" };
+  }
+  // Anything else (transport down, 5xx, auth, a non-claimable node type) means
+  // we couldn't establish the lease. Fail-open like the rest of the remote path
+  // (dec-cc-fail-open-hooks / the fail-soft briefing compile): warn and dispatch
+  // without a claim rather than blocking on an outage.
+  const code = r.json && r.json.error && r.json.error.code;
+  return { ok: false, error: r.transport ? r.error : `HTTP ${r.status}${code ? ` (${code})` : ""}` };
+}
+
 // Resolve the directory to launch in. --dir wins; else a known slug is looked up
-// in the map; else the cwd's repo root. { dir:null } means "slug unknown here".
+// in the map; else the cwd's durable repo root. { dir:null } means "slug unknown
+// here". The cwd fallback uses dispatchRoot() (not repoRoot()) so a dispatch run
+// from inside a linked worktree registers the main checkout, never the ephemeral
+// worktree path (issue-spor-dispatch-worktree-dir-stamping).
 function resolveDir(cfg, { dir, slug }) {
   if (dir) {
     const abs = path.resolve(dir);
@@ -1595,7 +1821,7 @@ function resolveDir(cfg, { dir, slug }) {
     const p = (cfg.get("dispatch.repos", {}) || {})[slug];
     return p ? { dir: p, slug, source: "config" } : { dir: null, slug, source: "unknown" };
   }
-  return { dir: repoRoot(), slug: safeSlug(), source: "cwd" };
+  return { dir: dispatchRoot(), slug: safeSlug(), source: "cwd" };
 }
 
 // Quote an argv element for the --print display only (never used to spawn).
@@ -1665,6 +1891,8 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   const dryRun = !!(values.print || values["dry-run"]);
   const full = !!values.full;
   const noBrief = !!values["no-brief"];
+  const noClaim = !!values["no-claim"];
+  const force = !!values.force;
   const backfill = !!values.backfill;
   const fromQueue = !!values["from-queue"];
   const dirOpt = values.dir || null;
@@ -1781,6 +2009,17 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     prompt = r.text;
   }
 
+  // Same-machine duplicate-dispatch guard (task-spor-dispatch-same-machine-guard).
+  // `spor dispatch` names each background agent after its node id, so an active
+  // agent with this name means this person already has this node in flight on THIS
+  // machine — a duplicate the auto-claim can't catch (a same-person re-claim is an
+  // idempotent renew by design, dec-cc-task-claim-lease). dispatchedAgents() is the
+  // same NO-LLM, fail-soft cross-reference `spor next --hide-dispatched` uses; node
+  // mode only (mirrors the auto-claim's scope), in BOTH local and remote (it's a
+  // local agent read, independent of the graph backend). claude absent / a stale
+  // exit / unparseable output => empty => no guard (fail-open); --force overrides.
+  const inFlight = nodeId && !backfill ? dispatchedAgents().get(name) || [] : [];
+
   const claudeBin = claudeCmd();
   const claudeArgs = ["--bg"];
   if (name) claudeArgs.push("--name", name);
@@ -1799,12 +2038,36 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
       out(`onboard: ${steps.join("; ")}`);
     }
     out(`brief:  ${brief ? `${brief.length} bytes` : "(none — graph had nothing relevant, or --no-brief/--backfill)"}`);
+    // Same-machine guard preview (node mode, any mode): a real dispatch would
+    // refuse if an agent with this name is already in flight here. Shown only on a
+    // hit, so a clean node --print stays byte-identical to before.
+    if (inFlight.length) {
+      out(
+        `in-flight: ${name} already has ${inFlight.length} agent(s) in flight here` +
+          (force ? " — --force set, dispatching anyway" : " — real dispatch would refuse (--force overrides)")
+      );
+    }
+    // Auto-claim preview (remote node dispatch only — local mode has no lease, so
+    // nothing is announced there and local --print stays byte-identical).
+    if (nodeId && !backfill && cfg.mode() === "remote") {
+      out(`claim:  ${noClaim ? "(--no-claim — lease not established)" : `would establish a lease on ${nodeId} at launch`}`);
+    }
     if (template != null) out(`template: ${path.resolve(templateOpt)}`);
     out(`run:    ${claudeBin} ${claudeArgs.slice(0, -1).map(shellQuote).join(" ")} <prompt>`);
     out(`\n--- prompt ---\n${prompt}`);
     return 0;
   }
 
+  // Refuse a same-machine duplicate BEFORE any side effect or claim
+  // (task-spor-dispatch-same-machine-guard): no repo registration, no lease, no
+  // launch for a node already in flight here. --force overrides.
+  if (inFlight.length && !force) {
+    err(`${name} already has a background agent in flight on this machine — not dispatching a duplicate.`);
+    err(`  in flight: ${inFlight.map((a) => `${a.id || "?"}${a.state ? ` (${a.state})` : ""}`).join(", ")}`);
+    err(`  re-run with --force to dispatch anyway, or 'spor next --json' to review what's already running.`);
+    return 1;
+  }
+
   // Side effects (real run only — --print writes nothing). --backfill is the
   // onboarding door, so it sets the repo up (init + enable) first; every
   // dispatch self-registers the dir it resolved.
@@ -1819,6 +2082,23 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     err("claude CLI not on PATH — install Claude Code, then re-run (or 'spor dispatch … --print' to see the prompt).");
     return 1;
   }
+  // Establish the claim/lease BEFORE launching (task-spor-dispatch-auto-claim):
+  // a node already claimed by someone else is caught here, so we never launch a
+  // duplicate agent onto contested work, and the lease is live the moment the
+  // agent starts (its post-tool writes then renew it — and seeing its own held
+  // claim, it skips the redundant claim-nudge). Remote node-mode only; --no-claim
+  // opts out (dispatch with no lease, the prior behavior).
+  if (nodeId && !backfill && !noClaim && cfg.mode() === "remote") {
+    const c = await claimDispatch(cfg, nodeId);
+    if (c.conflict) {
+      err(`${nodeId} is already claimed — ${c.message}`);
+      err(`  not dispatching a duplicate. Re-run with --no-claim to dispatch anyway (no lease),`);
+      err(`  or pick another task with 'spor next'.`);
+      return 1;
+    }
+    if (c.ok) out(`claimed ${nodeId} (lease established; the agent's writes will renew it)`);
+    else err(`warning: could not establish a lease on ${nodeId}: ${c.error} — dispatching without a claim`);
+  }
   const r = spawnSync(claudeBin, claudeArgs, { cwd: res.dir, stdio: "inherit" });
   if (r.error) {
     err(`could not launch ${claudeBin}: ${r.error.message}`);
@@ -2021,14 +2301,18 @@ const COMMANDS = {
     run: (cfg, p) => cmdAdd(cfg, p),
   },
   next: {
-    group: "Graph", parse: "raw", args: "[--project S]", aliases: ["queue"],
+    group: "Graph", parse: "raw", args: "[--project S | --all-projects] [--type T] [--exclude-type T]", aliases: ["queue"],
     summary: "the decision queue (local: lib/queue; remote: /v1/queue)",
-    help: "Show the ranked decision queue. Remote mode reads /v1/queue; local mode is a\nbyte-identical passthrough to lib/queue.js, so it also accepts that script's\nflags (--days, --no-front, --limit, --name-only, --nodes).\n\n--project accepts a repo slug (-> its home-project grouping union), a repo-<slug>\nnode id (-> that single repo), or a grouping id (-> the grouping union); an\nunknown token warns and yields an empty queue. Pin a default scope for both modes\nwith the queue.project config key (SPOR_QUEUE_PROJECT or .spor.json\n{\"queue\":{\"project\":\"...\"}}); an explicit --project still wins.",
+    help: "Show the ranked decision queue. Remote mode reads /v1/queue; local mode is a\nbyte-identical passthrough to lib/queue.js, so it also accepts that script's\nflags (--days, --no-front, --limit, --name-only, --nodes).\n\nSCOPE. --project accepts a repo slug (-> its home-project grouping union), a\nrepo-<slug> node id (-> that single repo), or a grouping id (-> the grouping\nunion); an unknown token warns and yields an empty queue. Pin a default scope\nfor both modes with the queue.project config key (SPOR_QUEUE_PROJECT or\n.spor.json {\"queue\":{\"project\":\"...\"}}); an explicit --project still wins.\n--all-projects (alias --all) widens to the whole-graph cross-project firehose,\ndropping the cwd/pinned default scope (an explicit --project still wins over it).\n\nNODE TYPES. --type/--exclude-type whitelist/blacklist node types from the\nranking; both are repeatable and comma-splittable (--type task,issue). Given\nboth, the include set is narrowed and then the excludes are removed (exclude\nwins on overlap). They compose with --project/--all-projects.\n\nIN-FLIGHT. --json stamps each item with an `in_flight` flag (and a `dispatched`\nagent summary when true) by cross-referencing live background agents from\n`claude agents --json` — `spor dispatch` names each agent after its node id, so\nan active agent on a queued item is detectable without model guidance.\n--hide-dispatched drops the items that already have an agent in flight. Both are\nclient-side (the server can't see local agents) and fail soft when the claude\nbinary is absent (every item then reads in_flight:false).",
     options: {
       project: { type: "string", value: "S", desc: "scope to a project slug (default: queue.project config, else inferred)" },
-      json: { type: "boolean", desc: "machine-readable JSON output" },
+      "all-projects": { type: "boolean", desc: "cross-project firehose — drop the default project scope (alias --all)" },
+      type: { type: "string", value: "T", desc: "include only these node types (repeatable, comma-ok)" },
+      "exclude-type": { type: "string", value: "T", desc: "exclude these node types from the ranking (repeatable, comma-ok)" },
+      json: { type: "boolean", desc: "machine-readable JSON output (adds the in_flight flag per item)" },
+      "hide-dispatched": { type: "boolean", desc: "drop items that already have a background agent in flight" },
     },
-    examples: ["spor next", "spor next --project spor --json"],
+    examples: ["spor next", "spor next --json", "spor next --json --hide-dispatched", "spor next --all-projects --type task,issue", "spor next --exclude-type capture-pending"],
     run: (cfg, args) => cmdNext(cfg, args),
   },
   get: {
@@ -2153,6 +2437,12 @@ const COMMANDS = {
       "right repo. Give free-text, a <node-id>, --node <id>, --from-queue (the top\n" +
       "ranked item), or --backfill (onboard/repair a repo). The target dir is the\n" +
       "slug->path map ('spor repos'), overridable with --dir.\n\n" +
+      "In remote mode a node dispatch auto-claims the task — it establishes the\n" +
+      "heartbeat lease at dispatch time, so concurrent dispatch of the same node is\n" +
+      "refused (the holder is named). --no-claim opts out (dispatch with no lease).\n\n" +
+      "A node dispatch is also refused if an agent for that node is already in flight\n" +
+      "on THIS machine (each agent is named after its node id) — catches the\n" +
+      "same-person duplicate the lease's idempotent renew can't. --force overrides.\n\n" +
       "--template supplies your own prompt with {{brief}}/{{task}}/{{node}}/{{title}}/\n" +
       "{{slug}}/{{dir}}/{{default}} placeholders.",
     options: {
@@ -2166,6 +2456,8 @@ const COMMANDS = {
       template: { type: "string", value: "F", desc: "prompt template file (placeholders above)" },
       full: { type: "boolean", desc: "full briefing instead of the digest" },
       "no-brief": { type: "boolean", desc: "raw task prompt, no briefing block" },
+      "no-claim": { type: "boolean", desc: "don't auto-claim the lease (remote node dispatch)" },
+      force: { type: "boolean", desc: "dispatch even if an agent for this node is already in flight here" },
       "from-queue": { type: "boolean", desc: "dispatch the top-ranked queue item" },
       backfill: { type: "boolean", desc: "onboard/repair this repo (runs /spor:backfill)" },
       print: { type: "boolean", desc: "dry run — print the prompt, launch nothing" },

package/lib/kernel/queue.js

@@ -421,8 +421,13 @@ function attachedSignals(reg, node, baseSignals, neighbors, sandboxFor) {
   }
 }
 
-// rankQueue(graph, { project?, assignee?, activity?, front?, leases?, now?, limit?, viewer?, sandboxFor? })
+// rankQueue(graph, { project?, assignee?, includeTypes?, excludeTypes?, activity?, front?, leases?, now?, limit?, viewer?, sandboxFor? })
 //   -> { items, count, muted?, dormant?, archived?, leased?, reserved? }
+// `includeTypes`/`excludeTypes` (task-cc-queue-filtering-enhancements) are
+// node-type allow/deny lists applied as a HARD scope filter before scoring,
+// like `project`/`assignee`: includeTypes keeps only those types, excludeTypes
+// drops them (exclude wins on overlap), and a filtered-out node is out of scope,
+// not counted. Empty/absent => no filter, byte-identical to before.
 // `assignee` is a person node id (task-cc-queue-assignee-filtering): when set,
 // the queue is scoped to the work that person carries — nodes with an outbound
 // `assigned` edge to them, plus the nodes they `steward`. It answers a manager's
@@ -503,6 +508,22 @@ function rankQueue(graph, opts = {}) {
   const assigneeSet = assigneeScope(graph, assignee);
   const inAssignee = (n) => !assigneeSet || assigneeSet.has(n.id);
 
+  // Node-type include/exclude (task-cc-queue-filtering-enhancements): whitelist
+  // or blacklist node types FROM THE RANKING. `includeTypes` keeps only those
+  // types; `excludeTypes` drops them; given both, the include set is narrowed
+  // and then the excludes are removed from it (exclude wins on overlap). Like
+  // `project`/`assignee` this is a HARD scope filter applied before scoring, so
+  // a filtered-out node is simply out of scope — NOT counted like
+  // mute/dormant/archived (the count describes the filtered queue, not what the
+  // firehose hid). Empty/absent arrays => no filter, so the queue is
+  // byte-identical to before these parameters existed
+  // (norm-cc-byte-identical-refactor). The type compared is the type the item
+  // surfaces AS: `schema` for a proposed-schema queue item, `node.type`
+  // otherwise — so excluding `schema` hides schema-approval items too.
+  const typeIncl = Array.isArray(opts.includeTypes) && opts.includeTypes.length ? new Set(opts.includeTypes) : null;
+  const typeExcl = Array.isArray(opts.excludeTypes) && opts.excludeTypes.length ? new Set(opts.excludeTypes) : null;
+  const inTypes = (t) => (!typeIncl || typeIncl.has(t)) && (!typeExcl || !typeExcl.has(t));
+
   // Task claim-lease (dec-cc-task-claim-lease / dec-cc-task-resumption-
   // reservation): an in-force `leases` entry held by ANOTHER viewer is
   // owner-exclusive — hidden from this viewer's actionable list, COUNTED. A
@@ -539,6 +560,7 @@ function rankQueue(graph, opts = {}) {
     if (node.type === "schema" && (node.status || "") === "proposed") {
       if (!inProject(node)) continue;
       if (!inAssignee(node)) continue;
+      if (!inTypes("schema")) continue; // hard type scope, uncounted (like project)
       if (isArchived(node)) { archivedCount++; continue; }
       if (isMuted(node)) { muted++; continue; }
       const age = ageDays(node, now);
@@ -559,6 +581,7 @@ function rankQueue(graph, opts = {}) {
     if (!reg.isQueueable(node.type)) continue;
     if (!inProject(node)) continue;
     if (!inAssignee(node)) continue;
+    if (!inTypes(node.type)) continue; // hard type scope, uncounted (like project)
     if (isArchived(node)) { archivedCount++; continue; } // counted, not silent
     if (!isLive(node, graph.supersededBy)) continue;
     if (resolvedBy[node.id]) continue; // retired by a live resolves/answers edge

package/lib/query.js

@@ -145,14 +145,22 @@ if (require.main === module) {
     to: has("to") ? opt("to", null) : null,
   });
 
+  // Project a loaded node for JSON output: drop the parser's load-time `file`
+  // artifact, and drop pin/exclude when empty — the regex parser initializes
+  // both to [] on every node, so they are noise unless a briefing/correction
+  // actually populated them (a non-empty list is kept). Deletes from a shallow
+  // copy so the original key order is preserved.
+  const cleanNode = (n) => {
+    const out = { ...n };
+    delete out.file;
+    if (Array.isArray(out.pin) && !out.pin.length) delete out.pin;
+    if (Array.isArray(out.exclude) && !out.exclude.length) delete out.exclude;
+    return out;
+  };
+
   if (has("json")) {
     if (r.edges) process.stdout.write(JSON.stringify(r.edges, null, 2) + "\n");
-    else {
-      // Strip the parser's internal `file` field from JSON node output (it's a
-      // load-time artifact, not graph data).
-      const clean = r.nodes.map(({ file, ...rest }) => rest);
-      process.stdout.write(JSON.stringify(clean, null, 2) + "\n");
-    }
+    else process.stdout.write(JSON.stringify(r.nodes.map(cleanNode), null, 2) + "\n");
     process.exit(0);
   }
 
@@ -183,8 +191,7 @@ if (require.main === module) {
       if (raw != null) {
         process.stdout.write(raw.endsWith("\n") ? raw : raw + "\n");
       } else {
-        const { file: _f, ...rest } = n; // drop the load-time artifact
-        process.stdout.write(JSON.stringify(rest, null, 2) + "\n");
+        process.stdout.write(JSON.stringify(cleanNode(n), null, 2) + "\n"); // raw file unreadable: reconstructed view
       }
       console.log("---");
     }

package/lib/queue.js

@@ -6,7 +6,9 @@
 //
 // Also a CLI (local mode / debugging):
 //   node lib/queue.js [--nodes <dir>] [--project <slug>] [--assignee <person-id>]
-//                     [--limit <n>] [--days <n>] [--no-front] [--json]
+//                     [--type <t>] [--exclude-type <t>] [--limit <n>]
+//                     [--days <n>] [--no-front] [--json]
+// --type / --exclude-type are repeatable and comma-splittable (--type task,issue).
 
 const kernel = require("./kernel/queue.js");
 
@@ -112,6 +114,18 @@ if (require.main === module) {
     const i = argv.indexOf(`--${n}`);
     return i >= 0 && argv[i + 1] != null ? argv[i + 1] : d;
   };
+  // Repeatable + comma-splittable flag (task-cc-queue-filtering-enhancements):
+  // `--type task --type issue` and `--type task,issue` both yield ["task","issue"].
+  // null when the flag is absent so the kernel filter stays inert (byte-identical).
+  const multi = (n) => {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+      if (argv[i] === `--${n}` && argv[i + 1] != null) {
+        out.push(...argv[i + 1].split(",").map((s) => s.trim()).filter(Boolean));
+      }
+    }
+    return out.length ? out : null;
+  };
   const home = require(path.join(__dirname, "shell", "home.js"));
   // Client config cascade (dec-spor-client-config-cascade); nodesDir() honors
   // config.nodes / SPOR_NODES then the graph-home default — byte-identical when
@@ -147,6 +161,8 @@ if (require.main === module) {
   const r = rankQueue(g, {
     project,
     assignee: opt("assignee", null),
+    includeTypes: multi("type"),
+    excludeTypes: multi("exclude-type"),
     limit: parseInt(opt("limit", String(kernel.DEFAULT_LIMIT)), 10),
     front,
     frontDays: days,

package/lib/seed/schema-edge-changes-requested-by.md

@@ -0,0 +1,35 @@
+---
+id: schema-edge-changes-requested-by
+type: schema
+kind: edge-schema
+schema_version: 2026.06.16.1
+title: Seed schema for changes-requested-by edges
+summary: Edge schema for the changes-requested-by type — this person reviewed the node and requested changes; the blocking outcome of the review-as-graph-object lifecycle. Does NOT count as an approval; the policy layer can surface it as an outstanding change request. Seed-pack default; a graph-resident schema node overrides it.
+date: 2026-06-16
+---
+
+Seed schema for the `changes-requested-by` edge type (work node → person),
+shipped with the plugin as a registry default (QUEUE.md §2). It is the
+**changes-requested** outcome of the native review lifecycle
+(review-as-graph-object, dec-spor-definition-of-done-org-policy): a
+`review-requested` edge to a reviewer flips in place to `changes-requested-by`
+when that reviewer asks for changes; addressing them and asking again flips it
+back to `review-requested`.
+
+It is explicitly **not** an approval: it never enters `view.approvals` and so
+never counts toward the definition-of-done quorum. The write path additionally
+hands these edges to the policy gate as `view.changes_requested` (reviewer +
+`roles`, author excluded), so a policy may require that no change request from
+a qualified role is outstanding before a work node may go `done` — the
+blocking complement to the quorum of `reviewed-by` approvals.
+
+Weight is mid (0.5, the `relates-to`/`assigned` tier): a recorded
+changes-requested verdict is a real outcome, not a structural dependency.
+
+```json
+{
+  "edge_type": "changes-requested-by",
+  "description": "this person reviewed the node and requested changes (does not count as an approval)",
+  "weight": 0.5
+}
+```

package/lib/seed/schema-edge-review-requested.md

@@ -0,0 +1,39 @@
+---
+id: schema-edge-review-requested
+type: schema
+kind: edge-schema
+schema_version: 2026.06.16.1
+title: Seed schema for review-requested edges
+summary: Edge schema for the review-requested type — a review of this node is requested OF a person; the open state of the review-as-graph-object lifecycle, surfaced into the reviewer's queue. Low traversal weight (routing wiring, not knowledge lineage). Seed-pack default; a graph-resident schema node overrides it.
+date: 2026-06-16
+---
+
+Seed schema for the `review-requested` edge type (work node → person),
+shipped with the plugin as a registry default (QUEUE.md §2). It is the
+*open* state of the native review lifecycle (review-as-graph-object,
+dec-spor-definition-of-done-org-policy): a resolving artifact (a change/PR)
+or any work node points a `review-requested` edge at each `person` a review
+is wanted from. The server surfaces those nodes into each named reviewer's
+personal queue (`my_queue` `reviews`), the same per-person filter questions
+and findings route through.
+
+An outcome **flips the edge in place**: an approval rewrites it to
+`reviewed-by`, a request for changes to `changes-requested-by`; a re-review
+flips it back to `review-requested`. The edge type *is* the state, so a node
+carries a `review-requested` edge only while that reviewer's verdict is
+still pending. Reviewer *selection* (who is asked) is a distinct point from
+gate-time *enforcement* (is the bar met, counted from `reviewed-by`): for the
+GitHub-reflected path selection comes from CODEOWNERS via the adapter, not a
+Spor router.
+
+Weight is low (0.3, like `routed-to`): a pending review request is routing
+wiring, not knowledge lineage, so it should not pull the requested node into
+unrelated briefings.
+
+```json
+{
+  "edge_type": "review-requested",
+  "description": "a review of this node is requested of this person (pending)",
+  "weight": 0.3
+}
+```

package/lib/seed/schema-edge-reviewed-by.md

@@ -0,0 +1,35 @@
+---
+id: schema-edge-reviewed-by
+type: schema
+kind: edge-schema
+schema_version: 2026.06.16.1
+title: Seed schema for reviewed-by edges
+summary: Edge schema for the reviewed-by type — this person reviewed and approved the node; the approving outcome of the review-as-graph-object lifecycle that the org-defined policy layer's quorum gate counts. Seed-pack default; a graph-resident schema node overrides it.
+date: 2026-06-16
+---
+
+Seed schema for the `reviewed-by` edge type (work node → person), shipped
+with the plugin as a registry default (QUEUE.md §2). It is the **approving**
+outcome of the native review lifecycle (review-as-graph-object,
+dec-spor-definition-of-done-org-policy): a `review-requested` edge to a
+reviewer flips in place to `reviewed-by` when that reviewer approves.
+
+This is the edge the org-defined policy layer's **definition-of-done quorum
+gate** counts (GRAPH.md "The org-defined policy layer"). On the write path
+the server joins each `reviewed-by` (and the synonym `approved-by`) edge to
+the reviewer's `roles` register and hands them to the gate as
+`view.approvals`, with the node's own author excluded — so a policy may
+require a quorum of approvals from a named role before a work node reaches a
+resolving/`done` state, and self-approval can never launder past the native
+floor.
+
+Weight is mid (0.5, the `relates-to`/`assigned` tier): an approval is a real
+outcome worth pulling through a briefing, but not a structural dependency.
+
+```json
+{
+  "edge_type": "reviewed-by",
+  "description": "this person reviewed and approved the node (counts toward a policy quorum)",
+  "weight": 0.5
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
   "license": "Apache-2.0",
   "author": "Anthony Allen",

package/skills/next/SKILL.md

@@ -45,6 +45,26 @@ curl -sS --max-time 6 -H "Authorization: Bearer $SPOR_TOKEN" \
 
 In Cowork, call the `my_queue` MCP tool with the same fields.
 
+**Scope and filter flags** (task-cc-queue-filtering-enhancements). The queue
+defaults to the session's project; three optional, composable levers widen or
+narrow it. Reach for them when the user asks for a wider/narrower view ("what's
+next across everything", "show me beta's queue", "just the open issues, ignore
+pending captures"):
+
+- **Cross-project firehose** — drop `?project=` entirely (`/v1/queue?limit=10`)
+  to rank every repo's queue at once. CLI: `spor next --all-projects`.
+- **A different project** — `?project=<slug>` (repo slug → grouping union;
+  `repo-<slug>` id → one repo; `proj-<slug>` id → the grouping). CLI:
+  `spor next --project <slug>`.
+- **Node-type allow/deny** — `?type=task,issue` keeps only those types;
+  `?exclude_type=capture-pending` drops them (comma-separated, repeatable,
+  exclude wins on overlap). They apply *before* ranking, so the aggregate counts
+  describe the filtered queue. CLI: `spor next --type task,issue`,
+  `spor next --exclude-type capture-pending`.
+
+The `my_queue` MCP tool takes the same as fields: `project`, `types`,
+`exclude_types` (arrays), plus `limit`/`offset`.
+
 ## Local mode (personal graph) — `SPOR_SERVER` unset
 
 `${CLAUDE_PLUGIN_ROOT}` is empty in the Bash tool, so first resolve the
@@ -56,6 +76,10 @@ SPOR_ROOT="$(cat "${SPOR_HOME:-$HOME/.spor}/cache/plugin-root" 2>/dev/null \
   || cat "$HOME/.substrate/cache/plugin-root" 2>/dev/null)"
 SPOR_ROOT="${SPOR_ROOT:-$CLAUDE_PLUGIN_ROOT}"
 node "$SPOR_ROOT/lib/queue.js" --json      # or --project <slug>, --limit <n>
+# Same scope/filter flags as remote: --type task,issue / --exclude-type
+# capture-pending (whitelist/blacklist node types), and omit --project for the
+# cross-project firehose. (`spor next --all-projects` is the CLI shorthand for
+# dropping the default scope.)
 ```
 
 Use `--json` and compose the human view from it — don't show the bare CLI
@@ -65,6 +89,43 @@ to surface (see Presenting).
 (No server means no activity feed, so heat is 0 locally; the other signals
 are identical.)
 
+## In-flight awareness — don't re-pick work an agent is already on (Claude Code only)
+
+`spor dispatch` launches Claude Code background agents named after the node id
+they work (art-res-task-spor-cli-dispatch-background-agents). Before you
+recommend an item, cross-reference live agent state so you don't surface work
+that's already in flight — otherwise whoever triages the queue picks up or
+re-dispatches a task an agent is already doing. This is **presentation-only and
+Claude-Code-only**: the `my_queue` / `GET /v1/queue` server surface cannot see
+local background agents, so the cross-reference happens here, at present time.
+Best-effort — if the `claude` binary is absent or errors (e.g. in Cowork or a
+plain shell), it is skipped silently and the queue presents as usual.
+
+**The `spor next` CLI does this cross-reference for you**
+(task-spor-cli-in-flight-surface). `spor next --json` (or
+`node "$SPOR_ROOT/bin/spor.js" next --json`, which carries the flag where the
+bare `lib/queue.js --json` does not) stamps each item with an `in_flight`
+boolean — and a `dispatched` summary (`{id, name, state, status, cwd}`) on the
+in-flight ones — by matching live background agents to node ids. Add
+`--hide-dispatched` to drop the in-flight items entirely (it reports a
+`hidden_dispatched` count, never silently). Prefer reading that flag over
+shelling out yourself.
+
+Under the hood (and what to do when you only have the raw `lib/queue.js --json`
+or `GET /v1/queue` output, which don't carry the flag):
+
+```bash
+claude agents --json 2>/dev/null   # array of {name, kind, state, cwd, ...}
+```
+
+A queue item is **in flight** when a `kind: "background"` agent has `name`
+equal to the item's id and `state` is not `"done"` (e.g. `working`). For those
+items: badge them "🤖 agent dispatched — in progress" and keep them OUT of the
+top "pick this next" recommendation (the work is already moving; surfacing it
+invites duplication). Mention them so the human can still choose to look —
+counted, never silently dropped, the same discipline the queue uses for mutes
+and leases. Items with no matching live agent are presented normally.
+
 ## Presenting and acting
 
 Present in plain language — you are talking to a human who may be new to Spor.