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(context): make --list refusals real and its ids resumable
Joseph Mikhail4000ba401aeb
diff --git a/docs/llm-format.md b/docs/llm-format.mdindex 7a2808e5..b7e84c9a 100644--- a/docs/llm-format.md+++ b/docs/llm-format.md@@ -83,6 +83,21 @@ contains method=12 field=4item name=parseFile kind=method```+`ix context --list`:++```+investigations total=2 skipped=1+investigation id=widget saved_at=2026-01-03T09:12:44.108Z target=Widget target_kind=class classification=current entities=12 relationships=20 evidence=8+investigation id=auth-path saved_at=2026-01-02T17:03:11.882Z target=verify_token target_kind=function classification=stale stale=true entities=31 relationships=64 evidence=25 truncated_evidence=4+```++`skipped` counts saved files that did not match the contract and is present+only when it is non-zero — it is the one thing about a listing that cannot be+seen from the records themselves. `id` is the id `--resume` and `--diff` take,+not the file name on disk; the two differ whenever an id contains a character+outside `[A-Za-z0-9._-]`. The counts describe each bundle; the bundles+themselves are not in the listing, and `ix context --resume <id>` fetches one.+Error line:```diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.tsindex 675a913d..fc6f492c 100644--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@ -426,15 +426,87 @@ describe("ix context investigation state", () => {// Without it, neither humans nor agents can see what they have stored —// the only path was reading the JSON files directly.describe("listInvestigations", () => {+ /**+ * Run `fn` with stdout and stderr captured separately.+ *+ * One helper for the whole block, and multi-arg calls joined with a space+ * the way a terminal shows them: the two ad-hoc capturers this replaces+ * disagreed on that (one joined, one pushed each argument as its own line),+ * so identical output produced different arrays depending on which test you+ * happened to be reading.+ */+ const captureStreams = (fn: () => void) => {+ const out: string[] = [];+ const err: string[] = [];+ const origLog = console.log;+ const origErr = console.error;+ console.log = (...a: unknown[]) => void out.push(a.join(" "));+ console.error = (...a: unknown[]) => void err.push(a.join(" "));+ try {+ fn();+ } finally {+ console.log = origLog;+ console.error = origErr;+ }+ return { out: out.join("\n"), err: err.join("\n") };+ };++ /** Restamp a saved investigation's `savedAt`, leaving everything else alone. */+ const stampSavedAt = (id: string, savedAt: string) => {+ const path = join(investigationsDir(), `${id}.json`);+ const state = JSON.parse(readFileSync(path, "utf8"));+ writeFileSync(path, JSON.stringify({ ...state, savedAt }), "utf8");+ };+it("returns saved investigations newest-first", () => {+ // The timestamps are set explicitly because `saveInvestigation` stamps+ // them from the clock and three writes inside one millisecond is the+ // ordinary case, not the rare one. The previous version of this test+ // asserted `saved[0].id === "widget-a" || saved[0].id === "widget-b"` and+ // called `.sort()` on the ids before comparing them, so it was true for+ // either order: inverting the comparator left every assertion green and+ // ordering — the function's whole stated purpose — had no coverage.saveInvestigation("widget-a", bundleWith([makeClaim("renders to DOM", 0.9)]));saveInvestigation("widget-b", bundleWith([makeClaim("mounts to DOM", 0.7)]));+ saveInvestigation("widget-c", bundleWith([makeClaim("unmounts cleanly", 0.5)]));+ stampSavedAt("widget-a", "2026-01-02T00:00:00.000Z");+ stampSavedAt("widget-b", "2026-01-03T00:00:00.000Z");+ stampSavedAt("widget-c", "2026-01-01T00:00:00.000Z");+const list = listInvestigations();- expect(list.saved.map((s) => s.id).sort()).toEqual(["widget-a", "widget-b"]);+ expect(list.saved.map((s) => s.id)).toEqual(["widget-b", "widget-a", "widget-c"]);expect(list.skipped).toBe(0);- // savedAt differs at least by a millisecond across the two writes; even- // on the rare same-ms tie the id tiebreaker keeps order deterministic.- expect(list.saved[0].id === "widget-a" || list.saved[0].id === "widget-b").toBe(true);+ });++ it("breaks a same-millisecond tie on the id, stably", () => {+ // The reason the comparator has a second clause at all: two saves in the+ // same millisecond must still come back in the same order every run.+ for (const id of ["widget-c", "widget-a", "widget-b"]) {+ saveInvestigation(id, bundleWith([makeClaim("renders to DOM", 0.9)]));+ stampSavedAt(id, "2026-01-01T00:00:00.000Z");+ }+ expect(listInvestigations().saved.map((s) => s.id)).toEqual([+ "widget-a",+ "widget-b",+ "widget-c",+ ]);+ });++ it("lists an id that --resume can actually take back", () => {+ // `sanitizeId` is injective and deliberately not idempotent — it encodes+ // `~` as `~7E` so a raw `~` cannot be mistaken for an escape — so the id+ // stored on disk is the wrong thing to print next to "Resume with:".+ // `widget/auth` was saved as `widget~2Fauth` and listed as that, and+ // resuming it looked for `widget~7E2Fauth`, which does not exist.+ saveInvestigation("widget/auth", bundleWith([makeClaim("renders to DOM", 0.9)]));+ const [only] = listInvestigations().saved;+ expect(only.id).toBe("widget~2Fauth"); // on disk, as stored++ const { out } = captureStreams(() => renderInvestigationList([only], 0, "json"));+ const listed = JSON.parse(out).investigations[0].id;+ expect(listed).toBe("widget/auth");+ // The whole point: the id the listing offers has to load.+ expect(loadInvestigation(listed)?.bundle.target.name).toBe("Widget");});it("skips files whose envelope or bundle does not match the contract", () => {@@ -471,36 +543,46 @@ describe("ix context investigation state", () => {saveInvestigation("good", bundleWith([makeClaim("renders to DOM", 0.9)]));const { saved } = listInvestigations();- const capture = (fn: () => void) => {- const out: string[] = [];- const err: string[] = [];- const origLog = console.log;- const origErr = console.error;- console.log = (...a: unknown[]) => void out.push(a.join(" "));- console.error = (...a: unknown[]) => void err.push(a.join(" "));- try {- fn();- } finally {- console.log = origLog;- console.error = origErr;- }- return { out: out.join("\n"), err: err.join("\n") };- };-- const json = capture(() => renderInvestigationList(saved, 3, "json"));+ const json = captureStreams(() => renderInvestigationList(saved, 3, "json"));expect(() => JSON.parse(json.out)).not.toThrow();- expect(JSON.parse(json.out)).toHaveLength(1);+ const parsed = JSON.parse(json.out);+ expect(parsed.investigations).toHaveLength(1);+ // An array had nowhere to put this, so a machine caller could not tell+ // three files had been rejected while the human saw a warning saying so.+ expect(parsed.skipped).toBe(3);expect(json.err).toContain("3 saved investigation file(s)");- const llm = capture(() => renderInvestigationList(saved, 3, "llm"));+ const llm = captureStreams(() => renderInvestigationList(saved, 3, "llm"));expect(llm.out.split("\n")[0]).toBe("investigations total=1 skipped=3");// The count is the record's business; nothing is written beside it.expect(llm.err).toBe("");// And with nothing skipped the field is simply absent.- const clean = capture(() => renderInvestigationList(saved, 0, "llm"));+ const clean = captureStreams(() => renderInvestigationList(saved, 0, "llm"));expect(clean.out.split("\n")[0]).toBe("investigations total=1");expect(clean.err).toBe("");+ // `skipped` is still there in json, as a zero rather than as nothing:+ // "none were rejected" is an answer, and its absence is not.+ const cleanJson = captureStreams(() => renderInvestigationList(saved, 0, "json"));+ expect(JSON.parse(cleanJson.out).skipped).toBe(0);+ });++ it("returns a summary per investigation, not the bundles themselves", () => {+ // `--list` is the discovery step. Twenty saved investigations is twenty+ // complete bundles — up to 50 entities, 100 relationships and 12000+ // characters of evidence each — and a caller that wants one of them asks+ // for it by id with `--resume <id> --format json`.+ saveInvestigation("widget", bundleWith([makeClaim("renders to DOM", 0.9)]));+ const { saved } = listInvestigations();+ expect(saved[0].bundle.evidence.length).toBeGreaterThan(0);++ const { out } = captureStreams(() => renderInvestigationList(saved, 0, "json"));+ const [item] = JSON.parse(out).investigations;+ expect(Object.keys(item).sort()).toEqual(+ ["counts", "freshness", "id", "savedAt", "target", "truncation"].sort(),+ );+ expect(item.counts.evidence).toBe(saved[0].bundle.evidence.length);+ expect(out).not.toContain("renders to DOM");});it("prints nothing itself, whatever it finds", () => {diff --git a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts b/ix-cli/src/cli/__tests__/context-mode-conflict.test.tsindex 173cec87..89e2be9f 100644--- a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts+++ b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts@@ -109,6 +109,34 @@ describe("detectContextModeConflict", () => {expect(detectContextModeConflict({ resume: "x", ...other })).toMatch(/--resume/);}});++ it("flags --list + --resume, which its own guard could never reach", () => {+ // `--list`'s guard named `--resume`, but it sat below `if (opts.resume)`,+ // which returns first. `ix context --list --resume widget` rendered one+ // investigation, exited 0, and never said the listing had been dropped.+ // Checked before any mode branch, that race cannot happen.+ expect(detectContextModeConflict({ list: true, resume: "x" })).toMatch(+ /--list and --resume cannot be combined/,+ );+ });++ it("flags --list + --out, which nothing checked at all", () => {+ // `ix context --list --out /tmp/list.json` listed to stdout, wrote no file,+ // and exited 0 — the silent-ignore gap this detector exists to close, on+ // the newest flag on the command it guards.+ expect(detectContextModeConflict({ list: true, out: "/tmp/list.json" })).toMatch(+ /--list cannot be combined with --out/,+ );+ });++ it("flags a positional target alongside --list", () => {+ // A positional is as ignorable as a flag: `ix context Widget --list`+ // dropped the target with nothing said.+ expect(detectContextModeConflict({ list: true }, "Widget")).toMatch(/--list takes no target/);+ // …and a target without --list is the ordinary path.+ expect(detectContextModeConflict({}, "Widget")).toBeUndefined();+ expect(detectContextModeConflict({ list: true })).toBeUndefined();+ });});describe("detectDiffModeConflict", () => {@@ -173,7 +201,7 @@ describe("detectDiffModeConflict", () => {*/describe("mode-flag coverage does not drift from the command", () => {/** Flags that select what the command does, or where its output goes. */- const CONTEXT_MODE_FLAGS = ["out", "save", "resume", "diff"] as const;+ const CONTEXT_MODE_FLAGS = ["out", "save", "resume", "diff", "list"] as const;/** Flags that shape the bundle a mode produces; any pair of these is legal. */const CONTEXT_BUILD_FLAGS = ["kind", "path", "pick", "depth", "asOfRev",@@ -276,6 +304,11 @@ describe("ix context action surfaces mode conflicts on stderr and exits 1", () ={ args: ["context", "--diff", "x", "--save", "y"], expect: /--diff cannot be combined with --save/ },{ args: ["context", "--diff", "x", "--out", "/tmp/x.json"], expect: /--diff cannot be combined with --out/ },{ args: ["context", "--save", "y", "--out", "/tmp/x.json"], expect: /--save and --out cannot be combined/ },+ { args: ["context", "--list", "--resume", "x"], expect: /--list and --resume cannot be combined/ },+ { args: ["context", "--list", "--diff", "x"], expect: /--list and --diff cannot be combined/ },+ { args: ["context", "--list", "--save", "y"], expect: /--list cannot be combined with --save/ },+ { args: ["context", "--list", "--out", "/tmp/x.json"], expect: /--list cannot be combined with --out/ },+ { args: ["context", "Widget", "--list"], expect: /--list takes no target/ },])("ix $args → stderr matches $expect and exit code is 1", ({ args, expect: re }) => {const r = runProgram(registerContextCommand, args);expect(r.exitCode).toBe(1);diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 5da4e3c3..9ef7fb2c 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -137,7 +137,7 @@ export function registerContextCommand(program: Command): void {"\nExamples:\n ix context IngestionService\n ix context src/main.ts --format json\n ix context Widget --max-entities 20 --max-evidence 10\n ix context Widget --save widget-investigation\n ix context --resume widget-investigation\n ix context --diff widget-investigation\n ix context --list",).action(async (target: string | undefined, opts: ContextOptions) => {- const conflict = detectContextModeConflict(opts);+ const conflict = detectContextModeConflict(opts, target);if (conflict) {reportModeConflict(conflict, opts.format);return;@@ -147,14 +147,9 @@ export function registerContextCommand(program: Command): void {return;}if (opts.list) {- if (opts.save || opts.diff || opts.resume) {- // A refusal exits non-zero, the way `refuseInvestigation` does two- // functions down and the way the sibling commands do: a warning with- // a success status tells a script the listing it never got was fine.- renderWarning("--list cannot be combined with --save, --diff or --resume.");- process.exitCode = 1;- return;- }+ // No guard of its own: every combination it used to check is refused+ // above, before any mode branch can return first. The old one lived+ // here, below `if (opts.resume)`, so its `--resume` arm was dead.const listed = listInvestigations();renderInvestigationList(listed.saved, listed.skipped, opts.format);return;@@ -297,7 +292,7 @@ async function buildFreshBundle(* without inventing a `format`.*/export type ContextModeOptions = Partial<- Pick<ContextOptions, "resume" | "diff" | "save" | "out" | "format">+ Pick<ContextOptions, "resume" | "diff" | "save" | "out" | "list" | "format">>;/**@@ -311,10 +306,37 @@ export type ContextModeOptions = Partial<* well-defined combined behaviour. Catching these combinations up front and* surfacing them as a hard error mirrors the explicit-conflict style in* subsystems.ts and prevents the user's typed flag from being a no-op.+ *+ * `--list` is checked here rather than inside the list branch, and that is the+ * point rather than tidiness. Its own guard sat below `if (opts.resume)`, which+ * returns first, so the `--list --resume` arm of it could never fire: the user+ * asked for a listing, silently got one investigation rendered, and the exit+ * code said it went fine. A guard that runs before every mode branch cannot+ * lose that race.+ *+ * `target` is a parameter because a positional is as ignorable as a flag:+ * `ix context Widget --list` dropped the target with nothing said.*/export function detectContextModeConflict(opts: ContextModeOptions,+ target?: string,): string | undefined {+ if (opts.list && target) {+ return `--list takes no target; it enumerates every saved investigation. Drop "${target}", or drop --list to build a fresh bundle for it.`;+ }+ if (opts.list && opts.resume) {+ return "--list and --resume cannot be combined; --list enumerates saved investigations, --resume renders one. Run --list first, then --resume the id you want.";+ }+ if (opts.list && opts.diff) {+ return "--list and --diff cannot be combined; --list enumerates saved investigations, --diff compares one against a fresh build.";+ }+ if (opts.list && opts.save) {+ return "--list cannot be combined with --save; --list reads saved investigations, --save writes one, and --list builds no bundle to write.";+ }+ if (opts.list && opts.out) {+ return "--list cannot be combined with --out; --list enumerates to stdout."+ + " Redirect it (`ix context --list --format json > <path>`) if you need the listing on disk.";+ }if (opts.resume && opts.diff) {return "--resume and --diff cannot be combined; --resume renders a saved investigation, --diff renders a comparison against one.";}@@ -381,6 +403,29 @@ export function sanitizeId(id: string): string {return out || "unnamed";}+/**+ * Recover the id the user typed from the id stored on disk.+ *+ * `sanitizeId` is injective and deliberately *not* idempotent — it encodes `~`+ * as `~7E` precisely so a raw `~` cannot be confused with an escape — so the+ * stored form is the wrong thing to hand back to the user. `ix context --list`+ * printed it anyway, next to "Resume with: ix context --resume <id>", and+ * `--resume` sanitizes what it is given: an id saved as `widget/auth` was+ * listed as `widget~2Fauth`, and resuming that looked for `widget~7E2Fauth`,+ * which does not exist. `saveInvestigation`'s own note echoes the id the user+ * typed, so the two affordances contradicted each other.+ *+ * `sanitizeId(unsanitizeId(stored)) === stored` for every id this CLI wrote,+ * which is what makes the listed id usable. A hand-written file whose id is+ * outside `sanitizeId`'s range has no input that reaches it and is not a case+ * this recovers.+ */+export function unsanitizeId(stored: string): string {+ return stored.replace(/~([0-9A-Fa-f]{2})/g, (_m, hex: string) =>+ String.fromCharCode(parseInt(hex, 16)),+ );+}+export function saveInvestigation(id: string, bundle: ContextBundle): void {const dir = investigationDir();mkdirSync(dir, { recursive: true });@@ -482,23 +527,58 @@ export function listInvestigations(): { saved: SavedInvestigation[]; skipped: nureturn { saved: out, skipped };}+/** One saved investigation as `--list` describes it: what it is, not what is in it. */+interface InvestigationSummary {+ /** The id to type back, not the id on disk — see `unsanitizeId`. */+ id: string;+ savedAt: string;+ target: { name: string; kind: string };+ freshness: ContextBundle["freshness"];+ counts: { entities: number; relationships: number; evidence: number };+ truncation: ContextBundle["truncation"];+}++/** Summarise one saved investigation for the listing. */+function summariseInvestigation(s: SavedInvestigation): InvestigationSummary {+ const b = s.bundle;+ return {+ id: unsanitizeId(s.id),+ savedAt: s.savedAt,+ target: { name: b.target.name, kind: b.target.kind },+ freshness: b.freshness,+ counts: {+ entities: b.entities.length,+ relationships: b.relationships.length,+ evidence: b.evidence.length,+ },+ truncation: b.truncation,+ };+}+/*** Render the saved investigations produced by `listInvestigations`.*- * JSON stays the array of saved envelopes; llm emits a summary record and one- * record per investigation; text prints the tabular summary.+ * Every format carries the same summary: what each investigation is, how big+ * it is, and how stale. Not the bundles themselves — `--list` is the discovery+ * step, and twenty saved investigations is twenty complete bundles, up to 50+ * entities, 100 relationships and 12000 characters of evidence each. A caller+ * that wants one of them asks for it by id with `--resume <id> --format json`.** `skipped` is reported in each format's own terms, and never on stdout except- * as a field. It used to be a `renderWarning` inside the enumerator — which is- * `console.log` — so a single corrupt file prepended a chalk-coloured prose- * line to the payload and `ix context --list --format json | jq` failed on it.- * The human warning goes to stderr; the machine formats carry a count.+ * as a field — including in `json`, which returns an object for exactly that+ * reason: an array has nowhere to put it, so a machine caller could not tell+ * that files had been rejected while the human saw a warning saying so. It used+ * to be a `renderWarning` inside the enumerator — which is `console.log` — so a+ * single corrupt file prepended a chalk-coloured prose line to the payload and+ * `ix context --list --format json | jq` failed on it. The human warning goes to+ * stderr; the machine formats carry a count.*/export function renderInvestigationList(items: SavedInvestigation[],skipped: number,format: string,): void {+ const summaries = items.map(summariseInvestigation);if (skipped > 0 && format !== "llm") {// `console.error`, not `renderWarning`: every renderer in ui.ts writes to// stdout, which is exactly how this line used to end up inside the JSON a@@ -511,57 +591,56 @@ export function renderInvestigationList();}if (format === "json") {- console.log(JSON.stringify(items, null, 2));+ console.log(JSON.stringify({ investigations: summaries, skipped }, null, 2));return;}if (format === "llm") {printLlmLines([// `skipped` is a field rather than a warning: it is the one thing about// the listing an agent cannot see from the records themselves.- llmLine("investigations", { total: items.length, skipped: skipped || undefined }),- ...items.map((s) =>+ llmLine("investigations", { total: summaries.length, skipped: skipped || undefined }),+ ...summaries.map((s) =>llmLine("investigation", {id: s.id,saved_at: s.savedAt,- target: s.bundle.target.name,- target_kind: s.bundle.target.kind,- classification: s.bundle.freshness.classification,- stale: s.bundle.freshness.stale,- entities: s.bundle.entities.length,- relationships: s.bundle.relationships.length,- evidence: s.bundle.evidence.length,- truncated_entities: s.bundle.truncation.entitiesTruncated,- truncated_relationships: s.bundle.truncation.relationshipsTruncated,- truncated_evidence: s.bundle.truncation.evidenceTruncated,- truncated_chars: s.bundle.truncation.charactersTruncated,+ target: s.target.name,+ target_kind: s.target.kind,+ classification: s.freshness.classification,+ stale: s.freshness.stale,+ entities: s.counts.entities,+ relationships: s.counts.relationships,+ evidence: s.counts.evidence,+ truncated_entities: s.truncation.entitiesTruncated,+ truncated_relationships: s.truncation.relationshipsTruncated,+ truncated_evidence: s.truncation.evidenceTruncated,+ truncated_chars: s.truncation.charactersTruncated,}),),]);return;}- if (items.length === 0) {+ if (summaries.length === 0) {renderNote("No saved investigations. Use `ix context <target> --save <id>` to create one.");return;}- renderSection(`Saved investigations (${items.length})`);- for (const s of items) {- const b = s.bundle;+ renderSection(`Saved investigations (${summaries.length})`);+ for (const s of summaries) {console.log(` ${s.id}`);- console.log(` target: ${b.target.name} (${b.target.kind})`);+ console.log(` target: ${s.target.name} (${s.target.kind})`);console.log(` saved_at: ${s.savedAt}`);- console.log(` freshness: ${b.freshness.classification}`);+ console.log(` freshness: ${s.freshness.classification}`);console.log(- ` counts: entities=${b.entities.length} relationships=${b.relationships.length} evidence=${b.evidence.length}`,+ ` counts: entities=${s.counts.entities} relationships=${s.counts.relationships} evidence=${s.counts.evidence}`,);if (- b.truncation.entitiesTruncated ||- b.truncation.relationshipsTruncated ||- b.truncation.evidenceTruncated ||- b.truncation.charactersTruncated+ s.truncation.entitiesTruncated ||+ s.truncation.relationshipsTruncated ||+ s.truncation.evidenceTruncated ||+ s.truncation.charactersTruncated) {console.log(- ` truncated: entities=${b.truncation.entitiesTruncated} relationships=${b.truncation.relationshipsTruncated} evidence=${b.truncation.evidenceTruncated} chars=${b.truncation.charactersTruncated}`,+ ` truncated: entities=${s.truncation.entitiesTruncated} relationships=${s.truncation.relationshipsTruncated} evidence=${s.truncation.evidenceTruncated} chars=${s.truncation.charactersTruncated}`,);}}