@sporhq/spor 0.18.0 → 0.18.2

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "spor",
   "displayName": "Spor Context Compiler",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "spor",
+  "version": "0.18.2",
+  "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
+  "author": {
+    "name": "Spor",
+    "url": "https://github.com/sporhq/spor"
+  },
+  "homepage": "https://sporhq.io",
+  "repository": "https://github.com/sporhq/spor",
+  "license": "Apache-2.0",
+  "keywords": [
+    "knowledge-graph",
+    "context",
+    "memory",
+    "agents",
+    "spor",
+    "provenance"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Spor Context Compiler",
+    "shortDescription": "Graph-backed briefings, captures, and queue triage for Codex.",
+    "longDescription": "Spor keeps durable project context in a typed knowledge graph, then helps Codex brief tasks, capture follow-up work, correct stale context, and work the decision queue.",
+    "developerName": "Spor",
+    "category": "Productivity",
+    "capabilities": [
+      "Knowledge graph",
+      "Task briefings",
+      "Queue triage"
+    ],
+    "websiteURL": "https://sporhq.io",
+    "defaultPrompt": [
+      "Brief this Spor task before I start work.",
+      "Capture this follow-up in the graph.",
+      "Show me what is next in the Spor queue."
+    ],
+    "brandColor": "#3B82F6"
+  }
+}

package/API.md

@@ -402,7 +402,7 @@ endpoint is the REST twin of a core call:
 | `GET /v1/nodes/{id}` | /spor:brief | `get_node` semantics; the node's active schema may attach read-time enrichment via a `get(node, ctx)` hook (GRAPH.md) — the seed `question`/`issue`/`task`/`incident` schemas attach `resolution`: a live inbound resolves/answers edge carrying the resolver's `summary`/`title` and a `lagging` flag (set when it contradicts a still-open status, clear when the node is already terminal, e.g. an answered question pointing at its answer). Open gardener findings about the node ride along as `open_findings`, and a node marked stale by an inbound supersedes edge as `superseded_by`. All enrichment is additive top-level keys; ignore unknown ones |
 | `GET /v1/nodes/{id}/history?limit=N` | `spor history <id>`, the `node_history` MCP tool | per-node commit lineage — a `git log` projection over `nodes/{id}.md` → `{id, head, count, history: [{sha, short, actor, actor_name, actor_email, date, message, internal, person}]}`, newest first. Each revision is labeled `internal:true` for a server-internal write (boot reconcile / migration, `server@spor.invalid`) vs. a real actor, and mapped to its `person` node by author email. Deliberately NOT `git log --follow` (node files share heavy frontmatter boilerplate, so similarity-based rename detection crosses node boundaries — dec-spor-node-history-git-log-projection). `limit` defaults to 50, max 200. The frontmatter `author` re-stamps to the LAST editor on every write, so this is the only durable record of the full chain of editors. A node with no commit history (unknown id) is `404`; a bad id is `422`. The `spor history <id>` CLI verb is the shell front-door (remote reads this; local mode runs the same projection over the graph home) |
 | `GET /v1/nodes/{id}/history/{sha}` | `spor history <id> <sha>`, `node_history` (sha mode) | one revision's detail, the expensive half gated behind an explicit per-sha fetch → the history record for that commit plus `{change, patch, content}`: the change type (`A`/`M`/`D`/`R`), the patch this commit introduced to the node file, and the full node content at that revision (`null` when the commit deleted it). The `sha` must be one from the node's own history — a sha that didn't touch the node, or an unresolvable sha, is `404`; a malformed sha is `422` |
-| `POST /v1/nodes` | drain-outbox, mechanical writers | `put_node` semantics, batch: `{nodes: [...], if_exists: "skip"}` (entries may be raw strings or `{node, if_exists, revision}`) → `{results: [...]}`, 207 when any entry failed. Entries are applied **sequentially** and each is fully validated before the next — including the completion-resolver gate that runs on create (GRAPH.md "the resolver gate") — so a born-terminal node (`done` task / `resolved` issue) must have its resolving `decision`/`artifact` EARLIER in the same batch (**resolver-first ordering**; the batch does not defer the gate to end-of-batch, dec-spor-batch-create-gate-resolver-first-ordering). The 207 is partial-success: entries already applied before a later entry's failure are not rolled back |
+| `POST /v1/nodes` | `spor put-node`, drain-outbox, mechanical writers | `put_node` semantics, batch: `{nodes: [...], if_exists: "skip"}` (entries may be raw strings or `{node, if_exists, revision}`) → `{results: [...]}`, 207 when any entry failed. Entries are applied **sequentially** and each is fully validated before the next — including the completion-resolver gate that runs on create (GRAPH.md "the resolver gate") — so a born-terminal node (`done` task / `resolved` issue) must have its resolving `decision`/`artifact` EARLIER in the same batch (**resolver-first ordering**; the batch does not defer the gate to end-of-batch, dec-spor-batch-create-gate-resolver-first-ordering). The 207 is partial-success: entries already applied before a later entry's failure are not rolled back |
 | `POST /v1/nodes/{id}/edges` `{type, to, attrs?}` | scripts, mechanical writers | `add_edge` semantics (§1): normalize/flip, dedupe, append — no revision echo. Optional `attrs` adds trailing flat edge attributes (e.g. a per-assignment `profile:` override); re-adding the same edge with different attrs upserts the set. Adding a review-outcome edge (`reviewed-by`/`changes-requested-by`/`review-requested`) flips a sibling review edge to the same person in place — the one-call submit-review primitive |
 | `DELETE /v1/nodes/{id}/edges` `{type, to}` | scripts, mechanical writers | `remove_edge` semantics (§1): the withdrawal twin of the POST above — drop one typed edge by `{type, to}`, normalize/flip exactly as `add_edge` (an inverse form removes the canonical edge on the *other* node and echoes its id), no revision echo. A missing edge is an idempotent `skipped`. For *withdrawing* a relationship the review flip can't express — a pulled review request, a dismissed review |
 | `POST /v1/nodes/{id}/status` `{status}` | scripts, mechanical writers | `set_status` semantics (§1): one-scalar update through the `transitions()` gate. Setting a work node to an in-progress status also CLAIMS it (same lease as `/claim` below) |

package/adapters/codex/README.md

@@ -7,7 +7,18 @@ is just a manifest over `bin/spor-hook.js`.
 ## Install
 
 1. Clone this repo somewhere stable, e.g. `~/tools/spor`.
-2. Resolve the path placeholder and install the manifest:
+2. Install the Codex plugin, hook manifest, and backfill custom agent:
+
+   ```sh
+   ~/tools/spor/bin/spor install codex
+   ```
+
+   This registers this checkout as the `spor` Codex marketplace, runs
+   `codex plugin add spor@spor`, resolves the hook path placeholder, and keeps
+   the custom agent sourced from `agents/backfill.md`.
+
+3. Manual hook-only install, if you are debugging the adapter without the Codex
+   plugin:
 
    ```sh
    SPOR_ROOT=~/tools/spor
@@ -18,7 +29,8 @@ is just a manifest over `bin/spor-hook.js`.
    (Or merge into an existing `~/.codex/hooks.json` / `[hooks]` table in
    `~/.codex/config.toml`. Per-repo installs go in `<repo>/.codex/hooks.json`.)
 
-3. Add the backfill custom agent:
+4. Add the backfill custom agent manually, only if you skipped
+   `spor install codex`:
 
    ```sh
    mkdir -p ~/.codex/agents
@@ -31,27 +43,20 @@ is just a manifest over `bin/spor-hook.js`.
    } > ~/.codex/agents/spor-backfill.toml
    ```
 
-   `spor install codex` performs both steps automatically and keeps the custom
-   agent sourced from `agents/backfill.md`.
-
-4. Approve the hooks in Codex's `/hooks` trust prompt on first run.
-5. Environment (the same variables on every host):
+5. Approve the hooks in Codex's `/hooks` trust prompt on first run.
+6. Environment (the same variables on every host):
 
    ```sh
    export SPOR_SERVER=https://spor.example.com   # remote mode
    export SPOR_TOKEN=spor_pat_...
-   # Distiller backend — Codex hosts usually won't have the claude CLI.
-   # Contract: prompt on stdin, response on stdout.
-   export SPOR_DISTILL_CMD='codex exec -'
-   # Capture-nudge backend — same contract, but it runs synchronously in the
-   # tool loop, so prefer a fast model. SPOR_NUDGE=0 disables it.
-   export SPOR_NUDGE_CMD='codex exec -'
+   # Capture-nudge defaults to `codex exec --model gpt-5.4-mini -`; distill
+   # defaults to `codex exec -`. Set SPOR_NUDGE_CMD / SPOR_DISTILL_CMD only to
+   # override those defaults; SPOR_NUDGE=0 disables the nudge.
    ```
 
-   (Legacy `SUBSTRATE_*` names are still read.) Without `SPOR_DISTILL_CMD` /
-   `SPOR_NUDGE_CMD` both default to `claude -p --model haiku`, which is fine if
-   the claude CLI is installed. See [adapters/README.md](../README.md) for the
-   nudge bounds (`SPOR_NUDGE_MAX`, `SPOR_NUDGE_TIMEOUT`).
+   (Legacy `SUBSTRATE_*` names are still read.) See
+   [adapters/README.md](../README.md) for the nudge bounds (`SPOR_NUDGE_MAX`,
+   `SPOR_NUDGE_TIMEOUT`).
 
 ## Event mapping
 

package/bin/spor-hook.js

@@ -153,7 +153,7 @@ async function main() {
   // `enabled:false` / `mode:off` makes every hook a no-op (exit 0, no output)
   // so an unrelated side project doesn't pollute the shared graph neighborhood;
   // default-enabled, so a repo without config is byte-identical to before.
-  const cfg = u.useConfig({ cwd: payload.cwd || process.cwd() });
+  const cfg = u.useConfig({ cwd: payload.cwd || process.cwd(), host });
   if (cfg.warnings.length) {
     try {
       const log = u.makeLogger(path.join(u.graphHome(), "journal", "remote.log"), "config: ");

package/bin/spor.js

@@ -747,6 +747,191 @@ function gitBlobSha(buf) {
   return h.digest("hex");
 }
 
+// --- spor put-node: full validated node writes -----------------------------
+// The shell twin of MCP put_node / REST POST /v1/nodes: write a complete node
+// markdown file (frontmatter + body) through the same create/update collision
+// policy instead of dropping to raw REST from scripts and skills.
+function readPutNodeInput(input) {
+  if (!input || input === "-") {
+    try {
+      return { raw: fs.readFileSync(0, "utf8"), label: "stdin" };
+    } catch (e) {
+      return { error: `could not read stdin: ${e.message}` };
+    }
+  }
+  try {
+    return { raw: fs.readFileSync(input, "utf8"), label: input };
+  } catch (e) {
+    return { error: `could not read ${input}: ${e.message}` };
+  }
+}
+
+function parsePutNode(raw, label) {
+  const graphLib = require(path.join(ROOT, "lib", "graph.js"));
+  let first;
+  try {
+    first = graphLib.parseFrontmatter(raw, label || "incoming.md");
+  } catch (e) {
+    return { error: `invalid node: ${e.message}` };
+  }
+  if (!first.id) return { error: "invalid node: missing id" };
+  if (!NODE_ID_RE.test(first.id)) return { error: `bad node id '${first.id}' — expected kebab-case` };
+  try {
+    return { node: graphLib.parseFrontmatter(raw, `${first.id}.md`) };
+  } catch (e) {
+    return { error: `invalid node: ${e.message}` };
+  }
+}
+
+function normalizeIfExists(raw) {
+  const value = raw == null ? "error" : String(raw).trim().toLowerCase();
+  if (["error", "skip", "update"].includes(value)) return { ok: true, value };
+  return { ok: false, error: `--if-exists must be one of: error, skip, update` };
+}
+
+function renderPutNodeResult(res, json) {
+  if (json) {
+    out(JSON.stringify(res || {}, null, 2));
+    return;
+  }
+  const status = (res && res.status) || "ok";
+  const id = res && res.id ? res.id : "(unknown)";
+  const rev = res && res.revision ? ` @ ${res.revision}` : "";
+  out(status === "skipped" ? `put-node skipped: ${id}${rev}` : `put-node ${status}: ${id}${rev}`);
+  for (const w of (res && res.warnings) || []) err(`  warning: ${w}`);
+}
+
+function putNodeEntryError(res0, httpStatus, prefix = "put-node") {
+  const parts = [];
+  if (res0 && res0.message) parts.push(res0.message);
+  if (res0 && res0.code && !parts.includes(res0.code)) parts.push(res0.code);
+  if (res0 && Array.isArray(res0.details)) parts.push(...res0.details);
+  if (res0 && res0.revision) parts.push(`current revision: ${res0.revision}`);
+  return `${prefix} error ${httpStatus}${parts.length ? `: ${parts.join("; ")}` : ""}`;
+}
+
+function copyNodeFilesForValidation(srcNodes, dstNodes, targetId, raw) {
+  fs.mkdirSync(dstNodes, { recursive: true });
+  for (const ent of fs.readdirSync(srcNodes, { withFileTypes: true })) {
+    if (!ent.isFile() || !ent.name.endsWith(".md")) continue;
+    if (ent.name === `${targetId}.md`) continue;
+    fs.copyFileSync(path.join(srcNodes, ent.name), path.join(dstNodes, ent.name));
+  }
+  fs.writeFileSync(path.join(dstNodes, `${targetId}.md`), raw);
+}
+
+function validatePutNodeLocal(nodesDir, node, raw) {
+  const graphLib = require(path.join(ROOT, "lib", "graph.js"));
+  let g;
+  try {
+    g = graphLib.loadGraph(nodesDir);
+  } catch (e) {
+    return { error: `could not load graph: ${e.message}` };
+  }
+  const v = graphLib.validateNode(g, node);
+  if (!v.ok) return { error: `invalid node:\n  ${v.errors.join("\n  ")}` };
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "spor-put-node-"));
+  const tmpNodes = path.join(tmp, "nodes");
+  try {
+    copyNodeFilesForValidation(nodesDir, tmpNodes, node.id, raw);
+    const vg = graphLib.validateGraph(tmpNodes);
+    if (vg.errors && vg.errors.length) return { error: `invalid graph after put-node:\n  ${vg.errors.join("\n  ")}` };
+    return { ok: true, warnings: vg.warnings || [] };
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+async function cmdPutNode(cfg, { values, positionals }) {
+  const input = positionals[0] || "-";
+  const ifExists = normalizeIfExists(values["if-exists"]);
+  if (!ifExists.ok) {
+    err(ifExists.error);
+    return 1;
+  }
+  const policy = ifExists.value;
+  const revision = values.revision || null;
+  if (policy === "update" && !revision) {
+    err("put-node update requires --revision from 'spor get <id> --json'");
+    return 1;
+  }
+  if (policy !== "update" && revision) {
+    err("--revision is only valid with --if-exists update");
+    return 1;
+  }
+
+  const inputRes = readPutNodeInput(input);
+  if (inputRes.error) {
+    err(inputRes.error);
+    return 1;
+  }
+  const raw = inputRes.raw;
+  const parsed = parsePutNode(raw, inputRes.label);
+  if (parsed.error) {
+    err(parsed.error);
+    return 1;
+  }
+  const id = parsed.node.id;
+
+  if (cfg.mode() === "remote") {
+    const entry = { node: raw, if_exists: policy };
+    if (revision) entry.revision = revision;
+    const r = await remote.post(cfg, "/v1/nodes", { nodes: [entry] }, { timeoutMs: 15000 });
+    if (r.transport) {
+      err(`offline — could not reach server (${r.error})`);
+      return 1;
+    }
+    const res0 = r.json && r.json.results && r.json.results[0];
+    if (!(res0 && res0.ok)) {
+      const top = r.json && r.json.error;
+      if (top && !res0) err(`put-node error ${r.status}${top.message ? `: ${top.message}` : ""}`);
+      else err(putNodeEntryError(res0, r.status));
+      return 1;
+    }
+    renderPutNodeResult(res0, !!values.json);
+    return 0;
+  }
+
+  const nodesDir = cfg.nodesDir();
+  if (!fs.existsSync(nodesDir)) {
+    err(`no graph at ${nodesDir} — run 'spor init' first`);
+    return 1;
+  }
+  const file = path.join(nodesDir, `${id}.md`);
+  const exists = fs.existsSync(file);
+  if (policy === "error" && exists) {
+    err(`node already exists: ${id} (use --if-exists update with --revision, or --if-exists skip)`);
+    return 1;
+  }
+  if (policy === "skip" && exists) {
+    const res = { ok: true, status: "skipped", id, revision: gitBlobSha(fs.readFileSync(file)), warnings: [] };
+    renderPutNodeResult(res, !!values.json);
+    return 0;
+  }
+  if (policy === "update") {
+    if (!exists) {
+      err(`no such node: ${id}`);
+      return 1;
+    }
+    const current = gitBlobSha(fs.readFileSync(file));
+    if (current !== revision) {
+      err(`put-node conflict: stale revision for ${id}; current revision: ${current}`);
+      return 1;
+    }
+  }
+
+  const valid = validatePutNodeLocal(nodesDir, parsed.node, raw);
+  if (valid.error) {
+    err(valid.error);
+    return 1;
+  }
+  fs.writeFileSync(file, raw);
+  const res = { ok: true, status: exists ? "updated" : "created", id, revision: gitBlobSha(Buffer.from(raw)), warnings: valid.warnings || [] };
+  renderPutNodeResult(res, !!values.json);
+  return 0;
+}
+
 // --- spor blame / commits: commit-sha -> nodes reverse lookup ---------------
 // (task-spor-blame-commit-lookup-cli-verb) The shell verb over the commit->node
 // reverse index: which decisions/tasks/issues reference a git commit in their
@@ -4685,7 +4870,7 @@ function cmdLink(cfg, { positionals }) {
 const HOSTS = {
   claude: { kind: "claude", label: "Claude Code" },
   codex: {
-    kind: "hooks",
+    kind: "codex",
     label: "Codex CLI",
     src: ["adapters", "codex", "hooks.json"],
     user: [".codex", "hooks.json"],
@@ -4722,6 +4907,12 @@ function claudeCmd() {
   return process.env.SPOR_CLAUDE_CMD || "claude";
 }
 
+// The Codex CLI binary, overridable for tests. Codex owns plugin install state,
+// so all plugin shell-outs route through this seam instead of writing its cache.
+function codexCmd() {
+  return process.env.SPOR_CODEX_CMD || "codex";
+}
+
 function spawnPortableSync(cmd, args, opts = {}) {
   if (process.platform !== "win32" || opts.shell) return spawnSync(cmd, args, opts);
   const resolved = u.whichSync(cmd) || cmd;
@@ -5079,6 +5270,37 @@ function installClaude(scope, dryRun) {
   return 0;
 }
 
+// Codex CLI: install the repo as a Codex plugin via its marketplace commands,
+// then keep the hook manifest + backfill custom agent installed. The plugin
+// manifest intentionally does not carry hooks (Codex plugin validation rejects
+// that field), so both halves matter.
+function installCodex(scope, dryRun) {
+  const cmd = codexCmd();
+  const mpArgs = ["plugin", "marketplace", "add", ROOT];
+  const pluginArgs = ["plugin", "add", "spor@spor"];
+  if (dryRun) {
+    out(`would run: ${cmd} ${mpArgs.join(" ")}`);
+    out(`would run: ${cmd} ${pluginArgs.join(" ")}`);
+    return installHookHost(HOSTS.codex, scope, true);
+  }
+  if (cmd === "codex" && !hasCmd("codex")) {
+    err("codex CLI not on PATH — install Codex, then re-run 'spor install codex'.");
+    return 1;
+  }
+  const mp = spawnPortableSync(cmd, mpArgs, { encoding: "utf8" });
+  if (mp.status !== 0 && !/already|exists|known/i.test((mp.stderr || "") + (mp.stdout || ""))) {
+    err(`codex plugin marketplace add failed: ${(mp.stderr || mp.stdout || "").trim() || "unknown error"}`);
+    return 1;
+  }
+  const plugin = spawnPortableSync(cmd, pluginArgs, { stdio: "inherit" });
+  if (plugin.status !== 0) {
+    err(`codex plugin add failed (exit ${plugin.status == null ? "?" : plugin.status})`);
+    return 1;
+  }
+  out("installed spor@spor into Codex.");
+  return installHookHost(HOSTS.codex, scope, false);
+}
+
 // JSON-hook hosts (codex/cursor/copilot/gemini): render + merge into the target.
 function installHookHost(spec, scope, dryRun) {
   const target = targetPath(spec, scope);
@@ -5181,6 +5403,7 @@ async function cmdInstall(cfg, { values, positionals: pos }) {
     const spec = HOSTS[host];
     let r;
     if (spec.kind === "claude") r = installClaude(scope, dryRun);
+    else if (spec.kind === "codex") r = installCodex(scope, dryRun);
     else if (spec.kind === "plugin") r = installPluginHost(spec, scope, dryRun);
     else r = installHookHost(spec, scope, dryRun);
     if (r !== 0) rc = r;
@@ -5201,10 +5424,12 @@ async function cmdInstall(cfg, { values, positionals: pos }) {
 // (issue-spor-upgrade-no-plugin-refresh) An npm bump updates the package on disk
 // but NOT what an agent already loaded: Claude Code runs its OWN cached copy of
 // the plugin, so it keeps running stale skills/hooks until 'plugin update' swaps
-// the copy. The hook hosts (codex/cursor/copilot/gemini/opencode) reference the
-// package by absolute path, so they only go stale if the checkout MOVED — for
-// which re-running the idempotent install refreshes the path. This verb does
-// both in one step and tells the user to restart the session.
+// the copy. Codex also caches an installed plugin copy, while its hooks still
+// reference this checkout by absolute path. Re-running the idempotent install
+// refreshes Codex's marketplace/plugin cache and rewrites the hook path. The
+// other hook hosts reference the package by absolute path, so they only go stale
+// if the checkout MOVED. This verb does both in one step and tells the user to
+// restart the session.
 
 // Refresh Claude Code's loaded plugin (marketplace add to register/repoint the
 // source, then the shared marketplace+plugin update). Returns 0/1.
@@ -5281,6 +5506,7 @@ async function cmdUpgrade(cfg, { values, positionals: pos }) {
   for (const host of hosts) {
     let r;
     if (host === "claude") r = upgradeClaude(scope, dryRun);
+    else if (host === "codex") r = installCodex(scope, dryRun);
     else {
       // Re-running install refreshes the absolute __SPOR_ROOT__ path (a no-op
       // when the path is unchanged; repairs a moved checkout when it is not).
@@ -7777,6 +8003,34 @@ const COMMANDS = {
     examples: ["spor get dec-cc-zero-dep-client", "spor get dec-cc-zero-dep-client --json"],
     run: (cfg, p) => cmdGet(cfg, p),
   },
+  "put-node": {
+    group: "Graph", parse: "strict", args: "[<file>|-]",
+    summary: "write a full node markdown file (local validated write; remote: /v1/nodes)",
+    help:
+      "Create, skip, or update one complete node markdown file (frontmatter + body)\n" +
+      "through the same validated full-node write path as MCP put_node / REST\n" +
+      "POST /v1/nodes. With no file, or with '-', reads the node markdown from stdin.\n\n" +
+      "Collision policy is explicit: --if-exists error (default) rejects an existing\n" +
+      "id, --if-exists skip no-ops on collision, and --if-exists update replaces an\n" +
+      "existing node only when --revision matches the blob SHA you read earlier.\n" +
+      "Get that revision with 'spor get <id> --json'; re-read and retry on conflict.\n\n" +
+      "Remote mode sends one-entry batch put_node to /v1/nodes, so server attribution,\n" +
+      "schema transition gates, edge normalization, and validation all apply. Local\n" +
+      "mode writes nodes/<id>.md after parsing and validating the candidate against a\n" +
+      "temporary graph view, so a malformed full node never lands on disk.",
+    options: {
+      "if-exists": { type: "string", value: "error|skip|update", desc: "collision policy (default: error)" },
+      revision: { type: "string", value: "sha", desc: "required with --if-exists update; from 'spor get <id> --json'" },
+      json: { type: "boolean", desc: "machine-readable result envelope" },
+    },
+    examples: [
+      "spor put-node ./nodes/dec-x.md",
+      "spor get dec-x --json",
+      "spor put-node ./dec-x.md --if-exists update --revision <blob-sha>",
+      "cat ./task-new.md | spor put-node --if-exists error",
+    ],
+    run: (cfg, p) => cmdPutNode(cfg, p),
+  },
   blame: {
     group: "Graph", parse: "strict", args: "<sha> [--repo <slug>]", aliases: ["commits"],
     summary: "which nodes reference a commit (local: graph scan; remote: /v1/commits/<sha>)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "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",
@@ -27,6 +27,7 @@
   },
   "files": [
     ".claude-plugin/",
+    ".codex-plugin/",
     "lib/",
     "bin/",
     "scripts/engines/",

package/scripts/engines/distill.js

@@ -252,7 +252,7 @@ async function distill(input) {
   // runs async on SessionEnd, so it tolerates more than the nudge, but a wedged
   // CLI should still not hang the SessionEnd hook indefinitely).
   const timeoutMs = u.cfgNum("distill.timeoutMs", "DISTILL_TIMEOUT", 120000);
-  const distillCmd = u.cfgStr("distill.cmd", "DISTILL_CMD");
+  const distillCmd = u.cfgStr("distill.cmd", "DISTILL_CMD") || u.hostDefaultBackendCmd("distill");
   if (distillCmd) {
     backend = `cmd:${distillCmd}`;
     response = u.runBackendCmd(distillCmd, prompt, { timeoutMs });

package/scripts/engines/post-tool.js

@@ -181,7 +181,7 @@ async function nudge({ input, graph, slug, session, file, remote }) {
   // PostToolUse budget (nudge.timeoutMs / SPOR_NUDGE_TIMEOUT, default 30s — room
   // for a ~17s claude -p haiku cold boot, well under the host's 60s).
   const timeoutMs = u.cfgNum("nudge.timeoutMs", "NUDGE_TIMEOUT", 30000);
-  const nudgeCmd = u.cfgStr("nudge.cmd", "NUDGE_CMD");
+  const nudgeCmd = u.cfgStr("nudge.cmd", "NUDGE_CMD") || u.hostDefaultBackendCmd("nudge");
   if (nudgeCmd) {
     backend = `cmd:${nudgeCmd}`;
     response = u.runBackendCmd(nudgeCmd, prompt, { timeoutMs });

package/scripts/engines/util.js

@@ -11,6 +11,7 @@ const crypto = require("crypto");
 const { execFileSync, spawnSync, spawn } = require("child_process");
 
 const ROOT = path.resolve(__dirname, "..", "..");
+const CODEX_NUDGE_MODEL = "gpt-5.4-mini";
 
 const home = require(path.join(ROOT, "lib", "shell", "home.js"));
 // The harness vocabulary the capability probe emits — owned by the pure matcher
@@ -25,7 +26,9 @@ const { HARNESS_BINARIES, SPOR_MCP_NAME } = require(path.join(ROOT, "lib", "kern
 // falls back to the exact env dual-read it replaced, so those paths stay
 // byte-identical (norm-cc-byte-identical-refactor).
 let _config = null;
+let _host = null;
 function useConfig(opts) {
+  _host = opts && opts.host ? opts.host : null;
   _config = require(path.join(ROOT, "lib", "config.js")).loadConfig(opts);
   return _config;
 }
@@ -35,6 +38,7 @@ function useConfig(opts) {
 // (serverBase/bearer/graphHome) honors a file-config or --org tenant instead of
 // silently falling back to raw env.
 function setConfig(cfg) {
+  _host = null;
   _config = cfg;
   return cfg;
 }
@@ -42,6 +46,7 @@ function config() {
   return _config;
 }
 function clearConfig() {
+  _host = null;
   _config = null; // test hook
 }
 // Config-aware string read: the active cascade value, else env dual-read.
@@ -61,6 +66,12 @@ function cfgNum(keyPath, envName, fallback) {
   return Number.isFinite(n) ? n : fallback;
 }
 
+function hostDefaultBackendCmd(kind) {
+  if (_host === "codex" && kind === "nudge") return `codex exec --model ${CODEX_NUDGE_MODEL} -`;
+  if (_host === "codex" && kind === "distill") return "codex exec -";
+  return undefined;
+}
+
 function graphHome() {
   return _config ? _config.graphHome() : home.graphHome();
 }
@@ -1068,6 +1079,7 @@ module.exports = {
   clearConfig,
   cfgStr,
   cfgNum,
+  hostDefaultBackendCmd,
   jqNow,
   isoMs,
   isoSeconds,

package/skills/spor/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: spor
-description: The operating manual for Spor — a knowledge-graph tool your training does not cover. Load it before any Spor graph operation so you use the right CLI syntax, node and edge format, MCP tools, and REST API instead of rediscovering them: querying or searching the graph, reading or writing nodes, adding edges, capturing or deferring work, running spor CLI commands or Spor MCP tools, working in local vs remote mode, or defining a new node/edge type or schema. It also routes you to the right /spor action skill (defer, brief, next, correct, ask, backfill) for a specific operation, and explains the node/edge mental model when you need it. For FIRST-TIME setup — installing, creating an identity, joining a team graph, or "spor isn't doing anything" — use /spor:onboard instead. When unsure how to operate Spor, consult this before guessing.
+description: >
+  The operating manual for Spor — a knowledge-graph tool your training does not
+  cover. Load it before any Spor graph operation so you use the right CLI
+  syntax, node and edge format, MCP tools, and REST API instead of rediscovering
+  them: querying or searching the graph, reading or writing nodes, adding edges,
+  capturing or deferring work, running spor CLI commands or Spor MCP tools,
+  working in local vs remote mode, or defining a new node/edge type or schema.
+  It also routes you to the right /spor action skill (defer, brief, next,
+  correct, ask, backfill) for a specific operation, and explains the node/edge
+  mental model when you need it. For FIRST-TIME setup — installing, creating an
+  identity, joining a team graph, or "spor isn't doing anything" — use
+  /spor:onboard instead. When unsure how to operate Spor, consult this before
+  guessing.
 ---
 
 # Operate Spor
@@ -80,6 +92,9 @@ rest are mode-specific (`spor status` confirms which mode you're in):
 spor status                    # resolved mode, graph, project, identity, health
 spor next [--project <slug>]   # the ranked decision queue — "what's next"
 spor get <id>                  # one node by id
+spor put-node [<file>|-] --if-exists <error|skip|update> [--revision <sha>]
+                               # write a full node markdown file through validated put_node semantics;
+                               # use `spor get <id> --json` first and pass its revision for updates
 spor blame <sha> [--repo <s>]  # which nodes reference a git commit (alias: spor commits <sha>)
 spor history <id> [<sha>]      # a node's commit lineage (actor/when/what); <sha> = that revision's diff (local git log / GET /v1/nodes/<id>/history)
 spor schema [<type>]           # introspect the live registry (types/prefixes/weights/flags/gates,
@@ -161,6 +176,13 @@ A few of these have enough surface to be worth a sentence:
   read from git content history, never `updated_at`
   (dec-spor-git-derived-timestamps). `--project`/`--type`/`--weeks`/`--json`
   scope and shape it.
+- **`spor put-node`** is the shell twin of MCP `put_node` / REST `POST
+  /v1/nodes`: pass a complete node markdown file, or `-`/stdin. Default
+  `--if-exists error` rejects collisions; `--if-exists skip` no-ops on an
+  existing id; `--if-exists update` requires the `revision` from `spor get <id>
+  --json` so updates are optimistic-concurrency checked instead of last-writer
+  wins. Prefer `spor edge`/`spor set-status` for narrow mutations; use
+  `put-node` for full-node artifacts such as briefing versions or body edits.
 - **`spor compile`/`spor brief`** are mode-aware: local runs the in-repo
   compiler, remote dispatches to the server (this is what `/spor:brief` pulls).
   In local mode add `--project <repo-slug>` to scope to a repo — without it

package/skills/triage/SKILL.md

@@ -148,7 +148,43 @@ referenced prior-art artifact no longer trips this; a genuine non-resolving work
 product still does. The one thing triage must not do is leave the flag with no
 decision — it's a question addressed to you.
 
-## 5. Latent dependencies → record missing `blocks` edges
+## 5. Stale briefing findings → recompile the briefing
+
+Gardener findings about briefing freshness are not ordinary "close?" chores.
+If a finding says a `brief-*` node is stale, missing `derived-from`
+provenance, has an input-fingerprint mismatch, or has source-set drift, the
+repair is a new briefing version with current provenance. Do not merely
+acknowledge the finding or mark it handled while the stale briefing remains in
+place — that leaves session-start serving bad context.
+
+Treat the affected briefing as a build artifact and rebuild it:
+
+- Read the finding and the affected `brief-*` node (`spor get <finding-id>` and
+  `spor get <brief-id>`). Check its `compiled-for`, `derived-from`, and
+  `shaped-by` edges so you know what it was meant to brief and which
+  corrections must still apply.
+- Compile/research the current source set for the briefing target. For a
+  root/node briefing, run `spor brief <target-id>` for the human body; in a local
+  graph, `spor compile --root <target-id> --skeleton` can produce the updated
+  provenance skeleton. For a standing project briefing, compile the current
+  repo/product context and honor every standing correction named by `shaped-by`.
+- Write the affected `brief-*` node as the next `version:` with the refreshed
+  body, exact current `derived-from` inputs, preserved `compiled-for`, and any
+  relevant `shaped-by` correction edges. Use `spor put-node <file> --if-exists
+  update --revision <sha>` (or MCP `put_node`) so the update is validated and
+  optimistic-concurrency checked.
+- Verify the condition clears, or is ready for the gardener to auto-resolve:
+  re-read the briefing and, when appropriate, run `spor admin gardener --json`
+  to confirm the stale-briefing finding is no longer filed.
+- Only after the repaired briefing exists should the finding be considered
+  handled. If the finding still fires, keep it open and report what source or
+  correction is still unresolved.
+
+This is intentionally more work than closing a stale anchor: stale briefing
+findings affect future agent context, so triage must leave a fresh `brief-*`
+artifact behind.
+
+## 6. Latent dependencies → record missing `blocks` edges
 
 Find tasks that should carry a `blocks`/`blocked-by` edge but don't — work the
 queue surfaces as actionable that actually can't start until something else
@@ -174,7 +210,7 @@ Record a confirmed one as a `blocks` edge from the prerequisite to the dependent
 (mirroring how an issue records its block). The dependent then leaves the
 actionable queue until its blocker resolves — which is the point.
 
-## 6. Open questions → brief the lineage, then answer
+## 7. Open questions → brief the lineage, then answer
 
 This is where triage earns its keep: the queue's `questions` are decisions
 waiting on a human, and a bare list of them is useless — the reader can't answer
@@ -200,7 +236,7 @@ decide.** For each open question:
 (If `questions` is empty there's nothing to do here — but it's the step most
 often forgotten, so check it every pass.)
 
-## 7. Prioritise → unblockers first
+## 8. Prioritise → unblockers first
 
 Once you understand the dependency shape, set explicit `priority:` (`p1`/`p2`/
 `p3`) so the queue sequences correctly. The highest-leverage move is to **bump
@@ -224,7 +260,7 @@ genuinely ready work, start/claim it or let `front` decay; don't fake a resolver
 to undo it. (A bare reference no longer trips this —
 `issue-spor-queue-held-guard-false-positive-referenced-outcome`.)
 
-## 8. Present the outcome
+## 9. Present the outcome
 
 Talk to a human, in plain language. Lead with what you did and what to pick up
 next, one short reason each. Give a compact before/after (queue size, what
@@ -246,11 +282,11 @@ the REST endpoint against the resolved server; in Cowork use the MCP tool. See
 | Set priority | `spor priority <id> <p1\|p2\|p3\|clear>` (or `POST /v1/nodes/<id>/priority {priority}`) | `set_priority` |
 | Set status (merged/rejected/resolved/…) | `spor set-status <id> <status>` (or `POST /v1/nodes/<id>/status {status}`) | `set_status` |
 | Add edge (supersedes/blocks/relates-to/answers) | `spor edge <id> <type> <to>` (or `POST /v1/nodes/<id>/edges {type, to}`) | `add_edge` |
-| Edit a field (body) | `POST /v1/nodes {nodes:[{node, if_exists:"update", revision}]}` | `put_node` |
+| Edit a field (body) | `spor put-node <file> --if-exists update --revision <sha>` (or `POST /v1/nodes {nodes:[{node, if_exists:"update", revision}]}`) | `put_node` |
 | Compile a question's lineage | `spor brief <id>` | `query_graph root_id=<id>` |
 
 Edges normalize/flip/dedupe server-side, so write a `blocks` from the
-prerequisite's perspective and let it record the inverse. `put_node` needs
+prerequisite's perspective and let it record the inverse. `spor put-node` / `put_node` needs
 `if_exists:"update"` **and** the current `revision` — without the explicit mode
 it skips an existing node. Status flips run through the schema `transitions()`
 gate (and terminal closes through the completion-resolver gate), so a denied