contextspin 0.6.3 → 0.7.0

package/README.md

@@ -14,39 +14,35 @@ ContextSpin is a **compositor and renderer, not a data layer.** It has no API cl
 - **CLI tools** already installed and authenticated on your machine (`gh`, `kubectl`, `aws`, your own scripts…)
 - **HTTP endpoints** you can already reach (internal dashboards, status APIs)
 
-ContextSpin polls those sources on a schedule, formats whatever they return into short one-line snippets, and injects the most relevant one into the Claude Code status bar. If a piece of data isn't reachable by a tool you already have, ContextSpin cannot show it — by design. The only runtime dependency is [`commander`](https://www.npmjs.com/package/commander).
+ContextSpin formats whatever your sources return into short one-line snippets and shows the most relevant one in the Claude Code status bar. If a piece of data isn't reachable by a tool you already have, ContextSpin cannot show it — by design. The only runtime dependency is [`commander`](https://www.npmjs.com/package/commander).
 
-## Architecture
+## Architecture (daemonless)
+
+There is **no background daemon by default**. The statusline render is the engine: it serves the cached snippet instantly, and only when a source is due does it kick off a detached one-shot refresh (lock-guarded so frequent renders never overlap). Nothing runs when you're not in Claude Code — idle cost is zero.
 
 ```
-  ┌─────────────────────────────────────────────────────────┐
-  │  SOURCES  (things you already have)                       │
-  │                                                           │
-  │   mcp   ──►  stdio MCP servers from ~/.claude.json        │
-  │   cli   ──►  shell commands (gh, kubectl, scripts...)     │
-  │   http  ──►  HTTP/JSON endpoints you can reach            │
-  └───────────────────────────┬─────────────────────────────┘
-                              │  poll on per-source cooldown
+  Claude Code draws the status bar (every refreshInterval)
+                              │
                               ▼
   ┌─────────────────────────────────────────────────────────┐
-  │  POLLING DAEMON  (detached background process)            │
-  │   • runs each source, applies filter + format             │
-  │   • merges / dedups / prioritizes snippets                │
-  │   • writes  ~/.contextspin-cache.json   (atomic)          │
+  │  RENDER  ~/.contextspin/statusline.mjs                    │
+  │   1. read ~/.contextspin-cache.json                       │
+  │   2. print one snippet NOW (stale is fine) ───────────────┼──► status bar
+  │   3. if a source is past its cooldown AND no refresh is    │
+  │      in flight → spawn a detached one-shot refresh:        │
   └───────────────────────────┬─────────────────────────────┘
-                              │  read cache
+                              │  (background, non-blocking)
                               ▼
   ┌─────────────────────────────────────────────────────────┐
-  │  INJECTOR  (statusline — non-destructive, composed)       │
-  │   statusline  ──►  ~/.contextspin/statusline.sh           │
-  │                    composed into ~/.claude/settings.json   │
-  │   patcher     ──►  rewrites spinner words (EXPERIMENTAL)   │
-  └───────────────────────────┬─────────────────────────────┘
-                              │
-                              ▼
-            Claude Code status bar shows one snippet
+  │  REFRESH  (one-shot)  src/refresh-entry.js               │
+  │   • runs each DUE source (cli / http / mcp), formats      │
+  │   • merges / dedups / prioritizes, records lastRun        │
+  │   • writes ~/.contextspin-cache.json  (atomic)           │
+  └─────────────────────────────────────────────────────────┘
 ```
 
+This is *stale-while-revalidate*: the bar is always fast (it never waits on the network), and freshness catches up in the background. A legacy always-on **daemon** is still available behind `injection.daemonless: false` — useful only if you poll stdio **MCP** sources, where a persistent connection beats per-render handshakes.
+
 The daemon and the injector are decoupled by the cache file: the daemon writes snippets, the injector reads them. Each runs on its own clock.
 
 ## Install
@@ -68,11 +64,11 @@ Prefer to do it yourself? `npx contextspin install` does the same thing. To remo
 
 ```bash
 npx contextspin setup     # create a config (add --yes to skip prompts)
-npx contextspin start     # start the background polling daemon
 npx contextspin inject    # wire snippets into the status bar
+# that's it — the render refreshes itself; no daemon to start
 ```
 
-Running `npx contextspin` with **no subcommand** is a shortcut: if no config exists it runs `setup`, otherwise it runs `start` followed by `inject` using the mode from your config.
+`npx contextspin install` is the recommended path (it also wires the self-healing SessionStart hook). Running `npx contextspin` with **no subcommand** sets up if unconfigured, otherwise wires + refreshes.
 
 </details>
 
@@ -187,6 +183,7 @@ ContextSpin reads one JSON file: `~/.contextspin.json` (override with the `CONTE
 | `injection.refresh` | number | seconds | `30` | Daemon poll interval and status-line refresh interval (seconds). |
 | `injection.maxVisible` | number | count | `5` | Global cap on snippets held in the cache. |
 | `injection.style` | boolean | — | `true` | Render the line in a styled box (cyan bars + italic). Set `false` for plain text. |
+| `injection.daemonless` | boolean | — | `true` | Render self-refreshes (stale-while-revalidate), no background process. Set `false` for the legacy always-on daemon. |
 | `snippets.deduplication` | boolean | — | `true` | Drop snippets with duplicate text when merging. |
 | `snippets.cooldownAfterShown` | number | count | `3` | A snippet stops being eligible once shown this many times. |
 | `snippets.priorityOrder` | string[] | source labels | `[]` | Earlier labels sort first (case-insensitive); unlisted sort last. |
@@ -229,15 +226,14 @@ Key facts:
 
 Restore the originals with `contextspin uninject --mode patcher` (or `inject --mode both` / `uninject --mode both` to do both at once). A backup with the suffix `.contextspin.backup` is created before any install is touched.
 
-## Daemon and cache
+## Refresh and cache
 
-`contextspin start` spawns a **detached** background process (the daemon). It writes its PID to `~/.contextspin/daemon.pid` and logs to `~/.contextspin/daemon.log`. The loop:
+By default there is **no background process**. Each time the status bar draws, the render:
 
-1. For each source whose `cooldown` has elapsed, runs it, applies the filter, formats records, and slices to `maxSnippets`.
-2. Merges the fresh snippets into the existing set: preserves `shownCount` for matching text, optionally dedups, sorts by `priorityOrder` then by recency, and caps to `injection.maxVisible`.
-3. Atomically writes the cache, then sleeps `injection.refresh` seconds.
+1. Prints the current cached snippet immediately (stale is fine).
+2. If any source is past its `cooldown` and no refresh is already in flight (a lock at `~/.contextspin/refresh.lock`, TTL 60s), spawns a **detached one-shot refresh**. That refresh runs only the due sources, merges into the existing set (preserves `shownCount` for matching text, optionally dedups, sorts by `priorityOrder` then recency, caps to `injection.maxVisible`), records per-source `lastRun`, and atomically writes the cache.
 
-`stop` / `restart` manage the process; `status` reports whether it's running and lists the current snippets.
+Set `injection.daemonless: false` to use the **legacy daemon** instead: `contextspin start` spawns a detached background process (PID at `~/.contextspin/daemon.pid`, logs at `~/.contextspin/daemon.log`) that polls on `injection.refresh` and writes the same cache. Use this only if you poll stdio MCP sources.
 
 ### Cache file format (`~/.contextspin-cache.json`)
 
@@ -252,27 +248,26 @@ Restore the originals with `contextspin uninject --mode patcher` (or `inject --m
       "fetchedAt": "2026-06-17T09:00:00.000Z",
       "shownCount": 0
     }
-  ]
+  ],
+  "meta": { "lastRun": { "2": 1781860451773 } }
 }
 ```
 
-`shownCount` is incremented by the status-line renderer each time a snippet is displayed; once it reaches `cooldownAfterShown` the snippet is no longer shown.
+`shownCount` is incremented by the render each time a snippet is displayed; once it reaches `cooldownAfterShown` the snippet is no longer shown. `meta.lastRun` maps `sourceId → last poll (epoch ms)` so the daemonless refresh honors per-source cooldowns across runs.
 
 ## CLI commands
 
 | Command | What it does |
 |---------|--------------|
-| `contextspin install` | **One-shot install:** wire a self-healing SessionStart hook, create the config, wire the statusline, and start the daemon. (This is what the curl script runs.) |
-| `contextspin uninstall` | **Full teardown:** remove the hook, restore your prior statusline in **every** scope it wired, and stop the daemon. |
+| `contextspin install` | **One-shot install:** wire a self-healing SessionStart hook, create the config, and wire the statusline. (This is what the curl script runs.) |
+| `contextspin uninstall` | **Full teardown:** remove the hook, restore your prior statusline in **every** scope it wired, and stop any daemon. |
 | `contextspin setup [--yes]` | Create `~/.contextspin.json` (interactive, or a detected config with `--yes` / non-TTY). |
-| `contextspin start` | Start the detached polling daemon. |
-| `contextspin stop` | Stop the daemon. |
-| `contextspin restart` | Stop then start. |
-| `contextspin status` | Show daemon state and the current cached snippets (source, age, shown count). |
-| `contextspin ensure` | Idempotent: create config + wire statusline + start daemon (run by the SessionStart hook each session). |
+| `contextspin status` | Show the engine, and the current cached snippets (source, age, shown count). |
+| `contextspin ensure` | Idempotent: create config + wire statusline (run by the SessionStart hook each session). |
 | `contextspin inject [--mode <m>]` | Install just the injector. `<m>` overrides `injection.mode` (`statusline` / `patcher` / `both`). |
 | `contextspin uninject [--mode <m>]` | Reverse just the injector. |
-| `contextspin` *(no subcommand)* | `setup` if unconfigured, otherwise `start` then `inject`. |
+| `contextspin start` / `stop` / `restart` | Manage the **legacy daemon** (only when `injection.daemonless: false`). |
+| `contextspin` *(no subcommand)* | `setup` if unconfigured, otherwise wire + refresh. |
 
 ## High-impact snippets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextspin",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Replace Claude Code spinner/statusline text with live org context (meetings, Slack, CI, incidents, PRs) aggregated from your existing MCP servers, CLIs, and HTTP endpoints.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -13,6 +13,7 @@ import {
   CONFIG_PATH,
   STATUSLINE_SH,
   CLAUDE_SETTINGS_PATH,
+  DEFAULT_DAEMONLESS,
   configExists,
   loadConfig,
   saveConfig,
@@ -24,12 +25,14 @@ import {
   stopDaemon,
   isDaemonRunning,
   readCache,
+  runRefreshOnce,
 } from './daemon.js';
 import {
   installStatusline,
   uninstallStatusline,
   uninstallAllStatuslines,
 } from './inject/statusline.js';
+import { addSessionStartHook, removeSessionStartHook } from './inject/hook.js';
 import { installPatcher, restorePatcher } from './inject/patcher.js';
 import { detectSources } from './detect.js';
 
@@ -263,7 +266,20 @@ async function runEnsure() {
       if (!wasOurs) did.push('wired statusline');
     }
 
-    if (!isDaemonRunning().running) {
+    // DAEMONLESS (default): the render revalidates itself, so no background
+    // process is started. Only the legacy daemon engine needs a daemon.
+    const daemonless =
+      config && config.injection && typeof config.injection.daemonless === 'boolean'
+        ? config.injection.daemonless
+        : DEFAULT_DAEMONLESS;
+    if (daemonless) {
+      // Upgrading from the daemon engine? Stop the now-redundant background
+      // process so it doesn't linger after the switch.
+      if (isDaemonRunning().running) {
+        await stopDaemon();
+        did.push('stopped legacy daemon');
+      }
+    } else if (!isDaemonRunning().running) {
       startDaemonDetached();
       did.push('started daemon');
     }
@@ -325,16 +341,45 @@ async function runRestart() {
   await runStart();
 }
 
+/**
+ * Force a one-shot refresh now (the daemonless "refresh now"): polls every due
+ * source and rewrites the cache. Works regardless of engine.
+ * @returns {Promise<void>}
+ */
+async function runRefresh() {
+  if (!configExists()) {
+    printSetupHint();
+    process.exit(1);
+    return;
+  }
+  await runRefreshOnce();
+  console.log('ContextSpin: refreshed.');
+}
+
 /**
  * Print the daemon running state plus the current cache contents.
  * @returns {Promise<void>}
  */
 async function runStatus() {
+  // Report the active engine. In daemonless mode (the default) there is no
+  // background process by design — the render revalidates the cache itself.
+  let daemonless = DEFAULT_DAEMONLESS;
+  try {
+    const cfg = await loadConfig();
+    if (cfg && cfg.injection && typeof cfg.injection.daemonless === 'boolean') {
+      daemonless = cfg.injection.daemonless;
+    }
+  } catch {
+    // no/invalid config -> assume the default engine
+  }
+
   const { running, pid } = isDaemonRunning();
-  if (running) {
-    console.log(`Daemon: running (pid ${pid})`);
+  if (daemonless) {
+    console.log('Engine: daemonless (statusline self-refreshes; no background process)');
+  } else if (running) {
+    console.log(`Engine: daemon (running, pid ${pid})`);
   } else {
-    console.log('Daemon: stopped');
+    console.log('Engine: daemon (stopped)');
   }
 
   const cache = await readCache();
@@ -476,106 +521,6 @@ async function runUninject(opts = {}) {
   }
 }
 
-/**
- * The SessionStart hook command the `install` flow wires into the user settings
- * so ContextSpin self-heals every session (the curl install replicates what the
- * Claude Code plugin's hook does, without the marketplace).
- *
- * The hook is pinned to the EXACT version doing the install (never `@latest` or a
- * range), so a future release never runs on the user's machine without them
- * deliberately re-installing. Runs from a neutral dir so npx never resolves a
- * confused local package (Exit 127).
- * @returns {string}
- */
-function sessionStartHookCmd() {
-  return `cd /tmp && npx --yes contextspin@${readVersion()} ensure >/dev/null 2>&1; exit 0`;
-}
-
-/**
- * Read+parse a JSON file, returning a fallback on any read/parse error.
- * @param {string} filePath
- * @param {*} fallback
- * @returns {*}
- */
-function readJsonSafeSync(filePath, fallback) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return fallback;
-  }
-}
-
-/**
- * Whether a SessionStart entry already runs ContextSpin (so install is idempotent).
- * @param {*} entry
- * @returns {boolean}
- */
-function entryRunsContextspin(entry) {
-  return !!(
-    entry &&
-    Array.isArray(entry.hooks) &&
-    entry.hooks.some(
-      (h) => h && typeof h.command === 'string' && h.command.includes('contextspin'),
-    )
-  );
-}
-
-/**
- * Wire a ContextSpin SessionStart hook into the user ~/.claude/settings.json so
- * the daemon + statusline self-heal every session. JSON-merge (preserves every
- * other key and any existing hooks). Idempotent.
- * @returns {boolean} true if the hook was added (false if already present).
- */
-function addSessionStartHook() {
-  fs.mkdirSync(path.dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
-  const settings = readJsonSafeSync(CLAUDE_SETTINGS_PATH, {});
-  const obj = settings && typeof settings === 'object' ? settings : {};
-  obj.hooks = obj.hooks && typeof obj.hooks === 'object' ? obj.hooks : {};
-  const arr = Array.isArray(obj.hooks.SessionStart) ? obj.hooks.SessionStart : [];
-
-  const desired = sessionStartHookCmd();
-  const existing = arr.find(entryRunsContextspin);
-  const alreadyCurrent =
-    existing &&
-    Array.isArray(existing.hooks) &&
-    existing.hooks.some((h) => h && h.command === desired);
-  // Already exactly this command (same pinned version) — nothing to do.
-  if (alreadyCurrent) return false;
-
-  // Upsert: drop any prior ContextSpin entry (e.g. an older pinned version) and
-  // add the current one, so re-installing a newer version re-pins cleanly.
-  const others = arr.filter((e) => !entryRunsContextspin(e));
-  others.push({
-    matcher: '',
-    hooks: [{ type: 'command', command: desired, timeout: 15 }],
-  });
-  obj.hooks.SessionStart = others;
-  fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(obj, null, 2));
-  return true;
-}
-
-/**
- * Remove any ContextSpin SessionStart hook from the user settings (best-effort,
- * JSON-merge). Prunes empty containers.
- * @returns {boolean} true if a hook was removed.
- */
-function removeSessionStartHook() {
-  const settings = readJsonSafeSync(CLAUDE_SETTINGS_PATH, null);
-  if (!settings || typeof settings !== 'object' || !settings.hooks) return false;
-  const arr = Array.isArray(settings.hooks.SessionStart)
-    ? settings.hooks.SessionStart
-    : [];
-  const kept = arr.filter((e) => !entryRunsContextspin(e));
-  if (kept.length === arr.length) return false;
-  if (kept.length > 0) settings.hooks.SessionStart = kept;
-  else delete settings.hooks.SessionStart;
-  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
-    delete settings.hooks;
-  }
-  fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2));
-  return true;
-}
-
 /**
  * One-shot install (the `curl | bash` entrypoint): wire the SessionStart hook so
  * ContextSpin self-heals each session, then run ensure (config + statusline +
@@ -583,7 +528,7 @@ function removeSessionStartHook() {
  * @returns {Promise<void>}
  */
 async function runInstall() {
-  const addedHook = addSessionStartHook();
+  const addedHook = addSessionStartHook(readVersion());
   await runEnsure();
   console.log('');
   console.log(
@@ -689,9 +634,14 @@ function buildProgram() {
     .description('Restart the background daemon')
     .action(action(async () => runRestart()));
 
+  program
+    .command('refresh')
+    .description('Force a one-shot refresh of all due sources now')
+    .action(action(async () => runRefresh()));
+
   program
     .command('status')
-    .description('Show daemon state and cached snippets')
+    .description('Show the engine and cached snippets')
     .action(action(async () => runStatus()));
 
   program

package/src/config.js

@@ -31,11 +31,28 @@ export const PID_PATH = path.join(STATE_DIR, "daemon.pid");
 /** Path to the daemon log file. */
 export const LOG_PATH = path.join(STATE_DIR, "daemon.log");
 
+/**
+ * Lock file for the DAEMONLESS engine: the render script triggers a detached
+ * one-shot refresh when a source is due, guarded by this lock so frequent
+ * renders never spawn overlapping refreshes. Holds a timestamp; stale locks
+ * (older than REFRESH_LOCK_TTL_MS) are ignored.
+ */
+export const REFRESH_LOCK_PATH = path.join(STATE_DIR, "refresh.lock");
+
+/** A refresh lock older than this (ms) is considered stale and overridable. */
+export const REFRESH_LOCK_TTL_MS = 60_000;
+
 /** Path to the generated statusline bash wrapper. */
 export const STATUSLINE_SH = path.join(STATE_DIR, "statusline.sh");
 
-/** Path to the generated statusline Node render script. */
-export const STATUSLINE_JS = path.join(STATE_DIR, "statusline-render.js");
+/**
+ * Path to the generated statusline Node render script. Uses the `.mjs` extension
+ * so Node treats it as ESM regardless of version — the script lives in STATE_DIR
+ * (no package.json), and Node 18 has no automatic ESM detection, so a plain
+ * `.js` would fail to parse its `import` statements ("Cannot use import statement
+ * outside a module").
+ */
+export const STATUSLINE_JS = path.join(STATE_DIR, "statusline-render.mjs");
 
 /**
  * Path to the recorded prior statusLine commands (captured when we wrap an
@@ -131,6 +148,15 @@ export const DEFAULTS = {
   snippets: { deduplication: true, cooldownAfterShown: 3, priorityOrder: [] },
 };
 
+/**
+ * Whether the DAEMONLESS engine is the default. When true, no background daemon
+ * runs: the statusline render does stale-while-revalidate — it serves the cached
+ * snippet instantly and triggers a detached one-shot refresh when a source is
+ * due. Idle cost is then zero (nothing runs unless the bar is being drawn).
+ * Honored unless a config explicitly sets `injection.daemonless`.
+ */
+export const DEFAULT_DAEMONLESS = true;
+
 /** Per-source defaults applied when a field is omitted. */
 export const SOURCE_DEFAULTS = { cooldown: 300, maxSnippets: 2 };
 

package/src/daemon.js

@@ -25,13 +25,16 @@ export async function readCache() {
   try {
     const raw = await fsp.readFile(CACHE_PATH, "utf8");
     const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object") return { updatedAt: null, snippets: [] };
+    if (!parsed || typeof parsed !== "object") return { updatedAt: null, snippets: [], meta: {} };
     return {
       updatedAt: parsed.updatedAt ?? null,
       snippets: Array.isArray(parsed.snippets) ? parsed.snippets : [],
+      // `meta.lastRun` maps sourceId -> last poll epoch ms, so the daemonless
+      // one-shot refresh can honor per-source cooldowns across separate runs.
+      meta: parsed.meta && typeof parsed.meta === "object" ? parsed.meta : {},
     };
   } catch {
-    return { updatedAt: null, snippets: [] };
+    return { updatedAt: null, snippets: [], meta: {} };
   }
 }
 
@@ -159,6 +162,53 @@ export async function pollOnce(config, runtime) {
   return runtime.snippets;
 }
 
+/**
+ * Run ONE refresh pass for the daemonless engine and exit. Unlike the daemon
+ * loop this keeps no in-memory state: it reads the cache (snippets +
+ * meta.lastRun), polls only the sources whose cooldown has elapsed, keeps the
+ * existing snippets for sources that are not yet due, merges, and writes the
+ * cache back (including the updated per-source lastRun). Errors for one source
+ * never drop the others' cached snippets.
+ *
+ * @param {{configPath?: string}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function runRefreshOnce(opts = {}) {
+  const config = await loadConfig(opts.configPath);
+  const cache = await readCache();
+  const lastRun = cache.meta && typeof cache.meta.lastRun === "object" ? { ...cache.meta.lastRun } : {};
+  const now = Date.now();
+
+  // Group existing cached snippets by source so not-yet-due sources persist.
+  const bySource = {};
+  for (const s of cache.snippets) {
+    if (!s) continue;
+    (bySource[s.sourceId] ||= []).push(s);
+  }
+
+  for (const source of config.sources) {
+    const last = lastRun[source.id] || 0;
+    if (now - last >= source.cooldown * 1000) {
+      try {
+        bySource[source.id] = await runSource(source, {});
+        lastRun[source.id] = Date.now();
+      } catch (err) {
+        console.error(`source "${source.label}" (#${source.id}) failed: ${err.message}`);
+        // keep whatever was cached for this source
+      }
+    }
+  }
+
+  const flattened = [];
+  for (const source of config.sources) {
+    const bucket = bySource[source.id];
+    if (Array.isArray(bucket)) flattened.push(...bucket);
+  }
+
+  const snippets = mergeSnippets(cache.snippets, flattened, config);
+  await writeCache({ updatedAt: nowISO(), snippets, meta: { lastRun } });
+}
+
 /**
  * Run the daemon poll loop. Writes the PID file, installs signal handlers, and
  * loops: pollOnce -> writeCache -> wait config.injection.refresh seconds.

package/src/inject/hook.js

@@ -0,0 +1,105 @@
+// src/inject/hook.js — manage ContextSpin's SessionStart hook in the user
+// ~/.claude/settings.json. Used by `contextspin install` / `uninstall` (the curl
+// flow) so ContextSpin self-heals every session without the plugin/marketplace.
+
+import fs from "node:fs";
+import path from "node:path";
+import { CLAUDE_SETTINGS_PATH } from "../config.js";
+
+/**
+ * Read+parse a JSON file, returning a fallback on any read/parse error.
+ * @param {string} filePath
+ * @param {*} fallback
+ * @returns {*}
+ */
+function readJsonSafeSync(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Build the SessionStart hook command, pinned to an EXACT version (never
+ * `@latest` or a range) so a future release never runs without a deliberate
+ * re-install. Runs from a neutral dir so npx can't resolve a confused local
+ * package (Exit 127).
+ * @param {string} version - The exact package version to pin (e.g. "0.6.3").
+ * @returns {string}
+ */
+export function sessionStartHookCmd(version) {
+  return `cd /tmp && npx --yes contextspin@${version} ensure >/dev/null 2>&1; exit 0`;
+}
+
+/**
+ * Whether a SessionStart entry already runs ContextSpin (any version).
+ * @param {*} entry
+ * @returns {boolean}
+ */
+export function entryRunsContextspin(entry) {
+  return !!(
+    entry &&
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some(
+      (h) => h && typeof h.command === "string" && h.command.includes("contextspin"),
+    )
+  );
+}
+
+/**
+ * Upsert the ContextSpin SessionStart hook into the user settings, pinned to
+ * `version`. JSON-merge (preserves every other key and any non-ours hooks).
+ * Drops any prior ContextSpin entry (e.g. an older pinned version) so
+ * re-installing a newer version re-pins cleanly. Idempotent when already current.
+ * @param {string} version
+ * @param {string} [settingsPath=CLAUDE_SETTINGS_PATH]
+ * @returns {boolean} true if the file was changed (added or re-pinned).
+ */
+export function addSessionStartHook(version, settingsPath = CLAUDE_SETTINGS_PATH) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  const settings = readJsonSafeSync(settingsPath, {});
+  const obj = settings && typeof settings === "object" ? settings : {};
+  obj.hooks = obj.hooks && typeof obj.hooks === "object" ? obj.hooks : {};
+  const arr = Array.isArray(obj.hooks.SessionStart) ? obj.hooks.SessionStart : [];
+
+  const desired = sessionStartHookCmd(version);
+  const existing = arr.find(entryRunsContextspin);
+  const alreadyCurrent =
+    existing &&
+    Array.isArray(existing.hooks) &&
+    existing.hooks.some((h) => h && h.command === desired);
+  if (alreadyCurrent) return false;
+
+  const others = arr.filter((e) => !entryRunsContextspin(e));
+  others.push({
+    matcher: "",
+    hooks: [{ type: "command", command: desired, timeout: 15 }],
+  });
+  obj.hooks.SessionStart = others;
+  fs.writeFileSync(settingsPath, JSON.stringify(obj, null, 2));
+  return true;
+}
+
+/**
+ * Remove any ContextSpin SessionStart hook from the user settings (JSON-merge,
+ * best-effort). Prunes empty containers.
+ * @param {string} [settingsPath=CLAUDE_SETTINGS_PATH]
+ * @returns {boolean} true if a hook was removed.
+ */
+export function removeSessionStartHook(settingsPath = CLAUDE_SETTINGS_PATH) {
+  const settings = readJsonSafeSync(settingsPath, null);
+  if (!settings || typeof settings !== "object" || !settings.hooks) return false;
+  const arr = Array.isArray(settings.hooks.SessionStart)
+    ? settings.hooks.SessionStart
+    : [];
+  const kept = arr.filter((e) => !entryRunsContextspin(e));
+  if (kept.length === arr.length) return false;
+  if (kept.length > 0) settings.hooks.SessionStart = kept;
+  else delete settings.hooks.SessionStart;
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  return true;
+}

package/src/inject/statusline.js

@@ -34,7 +34,11 @@ import {
   CLAUDE_SETTINGS_PATH,
   DEFAULT_SNIPPETS,
   WIRED_STATUSLINES_PATH,
+  REFRESH_LOCK_PATH,
+  REFRESH_LOCK_TTL_MS,
+  DEFAULT_DAEMONLESS,
 } from "../config.js";
+import { fileURLToPath } from "node:url";
 
 /**
  * Build the source text of the Node ESM render script that Claude Code invokes
@@ -70,12 +74,16 @@ import {
  * @param {string} prevPath - Absolute path to the prev-statusline MAP JSON file.
  * @returns {string} The ESM source of the render script.
  */
-function buildRenderScript(cachePath, configPath, prevPath) {
+function buildRenderScript(cachePath, configPath, prevPath, opts = {}) {
   const CACHE = JSON.stringify(cachePath);
   const CONFIG = JSON.stringify(configPath);
   const PREV = JSON.stringify(prevPath);
   const DEFAULTS = JSON.stringify(DEFAULT_SNIPPETS);
-  return `// contextspin statusline-render.js (generated) — composes any prior
+  const DAEMONLESS = opts.daemonless ? "true" : "false";
+  const REFRESH_ENTRY = JSON.stringify(opts.refreshEntry || "");
+  const LOCK = JSON.stringify(opts.lockPath || "");
+  const LOCK_TTL = String(typeof opts.lockTtlMs === "number" ? opts.lockTtlMs : 60000);
+  return `// contextspin statusline-render.mjs (generated) — composes any prior
 // statusline (looked up per-project) with one ContextSpin snippet line. MUST
 // always exit 0 and never lose the prior statusline's output, so the user's
 // status bar never breaks.
@@ -87,6 +95,14 @@ const CONFIG_PATH = ${CONFIG};
 const PREV_STATUSLINE_PATH = ${PREV};
 const DEFAULT_SNIPPETS = ${DEFAULTS};
 
+// DAEMONLESS engine: when true, this render does stale-while-revalidate — it
+// serves the cached snippet instantly and triggers a detached one-shot refresh
+// when a source is due (lock-guarded so frequent renders never overlap).
+const DAEMONLESS = ${DAEMONLESS};
+const REFRESH_ENTRY = ${REFRESH_ENTRY};
+const REFRESH_LOCK_PATH = ${LOCK};
+const REFRESH_LOCK_TTL_MS = ${LOCK_TTL};
+
 /** Buffer ALL of stdin into a Buffer. Resolves on end/close/error/timeout. */
 function readStdin() {
   return new Promise((resolve) => {
@@ -341,6 +357,65 @@ function styleLine(text) {
   return BAR + "┃" + RESET + " " + BODY + text + RESET + " " + BAR + "┃" + RESET;
 }
 
+/**
+ * DAEMONLESS stale-while-revalidate: if any source is past its cooldown and no
+ * fresh refresh is in flight, spawn a detached one-shot refresh. Never blocks
+ * the render (fire-and-forget) and never throws.
+ */
+function maybeTriggerRefresh() {
+  if (!DAEMONLESS || !REFRESH_ENTRY) return;
+  try {
+    // Is any source due? (sourceId is the source's index in the config.)
+    let cfg;
+    try {
+      cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+    } catch {
+      return;
+    }
+    const sources = Array.isArray(cfg && cfg.sources) ? cfg.sources : [];
+    if (sources.length === 0) return;
+
+    let lastRun = {};
+    try {
+      const c = JSON.parse(fs.readFileSync(CACHE_PATH, "utf8"));
+      if (c && c.meta && typeof c.meta.lastRun === "object") lastRun = c.meta.lastRun;
+    } catch {
+      // no cache yet -> everything is due
+    }
+
+    const now = Date.now();
+    let due = false;
+    for (let i = 0; i < sources.length; i++) {
+      const cd = (typeof sources[i].cooldown === "number" ? sources[i].cooldown : 300) * 1000;
+      if (now - (lastRun[i] || 0) >= cd) {
+        due = true;
+        break;
+      }
+    }
+    if (!due) return;
+
+    // Skip if a fresh refresh is already in flight.
+    try {
+      const t = Number(fs.readFileSync(REFRESH_LOCK_PATH, "utf8"));
+      if (Number.isFinite(t) && now - t < REFRESH_LOCK_TTL_MS) return;
+    } catch {
+      // no/!readable lock -> proceed
+    }
+
+    const child = spawn(process.execPath, [REFRESH_ENTRY], {
+      detached: true,
+      stdio: "ignore",
+      env: Object.assign({}, process.env, {
+        CONTEXTSPIN_CONFIG: CONFIG_PATH,
+        CONTEXTSPIN_CACHE: CACHE_PATH,
+      }),
+    });
+    child.unref();
+  } catch {
+    // never let revalidation break the render
+  }
+}
+
 /** Write a string to stdout, awaiting the flush callback. */
 function writeOut(text) {
   return new Promise((resolve) => {
@@ -374,6 +449,14 @@ async function main() {
     line = "";
   }
 
+  // (b2) DAEMONLESS: kick off a background refresh if anything is due. Detached
+  // and non-blocking — the line above is served immediately from cache.
+  try {
+    maybeTriggerRefresh();
+  } catch {
+    // ignore
+  }
+
   // (c) Compose: prior output, then our line on its own line beneath. We only
   // insert a separating newline when there is prior output that does not
   // already end in one, so a lone ContextSpin line stays a single clean line.
@@ -601,7 +684,20 @@ export async function installStatusline(config, opts = {}) {
   await writePrevMap(map);
 
   // (3) Render script (knows the prev-statusline MAP path) + bash wrapper.
-  const renderSource = buildRenderScript(CACHE_PATH, CONFIG_PATH, PREV_STATUSLINE_PATH);
+  // Resolve whether the DAEMONLESS engine is active (config opt-out wins) and the
+  // absolute path to the one-shot refresh entry, so the render can revalidate
+  // itself with no background daemon.
+  const daemonless =
+    config && config.injection && typeof config.injection.daemonless === "boolean"
+      ? config.injection.daemonless
+      : DEFAULT_DAEMONLESS;
+  const refreshEntry = fileURLToPath(new URL("../refresh-entry.js", import.meta.url));
+  const renderSource = buildRenderScript(CACHE_PATH, CONFIG_PATH, PREV_STATUSLINE_PATH, {
+    daemonless,
+    refreshEntry,
+    lockPath: REFRESH_LOCK_PATH,
+    lockTtlMs: REFRESH_LOCK_TTL_MS,
+  });
   await fsp.writeFile(STATUSLINE_JS, renderSource);
 
   // Silence stderr so node warnings never reach the status bar.

package/src/refresh-entry.js

@@ -0,0 +1,58 @@
+// src/refresh-entry.js — detached one-shot refresh for the DAEMONLESS engine.
+//
+// The statusline render spawns this (fire-and-forget) when a source is due. It
+// is lock-guarded so frequent renders can never spawn overlapping refreshes:
+// it acquires REFRESH_LOCK_PATH atomically (overriding a stale lock), runs one
+// refresh pass, and releases the lock. If the lock is held and fresh, it exits
+// immediately without doing anything.
+
+import fs from "node:fs";
+import { REFRESH_LOCK_PATH, REFRESH_LOCK_TTL_MS } from "./config.js";
+import { runRefreshOnce } from "./daemon.js";
+
+/**
+ * Try to acquire the refresh lock. Uses an exclusive create ("wx"); if the lock
+ * exists but is older than the TTL it is treated as stale and overridden.
+ * @returns {boolean} true if acquired.
+ */
+function acquireLock() {
+  try {
+    fs.writeFileSync(REFRESH_LOCK_PATH, String(Date.now()), { flag: "wx" });
+    return true;
+  } catch {
+    // Lock exists — override it only if stale.
+    try {
+      const age = Date.now() - Number(fs.readFileSync(REFRESH_LOCK_PATH, "utf8")) || 0;
+      if (age >= REFRESH_LOCK_TTL_MS) {
+        fs.writeFileSync(REFRESH_LOCK_PATH, String(Date.now()));
+        return true;
+      }
+    } catch {
+      // unreadable lock — leave it; another runner owns it
+    }
+    return false;
+  }
+}
+
+/** Release the refresh lock (best-effort). */
+function releaseLock() {
+  try {
+    fs.rmSync(REFRESH_LOCK_PATH, { force: true });
+  } catch {
+    // ignore
+  }
+}
+
+if (!acquireLock()) {
+  // A fresh refresh is already in flight; nothing to do.
+  process.exit(0);
+}
+
+runRefreshOnce({})
+  .catch((err) => {
+    console.error(`contextspin refresh failed: ${err && err.message ? err.message : err}`);
+  })
+  .finally(() => {
+    releaseLock();
+    process.exit(0);
+  });