@sporhq/spor 0.2.7 → 0.2.9

package/adapters/README.md

@@ -56,3 +56,35 @@ export SPOR_DISTILL_CMD="$HOME/repos/spor/scripts/distill-gemini.sh"
 
 The journal records the backend per call (`journal/llm-calls/`), so distill
 quality stays observable across backends through the same eval loop.
+
+## Capture-nudge backend
+
+The post-tool capture nudge (a Write/Edit of substantial prose to a `.md`
+outside the graph runs a classifier and, if it finds capturable facts, injects
+a capture-or-dismiss nudge) uses the **same backend contract** as the
+distiller — prompt on stdin, response on stdout — but a separate variable so
+you can point the two at different models:
+
+- `SPOR_NUDGE_CMD` — custom classifier command (defaults to `claude -p --model
+  haiku`, same as the distiller). Because the contract is identical,
+  `scripts/distill-gemini.sh` doubles as a nudge backend (it keys off
+  `SPOR_DISTILL_MODEL`, default `gemini-3.5-flash`):
+
+  ```sh
+  export SPOR_NUDGE_CMD="$HOME/repos/spor/scripts/distill-gemini.sh"
+  ```
+
+  This is the recommended latency fix: the nudge runs **synchronously** in the
+  tool loop, and Gemini Flash returns in ~2–7s versus ~17s for a `claude -p`
+  cold boot, with no quality regression (dec-cc-nudge-flash-latency).
+- `SPOR_NUDGE=0` — disable the nudge entirely.
+- `SPOR_NUDGE_MAX` — per-session ceiling on classifier calls (default 20),
+  bounding spend/latency in a docs-heavy session where many `.md` files each
+  classify to nothing. (A separate cap stops after 3 *fired* nudges.)
+- `SPOR_NUDGE_TIMEOUT` — milliseconds before a hung classifier is killed
+  (default 30000), so a wedged backend can't block the tool loop.
+
+(Legacy `SUBSTRATE_*` spellings are still read for all four.) The same
+`SPOR_DISTILLING=1` recursion guard is exported around the call, and the
+journal records each nudge call under `journal/llm-calls/` (source `nudge`)
+through the same eval loop as the distiller.

package/adapters/codex/README.md

@@ -27,11 +27,15 @@ is just a manifest over `bin/spor-hook`.
    # 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 -'
    ```
 
-   (Legacy `SUBSTRATE_*` names are still read.) Without `SPOR_DISTILL_CMD`
-   the distiller defaults to `claude -p --model haiku`, which is fine if the
-   claude CLI is installed.
+   (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`).
 
 ## Event mapping
 

package/adapters/copilot/README.md

@@ -20,8 +20,9 @@ sed "s|__SPOR_ROOT__|$SPOR_ROOT|g" \
 (Per-repo installs go in `.github/hooks/spor.json` — that is also the
 only location the Copilot cloud coding agent loads.) Environment is the
 usual set: `SPOR_SERVER`, `SPOR_TOKEN`, and `SPOR_DISTILL_CMD`
-(e.g. `copilot -p "$(cat)"`) if the claude CLI isn't installed; legacy
-`SUBSTRATE_*` names are still read.
+(e.g. `copilot -p "$(cat)"`) if the claude CLI isn't installed — set
+`SPOR_NUDGE_CMD` to the same value for the capture nudge, or `SPOR_NUDGE=0`
+to skip it; legacy `SUBSTRATE_*` names are still read.
 
 ## Event mapping
 

package/adapters/cursor/README.md

@@ -17,8 +17,9 @@ sed "s|__SPOR_ROOT__|$SPOR_ROOT|g" \
 (Or merge into an existing `~/.cursor/hooks.json` / project
 `.cursor/hooks.json`.) Environment is the usual set: `SPOR_SERVER`,
 `SPOR_TOKEN`, and `SPOR_DISTILL_CMD` if the claude CLI isn't installed
-(`cursor-agent -p` works: prompt on stdin, response on stdout); legacy
-`SUBSTRATE_*` names are still read.
+(`cursor-agent -p` works: prompt on stdin, response on stdout) — set
+`SPOR_NUDGE_CMD` to the same value for the capture nudge, or `SPOR_NUDGE=0`
+to skip it; legacy `SUBSTRATE_*` names are still read.
 
 ## Event mapping
 

package/adapters/gemini/README.md

@@ -31,6 +31,9 @@ export SPOR_SERVER=https://spor.example.com   # remote mode
 export SPOR_TOKEN=spor_pat_...
 # Distiller backend (prompt on stdin, response on stdout):
 export SPOR_DISTILL_CMD='gemini --model gemini-2.5-flash'
+# Capture-nudge backend (same contract; runs synchronously, so pick a fast
+# model). SPOR_NUDGE=0 disables it; see adapters/README.md for the bounds.
+export SPOR_NUDGE_CMD='gemini --model gemini-2.5-flash'
 ```
 
 (Legacy `SUBSTRATE_*` names are still read.)

package/adapters/opencode/README.md

@@ -24,6 +24,9 @@ export SPOR_TOKEN=spor_pat_...
 # Distiller backend (prompt on stdin -> response on stdout); without the
 # claude CLI installed, route through opencode itself:
 export SPOR_DISTILL_CMD='opencode run "$(cat)"'
+# Capture-nudge backend — same contract, runs synchronously, so prefer a fast
+# model. SPOR_NUDGE=0 disables it; see adapters/README.md for the bounds.
+export SPOR_NUDGE_CMD='opencode run "$(cat)"'
 ```
 
 ## Behavior mapping

package/bin/spor-hook

@@ -3,5 +3,29 @@
 # kept so existing hooks configs and adapter manifests that exec this path
 # keep working unchanged. Windows hosts invoke spor-hook.js via node
 # (or spor-hook.cmd) instead. Fail-open: no node, no output, exit 0.
-command -v node >/dev/null 2>&1 || exit 0
-exec node "$(dirname "$0")/spor-hook.js" "$@"
+if command -v node >/dev/null 2>&1; then
+  exec node "$(dirname "$0")/spor-hook.js" "$@"
+fi
+# No Node interpreter — the hook can do nothing (the client is zero-dep *Node*).
+# Stay fail-open (exit 0, no output, no latency on the working path above), but
+# drop a ONE-TIME greppable breadcrumb so the silence is diagnosable instead of
+# invisible (issue-spor-onboarding-no-node-silent-fail-open). Best-effort: every
+# step is guarded and we exit 0 regardless, so this can never break fail-open.
+# Resolve the graph home the way lib/shell/home.js does: $SPOR_HOME, then the
+# legacy $SUBSTRATE_HOME, else ~/.spor (or ~/.substrate if that legacy dir
+# exists). The breadcrumb is written at most once (guarded by its own marker).
+_spor_home="${SPOR_HOME:-${SUBSTRATE_HOME:-}}"
+if [ -z "$_spor_home" ]; then
+  if [ -d "$HOME/.spor" ]; then _spor_home="$HOME/.spor"
+  elif [ -d "$HOME/.substrate" ]; then _spor_home="$HOME/.substrate"
+  else _spor_home="$HOME/.spor"
+  fi
+fi
+_spor_warn="$_spor_home/journal/no-node.warn"
+if [ -n "$HOME" ] && [ ! -f "$_spor_warn" ]; then
+  if mkdir -p "$_spor_home/journal" 2>/dev/null; then
+    printf '%s spor-hook: node not found on PATH — every hook is a silent no-op. Spor needs a Node interpreter (see package.json engines; `spor status` reports the floor). Install Node, then restart your session.\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo now)" >"$_spor_warn" 2>/dev/null || true
+  fi
+fi
+exit 0

package/bin/spor-hook.js

@@ -15,6 +15,7 @@
 //   spor-hook post-tool      [--host ...]
 //   spor-hook distill        [--host ...] [--debounce SECONDS]
 //   spor-hook agents-md      [--cwd DIR]    # AGENTS.md floor; no stdin
+//   spor-hook doctor         [--cwd DIR]    # client health report; no stdin
 //
 // Fail-open contract (dec-cc-fail-open-hooks): any failure exits 0 with no
 // output — a Spor problem never costs the user their session.
@@ -114,6 +115,23 @@ async function main() {
     return;
   }
 
+  // `spor-hook doctor` (task-cc-client-hook-operability-diagnostics piece 3):
+  // an operator-run diagnostic, not a host hook — it takes no stdin and prints a
+  // human-readable health report. It runs even when the plugin is disabled for
+  // the repo (a disabled plugin is exactly what you'd want doctor to tell you).
+  // Write the report with fs.writeSync(1) so the full body flushes before the
+  // crash handler's process.exit(0) can truncate a piped stdout.
+  if (event === "doctor") {
+    const { doctor } = require("../scripts/engines/doctor");
+    let dCwd = process.cwd();
+    const ci = args.indexOf("--cwd");
+    if (ci >= 0 && args[ci + 1]) dCwd = args[ci + 1];
+    u.useConfig({ cwd: dCwd });
+    const report = await doctor();
+    fs.writeSync(1, report);
+    return;
+  }
+
   if (!(event in ENGINES)) {
     process.stderr.write(`spor-hook: unknown event '${event}'\n`);
     return;