sigmap 8.8.0 → 8.9.0

package/CHANGELOG.md

@@ -10,6 +10,25 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.9.0] — 2026-07-06
+
+Minor release — **the watcher, detached (D1).** `sigmap --watch` keeps the signature index fresh but held a terminal in the foreground. This adds a managed background daemon so you can start it once and forget it — the roadmap's #1 friction win. Zero-dependency, shell-free, deterministic.
+
+### Added
+- **Detached watch daemon — `sigmap daemon start|stop|status` (#447, PR #448):** runs the existing `--watch` mode as a background process, launched with `spawn(process.execPath, ['gen-context.js', '--watch'], { detached: true })` — an arguments array, never a shell command string — and tracked by a PID file under `.context/` (`daemon.pid`; output → `.context/daemon.log`). `start` does an initial generate then detaches, is idempotent (a second start reports "already running", spawns no second process), and clears a stale PID file first; `stop` sends SIGTERM and removes the PID file (a no-op when nothing is running); `status` reports the running PID and log path, exits 0 when running / 1 when not, and self-cleans a stale PID file. Every subcommand supports `--json`. New module `src/daemon/daemon.js`; CLI dispatch mirrors `sigmap mcp <sub>` and is listed in `--help`.
+
+## [8.8.1] — 2026-07-05
+
+Patch release — **byte-stable context, reproducible benchmark.** Closes the determinism residual tracked in #440: `gen-context` output is now byte-identical run-to-run across all 43 benchmark repos, and the retrieval benchmark reproduces a single hit@5 (87.8%) instead of flapping 85.6–87.8%. Plus a test-count derivation fix, docs/CI serving fixes, and repo hygiene.
+
+### Fixed
+- **gen-context determinism residual — token-budget recency boost (#440, PR #444):** the recency boost stamped `mtime = Date.now()` on every recently-committed file. On repos where nearly every file is "recently changed", consecutive files often landed on the *same millisecond* — so which equal-priority files shared a millisecond (and thus fell through to the `filePath` tie-break instead of sorting by a distinct mtime) shifted run to run, swapping which files survived at the budget cutoff and making the output non-byte-stable. The `Date.now()` value wasn't just a boost: it encoded the alphabetical walk order that the budget's best-first sort relied on; the nondeterminism was only the millisecond *collisions*. Replaced it with a deterministic monotonic counter (`nextRecentMtime`) that reproduces the exact same processing-order ranking without collisions. Result: all 43 benchmark repos are byte-identical across two clean runs (excluding the `Updated:` timestamp), and retrieval hit@5 reproduces at **87.8%** with identical per-repo results. Adds an integration regression guard (`test/integration/gen-context-determinism.test.js`) that runs gen-context twice on a committed fixture and asserts byte-equality — verified to fail on the old `Date.now()` behaviour.
+- **Derived test count after test relocation (503a6e5):** the test-count derivation globbed `tests/**/*.py`; after relocating `test_python_ast_extractor.py` into `test/` it matched neither pattern and dropped the count, failing `check:metrics` in CI. Now counts `test/**/test_*.py` (unittest-named), which matches the relocated test and excludes the fixture.
+- **Docs / CI serving (b236e08):** serve the OG banner image and the Google Search Console verification file; run the Python extractor tests in CI.
+
+### Changed
+- **Repo hygiene (a49e9c5):** dropped orphaned demo GIFs and a dead script; relocated a stray test from `tests/` into `test/`.
+
 ## [8.8.0] — 2026-07-05
 
 Minor release — **the squeeze engine, exposed mid-session (D6).** The always-on squeeze engine (`src/squeeze/`) that powers `sigmap squeeze` was reachable only from the CLI on pasted input. This release exposes it as an MCP tool an agent can call *mid-session*, and adds a named CLI entry point for compressing an agent/tool *response*. Zero-dependency, offline, deterministic — the last A+ ceiling item (Machine 9→10): the engine already shipped, this just exposes it.

package/README.md

@@ -120,8 +120,8 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.8-main (21 repositories, including R language)
-Date      : 2026-07-05
+Benchmark : sigmap-v8.9-main (21 repositories, including R language)
+Date      : 2026-07-06
 
 Hit@5          : 87.8%   (baseline 13.6%  — 6.5× lift)
 Token reduction: 97.0%   (across 21 repos)

package/gen-context.js

@@ -2592,6 +2592,134 @@ __factories["./src/create/orchestrate"] = function(module, exports) {
   
 };
 
+// ── ./src/daemon/daemon ──
+__factories["./src/daemon/daemon"] = function(module, exports) {
+  
+  /**
+   * Detached watch daemon (D1).
+   *
+   * Runs the existing `--watch` mode as a background process so the index stays
+   * fresh without holding a terminal. State lives under `.context/` (consistent
+   * with session/usage): `daemon.pid` records the watcher's PID, `daemon.log`
+   * captures its output.
+   *
+   * Zero-dependency and shell-free: the watcher is launched with
+   * `spawn(process.execPath, [gen-context.js, '--watch'], { detached: true })` —
+   * an arguments array, never a shell command string.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+  const { spawn } = require('child_process');
+
+  module.exports = { start, stop, status, pidFile, logFile, isAlive, readPid };
+
+  function daemonDir(cwd) {
+    return path.join(cwd, '.context');
+  }
+
+  function pidFile(cwd) {
+    return path.join(daemonDir(cwd), 'daemon.pid');
+  }
+
+  function logFile(cwd) {
+    return path.join(daemonDir(cwd), 'daemon.log');
+  }
+
+  /** True if a process with this PID exists (signal 0 probes without killing). */
+  function isAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      // EPERM = the process exists but is owned by another user — treat as alive.
+      return err.code === 'EPERM';
+    }
+  }
+
+  /** Read the recorded PID, or null if the file is missing/unparseable. */
+  function readPid(cwd) {
+    try {
+      const raw = fs.readFileSync(pidFile(cwd), 'utf8').trim();
+      const pid = parseInt(raw, 10);
+      return Number.isInteger(pid) && pid > 0 ? pid : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  function removePidFile(cwd) {
+    try {
+      fs.unlinkSync(pidFile(cwd));
+    } catch (_) {}
+  }
+
+  /**
+   * @returns {{ running: boolean, pid: number|null, pidFile: string, logFile: string }}
+   */
+  function status(cwd) {
+    const pid = readPid(cwd);
+    const running = pid != null && isAlive(pid);
+    // A recorded-but-dead PID is stale — clean it up so the state stays truthful.
+    if (pid != null && !running) removePidFile(cwd);
+    return { running, pid: running ? pid : null, pidFile: pidFile(cwd), logFile: logFile(cwd) };
+  }
+
+  /**
+   * Launch a detached `--watch` process. Idempotent: if one is already running
+   * this is a no-op that reports the existing PID.
+   *
+   * @param {string} cwd
+   * @param {{ scriptPath: string }} opts - path to gen-context.js (the CLI entry)
+   * @returns {{ status: 'started'|'already', pid: number, logFile: string }}
+   */
+  function start(cwd, opts = {}) {
+    const scriptPath = opts.scriptPath;
+    if (!scriptPath) throw new Error('daemon.start requires opts.scriptPath');
+
+    const current = status(cwd);
+    if (current.running) {
+      return { status: 'already', pid: current.pid, logFile: logFile(cwd) };
+    }
+
+    fs.mkdirSync(daemonDir(cwd), { recursive: true });
+    const out = fs.openSync(logFile(cwd), 'a');
+    try {
+      const child = spawn(process.execPath, [scriptPath, '--watch'], {
+        cwd,
+        detached: true,
+        stdio: ['ignore', out, out],
+      });
+      child.unref();
+      fs.writeFileSync(pidFile(cwd), String(child.pid) + '\n');
+      return { status: 'started', pid: child.pid, logFile: logFile(cwd) };
+    } finally {
+      try { fs.closeSync(out); } catch (_) {}
+    }
+  }
+
+  /**
+   * Stop the running watcher (SIGTERM) and clear its PID file.
+   *
+   * @returns {{ status: 'stopped'|'not-running'|'stale', pid?: number }}
+   */
+  function stop(cwd) {
+    const pid = readPid(cwd);
+    if (pid == null) return { status: 'not-running' };
+    if (!isAlive(pid)) {
+      removePidFile(cwd);
+      return { status: 'stale', pid };
+    }
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch (_) {}
+    removePidFile(cwd);
+    return { status: 'stopped', pid };
+  }
+  
+};
+
 // ── ./src/discovery/framework-detector ──
 __factories["./src/discovery/framework-detector"] = function(module, exports) {
   
@@ -13566,7 +13694,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.8.0',
+    version: '8.9.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -18158,7 +18286,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.8.0';
+const VERSION = '8.9.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -18368,6 +18496,26 @@ function annotateCoverage(sigs, testIndex, enabled) {
 // ---------------------------------------------------------------------------
 // Token budget enforcement
 // ---------------------------------------------------------------------------
+// Deterministic recency boost for recently-committed files so the token budget
+// doesn't drop them first. Previously this used `Date.now()`, which encoded the
+// (alphabetical) processing order as a monotonically increasing mtime — but on
+// repos where nearly every file is "recently changed", consecutive files often
+// landed on the *same* millisecond. Which files shared a millisecond (and so
+// fell through to the filePath tie-break instead of sorting by a distinct
+// mtime) shifted run to run, swapping which files survived at the budget cutoff
+// and making the output non-byte-stable. A monotonic integer counter preserves
+// the exact processing-order ranking Date.now() produced — recent files stay
+// ahead of non-recent ones, ordered among themselves by walk order — but is
+// collision-free and reproducible. RECENT_MTIME_BASE sits far above any real
+// filesystem mtime (ms since epoch ≈ 1.7e12) so boosted files always out-rank
+// non-boosted ones, and far below MAX_SAFE_INTEGER so the counter never
+// overflows. Call nextRecentMtime() once per boosted file, in walk order. (#440)
+const RECENT_MTIME_BASE = 1e15;
+let _recentMtimeSeq = 0;
+function nextRecentMtime() {
+  return RECENT_MTIME_BASE + (_recentMtimeSeq++);
+}
+
 function estimateTokens(str) {
   return Math.ceil(str.length / 4);
 }
@@ -19348,7 +19496,7 @@ function runDiff(cwd, config, stagedOnly, baseRef) {
 
     sigs = annotateCoverage(sigs, testIndex, !!config.testCoverage);
 
-    fileEntries.push({ filePath, sigs, deps: extractFileDeps(filePath, content, config), content, mtime: Date.now() });
+    fileEntries.push({ filePath, sigs, deps: extractFileDeps(filePath, content, config), content, mtime: nextRecentMtime() });
   }
 
   if (fileEntries.length === 0) {
@@ -19496,8 +19644,11 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
       mtime = fs.statSync(filePath).mtimeMs;
     } catch (_) {}
 
-    // Boost recently committed files (give them max mtime so they aren't dropped first)
-    if (recentFiles.has(filePath)) mtime = Date.now();
+    // Boost recently committed files (give them a max mtime so they aren't
+    // dropped first). A deterministic monotonic counter — not Date.now() — keeps
+    // the budget selection byte-stable when many files are recent, while
+    // preserving the original processing-order ranking (see nextRecentMtime, #440).
+    if (recentFiles.has(filePath)) mtime = nextRecentMtime();
 
     fileEntries.push({ filePath, sigs, deps: extractFileDeps(filePath, content, config), content, mtime });
   }
@@ -19939,6 +20090,7 @@ Usage:
   ${cmd} --track                           Append run metrics to .context/usage.ndjson
   ${cmd} --watch                           Generate + watch for file changes
   ${cmd} --setup                           Generate + install git hook + watch
+  ${cmd} daemon start|stop|status          Run --watch as a detached background daemon
   ${cmd} --mcp                             Start MCP server on stdio
   ${cmd} --report                          Token reduction stats to stdout
   ${cmd} --report --json                   Token report as JSON (for CI; exits 1 if over budget)
@@ -21480,6 +21632,46 @@ function main() {
     process.exit(1);
   }
 
+  // `sigmap daemon start|stop|status` — run `--watch` as a detached background
+  // process (D1). PID + log live under .context/. Mirrors the `mcp` sub-dispatch.
+  if (args[0] === 'daemon') {
+    const daemon = requireSourceOrBundled('./src/daemon/daemon');
+    const sub = args[1];
+    const jsonOut = args.includes('--json');
+
+    if (sub === 'start') {
+      const r = daemon.start(cwd, { scriptPath });
+      if (jsonOut) { process.stdout.write(JSON.stringify(r) + '\n'); process.exit(0); }
+      if (r.status === 'already') {
+        console.log(`[sigmap] daemon already running (pid ${r.pid})`);
+      } else {
+        console.log(`[sigmap] daemon started (pid ${r.pid}) — watching for changes`);
+        console.log(`[sigmap] logs: ${_displayPath(r.logFile, cwd)}   stop with: sigmap daemon stop`);
+      }
+      process.exit(0);
+    }
+
+    if (sub === 'stop') {
+      const r = daemon.stop(cwd);
+      if (jsonOut) { process.stdout.write(JSON.stringify(r) + '\n'); process.exit(0); }
+      if (r.status === 'not-running') console.log('[sigmap] daemon not running');
+      else if (r.status === 'stale') console.log(`[sigmap] removed stale pid file (pid ${r.pid} no longer alive)`);
+      else console.log(`[sigmap] daemon stopped (pid ${r.pid})`);
+      process.exit(0);
+    }
+
+    if (sub === 'status') {
+      const r = daemon.status(cwd);
+      if (jsonOut) { process.stdout.write(JSON.stringify(r) + '\n'); process.exit(r.running ? 0 : 1); }
+      if (r.running) console.log(`[sigmap] daemon running (pid ${r.pid}) — logs: ${_displayPath(r.logFile, cwd)}`);
+      else console.log('[sigmap] daemon not running');
+      process.exit(r.running ? 0 : 1);
+    }
+
+    console.error('[sigmap] usage: sigmap daemon start | stop | status');
+    process.exit(1);
+  }
+
   // `sigmap doctor` — diagnose config, index, freshness, coverage, and MCP
   // wiring; print an actionable fix for anything wrong. Exit 1 on a hard
   // failure (no context file / invalid config) so it is usable in CI.

package/llms-full.txt

@@ -11,13 +11,13 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.8.0 | Benchmark: sigmap-v8.8-main (2026-07-05)
+# Version: 8.9.0 | Benchmark: sigmap-v8.9-main (2026-07-06)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v8.8-main, 2026-07-05)
+## Core metrics (benchmark: sigmap-v8.9-main, 2026-07-06)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -59,6 +59,7 @@ sigmap --format cache                    Also write Anthropic prompt-cache JSON
 sigmap --track                           Append run metrics to .context/usage.ndjson
 sigmap --watch                           Generate + watch for file changes
 sigmap --setup                           Generate + install git hook + watch
+sigmap daemon start|stop|status          Run --watch as a detached background daemon
 sigmap --mcp                             Start MCP server on stdio
 sigmap --report                          Token reduction stats to stdout
 sigmap --report --json                   Token report as JSON (for CI; exits 1 if over budget)

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.8.0 | Benchmark: sigmap-v8.8-main (2026-07-05)
+# Version: 8.9.0 | Benchmark: sigmap-v8.9-main (2026-07-06)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -23,7 +23,7 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v8.8-main, 2026-07-05)
+## Core metrics (benchmark: sigmap-v8.9-main, 2026-07-06)
 
 - hit@5 retrieval: 87.8% vs 13.6% random baseline (6.5× lift)
 - Token reduction: 97.0% average across benchmark repos

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "8.8.0",
+  "version": "8.9.0",
   "description": "97% token reduction for AI coding. Extracts function & class signatures with TF-IDF ranking to feed only the right files to Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP. Zero dependencies, runs offline via npx.",
   "main": "packages/core/index.js",
   "exports": {
@@ -17,6 +17,7 @@
     "test": "node test/run.js && node test/r-language.test.js",
     "test:integration": "node test/integration/strategy.test.js && node test/integration/secret-scan.test.js && node test/integration/token-budget.test.js && node test/integration/auto-budget.test.js && node test/integration/mcp/server.test.js && node test/integration/verify-ai-output.test.js && node test/integration/memory-tools.test.js && node test/integration/squeeze.test.js && node test/integration/context-consistency.test.js && node test/integration/features/llms-current.test.js",
     "test:integration:all": "node test/integration/all.js",
+    "test:python": "python3 test/test_python_ast_extractor.py",
     "test:all": "node test/run.js && node test/r-language.test.js && node test/integration/strategy.test.js && node test/integration/secret-scan.test.js",
     "generate": "node gen-context.js",
     "watch": "node gen-context.js --watch",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "8.8.0",
+  "version": "8.9.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "8.8.0",
+  "version": "8.9.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/daemon/daemon.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * Detached watch daemon (D1).
+ *
+ * Runs the existing `--watch` mode as a background process so the index stays
+ * fresh without holding a terminal. State lives under `.context/` (consistent
+ * with session/usage): `daemon.pid` records the watcher's PID, `daemon.log`
+ * captures its output.
+ *
+ * Zero-dependency and shell-free: the watcher is launched with
+ * `spawn(process.execPath, [gen-context.js, '--watch'], { detached: true })` —
+ * an arguments array, never a shell command string.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+module.exports = { start, stop, status, pidFile, logFile, isAlive, readPid };
+
+function daemonDir(cwd) {
+  return path.join(cwd, '.context');
+}
+
+function pidFile(cwd) {
+  return path.join(daemonDir(cwd), 'daemon.pid');
+}
+
+function logFile(cwd) {
+  return path.join(daemonDir(cwd), 'daemon.log');
+}
+
+/** True if a process with this PID exists (signal 0 probes without killing). */
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM = the process exists but is owned by another user — treat as alive.
+    return err.code === 'EPERM';
+  }
+}
+
+/** Read the recorded PID, or null if the file is missing/unparseable. */
+function readPid(cwd) {
+  try {
+    const raw = fs.readFileSync(pidFile(cwd), 'utf8').trim();
+    const pid = parseInt(raw, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function removePidFile(cwd) {
+  try {
+    fs.unlinkSync(pidFile(cwd));
+  } catch (_) {}
+}
+
+/**
+ * @returns {{ running: boolean, pid: number|null, pidFile: string, logFile: string }}
+ */
+function status(cwd) {
+  const pid = readPid(cwd);
+  const running = pid != null && isAlive(pid);
+  // A recorded-but-dead PID is stale — clean it up so the state stays truthful.
+  if (pid != null && !running) removePidFile(cwd);
+  return { running, pid: running ? pid : null, pidFile: pidFile(cwd), logFile: logFile(cwd) };
+}
+
+/**
+ * Launch a detached `--watch` process. Idempotent: if one is already running
+ * this is a no-op that reports the existing PID.
+ *
+ * @param {string} cwd
+ * @param {{ scriptPath: string }} opts - path to gen-context.js (the CLI entry)
+ * @returns {{ status: 'started'|'already', pid: number, logFile: string }}
+ */
+function start(cwd, opts = {}) {
+  const scriptPath = opts.scriptPath;
+  if (!scriptPath) throw new Error('daemon.start requires opts.scriptPath');
+
+  const current = status(cwd);
+  if (current.running) {
+    return { status: 'already', pid: current.pid, logFile: logFile(cwd) };
+  }
+
+  fs.mkdirSync(daemonDir(cwd), { recursive: true });
+  const out = fs.openSync(logFile(cwd), 'a');
+  try {
+    const child = spawn(process.execPath, [scriptPath, '--watch'], {
+      cwd,
+      detached: true,
+      stdio: ['ignore', out, out],
+    });
+    child.unref();
+    fs.writeFileSync(pidFile(cwd), String(child.pid) + '\n');
+    return { status: 'started', pid: child.pid, logFile: logFile(cwd) };
+  } finally {
+    try { fs.closeSync(out); } catch (_) {}
+  }
+}
+
+/**
+ * Stop the running watcher (SIGTERM) and clear its PID file.
+ *
+ * @returns {{ status: 'stopped'|'not-running'|'stale', pid?: number }}
+ */
+function stop(cwd) {
+  const pid = readPid(cwd);
+  if (pid == null) return { status: 'not-running' };
+  if (!isAlive(pid)) {
+    removePidFile(cwd);
+    return { status: 'stale', pid };
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (_) {}
+  removePidFile(cwd);
+  return { status: 'stopped', pid };
+}

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '8.8.0',
+  version: '8.9.0',
   description: 'SigMap MCP server — code signatures on demand',
 };