@sporhq/spor 0.7.0 → 0.8.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.7.0",
+  "version": "0.8.0",
   "author": { "name": "losthammer" }
 }

package/API.md

@@ -376,8 +376,10 @@ anything with a token.
   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
-  (`SPOR_DISPATCH_AGENT`).
+  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/bin/spor.js

@@ -977,10 +977,45 @@ async function cmdAgent(cfg, args) {
   if (!sub || sub === "list") {
     return cfg.mode() === "remote" ? cmdAgentListRemote(cfg) : cmdAgentListLocal(cfg);
   }
-  err("usage: spor agent create <label> [--owner person-x] [--pubkey <fp>] | spor agent list");
+  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;
@@ -1009,7 +1044,8 @@ async function cmdAgentCreateRemote(cfg, { label, owner, pubkey }) {
   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(`  dispatch with this agent: spor dispatch … (set dispatch.agent=${j.id || `agent-${kebab(label)}`} to make it this machine's default)`);
+  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;
 }
 
@@ -1080,7 +1116,8 @@ async function cmdAgentCreateLocal(cfg, { label, owner, pubkey }) {
   fs.writeFileSync(path.join(nodesDir, `${id}.md`), md);
   out(`created agent ${id} owned by ${ownerId}`);
   out(`  spiffe: ${spiffe}`);
-  out(`  dispatch with this agent: set dispatch.agent=${id} (spor repos config), then 'spor dispatch …'`);
+  out(`  make it this machine's default: spor agent use ${id}`);
+  out(`  (note: agent-on-behalf-of attribution applies in remote mode)`);
   return 0;
 }
 
@@ -1633,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;
@@ -1818,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(" ")}`);
@@ -1967,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
@@ -2207,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
@@ -2335,10 +2402,22 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
   // 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. 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.
-  const identityAgent = cfg.mode() === "remote" ? dispatchAgentId(cfg) : null;
+  // 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"];
@@ -2367,9 +2446,10 @@ async function cmdDispatch(cfg, { values, positionals: pos }) {
     // unconfigured machine read "person-scoped" — byte-stable but for the new
     // session line, which is additive and always present now.
     if (identityAgent) {
-      out(`agent:  ${identityAgent} (would mint a per-session agent-scoped token + write a 0600 --mcp-config, then add --strict-mcp-config)`);
+      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 — set dispatch.agent=agent-<machine> to attribute as agent-on-behalf-of; dispatching person-scoped)`);
+      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
@@ -2642,7 +2722,7 @@ const COMMANDS = {
     run: (cfg, args) => cmdToken(cfg, args),
   },
   agent: {
-    group: "Team admin (remote, admin token)", parse: "raw", args: "create <label> [--owner <id>] [--pubkey <fp>] | list",
+    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" +
@@ -2654,10 +2734,15 @@ const COMMANDS = {
       "                                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\n" +
-      "Remote mode creates through POST /v1/admin/agents (admin-gated, the server mints\n" +
-      "the spiffe). Local mode writes the node + owned-by edge to the graph home.",
-    examples: ["spor agent create anthony-laptop", "spor agent create ci-runner --owner person-anthony", "spor agent list"],
+      "  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),
   },
 
@@ -2813,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" +
@@ -2822,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.7.0",
+  "version": "0.8.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",
@@ -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/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/spor/SKILL.md

@@ -86,9 +86,12 @@ 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 / SPOR_DISPATCH_AGENT). See API.md §3-§4.
+                               #   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)