candor-ts 0.4.6 → 0.5.0

package/scan.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * candor-ts — the TypeScript implementation of candor-spec 0.4.
+ * candor-ts — the TypeScript implementation of candor-spec 0.5.
  *
  * Origin (kept honest): this engine began as the clean-room derivability proof — a single-file
  * slice written from SPEC.md/SEMANTICS.md/CLASSIFIER.md alone, frozen as that claim in git history
@@ -26,6 +26,7 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { parsePolicy, evaluatePolicy } from "./policy.mjs";
 import { printAgents } from "./contract.mjs";
+import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql } from "./scan-core.mjs";
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -56,9 +57,6 @@ if (wantAgents) { printAgents(); process.exit(0); }
 if (target === null) { console.error(usage); process.exit(2); }
 
 // ---- project discovery (a dir, a single file, or a tsconfig) --------------------------------------
-function isTestPath(p) {
-  return /(^|\/)(node_modules|__tests__|tests?|spec)(\/|$)/.test(p) || /\.(test|spec)\.[mc]?tsx?$/.test(p);
-}
 let rootDir, fileNames, compilerOptions = {
   target: ts.ScriptTarget.ES2022,
   module: ts.ModuleKind.NodeNext,
@@ -221,68 +219,6 @@ const checker = program.getTypeChecker();
 const projectFiles = new Set(fileNames.map((f) => path.resolve(f)));
 const sources = program.getSourceFiles().filter((f) => projectFiles.has(path.resolve(f.fileName)));
 
-// ---- κ — the curated classifier (CLASSIFIER §2: the dispatch/execution boundary, not builders) ----
-// Node builtins + a curated npm tier (the same under-report-and-say-so posture as the crate table:
-// an unlisted package contributes nothing — never a guess).
-// One rules TABLE, two readers: kappa() classifies a call; kappaKnows() answers "is this package
-// curated at all?" for the coverage ledger (a κ-known package whose given call is pure — a TypeORM
-// builder — is covered, not a blind spot). A single source so the two can never drift.
-// [module-name regex, member regex (null = any member), effect]
-const KAPPA_RULES = [
-  [/^(node:)?fs(\/promises)?$/, null, "Fs"],
-  [/^(node:)?(net|dgram|tls|http2?|https)$/, null, "Net"],
-  [/^(node:)?child_process$/, null, "Exec"],
-  [/^(node:)?sqlite$/, null, "Db"],
-  // the curated npm tier
-  [/^(axios|got|node-fetch|undici|ws|socket\.io(-client)?|nodemailer)$/, null, "Net"],
-  [/^(pg|mysql2?|mongodb|ioredis|redis|sqlite3|better-sqlite3|knex)$/, null, "Db"],
-  [/^(execa|cross-spawn|shelljs)$/, null, "Exec"],
-  [/^(fs-extra|graceful-fs|rimraf|glob|chokidar)$/, null, "Fs"],
-  [/^dotenv$/, null, "Env"],
-  [/^(winston|pino|bunyan|npmlog)$/, null, "Log"],
-  // entropy: node:crypto's random surface + the password-hashing libs (salted -> Rand). Found by
-  // the CTA dogfood on a Nest app: argon2.hash came out SILENTLY PURE (the curated-kappa caveat
-  // landing on exactly the call a security review cares about).
-  [/^(node:)?crypto$/, /^random/, "Rand"],
-  [/^(argon2|bcrypt|bcryptjs)$/, null, "Rand"],
-  // The ORM tier — VERB-PRECISE (the CLASSIFIER discipline: tag the execution boundary, not
-  // builders; `createQueryBuilder` is pure, its `getMany`/`execute` is the I/O). Found on the
-  // first framework-APP scan: a TypeORM/Nest application — Db-heavy by construction — read zero
-  // Db because the ORM resolved into an unlisted package (the JVM's Spring-Data lesson, replayed).
-  [/^(typeorm|@nestjs\/typeorm)$/,
-   /^(find|save|remove|softRemove|recover|insert|update|upsert|delete|restore|count|exist|sum|average|minimum|maximum|query|clear|increment|decrement|getMany|getOne|getOneOrFail|getRawMany|getRawOne|getCount|getExists|execute|stream|transaction)/,
-   "Db"],
-  [/^(@prisma\/client|\.prisma|\.prisma\/client)$/,
-   /^(\$?(queryRaw|executeRaw|transaction)|find(Many|Unique|First)|create|createMany|update|updateMany|upsert|delete|deleteMany|aggregate|count|groupBy)/,
-   "Db"],
-  [/^mongoose$/,
-   /^(find|save|create|insertMany|updateOne|updateMany|replaceOne|deleteOne|deleteMany|aggregate|countDocuments|estimatedDocumentCount|distinct|exec|bulkWrite)/,
-   "Db"],
-  [/^(sequelize|drizzle-orm)$/,
-   /^(find|create|update|destroy|upsert|count|max|min|sum|query|select|insert|delete|execute|transaction)/,
-   "Db"],
-  // Nest's HttpService wraps axios — the request verbs are Net.
-  [/^@nestjs\/axios$/, /^(get|post|put|patch|delete|head|request)$/, "Net"],
-];
-function kappa(moduleName, member) {
-  for (const [mre, vre, eff] of KAPPA_RULES) {
-    if (mre.test(moduleName) && (!vre || vre.test(member))) return eff;
-  }
-  return null;
-}
-// Packages REVIEWED and ratified effect-free at the call boundary (decorator/metadata plumbing,
-// pure computation, operator algebras whose side effects live in visible user callbacks). This is
-// the ledger's triage outlet: an unlisted package either earns KAPPA_RULES entries or lands here —
-// never silently. NOT for anything that mints entropy (uuid), reads clocks, or signs with RSA-PSS
-// (jsonwebtoken stays unlisted on purpose).
-const KAPPA_PURE = new Set([
-  "@nestjs/common", "@nestjs/core", "@nestjs/swagger", "@nestjs/platform-express",
-  "class-validator", "class-transformer", "reflect-metadata",
-  "rxjs", "zod", "lodash", "ramda", "date-fns",
-]);
-function kappaKnows(moduleName) {
-  return KAPPA_PURE.has(moduleName) || KAPPA_RULES.some(([mre]) => mre.test(moduleName));
-}
 
 // The module a declaration came from: a project file → "<local>", @types/node → the builtin name,
 // node_modules/<pkg> → the package name, the ES lib → "<es-lib>".
@@ -297,6 +233,47 @@ function declModule(decl) {
   return f;
 }
 
+// SPEC §5.1 — the effect manifest. An uncurated package MAY declare its effect surface in its
+// package.json (`"candorEffects": ["Net"]`), read as the declared-not-verified tier: it kills the
+// silent pure/blind-spot the package would otherwise carry, exactly like a cap type (and unlike
+// candor's own analysis, which is checked). A name outside §1 VOIDS the declaration loudly — a typo
+// must never silently narrow a surface. Cached per package. `file` is the resolved declaration source.
+const EFFECT_VOCAB = new Set(["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard"]);
+const _manifestCache = new Map();
+// Returns the declared effect array (possibly EMPTY — `[]` is an explicit "declared pure", covered, not
+// a blind spot), or `null` for no/invalid declaration (still a blind spot). A name outside §1 voids the
+// declaration loudly; a non-array `candorEffects` is malformed and warned.
+function packageManifestEffects(file) {
+  const m = file && file.match(/^(.*\/node_modules\/(?:@[^/]+\/[^/]+|[^/]+))\//);
+  if (!m) return null;
+  let dir = m[1];
+  // A manifest read from an `@types/<pkg>` directory is a TRUST-BOUNDARY HOLE: the @types stub is a
+  // type-only package published by DefinitelyTyped/anyone — NOT the effect-owning package. Honoring its
+  // `candorEffects` let an attacker's `@types/realpkg` declare `[]` to SILENCE the real realpkg's effects
+  // AND its κ-ledger disclosure (defeating the spec's "a missing manifest is visible via κ" safety net).
+  // Redirect to the REAL package's own dir, whose author controls it (`@types/babel__core` → `@babel/core`,
+  // `@types/foo` → `foo`); if that has no manifest, it stays an honest κ-ledger blind spot, never silenced.
+  const at = dir.match(/^(.*\/node_modules\/)@types\/([^/]+)$/);
+  if (at) {
+    const real = at[2].includes("__") ? "@" + at[2].replace("__", "/") : at[2];
+    dir = at[1] + real;
+  }
+  if (_manifestCache.has(dir)) return _manifestCache.get(dir);
+  let result = null;
+  try {
+    const d = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).candorEffects;
+    if (Array.isArray(d)) {
+      const bad = d.filter((e) => !EFFECT_VOCAB.has(e));
+      if (bad.length) console.error(`candor-ts: ${path.basename(dir)} candorEffects has an invalid effect '${bad[0]}' — declaration voided (SPEC §1)`);
+      else result = d; // a valid declaration, including [] = declared pure
+    } else if (d !== undefined) {
+      console.error(`candor-ts: ${path.basename(dir)} candorEffects must be an array of §1 effect names — ignored`);
+    }
+  } catch { /* no/unreadable manifest → undeclared */ }
+  _manifestCache.set(dir, result);
+  return result;
+}
+
 // ---- the literal surfaces (SPEC §2 hosts/cmds/paths/tables): the statically-decidable subset ------
 // Read ONLY from string literals at a classified call — informative, never complete, never inferred.
 function firstStringLiteral(node) {
@@ -305,76 +282,19 @@ function firstStringLiteral(node) {
   }
   return null;
 }
-// Refine the Exec cliff (spec §4 ⟨0.5⟩): the effects a literal, statically-known subprocess head
-// implies, matched by basename. ADDED to a caller that already carries Exec (a subprocess is still
-// spawned — Exec is never dropped); an unrecognised head returns [] and keeps the bare cliff (never
-// guess). A candor engine reads Fs/Env only — spec §7 item 12 (the analyzer self-boundary) guarantees
-// it, so that case is spec-supplied. Only UNAMBIGUOUS single-effect tools belong here: a multi-modal
-// head (git status local vs git push Net; rsync local vs remote; make/npm run project code) would
-// fabricate the effect for its common case. The reference engines share this table verbatim.
-function commandHeadEffects(cmd) {
-  const base = cmd.trim().split(/\s+/)[0].split(/[/\\]/).pop();
-  if (["curl", "wget", "http", "ssh", "scp"].includes(base)) return ["Net"];
-  if (["psql", "mysql", "sqlite3", "mongosh", "redis-cli"].includes(base)) return ["Db"];
-  if (["candor", "candor-run.sh", "candor-scan", "candor-query", "candor-java",
-       "candor-classify", "candor-report", "cargo-candor"].includes(base)) return ["Env", "Fs"];
-  return [];
-}
-// host[:port] from an address/URL literal; non-address strings yield nothing (never fabricate).
-function hostLiteral(s) {
-  const m = s.match(/^[a-z][a-z0-9+.-]*:\/\/([^/]+)/i);   // scheme://host[:port]/…
-  if (m) return m[1].replace(/^.*@/, "");
-  if (/^[a-z0-9._-]+(:\d+)?$/i.test(s) && s.includes(".")) return s; // bare host[.tld][:port]
-  return null;
-}
-// Table-position identifiers in a SQL string literal (SPEC §2 `tables`). Mirrors the Rust
-// tables_in_sql exactly: must open with a statement keyword; FROM/JOIN/INTO anywhere,
-// statement-leading UPDATE/TRUNCATE, TABLE (skipping ONLY/IF NOT EXISTS); a FOR UPDATE locking
-// clause yields nothing. Conservative in the fabrication direction.
-function tablesInSql(sql) {
-  const stmt = new Set(["select","insert","update","delete","create","drop","alter","truncate","merge","replace","with"]);
-  const skip = new Set(["only","if","not","exists","table"]);
-  const stop = new Set(["select","set","where","values","on","using","group","order","by","limit",
-    "returning","as","inner","outer","left","right","cross","lateral","natural","union","all",
-    "distinct","case","when","null","default","skip","nowait","of","from","join","into","update",
-    "delete","insert"]);
-  // `,` survives as its OWN token: it lets `FROM t1, t2` continue the table list without
-  // fabricating from other comma-ridden positions (column lists, ON clauses).
-  const toks = sql.toLowerCase().replace(/[();]/g, " ").replace(/,/g, " , ").trim().split(/\s+/);
-  if (!toks.length || !stmt.has(toks[0])) return [];
-  const out = [];
-  const ident = (raw) => {
-    const t = raw.replace(/^["'`]+|["'`]+$/g, "");
-    if (!t || stop.has(t) || !/^[a-z_][a-z0-9_.$"`]*$/.test(t)) return null;
-    return t.replace(/["`]/g, "");
-  };
-  for (let i = 0; i < toks.length; i++) {
-    const tablePos = ["from","join","into","table"].includes(toks[i])
-      || ((toks[i] === "update" || toks[i] === "truncate") && i === 0);
-    if (!tablePos) continue;
-    let j = i + 1;
-    while (j < toks.length && skip.has(toks[j])) j++;
-    if (j >= toks.length) continue;
-    const first = ident(toks[j]);
-    if (first === null) continue;
-    if (!out.includes(first)) out.push(first);
-    // Comma-ADJACENT continuation only: `FROM t1, t2, t3` takes all three, while an alias breaks
-    // the chain (`FROM t1 a, t2` keeps just t1 — an under-report, never a guess: skipping an alias
-    // to chase the comma would fabricate tables out of `INSERT INTO t (a, b)`'s column list, whose
-    // parens are spaces by the time we tokenize).
-    while (j + 2 < toks.length && toks[j + 1] === ",") {
-      const more = ident(toks[j + 2]);
-      if (more === null) break;
-      if (!out.includes(more)) out.push(more);
-      j += 2;
-    }
-  }
-  return out;
-}
 
-// ---- pass 1: collect the analyzed functions across the project (SEMANTICS §2's F) -----------------
-// Names are MODULE-QUALIFIED (`src.db.save` for save() in src/db.ts; separators → "." so the §6.2
-// segment-scope rules apply naturally: `deny Net db` matches the db module). A single-file scan
+// The literal PROGRAM head a subprocess call NAMES — argv[0] specifically, never a later argument.
+// Unlike firstStringLiteral (the first literal ANYWHERE in the args), this refuses to refine when
+// the program (arg0) is a runtime value but a trailing arg is a literal whose basename hits the head
+// table: `spawn(toolVar, "curl")` must NOT fabricate Net — the literal is an argument, not the
+// program (spec §4 ⟨0.5⟩: the head is argv[0]). Mirrors candor-java programHeadLiteral and the Rust
+// is_cmd_naming_method gate. Returns null when arg0 is not a static string literal — the safe
+// direction. Used ONLY for the effect refinement, never to widen it; the cosmetic `cmds` surface
+// keeps firstStringLiteral.
+function programHeadLiteral(node) {
+  const a0 = (node.arguments ?? [])[0];
+  return a0 && ts.isStringLiteralLike(a0) ? a0.text : null;
+}
 // qualifies by the file's basename (`Cases.union_a`).
 const fns = new Map();           // qualified name -> { direct, edges, hosts, tables, cmds, paths, loc }
 const unlistedSeen = new Map();  // the κ-coverage ledger: unlisted npm package -> call-site count
@@ -562,6 +482,24 @@ function enclosing(node) {
   return null;
 }
 
+// True when a receiver expression's chain ROOTS at process.stdout/stderr/stdin — including method chains
+// (`process.stdin.on("data",f).on("end",g)`, `process.stdout.write(x).on(...)`). The std streams are typed
+// tty.ReadStream/WriteStream which EXTEND net.Socket, so `.on`/`.write`/`.end` resolve to net.Socket members
+// and the whole-module Net rule paints them — but console fd 0/1/2 I/O is not Net (§1 has no Console effect).
+// `net.Socket.on`/`.write` return the stream (`this`), so a chained call's receiver is still the std stream;
+// the exact-string check missed it (the receiver is the inner CallExpression). Walk the chain to its head.
+function rootsAtStdStream(expr) {
+  let e = expr;
+  for (;;) {
+    if (!e) return false;
+    const t = e.getText().replace(/\s+/g, "");
+    if (t === "process.stdout" || t === "process.stderr" || t === "process.stdin") return true;
+    if (ts.isCallExpression(e) || ts.isPropertyAccessExpression(e) || ts.isElementAccessExpression(e)
+        || ts.isParenthesizedExpression(e) || ts.isNonNullExpression(e)) { e = e.expression; continue; }
+    return false;
+  }
+}
+
 // ---- pass 2: per call site, the (CLASSIFY)/(EDGE)/(UNKNOWN) resolution of SEMANTICS §4 ------------
 function visitCalls(node) {
   if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
@@ -673,8 +611,37 @@ function visitCalls(node) {
               && checker.getTypeAtLocation(node.expression)?.symbol?.name === "DateConstructor")
             rec.direct.add("Clock");
         } else {
-          const member = decl.name ? decl.name.getText() : "";
-          const eff = kappa(mod, member); // (CLASSIFY)
+          // The member token κ matches: the resolved declaration's name, EXCEPT a `new X()` call,
+          // whose declaration is a Constructor (empty name) — synthesize "new" so a rule can exempt
+          // inert construction from its module-wide effect (the net cluster: `new http.Agent()` etc.).
+          // BUT a CONNECTING constructor is NOT inert: `new http.ClientRequest(url)` performs the
+          // network I/O on construction (it is what `http.request()` returns and dispatches), so the
+          // blanket `new`-exemption would convert a real Net source into pure (a cardinal-sin under-
+          // report). For such a ctor we synthesize the CLASS name instead of "new", so the net-cluster
+          // rule's `/^(?!new$)/` matcher keeps the effect. The set is the net cluster's documented
+          // public connecting ctors; http2 connects via `connect()` (a function, not a ctor) so it
+          // needs no entry here. Inert ctors (Agent/Server/Socket/TLSSocket/Http2Server*/message shells)
+          // still synthesize "new" and stay pure.
+          const CONNECTING_CTORS = new Set(["ClientRequest"]);
+          const ctorClassName = ts.isNewExpression(node)
+            ? (ts.isConstructorDeclaration(decl) ? decl.parent?.name?.getText?.()
+               : (decl.name ? decl.name.getText() : ""))
+            : "";
+          const isConstruction = ts.isConstructorDeclaration(decl) || ts.isNewExpression(node);
+          const member = isConstruction
+            ? (CONNECTING_CTORS.has(ctorClassName) ? ctorClassName : "new")
+            : (decl.name ? decl.name.getText() : "");
+          let eff = kappa(mod, member); // (CLASSIFY)
+          // process.stdout/stderr/stdin are typed `tty.WriteStream`, which EXTENDS `net.Socket`, so a
+          // `.write()`/`.end()` on them resolves to `net.Socket.write` and the whole-module Net rule
+          // paints it Net. But a console write to fd 0/1/2 is TTY/console I/O, NOT network — there is no
+          // "Console" effect in §1, so it must be PURE. Suppress the fabricated effect for these receivers
+          // (a real `net.Socket` you constructed and `.write()` to still classifies Net — only the three
+          // std streams are freed). Real-world sweep: nanoid/commander(×43)/bunyan/pino fabricated Net
+          // purely from a `process.stdout.write` — the cardinal sin.
+          if (eff && (ts.isPropertyAccessExpression(node.expression) || ts.isElementAccessExpression(node.expression))
+              && rootsAtStdStream(node.expression.expression))
+            eff = null;
           if (eff) rec.direct.add(eff);
           // the literal surfaces, read only at a CLASSIFIED call (SPEC §2)
           if (eff === "Net") {
@@ -698,15 +665,16 @@ function visitCalls(node) {
           }
           if (eff === "Exec") {
             const lit = firstStringLiteral(node);
-            if (lit) {
-              rec.cmds.add(lit.trim().split(/\s+/)[0]); // the program of a command line
-              // a known literal head refines the cliff (curl→Net, candor→Fs/Env); Exec stays
-              for (const e of commandHeadEffects(lit)) rec.direct.add(e);
-            }
+            if (lit) rec.cmds.add(lit.trim().split(/\s+/)[0]); // cosmetic cmds surface (any literal)
+            // a known literal head refines the cliff (curl→Net, candor→Fs/Env); Exec stays. The head
+            // MUST be argv[0] (programHeadLiteral), NOT any literal arg: `spawn(toolVar, "curl")`
+            // names no static program, so its trailing literal must not fabricate Net (spec §4).
+            const head = programHeadLiteral(node);
+            if (head) for (const e of commandHeadEffects(head)) rec.direct.add(e);
           }
           if (eff === "Fs") {
             const lit = firstStringLiteral(node);
-            if (lit && /[\/\\]|^[.~]/.test(lit)) rec.paths.add(lit); // path-shaped literals only
+            if (lit && /[/\\]|^[.~]/.test(lit)) rec.paths.add(lit); // path-shaped literals only
           }
           // CANDOR_DEPS: an unclassified call into a package with a loaded sibling report inherits
           // that function's recorded transitive effects (+ literal surfaces) by `hash`.
@@ -745,7 +713,13 @@ function visitCalls(node) {
             // via @types/lodash was falsely disclosed — kappaKnows saw the unstripped name).
             const pkg = mod.startsWith("@types/") ? mod.slice("@types/".length) : mod;
             const file = decl.getSourceFile().fileName;
-            if (!kappaKnows(pkg) && !depCoveredPkgs.has(pkg)
+            // SPEC §5.1: a package that DECLARES its effects (candorEffects in package.json) is read
+            // at the declared-not-verified tier — its effects are attributed and it is NOT a blind
+            // spot. Otherwise the κ ledger names it (an uncurated dependency the review must read).
+            const declared = packageManifestEffects(file);
+            if (declared !== null) {
+              for (const e of declared) rec.direct.add(e); // [] = declared pure: covered, adds nothing
+            } else if (!kappaKnows(pkg) && !depCoveredPkgs.has(pkg)
                 && /node_modules\//.test(file) && !/node_modules\/(@types\/node|typescript)\//.test(file)) {
               unlistedSeen.set(pkg, (unlistedSeen.get(pkg) ?? 0) + 1);
             }
@@ -848,12 +822,17 @@ for (const [name, rec] of fns) {
 }
 // `package` names what this report COVERS — a consumer chaining it registers coverage even when
 // `functions` is empty (an all-pure package's report is its purity claim, SPEC §2 rule 3).
-const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: "0.4" },
+const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: "0.5" },
                    package: pkgName, functions };
-fs.writeFileSync(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
 const cg = {};
 for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();
-fs.writeFileSync(`${outPrefix}.callgraph.json`, JSON.stringify(cg, null, 1));
+// Write ATOMICALLY (temp + rename): a concurrent reader — the MCP server or another `query` while
+// `candor-ts-watch` re-scans (the recommended agent setup runs both) — must never observe a
+// half-written report. An in-place writeFileSync leaves a truncation window where JSON.parse throws;
+// rename(2) is atomic within a filesystem, so a reader sees either the old report or the new one whole.
+const writeAtomic = (file, text) => { const tmp = `${file}.${process.pid}.tmp`; fs.writeFileSync(tmp, text); fs.renameSync(tmp, file); };
+writeAtomic(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
+writeAtomic(`${outPrefix}.callgraph.json`, JSON.stringify(cg, null, 1));
 console.error(`candor-ts: wrote ${functions.length} effectful functions (${fns.size} analyzed, ${sources.length} files) to ${outPrefix}.json`);
 if (unlistedSeen.size > 0) {
   const top = [...unlistedSeen.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));

package/watch.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * candor-ts-watch — keep a candor report FRESH as an agent edits, so candor-ts-mcp serves live ground
+ * truth (roadmap #1, the freshness half). It tracks the project's TS sources by content hash and
+ * re-scans only when a tracked source ACTUALLY changed — a no-op save, a touched node_modules file, or
+ * an unrelated write never triggers work. The MCP server reads the same `--out` prefix, so the loop is:
+ * agent edits → watcher refreshes the report → agent asks candor_impact and gets the post-edit answer.
+ *
+ * v1 re-runs a FULL scan on a real change — sound (the report always equals a clean scan), and fast
+ * enough for the edit loop on small/mid projects. The deeper optimisation — re-analysing only the
+ * changed file's subgraph and re-propagating incrementally (the part that needs candor-ts's scanner
+ * factored for per-file extraction) — is the staged next step; the content-hash gate here is the first
+ * increment of it (don't redo work when nothing relevant changed).
+ *
+ *   candor-ts-watch <dir> [--out <prefix>] [--interval <ms>]
+ */
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as Q from "./query-core.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = /\.[mc]?[jt]sx?$/;            // .ts/.tsx/.mts/.cts/.js/.jsx — what candor-ts analyses
+const SKIP = new Set(["node_modules", ".git", "dist", "build", ".candor"]);
+
+// The tracked source set: every analysable file under `target` (a dir), or the single file itself.
+export function trackedFiles(target) {
+  const st = fs.statSync(target);
+  if (st.isFile()) return SRC.test(target) ? [path.resolve(target)] : [];
+  const out = [];
+  (function walk(dir) {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (ent.name.startsWith(".") && ent.name !== ".") continue;
+      if (SKIP.has(ent.name)) continue;
+      const p = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(p);
+      else if (SRC.test(ent.name)) out.push(path.resolve(p));
+    }
+  })(target);
+  return out.sort();
+}
+
+// file -> content hash; a missing file is dropped (so deletes register as a change).
+export function hashFiles(files) {
+  const h = {};
+  for (const f of files) {
+    try { h[f] = crypto.createHash("sha1").update(fs.readFileSync(f)).digest("hex"); } catch { /* gone */ }
+  }
+  return h;
+}
+
+// The set of files whose hash differs between two snapshots (added, removed, or modified).
+export function changedFiles(prev, cur) {
+  const names = new Set([...Object.keys(prev), ...Object.keys(cur)]);
+  return [...names].filter((f) => prev[f] !== cur[f]).sort();
+}
+
+// One sound scan into `<out>` (the prefix the MCP server reads). Returns {ok, ms}.
+export function scanOnce(target, out) {
+  const t0 = Date.now();
+  const r = spawnSync("node", [path.join(HERE, "scan.mjs"), target, "--out", out], { encoding: "utf8" });
+  return { ok: r.status === 0, ms: Date.now() - t0, stderr: r.stderr };
+}
+
+function rel(f, target) { return path.relative(fs.statSync(target).isFile() ? path.dirname(target) : target, f) || f; }
+
+// The report from disk, or [] if there isn't one yet (the first scan has nothing to diff against).
+export function readReportSafe(out) {
+  try { return Q.loadReport(out); } catch { return []; }
+}
+
+// One-line summary of what an edit changed — the agent-loop payoff: not just "the report is fresh"
+// but "your edit added Net to f". Built on the same diff the CLI emits. "" when nothing's effects moved.
+export function formatDelta(changes) {
+  const leaf = (n) => n.split("::").pop().split(".").pop();
+  const parts = changes.slice(0, 4).map((c) => {
+    const g = c.gained.length ? `+${c.gained.join("/")}` : "";
+    const l = c.lost.length ? `-${c.lost.join("/")}` : "";
+    return `${leaf(c.fn)} ${[g, l].filter(Boolean).join(" ")}`.trim();
+  });
+  if (changes.length > 4) parts.push(`+${changes.length - 4} more`);
+  return parts.join("; ");
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let target = null, out = null, interval = 400;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--out") out = args[++i];
+    else if (args[i] === "--interval") interval = Number(args[++i]) || interval;
+    else if (!args[i].startsWith("--")) target = args[i];
+    else { console.error(`candor-ts-watch: unknown flag ${args[i]}`); process.exit(2); }
+  }
+  if (!target) { console.error("usage: candor-ts-watch <dir> [--out <prefix>] [--interval <ms>]"); process.exit(2); }
+  out ??= path.join(fs.statSync(target).isFile() ? path.dirname(target) : target, ".candor", "report");
+
+  let prev = hashFiles(trackedFiles(target));
+  const first = scanOnce(target, out);
+  console.error(`candor-ts-watch: ${Object.keys(prev).length} source(s) → ${out}.json (${first.ms}ms). Watching… (Ctrl-C to stop)`);
+  if (!first.ok) console.error(first.stderr?.trim());
+
+  setInterval(() => {
+    const cur = hashFiles(trackedFiles(target));
+    const changed = changedFiles(prev, cur);
+    if (!changed.length) return; // the freshness gate: nothing relevant changed, do nothing
+    prev = cur;
+    const before = readReportSafe(out); // the prior report, before this re-scan overwrites it
+    const r = scanOnce(target, out);
+    const names = changed.slice(0, 4).map((f) => rel(f, target)).join(", ") + (changed.length > 4 ? `, +${changed.length - 4}` : "");
+    if (!r.ok) {
+      console.error(`candor-ts-watch: scan FAILED after a change in ${names}: ${r.stderr?.trim()}`);
+      return;
+    }
+    // The edit-delta: what the change DID to the effect surface (the agent-loop payoff).
+    const delta = formatDelta(Q.diff(readReportSafe(out), before).changes);
+    console.error(`candor-ts-watch: re-scanned (${changed.length} changed: ${names}) in ${r.ms}ms`
+                  + (delta ? ` — Δ ${delta}` : " — no effect change"));
+  }, interval);
+  // NO .unref() — the interval is the ONLY thing keeping the process alive; unref'ing it made Node exit
+  // ~0.6s after the startup scan, so the watcher did ONE scan and died while printing "Watching…" (the
+  // whole feature was silently broken, and test-watch.mjs only tests the helpers, never the live loop).
+}
+
+if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) main();