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(map): a coalesced ix map leaves a rerun marker; the lock is never stolen from a live holder
KageBinary61bfbe9bf7fb
diff --git a/ix-cli/src/cli/__tests__/map-result-cache.test.ts b/ix-cli/src/cli/__tests__/map-result-cache.test.tsindex 0aa5d0c8..7c783852 100644--- a/ix-cli/src/cli/__tests__/map-result-cache.test.ts+++ b/ix-cli/src/cli/__tests__/map-result-cache.test.ts@@ -25,7 +25,8 @@ import {saveCachedMap,type MapCacheSlot,} from "../map-result-cache.js";-import { lockPathForTest } from "../single-flight.js";+import { acquireMapLock, lockPathForTest, requestMapRerun, takeMapRerun } from "../single-flight.js";+import { createHash } from "node:crypto";/*** `ix map` reuses its last `/v1/map` response when a run ingested nothing and@@ -51,6 +52,8 @@ class FakeBackend {revisionRecord = false;release = "1.0.30";systemId: string | null = null;+ /** Run on the next commit request, then cleared. */+ onCommit: (() => void) | undefined;readonly hashes = new Map<string, { workspaceId: string | null; uri: string; hash: string }>();private readonly patches = new Map<string, unknown[]>();private server: Server | undefined;@@ -88,6 +91,10 @@ class FakeBackend {};if (path === "/v1/patches/bulk" || path === "/v1/patch") {+ // Fired once, mid-run: what happens in the world while a map commits.+ const hook = this.onCommit;+ this.onCommit = undefined;+ hook?.();type SentPatch = { patchId?: string; source?: { uri?: string; sourceHash?: string; workspaceId?: string }; intent?: string; ops?: unknown[] };let patches: SentPatch[] = [];try {@@ -236,6 +243,45 @@ describe("ix map reuses an unchanged map", () => {}});+ describe("a map that coalesces is not lost", () => {+ const hashOf = (text: string) => createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");+ const stored = (uri: string) => [...backend.hashes.values()].find(row => row.uri === uri)?.hash;++ it("a coalescing map leaves a rerun request for the holder", async () => {+ const holder = acquireMapLock(repo, "holder")!;+ try {+ await map("--silent");+ expect(takeMapRerun(repo)).toBe(true);+ } finally {+ holder.release();+ }+ });++ it("the holder runs once more for an edit made while it was committing", async () => {+ await map("--silent");+ writeFileSync(join(repo, "src", "m1.ts"), "export const changed = 1;\n", "utf8");+ const late = "export const late = 2;\n";+ // Mid-commit: an edit lands after this run read the tree, and the+ // editor's own `ix map` coalesces.+ backend.onCommit = () => {+ writeFileSync(join(repo, "src", "m2.ts"), late, "utf8");+ requestMapRerun(repo);+ };++ await map("--silent");++ expect(stored("src/m2.ts"), "the late edit reached the backend in this invocation").toBe(hashOf(late));+ expect(takeMapRerun(repo), "the request was consumed").toBe(false);+ });++ it("a request left before a map starts is satisfied by that map, not rerun", async () => {+ requestMapRerun(repo);+ await map("--silent");+ const commits = backend.requests.filter(p => p === "/v1/patches/bulk" || p === "/v1/patch").length;+ expect(commits, "one ingest, not two").toBe(1);+ });+ });+it("makes no map request for an unchanged repo, and prints the same thing", async () => {// The first map ingests everything, which the output reports; every run// compared below ingests nothing.diff --git a/ix-cli/src/cli/__tests__/single-flight.test.ts b/ix-cli/src/cli/__tests__/single-flight.test.tsindex 30cfcd48..77f705d9 100644--- a/ix-cli/src/cli/__tests__/single-flight.test.ts+++ b/ix-cli/src/cli/__tests__/single-flight.test.ts@@ -1,11 +1,11 @@// Copyright 2026 Ix Infrastructure Inc.import { afterEach, beforeEach, describe, expect, it } from 'vitest';-import { mkdtempSync, rmSync, writeFileSync, readdirSync, existsSync } from 'node:fs';+import { mkdtempSync, rmSync, writeFileSync, readdirSync, existsSync, utimesSync } from 'node:fs';import { join } from 'node:path';import { tmpdir, hostname } from 'node:os';-import { acquireMapLock, isStaleForTest, lockPathForTest } from '../single-flight.js';+import { acquireMapLock, isStaleForTest, lockPathForTest, requestMapRerun, takeMapRerun } from '../single-flight.js';describe('acquireMapLock single-flight', () => {let dir: string;@@ -68,24 +68,60 @@ describe('acquireMapLock single-flight', () => {h!.release();});- it('steals a lock older than the max age even if the holder looks alive', () => {+ it('steals a lock whose holder has not touched it for the max age, even if its pid looks alive', () => {+ // A wedged holder, or a pid reused by an unrelated process.process.env.IX_MAP_LOCK_MAX_MS = '1000';const path = lockPathForTest('/work/repo');writeFileSync(path, JSON.stringify({ pid: process.pid, host: hostname(), startedAt: Date.now() - 60_000, label: 'old' }));+ const old = new Date(Date.now() - 60_000);+ utimesSync(path, old, old);const h = acquireMapLock('/work/repo', 'm');- expect(h).not.toBeNull(); // aged out → stolen+ expect(h).not.toBeNull(); // silent for longer than the max → stolenh!.release();});- it('treats an unparseable lockfile as abandoned', () => {+ it('does not steal a live holder that started long ago but is still working', () => {+ // It was measured from startedAt: a map running longer than the max was+ // taken over and a second map ran beside it.+ process.env.IX_MAP_LOCK_MAX_MS = '1000';+ const path = lockPathForTest('/work/repo');+ writeFileSync(path, JSON.stringify({ pid: process.pid, host: hostname(), startedAt: Date.now() - 60_000, label: 'long' }));+ expect(acquireMapLock('/work/repo', 'm')).toBeNull();+ });++ it('treats an unparseable lockfile as abandoned once it has sat for a moment', () => {const path = lockPathForTest('/work/repo');writeFileSync(path, 'not json');+ // Locks are now linked into place whole, so a fresh empty or torn file is+ // not a holder mid-write -- but it is still given a few seconds.+ expect(isStaleForTest(path)).toBe(false);+ const old = new Date(Date.now() - 10_000);+ utimesSync(path, old, old);expect(isStaleForTest(path)).toBe(true);const h = acquireMapLock('/work/repo', 'm');expect(h).not.toBeNull();h!.release();});+ it('a release does not delete a lock that is no longer its own', () => {+ // The holder was taken over as stale; letting go must not free the+ // successor's lock and admit a third runner.+ const path = lockPathForTest('/work/repo');+ const first = acquireMapLock('/work/repo', 'first')!;+ writeFileSync(path, JSON.stringify({ pid: process.pid, host: hostname(), startedAt: Date.now() + 1, label: 'successor' }));+ first.release();+ expect(existsSync(path)).toBe(true);+ expect(acquireMapLock('/work/repo', 'third')).toBeNull();+ });++ it('a coalesced map leaves a rerun request the holder takes once', () => {+ expect(takeMapRerun('/work/repo')).toBe(false);+ requestMapRerun('/work/repo');+ requestMapRerun('/work/repo');+ expect(takeMapRerun('/work/repo')).toBe(true);+ expect(takeMapRerun('/work/repo')).toBe(false);+ });+it('does not leak across a missing lock dir (fail-open is best-effort)', () => {// Sanity: a brand-new dir yields a clean acquire.expect(existsSync(dir)).toBe(true);diff --git a/ix-cli/src/cli/commands/map.ts b/ix-cli/src/cli/commands/map.tsindex 78ca3aea..d596724e 100644--- a/ix-cli/src/cli/commands/map.ts+++ b/ix-cli/src/cli/commands/map.ts@@ -11,7 +11,7 @@ import { formatFetchError } from "../errors.js";import { ingestFiles, type IngestFilesSummary } from "./ingest.js";import { detectSystem } from "../system.js";import { getRemoteRunner, isCloudReady } from "../remote.js";-import { acquireMapLock } from "../single-flight.js";+import { acquireMapLock, requestMapRerun, takeMapRerun } from "../single-flight.js";import { canRenderProgress } from "../stderr.js";import { loadIngestBaseline } from "../ingest-baseline.js";import { saveMapBaseline } from "../map-baseline.js";@@ -404,301 +404,12 @@ Examples:ix map . --full --verbose`).action(async (pathArg: string | undefined, opts: { format: string; level?: string; minConfidence: string; maxItems: string; allItems?: boolean; sort: string; graph?: boolean; list?: boolean; full?: boolean; verbose?: boolean; silent?: boolean }) => {- let cwd: string;+ const held: HeldMap = {};try {- cwd = resolveMapRoot(pathArg);- } catch (err: any) {- const message = err?.message ?? "Invalid map path";- if (opts.format === "json") {- printJson({ error: "invalid_map_path", message });- } else if (opts.format === "llm") {- console.log(llmError("invalid_map_path", message));- } else {- console.error(chalk.red("Error:"), message);- }- process.exitCode = 1;- return;+ await runMapCommand(pathArg, opts, held);+ } finally {+ if (held.root) await rerunIfRequested(held.root, held.local === true, opts);}-- const silent = opts.silent === true || opts.format === "silent";-- // Single-flight: refuse to stack. Background refresh can fire `ix map`- // repeatedly (e.g. once per change); if a map is slow or the backend is- // unhealthy, those invocations would otherwise pile up and run concurrently- // against the backend. The first map for a workspace holds the lock; any- // concurrent one coalesces and exits 0 here. The lock auto-releases on- // process exit (see single-flight.ts) and a stale lock from a crashed map- // is stolen, so this never wedges.- const mapLock = acquireMapLock(cwd, `ix map ${cwd}`);- if (!mapLock) {- 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- }-- // Background refresh is a local-only convenience. When invoked- // automatically (IX_AUTO_MAP=1, set by the editor/agent hooks) against a- // remote backend, skip: a remote graph should be fed deliberately, not by- // a write on every change from every client. Manual `ix map` is never- // skipped; opt the automatic path back in with IX_AUTO_MAP_CLOUD=1.- const autoMap = process.env.IX_AUTO_MAP === "1";- const cloudReady = await isCloudReady();- if (shouldSkipAutoMap({ auto: autoMap, cloudReady })) {- if (!silent && opts.format !== "json" && opts.format !== "llm") {- process.stderr.write(chalk.dim(" Skipping automatic map: active backend is remote (run `ix map` manually to refresh it).\n"));- }- return; // lock releases on process exit- }-- // Shared wall-clock deadline applied to every backend request this command- // makes (ingest + map), so the whole operation is bounded even if the- // backend stalls on individual long per-request timeouts.- const deadlineSignal = mapDeadlineSignal();-- // Auto-detect a multi-repo system (>= 2 child repo roots). When present we- // scope the map to its system_id; otherwise it's an ordinary single-repo map.- const systemId = detectSystem(cwd)?.systemId;-- // json and llm are machine formats: suppress progress chatter and route- // ingestion through the quiet path so stdout carries only the result.- const machineFormat = opts.format === "json" || opts.format === "llm";- // Report an error on the right channel: structured record for llm, prose for the rest.- const emitError = (msg: string) => {- if (opts.format === "llm") console.log(llmError("backend_error", msg));- else console.error(chalk.red("Error:"), msg);- };-- // Print warning when --full override is active- if (opts.full && !machineFormat && !silent) {- console.log(chalk.yellow("\nWarning"));- console.log(chalk.yellow(" Full local map override enabled.\n"));- console.log(" Ix will ignore automatic local safety limits and attempt full local mapping.");- console.log(" This may take a long time or fail on very large systems.\n");- }-- // Ingest the path before mapping so the graph is up to date.- //- // Routing: if Pro is loaded AND the user has an active cloud- // instance configured (isCloudReady === true), route ingestion- // through the cloud pipeline. To force local, switch the active- // instance with `ix instance use local` (or `ix instance bind- // local` to scope to one workspace).- //- // The local backend bootstrap below only runs on the local path —- // cloud ingestion doesn't require a local Ix backend.- const ingestStart = performance.now();- let localIngest: IngestFilesSummary | undefined;- if (cloudReady) {- const runner = getRemoteRunner()!; // isCloudReady guarantees non-null- try {- await runner.runIngestion({- cwd,- silent,- format: (machineFormat || silent) ? "json" : "text",- });- } catch (err: any) {- emitError(formatFetchError(err));- process.exitCode = 1;- return;- }- } else {- try {- await bootstrap(cwd);- } catch (err: any) {- emitError(err.message);- process.exitCode = 1;- return;- }- try {- localIngest = await ingestFiles(cwd, {- recursive: true,- format: (machineFormat || silent) ? "json" : "text",- printSummary: false,- suppressOutput: true,- mapMode: mapModeForIngest(),- deadlineSignal,- // `ix map` has no --debug, so the per-file `[commit error] <uri>`- // detail was unreachable from the command that produced the- // failure — and the failure message told the user to pass a flag- // that does not exist. --verbose is map's equivalent lever.- debug: Boolean(opts.verbose),- });- } catch (err: any) {- emitError(formatFetchError(err));- process.exitCode = 1;- return;- }- }- const ingestMs = Math.round(performance.now() - ingestStart);-- const client = new IxClient(getEndpoint(), deadlineSignal);-- const mapBarWidth = 25;- const mapStart = performance.now();-- // Path-2 grouping (Ix#225 Half B): a co-ingest system is found by detectSystem- // above; a SEPARATELY-ingested repo that the stitcher joined into a system has- // no local marker, so look its system_id up from the backend and scope to it,- // making `ix map <repo>` show the whole stitched system.- let effectiveSystemId = systemId;- if (!effectiveSystemId) {- const ws = resolveWorkspaceId(cwd);- if (ws) {- // Best-effort, as before workspaceSystem started reporting failures:- // an unanswered lookup leaves the map at workspace scope.- const looked = await client.workspaceSystem(ws).catch(() => ({ systemId: null }));- if (looked.systemId) effectiveSystemId = looked.systemId;- }- }- const mapRequest = { full: opts.full, workspaceId: effectiveSystemId ? undefined : resolveWorkspaceId(cwd), systemId: effectiveSystemId };-- // Reuse the last response when this run's ingest wrote nothing and the- // backend's head revision has not moved since it was computed. Local- // only: a cloud ingest reports no summary, so it cannot vouch for that.- const cacheSlot = localIngest ? await resolveMapCacheSlot(client, mapRequest, () => readBackendHealth(client)) : undefined;- const cached = cacheSlot && localIngest?.graphUnchanged ? loadCachedMap(cwd, cacheSlot) : undefined;-- let result: MapView;- if (cached) {- result = cached;- } else {- // Same gate as the ingest bar: --silent and the machine formats were the- // only ways to avoid this, and neither is available to something merely- // capturing normal output.- const mapInterval = (!machineFormat && !silent && canRenderProgress()) ? setInterval(() => {- const elapsed = performance.now() - mapStart;- const pct = 1 - Math.exp(-elapsed / 4000);- const filled = Math.round(pct * mapBarWidth);- const bar = chalk.cyan('█'.repeat(filled)) + chalk.dim('░'.repeat(mapBarWidth - filled));- const pctStr = chalk.cyan(`${Math.min(Math.round(pct * 100), 99)}%`.padStart(4));- process.stderr.write(`\r Computing map... ${bar} ${pctStr}`);- }, 80) : null;-- try {- result = await client.map(mapRequest) as MapResult;- } catch (err: any) {- if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }- clearMapResultCache(cwd);- emitError(formatFetchError(err));- process.exitCode = 1;- return;- }- if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }- }- const mapMs = Math.round(performance.now() - mapStart);-- const emptyMapError = invalidateBaselineForIncompleteCompletedMap(result, localIngest, cwd);- if (emptyMapError) {- emitError(emptyMapError);- process.exitCode = 1;- return;- }- // The cache holds the latest response the backend gave, or nothing: a- // response that is not kept removes the one before it, so a later hit- // can never be older than a miss in between.- if (persistCompletedMapBaseline(result, cwd) && cacheSlot) {- if (!cached) saveCachedMap(cwd, cacheSlot, result);- } else {- clearMapResultCache(cwd);- }-- // stderr, so it reaches a human on the text path and never contaminates- // the JSON/llm payload on stdout. The exit code deliberately stays 0:- // plugins read this command's JSON through runners that discard stdout on- // a non-zero exit, so failing here would hide the very diagnostics the- // caller needs (the #539 lesson).- emitDroppedFileWarning(localIngest);-- if (silent) {- const systems = result.regions.filter(r => r.label_kind === "system").length;- const subsystems = result.regions.filter(r => r.label_kind === "subsystem").length;- const modules = result.regions.filter(r => r.label_kind === "module").length;- // Ix#568: `--silent` returns before both format branches AND wins over- // `--format llm`, so it is the one output the hooks this field exists- // for actually see. A skipped stitch deliberately does not move the exit- // code -- without a token here an automated consumer cannot tell a clean- // map from one whose cross-repo edges are up to 15 minutes stale.- // Ix#568. The RULE, not just the fact -- and not for `incomplete`.- //- // `--silent` is the hook surface: one terse line per run. `incomplete`- // fires on nearly every incremental map, so emitting it here would put- // a token on almost every line and make `stitch_skipped` useless as a- // signal, while a consumer that actually needs to know an incremental- // map registered nothing has `--format json` and `--format llm`, which- // both carry it. What stays here is the guard refusing -- the case that- // means a backend is being protected from stacked joins.- const rule = localIngest?.stitchSkippedRule;- const stitch =- rule === undefined || rule === "incomplete" || rule === "run-errors"- ? ""- // `stitch_skipped_rule`, not `stitch_skipped`. The json and llm- // formats put the English prose under `stitch_skipped` and the rule- // under `stitch_skipped_rule`, and emitting the RULE under the- // prose key here gave one name two value spaces: a hook matching- // `stitch_skipped=cooling` on this line silently stopped matching- // the moment it was pointed at `--format json`.- : ` · stitch_skipped_rule=${rule}`;- process.stderr.write(- `map: ${result.file_count} files · ${systems}s/${subsystems}ss/${modules}m regions · ${mapMs}ms${stitch}\n`- );- return;- }-- if (!machineFormat) {- const mapSec = (mapMs / 1000).toFixed(1);- process.stderr.write(chalk.dim(` Mapped in ${mapSec}s\n`));- }-- const minConf = parseFloat(opts.minConfidence ?? "0");- const levelFilter = opts.level ? parseInt(opts.level, 10) : null;- const parsedMaxItems = parseInt(opts.maxItems ?? "10", 10);- const maxItems = Number.isFinite(parsedMaxItems) && parsedMaxItems > 0 ? parsedMaxItems : 10;- const sortMode = normalizeSortMode(opts.sort);-- let regions = result.regions;- if (levelFilter !== null) regions = regions.filter(r => r.level === levelFilter);- if (minConf > 0) regions = regions.filter(r => r.confidence >= minConf);-- if (opts.format === "json") {- printJson({- file_count: result.file_count,- region_count: regions.length,- levels: result.levels,- map_rev: result.map_rev,- outcome: result.outcome,- // Always present so a consumer can branch on them without a key check.- // A dropped file is silent otherwise: the backend still answers with a- // completed outcome, so `outcome` alone cannot distinguish a whole map- // from one missing every file that failed to build a patch (#554).- parse_errors: localIngest?.parseErrors ?? 0,- commit_errors: localIngest?.commitErrors ?? 0,- // Ix#568. The whole reason this is reported at all is hooks that run- // `ix map` and read the machine output; leaving it only in- // `ix ingest --format json` puts it where those hooks never look.- // `?? null`, not left undefined: JSON.stringify drops an undefined- // value, so a consumer could not tell the field apart from an older- // CLI that never emitted it. Its siblings are always present too.- stitch_skipped: localIngest?.stitchSkipped ?? null,- stitch_skipped_rule: localIngest?.stitchSkippedRule ?? null,- regions: regions.map((r: any) => ({- label: r.label,- level: r.level,- files: r.file_count,- cohesion: roundFloat(r.cohesion),- coupling: roundFloat(r.external_coupling),- confidence: roundFloat(r.confidence),- signals: r.dominant_signals,- })),- });- return;- }- if (opts.format === "llm") {- renderMapLlm(result, regions, localIngest);- return;- }- renderMapText(result, cwd, opts);});}@@ -1104,3 +815,336 @@ function formatRegionLine(region: MapRegion, verbose: boolean, depth = 0): strinconst signalText = signals.length > 0 ? chalk.dim(` ${signals}`) : "";return `${badge} ${chalk.bold(region.label)} ${fileText} ${clarityColor(`${clarity} ${confPct}%`)}${signalText}${crosscut}`;}++/** What a map that ran holds when it finishes: the workspace whose lock it took. */+interface HeldMap { root?: string; local?: boolean }++async function runMapCommand(pathArg: string | undefined, opts: { format: string; level?: string; minConfidence: string; maxItems: string; allItems?: boolean; sort: string; graph?: boolean; list?: boolean; full?: boolean; verbose?: boolean; silent?: boolean }, held: HeldMap): Promise<void> {+ let cwd: string;+ try {+ cwd = resolveMapRoot(pathArg);+ } catch (err: any) {+ const message = err?.message ?? "Invalid map path";+ if (opts.format === "json") {+ printJson({ error: "invalid_map_path", message });+ } else if (opts.format === "llm") {+ console.log(llmError("invalid_map_path", message));+ } else {+ console.error(chalk.red("Error:"), message);+ }+ process.exitCode = 1;+ return;+ }++ const silent = opts.silent === true || opts.format === "silent";++ // Single-flight: refuse to stack. Background refresh can fire `ix map`+ // repeatedly (e.g. once per change); if a map is slow or the backend is+ // unhealthy, those invocations would otherwise pile up and run concurrently+ // against the backend. The first map for a workspace holds the lock; any+ // concurrent one coalesces and exits 0 here. The lock auto-releases on+ // process exit (see single-flight.ts) and a stale lock from a crashed map+ // is stolen, so this never wedges.+ const mapLock = acquireMapLock(cwd, `ix map ${cwd}`);+ if (!mapLock) {+ if (!silent && opts.format !== "json" && opts.format !== "llm") {+ process.stderr.write(chalk.dim(" Another ix map is already running for this workspace — skipping.\n"));+ }+ // Tell the holder: this run's reason (an edit, usually) may have come+ // after it read the file, so it runs one more ingest before it lets go.+ requestMapRerun(cwd);+ applyRequestedMapCoalesceExitCode();+ return; // coalesce; the in-flight map will refresh the graph+ }+ // Holding the lock: whatever a map that coalesced before now asked for, this+ // run covers -- it has not read the tree yet.+ takeMapRerun(cwd);+ held.root = cwd;++ // Background refresh is a local-only convenience. When invoked+ // automatically (IX_AUTO_MAP=1, set by the editor/agent hooks) against a+ // remote backend, skip: a remote graph should be fed deliberately, not by+ // a write on every change from every client. Manual `ix map` is never+ // skipped; opt the automatic path back in with IX_AUTO_MAP_CLOUD=1.+ const autoMap = process.env.IX_AUTO_MAP === "1";+ const cloudReady = await isCloudReady();+ if (shouldSkipAutoMap({ auto: autoMap, cloudReady })) {+ if (!silent && opts.format !== "json" && opts.format !== "llm") {+ process.stderr.write(chalk.dim(" Skipping automatic map: active backend is remote (run `ix map` manually to refresh it).\n"));+ }+ return; // lock releases on process exit+ }++ // Shared wall-clock deadline applied to every backend request this command+ // makes (ingest + map), so the whole operation is bounded even if the+ // backend stalls on individual long per-request timeouts.+ const deadlineSignal = mapDeadlineSignal();++ // Auto-detect a multi-repo system (>= 2 child repo roots). When present we+ // scope the map to its system_id; otherwise it's an ordinary single-repo map.+ const systemId = detectSystem(cwd)?.systemId;++ // json and llm are machine formats: suppress progress chatter and route+ // ingestion through the quiet path so stdout carries only the result.+ const machineFormat = opts.format === "json" || opts.format === "llm";+ // Report an error on the right channel: structured record for llm, prose for the rest.+ const emitError = (msg: string) => {+ if (opts.format === "llm") console.log(llmError("backend_error", msg));+ else console.error(chalk.red("Error:"), msg);+ };++ // Print warning when --full override is active+ if (opts.full && !machineFormat && !silent) {+ console.log(chalk.yellow("\nWarning"));+ console.log(chalk.yellow(" Full local map override enabled.\n"));+ console.log(" Ix will ignore automatic local safety limits and attempt full local mapping.");+ console.log(" This may take a long time or fail on very large systems.\n");+ }++ // Ingest the path before mapping so the graph is up to date.+ //+ // Routing: if Pro is loaded AND the user has an active cloud+ // instance configured (isCloudReady === true), route ingestion+ // through the cloud pipeline. To force local, switch the active+ // instance with `ix instance use local` (or `ix instance bind+ // local` to scope to one workspace).+ //+ // The local backend bootstrap below only runs on the local path —+ // cloud ingestion doesn't require a local Ix backend.+ const ingestStart = performance.now();+ let localIngest: IngestFilesSummary | undefined;+ held.local = !cloudReady;+ if (cloudReady) {+ const runner = getRemoteRunner()!; // isCloudReady guarantees non-null+ try {+ await runner.runIngestion({+ cwd,+ silent,+ format: (machineFormat || silent) ? "json" : "text",+ });+ } catch (err: any) {+ emitError(formatFetchError(err));+ process.exitCode = 1;+ return;+ }+ } else {+ try {+ await bootstrap(cwd);+ } catch (err: any) {+ emitError(err.message);+ process.exitCode = 1;+ return;+ }+ try {+ localIngest = await ingestFiles(cwd, {+ recursive: true,+ format: (machineFormat || silent) ? "json" : "text",+ printSummary: false,+ suppressOutput: true,+ mapMode: mapModeForIngest(),+ deadlineSignal,+ // `ix map` has no --debug, so the per-file `[commit error] <uri>`+ // detail was unreachable from the command that produced the+ // failure — and the failure message told the user to pass a flag+ // that does not exist. --verbose is map's equivalent lever.+ debug: Boolean(opts.verbose),+ });+ } catch (err: any) {+ emitError(formatFetchError(err));+ process.exitCode = 1;+ return;+ }+ }+ const ingestMs = Math.round(performance.now() - ingestStart);++ const client = new IxClient(getEndpoint(), deadlineSignal);++ const mapBarWidth = 25;+ const mapStart = performance.now();++ // Path-2 grouping (Ix#225 Half B): a co-ingest system is found by detectSystem+ // above; a SEPARATELY-ingested repo that the stitcher joined into a system has+ // no local marker, so look its system_id up from the backend and scope to it,+ // making `ix map <repo>` show the whole stitched system.+ let effectiveSystemId = systemId;+ if (!effectiveSystemId) {+ const ws = resolveWorkspaceId(cwd);+ if (ws) {+ // Best-effort, as before workspaceSystem started reporting failures:+ // an unanswered lookup leaves the map at workspace scope.+ const looked = await client.workspaceSystem(ws).catch(() => ({ systemId: null }));+ if (looked.systemId) effectiveSystemId = looked.systemId;+ }+ }+ const mapRequest = { full: opts.full, workspaceId: effectiveSystemId ? undefined : resolveWorkspaceId(cwd), systemId: effectiveSystemId };++ // Reuse the last response when this run's ingest wrote nothing and the+ // backend's head revision has not moved since it was computed. Local+ // only: a cloud ingest reports no summary, so it cannot vouch for that.+ const cacheSlot = localIngest ? await resolveMapCacheSlot(client, mapRequest, () => readBackendHealth(client)) : undefined;+ const cached = cacheSlot && localIngest?.graphUnchanged ? loadCachedMap(cwd, cacheSlot) : undefined;++ let result: MapView;+ if (cached) {+ result = cached;+ } else {+ // Same gate as the ingest bar: --silent and the machine formats were the+ // only ways to avoid this, and neither is available to something merely+ // capturing normal output.+ const mapInterval = (!machineFormat && !silent && canRenderProgress()) ? setInterval(() => {+ const elapsed = performance.now() - mapStart;+ const pct = 1 - Math.exp(-elapsed / 4000);+ const filled = Math.round(pct * mapBarWidth);+ const bar = chalk.cyan('█'.repeat(filled)) + chalk.dim('░'.repeat(mapBarWidth - filled));+ const pctStr = chalk.cyan(`${Math.min(Math.round(pct * 100), 99)}%`.padStart(4));+ process.stderr.write(`\r Computing map... ${bar} ${pctStr}`);+ }, 80) : null;++ try {+ result = await client.map(mapRequest) as MapResult;+ } catch (err: any) {+ if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }+ clearMapResultCache(cwd);+ emitError(formatFetchError(err));+ process.exitCode = 1;+ return;+ }+ if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }+ }+ const mapMs = Math.round(performance.now() - mapStart);++ const emptyMapError = invalidateBaselineForIncompleteCompletedMap(result, localIngest, cwd);+ if (emptyMapError) {+ emitError(emptyMapError);+ process.exitCode = 1;+ return;+ }+ // The cache holds the latest response the backend gave, or nothing: a+ // response that is not kept removes the one before it, so a later hit+ // can never be older than a miss in between.+ if (persistCompletedMapBaseline(result, cwd) && cacheSlot) {+ if (!cached) saveCachedMap(cwd, cacheSlot, result);+ } else {+ clearMapResultCache(cwd);+ }++ // stderr, so it reaches a human on the text path and never contaminates+ // the JSON/llm payload on stdout. The exit code deliberately stays 0:+ // plugins read this command's JSON through runners that discard stdout on+ // a non-zero exit, so failing here would hide the very diagnostics the+ // caller needs (the #539 lesson).+ emitDroppedFileWarning(localIngest);++ if (silent) {+ const systems = result.regions.filter(r => r.label_kind === "system").length;+ const subsystems = result.regions.filter(r => r.label_kind === "subsystem").length;+ const modules = result.regions.filter(r => r.label_kind === "module").length;+ // Ix#568: `--silent` returns before both format branches AND wins over+ // `--format llm`, so it is the one output the hooks this field exists+ // for actually see. A skipped stitch deliberately does not move the exit+ // code -- without a token here an automated consumer cannot tell a clean+ // map from one whose cross-repo edges are up to 15 minutes stale.+ // Ix#568. The RULE, not just the fact -- and not for `incomplete`.+ //+ // `--silent` is the hook surface: one terse line per run. `incomplete`+ // fires on nearly every incremental map, so emitting it here would put+ // a token on almost every line and make `stitch_skipped` useless as a+ // signal, while a consumer that actually needs to know an incremental+ // map registered nothing has `--format json` and `--format llm`, which+ // both carry it. What stays here is the guard refusing -- the case that+ // means a backend is being protected from stacked joins.+ const rule = localIngest?.stitchSkippedRule;+ const stitch =+ rule === undefined || rule === "incomplete" || rule === "run-errors"+ ? ""+ // `stitch_skipped_rule`, not `stitch_skipped`. The json and llm+ // formats put the English prose under `stitch_skipped` and the rule+ // under `stitch_skipped_rule`, and emitting the RULE under the+ // prose key here gave one name two value spaces: a hook matching+ // `stitch_skipped=cooling` on this line silently stopped matching+ // the moment it was pointed at `--format json`.+ : ` · stitch_skipped_rule=${rule}`;+ process.stderr.write(+ `map: ${result.file_count} files · ${systems}s/${subsystems}ss/${modules}m regions · ${mapMs}ms${stitch}\n`+ );+ return;+ }++ if (!machineFormat) {+ const mapSec = (mapMs / 1000).toFixed(1);+ process.stderr.write(chalk.dim(` Mapped in ${mapSec}s\n`));+ }++ const minConf = parseFloat(opts.minConfidence ?? "0");+ const levelFilter = opts.level ? parseInt(opts.level, 10) : null;+ const parsedMaxItems = parseInt(opts.maxItems ?? "10", 10);+ const maxItems = Number.isFinite(parsedMaxItems) && parsedMaxItems > 0 ? parsedMaxItems : 10;+ const sortMode = normalizeSortMode(opts.sort);++ let regions = result.regions;+ if (levelFilter !== null) regions = regions.filter(r => r.level === levelFilter);+ if (minConf > 0) regions = regions.filter(r => r.confidence >= minConf);++ if (opts.format === "json") {+ printJson({+ file_count: result.file_count,+ region_count: regions.length,+ levels: result.levels,+ map_rev: result.map_rev,+ outcome: result.outcome,+ // Always present so a consumer can branch on them without a key check.+ // A dropped file is silent otherwise: the backend still answers with a+ // completed outcome, so `outcome` alone cannot distinguish a whole map+ // from one missing every file that failed to build a patch (#554).+ parse_errors: localIngest?.parseErrors ?? 0,+ commit_errors: localIngest?.commitErrors ?? 0,+ // Ix#568. The whole reason this is reported at all is hooks that run+ // `ix map` and read the machine output; leaving it only in+ // `ix ingest --format json` puts it where those hooks never look.+ // `?? null`, not left undefined: JSON.stringify drops an undefined+ // value, so a consumer could not tell the field apart from an older+ // CLI that never emitted it. Its siblings are always present too.+ stitch_skipped: localIngest?.stitchSkipped ?? null,+ stitch_skipped_rule: localIngest?.stitchSkippedRule ?? null,+ regions: regions.map((r: any) => ({+ label: r.label,+ level: r.level,+ files: r.file_count,+ cohesion: roundFloat(r.cohesion),+ coupling: roundFloat(r.external_coupling),+ confidence: roundFloat(r.confidence),+ signals: r.dominant_signals,+ })),+ });+ return;+ }+ if (opts.format === "llm") {+ renderMapLlm(result, regions, localIngest);+ return;+ }+ renderMapText(result, cwd, opts);+}++/**+ * One more ingest when a map that coalesced into this one asked for it (see+ * `requestMapRerun`), before the lock is let go. One pass at most: under a+ * stream of edits a rerun per request would never finish, and the next edit's+ * own map picks up whatever arrives after it. Ingest only -- this run's output+ * has already been printed, and the hierarchy is refreshed by the next map.+ */+async function rerunIfRequested(root: string, local: boolean, opts: { silent?: boolean; format: string }): Promise<void> {+ if (!local || !takeMapRerun(root)) return;+ try {+ await ingestFiles(root, {+ recursive: true,+ format: "json",+ printSummary: false,+ suppressOutput: true,+ mapMode: mapModeForIngest(),+ });+ } catch (err: any) {+ if (opts.silent !== true && opts.format !== "json" && opts.format !== "llm") {+ process.stderr.write(chalk.dim(` Re-run for a map that waited on this one failed: ${err?.message ?? err}\n`));+ }+ }+}diff --git a/ix-cli/src/cli/single-flight.ts b/ix-cli/src/cli/single-flight.tsindex 1cbcfa2f..5ba853f0 100644--- a/ix-cli/src/cli/single-flight.ts+++ b/ix-cli/src/cli/single-flight.ts@@ -1,6 +1,6 @@// Copyright 2026 Ix Infrastructure Inc.-import { mkdirSync, writeFileSync, readFileSync, rmSync, openSync, closeSync, realpathSync } from "node:fs";+import { mkdirSync, writeFileSync, readFileSync, rmSync, realpathSync, linkSync, statSync, utimesSync } from "node:fs";import { join, resolve } from "node:path";import { hostname } from "node:os";import { createHash } from "node:crypto";@@ -104,12 +104,33 @@ function readMeta(path: string): LockMeta | null {}}-/** A held lock is stale if its holder is gone, on another host, or too old. */-function isStale(meta: LockMeta | null): boolean {- if (!meta) return true; // unparseable/empty → treat as abandoned+/** How often a holder touches its lock file to show it is still working. */+const HEARTBEAT_MS = 30_000;++/** When the lock file was last written or touched by its holder. */+function lastHeartbeat(path: string): number | null {+ try { return statSync(path).mtimeMs; } catch { return null; }+}++/**+ * A held lock is stale when its holder is gone: a dead pid on this host, or a+ * holder that has not touched the file for `IX_MAP_LOCK_MAX_MS` -- on another+ * host, where the pid cannot be checked, or on this one, where the pid may+ * have been reused by an unrelated process.+ *+ * Age alone no longer makes a lock stale. It used to be measured from+ * `startedAt`, so a live map running longer than 20 minutes was stolen, and a+ * second map ran beside it.+ */+function isStale(meta: LockMeta | null, path?: string): boolean {+ const heartbeat = path ? lastHeartbeat(path) : null;+ const silentFor = Date.now() - (heartbeat ?? meta?.startedAt ?? 0);+ // Unreadable meta: written whole via link(), so a holder never leaves one+ // behind mid-write. Give a foreign or truncated file a moment before+ // taking it.+ if (!meta) return silentFor > 5_000;if (meta.host === hostname() && !pidAlive(meta.pid)) return true;- if (Date.now() - meta.startedAt > lockMaxMs()) return true;- return false;+ return silentFor > lockMaxMs();}/**@@ -140,26 +161,32 @@ export function acquireLockAt(path: string, label: string): LockHandle | null {const meta: LockMeta = { pid: process.pid, host: hostname(), startedAt: Date.now(), label };const tryCreate = (): boolean => {+ // The meta is written to a private file first and linked into place.+ // link() fails if the lock exists, like O_EXCL, but the lock appears+ // complete: creating it empty and then writing left a window in which+ // another process read an empty lock as abandoned and took it.+ const tmp = `${path}.${process.pid}.${meta.startedAt}.tmp`;try {- // 'wx' = O_CREAT | O_EXCL: fails if the file already exists. mode 0600 —- // the lock carries no secrets but matches the rest of ~/.ix.- const fd = openSync(path, "wx", 0o600);- try { writeFileSync(fd, JSON.stringify(meta)); } finally { closeSync(fd); }+ // mode 0600 — the lock carries no secrets but matches the rest of ~/.ix.+ writeFileSync(tmp, JSON.stringify(meta), { mode: 0o600 });+ linkSync(tmp, path);return true;} catch (err: any) {if (err?.code === "EEXIST") return false;// Any other error (e.g. permission, read-only FS): fail open rather than// block the user's map. Single-flight is an optimization, not correctness.return true;+ } finally {+ try { rmSync(tmp, { force: true }); } catch { /* best effort */ }}};- if (tryCreate()) return makeHandle(path);+ if (tryCreate()) return makeHandle(path, meta);// Contended — is the holder still alive?- if (isStale(readMeta(path))) {+ if (isStale(readMeta(path), path)) {try { rmSync(path, { force: true }); } catch { /* best effort */ }- if (tryCreate()) return makeHandle(path);+ if (tryCreate()) return makeHandle(path, meta);}return null; // a live holder owns it — caller should coalesce}@@ -192,18 +219,36 @@ export function setLockOwnerResolver(resolve: () => LockOwner): void {const held = new Map<() => void, LockOwner>();-function makeHandle(path: string): LockHandle {+/** The lock at `path` is still the one `meta` describes -- not a successor's. */+function stillOurs(path: string, meta: LockMeta): boolean {+ const current = readMeta(path);+ return current !== null && current.pid === meta.pid && current.startedAt === meta.startedAt && current.host === meta.host;+}++function makeHandle(path: string, meta: LockMeta): LockHandle {let released = false;+ // Touch the file while the lock is held: `isStale` reads its mtime, so a+ // live holder is never mistaken for an abandoned one however long it runs.+ const heartbeat = setInterval(() => {+ if (!stillOurs(path, meta)) return;+ const now = new Date();+ try { utimesSync(path, now, now); } catch { /* best effort */ }+ }, HEARTBEAT_MS);+ heartbeat.unref?.();const release = (): void => {if (released) return;released = true;held.delete(release);+ clearInterval(heartbeat);// Both listeners are removed with the lock. A long-lived process that maps// repeatedly would otherwise accumulate one set per map and trip Node's// max-listeners warning.process.off("exit", release);process.off("SIGINT", onSigint);process.off("SIGTERM", onSigterm);+ // Only our own lock. If it was taken over as stale, deleting it would+ // free a lock someone else now holds and let a third runner in.+ if (!stillOurs(path, meta)) return;try { rmSync(path, { force: true }); } catch { /* best effort */ }};const onSigint = (): void => { release(); process.exit(130); };@@ -237,11 +282,36 @@ export function releaseLocksOwnedBy(owner: LockOwner): void {for (const [release, heldBy] of [...held]) if (heldBy === owner) release();}+/**+ * Ask the process holding the map lock for `workspaceRoot` to run once more.+ *+ * A map that coalesces used to exit and tell nobody: an edit made after the+ * holder had read that file reached the graph only on a third invocation.+ * The marker sits beside the lock; the holder takes it before it lets go.+ */+export function requestMapRerun(workspaceRoot: string): void {+ try {+ mkdirSync(lockDir(), { recursive: true });+ writeFileSync(`${lockPathFor(workspaceRoot)}.rerun`, String(Date.now()), { mode: 0o600 });+ } catch { /* best effort: without it the next edit's map catches up */ }+}++/** True, and the request consumed, when a coalesced map asked for a rerun. */+export function takeMapRerun(workspaceRoot: string): boolean {+ const marker = `${lockPathFor(workspaceRoot)}.rerun`;+ try {+ rmSync(marker);+ return true;+ } catch {+ return false;+ }+}+// ── Test-only surface ──────────────────────────────────────────────────────// Exported for unit tests; not part of the public CLI API.export function lockPathForTest(workspaceRoot: string): string {return lockPathFor(workspaceRoot);}export function isStaleForTest(path: string): boolean {- return isStale(readMeta(path));+ return isStale(readMeta(path), path);}