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(config): never write config.yaml without the lock; break stale locks
KageBinary604f47869fef
diff --git a/ix-cli/src/cli/__tests__/config-file-mode.test.ts b/ix-cli/src/cli/__tests__/config-file-mode.test.tsindex dafb2a89..c83537a8 100644--- a/ix-cli/src/cli/__tests__/config-file-mode.test.ts+++ b/ix-cli/src/cli/__tests__/config-file-mode.test.ts@@ -51,7 +51,7 @@ describe("saveConfig persistence", () => {saveConfig({ endpoint: "http://localhost:8090", format: "json" });expect(readConfig()).toMatchObject({ endpoint: "http://localhost:8090", format: "json" });- expect(fs.readdirSync(cfgDir())).toEqual(["config.yaml"]);+ expect(fs.readdirSync(cfgDir()).filter((n) => n !== "locks")).toEqual(["config.yaml"]); // the lock directory stays});it.skipIf(!posix)("creates the config directory 0700", () => {@@ -84,7 +84,7 @@ describe("saveConfig persistence", () => {const currentInode = fs.statSync(cfgPath()).ino;if (previousInode !== 0 && currentInode !== 0) expect(currentInode).not.toBe(previousInode);- expect(fs.readdirSync(cfgDir())).toEqual(["config.yaml"]);+ expect(fs.readdirSync(cfgDir()).filter((n) => n !== "locks")).toEqual(["config.yaml"]); // the lock directory staysexpect(readConfig()).toMatchObject({ endpoint: "http://new.example", format: "json" });});@@ -132,6 +132,6 @@ describe("saveConfig with an unparseable config", () => {expect(() => saveConfig({ endpoint: "http://localhost:8090", format: "text" })).toThrow(/not valid YAML/);expect(fs.readFileSync(cfgPath(), "utf8")).toBe(broken);- expect(fs.readdirSync(cfgDir())).toEqual(["config.yaml"]);+ expect(fs.readdirSync(cfgDir()).filter((n) => n !== "locks")).toEqual(["config.yaml"]); // the lock directory stays});});diff --git a/ix-cli/src/cli/__tests__/config-integrity.test.ts b/ix-cli/src/cli/__tests__/config-integrity.test.tsindex 0f97e521..ff6ab9cd 100644--- a/ix-cli/src/cli/__tests__/config-integrity.test.ts+++ b/ix-cli/src/cli/__tests__/config-integrity.test.ts@@ -1,10 +1,12 @@// Copyright 2026 Ix Infrastructure Inc.import { execFile } from "node:child_process";-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { execFileSync } from "node:child_process";+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, utimesSync, writeFileSync } from "node:fs";+import { hostname } from "node:os";import { tmpdir } from "node:os";import { join, resolve } from "node:path";-import { fileURLToPath } from "node:url";+import { fileURLToPath, pathToFileURL } from "node:url";import { promisify } from "node:util";import { Command } from "commander";@@ -20,7 +22,11 @@ import { parse } from "yaml";const execFileAsync = promisify(execFile);const CLI_ROOT = resolve(fileURLToPath(new URL("../../..", import.meta.url)));-const TSX = join(CLI_ROOT, "node_modules", ".bin", "tsx");+// tsx's own entry, run by this node: node_modules/.bin/tsx is a .cmd shim on+// Windows, which execFile cannot start (ENOENT).+const TSX_CLI = join(CLI_ROOT, "node_modules", "tsx", "dist", "cli.mjs");+const tsx = (args: string[], options: Parameters<typeof execFileAsync>[2]) =>+ execFileAsync(process.execPath, [TSX_CLI, ...args], options);const BOOTSTRAP = join(CLI_ROOT, "src", "cli", "bootstrap.ts");let home: string;@@ -43,9 +49,11 @@ afterEach(() => {const configPath = () => join(home, "config.yaml");describe("parallel registrations", () => {- it.skipIf(process.platform === "win32")("8 processes registering 8 repositories at once keep all 8", async () => {+ // Generous: each process is a cold tsx start, and a slow macOS or Windows+ // runner takes seconds per start. The lock itself waits up to 30 s.+ it("8 processes registering 8 repositories at once keep all 8", async () => {const script = join(home, "register.mts");- writeFileSync(script, `import { ensureWorkspaceRegistered } from ${JSON.stringify(BOOTSTRAP)};\nensureWorkspaceRegistered(process.argv[2]);\n`);+ writeFileSync(script, `import { ensureWorkspaceRegistered } from ${JSON.stringify(pathToFileURL(BOOTSTRAP).href)};\nensureWorkspaceRegistered(process.argv[2]);\n`);for (let trial = 0; trial < 2; trial++) {rmSync(configPath(), { force: true });const dirs = Array.from({ length: 8 }, (_, i) => {@@ -53,12 +61,98 @@ describe("parallel registrations", () => {mkdirSync(d, { recursive: true });return d;});- await Promise.all(dirs.map((d) =>- execFileAsync(TSX, [script, d], { env: { ...process.env, IX_HOME: home, IX_LOCK_DIR: join(home, "locks") } })));+ const env: NodeJS.ProcessEnv = { ...process.env, IX_HOME: home, IX_LOCK_DIR: join(home, "locks") };+ delete env.FORCE_COLOR;+ await Promise.all(dirs.map((d) => tsx([script, d], { env })));const registered = (parse(readFileSync(configPath(), "utf8")).workspaces ?? []).map((w: { root_path: string }) => w.root_path);- expect(registered.sort()).toEqual(dirs.sort());+ // Registration stores the canonical path (macOS: /private/var/..., not+ // tmpdir's /var/...; Windows: the long name, not RUNNER~1).+ expect(registered.sort()).toEqual(dirs.map((d) => realpathSync.native(d)).sort());}- }, 60_000);+ }, 180_000);+});++describe("the config lock", () => {+ const lockDir = () => join(home, "locks");+ beforeEach(() => { process.env.IX_LOCK_DIR = lockDir(); });+ afterEach(() => {+ delete process.env.IX_LOCK_DIR;+ delete process.env.IX_CONFIG_LOCK_WAIT_MS;+ });++ async function lockFile(): Promise<string> {+ const { namedLockPath } = await import("../single-flight.js");+ return namedLockPath("config", configPath());+ }++ /** A pid that was alive a moment ago and is not now. */+ function deadPid(): number {+ const out = execFileSync(process.execPath, ["-e", "process.stdout.write(String(process.pid))"], { encoding: "utf8" });+ return Number(out);+ }++ function plant(path: string, pid: number): void {+ mkdirSync(lockDir(), { recursive: true });+ writeFileSync(path, JSON.stringify({ pid, host: hostname(), token: "planted", startedAt: Date.now(), label: "test" }));+ }++ it("breaks a lock left by a dead process, and the write goes through", async () => {+ const path = await lockFile();+ plant(path, deadPid()); // fresh mtime: only the dead pid makes it stale+ const { updateConfig, loadConfig } = await import("../config.js");+ const started = Date.now();+ updateConfig((c) => ({ save: { ...c, format: "json" }, result: undefined }));+ expect(Date.now() - started).toBeLessThan(5_000);+ expect(loadConfig().format).toBe("json");+ expect(existsSync(path)).toBe(false);+ });++ it("breaks a lock older than the bound even when its pid is alive", async () => {+ const path = await lockFile();+ plant(path, process.pid);+ const old = new Date(Date.now() - 120_000);+ utimesSync(path, old, old);+ const { saveConfig, loadConfig } = await import("../config.js");+ saveConfig({ ...loadConfig(), format: "llm" });+ expect(loadConfig().format).toBe("llm");+ });++ it("fails loudly, writing nothing, while a live holder keeps it", async () => {+ writeFileSync(configPath(), "endpoint: http://localhost:8090\nformat: text\n");+ const before = readFileSync(configPath(), "utf8");+ const path = await lockFile();+ plant(path, process.pid);+ process.env.IX_CONFIG_LOCK_WAIT_MS = "300";+ const { updateConfig, saveConfig, loadConfig, ConfigLockError } = await import("../config.js");+ expect(() => updateConfig((c) => ({ save: { ...c, format: "json" }, result: undefined }))).toThrow(ConfigLockError);+ expect(() => saveConfig({ ...loadConfig(), format: "json" })).toThrow(/Nothing was written/);+ expect(readFileSync(configPath(), "utf8")).toBe(before);+ expect(existsSync(path)).toBe(true); // a live holder's lock is not taken++ const { renderCliError } = await import("../errors.js");+ const lines: string[] = [];+ vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => { lines.push(a.join(" ")); });+ vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => { lines.push(a.join(" ")); });+ vi.spyOn(process.stderr, "write").mockImplementation((s: string | Uint8Array) => { lines.push(String(s)); return true; });+ vi.spyOn(process, "exit").mockImplementation(((code?: number) => { throw new Error(`exit ${code}`); }) as never);+ let err: unknown;+ try { updateConfig(() => ({ result: undefined })); } catch (e) { err = e; }+ expect(() => renderCliError(err)).toThrow("exit 1");+ const text = lines.join("\n");+ expect(text).toContain(path);+ expect(text).not.toMatch(/\n\s+at /); // no stack trace+ });++ it("is re-entrant: saveConfig inside updateConfig does not wait on itself", async () => {+ process.env.IX_CONFIG_LOCK_WAIT_MS = "300";+ const { updateConfig, saveConfig, loadConfig } = await import("../config.js");+ updateConfig((c) => {+ saveConfig({ ...c, format: "json" });+ return { save: { ...loadConfig(), endpoint: "http://127.0.0.1:8190" }, result: undefined };+ });+ expect(loadConfig()).toMatchObject({ format: "json", endpoint: "http://127.0.0.1:8190" });+ expect(existsSync(await lockFile())).toBe(false);+ });});describe("a config that does not parse", () => {@@ -101,7 +195,7 @@ describe("a config that does not parse", () => {const env: NodeJS.ProcessEnv = { ...process.env, IX_HOME: home, IX_ENDPOINT: "http://127.0.0.1:1" };delete env.FORCE_COLOR;for (const format of ["json", "llm"]) {- const out = await execFileAsync(TSX, [main, "map", "--format", format], { cwd: repo, env })+ const out = await tsx([main, "map", "--format", format], { cwd: repo, env }).then(() => { throw new Error("ix map exited 0 on a broken config"); },(e: { code?: number; stdout?: string }) => e);expect(out.code).toBe(1);diff --git a/ix-cli/src/cli/bootstrap.ts b/ix-cli/src/cli/bootstrap.tsindex 68df0b96..71f07a14 100644--- a/ix-cli/src/cli/bootstrap.ts+++ b/ix-cli/src/cli/bootstrap.ts@@ -7,7 +7,7 @@ import { execFileSync } from "node:child_process";import chalk from "chalk";import { createClient } from "../client/factory.js";import { renderBanner } from "./banner.js";-import { canonicalWorkspacePath, getEndpoint, gitRootFor, loadConfig, loadWorkspaces, findWorkspaceForCwd, updateConfig, type IxConfig, type WorkspaceConfig } from "./config.js";+import { canonicalWorkspacePath, getEndpoint, gitRootFor, loadConfig, loadWorkspaces, findWorkspaceForCwd, updateConfig, withConfigWriteLock, type IxConfig, type WorkspaceConfig } from "./config.js";import { WorkspaceNotMappedError, workspaceNotMappedHint } from "./errors.js";import { ixHome } from "./ix-home.js";import { stderr } from "./stderr.js";@@ -30,16 +30,21 @@ export function ensureLocalConfig(): boolean {const configDir = ixHome();const configPath = join(configDir, "config.yaml");mkdirSync(configDir, { recursive: true });- try {- // 'wx' creates the file atomically and throws EEXIST if it already exists,- // avoiding the existsSync-then-write TOCTOU (CodeQL js/file-system-race).- writeFileSync(configPath, `endpoint: ${getEndpoint()}\nformat: text\n`, { flag: "wx" });- noteRelocatedConfig(configPath);- return true;- } catch (err: any) {- if (err?.code === "EEXIST") return false;- throw err;- }+ // Under the config lock like every other write, so a registration that has+ // just read "no file" is not overtaken by this one.+ const created = withConfigWriteLock(() => {+ try {+ // 'wx' creates the file atomically and throws EEXIST if it already exists,+ // avoiding the existsSync-then-write TOCTOU (CodeQL js/file-system-race).+ writeFileSync(configPath, `endpoint: ${getEndpoint()}\nformat: text\n`, { flag: "wx" });+ return true;+ } catch (err: any) {+ if (err?.code === "EEXIST") return false;+ throw err;+ }+ });+ if (created) noteRelocatedConfig(configPath);+ return created;}/**diff --git a/ix-cli/src/cli/config-lock.ts b/ix-cli/src/cli/config-lock.tsnew file mode 100644index 00000000..3aea0411--- /dev/null+++ b/ix-cli/src/cli/config-lock.ts@@ -0,0 +1,266 @@+// Copyright 2026 Ix Infrastructure Inc.++import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from "node:fs";+import { dirname } from "node:path";+import { hostname } from "node:os";+import { randomBytes } from "node:crypto";+import { namedLockPath } from "./single-flight.js";++/**+ * The lock every write of config.yaml holds.+ *+ * A write is a read-modify-write: read the file, change it, rename a new copy+ * over it. Two processes doing that at once each rename their own copy over the+ * other's, and one of the two changes is gone -- eight parallel `ix map` runs+ * registering eight repositories kept one or two of them. So nothing writes the+ * file without this lock, ever: a writer that cannot get it waits, breaks it if+ * its holder is gone, and otherwise fails with {@link ConfigLockError}. There is+ * no "go ahead unlocked after a while"; that fallback is the race it exists to+ * prevent, and on a slow machine it was taken.+ *+ * The critical section is synchronous and a few milliseconds long, so a holder+ * cannot be interrupted part-way by anything short of the process dying, and a+ * dead holder is recognised by its pid. A lock older than the bound is stale+ * too, which covers a pid on another host, a reused pid, and a holder that was+ * stopped and never resumed.+ *+ * Re-entrant within a process: `saveConfig` takes the lock itself, and+ * `updateConfig` calls it while already holding it.+ */++/** config.yaml could not be locked for a write, and nothing was written. */+export class ConfigLockError extends Error {+ constructor(readonly configPath: string, readonly lockPath: string, readonly detail: string) {+ super(`Could not lock ${configPath} to write it: ${detail}`);+ this.name = "ConfigLockError";+ }+}++interface LockMeta {+ pid: number;+ host: string;+ /** Absent in a lock an older Ix wrote. */+ token?: string;+ startedAt: number;+ label: string;+}++const DEFAULT_WAIT_MS = 30_000;+const DEFAULT_STALE_MS = 30_000;+/** A lock file with no readable meta yet is being written; give it this long. */+const UNREADABLE_GRACE_MS = 5_000;++/** A positive whole number of ms from the environment, or the default. Digits only: "30s" is not 30 ms. */+function envMs(name: string, fallback: number): number {+ const raw = process.env[name];+ if (!raw || !/^\d+$/.test(raw)) return fallback;+ const n = Number.parseInt(raw, 10);+ return n > 0 ? n : fallback;+}++/** How long a writer waits for the lock before failing. */+function waitMs(): number { return envMs("IX_CONFIG_LOCK_WAIT_MS", DEFAULT_WAIT_MS); }+/** A lock untouched for this long is presumed abandoned. */+function staleMs(): number { return envMs("IX_CONFIG_LOCK_STALE_MS", DEFAULT_STALE_MS); }++const pause = new Int32Array(new SharedArrayBuffer(4));+/** A synchronous sleep: config writes run inside synchronous callers. */+function sleepSync(ms: number): void {+ Atomics.wait(pause, 0, 0, Math.max(1, Math.floor(ms)));+}++/** Windows reports a file that is open elsewhere, or pending deletion, as these. Transient there. */+function isTransientWindowsError(err: unknown): boolean {+ if (process.platform !== "win32") return false;+ const code = (err as NodeJS.ErrnoException | undefined)?.code;+ return code === "EPERM" || code === "EACCES" || code === "EBUSY";+}++function pidAlive(pid: number): boolean {+ if (!Number.isInteger(pid) || pid <= 0) return false;+ try {+ process.kill(pid, 0);+ return true;+ } catch (err) {+ // EPERM: it exists, under another user.+ return (err as NodeJS.ErrnoException | undefined)?.code === "EPERM";+ }+}++interface Observed {+ meta: LockMeta | null;+ /** Identity of the file observed, so a breaker removes only what it judged. */+ id: string;+ mtimeMs: number;+}++function observe(path: string): Observed | null {+ let st;+ try { st = statSync(path); } catch { return null; }+ let meta: LockMeta | null = null;+ try {+ const parsed = JSON.parse(readFileSync(path, "utf-8"));+ // An older Ix wrote this lock without a token; its pid still tells.+ if (parsed && typeof parsed === "object" && typeof parsed.pid === "number") meta = parsed as LockMeta;+ } catch { /* being written, or not ours */ }+ return { meta, id: `${meta?.token ?? ""}:${st.ino}:${st.mtimeMs}:${st.size}`, mtimeMs: st.mtimeMs };+}++/** Why the observed holder is gone, or undefined while it may still be working. */+function staleReason(o: Observed): string | undefined {+ const age = Date.now() - o.mtimeMs;+ if (!o.meta) return age > Math.min(UNREADABLE_GRACE_MS, staleMs()) ? "an unreadable lock file" : undefined;+ if (o.meta.host === hostname() && !pidAlive(o.meta.pid)) return `its holder, pid ${o.meta.pid}, is gone`;+ if (age > staleMs()) return `it is ${Math.round(age / 1000)}s old`;+ return undefined;+}++/**+ * Create `path` exclusively with `meta` in it. True when created, false when it+ * already exists (or, on Windows, is still being deleted); anything else throws.+ */+function createExclusive(path: string, meta: LockMeta): boolean {+ let fd: number;+ try {+ fd = openSync(path, "wx", 0o600);+ } catch (err) {+ if ((err as NodeJS.ErrnoException | undefined)?.code === "EEXIST" || isTransientWindowsError(err)) return false;+ throw err;+ }+ try { writeSync(fd, JSON.stringify(meta)); } finally { closeSync(fd); }+ return true;+}++function removeIfSame(path: string, id: string): void {+ const now = observe(path);+ if (now && now.id === id) rmSync(path, { force: true });+}++/**+ * Remove the lock at `path` if it is still the one judged stale. Serialised by+ * a second, short-lived lock, so that two waiters that both judged the same+ * dead holder cannot have one of them delete the lock the other just took.+ */+function breakStale(path: string, judged: Observed, meta: LockMeta): void {+ const breaker = `${path}.break`;+ if (!createExclusive(breaker, meta)) {+ // Another waiter is breaking it. Its own breaker is abandoned only if that+ // waiter died in the few syscalls it holds it for.+ const b = observe(breaker);+ if (b && staleReason(b)) {+ try { removeIfSame(breaker, b.id); } catch { /* next round */ }+ }+ return;+ }+ try {+ removeIfSame(path, judged.id);+ } catch { /* retried by the caller's loop */ } finally {+ try { rmSync(breaker, { force: true }); } catch { /* broken as stale later */ }+ }+}++function release(path: string, token: string): void {+ for (let attempt = 0; ; attempt++) {+ try {+ const o = observe(path);+ if (o?.meta?.token !== undefined && o.meta.token === token) rmSync(path, { force: true });+ return;+ } catch (err) {+ // Left behind, it is broken as soon as this process exits.+ if (!isTransientWindowsError(err) || attempt >= 20) return;+ sleepSync(10 + attempt * 10);+ }+ }+}++function acquire(configPath: string, label: string): () => void {+ const path = namedLockPath("config", configPath);+ try {+ // 0700, like saveConfig's: this can be what creates ~/.ix itself.+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });+ } catch (err) {+ throw new ConfigLockError(configPath, path, `the lock directory ${dirname(path)} cannot be created (${(err as Error).message})`);+ }+ const token = randomBytes(12).toString("hex");+ const meta: LockMeta = {+ pid: process.pid,+ host: hostname(),+ token,+ startedAt: Date.now(),+ label,+ };+ const deadline = Date.now() + waitMs();+ let delay = 5;+ let last: Observed | null = null;+ for (;;) {+ let created: boolean;+ try {+ created = createExclusive(path, meta);+ } catch (err) {+ throw new ConfigLockError(configPath, path, `the lock file ${path} cannot be created (${(err as Error).message})`);+ }+ if (created) return () => release(path, token);++ const held = observe(path);+ if (held) {+ last = held;+ if (staleReason(held)) {+ breakStale(path, held, meta);+ continue;+ }+ }+ if (Date.now() >= deadline) {+ const holder = last?.meta+ ? `pid ${last.meta.pid} on ${last.meta.host}${last.meta.label ? ` (${last.meta.label})` : ""}`+ : "another process";+ throw new ConfigLockError(+ configPath, path,+ `${holder} has held its lock for more than ${Math.round(waitMs() / 1000)}s. Nothing was written. ` ++ `If no other ix command is running, delete ${path} and run the command again.`,+ );+ }+ sleepSync(Math.min(delay + Math.random() * delay, Math.max(1, deadline - Date.now())));+ delay = Math.min(delay * 1.5, 250);+ }+}++let depth = 0;++/**+ * Run `fn` holding the config lock. Synchronous only: the lock is released+ * when `fn` returns, so a promise it returned would run unlocked.+ */+export function withConfigLock<T>(configPath: string, label: string, fn: () => T): T {+ if (depth > 0) {+ depth++;+ try { return fn(); } finally { depth--; }+ }+ const releaseLock = acquire(configPath, label);+ depth = 1;+ try {+ return fn();+ } finally {+ depth = 0;+ releaseLock();+ }+}++/**+ * Rename `from` over `to`, retrying the errors Windows gives while another+ * process has `to` open (a reader, an indexer, an antivirus scan). Elsewhere a+ * rename either works or fails for good.+ */+export function renameWithRetry(from: string, to: string): void {+ const deadline = Date.now() + 5_000;+ let delay = 10;+ for (;;) {+ try {+ renameSync(from, to);+ return;+ } catch (err) {+ if (!isTransientWindowsError(err) || Date.now() >= deadline) throw err;+ sleepSync(delay);+ delay = Math.min(delay * 2, 200);+ }+ }+}diff --git a/ix-cli/src/cli/config.ts b/ix-cli/src/cli/config.tsindex d2c9c53a..ea3976e3 100644--- a/ix-cli/src/cli/config.ts+++ b/ix-cli/src/cli/config.ts@@ -1,6 +1,6 @@// Copyright 2026 Ix Infrastructure Inc.-import { readFileSync, writeFileSync, existsSync, rmSync, chmodSync, renameSync, realpathSync, mkdirSync, statSync } from "node:fs";+import { readFileSync, writeFileSync, existsSync, rmSync, chmodSync, realpathSync, mkdirSync, statSync } from "node:fs";import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";import { createHash, randomBytes } from "node:crypto";import { execFileSync } from "node:child_process";@@ -8,7 +8,9 @@ import { parse, stringify } from "yaml";import { IxClient } from "../client/api.js";import { ixHome } from "./ix-home.js";import { isLocalEndpoint } from "./backend-version.js";-import { acquireLockAt, namedLockPath } from "./single-flight.js";+import { renameWithRetry, withConfigLock } from "./config-lock.js";++export { ConfigLockError } from "./config-lock.js";/*** The key of a project root's per-root state files. Canonical first: `ix@@ -249,9 +251,6 @@ export function resetConfigMemo(): void {configMemo = undefined;}-/** How long a config write waits for another process's before going ahead anyway. */-const CONFIG_LOCK_WAIT_MS = 5_000;-/*** Read config.yaml, apply `mutate`, and write it back, with no other Ix* process writing it in between.@@ -260,36 +259,30 @@ const CONFIG_LOCK_WAIT_MS = 5_000;* runs registering eight new repositories each read the file, each appended* its own workspace, and each renamed its copy over the others' -- leaving one* or two of the eight. Under the lock each one reads what the previous one- * wrote. The lock is the single-flight link lock, so a crashed holder is- * detected by its dead pid; past {@link CONFIG_LOCK_WAIT_MS} the write goes- * ahead unlocked rather than hang a command.+ * wrote. A writer that cannot get the lock waits, breaks it if its holder is+ * gone, and otherwise fails with `ConfigLockError`; it never writes unlocked+ * (see config-lock.ts).** `mutate` gets a fresh read, never the memoised one, and returns the config- * to save, or undefined to leave the file as it is.+ * to save, or undefined to leave the file as it is. It must be synchronous.*/export function updateConfig<T>(mutate: (config: IxConfig) => { save?: IxConfig; result: T }): T {const configPath = join(ixHome(), "config.yaml");- const lock = waitForLock(namedLockPath("config", configPath), `config write ${configPath}`);- try {+ return withConfigLock(configPath, `config write ${configPath}`, () => {configMemo = undefined;const { save, result } = mutate(loadConfig());if (save) saveConfig(save);return result;- } finally {- lock?.release();- }+ });}-function waitForLock(path: string, label: string): { release(): void } | null {- const deadline = Date.now() + CONFIG_LOCK_WAIT_MS;- const pause = new Int32Array(new SharedArrayBuffer(4));- for (;;) {- const handle = acquireLockAt(path, label);- if (handle) return handle;- if (Date.now() >= deadline) return null;- // A synchronous wait: registration runs inside synchronous callers.- Atomics.wait(pause, 0, 0, 5 + Math.floor(Math.random() * 20));- }+/**+ * Run `fn` holding the config lock, for a write that is not a plain+ * `updateConfig` -- creating the file, say. Synchronous only.+ */+export function withConfigWriteLock<T>(fn: () => T): T {+ const configPath = join(ixHome(), "config.yaml");+ return withConfigLock(configPath, `config write ${configPath}`, fn);}// Keys the OSS schema owns. For these, the in-memory `config` argument is@@ -308,9 +301,18 @@ const OSS_OWNED_KEYS = new Set<keyof IxConfig>(["auth",]);+/**+ * Write `config` over config.yaml, keeping the keys OSS does not own. Takes the+ * config lock (re-entrantly, so `updateConfig` can call it), and re-reads the+ * file under it, so the keys it preserves are the current ones.+ */export function saveConfig(config: IxConfig): void {const configDir = ixHome();const configPath = join(configDir, "config.yaml");+ withConfigLock(configPath, `config write ${configPath}`, () => writeConfigLocked(config, configDir, configPath));+}++function writeConfigLocked(config: IxConfig, configDir: string, configPath: string): void {// 0700, to match the 0600 the config itself is written with below: the file// holds credentials (Pro's instances carry a tunnel JWT and a long-lived IdP// refresh token), and a directory created at the default umask (typically@@ -351,10 +353,14 @@ export function saveConfig(config: IxConfig): void {// js/file-system-race). Same-dir keeps the rename atomic; rename replaces on// POSIX and Windows alike, and inherits the temp's 0600 mode (tightening any// pre-existing group/world-readable config).- const tmpPath = `${configPath}.${process.pid}.tmp`;+ //+ // On Windows the rename is MoveFileEx with REPLACE_EXISTING, which fails with+ // EPERM/EBUSY while another process has the target open -- an unlocked+ // reader, an indexer, antivirus -- so it is retried for a few seconds.+ const tmpPath = `${configPath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;writeFileSync(tmpPath, stringify(merged), { mode: 0o600 });try {- renameSync(tmpPath, configPath);+ renameWithRetry(tmpPath, configPath);} catch (err) {try { rmSync(tmpPath, { force: true }); } catch { /* best effort */ }throw err;diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.tsindex 894d61c7..d170fd5a 100644--- a/ix-cli/src/cli/errors.ts+++ b/ix-cli/src/cli/errors.ts@@ -337,6 +337,19 @@ export function configParseError(path: string, detail: string): StructuredError};}+/**+ * config.yaml could not be locked for a write. Nothing was written: Ix never+ * writes the file unlocked, because that is how parallel registrations lost+ * each other's workspaces.+ */+export function configLockError(detail: string): StructuredError {+ return {+ error: "config_lock_timeout",+ message: `Ix could not lock its config to write it: ${detail}`,+ next: "Wait for the other ix command to finish and run this one again.",+ };+}+/*** The backend answered 401 `local_token_required`: it was started with* IX_LOCAL_TOKEN and this CLI sent no token, or a different one.@@ -393,6 +406,13 @@ export function renderCliError(err: unknown, debug = false, endpoint?: string):process.exit(1);}+ if (e?.name === "ConfigLockError") {+ const locked = configLockError(e.detail);+ if (!emitLlmError(locked.error, locked.message, locked.next)) renderStructuredError(locked);+ if (debug) writeDebugDetail(err);+ process.exit(1);+ }+if (e?.name === "LocalTokenRequiredError") {const refused = localTokenRequiredError(endpoint);if (!emitLlmError(refused.error, refused.message, refused.next)) {