Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(cli): reconcile reset outcomes and require Pro auth initialization (#674)

Joseph Mikhailb3d323dc9366
diff --git a/docs/api/README.md b/docs/api/README.md
index 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 Surface
diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 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: resetAsync
responses:
- "200":
+ "202":
description: Operation handle
content:
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: string
nullable: 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.md
new file mode 100644
index 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.json
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.commands
diff --git a/ix-cli/src/cli/register/pro-failure.ts b/ix-cli/src/cli/register/pro-failure.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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. */