Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
index 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.ts
index 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 → stolen
h!.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.ts
index 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): strin
const 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.ts
index 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);
}