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(cli): reconcile reset outcomes and require Pro auth initialization (#674)
Joseph Mikhailb3d323dc9366
diff --git a/docs/api/README.md b/docs/api/README.mdindex 34d0f0a7..178e840c 100644--- a/docs/api/README.md+++ b/docs/api/README.md@@ -620,14 +620,22 @@ Reset savings metrics.| POST | `/v1/reset/async` | Begin an async wipe (remote endpoints) || POST | `/v1/reset/code` | Wipe only the code graph, preserving planning artifacts || POST | `/v1/reset/code/async` | Async variant of the code wipe |-| GET | `/v1/reset/status/{opId}` | Poll async op — `{ state: "done" \| "failed", error? }` |+| GET | `/v1/reset/status/{opId}` | Poll async op — `{ opId, state: "running" \| "done" \| "failed", error? }` || POST | `/v1/reset/workspace` | **Scoped** wipe — `{ workspaceId }`; other workspaces untouched |**Async reset flow (client-side):** local endpoints use the sync path; remote-endpoints begin via `/async`, then poll `/v1/reset/status/{opId}` every 2s up-to 15 minutes. A 404 on `begin` falls back to the sync path (old backend); a-404 on `status` means the op was lost to a server restart — reset is idempotent,-so re-run to confirm.+endpoints begin via `/async`, which answers **202** with `{ opId }` (a+lowercase RFC-4122 UUID), then poll `/v1/reset/status/{opId}` every 2s up to+15 minutes. The status body repeats `opId`, and the client rejects a body+naming a different operation.++A 404 on `begin` falls back to the sync path (old backend). A 404 on `status`+does **not**: the op ledger is in-process, so a restart, a different replica or+eviction drops the entry while the reset itself may have completed. Reset is+not safely repeatable — re-running can delete work created since the original+operation — so the client stops and reports the operation ID for an+administrator to reconcile. Do not advise re-running it. See+[reset outcome reconciliation](../security/reset-outcome-reconciliation.md).## Visualizer Proxy Surfacediff --git a/docs/api/openapi.yaml b/docs/api/openapi.yamlindex 0784450b..099de414 100644--- a/docs/api/openapi.yaml+++ b/docs/api/openapi.yaml@@ -893,14 +893,25 @@ paths:summary: Begin an async wipe (remote deployments)operationId: resetAsyncresponses:- "200":+ "202":description: Operation handlecontent:application/json:schema:type: object+ required: [opId]properties:- opId: { type: string }+ # `format: uuid` alone admits uppercase hex. The backend emits+ # UUID.randomUUID().toString(), which is lowercase, and the+ # client validates this handle before polling.+ opId:+ type: string+ format: uuid+ pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'+ "404":+ description: |+ Route not present on this deployment (older backend). The client+ falls back to the synchronous reset path on this status only./v1/reset/status/{opId}:get:@@ -919,11 +930,22 @@ paths:application/json:schema:type: object+ required: [opId, state]properties:+ opId:+ type: string+ format: uuid+ pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'state: { type: string, enum: [done, failed, running] }error:type: stringnullable: true+ "404":+ description: |+ No ledger entry for this operation. The ledger is in-process and+ bounded, so a restart, a different replica or eviction produces+ this for an operation that may have completed. It is NOT proof the+ reset did not run./v1/reset/code:post:diff --git a/docs/security/reset-outcome-reconciliation.md b/docs/security/reset-outcome-reconciliation.mdnew file mode 100644index 00000000..dfdeb4ac--- /dev/null+++ b/docs/security/reset-outcome-reconciliation.md@@ -0,0 +1,45 @@+# Reset outcome reconciliation++An asynchronous reset can change graph or ingestion state before the client+loses its connection or status entry. Repeating it can delete work created+since the original reset. A missing status does not establish that nothing ran.++The CLI now requires a 202 start acknowledgment with a UUID and a status body+identifying that same operation with `running`, `done` or `failed`. It stops+with explicit reconciliation guidance after missing, denied, invalid or+unavailable status, a partial failure, or an observation deadline. It reports+the operation ID when known and never submits another reset on these paths.++An administrator should inspect the original operation, graph effects and+pipeline claim before deciding how to recover. Do not delete a durable claim+or create a new reset solely because a status is absent. The status ledger is+process-local and bounded: restarts, replica selection and eviction can each+make an operation unavailable while the reset itself completed.++Authorization for the status route is whatever the transport in front of it+enforces; the route itself resolves an operation ID against the ledger.++Treat the blast radius of a repeated reset as wider than the caller expects.+That is the reason this client stops rather than retrying, and why recovery+is an operator decision made against the deployment's own records rather than+something the CLI can infer.++Local synchronous reset and the existing synchronous fallback for an absent+async **start** route remain. A 404 from **status** never invokes that fallback.+Authentication errors at start remain errors. This patch does not add tenant+headers, credentials or an authorization bypass; the remote transport must+establish the expected verified caller identity.++`ix-cli/src/client/reset-outcome.test.ts` executes the real client with synthetic+HTTP responses and asserts the exact request sequence. It covers success for+both reset kinds, invalid/foreign operation IDs, partial failure, transport+loss, deadlines and local/older-server compatibility. Live authenticated+remote transport and supported-release integration still need verification+before claiming deployment acceptance.++Pro is an optional, separately installed private plugin; the OSS package does+not fetch it as a dependency. Its explicit runtime resolution is therefore+listed in Knip's dependency exceptions. The loader returns normally only when+Pro is absent or fully initialized. Missing peer modules, invalid registration+exports, and credential-guard failures in an installed Pro abort command+startup instead of silently falling back to unguarded OSS execution.diff --git a/ix-cli/knip.json b/ix-cli/knip.jsonindex 16c783f9..0acd1637 100644--- a/ix-cli/knip.json+++ b/ix-cli/knip.json@@ -1,5 +1,6 @@{"$schema": "https://unpkg.com/knip@5/schema.json",+ "ignoreDependencies": ["@ix/pro"],"entry": ["src/cli/main.ts", "src/index.ts", "test/parser.smoke.mjs"],"project": ["src/**/*.ts"],"ignore": ["test/fixtures/**", "test/parser.stress.mjs"],diff --git a/ix-cli/src/cli/__tests__/pro-failure.test.ts b/ix-cli/src/cli/__tests__/pro-failure.test.tsnew file mode 100644index 00000000..93284f72--- /dev/null+++ b/ix-cli/src/cli/__tests__/pro-failure.test.ts@@ -0,0 +1,61 @@+// Copyright 2026 Ix Infrastructure Inc.++import { afterEach, describe, expect, it, vi } from "vitest";+import { isRepairInvocation } from "../register/pro-failure.js";++const argv = (...args: string[]) => ["/node", "/ix", ...args];++describe("repair invocations after an installed Pro fails to initialize", () => {+ it.each(["upgrade", "status", "docker", "help", "--help", "-h", "--version", "-V"])(+ "lets %s through so the install can be repaired or reported",+ (name) => expect(isRepairInvocation(argv(name))).toBe(true),+ );++ // The guard exists for these: anything that reaches the graph or the cloud+ // must not run while Pro's credential guard is known to be broken.+ it.each(["reset", "search", "map", "ingest", "plan", "decide", "login", "connect"])(+ "still stops %s",+ (name) => expect(isRepairInvocation(argv(name))).toBe(false),+ );++ it("stops a bare ix rather than printing help over the failure", () => {+ expect(isRepairInvocation(argv())).toBe(false);+ });++ it("reads the command, not a flag that happens to precede it", () => {+ expect(isRepairInvocation(argv("reset", "--help"))).toBe(false);+ });+});++describe("detectPro", () => {+ afterEach(() => { vi.resetModules(); vi.doUnmock("../register/pro-loader.js"); });++ it("resolves false — never a cached rejection — for a broken installed Pro", async () => {+ vi.resetModules();+ const loader = vi.fn(async () => { throw new Error("Installed Ix Pro could not initialize"); });+ vi.doMock("../register/pro-loader.js", () => ({ tryLoadProCommands: loader }));+ const stderr = vi.spyOn(console, "error").mockImplementation(() => {});++ const { detectPro } = await import("../../mcp/runner.js");++ // Every later caller — `ix mcp doctor`, the server's own startup — shares+ // the memoized promise. A cached rejection would take all of them down.+ await expect(detectPro()).resolves.toBe(false);+ await expect(detectPro()).resolves.toBe(false);+ expect(loader).toHaveBeenCalledTimes(1);+ expect(stderr.mock.calls.flat().join("")).toContain("failed to initialize");+ stderr.mockRestore();+ });++ it("still reports a genuinely absent Pro as false without warning", async () => {+ vi.resetModules();+ vi.doMock("../register/pro-loader.js", () => ({ tryLoadProCommands: async () => false }));+ const stderr = vi.spyOn(console, "error").mockImplementation(() => {});++ const { detectPro } = await import("../../mcp/runner.js");++ await expect(detectPro()).resolves.toBe(false);+ expect(stderr).not.toHaveBeenCalled();+ stderr.mockRestore();+ });+});diff --git a/ix-cli/src/cli/__tests__/pro-loader.test.ts b/ix-cli/src/cli/__tests__/pro-loader.test.tsnew file mode 100644index 00000000..437905e5--- /dev/null+++ b/ix-cli/src/cli/__tests__/pro-loader.test.ts@@ -0,0 +1,77 @@+// Copyright 2026 Ix Infrastructure Inc.++import { afterEach, expect, it } from "vitest";+import { spawnSync } from "node:child_process";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { dirname, join, resolve } from "node:path";+import { tmpdir } from "node:os";+import ts from "typescript";++const roots: string[] = [];+const loader = ts.transpileModule(readFileSync(new URL("../register/pro-loader.ts", import.meta.url), "utf8"), {+ compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },+}).outputText;+afterEach(() => { for (const root of roots.splice(0)) {+ expect(dirname(resolve(root))).toBe(resolve(tmpdir())); rmSync(root, { recursive: true, force: true });+} });+function run(code?: string, exports: unknown = { "./register": "./register.js" }) {+ const root = mkdtempSync(join(tmpdir(), "ix-pro-loader-")); roots.push(root);+ writeFileSync(join(root, "loader.mjs"), loader);+ writeFileSync(join(root, "run.mjs"), `+ import {tryLoadProCommands} from './loader.mjs';+ const p={commands:[]};+ try {const loaded=await tryLoadProCommands(p); console.log(JSON.stringify({loaded,commands:p.commands}));}+ catch(e){console.error(e.message);process.exitCode=1;}+ `);+ if (code !== undefined) {+ const pro = join(root, "node_modules", "@ix", "pro"); mkdirSync(pro, { recursive: true });+ writeFileSync(join(pro, "package.json"), JSON.stringify({ name: "@ix/pro", type: "module", exports }));+ writeFileSync(join(pro, "register.js"), code);+ }+ const result=spawnSync(process.execPath,[join(root,"run.mjs")],{cwd:root,encoding:"utf8",timeout:15000});+ expect(result.error).toBeUndefined(); return result;+}+it("keeps a real OSS installation without Pro usable", () => {+ const r=run(); expect(r.status).toBe(0); expect(JSON.parse(r.stdout)).toEqual({loaded:false,commands:[]});+});+it("awaits real asynchronous Pro registration", () => {+ const r=run('export async function registerProCommands(p){await Promise.resolve();p.commands.push("synthetic");}');+ expect(r.status).toBe(0); expect(JSON.parse(r.stdout)).toEqual({loaded:true,commands:["synthetic"]});+});+it.each([+ ['missing nested peer', 'import "missing-synthetic-cli-peer"; export function registerProCommands(){}'],+ ['missing registration export', 'export const unrelated=true;'],+ ['failed credential guard', 'export async function registerProCommands(){throw new Error("synthetic-auth-guard-failed");}'],+])("fails closed for an installed plugin with %s", (_label, code) => {+ const r=run(code); expect(r.status).toBe(1); expect(r.stderr).toContain("Installed Ix Pro could not initialize");+ expect(r.stdout).toBe("");+});+it("does not treat an installed plugin with a missing export path as absent", () => {+ const r=run('export const unrelated=true;', {".":"./register.js"});+ expect(r.status).toBe(1); expect(r.stderr).toContain("Installed Ix Pro could not be resolved");+});++// Absence is decided by re-resolving the PACKAGE, never by matching Node's+// "Cannot find package" wording. An install with no exports map and a missing+// entry is the shape most easily mistaken for absence: the subpath resolves+// through the legacy path rules (resolution does not stat the file), so the+// failure surfaces at import instead. Either way the package IS installed, so+// the only acceptable outcome is failing closed rather than registering OSS.+it("does not treat an installed plugin with no exports map and no entry as absent", () => {+ const root = mkdtempSync(join(tmpdir(), "ix-pro-loader-")); roots.push(root);+ writeFileSync(join(root, "loader.mjs"), loader);+ writeFileSync(join(root, "run.mjs"),+ "import {tryLoadProCommands} from './loader.mjs';\n" ++ "try {console.log(JSON.stringify({loaded:await tryLoadProCommands({commands:[]})}));}\n" ++ "catch(e){console.error(e.message);process.exitCode=1;}\n");+ const pro = join(root, "node_modules", "@ix", "pro"); mkdirSync(pro, { recursive: true });+ // No `exports`, and register.js is deliberately never written.+ writeFileSync(join(pro, "package.json"), JSON.stringify({ name: "@ix/pro", type: "module" }));+ writeFileSync(join(pro, "index.js"), "export const installed=true;");+ const r = spawnSync(process.execPath, [join(root, "run.mjs")], { cwd: root, encoding: "utf8", timeout: 15000 });+ expect(r.error).toBeUndefined();+ expect(r.status).toBe(1);+ expect(r.stdout).toBe(""); // never reports loaded:false+ expect(r.stderr).toMatch(/^Installed Ix Pro could not (be resolved|initialize)\./);+ expect(r.stderr).toContain("Reinstall the reviewed CLI/Pro pair");+});diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.tsindex 003c2755..79adc30c 100644--- a/ix-cli/src/cli/errors.ts+++ b/ix-cli/src/cli/errors.ts@@ -1,6 +1,7 @@// Copyright 2026 Ix Infrastructure Inc.import chalk from "chalk";+import { PRE_CONNECTION_CODES, RESET_RECONCILIATION_ERROR } from "../client/transport.js";import { llmError } from "./llm.js";@@ -187,15 +188,12 @@ export function formatFetchError(err: unknown): string {* 10s connect timeout fires first and reports `UND_ERR_CONNECT_TIMEOUT`, which* is already listed here.*/-const UNREACHABLE_CODES = new Set([- "ECONNREFUSED",- "ENOTFOUND",- "EHOSTUNREACH",- "ENETUNREACH",- "EAI_AGAIN",- "UND_ERR_CONNECT_TIMEOUT",- "UND_ERR_SOCKET",-]);+// The pre-connection codes are shared with the HTTP client, which needs the+// same "nothing was transmitted" judgement to decide whether a failed reset+// could have deleted anything. One definition, not two: a second hand-written+// copy is how the two drift apart. `UND_ERR_SOCKET` is added only here — see+// above for why it counts as unreachable for rendering but not for reset.+const UNREACHABLE_CODES = new Set([...PRE_CONNECTION_CODES, "UND_ERR_SOCKET"]);function isUnreachableCode(e: { code?: unknown } | null | undefined): boolean {return typeof e?.code === "string" && UNREACHABLE_CODES.has(e.code);@@ -250,7 +248,12 @@ function writeDebugDetail(err: unknown): void {* instead of an undici stack trace.*/export function isBackendUnreachable(err: unknown): boolean {- const e = err as { code?: unknown; cause?: unknown } | null | undefined;+ const e = err as { name?: unknown; code?: unknown; cause?: unknown } | null | undefined;+ // An error that carries its own instruction must not be re-explained by its+ // cause. Reset attaches the transport failure for IX_DEBUG, which would+ // otherwise render "start the backend, then check status" on top of a+ // "do not repeat this reset" warning — advising the retry it exists to stop.+ if (e?.name === RESET_RECONCILIATION_ERROR) return false;if (isUnreachableCode(e)) return true;return isUnreachableCode(e?.cause as { code?: unknown } | null | undefined);}diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.tsindex 1505022c..b66bc323 100644--- a/ix-cli/src/cli/main.ts+++ b/ix-cli/src/cli/main.ts@@ -4,6 +4,7 @@import { Command } from "commander";import { registerOssCommands, registerProStubs } from "./register/oss.js";import { tryLoadProCommands } from "./register/pro-loader.js";+import { isRepairInvocation } from "./register/pro-failure.js";import { buildHelpText } from "./help-text.js";import { checkForUpdate, updateCheckEnabled } from "./commands/upgrade.js";import { stderrIsTerminal } from "./stderr.js";@@ -80,7 +81,26 @@ registerOssCommands(program);(async () => {const ossCmdNames = new Set(program.commands.map((c: Command) => c.name()));- const proLoaded = await tryLoadProCommands(program);+ // An installed-but-broken Pro throws here rather than reporting absence, so+ // commands never run without its credential guard. Note this call sits+ // OUTSIDE the parseAsync try/catch below — render the failure here rather+ // than letting it reach the unhandledRejection handler by accident.+ let proLoaded = false;+ try {+ proLoaded = await tryLoadProCommands(program);+ } catch (err) {+ if (!isRepairInvocation(process.argv)) {+ renderCliError(err, debug, safeEndpoint()); // exits 1+ }+ // Repair invocation: continue OSS-only. proLoaded stays false, so the Pro+ // stubs register below and would misreport a broken Pro as absent — the+ // warning here is what distinguishes the two, and no command in the set+ // above reaches a stub.+ console.error(+ "[!!] Ix Pro is installed but failed to initialize; continuing with OSS " ++ "commands only so this one can repair the install.",+ );+ }if (proLoaded) {// Collect commands that Pro added (weren't in OSS set)const proCommands = program.commandsdiff --git a/ix-cli/src/cli/register/pro-failure.ts b/ix-cli/src/cli/register/pro-failure.tsnew file mode 100644index 00000000..d0315b49--- /dev/null+++ b/ix-cli/src/cli/register/pro-failure.ts@@ -0,0 +1,45 @@+// Copyright 2026 Ix Infrastructure Inc.++/**+ * Which invocations survive an installed-but-broken `@ix/pro`.+ *+ * `tryLoadProCommands` throws rather than reporting absence when Pro is+ * installed and cannot initialize, so no command runs without its credential+ * guard. Taken literally that also kills `ix upgrade` — the command the thrown+ * message tells the user to run, and the only in-CLI way to reinstall the+ * pair. That leaves hand-run npm as the sole route out of a broken install.+ *+ * These invocations are allowed through OSS-only instead. None of them carries+ * Pro behaviour: `upgrade` reinstalls, the others only report. Everything else+ * — every command that could touch the graph or the cloud — still stops.+ *+ * A bare `ix` (no argument) deliberately stops: the initialization error is+ * more useful to someone staring at a broken install than the help text is.+ */+const REPAIR_INVOCATIONS = new Set([+ "upgrade",+ "status",+ "doctor",+ "config",+ "docker",+ // MCP hosts launch the server as the bare command `ix mcp` (see+ // mcp/hosts.ts, which writes `command: "ix", args: ["mcp"]`). Without this+ // the server exits before the mcp command is ever reached, so the host sees+ // only a dead server and `detectPro`'s own handling never runs. Allowing it+ // does not weaken anything: `detectPro` then declines to advertise the Pro+ // tools, and `buildProgram` still rejects for any call that would need them.+ "mcp",+ "help",+ "--help",+ "-h",+ "--version",+ "-V",+]);++/**+ * True when `argv` (process.argv, whole) names an invocation that must keep+ * working after an installed Pro fails to initialize.+ */+export function isRepairInvocation(argv: readonly string[]): boolean {+ return REPAIR_INVOCATIONS.has(argv[2] ?? "");+}diff --git a/ix-cli/src/cli/register/pro-loader.ts b/ix-cli/src/cli/register/pro-loader.tsindex cd49d1aa..96ec0b95 100644--- a/ix-cli/src/cli/register/pro-loader.ts+++ b/ix-cli/src/cli/register/pro-loader.ts@@ -2,29 +2,48 @@import type { Command } from "commander";-export async function tryLoadProCommands(program: Command): Promise<boolean> {+/**+ * True only when `@ix/pro` is not installed at all.+ *+ * A package that is present but exposes no "." export fails with+ * ERR_PACKAGE_PATH_NOT_EXPORTED rather than ERR_MODULE_NOT_FOUND, which still+ * proves it is installed — so that counts as present, and the caller fails+ * closed.+ */+function proPackageIsAbsent(): boolean {try {- const dynamicImport = new Function(- "specifier",- "return import(specifier)"- ) as (specifier: string) => Promise<any>;-- const mod = await dynamicImport("@ix/pro/register");+ import.meta.resolve("@ix/pro");+ return false;+ } catch (error) {+ return (error as { code?: string }).code === "ERR_MODULE_NOT_FOUND";+ }+}- if (mod?.registerProCommands) {- // registerProCommands is async: it dynamically imports each command so- // one broken command can't disable them all. It MUST be awaited here.- // main.ts calls program.parse() synchronously right after this resolves,- // so without the await the dynamic imports are still pending and NO pro- // command is registered in time — every `ix <pro-cmd>` then fails with- // "unknown command". (Older sync versions of registerProCommands did not- // need the await; awaiting is safe for both.)- await mod.registerProCommands(program);- return true;+export async function tryLoadProCommands(program: Command): Promise<boolean> {+ let specifier: string;+ try {+ specifier = import.meta.resolve("@ix/pro/register");+ } catch (error) {+ // Pro is optional for OSS installs. An installed-but-broken plugin is not+ // absence: silently falling back would run commands without its auth guard.+ //+ // Which of the two this is gets decided by re-resolving the PACKAGE, not by+ // matching the error text. Every OSS install takes this path on every+ // command, and the else-branch now throws, so a Node reword of "Cannot find+ // package" would have turned a normal OSS install into a CLI that refuses+ // to run anything.+ if (proPackageIsAbsent()) return false;+ throw new Error("Installed Ix Pro could not be resolved. Reinstall the reviewed CLI/Pro pair before running commands.", { cause: error });+ }+ try {+ const mod = await import(specifier);+ if (typeof mod.registerProCommands !== "function") {+ throw new Error("Ix Pro does not export registerProCommands");}-- return false;- } catch {- return false;+ // Await security initialization and command registration before parsing.+ await mod.registerProCommands(program);+ return true;+ } catch (error) {+ throw new Error("Installed Ix Pro could not initialize. Reinstall the reviewed CLI/Pro pair before running commands.", { cause: error });}}diff --git a/ix-cli/src/client/__tests__/reset-outcome.test.ts b/ix-cli/src/client/__tests__/reset-outcome.test.tsnew file mode 100644index 00000000..ac114e31--- /dev/null+++ b/ix-cli/src/client/__tests__/reset-outcome.test.ts@@ -0,0 +1,159 @@+// Copyright 2026 Ix Infrastructure Inc.++import { afterEach, describe, expect, it, vi } from "vitest";+import { IxClient } from "../api.js";+import { isBackendUnreachable } from "../../cli/errors.js";++const opId = "11111111-1111-4111-8111-111111111111";+const foreignId = "22222222-2222-4222-8222-222222222222";+const response = (body: unknown, status = 200) => Response.json(body, { status });+const accepted = () => response({ opId }, 202);++afterEach(() => { vi.unstubAllGlobals(); vi.restoreAllMocks(); vi.useRealTimers(); });++function mockRequests(...results: (Response | Error)[]) {+ const requests: { url: string; method: string }[] = [];+ const fetch = vi.fn(async (url: string, init?: RequestInit) => {+ requests.push({ url, method: init?.method ?? "GET" });+ const next = results.shift();+ if (!next) throw new Error("Unexpected additional request");+ if (next instanceof Error) throw next;+ return next;+ });+ vi.stubGlobal("fetch", fetch);+ return requests;+}++describe("remote reset outcome", () => {+ it.each(["reset", "resetCode"] as const)("keeps %s polling the same UUID until confirmed done", async method => {+ vi.useFakeTimers();+ const requests = mockRequests(accepted(), response({ opId, state: "running" }), response({ opId, state: "done" }));+ const result = new IxClient("https://synthetic.example")[method]();+ await vi.advanceTimersByTimeAsync(2000);+ await expect(result).resolves.toMatchObject({ ok: true });+ expect(requests.map(r => r.method)).toEqual(["POST", "GET", "GET"]);+ expect(requests[1].url).toBe(`https://synthetic.example/v1/reset/status/${opId}`);+ expect(requests[2].url).toBe(requests[1].url);+ });++ it.each([+ ["lost status", () => response({}, 404)],+ ["denied status", () => response({}, 403)],+ ["unavailable status", () => response({}, 503)],+ ["transport failure", () => new Error("synthetic transport loss")],+ ["malformed JSON", () => new Response("{", { status: 200 })],+ ["wrong operation", () => response({ opId: foreignId, state: "done" })],+ ["missing operation", () => response({ state: "done" })],+ ["invalid state", () => response({ opId, state: "unrecognized" })],+ ["invalid state type", () => response({ opId, state: ["done"] })],+ ["partial failure", () => response({ opId, state: "failed", error: "pipeline operation requires reconciliation" })],+ ] as const)("requires reconciliation after %s without sending another reset", async (_label, statusResult) => {+ const requests = mockRequests(accepted(), statusResult());+ const result = new IxClient("https://synthetic.example").resetCode();+ await expect(result).rejects.toThrow(opId);+ await expect(result).rejects.toThrow("Do not repeat the reset until an administrator has reconciled");+ await expect(result).rejects.not.toThrow("re-run the command");+ expect(requests.map(r => r.method)).toEqual(["POST", "GET"]);+ });++ it.each([+ ["unavailable start", () => new Error("synthetic response loss")],+ ["unexpected 200", () => response({ opId })],+ ["malformed acknowledgment", () => new Response("{", { status: 202 })],+ ["null acknowledgment", () => response(null, 202)],+ ["missing operation ID", () => response({}, 202)],+ ["injected path", () => response({ opId: "../another-tenant" }, 202)],+ ] as const)("does not poll or fall back after %s", async (_label, beginResult) => {+ const requests = mockRequests(beginResult());+ await expect(new IxClient("https://synthetic.example").reset()).rejects.toThrow("Do not repeat the reset");+ expect(requests.map(r => r.method)).toEqual(["POST"]);+ });++ it("does not interpret rejected starts as an unsupported endpoint", async () => {+ const requests = mockRequests(response({ error: "verified_tenant_required" }, 401));+ await expect(new IxClient("https://synthetic.example").reset()).rejects.toThrow("401");+ expect(requests).toHaveLength(1);+ });++ it("preserves synchronous fallback only when the async start route is absent", async () => {+ const requests = mockRequests(response({}, 404), response({ ok: true, message: "Graph reset." }));+ await expect(new IxClient("https://synthetic.example").reset()).resolves.toMatchObject({ ok: true });+ expect(requests.map(r => r.url)).toEqual([+ "https://synthetic.example/v1/reset/async", "https://synthetic.example/v1/reset"]);+ });++ it("leaves local synchronous behavior unchanged", async () => {+ const requests = mockRequests(response({ ok: true, message: "Graph reset." }));+ await expect(new IxClient("http://127.0.0.1:8090").resetCode()).resolves.toMatchObject({ ok: true });+ expect(requests).toEqual([{ url: "http://127.0.0.1:8090/v1/reset/code", method: "POST" }]);+ });++ it("requires reconciliation at the polling deadline without another reset", async () => {+ vi.useFakeTimers();+ vi.setSystemTime(0);+ const running = response({ opId, state: "running" });+ vi.spyOn(running, "json").mockImplementation(async () => {+ vi.setSystemTime(900001);+ return { opId, state: "running" };+ });+ const requests = mockRequests(accepted(), running);+ const failure = expect(new IxClient("https://synthetic.example").reset())+ .rejects.toThrow("Completion was not confirmed");+ await vi.advanceTimersByTimeAsync(2000);+ await failure;+ expect(requests.map(r => r.method)).toEqual(["POST", "GET"]);+ });++ // undici reports the real code one level down, under a "fetch failed" wrapper.+ const coded = (code: string, nested = false) => {+ const inner = Object.assign(new Error(code), { code });+ return nested ? Object.assign(new TypeError("fetch failed"), { cause: inner }) : inner;+ };++ it.each([+ ["a refused connection", "ECONNREFUSED", false],+ ["an unresolved host", "ENOTFOUND", false],+ ["a refused connection wrapped by undici", "ECONNREFUSED", true],+ ] as const)("reports %s as unreachable rather than possible data loss", async (_l, code, nested) => {+ const requests = mockRequests(coded(code, nested));+ const result = new IxClient("https://synthetic.example").reset();+ // The request never left the machine, so nothing was deleted. Surfacing+ // the transport error lets renderCliError say "start the backend".+ await expect(result).rejects.not.toThrow("Do not repeat the reset");+ await expect(result).rejects.toMatchObject(nested ? { cause: { code } } : { code });+ expect(requests.map(r => r.method)).toEqual(["POST"]);+ });++ it("still requires reconciliation when an established socket closes at start", async () => {+ // UND_ERR_SOCKET counts as unreachable for error RENDERING but not here:+ // the socket was established, so the reset may have been transmitted.+ const requests = mockRequests(coded("UND_ERR_SOCKET"));+ await expect(new IxClient("https://synthetic.example").reset())+ .rejects.toThrow("Do not repeat the reset");+ expect(requests).toHaveLength(1);+ });++ // Regression guard: attaching `cause` put a transport code one level below an+ // error whose OWN message is the thing that must be read. Without the marker,+ // renderCliError classified these by that cause and printed "start the+ // backend, then check status" — telling the user to retry the reset.+ it.each(["UND_ERR_SOCKET", "ECONNREFUSED"])(+ "renders the do-not-repeat warning, not retry advice, when the cause is %s",+ async (code) => {+ const transport = coded(code);+ mockRequests(accepted(), transport);+ const failure = await new IxClient("https://synthetic.example").reset().catch((e) => e);+ expect(isBackendUnreachable(failure)).toBe(false);+ expect(failure.message).toContain("Do not repeat the reset");+ });++ it("keeps reconciliation for a lost status poll and preserves the cause", async () => {+ // Asymmetric with the start call on purpose: by now the reset is accepted+ // (202) and running server-side, so why the poll failed does not matter.+ const transport = coded("ECONNREFUSED");+ mockRequests(accepted(), transport);+ const result = new IxClient("https://synthetic.example").resetCode();+ await expect(result).rejects.toThrow("Do not repeat the reset");+ await expect(result).rejects.toMatchObject({ cause: transport });+ });+});diff --git a/ix-cli/src/client/api.ts b/ix-cli/src/client/api.tsindex 2d09d80c..c1b0238c 100644--- a/ix-cli/src/client/api.ts+++ b/ix-cli/src/client/api.ts@@ -1,5 +1,6 @@// Copyright 2026 Ix Infrastructure Inc.+import { isPreConnectionFailure, RESET_RECONCILIATION_ERROR } from "./transport.js";import type {IngestResult,StructuredContext,@@ -457,12 +458,23 @@ export class IxClient {return this.runResetSync(syncPath);}- const beginResp = await fetch(`${this.endpoint}${asyncPath}`, {- method: "POST",- headers: { "Content-Type": "application/json" },- body: JSON.stringify({}),- signal: AbortSignal.timeout(30 * 1000),- });+ let beginResp: Response;+ try {+ beginResp = await fetch(`${this.endpoint}${asyncPath}`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({}),+ signal: AbortSignal.timeout(30 * 1000),+ });+ } catch (error) {+ // A refused connection or unresolved host proves the request never left+ // this machine, so nothing was deleted and nothing needs reconciling.+ // Rethrowing lets renderCliError give its actionable "backend not+ // reachable" message instead of a data-integrity warning — which would+ // otherwise fire on the most common failure of a fresh install.+ if (isPreConnectionFailure(error)) throw error;+ throw this.resetReconciliationError("The start response was unavailable.", undefined, error);+ }if (beginResp.status === 404) {return this.runResetSync(syncPath);@@ -472,36 +484,73 @@ export class IxClient {throw new Error(`${beginResp.status}: ${text}`);}- const { opId } = (await beginResp.json()) as { opId: string };+ if (beginResp.status !== 202) {+ throw this.resetReconciliationError(`Unexpected start response (${beginResp.status}).`);+ }+ let begin: unknown;+ try { begin = await beginResp.json(); }+ catch { throw this.resetReconciliationError("The start acknowledgment was unreadable."); }+ if (!begin || typeof begin !== "object" || !("opId" in begin) ||+ typeof begin.opId !== "string" ||+ !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(begin.opId)) {+ throw this.resetReconciliationError("The start acknowledgment had no valid operation ID.");+ }+ const opId = begin.opId;const deadlineMs = Date.now() + 15 * 60 * 1000;while (Date.now() < deadlineMs) {- const statusResp = await fetch(`${this.endpoint}/v1/reset/status/${opId}`, {- method: "GET",- signal: AbortSignal.timeout(30 * 1000),- });- // Op state is in-process on the server — a restart drops it. Reset is- // idempotent, so the safe recovery is to tell the user to re-run.+ let statusResp: Response;+ try {+ statusResp = await fetch(`${this.endpoint}/v1/reset/status/${opId}`, {+ method: "GET",+ signal: AbortSignal.timeout(30 * 1000),+ });+ } catch (error) {+ // NOT treated as pre-connection like the start call above: the reset+ // was already accepted (202) and is running server-side, so losing the+ // status poll is ambiguous no matter why it failed.+ throw this.resetReconciliationError("The status response was unavailable.", opId, error);+ }+ // Missing process-local status does not prove the reset did not run.+ // A new reset could delete writes created after the original operation.if (statusResp.status === 404) {- throw new Error(- `Reset status for operation ${opId} was lost (the server may have ` +- `restarted). Reset is idempotent — re-run the command to confirm.`,- );+ throw this.resetReconciliationError("The status is unavailable or inaccessible.", opId);+ }+ if (statusResp.status !== 200) {+ throw this.resetReconciliationError(`Status request returned ${statusResp.status}.`, opId);}- if (!statusResp.ok) {- const text = await statusResp.text();- throw new Error(`${statusResp.status}: ${text}`);+ let status: unknown;+ try { status = await statusResp.json(); }+ catch { throw this.resetReconciliationError("The status response was unreadable.", opId); }+ if (!status || typeof status !== "object" || !("opId" in status) || status.opId !== opId ||+ !("state" in status) || typeof status.state !== "string" ||+ !["running", "done", "failed"].includes(status.state)) {+ throw this.resetReconciliationError("The status did not identify this operation and a valid state.", opId);}- const status = (await statusResp.json()) as { state: string; error?: string | null };if (status.state === "done") {return { ok: true, message: doneMessage };}if (status.state === "failed") {- throw new Error(`Reset failed: ${status.error ?? "unknown error"}`);+ const detail = "error" in status && typeof status.error === "string" ? status.error : "unknown error";+ throw this.resetReconciliationError(`Reset reported failure: ${detail}.`, opId);}await new Promise((resolve) => setTimeout(resolve, 2000));}- throw new Error(`Reset did not complete within 15 minutes (operation ${opId}).`);+ throw this.resetReconciliationError("Completion was not confirmed within 15 minutes.", opId);+ }++ private resetReconciliationError(reason: string, opId?: string, cause?: unknown): Error {+ const operation = opId ? ` (operation ${opId})` : "";+ // Carry `cause` so IX_DEBUG=1 can still show the underlying transport+ // failure — swallowing it left no way to tell these outcomes apart.+ const error = new Error(+ `${reason}${operation} Graph or pipeline changes may already have occurred. ` ++ "Do not repeat the reset until an administrator has reconciled its effects and operation records.",+ cause === undefined ? undefined : { cause });+ // Marked so error rendering does not reclassify this by its cause and+ // print "start the backend, then retry" over a do-not-repeat warning.+ error.name = RESET_RECONCILIATION_ERROR;+ return error;}private async runResetSync(syncPath: string): Promise<{ ok: boolean; message: string }> {diff --git a/ix-cli/src/client/transport.ts b/ix-cli/src/client/transport.tsnew file mode 100644index 00000000..dbc1b048--- /dev/null+++ b/ix-cli/src/client/transport.ts@@ -0,0 +1,51 @@+// Copyright 2026 Ix Infrastructure Inc.++/**+ * Failure codes that mean the request never reached the server.+ *+ * The connection was refused, the host did not resolve, or the connect phase+ * timed out — in every case nothing was transmitted, so a destructive request+ * provably did not run. That judgement is what lets `reset` distinguish "your+ * backend is not running" from "something may have been deleted".+ *+ * `UND_ERR_SOCKET` is deliberately NOT here even though `cli/errors.ts` counts+ * it as unreachable for rendering purposes. It means an established socket+ * closed without answering, so the request may well have been transmitted and+ * acted on — exactly the ambiguous case reset must not wave through.+ * `ECONNRESET` and `ETIMEDOUT` are absent for the same reason.+ *+ * Lives in `client/` rather than `cli/` so the HTTP client can use it without+ * pulling the CLI's presentation layer (chalk) into the `./client/*` export.+ */+export const PRE_CONNECTION_CODES = new Set([+ "ECONNREFUSED",+ "ENOTFOUND",+ "EHOSTUNREACH",+ "ENETUNREACH",+ "EAI_AGAIN",+ "UND_ERR_CONNECT_TIMEOUT",+]);++/**+ * True when `err` (or any error in its `cause` chain — undici wraps the real+ * code one level down in a `TypeError: fetch failed`) proves nothing was sent.+ */+/**+ * `name` on the errors reset raises when an operation's outcome is unknown.+ *+ * These carry a `cause` so IX_DEBUG can show the transport failure, which puts+ * a code like UND_ERR_SOCKET one level below an error whose OWN message is the+ * thing the user must read. Without this marker `isBackendUnreachable` matches+ * on that cause and renders "start the backend, then check status" — turning+ * "do not repeat this reset" into an instruction to retry.+ */+export const RESET_RECONCILIATION_ERROR = "ResetReconciliationError";++export function isPreConnectionFailure(err: unknown): boolean {+ for (let e: unknown = err, hops = 0; e && hops < 5; hops++) {+ const code = (e as { code?: unknown }).code;+ if (typeof code === "string" && PRE_CONNECTION_CODES.has(code)) return true;+ e = (e as { cause?: unknown }).cause;+ }+ return false;+}diff --git a/ix-cli/src/mcp/runner.ts b/ix-cli/src/mcp/runner.tsindex 16c4f42f..3340b4fa 100644--- a/ix-cli/src/mcp/runner.ts+++ b/ix-cli/src/mcp/runner.ts@@ -538,7 +538,19 @@ let proProbe: Promise<boolean> | undefined;* rather than offering tools whose every call answers "requires Ix Pro".*/export function detectPro(): Promise<boolean> {- return (proProbe ??= tryLoadProCommands(new Command()));+ // tryLoadProCommands now REJECTS for an installed-but-broken Pro. Cache the+ // resolved answer, never the rejection: `??=` would otherwise memoize a+ // rejected promise and every later caller — `ix mcp doctor`, the server's+ // own startup — would inherit it. Not advertising the tools is the correct+ // answer here anyway, and it does not reopen the guard: `buildProgram`+ // awaits the same loader for every in-process call (the default runner —+ // runCurrentIx only spawns a child when IX_MCP_SUBPROCESS=1), so a call+ // that would need Pro still fails.+ return (proProbe ??= tryLoadProCommands(new Command()).catch((err: unknown) => {+ const message = err instanceof Error ? err.message : String(err);+ console.error(`[!!] Ix Pro is installed but failed to initialize: ${message}`);+ return false;+ }));}/** Spawn the CLI as a child process — one command per process, fully isolated. */