@sporhq/spor 0.6.0 → 0.7.1

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

package/API.md

@@ -16,8 +16,13 @@ Every mutation is validated, attributed, serialized, and committed to the
 graph's git repo. What a client sees:
 
 - **Attribution**: the server stamps `author: <identity>` and
-  `authored_via: mcp|rest|capture` from the authenticated token — any
-  `author:` supplied in the payload is discarded.
+  `authored_via: mcp|rest|capture|dispatch` from the authenticated token — any
+  `author:` supplied in the payload is discarded. A write under an
+  **agent-scoped token** (§4) additionally stamps `authored_by_agent: <agent-id>`
+  and `session: <id>` and uses `authored_via: dispatch`, while `author:` stays
+  the agent's **owning person** — so the node reads "agent on behalf of person".
+  These ride-along fields are token-derived too; any supplied in the payload are
+  discarded.
 - **Create**: `if_exists: "skip"` → id collision is reported as `skipped`
   (the distiller default); `if_exists: "error"` → id collision is a
   `conflict` error.
@@ -291,7 +296,7 @@ endpoint is the REST twin of a core call:
 | `GET /v1/status` | session-start, monitoring | `{node_count, projects: {...}, head, uptime, metrics}`; doubles as the health check. `?titles=1` adds `titles: [{id, type, project, title}]` — the one-round-trip graph index the distiller dedups against |
 | `GET /v1/me` | `spor whoami`/`status`, onboarding | identity echo for the bearer token → `{person, name, email, bound, is_admin}`. `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 |
 | `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, min_sim?}` | prompt-context | digest-mode compile → `{found, text}`; `found: false` is a successful empty result |
+| `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; 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 |
@@ -314,6 +319,9 @@ endpoint is the REST twin of a core call:
 | `GET /v1/admin/tokens` | offboarding / audit | list PATs → `{tokens: [{hash_prefix, person, name, email, created, expires, expired}], count}` — never plaintext, never full hashes. Admin-only (§4) |
 | `POST /v1/admin/tokens` `{person, expires?}` | onboarding | mint a PAT bound to an existing person node (`expires` is `<N>d` or an ISO date) → 201 `{token, hash_prefix, person, name, email, expires}`; the plaintext `token` is returned **once**. Admin-only |
 | `DELETE /v1/admin/tokens/{hash-prefix}` | offboarding / rotation | revoke the single PAT matching the hash prefix (≥8 hex chars; an ambiguous prefix is a 409) → `{revoked, hash_prefix}`. Admin-only |
+| `GET /v1/agents` | `spor agent list` | list the agents the caller **owns** → `{agents: [{id, label, owner, spiffe, pubkey, status}], count}`; `?all=1` lists every agent (admin-only) |
+| `POST /v1/admin/agents` `{label, owner?, id?, pubkey?}` | `spor agent create`, onboarding | create a person-owned `agent` node + its `owned-by` edge (`owner` defaults to the caller's person; `id` derives from `label`) → 201 `{id, owner, spiffe, pubkey, status, revision}`. 409 dup id / 422 invalid / 403 non-admin. Admin-only, same `stewards→root` gate as `/v1/admin/tokens` |
+| `POST /v1/agents/{id}/token` `{session, audience?, expires?}` | `spor dispatch` | **self-serve** (NOT admin): mint a short-TTL, per-session token scoped to agent `{id}` → 201 `{token, expires_at, agent, session}`. Authorized iff the caller's person **owns** the agent (its `owned-by` edge) — else `403`; `404` unknown agent; `422` bad/missing `session`. The token carries `{agent, session}` (the person is derived from the `owned-by` edge at verify time); a write under it is stamped agent-on-behalf-of-person (§1). A caller `expires` may only shorten the default TTL, never extend it |
 
 Path parameters (node ids, project slugs) must match
 `^[a-z0-9][a-z0-9-]*$`. Request bodies are capped at 1MB
@@ -357,6 +365,21 @@ anything with a token.
   --admin --person <id>` (it writes that `stewards` edge, creating the person
   node from `--name`/`--email` if needed). Hand-editing the token file stays
   as the break-glass path.
+- **Agent-scoped session tokens.** A person mints a short-lived, per-session
+  token for an `agent` they **own** through the self-serve
+  `POST /v1/agents/{id}/token` (§3) — authorized by ownership (the agent's
+  `owned-by → person` edge), never admin, so a dispatcher needs no special
+  privilege to run their own agents. The token's record carries `{agent,
+  session}` and no person; the owning person (and its `{name, email}`) resolves
+  from the `owned-by` edge at verify time, so a deleted agent or owner makes the
+  token fail closed rather than impersonate. Writes under it are attributed
+  agent-on-behalf-of-person (§1) — the `person → agent` chain is the audit
+  trail. `spor dispatch` mints one per run and injects it into the launched
+  background agent (so the agent's own graph writes carry its identity), picking
+  the machine's default agent from the `dispatch.agent` client config (set with
+  `spor agent use <agent-id>`, or `SPOR_DISPATCH_AGENT`), which `spor dispatch
+  --as <agent-id>` overrides for a single run. (Not to be confused with `spor
+  dispatch --agent`, the unrelated `claude --agent` harness passthrough.)
 - **OAuth 2.1 for MCP connectors** (Cowork/claude.ai, which cannot carry a
   static bearer token): protected-resource metadata discovery (RFC 9728,
   advertised on the `/mcp` 401 via `WWW-Authenticate`), authorization-server

package/GRAPH.md

@@ -94,6 +94,7 @@ Rules:
 | correction | `corr-`   | standing fix to a briefing: pin/exclude/guidance (never traversed) |
 | question   | `question-` | a routed ask the graph could not answer (queueable; status `open`/`answered`, gated) |
 | person     | `person-` | a member of the org — the identity anchor for `$viewer` binding and Tier-2 question routing (team mode; see "People, routing, and onboarding") |
+| agent      | `agent-`  | a person-owned automation principal — a dispatched session's durable identity, owned by a person via an `owned-by` edge; its writes attribute "agent on behalf of person" (see "Agents") |
 | capture-pending | `cap-` | raw captured text that fit no schema; filed by the server for later triage (QUEUE.md §2.3); born status-less, closed only as `merged` (content now in proper node(s)) or `rejected` (no durable fact) — a `transitions()` gate rejects other statuses at write time |
 | finding    | `find-`   | a gardener observation about another node, filed as a queue item (QUEUE.md §6) |
 | repo       | `repo-`   | durable git-repo identity: slug aliases + repo fingerprints; heals renames at read time (below) |
@@ -555,6 +556,56 @@ client surfaces no warning when the authenticated identity maps to no person
 node. Surfacing that unbound state in queue and briefing responses is tracked
 server-side (issue-cc-onboarding-email-mismatch-silent-degradation).
 
+### Agents (person-owned principals)
+
+An `agent` node (prefix `agent-`) is a person's automation principal — the
+durable identity of a dispatched `claude --bg` session
+(dec-spor-agent-identity-nodes). It generalizes the workflow-run principal: a
+dispatched session is just another principal kind owned by a person, so work it
+creates reads "agent **on behalf of** person" rather than person-direct.
+
+```markdown
+---
+id: agent-anthony-laptop
+type: agent
+title: Anthony's laptop agent
+summary: Dispatched-session principal on Anthony's laptop; owned by person-anthony.
+spiffe: spiffe://spor.sporhq/person/person-anthony/agent/anthony-laptop
+pubkey: ""
+status: active
+date: 2026-06-16
+edges:
+  - {type: owned-by, to: person-anthony}
+---
+```
+
+- **Grain: persistent, one per machine/install.** An agent node is created once
+  (`spor agent create <label>`, or the admin endpoint) and REUSED across every
+  dispatch — NOT one node per session. Each dispatch's Claude Code `session_id`
+  is the ephemeral which-run, recorded as an additive `session:` stamp on the
+  nodes it writes, not as its own node (promote to a `run-<id>` node only if run
+  metadata later needs a home).
+- **`owned-by` is the ownership edge** (agent → person, inverse `owns`). Like
+  `grouped-under` it is a low-weight (0.3) structural identity binding, not a
+  work dependency — the owner is not pulled into the agent's work neighborhoods.
+  Ownership lives on this edge, NOT in frontmatter.
+- **`spiffe:` / `pubkey:` are forward-compat shape, unenforced.** The `spiffe:`
+  URI encodes the binding in its path
+  (`spiffe://spor.<org>/person/<id>/agent/<label>`, extended to
+  `…/session/<uuid>` per dispatch); `pubkey:` records the agent's key
+  fingerprint (may be empty). Both adopt the SHAPE (dec-cc-spiffe-forward-compat)
+  — no signature verification, JWKS, or signed commits ship in this cut.
+- **Attribution stamps (additive).** Work an agent creates keeps `author:` = the
+  owning person (so `$viewer`, routing, history, and the queue are unchanged) and
+  ADDS `authored_by_agent: agent-<id>`, `authored_via: dispatch`, and `session:
+  <id>`. These are token-derived, never from the payload
+  (dec-cc-attribution-from-token); old nodes lack them and read as person-direct.
+  This is purely additive — the stamp itself needs no `schema_version` bump.
+- `capturable: false` (agent node and `owned-by` edge): both are created
+  deliberately, never drafted from a capture or distilled from a transcript —
+  mirroring `person`, `repo`, and `workflow-run`. (So the distiller's emit
+  vocabulary deliberately omits `agent`/`owned-by`.)
+
 ## Edge types and traversal weights
 
 | edge             | weight | meaning                                          |
@@ -574,6 +625,7 @@ server-side (issue-cc-onboarding-email-mismatch-silent-degradation).
 | `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 |
+| `owned-by`       | 0.3    | this agent is owned by that person (inverse `owns`); structural identity binding, 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)      |

package/bin/spor.js

@@ -21,6 +21,7 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const https = require("https");
+const crypto = require("crypto");
 const { spawnSync } = require("child_process");
 const { parseArgs } = require("util");
 
@@ -945,6 +946,254 @@ async function cmdInvite(cfg, { values }) {
   return 0;
 }
 
+// --- spor agent: a person-owned automation principal ----------------------
+// dec-spor-agent-identity-nodes: an agent is a first-class `type: agent` node
+// owned by a person via an `owned-by` edge, so a dispatched session's writes
+// read "agent on behalf of person" instead of person-direct. One persistent
+// node per machine/install, created once here and reused across dispatches.
+//
+// REMOTE: POST /v1/admin/agents creates the node + owned-by edge through the
+//   server's validated Store door, admin-gated like /v1/admin/people (the
+//   server is the CA, it mints the spiffe). FAIL-SOFT on 404 — the endpoint is
+//   landing in the spor-server stream; an old server gets a clear message, not
+//   a crash.
+// LOCAL: write the agent node + owned-by edge to the graph home via the same
+//   lib/graph validate-before-write path cmdAdd uses; the spiffe is built
+//   client-side from a config `org` (forward-compat shape, unenforced).
+async function cmdAgent(cfg, args) {
+  const sub = args[0];
+  if (sub === "create") {
+    const label = args[1];
+    if (!label || label.startsWith("-")) {
+      err("usage: spor agent create <label> [--owner person-x] [--pubkey <fp>]");
+      return 1;
+    }
+    const owner = optVal(args, "owner");
+    const pubkey = optVal(args, "pubkey") || "";
+    return cfg.mode() === "remote"
+      ? cmdAgentCreateRemote(cfg, { label, owner, pubkey })
+      : cmdAgentCreateLocal(cfg, { label, owner, pubkey });
+  }
+  if (!sub || sub === "list") {
+    return cfg.mode() === "remote" ? cmdAgentListRemote(cfg) : cmdAgentListLocal(cfg);
+  }
+  if (sub === "use") {
+    return cmdAgentUse(cfg, { id: args[1] });
+  }
+  err("usage: spor agent create <label> [--owner person-x] [--pubkey <fp>] | spor agent list | spor agent use <agent-id>");
+  return 1;
+}
+
+// `spor agent use <agent-id>` — make this agent the machine's default dispatch
+// identity by writing `dispatch.agent` to the USER config.json (the same
+// machine-local, never-committed file as the repo map; per-machine, like
+// dispatch.repos). This is the real setter the create/list hints point to;
+// before it, dispatch.agent was settable only via env or by hand-editing the
+// config. `spor agent use --clear` (or an empty id) drops back to person-scoped
+// dispatch. Not a graph write — purely local config, so it works in both modes.
+function cmdAgentUse(cfg, { id }) {
+  const clear = id === "--clear" || id === "none" || id === "";
+  if (!id) {
+    err("usage: spor agent use <agent-id>   (or: spor agent use --clear)");
+    return 1;
+  }
+  if (!clear && !/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+    err(`invalid agent id '${id}' — must match ^[a-z0-9][a-z0-9-]*$ (e.g. agent-your-machine)`);
+    return 1;
+  }
+  const home = cfg.userConfigHome();
+  const wrote = u.setDispatchAgent(home, clear ? null : id);
+  if (clear) {
+    out(wrote ? "cleared dispatch.agent — dispatches run person-scoped again" : "dispatch.agent was already unset");
+    return 0;
+  }
+  if (wrote) {
+    out(`dispatch.agent = ${id}  (this machine now dispatches as ${id}; ${path.join(home, "config.json")})`);
+  } else {
+    out(`dispatch.agent already = ${id} (no change)`);
+  }
+  out("  attribution is remote-only; override one dispatch with: spor dispatch --as <agent-id>");
+  return 0;
+}
+
+async function cmdAgentCreateRemote(cfg, { label, owner, pubkey }) {
+  const body = { label };
+  if (owner) body.owner = owner;
+  if (pubkey) body.pubkey = pubkey;
+  const r = await remote.post(cfg, "/v1/admin/agents", body);
+  if (r.transport) {
+    err(`offline — could not reach server (${r.error})`);
+    return 1;
+  }
+  if (notAdminHint(r)) return 1;
+  if (r.status === 404) {
+    // The endpoint is part of the agent-identity rollout (the spor-server
+    // stream); an older server doesn't have it yet. Fail soft, don't crash.
+    err("this server has no agent-creation endpoint yet (POST /v1/admin/agents).");
+    err("  upgrade the Spor server, or create the agent in local mode against a checkout.");
+    return 1;
+  }
+  if (r.status === 409) {
+    err(`agent already exists: ${(r.json && r.json.error && r.json.error.message) || "duplicate id"}`);
+    return 1;
+  }
+  if (!r.ok) {
+    err(`agent create failed (${r.status}): ${(r.json && r.json.error && r.json.error.message) || r.text}`);
+    return 1;
+  }
+  const j = r.json || {};
+  out(`created agent ${j.id || `agent-${kebab(label)}`}${j.owner ? ` owned by ${j.owner}` : ""}`);
+  if (j.spiffe) out(`  spiffe: ${j.spiffe}`);
+  out(`  make it this machine's default: spor agent use ${j.id || `agent-${kebab(label)}`}`);
+  out(`  or dispatch as it once: spor dispatch --as ${j.id || `agent-${kebab(label)}`} …`);
+  return 0;
+}
+
+// Build the agent node + owned-by edge locally. Owner defaults to a single
+// person node in the graph when unambiguous (the solo-local common case),
+// else it must be named — the binding is identity-load-bearing, never guessed.
+async function cmdAgentCreateLocal(cfg, { label, owner, pubkey }) {
+  const graphLib = require(path.join(ROOT, "lib", "graph.js"));
+  const nodesDir = cfg.nodesDir();
+  if (!fs.existsSync(nodesDir)) {
+    err(`no graph at ${nodesDir} — run 'spor init' first`);
+    return 1;
+  }
+  let g;
+  try {
+    g = graphLib.loadGraph(nodesDir);
+  } catch (e) {
+    err(`could not load graph: ${e.message}`);
+    return 1;
+  }
+  let ownerId = owner;
+  if (!ownerId) {
+    const people = Object.values(g.nodes || {}).filter((n) => n.type === "person");
+    if (people.length === 1) {
+      ownerId = people[0].id;
+    } else if (people.length === 0) {
+      err("no person node in the graph to own this agent — pass --owner person-x");
+      err("  (an agent's owner is recorded as an owned-by edge to a person node).");
+      return 1;
+    } else {
+      err(`several person nodes — name the owner with --owner (one of: ${people.map((p) => p.id).slice(0, 6).join(", ")}${people.length > 6 ? ", …" : ""})`);
+      return 1;
+    }
+  } else if (!(g.nodes && g.nodes[ownerId])) {
+    err(`no such person node: ${ownerId}`);
+    return 1;
+  }
+
+  const prefix = (g.registry && g.registry.prefixesFor("agent") || ["agent-"])[0] || "agent-";
+  const id = `${prefix}${kebab(label)}`;
+  if (fs.existsSync(path.join(nodesDir, `${id}.md`))) {
+    err(`agent already exists: ${id}`);
+    return 1;
+  }
+  // Forward-compat spiffe shape (dec-cc-spiffe-forward-compat): recorded, not
+  // verified. <org> from config (default "local") so a solo graph is sensible.
+  const org = cfg.get("org", null) || "local";
+  const personLabel = ownerId.replace(/^person-/, "") || ownerId;
+  const spiffe = `spiffe://spor.${org}/person/${personLabel}/agent/${kebab(label)}`;
+  const md =
+    `---\nid: ${id}\ntype: agent\ntitle: ${label.replace(/\n/g, " ")}\n` +
+    `summary: Automation principal ${label}, owned by ${ownerId} — its dispatched-session writes read "agent on behalf of person".\n` +
+    `spiffe: ${spiffe}\npubkey: ${pubkey.replace(/\n/g, " ")}\nstatus: active\ndate: ${today()}\n` +
+    `edges:\n  - {type: owned-by, to: ${ownerId}}\n---\n\n` +
+    `Person-owned automation principal (dec-spor-agent-identity-nodes). Created by \`spor agent create\`; reused across dispatches as this machine's durable identity.\n`;
+  let node;
+  try {
+    node = graphLib.parseFrontmatter(md, `${id}.md`);
+  } catch (e) {
+    err(`invalid node: ${e.message}`);
+    return 1;
+  }
+  const v = graphLib.validateNode(g, node);
+  if (!v.ok) {
+    err(`invalid agent node:\n  ${v.errors.join("\n  ")}`);
+    return 1;
+  }
+  fs.writeFileSync(path.join(nodesDir, `${id}.md`), md);
+  out(`created agent ${id} owned by ${ownerId}`);
+  out(`  spiffe: ${spiffe}`);
+  out(`  make it this machine's default: spor agent use ${id}`);
+  out(`  (note: agent-on-behalf-of attribution applies in remote mode)`);
+  return 0;
+}
+
+// List agent nodes. Remote: GET /v1/agents (the caller's owned agents — the
+// dedicated route). If that surface isn't deployed (404), fall back to projecting
+// the /v1/changes audit trail and keeping the type:agent rows (newest change per
+// node first, so the first row per id is the live one). Local: scan the graph
+// home. Fail-soft on any read error.
+async function cmdAgentListRemote(cfg) {
+  const a = await remote.get(cfg, "/v1/agents", { timeoutMs: 6000 });
+  if (a.transport) {
+    err(`offline — could not reach server (${a.error})`);
+    return 1;
+  }
+  if (a.ok && a.json && Array.isArray(a.json.agents)) {
+    const rows = a.json.agents.map((ag) => `${ag.id}\t${ag.owner ? `owned-by ${ag.owner}` : (ag.title || "")}\t${ag.status || "active"}`);
+    if (!rows.length) {
+      out("no agents yet — create one with 'spor agent create <label>'");
+      return 0;
+    }
+    rows.forEach((l) => out(l));
+    return 0;
+  }
+  // /v1/agents not deployed yet — degrade to the audit-trail projection, which
+  // every remote client already has.
+  if (a.status === 404) {
+    const q = await remote.get(cfg, "/v1/changes?limit=500", { timeoutMs: 6000 });
+    if (q.ok && q.json && Array.isArray(q.json.changes)) {
+      const seen = new Set();
+      const rows = [];
+      for (const c of q.json.changes) {
+        if (!c || c.type !== "agent" || c.change === "deleted") continue;
+        if (seen.has(c.id)) continue; // first (newest) wins
+        seen.add(c.id);
+        rows.push(`${c.id}\t${c.title || ""}`);
+      }
+      if (!rows.length) {
+        out("no agents yet — create one with 'spor agent create <label>'");
+        return 0;
+      }
+      rows.forEach((l) => out(l));
+      return 0;
+    }
+  }
+  err("could not list agents from this server (no /v1/agents or /v1/changes route).");
+  err("  list them in local mode against a checkout, or upgrade the server.");
+  return 1;
+}
+
+function cmdAgentListLocal(cfg) {
+  const graphLib = require(path.join(ROOT, "lib", "graph.js"));
+  const nodesDir = cfg.nodesDir();
+  if (!fs.existsSync(nodesDir)) {
+    err(`no graph at ${nodesDir} — run 'spor init' first`);
+    return 1;
+  }
+  let g;
+  try {
+    g = graphLib.loadGraph(nodesDir);
+  } catch (e) {
+    err(`could not load graph: ${e.message}`);
+    return 1;
+  }
+  const agents = Object.values(g.nodes || {}).filter((n) => n.type === "agent");
+  if (!agents.length) {
+    out("no agents yet — create one with 'spor agent create <label>'");
+    return 0;
+  }
+  for (const a of agents.sort((x, y) => x.id.localeCompare(y.id))) {
+    const ownedBy = (a.edges || []).find((e) => e.type === "owned-by");
+    const status = a.status || "active";
+    out(`${a.id}\t${ownedBy ? `owned-by ${ownedBy.to}` : "(no owner)"}\t${status}`);
+  }
+  return 0;
+}
+
 async function cmdToken(cfg, args) {
   if (cfg.mode() !== "remote") {
     err("token admin needs a team graph (remote mode).");
@@ -1421,7 +1670,10 @@ function detectHosts() {
 // already ensured the claude CLI exists and the marketplace is registered.
 function refreshClaudePlugin(cmd, cliScope, before) {
   spawnSync(cmd, ["plugin", "marketplace", "update", "spor"], { encoding: "utf8" });
-  const upd = spawnSync(cmd, ["plugin", "update", "spor", "--scope", cliScope], { stdio: "inherit" });
+  // Claude Code resolves an installed plugin by its name@marketplace id (the
+  // install side uses 'spor@spor'); the bare 'spor' is unresolvable and fails
+  // with "Plugin 'spor' not found" (issue-spor-upgrade-wrong-plugin-marketplace-id).
+  const upd = spawnSync(cmd, ["plugin", "update", "spor@spor", "--scope", cliScope], { stdio: "inherit" });
   if (upd.status !== 0) {
     err(`claude plugin update failed (exit ${upd.status == null ? "?" : upd.status})`);
     return 1;
@@ -1606,7 +1858,10 @@ function upgradeClaude(scope, dryRun) {
   const cliScope = scope === "repo" ? "project" : "user";
   const mpAdd = ["plugin", "marketplace", "add", ROOT];
   const mpUpd = ["plugin", "marketplace", "update", "spor"];
-  const plUpd = ["plugin", "update", "spor", "--scope", cliScope];
+  // Plugin id is name@marketplace ('spor@spor'); the bare name doesn't resolve
+  // (issue-spor-upgrade-wrong-plugin-marketplace-id). Keep this dry-run preview
+  // in sync with the real call in refreshClaudePlugin().
+  const plUpd = ["plugin", "update", "spor@spor", "--scope", cliScope];
   if (dryRun) {
     out(`would run: ${cmd} ${mpAdd.join(" ")}`);
     out(`would run: ${cmd} ${mpUpd.join(" ")}`);
@@ -1755,22 +2010,45 @@ async function compileBriefing(cfg, { nodeId, query, full, project }) {
   return (r.stdout || "").trim();
 }
 
-// The single highest-ranked open queue item (for --from-queue). Mode-aware,
-// fail-soft (null on any error/empty).
+// The highest-ranked open queue item for --from-queue — the first that ISN'T
+// already in flight on THIS machine. Mode-aware, fail-soft (null on any
+// error/empty). This used to take limit=1 blindly, but the queue's lease filter
+// is viewer-relative (lib/kernel/queue.js): a lease held by ANOTHER person is
+// dropped, yet the dispatcher's OWN in-progress claim is kept and floated up by
+// its `front` signal — so the top item was frequently the caller's own active
+// work, which the same-machine guard then refused instead of advancing
+// (task-spor-dispatch-from-queue-skip-in-flight). So pull a page and skip items
+// with a background agent already running here — dispatchedAgents()/
+// annotateInFlight, the same NO-LLM, fail-soft cross-reference the same-machine
+// guard and `spor next --hide-dispatched` use — returning the first not-in-flight
+// item. If EVERY candidate is in flight, fall back to the top one so the caller's
+// guard reports it (rather than a misleading "queue empty"). A page (not just the
+// top) is fetched in BOTH modes; with no agents in flight free[0] is still the
+// top item, so the prior single-pick behavior is preserved.
 async function topQueueItem(cfg, slug) {
+  const LIMIT = 25;
+  let items = [];
   if (cfg.mode() === "remote") {
-    const q = slug ? `?project=${encodeURIComponent(slug)}&limit=1` : "?limit=1";
+    const q = slug ? `?project=${encodeURIComponent(slug)}&limit=${LIMIT}` : `?limit=${LIMIT}`;
     const r = await remote.get(cfg, `/v1/queue${q}`, { timeoutMs: 6000 });
-    return r.ok && r.json ? (r.json.items || [])[0] || null : null;
+    items = r.ok && r.json ? r.json.items || [] : [];
+  } else {
+    try {
+      const g = require(path.join(ROOT, "lib", "graph.js")).loadGraph(cfg.nodesDir());
+      const { rankQueue } = require(path.join(ROOT, "lib", "queue.js"));
+      const r = rankQueue(g, slug ? { project: slug, limit: LIMIT } : { limit: LIMIT });
+      items = r.items || [];
+    } catch {
+      items = [];
+    }
   }
-  try {
-    const g = require(path.join(ROOT, "lib", "graph.js")).loadGraph(cfg.nodesDir());
-    const { rankQueue } = require(path.join(ROOT, "lib", "queue.js"));
-    const r = rankQueue(g, slug ? { project: slug, limit: 1 } : { limit: 1 });
-    return (r.items || [])[0] || null;
-  } catch {
-    return null;
+  if (!items.length) return null;
+  // Skip items already in flight on this machine; advance to the first free one.
+  const { items: free, hidden } = annotateInFlight(items, dispatchedAgents(), true);
+  if (hidden && free.length) {
+    err(`from-queue: skipped ${hidden} item(s) already in flight on this machine; picking ${free[0].id}`);
   }
+  return free[0] || items[0] || null;
 }
 
 // Auto-claim a dispatched node so its lease is established at dispatch time
@@ -1778,17 +2056,20 @@ async function topQueueItem(cfg, slug) {
 // 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 });
+// local dispatch stays byte-identical. SESSION-BOUND at dispatch
+// (dec-spor-session-identity-active-record): dispatch now FORCES the session id
+// (`--session-id <uuid>`), so it knows the working session up front and binds the
+// lease to it; the launched bg agent runs under that exact session, so its
+// post-tool heartbeat renews the same-session lease (the earlier person-scoped /
+// session:null workaround existed only because the old dispatcher did NOT know
+// the working session — that reason is gone). Omitting `session` leaves the lease
+// person-scoped, the prior behavior. 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, session) {
+  const body = session ? { session } : {};
+  const r = await remote.post(cfg, `/v1/nodes/${encodeURIComponent(nodeId)}/claim`, body, { 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
@@ -1887,6 +2168,100 @@ function onboardRepo(cfg, dir) {
   }
 }
 
+// --- dispatch agent identity (dec-spor-session-identity-active-record) -----
+// A dispatched session runs AS this machine's agent, carried on a per-session
+// agent-scoped MCP token (env does NOT propagate through `claude --bg`, so
+// identity rides the token in --mcp-config, never env). These three helpers are
+// the verified mechanism; all fail soft so a server without the agent surface,
+// or a machine with no agent configured, degrades to the prior person-scoped
+// dispatch with a clear line.
+
+// This machine's agent node id, or null. A per-machine config key the shared
+// graph can't hold (like dispatch.repos) — SPOR_DISPATCH_AGENT / .spor.json
+// {"dispatch":{"agent":"agent-x"}} / user config. null => dispatch without
+// agent-scoping (graceful, person-attributed as before).
+function dispatchAgentId(cfg) {
+  return cfg.get("dispatch.agent", null) || null;
+}
+
+// Mint a per-session agent-scoped token (dec-spor-session-identity-active-record):
+// carries the agent (spiffe sub), the person (RFC 8693 act.sub), and the session
+// id; audience-restricted, short TTL — the server is the CA. SELF-SERVE and
+// OWNERSHIP-gated, NOT admin-gated: POST /v1/agents/{id}/token authenticated with
+// the dispatcher's normal person token (SPOR_TOKEN); the server checks the caller
+// OWNS agent {id} (the owned-by edge) — so a normal teammate can mint a token for
+// their own machine's agent without being an admin. REMOTE only. Returns
+// { ok, token } on success, { absent:true } when the mint surface isn't deployed
+// yet (404 — the spor-server stream is building it; fail soft, dispatch without
+// agent-scoping), or { error } on any other failure incl. 403/owner-mismatch
+// (also fail soft — warn and dispatch person-scoped, never block).
+async function mintAgentToken(cfg, { agent, session }) {
+  const r = await remote.post(cfg, `/v1/agents/${encodeURIComponent(agent)}/token`, { session }, { timeoutMs: 6000 });
+  if (r.transport) return { error: r.error };
+  // 404 = no route (surface not deployed) => absent, dispatch falls back cleanly.
+  if (r.status === 404) return { absent: true };
+  if (!r.ok) return { error: `HTTP ${r.status}${r.json && r.json.error && r.json.error.code ? ` (${r.json.error.code})` : ""}` };
+  const token = r.json && (r.json.token || r.json.access_token);
+  if (!token) return { absent: true };
+  return { ok: true, token };
+}
+
+// Write the 0600 --mcp-config JSON that gives the bg agent ONLY its own
+// agent-scoped Spor MCP (account connector excluded by --strict-mcp-config,
+// verified #1). Machine-local, gitignored-adjacent path under the user config
+// home's outbox; per-session filename so concurrent dispatches don't collide.
+// Returns the file path. The bg agent reads it on startup AFTER this process
+// exits (claude --bg detaches), so we cannot delete it eagerly — cleanup is a
+// best-effort sweep of stale files here, plus the documented short-TTL token
+// inside it (dec-spor-session-identity-active-record open item).
+function writeDispatchMcpConfig(cfg, { token, session }) {
+  const dir = path.join(cfg.userConfigHome(), "outbox", "dispatch");
+  fs.mkdirSync(dir, { recursive: true });
+  sweepStaleMcpConfigs(dir);
+  const file = path.join(dir, `mcp-${session}.json`);
+  const conf = {
+    mcpServers: {
+      spor: {
+        type: "http",
+        url: `${remote.base(cfg)}/mcp`,
+        headers: { Authorization: `Bearer ${token}` },
+      },
+    },
+  };
+  // 0600: the file holds a live bearer token. Create with O_EXCL (wx) so a
+  // pre-placed file or symlink at this path is REFUSED rather than written
+  // through, and the file is 0600 from creation (no widen-then-narrow window).
+  // The session-uuid filename makes a real collision a non-issue; a stale
+  // leftover was swept above.
+  const fd = fs.openSync(file, "wx", 0o600);
+  try {
+    fs.writeSync(fd, JSON.stringify(conf, null, 2) + "\n");
+  } finally {
+    fs.closeSync(fd);
+  }
+  return file;
+}
+
+// Best-effort cleanup: remove dispatch mcp-config files older than a day. The
+// tokens inside are short-TTL, but the files linger because claude --bg reads
+// them after we exit; sweep on the next dispatch so they don't accumulate.
+function sweepStaleMcpConfigs(dir) {
+  try {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    for (const f of fs.readdirSync(dir)) {
+      if (!/^mcp-.*\.json$/.test(f)) continue;
+      const p = path.join(dir, f);
+      try {
+        if (fs.statSync(p).mtimeMs < cutoff) fs.unlinkSync(p);
+      } catch {
+        /* racing another dispatch — ignore */
+      }
+    }
+  } catch {
+    /* dir vanished or unreadable — nothing to sweep */
+  }
+}
+
 async function cmdDispatch(cfg, { values, positionals: pos }) {
   const dryRun = !!(values.print || values["dry-run"]);
   const full = !!values.full;
@@ -1898,7 +2273,8 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   const dirOpt = values.dir || null;
   const model = values.model || null;
   const permMode = values["permission-mode"] || null;
-  const agent = values.agent || null;
+  const agent = values.agent || null; // claude --agent (harness agent DEFINITION)
+  const asAgent = values.as || null; // Spor agent IDENTITY override for dispatch.agent
   // A user-supplied prompt template (task-spor-dispatch-user-prompt-templates):
   // --template wins, else a personal default in the config cascade
   // (dispatch.template — an absolute path, like dispatch.repos). Empty until we
@@ -2020,13 +2396,38 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   // exit / unparseable output => empty => no guard (fail-open); --force overrides.
   const inFlight = nodeId && !backfill ? dispatchedAgents().get(name) || [] : [];
 
+  // Session identity (dec-spor-session-identity-active-record). Force the
+  // session id up front — `--session-id <uuid>` makes the dispatched run's
+  // session deterministic, so the agent-scoped token below can bind it AND the
+  // claim can be session-bound at dispatch (the bg agent's post-tool heartbeat
+  // renews under this same id). SPOR_SESSION_ID pins it for tests/reproducibility.
+  const session = process.env.SPOR_SESSION_ID || crypto.randomUUID();
+  // This machine's agent node — the WHO a dispatched session runs as. `--as`
+  // overrides the per-machine dispatch.agent default for this one dispatch (its
+  // id format mirrors a node id; a bad/unowned one fails soft at token-mint
+  // below, like the config default). Only meaningful remotely (the server is the
+  // CA that mints the agent token); a local-mode dispatch or an unconfigured
+  // machine simply runs person-scoped.
+  if (asAgent && !/^[a-z0-9][a-z0-9-]*$/.test(asAgent)) {
+    err(`invalid --as agent id '${asAgent}' — must match ^[a-z0-9][a-z0-9-]*$ (e.g. agent-your-machine)`);
+    return 1;
+  }
+  const identityAgent = cfg.mode() === "remote" ? (asAgent || dispatchAgentId(cfg)) : null;
+  // An explicit --as can't take effect in local mode — there is no CA to mint the
+  // agent token. Say so rather than silently dropping it to person-scoped.
+  if (asAgent && cfg.mode() !== "remote") {
+    err(`note: --as ${asAgent} ignored in local mode — agent-on-behalf-of attribution is remote-only`);
+  }
+
   const claudeBin = claudeCmd();
   const claudeArgs = ["--bg"];
   if (name) claudeArgs.push("--name", name);
   if (model) claudeArgs.push("--model", model);
   if (permMode) claudeArgs.push("--permission-mode", permMode);
   if (agent) claudeArgs.push("--agent", agent);
-  claudeArgs.push(prompt);
+  // Force the session id on every dispatch (local or remote). It is the run leaf
+  // of the agent's identity and what the session-bound claim + heartbeat key on.
+  claudeArgs.push("--session-id", session);
 
   if (dryRun) {
     out(`dir:    ${res.dir}  (slug: ${res.slug}, via ${res.source})`);
@@ -2038,6 +2439,18 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
       out(`onboard: ${steps.join("; ")}`);
     }
     out(`brief:  ${brief ? `${brief.length} bytes` : "(none — graph had nothing relevant, or --no-brief/--backfill)"}`);
+    out(`session: ${session}`);
+    // Identity preview: what the real dispatch would do for agent-scoping. The
+    // token mint + 0600 mcp-config are SIDE EFFECTS, so --print only describes
+    // them (it writes nothing and makes no network call here). Local mode and an
+    // unconfigured machine read "person-scoped" — byte-stable but for the new
+    // session line, which is additive and always present now.
+    if (identityAgent) {
+      const src = asAgent ? " (via --as)" : "";
+      out(`agent:  ${identityAgent}${src} (would mint a per-session agent-scoped token + write a 0600 --mcp-config, then add --strict-mcp-config)`);
+    } else if (cfg.mode() === "remote") {
+      out(`agent:  (none configured — 'spor agent use agent-<machine>' or --as to attribute as agent-on-behalf-of; dispatching person-scoped)`);
+    }
     // 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.
@@ -2050,10 +2463,10 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     // 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`}`);
+      out(`claim:  ${noClaim ? "(--no-claim — lease not established)" : `would establish a session-bound 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(`run:    ${claudeBin} ${claudeArgs.map(shellQuote).join(" ")} <prompt>`);
     out(`\n--- prompt ---\n${prompt}`);
     return 0;
   }
@@ -2082,23 +2495,49 @@ 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;
   }
+
+  // Agent-scoped identity injection (dec-spor-session-identity-active-record,
+  // the VERIFIED mechanism): mint a per-session agent-scoped token, write it into
+  // a 0600 --mcp-config that exposes ONLY the agent's own Spor MCP, and add
+  // --strict-mcp-config so the account connector is excluded by construction. The
+  // server then stamps authored_by_agent + session from that token. FAIL SOFT at
+  // every step — a server without the mint surface, or a transient error, falls
+  // back to the prior person-scoped dispatch with a clear line. Remote + a
+  // configured agent only; local/unconfigured dispatch is byte-identical but for
+  // the always-present --session-id.
+  if (identityAgent) {
+    const mint = await mintAgentToken(cfg, { agent: identityAgent, session });
+    if (mint.ok) {
+      const mcpFile = writeDispatchMcpConfig(cfg, { token: mint.token, session });
+      claudeArgs.push("--mcp-config", mcpFile, "--strict-mcp-config");
+      out(`agent:  ${identityAgent} (session ${session} — writes attributed agent-on-behalf-of-you)`);
+    } else if (mint.absent) {
+      err(`warning: this server can't mint agent-scoped session tokens yet — dispatching person-scoped (session ${session}).`);
+    } else {
+      err(`warning: could not mint an agent token (${mint.error}) — dispatching person-scoped (session ${session}).`);
+    }
+  }
+
   // 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).
+  // opts out (dispatch with no lease, the prior behavior). Now SESSION-BOUND
+  // (dec-spor-session-identity-active-record): dispatch forces the session id, so
+  // the lease binds it and the bg agent's same-session heartbeat renews it.
   if (nodeId && !backfill && !noClaim && cfg.mode() === "remote") {
-    const c = await claimDispatch(cfg, nodeId);
+    const c = await claimDispatch(cfg, nodeId, session);
     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)`);
+    if (c.ok) out(`claimed ${nodeId} (session-bound 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`);
   }
+  claudeArgs.push(prompt);
   const r = spawnSync(claudeBin, claudeArgs, { cwd: res.dir, stdio: "inherit" });
   if (r.error) {
     err(`could not launch ${claudeBin}: ${r.error.message}`);
@@ -2282,6 +2721,30 @@ const COMMANDS = {
     examples: ["spor token list", "spor token revoke a1b2c3"],
     run: (cfg, args) => cmdToken(cfg, args),
   },
+  agent: {
+    group: "Team admin (remote, admin token)", parse: "raw", args: "create <label> [--owner <id>] [--pubkey <fp>] | list | use <agent-id>",
+    summary: "person-owned automation principals (dispatch identity)",
+    help:
+      "Create and list agents — first-class `type: agent` nodes owned by a person\n" +
+      "(dec-spor-agent-identity-nodes). A dispatched session runs AS its agent, so its\n" +
+      "writes read \"agent on behalf of person\" rather than person-direct. One durable\n" +
+      "agent per machine/install, reused across dispatches.\n\n" +
+      "  spor agent create <label>     create the agent + its owned-by edge to a person\n" +
+      "      --owner <person-id>       owner (remote: defaults to your person; local:\n" +
+      "                                defaults to the sole person node, else required)\n" +
+      "      --pubkey <fingerprint>    record a public-key fingerprint (forward-compat,\n" +
+      "                                unenforced — may be omitted)\n" +
+      "  spor agent list               list agents and their owners\n" +
+      "  spor agent use <agent-id>     make it THIS machine's default dispatch identity\n" +
+      "                                (writes dispatch.agent to your user config; pass\n" +
+      "                                --clear to go back to person-scoped dispatch)\n\n" +
+      "'use' is a local config write, not a graph write — it sets which agent\n" +
+      "`spor dispatch` runs as by default (override one dispatch with 'dispatch --as').\n" +
+      "Create/list run remote (POST /v1/admin/agents, admin-gated, the server mints the\n" +
+      "spiffe); local mode writes the node + owned-by edge to the graph home.",
+    examples: ["spor agent create anthony-laptop", "spor agent use agent-anthony-laptop", "spor agent list"],
+    run: (cfg, args) => cmdAgent(cfg, args),
+  },
 
   // --- Graph ---
   add: {
@@ -2435,7 +2898,8 @@ const COMMANDS = {
     help:
       "Compile a briefing for a task and launch a Claude Code background agent in the\n" +
       "right repo. Give free-text, a <node-id>, --node <id>, --from-queue (the top\n" +
-      "ranked item), or --backfill (onboard/repair a repo). The target dir is the\n" +
+      "ranked item NOT already in flight on this machine), or --backfill (onboard/\n" +
+      "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" +
@@ -2444,21 +2908,27 @@ const COMMANDS = {
       "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.",
+      "{{slug}}/{{dir}}/{{default}} placeholders.\n\n" +
+      "Two different 'agent' axes, don't confuse them: --as picks the Spor agent\n" +
+      "IDENTITY the dispatch runs AS (attribution 'agent on behalf of person',\n" +
+      "remote-only; defaults to dispatch.agent — set it with 'spor agent use <id>').\n" +
+      "--agent is the unrelated 'claude --agent' passthrough that picks the harness\n" +
+      "agent DEFINITION (subagent personality/toolset) the background session runs.",
     options: {
       dir: { type: "string", value: "path", desc: "launch directory (overrides the slug map)" },
       node: { type: "string", value: "id", desc: "dispatch a specific node id" },
       slug: { type: "string", value: "slug", desc: "target project slug (cross-repo resolution)" },
+      as: { type: "string", value: "agent-id", desc: "Spor agent IDENTITY to run as (overrides dispatch.agent; remote-only)" },
       model: { type: "string", value: "M", desc: "claude --model" },
       "permission-mode": { type: "string", value: "P", desc: "claude --permission-mode" },
-      agent: { type: "string", value: "A", desc: "claude --agent" },
+      agent: { type: "string", value: "A", desc: "claude --agent (harness agent DEFINITION — NOT the Spor identity; see --as)" },
       name: { type: "string", value: "N", desc: "claude --name (session name)" },
       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" },
+      "from-queue": { type: "boolean", desc: "dispatch the top-ranked queue item not already in flight here" },
       backfill: { type: "boolean", desc: "onboard/repair this repo (runs /spor:backfill)" },
       print: { type: "boolean", desc: "dry run — print the prompt, launch nothing" },
       "dry-run": DRYRUN_OPT,

package/lib/config.js

@@ -86,6 +86,7 @@ const ENV_MAP = [
   ["QUEUE_FRONT", "queue.front.enabled"], // SPOR_QUEUE_FRONT=0 disables local git-derived front
   ["QUEUE_FRONT_DAYS", "queue.front.days"], // rolling front window (days)
   ["QUEUE_PROJECT", "queue.project"], // default --project scope for `spor next` (both modes); explicit --project wins
+  ["DISPATCH_AGENT", "dispatch.agent"], // this machine's default agent for `spor dispatch` (per-machine, like dispatch.repos)
 ];
 
 function isPlainObject(v) {

package/lib/graph.js

@@ -86,6 +86,8 @@ module.exports = {
   renderSkeleton,
   parseFrontmatter: kernel.parseFrontmatter,
   rankAgainst: kernel.rankAgainst,
+  // agent-on-behalf-of authorship read-out (dec-spor-agent-identity-nodes)
+  authorshipLine: kernel.authorshipLine,
   // project identity (task-cc-project-identity-nodes): slug-alias resolution
   resolveProject: kernel.resolveProject,
   // grouping membership (task-cc-grouping-brief-digest-reads): repo<->grouping

package/lib/kernel/graph.js

@@ -423,6 +423,26 @@ function structuralWalk(graph, seeds) { // seeds: {id: initialScore}
   return best;
 }
 
+// Authorship read-out (dec-spor-agent-identity-nodes). A node written by a
+// dispatched agent carries the additive `authored_by_agent: agent-<id>` stamp
+// (server-applied from the token, never the payload) alongside its unchanged
+// person `author:`. When present, the node reads "agent <label> on behalf of
+// <person>" — the agent is the WHO that did the work, the person remains the
+// accountable owner. ADDITIVE and backward-readable: a node WITHOUT the stamp
+// (every pre-feature node, and every person-direct write) returns the plain
+// `author` string exactly as before, so existing output is byte-identical. The
+// agent's display label is its node title when the agent node is in the graph,
+// else the bare id; an unresolvable stamp still reads as agent-on-behalf-of so
+// the provenance survives a missing agent node.
+function authorshipLine(node, nodes) {
+  const author = (typeof node.author === "string" && node.author.trim()) || "";
+  const byAgent = typeof node.authored_by_agent === "string" && node.authored_by_agent.trim();
+  if (!byAgent) return author; // person-direct — unchanged
+  const agentNode = nodes && nodes[byAgent];
+  const label = (agentNode && typeof agentNode.title === "string" && agentNode.title.trim()) || byAgent;
+  return author ? `agent ${label} on behalf of ${author}` : `agent ${label}`;
+}
+
 // ---------- compile ----------
 //
 // opts: { rootId?, query?, digest?, minSim?, seedSchemas? }
@@ -746,7 +766,12 @@ function compile(graph, opts = {}) {
   // node's `author:` frontmatter); unattributed norms say so, which is itself a
   // signal to distrust.
   function renderNorm(n, full) {
-    const author = (typeof n.author === "string" && n.author.trim()) || "unattributed — treat with extra suspicion";
+    // Agent-on-behalf-of read-out (dec-spor-agent-identity-nodes): when the norm
+    // carries an `authored_by_agent` stamp it reads "agent <label> on behalf of
+    // <person>"; without it, the plain person author exactly as before (so a
+    // norm with no stamp — every existing one — is byte-identical). An entirely
+    // unattributed norm keeps its distrust marker.
+    const author = authorshipLine(n, nodes) || "unattributed — treat with extra suspicion";
     const head = `### ${n.id} — ${n.title} (norm, ${n.date}${statusTag(n)}${crossTag(n)})\n*authored by: ${author}*\n`;
     const body = full ? n.body : n.summary;
     // Blockquote every line so the norm reads as quoted data, not prose
@@ -1050,6 +1075,7 @@ module.exports = {
   validateNode,
   validateGraphFiles,
   rankAgainst,
+  authorshipLine,
   registry,
   DIGEST_CAP,
   DEFAULT_MIN_SIM,

package/lib/seed/schema-agent.md

@@ -0,0 +1,67 @@
+---
+id: schema-agent
+type: schema
+kind: node-schema
+schema_version: 2026.06.16.1
+title: Seed schema for agent nodes
+summary: Node schema for the agent type — a person-owned automation principal (a dispatched Claude session's durable identity), owned by a person via an `owned-by` edge and carrying a forward-compat `spiffe:`/`pubkey:` shape. One persistent node per machine/install, reused across dispatches; its writes are attributed "agent on behalf of person", not as the person directly. Seed-pack default; a graph-resident schema node for this type overrides it.
+date: 2026-06-16
+---
+
+Seed schema for the `agent` node type (ontology in GRAPH.md), shipped with the
+plugin as a registry default (QUEUE.md §2). A `type: schema` node in the graph
+with `kind: node-schema` and the same `node_type` overrides this entry.
+
+An agent node makes a person's automation principal first-class instead of an
+anonymous flag on a write (dec-spor-agent-identity-nodes). It generalizes the
+workflow-run principal the graph already carries: an interactively dispatched
+`claude --bg` session is just another principal kind owned by a person, so its
+created nodes can read "agent on behalf of person" instead of person-direct.
+
+**Grain: persistent + lightweight runs.** One durable agent node per
+machine/install, created once (e.g. `agent-anthony-laptop`) by `spor agent
+create`, and REUSED across dispatches — NOT one node per session. The Claude
+Code `session_id` of each dispatch is the ephemeral which-run; it rides as an
+additive `session:` stamp on created nodes, not its own node (promote to a
+`run-<id>` node only if run metadata later needs a home).
+
+**Ownership is an edge, not a field.** An agent's owner is recorded with an
+`owned-by` edge → its `person-<id>` (schema-edge-owned-by), so the binding is a
+first-class, traversable graph fact rather than a frontmatter scalar — the same
+shape question routing and `$viewer` already key on for person edges. The
+agent/person binding is authorization-load-bearing, so like all attribution
+(dec-cc-attribution-from-token) it is asserted only by an authenticated
+identity, never from a caller's payload.
+
+Instances carry, beyond the standard fields (`id`, `type`, `title`, `summary`,
+`date`), three identity registers — all flat scalars the regex frontmatter
+parser already supports:
+
+- `spiffe:` — a SPIFFE-shaped URI encoding the agent→person binding in its
+  path: `spiffe://spor.<org>/person/<person-id>/agent/<label>`. The dispatch
+  run extends it to the session leaf the workflow side already uses
+  (`…/agent/<label>/session/<uuid>`). Adopted as forward-compat SHAPE
+  (dec-cc-spiffe-forward-compat) — recorded, not yet runtime-verified.
+- `pubkey:` — the agent's public-key fingerprint string. MAY BE EMPTY in this
+  cut; recorded for forward-compat (server-token JWKS / local signed-commit
+  web-of-trust) but UNENFORCED — no signature verification ships yet.
+- `status: active` — an agent is live by default. Any other status (or none)
+  reads as before; declarative data only, not gated by a `transitions()` enum,
+  so it stays backward-readable.
+
+`capturable: false`: agent identity is created deliberately (`spor agent
+create`, or the admin endpoint), never drafted from a capture or a distilled
+transcript — mirroring `person`, `repo`, and `workflow-run`. Graphs without
+agent nodes behave exactly as before; their nodes simply lack the
+`authored_by_agent`/`session` attribution stamps and read as person-direct.
+
+```json
+{
+  "node_type": "agent",
+  "description": "a person-owned automation principal — a dispatched session's durable identity, owned by a person via an owned-by edge; its writes are attributed agent-on-behalf-of-person",
+  "prefix": [
+    "agent-"
+  ],
+  "capturable": false
+}
+```

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

@@ -0,0 +1,37 @@
+---
+id: schema-edge-owned-by
+type: schema
+kind: edge-schema
+schema_version: 2026.06.16.1
+title: Seed schema for owned-by edges
+summary: Edge schema for the owned-by type — an agent is owned by a person; the identity-binding key for agent-on-behalf-of-person attribution. Structural membership like grouped-under, not a work dependency. Seed-pack default; a graph-resident schema node for this edge type overrides it.
+date: 2026-06-16
+---
+
+Seed schema for the `owned-by` edge type (agent → person), shipped with the
+plugin as a registry default (QUEUE.md §2). Written from a `type: agent` node
+(schema-agent) to its owning `person-` node by `spor agent create` / the admin
+endpoint, recording the person-owns-agent binding as a first-class graph fact
+(dec-spor-agent-identity-nodes).
+
+A low structural weight, mirroring `grouped-under` (0.3): like a repo's home
+grouping, an agent's owner is durable membership, not work flow — the owner
+rarely needs to be pulled into a work neighborhood, and a low weight keeps agent
+identity from polluting task briefings. It sits just under the person-graph
+identity edges (`stewards` 0.4, `assigned` 0.5), which DO carry work signal. Its
+inverse `owns` is how the binding reads from the person's side (person owns
+agent), flipped onto the person on write.
+
+`capturable: false`: the binding is created deliberately alongside the agent
+node (schema-agent), never drafted from a capture — mirroring the identity-node
+types it joins.
+
+```json
+{
+  "edge_type": "owned-by",
+  "description": "this agent is owned by the target person — the agent-on-behalf-of-person identity binding",
+  "weight": 0.3,
+  "inverse_label": "owns",
+  "capturable": false
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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",
@@ -46,6 +46,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
+    "test:e2e": "node --test test/e2e-claude.test.js",
     "conformance": "node conformance/runner.js"
   },
   "engines": {

package/scripts/engines/prompt-context.js

@@ -127,10 +127,20 @@ async function promptContext(input) {
     const rlogFile = path.join(graph, "journal", "remote.log");
     const rlog = u.makeLogger(rlogFile, "prompt-context: ");
 
+    // Send the session project so the SERVER-side compile applies the same
+    // project scoping the local digest already gets — the same-project
+    // relevance boost, the grouping union, and the norm `applies_to_*`
+    // ride-along (issue-spor-remote-digest-project-blind). The remote digest
+    // was project-blind: it posted only `query`, so every compile() session-
+    // project feature silently no-opped in remote mode. `slug` is the same
+    // `projectSlug(cwd)` already fed to the local merge below. Absent a slug
+    // the body is byte-identical to the prior project-blind POST, and an older
+    // server simply ignores the field (it stays the default), so this is safe
+    // either way.
     const resp = await u.curl(`${u.serverBase()}/v1/digest`, {
       method: "POST",
       headers: { ...u.bearer(), "Content-Type": "application/json" },
-      body: JSON.stringify({ query: prompt }),
+      body: JSON.stringify(slug ? { query: prompt, project: slug } : { query: prompt }),
       timeoutMs: 4000,
     });
 

package/scripts/engines/session-start.js

@@ -9,8 +9,15 @@ const fs = require("fs");
 const path = require("path");
 const u = require("./util");
 
+// The /spor:spor preload instruction LEADS every usage string (and so every
+// session-start envelope, all modes): Spor's CLI syntax, node/edge format, and
+// MCP/REST surface aren't in the model's training, so any graph operation
+// attempted without first loading the skill tends to invent syntax. Stating it
+// as a standing precondition here is cheaper than the agent rediscovering it
+// per session. Phrased as "before any operation on the graph" to match the
+// skill's own trigger.
 const USAGE =
-  "Use /spor:brief <query or node-id> for a task-specific briefing, /spor:correct to fix a bad briefing.";
+  "Before any operation on the Spor graph (searching/querying, reading or writing nodes, adding edges, capturing, or running spor CLI/MCP tools), load the /spor:spor skill first — it carries the CLI syntax, node/edge format, and tool surface your training doesn't cover. Use /spor:brief <query or node-id> for a task-specific briefing, /spor:correct to fix a bad briefing.";
 const USAGE_REMOTE =
   USAGE +
   " When you defer discovered work mid-task (out-of-scope fix, follow-up, dismissed approach), capture it the moment you defer it: /spor:defer <2-3 sentences, what + why> — one call, the server types and links it.";

package/scripts/engines/util.js

@@ -490,6 +490,43 @@ function forgetRepo(graphHomeDir, slug) {
   });
 }
 
+// Record this machine's default dispatch identity (`dispatch.agent`) into the
+// SAME user config.json as the repo map — the per-machine key `spor dispatch`
+// reads to attribute a dispatched session "agent on behalf of person". Scalar
+// sibling of registerRepo: agentId is an `agent-...` node id, or null/"" to
+// clear. Returns true only when it actually wrote; refuses to clobber a
+// present-but-malformed config (same fail-safe as editRepoMap).
+function setDispatchAgent(graphHomeDir, agentId) {
+  try {
+    const file = userConfigPath(graphHomeDir);
+    let raw = null;
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch {
+      raw = null; // absent — start fresh
+    }
+    let data = {};
+    if (raw != null) {
+      try {
+        data = JSON.parse(raw);
+      } catch {
+        return false; // malformed — do NOT overwrite
+      }
+      if (data == null || typeof data !== "object" || Array.isArray(data)) data = {};
+    }
+    if (data.dispatch == null || typeof data.dispatch !== "object" || Array.isArray(data.dispatch)) data.dispatch = {};
+    const next = agentId || null;
+    if ((data.dispatch.agent || null) === next) return false; // unchanged — skip the write
+    if (next == null) delete data.dispatch.agent;
+    else data.dispatch.agent = next;
+    if (!ensureDir(graphHomeDir)) return false;
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function appendLine(file, line) {
   try {
     fs.appendFileSync(file, line + "\n");
@@ -780,6 +817,7 @@ module.exports = {
   ensureGraphGitignore,
   registerRepo,
   forgetRepo,
+  setDispatchAgent,
   appendLine,
   makeLogger,
   loadGraphCached,

package/skills/brief/SKILL.md

@@ -24,15 +24,28 @@ Steps:
    **Remote mode (team graph) — when `SPOR_SERVER` is set:** the compile
    runs on the server. Use its REST twins (API.md §3) instead of the local
    compile.js. (Env vars here are the `SPOR_*` family; the legacy
-   `SUBSTRATE_*` names are still read.)
+   `SUBSTRATE_*` names are still read.) First resolve THIS repo's project slug
+   the same way a session does and send it as `"project"` so the server scopes
+   the compile to your repo — the same-project relevance boost, the grouping
+   union, and the `always_on` norm `applies_to_*` ride-along — instead of
+   running *project-blind* (issue-spor-remote-digest-project-blind). Resolve the
+   plugin root from the session-start cache, then the slug:
+   ```bash
+   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}"
+   SLUG="$(node -e 'process.stdout.write(require("'"$SPOR_ROOT"'/scripts/engines/util.js").projectSlug(process.cwd()))' 2>/dev/null)"
+   ```
    - free-text query: `POST ${SPOR_SERVER%/}/v1/digest` with
-     `{"query":"<text>"}` (`Authorization: Bearer $SPOR_TOKEN`); the `text`
-     field is the compiled neighborhood. A `{"found":false}` means the team
-     graph has nothing relevant — say so and stop.
+     `{"query":"<text>","project":"<slug>"}` (`Authorization: Bearer
+     $SPOR_TOKEN`); the `text` field is the compiled neighborhood. A
+     `{"found":false}` means the team graph has nothing relevant — say so and
+     stop. (Omit `project` only if the slug couldn't be resolved.)
    - node id: `GET ${SPOR_SERVER%/}/v1/nodes/<id>` for the raw node, and
-     `POST /v1/digest` with the node's title/summary as the query for its
-     neighborhood. In Cowork, call the `query_graph` MCP tool (with `root_id` for
-     a node id, or `query` for free text) — there is no compile.js there.
+     `POST /v1/digest` with the node's title/summary as the query (plus the same
+     `"project":"<slug>"`) for its neighborhood. In Cowork, call the
+     `query_graph` MCP tool (with `root_id` for a node id, or `query` for free
+     text) — there is no compile.js there.
 
    **Local mode (personal graph) — `SPOR_SERVER` unset:** first resolve the
    plugin root — `${CLAUDE_PLUGIN_ROOT}` is empty in the Bash tool, so read

package/skills/spor/SKILL.md

@@ -85,6 +85,13 @@ spor add "<2-3 sentences>"     # capture a node (typed file locally; /v1/capture
 
 # remote (team server) only
 spor lens [<id>]               # list saved views, or render one
+spor agent create <label>      # create one of your agents — a person-owned principal (`spor agent list`)
+spor agent use <agent-id>      # make it THIS machine's default dispatch identity (writes dispatch.agent)
+spor dispatch <id>|"<task>"    # run work as a background agent; in team mode its graph writes are
+                               #   attributed "agent on behalf of you" (the machine's default agent =
+                               #   dispatch.agent, set by `spor agent use`; --as <agent-id> overrides it
+                               #   per dispatch; --agent is the unrelated `claude --agent` passthrough).
+                               #   See API.md §3-§4.
 
 # dual-mode (local passthrough / remote dispatch to the server)
 spor compile --query "<text>"  # search → compiled neighborhood (--digest for compact)

package/skills/spor/references/concepts.md

@@ -23,6 +23,7 @@ the decision queue (QUEUE.md §4).
 | correction | `corr-` | a standing fix to a briefing (pin/exclude/guidance) | `traversable: false`; applied at every future compile of its target |
 | question | `question-` | a routed ask the graph couldn't answer | queueable; status `open`/`answered`; joins the queue until answered |
 | person | `person-` | an org member | anchor for `$viewer` binding and question routing |
+| agent | `agent-` | a person-owned automation principal | a dispatched session's durable identity; owned by a person via `owned-by`; `capturable: false`; carries forward-compat `spiffe:`/`pubkey:` |
 | capture-pending | `cap-` | raw captured text that fit no schema | born status-less; closes only as `merged` or `rejected` |
 | finding | `find-` | a gardener observation (stale anchor, cold work) | filed as a queue item |
 | repo | `repo-` | a durable git-repo identity | carries `slugs:` aliases + `fingerprints:`; heals renames at read time; optional `tags:` are the match key for a norm's `applies_to_tags` |
@@ -55,6 +56,7 @@ are same-direction synonyms renamed at write time.
 | mentions | 0.5 | weakest association | — |
 | stewards | 0.4 | this person stewards the target area/spec/norm | question-routing key |
 | grouped-under | 0.3 | this repo's home project grouping (structural) | inverse `groups` |
+| owned-by | 0.3 | this agent is owned by that person (structural identity) | inverse `owns` |
 | routed-to | 0.3 | this question is routed to that person | — |
 | compiled-for | — | briefing → the task/query it was compiled for | provenance only |
 | shaped-by | — | briefing → the corrections that shaped it | provenance only |
@@ -62,7 +64,7 @@ are same-direction synonyms renamed at write time.
 **Ride-along flags** (set in a schema's JSON payload):
 - `always_on: true` (norm) — injected into every project-relevant compile.
 - `traversable: false` (briefing, correction) — excluded from lineage walks.
-- `capturable: false` (briefing, workflow-run) — never produced by capture.
+- `capturable: false` (briefing, workflow-run, agent) — never produced by capture.
 
 An `always_on` norm rides along project-wide by default, but that scope is the
 whole home-project **grouping** — so under a project that spans heterogeneous
@@ -107,7 +109,9 @@ a load-bearing reason exists ("because the release is Friday"), record it here.
 One fact per node; if you're writing "and also…", split it.
 ```
 
-Server-stamped fields you don't set by hand: `author`, `authored_via`. Other
+Server-stamped fields you don't set by hand: `author`, `authored_via` (plus `authored_by_agent` +
+`session`, with `authored_via: dispatch`, on a write made under an agent-scoped
+token — the node reads "agent on behalf of person"). Other
 type-specific fields exist (`wake:` dormancy date; `commits:` linked git shas;
 `pin:`/`exclude:` on corrections; `slugs:`/`fingerprints:`/`tags:` on repo nodes;
 `applies_to_tags:`/`applies_to_repos:`/`applies_to_projects:` ride-along