Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
fix(watch): refresh through canonical map ingestion (#421)
Hiro-Chibafef671cca4e9
diff --git a/ix-cli/src/cli/__tests__/map-auto-skip.test.ts b/ix-cli/src/cli/__tests__/map-auto-skip.test.tsindex 8e1861dd..4ef148db 100644--- a/ix-cli/src/cli/__tests__/map-auto-skip.test.ts+++ b/ix-cli/src/cli/__tests__/map-auto-skip.test.ts@@ -1,5 +1,17 @@-import { afterEach, describe, expect, it } from 'vitest';-import { shouldSkipAutoMap } from '../commands/map.js';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import { hostname } from 'node:os';+import { Command } from 'commander';+import { afterEach, describe, expect, it, vi } from 'vitest';+import {+ applyRequestedMapCoalesceExitCode,+ mapModeForIngest,+ registerMapCommand,+ requestedMapCoalesceExitCode,+ shouldSkipAutoMap,+} from '../commands/map.js';+import { lockPathForTest } from '../single-flight.js';describe('shouldSkipAutoMap', () => {afterEach(() => { delete process.env.IX_AUTO_MAP_CLOUD; });@@ -21,3 +33,63 @@ describe('shouldSkipAutoMap', () => {expect(shouldSkipAutoMap({ auto: true, cloudReady: true })).toBe(false);});});++describe('requestedMapCoalesceExitCode', () => {+ it('accepts a private non-zero process exit code', () => {+ expect(requestedMapCoalesceExitCode('75')).toBe(75);+ });++ it.each([undefined, '', '0', '256', '1.5', 'nope'])('ignores invalid value %s', value => {+ expect(requestedMapCoalesceExitCode(value)).toBeUndefined();+ });++ it('applies the requested exit code on the map-lock coalesce path', () => {+ let applied: number | undefined;++ expect(applyRequestedMapCoalesceExitCode('75', code => { applied = code; })).toBe(true);+ expect(applied).toBe(75);+ });++ it('preserves normal exit behavior when the private option is absent', () => {+ const apply = vi.fn();++ expect(applyRequestedMapCoalesceExitCode(undefined, apply)).toBe(false);+ expect(apply).not.toHaveBeenCalled();+ });++ it('makes the real map action exit before ingest when its lock is contended', async () => {+ const lockDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ix-map-coalesce-'));+ const root = path.join(lockDir, 'workspace');+ fs.mkdirSync(root);+ process.env.IX_LOCK_DIR = lockDir;+ process.env.IX_MAP_COALESCE_EXIT_CODE = '75';+ fs.writeFileSync(lockPathForTest(root), JSON.stringify({+ pid: process.pid,+ host: hostname(),+ startedAt: Date.now(),+ label: 'held by test',+ }));++ try {+ const program = new Command();+ registerMapCommand(program);+ await program.parseAsync(['node', 'ix', 'map', root, '--silent']);+ expect(process.exitCode).toBe(75);+ } finally {+ process.exitCode = undefined;+ delete process.env.IX_LOCK_DIR;+ delete process.env.IX_MAP_COALESCE_EXIT_CODE;+ fs.rmSync(lockDir, { recursive: true, force: true });+ }+ });+});++describe('mapModeForIngest', () => {+ it('keeps ordinary map ingestion topology-only', () => {+ expect(mapModeForIngest(undefined)).toBe(true);+ });++ it('lets watch request full canonical patches after the map lock is acquired', () => {+ expect(mapModeForIngest('1')).toBe(false);+ });+});diff --git a/ix-cli/src/cli/__tests__/watch-dedup.test.ts b/ix-cli/src/cli/__tests__/watch-dedup.test.tsindex 5eb30623..861da937 100644--- a/ix-cli/src/cli/__tests__/watch-dedup.test.ts+++ b/ix-cli/src/cli/__tests__/watch-dedup.test.ts@@ -1,57 +1,277 @@-import { describe, it, expect } from "vitest";import * as fs from "node:fs";import * as path from "node:path";-import { readFileContent } from "../commands/watch-utils.js";+import { spawnSync } from "node:child_process";+import { EventEmitter } from "node:events";+import { fileURLToPath } from "node:url";+import { describe, expect, it, vi } from "vitest";+import {+ WatchRefreshScheduler,+ canonicalMapInvocation,+ childCliArgs,+ mapRetryDelay,+ prepareMigratedWorkspaceRefresh,+ runCanonicalMap,+ shouldWatch,+ updatePollingSnapshot,+} from "../commands/watch.js";-const watchTsPath = path.resolve(__dirname, "../commands/watch.ts");-const watchContent = fs.readFileSync(watchTsPath, "utf-8");+describe("WatchRefreshScheduler", () => {+ it("serializes refreshes and coalesces requests made while one is running", async () => {+ let releaseFirst!: () => void;+ const first = new Promise<void>((resolve) => {+ releaseFirst = resolve;+ });+ let runs = 0;+ let active = 0;+ let maxActive = 0;+ const refresh = vi.fn(async () => {+ runs++;+ active++;+ maxActive = Math.max(maxActive, active);+ if (runs === 1) await first;+ active--;+ });+ const errors: unknown[] = [];+ const scheduler = new WatchRefreshScheduler(refresh, (err) => errors.push(err));-// ── Unit tests for readFileContent ──────────────────────────────────+ scheduler.request();+ scheduler.request();+ scheduler.request();+ expect(refresh).toHaveBeenCalledTimes(1);-describe("readFileContent", () => {- it("reads an existing file", () => {- const result = readFileContent(watchTsPath);- expect(result).not.toBeNull();- expect(result).toContain("readFileContent");+ releaseFirst();+ await scheduler.waitForIdle();++ expect(refresh).toHaveBeenCalledTimes(2);+ expect(maxActive).toBe(1);+ expect(errors).toEqual([]);});- it("returns null for non-existent file", () => {- const result = readFileContent("/tmp/ix-test-nonexistent-file-abc123.ts");- expect(result).toBeNull();+ it("reports a failed refresh and remains usable", async () => {+ const failure = new Error("backend rejected patch");+ const refresh = vi.fn().mockRejectedValueOnce(failure).mockResolvedValueOnce(undefined);+ const onError = vi.fn();+ const scheduler = new WatchRefreshScheduler(refresh, onError);++ scheduler.request();+ await scheduler.waitForIdle();+ scheduler.request();+ await scheduler.waitForIdle();++ expect(onError).toHaveBeenCalledWith(failure);+ expect(refresh).toHaveBeenCalledTimes(2);});});-// ── Source-reading: watch.ts watcher correctness ────────────────────+describe("canonical watch refresh", () => {+ it("keeps TypeScript runtime loaders without copying debugger flags", () => {+ expect(+ childCliArgs(+ "/workspace/src/cli/main.ts",+ ["--version"],+ [+ "--inspect=0",+ "--require",+ "/workspace/node_modules/tsx/dist/preflight.cjs",+ "--import=file:///workspace/node_modules/tsx/dist/loader.mjs",+ "--trace-warnings",+ ],+ ),+ ).toEqual([+ "--require",+ "/workspace/node_modules/tsx/dist/preflight.cjs",+ "--import=file:///workspace/node_modules/tsx/dist/loader.mjs",+ "/workspace/src/cli/main.ts",+ "--version",+ ]);+ });-describe("watch.ts watcher correctness", () => {- it("uses content hash for deduplication", () => {- expect(watchContent).toContain("hashContent");- expect(watchContent).toContain("createHash");- expect(watchContent).toContain('lastHash.get(filePath) === hash');+ it("drops parent runtime flags for a built JavaScript entry", () => {+ expect(+ childCliArgs(+ "/workspace/dist/cli/main.js",+ ["--help"],+ ["--inspect=0", "--require", "preflight.cjs", "--import", "loader.mjs"],+ ),+ ).toEqual(["/workspace/dist/cli/main.js", "--help"]);});- it("re-reads file at ingest time, not event time", () => {- // readFileContent called inside ingestFile, not in the event handler- expect(watchContent).toContain("readFileContent(filePath)");- // The debounce callback does NOT read the file- expect(watchContent).toContain("content is re-read at ingest time");+ it("starts both the tsx source CLI and a normal built CLI child", () => {+ const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");+ const tempRoot = fs.mkdtempSync(path.join(packageRoot, ".watch-child-runtime-"));+ const ixHome = path.join(tempRoot, "ix-home");+ fs.mkdirSync(ixHome);+ fs.writeFileSync(+ path.join(ixHome, ".version-check.json"),+ JSON.stringify({ latest: "0.9.3", checkedAt: Date.now() }),+ );+ const env = { ...process.env, IX_HOME: ixHome, NO_COLOR: "1" };++ try {+ const sourceEntry = path.join(packageRoot, "src/cli/main.ts");+ const source = spawnSync(+ process.execPath,+ childCliArgs(sourceEntry, ["--version"], ["--inspect=0", "--import", "tsx"]),+ { cwd: packageRoot, env, encoding: "utf8" },+ );+ expect(source.status, source.stderr).toBe(0);+ expect(source.stdout.trim()).toBe("0.9.3");+ expect(source.stderr).not.toContain("Debugger listening");++ const outDir = path.join(tempRoot, "dist");+ const build = spawnSync(+ process.execPath,+ [+ path.join(packageRoot, "node_modules/typescript/bin/tsc"),+ "-p",+ path.join(packageRoot, "tsconfig.build.json"),+ "--outDir",+ outDir,+ "--declaration",+ "false",+ ],+ { cwd: packageRoot, env, encoding: "utf8" },+ );+ expect(build.status, build.stderr || build.stdout).toBe(0);++ const builtEntry = path.join(outDir, "cli/main.js");+ const built = spawnSync(+ process.execPath,+ childCliArgs(builtEntry, ["--help"], ["--inspect=0", "--import", "tsx"]),+ { cwd: packageRoot, env, encoding: "utf8" },+ );+ expect(built.status, built.stderr).toBe(0);+ expect(built.stdout).toContain("ix — System Intelligence CLI");+ expect(built.stderr).not.toContain("Debugger listening");+ } finally {+ fs.rmSync(tempRoot, { recursive: true, force: true });+ }+ }, 30_000);++ it("delegates the workspace root to the existing map command with full ingest enabled", () => {+ const root = "/workspace/project";+ const entry = "/workspace/dist/cli/main.js";+ const map = canonicalMapInvocation(root, entry, ["--inspect=0"]);++ expect(map.command).toBe(process.execPath);+ expect(map.args).toEqual([entry, "map", root, "--silent"]);+ expect(map.env.IX_AUTO_MAP).toBe("1");+ expect(map.env.IX_MAP_FULL_INGEST).toBe("1");+ expect(map.env.IX_MAP_COALESCE_EXIT_CODE).toBe("75");});- it("uses short debounce (300ms)", () => {- expect(watchContent).toContain("DEBOUNCE_MS = 300");+ it("retries a map coalesced by another process so the change is not lost", async () => {+ const exits = [75, 0];+ const launch = vi.fn(() => {+ const child = new EventEmitter();+ queueMicrotask(() => child.emit("exit", exits.shift(), null));+ return child as any;+ });+ const wait = vi.fn().mockResolvedValue(undefined);++ await runCanonicalMap("/workspace/project", launch, wait);++ expect(launch).toHaveBeenCalledTimes(2);+ expect(wait).toHaveBeenCalledOnce();});- it("tracks last hash per file", () => {- expect(watchContent).toContain("lastHash");- expect(watchContent).toContain("lastHash.set(filePath, hash)");+ it("propagates a canonical map failure without spinning", async () => {+ const launch = vi.fn(() => {+ const child = new EventEmitter();+ queueMicrotask(() => child.emit("exit", 2, null));+ return child as any;+ });++ await expect(runCanonicalMap("/workspace/project", launch)).rejects.toThrow(+ "ix map failed (exit 2)",+ );+ expect(launch).toHaveBeenCalledOnce();});- it("skips ingest when content hash unchanged", () => {- expect(watchContent).toContain("unchanged (hash)");+ it("gives up on a lock that is never released instead of retrying forever", async () => {+ // A holder that never exits 0 — a crashed process whose lockfile outlived+ // it. Unbounded, this spawned a Node process every second indefinitely.+ const launch = vi.fn(() => {+ const child = new EventEmitter();+ queueMicrotask(() => child.emit("exit", 75, null));+ return child as any;+ });+ const wait = vi.fn().mockResolvedValue(undefined);++ await expect(runCanonicalMap("/workspace/project", launch, wait, () => {})).rejects.toThrow(+ /stayed coalesced across \d+ attempts/,+ );+ expect(launch.mock.calls.length).toBeLessThanOrEqual(45);+ expect(wait).toHaveBeenCalledTimes(launch.mock.calls.length);});- it("coalesces rapid events per file via debounce map", () => {- expect(watchContent).toContain("pending.get(fullPath)");- expect(watchContent).toContain("clearTimeout(existing)");+ it("tells the user why it is waiting, since the child map runs --silent", async () => {+ const exits = [75, 75, 75, 0];+ const launch = vi.fn(() => {+ const child = new EventEmitter();+ queueMicrotask(() => child.emit("exit", exits.shift(), null));+ return child as any;+ });+ const notify = vi.fn();++ await runCanonicalMap("/workspace/project", launch, vi.fn().mockResolvedValue(undefined), notify);++ expect(notify).toHaveBeenCalledOnce();+ expect(notify.mock.calls[0]![0]).toMatch(/another ix map holds this workspace/);+ });++ it("backs off exponentially up to a ceiling", () => {+ expect([1, 2, 3, 4, 5, 6].map(mapRetryDelay)).toEqual([1000, 2000, 4000, 8000, 16000, 30000]);+ // Capped, so a long wait costs attempts rather than unbounded sleep growth.+ expect(mapRetryDelay(45)).toBe(30000);+ // 45 attempts spans past single-flight's 20-minute stale-lock window.+ const total = Array.from({ length: 45 }, (_, i) => mapRetryDelay(i + 1)).reduce((a, b) => a + b, 0);+ expect(total).toBeGreaterThan(20 * 60 * 1000);+ });++ it("keeps delete events eligible without requiring the file to exist", () => {+ expect(shouldWatch("/workspace/project", "/workspace/project/deleted.ts")).toBe(true);+ });++ it("clears the parent's baseline before migration refresh crosses into a child process", () => {+ const clear = vi.fn();+ const root = "/workspace/migrated";++ prepareMigratedWorkspaceRefresh(root, clear);++ expect(clear).toHaveBeenCalledWith(root);+ expect(canonicalMapInvocation(root, "/workspace/dist/cli/main.js").args).toEqual([+ "/workspace/dist/cli/main.js",+ "map",+ root,+ "--silent",+ ]);+ });+});++describe("updatePollingSnapshot", () => {+ it("detects new, modified, and deleted files", () => {+ const mtimes = new Map([+ ["kept.ts", 1],+ ["changed.ts", 1],+ ["deleted.ts", 1],+ ]);+ const current = ["kept.ts", "changed.ts", "new.ts"];+ const values = new Map([+ ["kept.ts", 1],+ ["changed.ts", 2],+ ["new.ts", 3],+ ]);++ const changed = updatePollingSnapshot(current, mtimes, (filePath) => values.get(filePath)!);++ expect(changed).toEqual(["changed.ts", "new.ts", "deleted.ts"]);+ expect(mtimes).toEqual(values);+ });++ it("detects a backwards mtime change instead of requiring mtime to increase", () => {+ const mtimes = new Map([["restored.ts", 10]]);++ expect(updatePollingSnapshot(["restored.ts"], mtimes, () => 5)).toEqual(["restored.ts"]);});});diff --git a/ix-cli/src/cli/commands/map.ts b/ix-cli/src/cli/commands/map.tsindex e195a01c..b3662ebc 100644--- a/ix-cli/src/cli/commands/map.ts+++ b/ix-cli/src/cli/commands/map.ts@@ -38,6 +38,30 @@ export function shouldSkipAutoMap(opts: { auto: boolean; cloudReady: boolean }):return true;}+/** Optional exit code for callers that must distinguish coalescing from success. */+export function requestedMapCoalesceExitCode(+ raw = process.env.IX_MAP_COALESCE_EXIT_CODE,+): number | undefined {+ if (raw === undefined) return undefined;+ const code = Number(raw);+ return Number.isInteger(code) && code >= 1 && code <= 255 ? code : undefined;+}++export function applyRequestedMapCoalesceExitCode(+ raw = process.env.IX_MAP_COALESCE_EXIT_CODE,+ apply: (code: number) => void = code => { process.exitCode = code; },+): boolean {+ const code = requestedMapCoalesceExitCode(raw);+ if (code === undefined) return false;+ apply(code);+ return true;+}++/** Watch opts into full patches; ordinary `ix map` keeps its topology-only ingest. */+export function mapModeForIngest(raw = process.env.IX_MAP_FULL_INGEST): boolean {+ return raw !== "1";+}+export interface MapRegion {id: string;label: string;@@ -175,6 +199,7 @@ Examples:if (!silent && opts.format !== "json" && opts.format !== "llm") {process.stderr.write(chalk.dim(" Another ix map is already running for this workspace — skipping.\n"));}+ applyRequestedMapCoalesceExitCode();return; // coalesce; the in-flight map will refresh the graph}@@ -256,7 +281,7 @@ Examples:format: (machineFormat || silent) ? "json" : "text",printSummary: false,suppressOutput: true,- mapMode: true,+ mapMode: mapModeForIngest(),deadlineSignal,// `ix map` has no --debug, so the per-file `[commit error] <uri>`// detail was unreachable from the command that produced thediff --git a/ix-cli/src/cli/commands/watch.ts b/ix-cli/src/cli/commands/watch.tsindex d0710807..f4964213 100644--- a/ix-cli/src/cli/commands/watch.ts+++ b/ix-cli/src/cli/commands/watch.ts@@ -1,14 +1,11 @@import * as fs from "node:fs";import * as path from "node:path";-import * as crypto from "node:crypto";+import { spawn } from "node:child_process";+import type { SpawnOptions } from "node:child_process";import type { Command } from "commander";import chalk from "chalk";-import { spawnSync } from "node:child_process";-import { IxClient } from "../../client/api.js";-import { getEndpoint, resolveWorkspaceRoot, clearIngestMtimeCache } from "../config.js";-import { bootstrap, ensureWorkspaceId, ensureWorkspaceIdState } from "../bootstrap.js";-import { loadWatchIngestionModules } from "./ingestion-loader.js";-import { readFileContent } from "./watch-utils.js";+import { resolveWorkspaceRoot, clearIngestMtimeCache } from "../config.js";+import { bootstrap, ensureWorkspaceIdState } from "../bootstrap.js";import { SUPPORTED_EXTENSIONS } from "../supported-extensions.js";const SUPPORTED_NAMES = new Set([@@ -24,21 +21,263 @@ const IGNORE_DIRS = new Set([]);const DEBOUNCE_MS = 300;+const MAP_COALESCED_EXIT_CODE = 75;+const MAP_RETRY_MS = 1000;+const MAP_RETRY_MAX_MS = 30_000;+/**+ * How many times a coalesced map is retried before the refresh is given up on.+ *+ * The backoff below reaches its 30s ceiling after five doublings (31s of+ * waiting), so 45 attempts spans roughly 21 minutes. That is deliberately just+ * past `DEFAULT_LOCK_MAX_MS` in single-flight.ts (20 min), which is the point at+ * which a lock whose holder died is stolen — so a genuinely long map is still+ * waited out, and only a lock that outlives its own staleness window gives up.+ *+ * A fixed 1s retry with no ceiling reached that same 20 minutes in ~1,200 Node+ * process spawns. This reaches it in 45.+ */+const MAP_RETRY_ATTEMPTS = 45;+/** Retrying silently for minutes looks identical to a watcher that has died. */+const MAP_RETRY_NOTIFY_AFTER = 3;-/** Compute SHA-256 hash of file content for dedup. */-function hashContent(content: string): string {- return crypto.createHash("sha256").update(content).digest("hex");+interface MapChild {+ once(event: "error", listener: (err: Error) => void): unknown;+ once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;}-/**- * Convert an absolute path to a workspace-relative POSIX path. This is the- * canonical source_uri and the basis for every deterministic node/edge/chunk- * id, so it must match what `ix ingest` emits (see toWorkspaceRelative in- * ingest.ts). Forcing POSIX separators keeps ids stable across operating- * systems and never embeds an absolute host path.- */-function toWorkspaceRelative(root: string, absPath: string): string {- return path.relative(root, absPath).split(path.sep).join("/");+type MapLauncher = (command: string, args: string[], options: SpawnOptions) => MapChild;++const RUNTIME_LOADER_FLAGS = new Set([+ "--import", "--loader", "--experimental-loader", "--require", "-r",+]);++/** Preserve source loaders for a TypeScript CLI entry without cloning debugger flags. */+export function childCliArgs(+ entry: string,+ cliArgs: string[],+ execArgv: string[] = process.execArgv,+): string[] {+ if (!/\.[cm]?tsx?$/.test(entry)) return [entry, ...cliArgs];++ const loaders: string[] = [];+ for (let index = 0; index < execArgv.length; index++) {+ const arg = execArgv[index]!;+ if (RUNTIME_LOADER_FLAGS.has(arg)) {+ const value = execArgv[index + 1];+ if (value !== undefined) {+ loaders.push(arg, value);+ index++;+ }+ continue;+ }+ if (+ [...RUNTIME_LOADER_FLAGS].some(flag => arg.startsWith(`${flag}=`)) ||+ (arg.startsWith("-r") && !arg.startsWith("--") && arg.length > 2)+ ) {+ loaders.push(arg);+ }+ }++ return [...loaders, entry, ...cliArgs];+}++export function canonicalMapInvocation(+ root: string,+ entry = process.argv[1],+ execArgv = process.execArgv,+): { command: string; args: string[]; env: NodeJS.ProcessEnv } {+ if (!entry) throw new Error("Could not locate the Ix CLI entry point.");+ return {+ command: process.execPath,+ args: childCliArgs(entry, ["map", root, "--silent"], execArgv),+ env: {+ ...process.env,+ IX_AUTO_MAP: "1",+ IX_MAP_FULL_INGEST: "1",+ IX_MAP_COALESCE_EXIT_CODE: String(MAP_COALESCED_EXIT_CODE),+ },+ };+}++function runChild(+ invocation: ReturnType<typeof canonicalMapInvocation>,+ launch: MapLauncher,+): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {+ return new Promise((resolve, reject) => {+ const child = launch(invocation.command, invocation.args, {+ env: invocation.env,+ stdio: "inherit",+ });+ child.once("error", reject);+ child.once("exit", (code, signal) => {+ if (code === 0 || code === MAP_COALESCED_EXIT_CODE) {+ resolve({ code, signal });+ } else {+ reject(new Error(`ix map failed${signal ? ` (${signal})` : ` (exit ${code ?? 1})`}`));+ }+ });+ });+}++/** Exponential backoff, capped, so a held lock costs attempts rather than spawns. */+export function mapRetryDelay(attempt: number): number {+ return Math.min(MAP_RETRY_MS * 2 ** (attempt - 1), MAP_RETRY_MAX_MS);+}++export async function runCanonicalMap(+ root: string,+ launch: MapLauncher = spawn as MapLauncher,+ wait: (ms: number) => Promise<void> = ms => new Promise(resolve => setTimeout(resolve, ms)),+ notify: (message: string) => void = message => console.error(`${chalk.dim("[watch]")} ${message}`),+): Promise<void> {+ const invocation = canonicalMapInvocation(root);+ for (let attempt = 1; attempt <= MAP_RETRY_ATTEMPTS; attempt++) {+ const { code } = await runChild(invocation, launch);+ if (code === 0) return;+ // Exit 75 means another ix map holds the workspace lock. The child runs+ // --silent, so without this the watcher looks hung rather than patient.+ if (attempt === MAP_RETRY_NOTIFY_AFTER) {+ notify("another ix map holds this workspace; waiting for it to finish...");+ }+ await wait(mapRetryDelay(attempt));+ }+ throw new Error(+ `ix map stayed coalesced across ${MAP_RETRY_ATTEMPTS} attempts; another ix map has held the workspace lock the whole time`,+ );+}++/** Serialize refreshes and coalesce changes during a run into one trailing refresh. */+export class WatchRefreshScheduler {+ private running = false;+ private queued = false;+ private idleWaiters: Array<() => void> = [];++ constructor(+ private readonly refresh: () => Promise<void>,+ private readonly onError: (err: unknown) => void,+ ) {}++ request(): void {+ this.queued = true;+ if (!this.running) void this.drain();+ }++ waitForIdle(): Promise<void> {+ if (!this.running && !this.queued) return Promise.resolve();+ return new Promise(resolve => this.idleWaiters.push(resolve));+ }++ private async drain(): Promise<void> {+ this.running = true;+ try {+ while (this.queued) {+ this.queued = false;+ try {+ await this.refresh();+ } catch (err) {+ this.onError(err);+ }+ }+ } finally {+ this.running = false;+ for (const resolve of this.idleWaiters.splice(0)) resolve();+ }+ }+}++/** Detect new, changed, and deleted files while advancing the polling snapshot. */+export function updatePollingSnapshot(+ currentFiles: string[],+ mtimes: Map<string, number>,+ statMtime: (filePath: string) => number = filePath => fs.statSync(filePath).mtimeMs,+): string[] {+ const next = new Map<string, number>();+ const changed: string[] = [];++ for (const filePath of currentFiles) {+ try {+ const mtime = statMtime(filePath);+ next.set(filePath, mtime);+ if (mtimes.get(filePath) !== mtime) changed.push(filePath);+ } catch {+ // A racy delete is handled by the missing-file pass below.+ }+ }++ const current = new Set(next.keys());+ for (const filePath of mtimes.keys()) {+ if (!current.has(filePath)) changed.push(filePath);+ }++ mtimes.clear();+ for (const [filePath, mtime] of next) mtimes.set(filePath, mtime);+ return changed;+}++function isSupportedPath(filePath: string): boolean {+ const ext = path.extname(filePath).toLowerCase();+ return SUPPORTED_EXTENSIONS.has(ext) || SUPPORTED_NAMES.has(path.basename(filePath));+}++export function shouldWatch(root: string, filePath: string): boolean {+ if (!isSupportedPath(filePath)) return false;+ const segments = path.relative(root, filePath).split(path.sep);+ return !segments.some(segment => IGNORE_DIRS.has(segment));+}++export function prepareMigratedWorkspaceRefresh(+ root: string,+ clear: (workspaceRoot: string) => void = clearIngestMtimeCache,+): void {+ clear(root);+}++function collectFiles(dir: string): string[] {+ const results: string[] = [];+ const stack = [dir];+ while (stack.length > 0) {+ const current = stack.pop()!;+ let entries: fs.Dirent[];+ try { entries = fs.readdirSync(current, { withFileTypes: true }); }+ catch { continue; }+ for (const entry of entries) {+ if (IGNORE_DIRS.has(entry.name)) continue;+ if (entry.name.startsWith(".") && entry.isDirectory()) continue;+ const fullPath = path.join(current, entry.name);+ if (entry.isDirectory()) stack.push(fullPath);+ else if (entry.isFile() && isSupportedPath(fullPath)) results.push(fullPath);+ }+ }+ return results;+}++function createBatchNotifier(root: string, scheduler: WatchRefreshScheduler): {+ notify(filePath: string): void;+ cancel(): void;+} {+ const pending = new Set<string>();+ let timer: NodeJS.Timeout | undefined;++ const flush = () => {+ timer = undefined;+ for (const filePath of [...pending].sort()) {+ console.log(`${chalk.dim("[watch]")} changed: ${path.relative(root, filePath)}`);+ }+ pending.clear();+ scheduler.request();+ };++ return {+ notify(filePath: string) {+ pending.add(filePath);+ if (timer) clearTimeout(timer);+ timer = setTimeout(flush, DEBOUNCE_MS);+ },+ cancel() {+ if (timer) clearTimeout(timer);+ pending.clear();+ },+ };}export function registerWatchCommand(program: Command): void {@@ -48,24 +287,15 @@ export function registerWatchCommand(program: Command): void {.option("--path <path>", "Restrict watching to a subdirectory").option("--root <dir>", "Workspace root directory").action(async (opts: { path?: string; root?: string }) => {+ const root = path.resolve(resolveWorkspaceRoot(opts.root));try {- await bootstrap();+ await bootstrap(root);} catch (err: any) {console.error(chalk.red("Error:"), err.message);process.exit(1);}- const root = resolveWorkspaceRoot(opts.root);- const { workspaceId, migrated } = ensureWorkspaceIdState(root);- // If the workspace_id was just migrated to the path-based id (Ix#225 gap 2), the- // new id has no nodes yet and watch only ingests files as they change — so do a- // one-time full re-ingest under the new id first (clear the mtime cache so the- // spawned map re-ingests everything, then run it synchronously before watching).- if (migrated) {- console.error(chalk.dim("[watch] Workspace migrated to a stable id; re-ingesting once before watching..."));- clearIngestMtimeCache(root);- spawnSync(process.argv[0], [process.argv[1], "map", root, "--silent"], { stdio: "inherit" });- }+ const { migrated } = ensureWorkspaceIdState(root);const watchPath = opts.path? path.resolve(root, opts.path): root;@@ -75,88 +305,36 @@ export function registerWatchCommand(program: Command): void {process.exit(1);}- const client = new IxClient(getEndpoint());+ const refresh = () => runCanonicalMap(root);+ const scheduler = new WatchRefreshScheduler(refresh, err =>+ console.error(`${chalk.red("[watch]")} refresh error: ${(err as Error).message}`)+ );++ if (migrated) {+ console.error(chalk.dim("[watch] Workspace migrated to a stable id; re-ingesting once before watching..."));+ prepareMigratedWorkspaceRefresh(root);+ await refresh();+ }const relative = path.relative(root, watchPath) || ".";console.log(chalk.cyan(`[watch] Watching ${relative}`));console.log(chalk.dim(`[watch] Debounce: ${DEBOUNCE_MS}ms`));console.log(chalk.dim("[watch] Press Ctrl+C to stop.\n"));- // Track pending changes with debounce + content hash dedup- const pending = new Map<string, NodeJS.Timeout>();- const lastHash = new Map<string, string>();-- function shouldWatch(filePath: string): boolean {- const ext = path.extname(filePath).toLowerCase();- const basename = path.basename(filePath);- if (!SUPPORTED_EXTENSIONS.has(ext) && !SUPPORTED_NAMES.has(basename)) return false;- // Check no segment is an ignored dir- const segments = path.relative(root, filePath).split(path.sep);- return !segments.some(s => IGNORE_DIRS.has(s));- }-- async function ingestFile(filePath: string): Promise<void> {- const [{ parseFile }, { buildPatch }] = await loadWatchIngestionModules();- // Workspace-relative POSIX path drives source_uri and node identity; it- // must match `ix ingest` or the same file ingested via watch vs ingest- // would mint divergent node ids and reintroduce absolute-path coupling.- const relPath = toWorkspaceRelative(root, filePath);-- // Re-read content at actual ingest time (not at event time)- const content = readFileContent(filePath);- if (content === null) return;-- // Skip if content hash is unchanged since last ingest- const hash = hashContent(content);- if (lastHash.get(filePath) === hash) {- console.log(`${chalk.dim("[watch]")} unchanged (hash): ${relPath}`);- return;- }-- try {- const parsed = parseFile(relPath, content);- if (!parsed) {- console.log(`${chalk.dim("[watch]")} skipped (unsupported): ${relPath}`);- return;- }- const patch = buildPatch(parsed, hash, workspaceId);- const result = await client.commitPatch(patch);- lastHash.set(filePath, hash);- console.log(`${chalk.cyan("[watch]")} ingested: ${chalk.bold(relPath)} → rev ${result.rev}`);- } catch (err: any) {- console.error(`${chalk.red("[watch]")} error ingesting ${relPath}: ${err.message}`);- }- }+ const batch = createBatchNotifier(root, scheduler);// Use fs.watch recursivelytry {const watcher = fs.watch(watchPath, { recursive: true }, (_event, filename) => {if (!filename) return;const fullPath = path.resolve(watchPath, filename);- if (!shouldWatch(fullPath)) return;-- // Check file still exists (might be a delete event)- if (!fs.existsSync(fullPath)) return;-- const rel = path.relative(root, fullPath);-- // Cancel any existing debounce for this file- const existing = pending.get(fullPath);- if (existing) clearTimeout(existing);-- // Set new debounce — content is re-read at ingest time, not here- pending.set(fullPath, setTimeout(async () => {- pending.delete(fullPath);- console.log(`${chalk.dim("[watch]")} changed: ${rel}`);- await ingestFile(fullPath);- }, DEBOUNCE_MS));+ if (shouldWatch(root, fullPath)) batch.notify(fullPath);});// Keep process aliveprocess.on("SIGINT", () => {watcher.close();- // Clear pending timers- for (const timer of pending.values()) clearTimeout(timer);+ batch.cancel();console.log(chalk.dim("\n[watch] Stopped."));process.exit(0);});@@ -164,7 +342,7 @@ export function registerWatchCommand(program: Command): void {// Fallback to polling if fs.watch with recursive isn't supportedif (err.code === "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM") {console.log(chalk.dim("[watch] Falling back to polling mode (2s interval)..."));- await pollMode(watchPath, root, client);+ pollMode(watchPath, root, scheduler);} else {throw err;}@@ -175,81 +353,29 @@ export function registerWatchCommand(program: Command): void {/*** Fallback polling mode for platforms where recursive fs.watch isn't available.*/-async function pollMode(+function pollMode(watchPath: string,root: string,- client: IxClient-): Promise<void> {- const [{ parseFile }, { buildPatch }] = await loadWatchIngestionModules();- const workspaceId = ensureWorkspaceId(root);+ scheduler: WatchRefreshScheduler,+): void {const mtimes = new Map<string, number>();- function collectFiles(dir: string): string[] {- const results: string[] = [];- const stack = [dir];- while (stack.length > 0) {- const current = stack.pop()!;- let entries: fs.Dirent[];- try { entries = fs.readdirSync(current, { withFileTypes: true }); }- catch { continue; }- for (const entry of entries) {- if (IGNORE_DIRS.has(entry.name)) continue;- if (entry.name.startsWith(".") && entry.isDirectory()) continue;- const fullPath = path.join(current, entry.name);- if (entry.isDirectory()) {- stack.push(fullPath);- } else if (entry.isFile()) {- const ext = path.extname(entry.name).toLowerCase();- if (SUPPORTED_EXTENSIONS.has(ext) || SUPPORTED_NAMES.has(entry.name)) {- results.push(fullPath);- }- }- }- }- return results;- }-// Initial scanfor (const f of collectFiles(watchPath)) {try { mtimes.set(f, fs.statSync(f).mtimeMs); } catch {}}- const poll = async () => {- const currentFiles = collectFiles(watchPath);- const changed: string[] = [];-- for (const f of currentFiles) {- try {- const mtime = fs.statSync(f).mtimeMs;- const prev = mtimes.get(f);- if (prev === undefined || mtime > prev) {- changed.push(f);- mtimes.set(f, mtime);- }- } catch {}+ const interval = setInterval(() => {+ const changed = updatePollingSnapshot(collectFiles(watchPath), mtimes);+ if (changed.length === 0) return;+ for (const filePath of changed.sort()) {+ console.log(`${chalk.dim("[watch]")} changed: ${path.relative(root, filePath)}`);}-- for (const f of changed) {- const relPath = toWorkspaceRelative(root, f);- console.log(`${chalk.dim("[watch]")} changed: ${relPath}`);- try {- const content = readFileContent(f);- if (!content) continue;- const parsed = parseFile(relPath, content);- if (!parsed) continue;- const hash = hashContent(content);- const patch = buildPatch(parsed, hash, workspaceId);- const result = await client.commitPatch(patch);- console.log(`${chalk.cyan("[watch]")} ingested: ${chalk.bold(relPath)} → rev ${result.rev}`);- } catch (err: any) {- console.error(`${chalk.red("[watch]")} error: ${err.message}`);- }- }- };-- setInterval(poll, 2000);+ scheduler.request();+ }, 2000);process.on("SIGINT", () => {+ clearInterval(interval);console.log(chalk.dim("\n[watch] Stopped."));process.exit(0);});