Skip to content

armgit / Ix

Public Imported from GitHub
0

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

145 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import type { Command } from "commander";
import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { dirname, join, resolve } from "node:path";

import {
  BUNDLE_SCHEMA,
  contextBundleSchema,
  savedInvestigationSchema,
} from "../context-bundle-schema.js";

import { IxClient } from "../../client/api.js";
import { createClient } from "../../client/factory.js";
import type {
  ConflictReport,
  DecisionReport,
  GraphNode,
  IntentReport,
  StructuredContext,
} from "../../client/types.js";
import { resolveWorkspaceRoot } from "../config.js";
import { collectFacts, type ContextFacts, type EntityLocation } from "../explain/facts.js";
import {
  CENTRE_FALLBACK_TRIES,
  chooseCentre,
  CLOSENESS_BOOST,
  leanIssueView,
  planIssue,
  rankIssueFiles,
  readIssueText,
  type Closeness,
  type LeanIssueView,
  type RankedFile,
  type StartingPoint,
  type SymbolHit,
} from "../explain/issue.js";
import { symbolReadChecker } from "../symbol-read-check.js";
import { collectRelatedFiles, MAX_RELATED, type RelatedRef } from "../explain/related-files.js";
import { cachedBm25Ranker } from "../explain/bm25-cache.js";
import { collectTextReferences, gitRepoAccess, type TextSource } from "../explain/text-references.js";
import { coChangedFiles, gitRunner, recentCommits, type CommitRef } from "../explain/history.js";
import { llmLine, llmShortId, printLlmLines } from "../llm.js";
import { parseBudgetOption, parsePickOption, parseRevisionOption } from "../options.js";
import { activeReadScope, ensureReadScope, resolveFileOrReport } from "../resolve.js";
import { createStaleProbe, hasCompletedSourceGraphBaseline } from "../stale.js";
import { renderNote, renderSection, renderWarning, renderWarningErr, reportFailure } from "../ui.js";
import { printJson, relativePath } from "../format.js";
import { forMcp, suggest, toolCall } from "../next-step.js";
import {
  assessTargetStructure, checkGraphHealth, graphHealthJson, isUnhealthy, worseHealth, type GraphHealth,
} from "../graph-health.js";

/** The `--max-*` knobs that bound a bundle. */
interface BudgetSnapshot {
  maxEntities: number;
  maxRelationships: number;
  maxEvidence: number;
  maxTokens: number;
  maxChars: number;
}

/**
 * The budgets, described once: flag key, output label, clamp range, and the
 * default applied when the flag is absent.
 *
 * These four facts used to live in five hand-maintained places -- the option
 * registration, the `clampInt` calls, the record fields, the prose formatter
 * and the requested-budget reader -- so a fifth budget meant five edits and
 * missing one was silent. They had already drifted: a comment on the
 * registration described `clampInt(opts.max*, 1, 500, 50)` as if it were the
 * rule for all four, which is right for entities and wrong for the rest
 * (`--max-chars` is 1000-1000000 defaulting to 12000). Everything below reads
 * this table, and `--help` interpolates it, so the number a user is told is
 * the number that is applied.
 */
/**
 * Hard cap on the conflict reports carried in a bundle. Not a `--max-*` flag:
 * the bundle reports the count it saw either way, and a caller who needs every
 * report wants `ix conflicts`, not a bigger context bundle.
 */
const MAX_CONFLICTS = 10;

const BUDGETS = [
  { key: "maxEntities", flag: "--max-entities", label: "entities", help: "Maximum entities in the bundle", min: 1, max: 500, fallback: 50 },
  { key: "maxRelationships", flag: "--max-relationships", label: "relationships", help: "Maximum relationships in the bundle", min: 1, max: 1000, fallback: 100 },
  { key: "maxEvidence", flag: "--max-evidence", label: "evidence", help: "Maximum evidence items in the bundle", min: 1, max: 200, fallback: 25 },
  { key: "maxTokens", flag: "--max-tokens", label: "tokens", help: "Token budget for the printed output (llm: all of it; json and text: the evidence)", min: 500, max: 200_000, fallback: 3_000 },
  { key: "maxChars", flag: "--max-chars", label: "chars", help: "Character budget for the printed output (llm: all of it; json and text: the evidence)", min: 1000, max: 1_000_000, fallback: 12_000 },
] as const satisfies ReadonlyArray<{
  key: keyof BudgetSnapshot;
  flag: string;
  label: string;
  help: string;
  min: number;
  max: number;
  fallback: number;
}>;

/**
 * `--help` text for one budget flag.
 *
 * The Commander defaults were removed so an absent flag is distinguishable
 * from one set to the default value -- `--diff` reports which budgets the
 * caller actually asked for. Removing them also removed `(default: "50")` from
 * `ix context --help`, leaving four flags whose default and range a user could
 * not discover from the CLI at all, so the text says both, read off the table
 * that enforces them.
 */
function budgetHelp(key: keyof BudgetSnapshot): string {
  const b = budgetField(key);
  return `${b.help} (default: ${b.fallback}, clamped to ${b.min}-${b.max})`;
}

/** The table row for one budget. */
function budgetField(key: keyof BudgetSnapshot): (typeof BUDGETS)[number] {
  return BUDGETS.find((entry) => entry.key === key)!;
}

/**
 * The Commander `argParser` for one budget flag.
 *
 * The example in the rejection message comes from the flag's own default, not
 * from a constant: a single hardcoded "50" told someone who mistyped
 * `--max-chars` to try 50, which parses and is then silently clamped up to 1000
 * by `clampBudgets` -- while the help text one line away says the range is
 * 1000-1000000.
 */
function budgetParser(key: keyof BudgetSnapshot): (value: string) => number {
  const example = String(budgetField(key).fallback);
  return (value: string) => parseBudgetOption(value, example);
}

/** The text a bundle is printed as: `--format llm`, `--format json`, or the prose fallthrough. */
export type BundleFormat = "llm" | "json" | "text";

/** Maps a `--format` value the way `renderBundle` does: anything but json and llm is prose. */
export function bundleFormat(fmt: string | undefined): BundleFormat {
  return fmt === "json" ? "json" : fmt === "llm" ? "llm" : "text";
}

/**
 * Characters per token, by the format the bundle is printed in.
 *
 * `--max-tokens` is charged against the text that is actually emitted, so the
 * ratio is per format. Every format still uses 2.14, the value measured across
 * 41 recorded bundles (JSON plus prompt) and the one saved investigations were
 * sized at, so the default budget is the 6,420 characters it has always been.
 * cl100k measured llm 3.73 and json 2.69 on the audit fixture, so 2.14 is
 * conservative for both: a bundle comes in under its token budget, never over.
 *
 * Raising a ratio makes every default bundle larger (the ix-bench result that
 * all expected files appear at 3,000 tokens was measured at 2.14), so it waits
 * until that is re-measured. Never raise one to make a bundle fit.
 */
export const CHARS_PER_TOKEN: Record<BundleFormat, number> = { llm: 2.14, json: 2.14, text: 2.14 };

/**
 * Apply the table's range and default to whatever the caller supplied, and
 * turn the token budget into the character budget that bounds the evidence.
 *
 * `--max-tokens` is the budget a caller actually has: the thing being spent is
 * a context window, and 12,000 characters is a number nobody can convert in
 * their head into what it costs them. `--max-chars` stays for the caller who
 * needs exact bytes, and wins outright when passed — the two together are
 * refused up front rather than silently ranked, because which one lost is not
 * visible in the output.
 */
export function clampBudgets(opts: Partial<BudgetSnapshot>, format: BundleFormat = "json"): BudgetSnapshot {
  const out = {} as BudgetSnapshot;
  for (const b of BUDGETS) {
    const raw = opts[b.key];
    out[b.key] = raw === undefined ? b.fallback : Math.min(b.max, Math.max(b.min, raw));
  }
  if (opts.maxChars === undefined) {
    const chars = budgetField("maxChars");
    out.maxChars = Math.min(
      chars.max,
      Math.max(chars.min, Math.round(out.maxTokens * CHARS_PER_TOKEN[format])),
    );
  }
  return out;
}

interface ContextOptions extends Partial<BudgetSnapshot> {
  /** An issue or bug report to start from, in place of a target: a file, or `-` for stdin. */
  fromIssue?: string;
  /** With `--from-issue`: only the trusted starting points and a few ranked files. */
  lean?: boolean;
  kind?: string;
  path?: string;
  pick?: number;
  depth?: string;
  asOfRev?: number;
  out?: string;
  save?: string;
  resume?: string;
  diff?: string;
  list?: boolean;
  format: string;
}

const CONTEXT_DEPTHS = ["compact", "standard", "full", "shallow", "deep"] as const;

/**
 * The depth vocabulary the backend understands, and what to do about anything
 * else.
 *
 * `ContextService` normalizes `shallow`->`compact` and `deep`->`full`, then
 * picks its limits with a `case _` that lands every unrecognized value on the
 * `standard` tier. So `--depth 2` was never an error: it silently ran a
 * standard-depth query, and scripts have been passing values like it.
 *
 * Rejecting those outright would be a breaking change in a patch release, for
 * a flag whose wrong values were previously harmless. So this warns and does
 * exactly what the backend already did with them — the typo still gets
 * surfaced, on stderr so `--format json` and `--format llm` stay parseable,
 * but nobody's pipeline starts exiting 1 on upgrade.
 *
 * Deliberately not an `InvalidArgumentError`, unlike `--pick` and `--as-of-rev`
 * next to it: those reject values that have no defined meaning, whereas this
 * one has a defined meaning and it is `standard`.
 */
export function parseContextDepthOption(value: string): string {
  const normalized = value.trim().toLowerCase();
  if ((CONTEXT_DEPTHS as readonly string[]).includes(normalized)) return normalized;

  renderWarningErr(
    `--depth ${value} is not one of ${CONTEXT_DEPTHS.join(", ")}; using standard.`
  );
  return "standard";
}

/** Stable evidence kinds, ordered by relevance tier (lower is more relevant). */
type EvidenceKind =
  | "target"
  | "structural"
  | "claim"
  | "decision"
  | "conflict"
  | "intent"
  | "relationship"
  | "provenance";

/** Where an evidence item is defined, when the graph knows. */
interface EvidenceLocation {
  path: string;
  lineStart?: number;
  lineEnd?: number;
}

interface EvidenceItem {
  id: string;
  kind: EvidenceKind;
  source: string;
  title: string;
  /** Deterministic relevance score: tier plus a stable tiebreaker. */
  score: number;
  reason: string;
  refs: string[];
  /**
   * Without it an agent handed `member resolveWorkspaceRoot` has to search the
   * repository for the thing Ix just found -- and for a file target named
   * `config.ts`, first work out which of several `config.ts` files it was.
   */
  location?: EvidenceLocation;
  /**
   * How many of how many, for a row that samples a larger set (the "used by"
   * row). Structured so the number can be rendered as a floor where the backend
   * capped it, without parsing the title.
   */
  count?: { shown: number; total: number };
}

interface ContextBundle {
  schema: typeof BUNDLE_SCHEMA;
  /**
   * The one explicitly declared time-dependent field. Absent from the MCP
   * structured copy so identical calls are byte-identical.
   */
  generatedAt?: string;
  target: { id: string; name: string; kind: string; resolutionMode: string; path?: string };
  /**
   * Where an issue's bundle starts, and what in the issue did not resolve.
   * Only on a bundle built with `--from-issue`; absent, not empty, otherwise.
   */
  issue?: IssueSummary;
  /** The files to read for the issue, best first. Only with `--from-issue`. */
  rankedFiles?: RankedFile[];
  entities: Array<{
    id: string;
    name: string;
    kind: string;
    path?: string;
    lineStart?: number;
    lineEnd?: number;
    stale: boolean;
  }>;
  relationships: Array<{ src: string; dst: string; predicate: string }>;
  claims: Array<{ id: string; entityId: string; statement: string; status: string }>;
  decisions: DecisionReport[];
  conflicts: ConflictReport[];
  intents: IntentReport[];
  provenance: {
    sourceUri?: string;
    sourceHash?: string;
    extractor?: string;
    sourceType?: string;
    observedAt?: string;
    introducedRev?: number;
    historyLength: number;
    stale: boolean;
  };
  /**
   * `degraded` when the graph has lost its structural edges (see
   * graph-health.ts): nothing is known to have changed on disk, but the
   * bundle's members, callers and neighbours are missing, not absent.
   */
  freshness: { stale: boolean; classification: "current" | "stale" | "unverified" | "degraded" };
  /** Present only for a degraded or empty graph: what is wrong and the fix. */
  graph?: Record<string, unknown>;
  evidence: EvidenceItem[];
  /** `format` is the output the budget was sized for; absent on bundles saved before it existed (json sizing). */
  budgets: BudgetSnapshot & { format?: BundleFormat };
  truncation: {
    entitiesTruncated: number;
    relationshipsTruncated: number;
    evidenceTruncated: number;
    charactersTruncated: number;
    conflictsTruncated: number;
    /**
     * What the budget dropped, by category, largest first.
     *
     * The counts above say how much went; this says what it was. "Rerun with
     * larger --max-* budgets" was the same sentence for a file that lost 36 of
     * its own members and for a symbol that lost two claims, and it named the
     * one lever that costs the caller the most to pull.
     */
    cut?: Array<{ what: string; count: number }>;
  };
  metadata: {
    asOfRev?: number;
    depth?: string;
    rankingRule: "deterministic-tier";
  };
}

/**
 * Build a bounded, deterministic context bundle for one target.
 *
 * This composes Ix's existing intelligence rather than re-deriving it: the
 * target is resolved through the same resolver as `ix explain`, structural
 * facts come from the same collector, and claims/conflicts/decisions/intents
 * come from the same `/v1/context` service. The only new thing here is the
 * bundling, budgeting, and deterministic ranking.
 */
export function registerContextCommand(program: Command): void {
  program
    .command("context [target]")
    .description(
      "Build a bounded, deterministic context bundle for a symbol, file, or entity (or resume/diff a saved investigation without a target)",
    )
    .option(
      "--from-issue <file>",
      "Start from an issue or bug report instead of a target: a file, or - for stdin",
    )
    .option(
      "--lean",
      "With --from-issue: only the starting points Ix trusts and the next few files, or one line saying it trusts none",
    )
    .option("--kind <kind>", "Filter target entity by kind")
    .option("--path <path>", "Restrict to symbols from files matching this path substring")
    .option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
    .option(
      "--depth <depth>",
      `Context-graph expansion depth (${CONTEXT_DEPTHS.join("|")})`,
      parseContextDepthOption,
    )
    .option("--as-of-rev <n>", "Historical context as of a graph revision", parseRevisionOption)
    // No Commander default on the --max-* flags, so `parseRequestedBudgets`
    // can tell an absent flag from one set to the default value. The defaults
    // and ranges are the BUDGETS table's, applied by `clampBudgets` and shown
    // in the help text by `budgetHelp` -- they differ per flag, so there is no
    // single pair to name here.
    .option("--max-entities <n>", budgetHelp("maxEntities"), budgetParser("maxEntities"))
    .option("--max-relationships <n>", budgetHelp("maxRelationships"), budgetParser("maxRelationships"))
    .option("--max-evidence <n>", budgetHelp("maxEvidence"), budgetParser("maxEvidence"))
    .option("--max-tokens <n>", budgetHelp("maxTokens"), budgetParser("maxTokens"))
    // Not `budgetHelp`: there is no independent default to name any more. The
    // character budget is derived from `--max-tokens` unless this flag is
    // passed, and printing "(default: 12000)" beside a flag whose absence
    // produces 3,210 would be the kind of drift the BUDGETS table exists to
    // stop.
    .option(
      "--max-chars <n>",
      `${budgetField("maxChars").help} (overrides --max-tokens; clamped to ${budgetField("maxChars").min}-${budgetField("maxChars").max})`,
      budgetParser("maxChars"),
    )
    .option("--format <fmt>", "Output format (text|json|llm)", "text")
    .option("--out <path>", "Write the JSON bundle to this file instead of stdout")
    .option("--save <id>", "Persist the bundle as a resumable investigation state")
    .option("--resume <id>", "Render a saved investigation state without a backend")
    .option("--diff <id>", "Diff a saved investigation against a fresh build of the same target")
    .option("--list", "List saved investigations (no target, no backend)")
    .addHelpText(
      "after",
      "\nExamples:\n  ix context IngestionService\n  ix context src/main.ts --format json\n  ix context --from-issue issue.md --format llm\n  gh issue view 123 --json body -q .body | ix context --from-issue -\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, target);
      if (conflict) {
        reportFailure("mode_conflict", conflict, opts.format);
        return;
      }
      // The output the evidence budget is charged against; --out writes JSON.
      const fmt = opts.out ? "json" : bundleFormat(opts.format);
      if (opts.resume) {
        renderSavedInvestigation(opts.resume, opts.format);
        return;
      }
      if (opts.list) {
        // 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;
      }
      if (opts.diff) {
        const saved = loadInvestigation(opts.diff, opts.format);
        if (!saved) return;
        if (saved.bundle.issue && !target) {
          // The fresh side would be `ix context <centre>`: a named-target
          // bundle without the issue's rows, so every diff would report them
          // removed. The issue's text is not saved, so it cannot be rebuilt.
          reportFailure(
            "diff_unsupported",
            `Investigation "${opts.diff}" was built with --from-issue, and --diff can only rebuild a bundle from a named target. Run ix context --resume ${opts.diff} to see it, or build it again with --from-issue.`,
            opts.format,
          );
          return;
        }
        // The fresh side of --diff is built with the saved investigation's own
        // budgets, the argument to `buildFreshBundle` below, so any --max-*
        // flags the caller passed are not applied to it. Captured here so the
        // diff output can report what was asked for instead of dropping it
        // silently; what actually governed is read back off the built bundle.
        const requestedBudgets = parseRequestedBudgets(opts);
        const fresh = await buildFreshBundle(
          target ?? saved.bundle.target.name,
          { ...opts, ...mergeDiffOptions(saved, opts) },
          saved.bundle.budgets,
          opts.format,
        );
        if (!fresh) return;
        renderInvestigationDiff(saved, fresh, opts.format, requestedBudgets);
        return;
      }
      if (opts.fromIssue && opts.lean) {
        await emitLeanIssue(opts.fromIssue, opts);
        return;
      }
      if (opts.fromIssue) {
        const bundle = await buildIssueBundle(opts.fromIssue, opts, clampBudgets(opts, fmt), fmt);
        if (bundle) await emitBundle(bundle, opts);
        return;
      }
      if (!target) {
        // An error with a non-zero status, not a stdout warning with a zero one:
        // a script asked for a bundle and got none, and a `--format llm` caller
        // got a prose line in the middle of a record stream saying so.
        reportFailure(
          "missing_target",
          "ix context requires a target unless --from-issue <file>, --resume <id>, --diff <id> or --list is given.",
          opts.format,
        );
        return;
      }

      const client = createClient({ query: true });

      const resolved = await resolveFileOrReport(client, target, {
        kind: opts.kind,
        path: opts.path,
        pick: opts.pick,
      }, opts.format);
      if (!resolved) return;

      const budgets = clampBudgets(opts, fmt);
      const asOfRev = opts.asOfRev;

      const [facts, context, workspaceHealth] = await Promise.all([
        // Also carries the provenance response: `collectFacts` needs it for the
        // history length, and fetching it again here doubled one of the
        // slowest calls the command makes (~1.3s on the Ix repo's graph).
        collectContextFacts(client, resolved),
        // By id, not by name. Seeding by name makes the backend re-run the
        // search the resolver just did, and it can land on a different node of
        // the same name. Both call sites in this file must use it: converting
        // only one makes `--diff` compare a by-id bundle against a by-name one
        // and report the whole graph as changed.
        client.contextForNode(resolved.id, {
          asOfRev,
          depth: opts.depth,
        }),
        // Cached per backend revision (graph-health.ts); in parallel, so free
        // on a warm cache.
        checkGraphHealth(client, activeReadScope()),
      ]);
      const provenance = facts.provenance;

      const bundle = buildBundle({
        resolved,
        facts,
        context,
        provenance,
        asOfRev,
        depth: opts.depth,
        budgets,
        format: fmt,
        graphCompleted: hasCompletedSourceGraphBaseline(),
        graphHealth: bundleGraphHealth(workspaceHealth, resolved, facts),
      });

      await emitBundle(bundle, opts);
    });

/** `--save`, `--out`, or render: what every freshly built bundle goes through. */
async function emitBundle(bundle: ContextBundle, opts: ContextOptions): Promise<void> {
  if (opts.save) {
    saveInvestigation(opts.save, bundle);
    renderNote(`Saved investigation "${opts.save}" (${bundle.entities.length} entities, ${bundle.relationships.length} relationships, ${bundle.evidence.length} evidence items). Resume with: ix context --resume ${opts.save}`);
    return;
  }

  if (opts.out && opts.format !== "json") {
    // stderr: --out still writes the file and still prints a note, so this
    // advisory would otherwise sit in the stdout an `llm` caller is reading.
    renderWarningErr("--out writes JSON; ignoring --format and forcing json.");
  }
  const out = opts.out;
  if (out) {
    const fs = await import("node:fs");
    // Validate the network-derived bundle against the versioned contract
    // before persisting it: only a bundle matching ix-context-bundle/1 is
    // written, so a malformed or unexpected backend payload can never land
    // in a caller-owned file (CodeQL js/network-data-written-to-file).
    const parsed = contextBundleSchema.safeParse(bundle);
    if (!parsed.success) {
      reportFailure(
        "out_refused",
        `--out "${out}" refused: the bundle does not match the ${BUNDLE_SCHEMA} schema (${parsed.error.issues.length} issue(s)).`,
        opts.format,
      );
      return;
    }
    // Atomic write: serialize to a private temp file in the SAME directory,
    // then rename over the target, so the write is never a check-then-write
    // race and a partial file is never visible (CodeQL js/file-system-race;
    // same pattern as the config writer in src/cli/config.ts). Renaming
    // onto an existing directory fails, which surfaces as the refusal below.
    const targetPath = resolve(out);
    const tmpPath = join(dirname(targetPath), `.${process.pid}.${Date.now().toString(36)}.tmp`);
    try {
      fs.writeFileSync(tmpPath, JSON.stringify(parsed.data, null, 2) + "\n", "utf8");
      fs.renameSync(tmpPath, targetPath);
    } catch (error) {
      try { fs.rmSync(tmpPath, { force: true }); } catch { /* best effort */ }
      const err = error as NodeJS.ErrnoException;
      if (err.code === "EISDIR" || err.code === "EPERM") {
        try {
          if (fs.statSync(targetPath).isDirectory()) {
            reportFailure(
              "out_refused",
              `--out "${out}" is a directory; refusing to write the bundle there.`,
              opts.format,
            );
            return;
          }
        } catch { /* target may not exist; fall through to rethrow */ }
      }
      throw error;
    }
    renderNote(`Wrote ${parsed.data.entities.length} entities, ${parsed.data.relationships.length} relationships, ${parsed.data.evidence.length} evidence items to ${out}`);
    return;
  }
  renderBundle(bundle, opts.format);
}

async function buildFreshBundle(
  target: string,
  opts: { kind?: string; path?: string; pick?: number; depth?: string; asOfRev?: number },
  budgets: BudgetSnapshot & { format?: BundleFormat },
  format: string,
): Promise<ContextBundle | undefined> {
  const client = createClient({ query: true });
  const resolved = await resolveFileOrReport(client, target, {
    kind: opts.kind,
    path: opts.path,
    pick: opts.pick,
  }, format);
  if (!resolved) return undefined;

  const asOfRev = opts.asOfRev;
  const [facts, context, workspaceHealth] = await Promise.all([
    collectContextFacts(client, resolved),
    client.contextForNode(resolved.id, { asOfRev, depth: opts.depth }),
    checkGraphHealth(client, activeReadScope()),
  ]);

  return buildBundle({
    resolved, facts, context, provenance: facts.provenance, asOfRev, depth: opts.depth, budgets,
    // The saved bundle's own sizing format, not the diff's render format, so --diff compares like with like.
    format: budgets.format ?? "json",
    graphCompleted: hasCompletedSourceGraphBaseline(),
    graphHealth: bundleGraphHealth(workspaceHealth, resolved, facts),
  });
}
}


/**
 * What `detectContextModeConflict` reads: all of `ContextOptions`.
 *
 * Derived from the action handler's own declaration, never hand-copied. The
 * detector exists to stop a typed flag being a no-op, so a shape it maintains
 * separately is the one thing it cannot afford: written out field-by-field it
 * drifted immediately, when `--list` was added to `ContextOptions` on a sibling
 * branch and the detector could not see it with nothing from the typechecker to
 * say so. `Partial` so the pure function can be called with one flag at a time
 * in a test, without inventing a `format`.
 */
export type ContextModeOptions = Partial<ContextOptions>;

/**
 * Flags that shape a bundle this run builds, and are therefore meaningless to a
 * mode that builds none.
 *
 * `--list` enumerates saved state and `--resume` renders it verbatim; neither
 * resolves a target or applies a budget, so every one of these was accepted and
 * dropped in silence — `ix context --list --max-entities 10 --kind class` took
 * five typed flags and exited 0. `--diff` is not here: it re-resolves the target
 * with `--kind`/`--path`/`--pick`, forwards `--depth`/`--as-of-rev` through
 * `mergeDiffOptions`, and reports the `--max-*` values rather than dropping
 * them.
 *
 * Listed as `[field, flag]` because the message has to name what the user
 * typed, and Commander's camelCase attribute is not that.
 */
const BUILD_FLAGS: ReadonlyArray<[keyof ContextOptions, string]> = [
  ["fromIssue", "--from-issue"],
  ["kind", "--kind"],
  ["path", "--path"],
  ["pick", "--pick"],
  ["depth", "--depth"],
  ["asOfRev", "--as-of-rev"],
  ...BUDGETS.map((b) => [b.key, b.flag] as [keyof ContextOptions, string]),
];

/**
 * Detect mutually-incompatible mode/output flags on `ix context` and return a
 * human-readable message naming the conflict, or `undefined` if no conflict.
 *
 * The action handler used to silently drop `--save` and `--out` whenever
 * `--resume` or `--diff` was passed (those branches `return` before the
 * `--save`/`--out` branches ever run). It also accepted `--save <id>` alongside
 * `--out <file>`, which describes two different write targets and so has no
 * 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` and `ix context Widget --resume x` both dropped it
 * with nothing said.
 */
export function detectContextModeConflict(
  opts: ContextModeOptions,
  target?: string,
): string | undefined {
  if (opts.lean && opts.fromIssue === undefined) {
    return "--lean only shapes a bundle built with --from-issue; add --from-issue <file>, or drop --lean.";
  }
  if (opts.lean && (opts.save || opts.out)) {
    return `--lean cannot be combined with ${opts.save ? "--save" : "--out"}; a lean view is a few lines of pointers, not a bundle to persist. Drop --lean to save the full bundle.`;
  }
  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.resume && target) {
    return `--resume takes no target; it renders the investigation you name, whatever that was built for. Drop "${target}", or use --diff <id> to compare a saved investigation against a fresh build of it.`;
  }
  if (opts.fromIssue !== undefined) {
    // The issue is the target: it names its own starting points, so a second
    // target, or a flag that narrows the candidates for one, has nothing to
    // act on. `--diff` rebuilds a saved investigation by its target's name,
    // which a bundle built from an issue does not have.
    if (target) {
      return `--from-issue takes no target; the issue's text picks the starting points. Drop "${target}", or drop --from-issue to build a bundle for it.`;
    }
    if (opts.diff) {
      return "--from-issue cannot be combined with --diff; --diff rebuilds a saved investigation from its target's name. Save the issue's bundle with --save and --resume it instead.";
    }
    const narrowing = ([["kind", "--kind"], ["path", "--path"], ["pick", "--pick"]] as const)
      .filter(([field]) => opts[field] !== undefined)
      .map(([, flag]) => flag);
    if (narrowing.length > 0 && !opts.list && !opts.resume) {
      return `${narrowing.join(", ")} cannot be combined with --from-issue; ${narrowing.length > 1 ? "they narrow" : "it narrows"} the candidates for a named target, and the issue's starting points are chosen from its text.`;
    }
  }
  // Flags that shape a bundle, given to a mode that builds none. Reported as
  // one message naming every offender, because dropping one at a time and
  // re-running to find the next is the experience this detector exists to
  // avoid, and the flags are all wrong for the same reason.
  for (const [mode, why] of [
    ["list", "--list enumerates saved investigations and builds no bundle"],
    ["resume", "--resume renders a saved investigation exactly as it was built"],
  ] as const) {
    if (!opts[mode]) continue;
    const ignored = BUILD_FLAGS.filter(([field]) => opts[field] !== undefined).map(([, flag]) => flag);
    if (ignored.length > 0) {
      return `${ignored.join(", ")} cannot be combined with --${mode}; ${why}, so ${ignored.length > 1 ? "those flags change" : "that flag changes"} nothing. Drop ${ignored.length > 1 ? "them" : "it"}, or run ix context <target> to build a bundle with ${ignored.length > 1 ? "them" : "it"}.`;
    }
  }
  if (opts.maxTokens !== undefined && opts.maxChars !== undefined) {
    // Refused rather than ranked. They bound the same thing — the evidence
    // block — in two units, and whichever one lost does not appear anywhere in
    // the output, so a caller who set both would have no way to tell which
    // budget was applied. Same rule `ix diff` uses for --summary and --limit.
    return "--max-tokens and --max-chars cannot be combined; both bound the evidence block, in different units. Use --max-tokens for a context-window budget, or --max-chars for exact bytes.";
  }
  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.";
  }
  if (opts.resume && opts.save) {
    return "--resume cannot be combined with --save; --resume only renders a saved investigation, while --save writes a new one. Run --save on a fresh build instead.";
  }
  if (opts.resume && opts.out) {
    // No "use --format json with --out" hint here. That hint was unactionable:
    // this branch fires on `--resume` plus `--out` whatever the format, so a
    // user who followed it landed straight back on the same error, this time
    // with no advice at all. The two things that do work are a redirect and
    // the saved file itself, so name those.
    return "--resume cannot be combined with --out; --resume renders to stdout."
      + " Redirect it (`ix context --resume <id> --format json > <path>`), or read"
      + " IX_HOME/investigations/<id>.json, which is already the saved JSON.";
  }
  if (opts.diff && opts.save) {
    return "--diff cannot be combined with --save; --diff renders a comparison against a saved investigation. To persist the fresh side as a new investigation, run the fresh build without --diff and use --save there.";
  }
  if (opts.diff && opts.out) {
    return "--diff cannot be combined with --out; --diff renders the comparison to stdout.";
  }
  if (opts.save && opts.out) {
    return "--save and --out cannot be combined; --save writes to IX_HOME/investigations/<id>.json, while --out writes to a caller-chosen path. Pick one.";
  }
  return undefined;
}

/** Saved investigation state lives under ~/.ix/investigations. */
function investigationDir(): string {
  // IX_HOME is the Ix home *directory*, not the investigations directory —
  // backend-status.ts, docker.ts and upgrade.ts all read it as `IX_HOME ||
  // ~/.ix` and then join their own subdirectory onto it. Putting the subdirectory
  // only in the fallback made the two branches disagree: with IX_HOME set, saved
  // investigations landed loose in the Ix home beside config.yaml, bin/ and cli/,
  // and `investigations/` was never created at all.
  return join(process.env.IX_HOME || join(homedir(), ".ix"), "investigations");
}

function investigationPath(id: string): string {
  return join(investigationDir(), `${sanitizeId(id)}.json`);
}

/**
 * Encode an investigation id into a filesystem-safe file name, injectively.
 *
 * `[A-Za-z0-9._-]` passes through unchanged; every other UTF-16 code unit —
 * including the escape marker `~` itself — is hex-encoded, as `~HH` below
 * U+0100 and `~uHHHH` at or above it. Two different logical ids can therefore
 * never map to the same file, and a raw `~` in user input cannot be confused
 * with an encoding: `a/b`, `a?b`, and `a~2Fb` all land in distinct,
 * single-segment files under the investigation directory instead of silently
 * colliding or escaping it.
 *
 * A leading `.` is encoded too, so no id can produce a dotfile. `.` is otherwise
 * an ordinary character here, and encoding it only in first position keeps the
 * mapping injective: `.a` becomes `~2Ea`, which no other id can also produce.
 */
export function sanitizeId(id: string): string {
  let out = "";
  // Iterate UTF-16 code units, not code points. `for...of` walks code points
  // while `charCodeAt(0)` reads only the leading surrogate, so every astral
  // character encoded as just its high surrogate and they all collided (#478).
  for (let i = 0; i < id.length; i++) {
    const ch = id[i];
    if (/[A-Za-z0-9._-]/.test(ch)) {
      out += ch;
      continue;
    }
    const code = id.charCodeAt(i);
    // Two escape widths, and the `u` is what keeps them apart. A bare
    // `~HHHH` would be ambiguous: `~D83D` reads equally well as one code unit
    // or as `~D8` followed by the literal characters `3D`, and hex digits pass
    // through unencoded, so both readings are producible. That is not
    // hypothetical — it is how U+1F600 collided with the ordinary string
    // `Ø3DÞ00`, which is the same overwrite bug #478 was about, one layer down.
    //
    // `u` cannot be confused with the narrow form because it is not a hex
    // digit, and a literal `~` in the input is itself encoded (`~7E`), so the
    // character after an escape marker is never user data.
    //
    // The narrow form is kept for everything below U+0100 so that every id
    // already on disk keeps the name it was saved under.
    out += code < 0x100
      ? `~${code.toString(16).toUpperCase().padStart(2, "0")}`
      : `~u${code.toString(16).toUpperCase().padStart(4, "0")}`;
  }
  if (out.startsWith(".")) out = `~2E${out.slice(1)}`;
  return out || "unnamed";
}

/**
 * The id to show the user, given the id stored on disk.
 *
 * `sanitizeId` is deliberately *not* idempotent — it encodes `~` as `~7E` so a
 * raw `~` cannot be mistaken for an escape — so the stored form is the wrong
 * thing to hand back. `ix context --list` printed it 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.
 *
 * Decodes both escape widths and then re-encodes to check itself, rather than
 * trusting the decode. The check is not ceremony: ids written before the
 * `~uHHHH` form existed still carry bare `~HHHH`, which decodes to a different
 * string than it was saved from, and the re-encode is what catches that and
 * returns the stored id untouched instead of showing a plausible wrong answer.
 * `loadInvestigation` accepts the stored form too, so a listed id loads either
 * way — the display is the nicety, the load is the contract.
 */
export function displayId(stored: string): string {
  const decoded = stored.replace(
    /~u([0-9A-Fa-f]{4})|~([0-9A-Fa-f]{2})/g,
    (_m, wide: string | undefined, narrow: string | undefined) =>
      String.fromCharCode(parseInt(wide ?? narrow ?? "", 16)),
  );
  return sanitizeId(decoded) === stored ? decoded : stored;
}

/**
 * The shape `sanitizeId` produces: what a file in the investigations directory
 * can be named, and therefore what `loadInvestigation` may accept verbatim.
 *
 * The leading character excludes `.` so no input names a dotfile, and the set
 * excludes every path separator, so nothing here can address a second directory
 * segment or a parent.
 */
const STORED_ID = /^[A-Za-z0-9_~-][A-Za-z0-9._~-]*$/;

export function saveInvestigation(id: string, bundle: ContextBundle): void {
  const dir = investigationDir();
  mkdirSync(dir, { recursive: true });
  // Refuse to persist a bundle that does not match the versioned contract:
  // network-derived investigation state is validated before it reaches disk
  // (CodeQL js/network-data-written-to-file).
  const parsed = contextBundleSchema.safeParse(bundle);
  if (!parsed.success) {
    renderWarning(`Refusing to save investigation "${id}": the bundle does not match the ${BUNDLE_SCHEMA} schema (${parsed.error.issues.length} issue(s)).`);
    return;
  }
  const state = {
    schema: "ix-investigation/1",
    id: sanitizeId(id),
    savedAt: new Date().toISOString(),
    bundle: parsed.data,
  };
  // Atomic write (temp + rename in the same directory), matching the config
  // writer, so a saved investigation is never partially written (CodeQL
  // js/file-system-race).
  const path = investigationPath(id);
  const tmpPath = join(dirname(path), `.${process.pid}.${Date.now().toString(36)}.tmp`);
  writeFileSync(tmpPath, JSON.stringify(state, null, 2) + "\n", "utf8");
  try {
    renameSync(tmpPath, path);
  } catch (err) {
    try { rmSync(tmpPath, { force: true }); } catch { /* best effort */ }
    throw err;
  }
}

interface SavedInvestigation {
  schema: string;
  id: string;
  savedAt: string;
  bundle: ContextBundle;
}

/**
 * Carry the saved investigation's revision and depth into a fresh `--diff`
 * build unless the caller explicitly overrides them, so a plain
 * `ix context --diff <id>` compares like-for-like instead of silently
 * re-basing the saved state onto current HEAD.
 */
export function mergeDiffOptions(
  saved: SavedInvestigation,
  opts: { asOfRev?: number; depth?: string },
): { asOfRev?: number; depth?: string } {
  // Numbers on both sides now: `--as-of-rev` is validated by its Commander
  // argParser, so the round trip through a string that this used to do -- and
  // the `parseInt` on the far side of it -- is gone.
  return {
    asOfRev: opts.asOfRev ?? saved.bundle.metadata.asOfRev,
    depth: opts.depth ?? saved.bundle.metadata.depth,
  };
}

/**
 * Enumerate every saved investigation under IX_HOME/investigations.
 *
 * Validated with `savedInvestigationSchema` — the same contract the write side
 * and `loadInvestigation` enforce — rather than a hand-rolled envelope check
 * beside it. A file that fails it is skipped and counted; the count is
 * returned, not printed, because this runs before the renderer knows which
 * format was asked for.
 *
 * Determinism: newest first by `savedAt`, falling back to the id so two files
 * saved in the same millisecond still order stably across runs.
 */
export function listInvestigations(): { saved: SavedInvestigation[]; skipped: number } {
  const dir = investigationDir();
  if (!existsSync(dir)) return { saved: [], skipped: 0 };
  const entries = readdirSync(dir).filter((f) => f.endsWith(".json"));
  const out: SavedInvestigation[] = [];
  let skipped = 0;
  for (const file of entries) {
    let raw: unknown;
    // Scoped to the read and the parse, as in `loadInvestigation`: they are the
    // only calls here that throw.
    try {
      raw = JSON.parse(readFileSync(join(dir, file), "utf8"));
    } catch {
      skipped += 1;
      continue;
    }
    const parsed = savedInvestigationSchema.safeParse(raw);
    if (!parsed.success) {
      skipped += 1;
      continue;
    }
    // The validated value, not the raw parse — the same assertion
    // `loadInvestigation` makes, and for the same reason: it re-narrows the
    // open report arrays the schema leaves as records, and every field the
    // renderer dereferences has been checked by this point. The id is decoded
    // here too, so every reader of an enumerated investigation sees the id it
    // can type back — see `displayId`.
    const state = parsed.data as unknown as SavedInvestigation;
    out.push({ ...state, id: displayId(state.id) });
  }
  out.sort((a, b) => {
    if (a.savedAt !== b.savedAt) return a.savedAt < b.savedAt ? 1 : -1;
    return cmp(a.id, b.id);
  });
  return { 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 — decoded by `displayId` on read. */
  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: 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`.
 *
 * 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 — 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
    // caller was piping. Plain text rather than chalk — nothing else in this
    // file writes to stderr, and a colour code is not worth an import that
    // only this line needs.
    renderWarningErr(
      `${skipped} saved investigation file(s) in ${investigationDir()} did not match the contract; skipped.`,
    );
  }
  if (format === "json") {
    printJson({ investigations: summaries, skipped });
    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: summaries.length, skipped: skipped || undefined }),
      ...summaries.map((s) =>
        llmLine("investigation", {
          id: s.id,
          saved_at: s.savedAt,
          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 (summaries.length === 0) {
    renderNote("No saved investigations. Use `ix context <target> --save <id>` to create one.");
    return;
  }
  renderSection(`Saved investigations (${summaries.length})`);
  for (const s of summaries) {
    console.log(`  ${s.id}`);
    console.log(`    target:       ${s.target.name} (${s.target.kind})`);
    console.log(`    saved_at:     ${s.savedAt}`);
    console.log(`    freshness:    ${s.freshness.classification}`);
    console.log(
      `    counts:       entities=${s.counts.entities} relationships=${s.counts.relationships} evidence=${s.counts.evidence}`,
    );
    if (
      s.truncation.entitiesTruncated ||
      s.truncation.relationshipsTruncated ||
      s.truncation.evidenceTruncated ||
      s.truncation.charactersTruncated
    ) {
      console.log(
        `    truncated:    entities=${s.truncation.entitiesTruncated} relationships=${s.truncation.relationshipsTruncated} evidence=${s.truncation.evidenceTruncated} chars=${s.truncation.charactersTruncated}`,
      );
    }
  }
  console.log();
  console.log(`Resume with: ix context --resume <id>`);
  console.log(`Diff with:   ix context --diff <id>`);
}

/**
 * Refuse a saved investigation: warn, and set a non-zero status so a scripted
 * `--resume`/`--diff` can tell a refusal from a successful render. The sibling
 * commands (config, init, map) already signal refusals this way.
 */
function refuseInvestigation(code: string, message: string, format?: string): undefined {
  // `--format llm` gets the record every sibling command emits for a failure
  // (`callers.ts`, `contains.ts`, `depends.ts`, `diff.ts`, `history.ts` all do
  // this, and docs/llm-format.md specifies the shape). This path used to write
  // `renderWarning`, which is `console.log`, so the one command being made
  // llm-clean answered a refusal with a chalk-coloured prose line in the middle
  // of the record stream — and with a prose line inside the JSON payload for a
  // `--format json` caller piping to `jq`. The human keeps the same wording, on
  // stderr, where prose belongs whatever the format.
  reportFailure(code, message, format);
  return undefined;
}

export function loadInvestigation(id: string, format?: string): SavedInvestigation | undefined {
  let path = investigationPath(id);
  if (!existsSync(path) && STORED_ID.test(id)) {
    // Also accept the on-disk form. `sanitizeId` is not idempotent, so an id
    // that is already encoded gets encoded again and misses its own file:
    // `widget/auth` is stored as `widget~2Fauth`, and asking for
    // `widget~2Fauth` looked for `widget~7E2Fauth`. `displayId` recovers the
    // typed form for every Latin-1 id, but the escape width is ambiguous above
    // that, so for the rest the encoded name is the only thing a listing can
    // print — and it has to work. Second, not first, so an id that is genuinely
    // spelled `widget~2Fauth` still finds its own file before this.
    const encoded = join(investigationDir(), `${id}.json`);
    if (existsSync(encoded)) path = encoded;
  }
  if (!existsSync(path)) {
    return refuseInvestigation("no_saved_investigation", `No saved investigation "${id}" at ${path}`, format);
  }
  let raw: unknown;
  // Scoped to the read and the parse: those are the only calls here that throw,
  // and widening it would report a validation or rendering failure below as
  // "not valid JSON" — naming the wrong cause on a file that parses fine.
  try {
    raw = JSON.parse(readFileSync(path, "utf8"));
  } catch {
    return refuseInvestigation("invalid_saved_investigation", `Saved investigation "${id}" is not valid JSON; refusing to resume.`, format);
  }

  // Validate the whole envelope coming back off disk against the same versioned
  // contract the write side enforces (saveInvestigation and --out). The two
  // halves were asymmetric: writes were schema-checked, reads trusted a bare
  // `as` cast guarded only by a truthiness check on `bundle`. That gap is
  // reachable — `--diff` re-resolves `bundle.target.name`, `metadata.depth` and
  // `metadata.asOfRev` and sends them to the backend, and `--resume` renders the
  // bundle — so a file whose `schema` field was right and whose body was
  // anything at all used to be honoured.
  const parsed = savedInvestigationSchema.safeParse(raw);
  if (!parsed.success) {
    const issues = parsed.error.issues;
    // Distinguish the two version-skew cases from a generic shape mismatch, so
    // the warning names which contract was not met.
    if (issues.some((issue) => issue.path[0] === "schema")) {
      return refuseInvestigation("invalid_saved_investigation", `Saved investigation "${id}" has an unknown schema; refusing to resume.`, format);
    }
    if (issues.some((issue) => issue.path[0] === "bundle" && issue.path[1] === "schema")) {
      return refuseInvestigation(
        "invalid_saved_investigation",
        `Saved investigation "${id}" holds a bundle from a different contract than ${BUNDLE_SCHEMA}; refusing to resume.`,
        format,
      );
    }
    return refuseInvestigation(
      "invalid_saved_investigation",
      `Saved investigation "${id}" does not match the ${BUNDLE_SCHEMA} schema (${issues.length} issue(s)); refusing to resume.`,
      format,
    );
  }
  // Return the validated value, not the raw parse: saveInvestigation persists
  // `parsed.data` for the same reason, so unknown keys smuggled into a
  // hand-edited file are dropped here rather than echoed back out by
  // `--resume --format json` or copied into the emitted diff.
  //
  // The assertion re-narrows the three report arrays the schema deliberately
  // leaves as open records (decisions/conflicts/intents, whose shapes belong to
  // the backend) plus the literals zod widens to `string`. Every field this file
  // dereferences has been checked by this point — unlike the `as` cast on raw
  // JSON.parse output that this replaces, which checked nothing.
  //
  // The id is decoded here, at the one boundary every reader comes through,
  // rather than at each place one is printed. Decoding per call site is how
  // `--format llm` came to report `widget/auth` while `--format json` and the
  // text header reported `widget~2Fauth` for the same investigation, and a
  // JSON-chaining caller fed the second back to `--resume` and was refused.
  const state = parsed.data as unknown as SavedInvestigation;
  return { ...state, id: displayId(state.id) };
}

export function renderSavedInvestigation(id: string, format: string): void {
  const saved = loadInvestigation(id, format);
  if (!saved) return;
  if (format === "json") {
    printJson(saved);
    return;
  }
  if (format === "llm") {
    // A record, not the prose note below. `renderNote` would put a
    // chalk-coloured English sentence at the head of a record stream, and
    // it carries the one fact the bundle records do not: when this snapshot
    // was taken. `classification=current` says it was fresh when it was
    // saved, not when that was.
    printLlmLines([llmLine("resumed", { id: saved.id, saved_at: saved.savedAt })]);
    renderBundle(saved.bundle, format);
    return;
  }
  renderNote(`Resumed investigation "${saved.id}" saved ${saved.savedAt}`);
  renderBundle(saved.bundle, format);
}

/**
 * A budget snapshot as llm record fields.
 *
 * Absent values are simply absent — `llmField` drops nullish, so a partial
 * override needs no `not-given` sentinel the way the prose form does.
 */
function budgetFields(b: Partial<BudgetSnapshot>): Record<string, number | undefined> {
  return Object.fromEntries(BUDGETS.map((f) => [f.label, b[f.key]]));
}

/** Compact one-line representation of a budget snapshot for human rendering. */
function formatBudgets(b: Partial<BudgetSnapshot>, partial = false): string {
  const segments = BUDGETS.map((f) => {
    const val = b[f.key];
    return `${f.label}=${val === undefined ? "not-given" : String(val)}`;
  }).join(" ");
  return partial ? `${segments} (CLI override; not applied to --diff fresh side)` : segments;
}

/**
 * Which `--max-*` flags the caller actually passed, or `undefined` for none.
 *
 * Validation happens once, at parse time: `parseBudgetOption` is the flags'
 * Commander `argParser`, so a value that reaches here is already a positive
 * integer. Reading the raw strings back out with `Number.parseInt` was not a
 * check — it took `"10abc"` as 10, `"1e3"` as 1 and `"-5"` as -5, and this
 * record's whole purpose is reporting what the caller asked for, so a silently
 * repaired number is the one error it cannot afford.
 *
 * Deliberately *not* clamped, unlike `clampBudgets` on a direct run: these
 * values are reported, never applied — saved budgets govern `--diff` — so
 * clamping them would report a budget the caller did not ask for either. If
 * they are ever made to win on the fresh side, they must be clamped there.
 */
export function parseRequestedBudgets(opts: Partial<BudgetSnapshot>): Partial<BudgetSnapshot> | undefined {
  const out: Partial<BudgetSnapshot> = {};
  let provided = false;
  for (const f of BUDGETS) {
    const value = opts[f.key];
    if (value === undefined) continue;
    out[f.key] = value;
    provided = true;
  }
  return provided ? out : undefined;
}

export function diffInvestigations(
  saved: SavedInvestigation,
  fresh: ContextBundle,
  requestedBudgets?: Partial<BudgetSnapshot>,
): InvestigationDiff {
  const prev = saved.bundle;
  const addedEntities = fresh.entities.filter((e) => !prev.entities.some((p) => p.id === e.id));
  const removedEntities = prev.entities.filter((p) => !fresh.entities.some((e) => e.id === p.id));
  const addedRelationships = fresh.relationships.filter(
    (r) => !prev.relationships.some((p) => p.src === r.src && p.dst === r.dst && p.predicate === r.predicate),
  );
  const removedRelationships = prev.relationships.filter(
    (p) => !fresh.relationships.some((r) => r.src === p.src && r.dst === p.dst && r.predicate === p.predicate),
  );
  // Same id and same title. A row that summarises a set -- `used-by`,
  // `recent-commits`, `related-files` -- keeps its id while what it says
  // changes, and matched on id alone a new top caller or a total going from 3
  // to 40 was no change at all. A changed row is reported as removed and added.
  const sameEvidence = (a: EvidenceItem, b: EvidenceItem) => a.id === b.id && a.title === b.title;
  const addedEvidence = fresh.evidence.filter((e) => !prev.evidence.some((p) => sameEvidence(p, e)));
  const removedEvidence = prev.evidence.filter((p) => !fresh.evidence.some((e) => sameEvidence(p, e)));
  const addedClaims = fresh.claims.filter((c) => !prev.claims.some((p) => p.id === c.id));
  const removedClaims = prev.claims.filter((p) => !fresh.claims.some((c) => c.id === p.id));

  // Read off the bundle that was actually built, not restated from the
  // argument that built it. `{ ...saved.bundle.budgets }` would assert how the
  // fresh side was constructed rather than report it: today the two agree, but
  // letting CLI overrides win would mean editing the `buildFreshBundle` call in
  // the action handler, and `effective` would go on reporting the saved budget
  // while the fresh side used another one -- the silent misreport this record
  // exists to prevent. `ContextBundle.budgets` records the truth on both sides.
  const effective: BudgetSnapshot = { ...fresh.budgets };
  // Whether the caller's --max-* flags governed the fresh side.
  //
  // Not `requested equals effective`. Equal numbers are not evidence of
  // causation: `--max-evidence 25` against a saved budget of 25 produces
  // identical values while the flag changed nothing, and reporting `true` there
  // told an agent its override had taken -- so it raised the number, got the
  // saved budget again and now `false`. Three formats of one command disagreed,
  // because the note printed beside it said the opposite.
  //
  // What decides this is which budget the action handler hands
  // `buildFreshBundle`, and that is `saved.bundle.budgets` unconditionally, one
  // call site named in the comment there. So this is false, and the day that
  // call changes it is the day this needs to change with it.
  const requestedApplied = false;

  return {
    schema: "ix-investigation-diff/1",
    investigation: saved.id,
    savedAt: saved.savedAt,
    generatedAt: new Date().toISOString(),
    target: fresh.target,
    freshness: { previous: prev.freshness, current: fresh.freshness },
    budgets: {
      saved: saved.bundle.budgets,
      requested: requestedBudgets,
      effective,
      // The same fact the llm record carries as `applied=`. It was prose only
      // here, so a JSON consumer had to string-match a sentence whose wording
      // changed with the case, while the llm consumer got a boolean it could
      // test. One contract, both formats.
      requestedApplied,
      // Prose for the human reading the JSON, and only when there is something
      // to explain: without --max-* flags the sentence said nothing.
      ...(requestedBudgets
        ? {
            note: "Saved investigation budgets govern --diff; the --max-* flags recorded here were not applied to the fresh side.",
          }
        : {}),
    },
    added: {
      entities: addedEntities,
      relationships: addedRelationships,
      evidence: addedEvidence,
      claims: addedClaims,
    },
    removed: {
      entities: removedEntities,
      relationships: removedRelationships,
      evidence: removedEvidence,
      claims: removedClaims,
    },
  };
}

interface InvestigationDiff {
  schema: string;
  investigation: string;
  savedAt: string;
  generatedAt: string;
  target: ContextBundle["target"];
  freshness: { previous: ContextBundle["freshness"]; current: ContextBundle["freshness"] };
  budgets: {
    saved: BudgetSnapshot;
    requested?: Partial<BudgetSnapshot>;
    effective: BudgetSnapshot;
    /** Did `requested` govern the fresh side? The testable form of `note`. */
    requestedApplied: boolean;
    /** Present only when `requested` is: without it there is nothing to explain. */
    note?: string;
  };
  added: { entities: ContextBundle["entities"]; relationships: ContextBundle["relationships"]; evidence: EvidenceItem[]; claims: ContextBundle["claims"] };
  removed: { entities: ContextBundle["entities"]; relationships: ContextBundle["relationships"]; evidence: EvidenceItem[]; claims: ContextBundle["claims"] };
}

/** Which side of a comparison a record is on, or neither for a plain bundle. */
type RecordChange = "added" | "removed" | undefined;

/**
 * The `entity`, `evidence` and `claim` records, built in one place.
 *
 * `ix context <target> --format llm` and `ix context --diff <id> --format llm`
 * are the same command and emitted two different grammars for the same record
 * kind: the bundle renderer built `evidence 30 relationship <title>` from a
 * template literal, positional and unquoted, so a title with a space in it —
 * which is every title — split into tokens no consumer could reassemble. These
 * builders are the keyed form, and `llmQuote` handles the spaces and newlines.
 *
 * `change` is dropped when absent (`llmField` drops nullish), so the plain
 * bundle emits the same record without it.
 */
function entityRecord(change: RecordChange) {
  return (e: ContextBundle["entities"][number]): string =>
    llmLine("entity", {
      change,
      // Relationship records name their endpoints by entity id, so this is
      // what lets a reader resolve `src=`/`dst=` to something it has seen.
      // Shortened on both sides of that reference, so it still resolves.
      id: llmShortId(e.id),
      kind: e.kind,
      name: e.name,
      path: e.path,
      // Only when true: `stale=false` on every entity is noise, and `llmField`
      // renders a boolean rather than dropping it.
      stale: e.stale || undefined,
    });
}

function evidenceRecord(change: RecordChange) {
  return (e: EvidenceItem): string =>
    llmLine("evidence", {
      change,
      score: e.score,
      kind: e.kind,
      title: e.title,
      path: e.location?.path,
      lines: e.location ? lineRange(e.location) : undefined,
    });
}

function claimRecord(change: RecordChange) {
  return (c: ContextBundle["claims"][number]): string =>
    llmLine("claim", {
      change,
      id: llmShortId(c.id),
      entity: llmShortId(c.entityId),
      status: c.status,
      statement: c.statement,
    });
}

export function renderInvestigationDiff(
  saved: SavedInvestigation,
  fresh: ContextBundle,
  format: string,
  requestedBudgets?: Partial<BudgetSnapshot>,
): void {
  const prev = saved.bundle;
  const diff = diffInvestigations(saved, fresh, requestedBudgets);

  if (format === "json") {
    printJson(diff);
    return;
  }
  if (format === "llm") {
    // `ix context --diff --format llm` used to fall through to the prose
    // renderer below, because this path only branched on `json`. That made the
    // most common agent path the worst one: escaping the prose is what `llm`
    // exists for.
    //
    // Every line goes through `llmLine`, never a template literal. The values
    // here are the ones most likely to contain a space in the whole CLI — an
    // evidence title is a sentence, and a claim id carries the statement — and
    // `key=value` with an unquoted space is not a record a consumer can split.
    // `llmQuote` also encodes newlines, so a title cannot break the one
    // record per line invariant.
    printLlmLines([
      llmLine("diff", {
        investigation: saved.id,
        target: fresh.target.name,
        // How old the saved side is. `freshness_previous=current` says the
        // snapshot was fresh when it was taken, not when that was — and a
        // snapshot from five minutes ago and one from three months ago are the
        // same word. Both timestamps are on the JSON diff; only the prose
        // renderer showed them, so the llm stream was the one surface that
        // could not tell how stale the comparison's own baseline is.
        saved_at: diff.savedAt,
        generated_at: diff.generatedAt,
        freshness_previous: prev.freshness.classification,
        freshness_current: fresh.freshness.classification,
      }),
      // Which budgets governed the comparison. `scope=requested` appears
      // only when --max-* flags were passed, and carries `applied=` rather
      // than a sentence explaining itself: the precedence rule is that saved
      // budgets govern --diff, and a field an agent can test beats a note it
      // has to read. `effective` is read off the bundle that was built, so it
      // is a report and not a restatement of `saved`.
      llmLine("budgets", { scope: "saved", ...budgetFields(diff.budgets.saved) }),
      ...(diff.budgets.requested
        ? [llmLine("budgets", {
            scope: "requested",
            ...budgetFields(diff.budgets.requested),
            applied: diff.budgets.requestedApplied,
          })]
        : []),
      llmLine("budgets", { scope: "effective", ...budgetFields(diff.budgets.effective) }),
      // One record rather than eight, and the zeros are kept: "nothing was
      // added" is the answer to the question `--diff` was asked, so dropping
      // it as a default would remove the signal.
      llmLine("count", {
        added_entities: diff.added.entities.length,
        removed_entities: diff.removed.entities.length,
        added_relationships: diff.added.relationships.length,
        removed_relationships: diff.removed.relationships.length,
        added_evidence: diff.added.evidence.length,
        removed_evidence: diff.removed.evidence.length,
        added_claims: diff.added.claims.length,
        removed_claims: diff.removed.claims.length,
      }),
      // `change=` rather than a `+`/`-` prefix on the record kind: a consumer
      // routing on the kind should still match `entity` on both sides of the
      // comparison, and a fused marker means it matches neither.
      //
      // `id=` on entities is what makes the stream joinable. Relationship
      // records name their endpoints by entity id, so without it
      // `relationship src=entity-1 dst=entity-2` resolves to nothing a reader
      // has seen and an added entity cannot be matched to the edge that
      // involves it. `--format json` loses none of this, and llm carrying less
      // than the format it is meant to replace is the wrong trade.
      ...diff.added.entities.map(entityRecord("added")),
      ...diff.removed.entities.map(entityRecord("removed")),
      ...diff.added.relationships.map((r) => llmLine("relationship", { change: "added", src: llmShortId(r.src), pred: r.predicate, dst: llmShortId(r.dst) })),
      ...diff.removed.relationships.map((r) => llmLine("relationship", { change: "removed", src: llmShortId(r.src), pred: r.predicate, dst: llmShortId(r.dst) })),
      ...diff.added.evidence.map(evidenceRecord("added")),
      ...diff.removed.evidence.map(evidenceRecord("removed")),
      // `statement=` is the field that says what changed. The id is the
      // backend's (`c-8f31a2`), so `claim change=added id=c-8f31a2
      // status=active` told a reader that a claim changed and not what it
      // says. The test fixture hid it by fabricating `claim-<statement>` ids.
      ...diff.added.claims.map(claimRecord("added")),
      ...diff.removed.claims.map(claimRecord("removed")),
    ]);
    return;
  }

  renderSection(`Investigation diff: ${saved.id}`);
  console.log(`  freshness: ${prev.freshness.classification} -> ${fresh.freshness.classification}`);
  // Prose only: `--format llm` returned above with records of its own. The
  // llm branch here used to be this same block with the colons moved, which
  // is the one thing the format is defined not to be.
  console.log(`  budgets:`);
  console.log(`    saved     : ${formatBudgets(diff.budgets.saved)}`);
  if (diff.budgets.requested) {
    console.log(`    requested : ${formatBudgets(diff.budgets.requested, true)}`);
  } else {
    console.log(`    requested : (none)`);
  }
  console.log(`    effective : ${formatBudgets(diff.budgets.effective)}`);
  console.log(`  entities:  -${diff.removed.entities.length} +${diff.added.entities.length}`);
  console.log(`  relationships: -${diff.removed.relationships.length} +${diff.added.relationships.length}`);
  console.log(`  evidence:  -${diff.removed.evidence.length} +${diff.added.evidence.length}`);
  console.log(`  claims:    -${diff.removed.claims.length} +${diff.added.claims.length}`);
  if (diff.added.entities.length > 0) {
    renderSection("Added entities");
    for (const e of diff.added.entities) console.log(`  ${e.name} (${e.kind})`);
  }
  if (diff.removed.entities.length > 0) {
    renderSection("Removed entities");
    for (const e of diff.removed.entities) console.log(`  ${e.name} (${e.kind})`);
  }
  if (diff.added.evidence.length > 0) {
    renderSection("Added evidence");
    for (const e of diff.added.evidence) console.log(`  [${e.score}] ${e.kind} - ${e.title}`);
  }
  if (diff.removed.evidence.length > 0) {
    renderSection("Removed evidence");
    for (const e of diff.removed.evidence) console.log(`  [${e.score}] ${e.kind} - ${e.title}`);
  }
  console.log();
}

interface BuildInput {
  resolved: { id: string; name: string; kind: string; resolutionMode: string };
  facts: ContextFacts;
  context: StructuredContext;
  provenance: unknown;
  asOfRev?: number;
  depth?: string;
  budgets: BudgetSnapshot;
  /**
   * The output the evidence budget is charged against. Defaults to json, the
   * legacy sizing, so injected fixtures and old saved bundles keep their size.
   */
  format?: BundleFormat;
  /**
   * Per-entity staleness probe. Injected so buildBundle stays a pure function
   * under test; production passes nothing and gets the real baseline-backed one.
   */
  isStale?: (path: string) => boolean;
  /**
   * Whether the workspace has a completed source graph baseline. Injected for the same
   * reason as `isStale`: it is a filesystem question, and buildBundle stays
   * pure under test. Both production callers pass the real answer; the default
   * is the optimistic one so a bundle built from injected facts alone is not
   * silently reclassified.
   */
  graphCompleted?: boolean;
  /**
   * The graph-health verdict (graph-health.ts), workspace-wide. The target's
   * own structure is judged here from `facts`. Absent under test and when the
   * check could not run, which says nothing.
   */
  graphHealth?: GraphHealth;
  /** Set by `--from-issue`: the starting points and the ranked files. */
  issue?: IssueBundleInput;
}

/** What `--from-issue` records in the bundle. */
interface IssueSummary {
  startingPoints: StartingPoint[];
  unresolved: string[];
  /** Nothing in the issue resolved; the start is BM25's best file. */
  fallback: boolean;
}

export interface IssueBundleInput extends IssueSummary {
  rankedFiles: RankedFile[];
  /** The other starting points' related files, entered as entities. */
  extraEntities?: EntityLocation[];
}

/**
 * The facts a bundle is built from: one hop from `collectFacts`, then the
 * ranked files two hops out, which are seeded from those facts. The second
 * step is best-effort -- a bundle without it is the bundle `ix context` built
 * before it existed, and failing the command over it would be a regression.
 */
async function collectContextFacts(
  client: IxClient,
  resolved: { id: string; name: string; kind: string },
): Promise<ContextFacts> {
  const facts = await collectFacts(client, resolved.id, resolved.name, resolved.kind, "context");
  const graphRefs = await collectRelatedFiles(client, resolved, facts).catch(() => []);
  const textRefs = await collectTextRelated(client, facts, graphRefs).catch(() => []);
  const history = await collectHistory(client, facts, [...graphRefs, ...textRefs]).catch(() => undefined);
  // Added to the graph's files, not ranked against them. Put first and sharing
  // the eight slots, they displaced graph finds the benchmark needed
  // (`main.ts` for `mcp/runner.ts`) with mentions that led nowhere.
  const relatedRefs = [...graphRefs.slice(0, MAX_RELATED), ...textRefs, ...(history?.coChanged ?? [])];
  return {
    ...facts,
    ...(relatedRefs.length > 0 ? { relatedRefs } : {}),
    ...(history?.recent.length ? { recentCommits: history.recent } : {}),
  };
}

/**
 * The target file's recent commits, and the files that changed with it. From
 * the working tree's git, so absent outside a checkout. See `explain/history.ts`.
 */
async function collectHistory(
  client: IxClient,
  facts: ContextFacts,
  related: RelatedRef[],
): Promise<{ recent: CommitRef[]; coChanged: RelatedRef[] } | undefined> {
  if (!facts.path) return undefined;
  const git = gitRunner(resolveWorkspaceRoot());
  const known = new Set<string>([facts.path]);
  for (const ref of [
    ...(facts.importRefs ?? []), ...(facts.calleeRefs ?? []), ...(facts.topCallerRefs ?? []),
    ...(facts.topDependentRefs ?? []), ...(facts.neighbourRefs ?? []), ...related,
  ]) {
    if (ref.path) known.add(ref.path);
  }
  const [recent, coChanges] = await Promise.all([recentCommits(git, facts.path), coChangedFiles(git, facts.path, known)]);
  const coChanged = await Promise.all(coChanges.map(async (c) => {
    const name = c.path.split("/").pop()!;
    const id = await fileNodeId(client, c.path);
    const named = `changed with the target in ${c.commits} commits`;
    return { id, name, kind: "file", path: c.path, score: c.score, reason: named, via: [], named };
  }));
  return { recent, coChanged };
}

/**
 * A file's graph node id, for an entity the rest of the bundle can refer to.
 * Scoped: a backend holding two checkouts of one repository has two. Falls
 * back to a synthetic id rather than dropping a file the graph has not seen.
 */
async function fileNodeId(client: IxClient, path: string): Promise<string> {
  return (await findFileNode(client, path)) ?? `file:${path}`;
}

/**
 * Search candidates for one file node. `scope` narrows the search to the path
 * on a backend that applies it (Ix-memory >= 1.0.31); an older one ignores it
 * and returns every file sharing the basename, so the limit has to reach past
 * a monorepo's `index.ts`, `__init__.py` or `mod.rs` -- at 10 a file ranked
 * eleventh among its namesakes had no node, and `--from-issue` discarded a path
 * the issue named for a BM25 guess.
 */
const FILE_NODE_SEARCH_LIMIT = 200;

/** A file's graph node id, or undefined when the graph has no node for it. */
export async function findFileNode(client: IxClient, path: string): Promise<string | undefined> {
  const name = path.split("/").pop()!;
  const nodes = await client.search(name, {
    kind: "file", nameOnly: true, limit: FILE_NODE_SEARCH_LIMIT, scope: path, ...activeReadScope(),
  }).catch(() => []);
  return nodes.find((n) => relativePath(n.provenance?.sourceUri) === path)?.id;
}

/** Search candidates fetched per name the issue mentions; only exact names are kept. */
const ISSUE_SEARCH_LIMIT = 20;

/**
 * `ix context --from-issue`: a bundle built from an issue's text rather than a
 * named target. See `explain/issue.ts` for how starting points are chosen and
 * files ranked.
 *
 * The bundle is centred on the first starting point the graph has a node for,
 * built exactly as `ix context <that target>` would be. The other starting
 * points enter it as entities, with their own related files, and every
 * starting point's neighbourhood feeds the closeness that nudges the ranking.
 * Their facts are collected without text references or git history: those
 * are the expensive, centre-only parts of `collectContextFacts`.
 */
async function buildIssueBundle(
  arg: string,
  opts: ContextOptions,
  budgets: BudgetSnapshot,
  format: BundleFormat,
): Promise<ContextBundle | undefined> {
  const text = await readIssueOrReport(arg, opts.format);
  if (text === undefined) return undefined;
  const client = createClient({ query: true });
  const plan = await planIssueWith(client, text);
  // A path start has no node yet, and the graph may not have one either: it
  // does not index every tracked file. chooseCentre walks BM25 for one it does.
  const { starts, centre, walked } = await chooseCentre(
    plan.starts, plan.bm25, (path) => findFileNode(client, path));
  if (!centre) {
    issueFailure(
      "issue_unresolved",
      starts.length === 0
        ? `Nothing the issue names resolved to a definition${plan.unresolved.length > 0 ? ` (tried ${plan.unresolved.slice(0, 5).join(", ")})` : ""}, and no tracked source file matched its text. Name a symbol or file and run ix context <target>.`
        : `Neither the issue's starting points (${starts.map((s) => s.path).join(", ")}) nor the ${CENTRE_FALLBACK_TRIES} source files that best match its text are in the graph. Name a symbol or file and run ix context <target>, or run ix map if this workspace has not been mapped.`,
      opts.format,
    );
    return undefined;
  }
  const resolved = { id: centre.id!, name: centre.name, kind: centre.kind, resolutionMode: "issue" };
  const [facts, context, around, workspaceHealth] = await Promise.all([
    collectContextFacts(client, resolved),
    client.contextForNode(resolved.id, { asOfRev: opts.asOfRev, depth: opts.depth }),
    Promise.all(starts.filter((s) => s.id && s !== centre).map((s) => startNeighbourhood(client, s))),
    checkGraphHealth(client, activeReadScope()),
  ]);

  const near = new Map<string, Closeness>();
  const mark = (path: string | undefined, weight: number, reason: string) => {
    if (!path) return;
    const prior = near.get(path);
    if (!prior || weight > prior.weight) near.set(path, { weight, reason });
  };
  for (const n of [{ start: centre, facts, related: facts.relatedRefs ?? [] }, ...around]) {
    for (const ref of oneHopRefs(n.facts)) {
      if (ref.path !== n.start.path) mark(ref.path, 1, `one hop from ${n.start.name}`);
    }
    for (const ref of n.related) mark(ref.path, 0.5, `near ${n.start.name}`);
  }

  return buildBundle({
    resolved,
    facts,
    context,
    provenance: facts.provenance,
    asOfRev: opts.asOfRev,
    depth: opts.depth,
    budgets,
    format,
    graphCompleted: hasCompletedSourceGraphBaseline(),
    graphHealth: bundleGraphHealth(workspaceHealth, resolved, facts),
    issue: {
      startingPoints: starts,
      unresolved: plan.unresolved,
      fallback: plan.fallback || walked,
      rankedFiles: rankIssueFiles({ starts, bm25: plan.bm25, near }),
      extraEntities: around.flatMap((n) => n.related),
    },
  });
}

/** The issue's text, or undefined after reporting why it has none. */
async function readIssueOrReport(arg: string, format: string | undefined): Promise<string | undefined> {
  let text: string;
  try {
    text = await readIssueText(arg);
  } catch (error) {
    issueFailure(
      "issue_unreadable",
      `Cannot read the issue from ${arg === "-" ? "stdin" : `"${arg}"`}: ${(error as Error).message}`,
      format,
    );
    return undefined;
  }
  if (!text.trim()) {
    issueFailure("empty_issue", `The issue ${arg === "-" ? "on stdin" : `in "${arg}"`} is empty.`, format);
    return undefined;
  }
  return text;
}

/** The issue's starting points and lexical ranking, against this workspace's graph. */
async function planIssueWith(client: IxClient, text: string) {
  await ensureReadScope(client);
  const scope = activeReadScope();
  const root = resolveWorkspaceRoot();
  return planIssue(text, {
    repo: gitRepoAccess(root),
    // Through the on-disk term index (bm25-cache.ts): the same ranking, with
    // only the files that differ from HEAD read again.
    rank: cachedBm25Ranker(root),
    search: async (name) =>
      (await client.search(name, { limit: ISSUE_SEARCH_LIMIT, nameOnly: true, ...scope })).map(symbolHit),
  });
}

/**
 * `ix context --from-issue --lean`: the starting points Ix trusts and the
 * next few files, with no bundle around them. See `leanIssueView` for why.
 * Nothing here needs a centre node, so it is also the cheap path: one search
 * per name the issue mentions, and BM25 over the tracked files.
 */
async function emitLeanIssue(arg: string, opts: ContextOptions): Promise<void> {
  const text = await readIssueOrReport(arg, opts.format);
  if (text === undefined) return;
  const view = leanIssueView(await planIssueWith(createClient({ query: true }), text));
  if (opts.format === "json") {
    printJson({ kind: "issue_lean", ...view });
  } else if (opts.format === "llm") {
    printLlmLines(renderLeanIssueLlm(view));
  } else {
    console.log(renderLeanIssueText(view));
  }
}

function spanOf(s: StartingPoint): string {
  return s.lineStart !== undefined ? `${s.path}:${s.lineStart}-${s.lineEnd ?? s.lineStart}` : s.path;
}

/** Why a start was trusted, in the words an agent reads. */
function startWhy(s: StartingPoint): string {
  return s.via === "path in issue" ? "the issue names this file" : `the issue names \`${s.token}\``;
}

export function renderLeanIssueText(view: LeanIssueView): string {
  if (view.confidence === "low") {
    return `Ix found no confident starting point for this issue: ${view.reason}.`;
  }
  const lines = ["Where to start (Ix resolved these from the issue's own words):"];
  for (const s of view.startingPoints) {
    lines.push(`  ${spanOf(s)}  ${s.kind === "file" ? "" : `${s.name} (${s.kind}) — `}${startWhy(s)}`);
  }
  if (view.alsoRanked.length > 0) {
    lines.push(`Then, by the issue's text: ${view.alsoRanked.map((f) => f.path).join(", ")}`);
  }
  return lines.join("\n");
}

export function renderLeanIssueLlm(view: LeanIssueView): string[] {
  const out = [llmLine("issue", [
    ["confidence", view.confidence],
    ...(view.reason ? [["reason", view.reason] as [string, string]] : []),
  ])];
  for (const s of view.startingPoints) {
    out.push(llmLine("start", [
      ["path", s.path],
      ...(s.lineStart !== undefined ? [["lines", `${s.lineStart}-${s.lineEnd ?? s.lineStart}`] as [string, string]] : []),
      ["name", s.name], ["kind", s.kind], ["why", startWhy(s)],
    ]));
  }
  for (const f of view.alsoRanked) out.push(llmLine("ranked", [["path", f.path]]));
  return out;
}

/**
 * A `--from-issue` failure, readable by the format asked for. `reportFailure`
 * writes nothing to stdout under `--format json`, so a JSON caller got an empty
 * stdout and had to scrape stderr; this prints the record the other commands'
 * JSON failures use.
 */
function issueFailure(code: string, message: string, format: string | undefined): void {
  if (format === "json") {
    printJson({ error: code, message });
    process.exitCode = 1;
    return;
  }
  reportFailure(code, message, format);
}

/** A secondary starting point's one-hop facts and related files. Best-effort. */
async function startNeighbourhood(
  client: IxClient,
  start: StartingPoint,
): Promise<{ start: StartingPoint; facts?: ContextFacts; related: RelatedRef[] }> {
  try {
    const facts = await collectFacts(client, start.id!, start.name, start.kind, "context");
    const related = await collectRelatedFiles(client, { id: start.id!, kind: start.kind }, facts).catch(() => []);
    return { start, facts, related };
  } catch {
    return { start, related: [] };
  }
}

/** What a target reaches, and what reaches it, one step out. */
function oneHopRefs(facts: ContextFacts | undefined): EntityLocation[] {
  if (!facts) return [];
  return [
    ...(facts.importRefs ?? []), ...(facts.calleeRefs ?? []), ...(facts.topCallerRefs ?? []),
    ...(facts.topDependentRefs ?? []), ...(facts.neighbourRefs ?? []),
  ];
}

/** A search result as the starting-point picker reads it. */
function symbolHit(node: GraphNode): SymbolHit {
  const attrs = (node.attrs ?? {}) as Record<string, unknown>;
  const line = (v: unknown) => (typeof v === "number" && Number.isInteger(v) && v > 0 ? v : undefined);
  const lineStart = line(attrs.line_start);
  const lineEnd = line(attrs.line_end);
  return {
    id: node.id,
    name: node.name || (typeof attrs.name === "string" ? attrs.name : ""),
    kind: node.kind || "unknown",
    path: relativePath(node.provenance?.sourceUri),
    ...(lineStart !== undefined ? { lineStart } : {}),
    ...(lineEnd !== undefined ? { lineEnd } : {}),
  };
}

/** Imported files whose text is read for names, after the target's own. */
const TEXT_SOURCE_IMPORTS = 8;

/**
 * Files linked to the target by text rather than by any graph edge: a path in
 * a string (`"../../../../core-ingestion/dist/languages.js"`), a file named
 * in a comment, a test that reads a file by path. Read from the working tree,
 * so skipped outside a git checkout. See `collectTextReferences`.
 */
async function collectTextRelated(
  client: IxClient,
  facts: ContextFacts,
  graphRefs: RelatedRef[],
): Promise<RelatedRef[]> {
  if (!facts.path) return [];
  const repo = gitRepoAccess(resolveWorkspaceRoot());
  if (!repo) return [];
  const sources: TextSource[] = [
    { path: facts.path, role: "target" },
    ...(facts.importRefs ?? [])
      .filter((ref) => ref.kind === "file" && ref.path)
      .slice(0, TEXT_SOURCE_IMPORTS)
      .map((ref) => ({ path: ref.path!, role: "import" as const })),
  ];
  const known = new Set<string>();
  for (const ref of [
    ...(facts.importRefs ?? []), ...(facts.calleeRefs ?? []), ...(facts.topCallerRefs ?? []),
    ...(facts.topDependentRefs ?? []), ...(facts.neighbourRefs ?? []), ...graphRefs,
  ]) {
    if (ref.path) known.add(ref.path);
  }
  const found = collectTextReferences(repo, sources, known);
  return Promise.all(found.map(async (ref): Promise<RelatedRef> => ({
    id: await fileNodeId(client, ref.path), name: ref.path.split("/").pop()!, kind: "file", path: ref.path,
    score: ref.score, reason: ref.reason, via: [], named: ref.reason,
  })));
}

/**
 * The workspace verdict, made worse by the target's own structure when a
 * definition no file contains shows its edges are gone even though the
 * workspace as a whole looks fine (only some files re-ingested elsewhere).
 */
function bundleGraphHealth(
  workspace: GraphHealth,
  resolved: { name: string; kind: string },
  facts: { path?: string; container?: unknown },
): GraphHealth {
  return worseHealth(workspace, assessTargetStructure({
    name: resolved.name, kind: resolved.kind, path: facts.path, container: facts.container,
  }));
}

export function buildBundle(input: BuildInput): ContextBundle {
  const { resolved, facts, context, provenance, asOfRev, depth, budgets } = input;
  const format = input.format ?? "json";

  const stale = facts.stale;
  // Three states, not two. Without a completed source graph baseline the
  // backend may still answer from partially committed graph patches. It is not
  // `stale` either — nothing is known to have changed. The
  // freshness union has carried `unverified` for exactly this case since it was
  // written; this is the first thing to produce it.
  const graphCompleted = input.graphCompleted ?? true;
  // A hollowed graph outranks all three: "current" would vouch for a bundle
  // whose members and callers the graph has lost.
  const health = input.graphHealth;
  const degraded = isUnhealthy(health);
  const classification = degraded ? "degraded" : !graphCompleted ? "unverified" : stale ? "stale" : "current";
  const prov = provenanceSource(provenance);

  // Entities: the target itself plus every referenced node, deduped by id and
  // ordered deterministically (kind, name, id) before budgeting.
  // `stale` here is the TARGET's staleness, from the facts collector. It is
  // right for the bundle-level `freshness`, but every other entity has to be
  // asked about separately — stamping the target's answer onto all of them
  // reported an untouched dependency as stale whenever the target was, and a
  // genuinely stale one as current whenever the target was not. Staleness is
  // the field an agent reads to decide whether to trust the rest, so a wrong
  // one is worse than none.
  const seen = new Set<string>([resolved.id]);
  const entities: ContextBundle["entities"] = [
    {
      id: resolved.id,
      name: resolved.name,
      kind: resolved.kind,
      ...locationFields(targetLocation(facts) ?? {}),
      stale,
    },
  ];
  // The entities the facts collector located, most relevant first: the
  // top-ranked members, then the named callers and dependents. They go ahead of
  // the backend's context nodes, which are ordered by kind and name, so the
  // entity budget cuts what matters least. They also carry the paths and lines
  // that the backend's node summaries do not.
  //
  // Only the leading members jump the queue. A large file has more members than
  // the whole entity budget -- `ingest.ts` in the Ix repo has over a hundred --
  // and putting all of them first crowded out the files it imports and is
  // imported by, which are what cross-file questions need. The rest follow the
  // context nodes.
  const memberRefs = facts.memberRefs ?? [];
  const pushLocated = (refs: EntityLocation[]) => {
    for (const ref of refs) {
      if (seen.has(ref.id)) continue;
      seen.add(ref.id);
      entities.push({
        id: ref.id,
        name: ref.name,
        kind: ref.kind,
        // A package's provenance names the file that imports it, not the
        // package: `node:fs` came out located in `commands/watch.ts`.
        ...(ref.kind === "module" ? {} : locationFields(ref)),
        stale: false, // replaced below, for the entities that survive the budget
      });
    }
  };
  const issue = input.issue;
  pushLocated([
    // The issue's other starting points, right after the one the bundle is
    // centred on: they are as much the target as it is.
    ...(issue?.startingPoints ?? [])
      .filter((s) => s.id && s.id !== resolved.id)
      .map((s) => ({ id: s.id!, name: s.name, kind: s.kind, ...locationFields(s) })),
    ...memberRefs.slice(0, LEADING_MEMBERS),
    // What the target reaches, before what reaches it: an agent starting from
    // an entry point is looking for where to go next.
    ...(facts.importRefs ?? []),
    ...(facts.calleeRefs ?? []),
    // What those files define. Naming the file is half an answer to "which
    // function does X"; these are the other half.
    ...(facts.neighbourRefs ?? []),
    ...(facts.topCallerRefs ?? []),
    ...(facts.topDependentRefs ?? []),
    // Two steps out, ranked. After everything one step out, and ahead of the
    // backend's context nodes, which are ordered by kind and name only.
    ...(facts.relatedRefs ?? []),
    ...(issue?.extraEntities ?? []),
  ]);
  // Compact and standard backend responses omit the full graph arrays and
  // carry the same graph as summaries. Falling back here keeps the default
  // context mode from collapsing to a target-only bundle.
  const contextNodes = context.nodes.length > 0
    ? context.nodes.map((node) => ({
        id: node.id,
        name: node.name,
        kind: node.kind,
        path: node.provenance?.sourceUri,
      }))
    : (context.nodeSummaries ?? []).map((node) => ({
        id: node.id,
        name: node.name,
        kind: node.kind,
        path: node.path ?? node.sourceUri ?? undefined,
      }));
  // The facts collector's own record of an entity wins over the backend's
  // summary of it. Backends up to at least 1.0.30 summarize a file's members
  // with the FILE's name and no path, so a member that reached the bundle
  // through the summaries -- ahead of its located ref, which `seen` then
  // skipped -- came out as twelve entities all named `watch.ts`.
  const trailingMembers = memberRefs.slice(LEADING_MEMBERS);
  const locatedById = new Map(trailingMembers.map((ref) => [ref.id, ref]));
  const fileNames = new Set(
    [...contextNodes, resolved].filter((n) => n.kind === "file").map((n) => n.name));
  for (const node of orderedNodes(contextNodes)) {
    if (seen.has(node.id)) continue;
    const located = locatedById.get(node.id);
    if (located) {
      pushLocated([located]);
      continue;
    }
    // The same defect with no located ref to fall back on: a symbol with no
    // location, named after a file. Its name is wrong and it cannot be
    // opened, so it would only spend entity budget misleading the reader.
    if (!node.path && node.kind !== "file" && node.kind !== "module" && fileNames.has(node.name)) {
      continue;
    }
    seen.add(node.id);
    entities.push({
      id: node.id,
      name: node.name,
      kind: node.kind,
      ...(node.kind === "module" || !node.path ? {} : { path: node.path }),
      stale: false, // replaced below, for the entities that survive the budget
    });
  }
  pushLocated(trailingMembers);

  // Relationships: graph edges, ordered deterministically.
  const contextEdges = context.edges.length > 0 ? context.edges : (context.edgeSummaries ?? []);
  const relationships = [...contextEdges]
    .sort((a, b) => cmp(a.src, b.src) || cmp(a.dst, b.dst) || cmp(a.predicate, b.predicate))
    .map((edge) => ({ src: edge.src, dst: edge.dst, predicate: edge.predicate }));

  const evidence = rankEvidence({ resolved, facts, context, relationships, prov, entities, issue });

  const bundle: ContextBundle = {
    schema: BUNDLE_SCHEMA,
    generatedAt: new Date().toISOString(),
    target: {
      id: resolved.id,
      name: resolved.name,
      kind: resolved.kind,
      resolutionMode: resolved.resolutionMode,
      ...(facts.path ? { path: facts.path } : {}),
    },
    ...(issue
      ? {
          issue: { startingPoints: issue.startingPoints, unresolved: issue.unresolved, fallback: issue.fallback },
          rankedFiles: issue.rankedFiles,
        }
      : {}),
    entities: [],
    relationships: [],
    claims: [...context.claims]
      .sort(
        (a, b) =>
          cmp(a.claim.entityId, b.claim.entityId) ||
          cmp(a.claim.statement, b.claim.statement) ||
          cmp(a.claim.id, b.claim.id),
      )
      .map((scored) => ({
        id: scored.claim.id,
        entityId: scored.claim.entityId,
        statement: scored.claim.statement,
        status: scored.claim.status,
      })),
    decisions: [...context.decisions].sort((a, b) => cmp(a.title, b.title) || a.rev - b.rev || cmp(a.rationale, b.rationale)),
    conflicts: [...context.conflicts].sort((a, b) => cmp(a.claimA, b.claimA) || cmp(a.claimB, b.claimB) || cmp(a.id, b.id)),
    intents: [...context.intents].sort((a, b) => cmp(a.statement, b.statement) || cmp(a.id, b.id)),
    provenance: {
      sourceUri: asString(prov.sourceUri) ?? facts.path,
      sourceHash: asString(prov.sourceHash),
      extractor: asString(prov.extractor),
      sourceType: asString(prov.sourceType),
      observedAt: asString(prov.observedAt),
      introducedRev: facts.introducedRev,
      historyLength: facts.historyLength,
      stale,
    },
    freshness: { stale, classification },
    ...(degraded ? { graph: graphHealthJson(health) } : {}),
    evidence: [],
    budgets: { ...budgets, format },
    truncation: {
      entitiesTruncated: 0,
      relationshipsTruncated: 0,
      evidenceTruncated: 0,
      charactersTruncated: 0,
      conflictsTruncated: 0,
    },
    metadata: {
      asOfRev,
      depth,
      rankingRule: "deterministic-tier",
    },
  };

  // Apply budgets with explicit truncation metadata. Ordering is already
  // deterministic, so cutting from the tail is stable across runs.
  const entityLimit = Math.min(entities.length, budgets.maxEntities);
  // Probe staleness after budgeting, so the cost is bounded by maxEntities
  // rather than by however many nodes the context service returned. The target
  // keeps the answer the facts collector already produced for it.
  const probeStale = input.isStale ?? createStaleProbe();
  bundle.entities = entities.slice(0, entityLimit).map((entity) =>
    entity.id === resolved.id || !entity.path
      ? entity
      : { ...entity, stale: probeStale(entity.path) },
  );
  bundle.truncation.entitiesTruncated = entities.length - entityLimit;

  // Relationships are budgeted against the entities that SURVIVED, not against
  // the full list. The two budgets used to be applied independently, so an edge
  // could be kept while one or both of its endpoints were cut: measured on a
  // real target at `--max-entities 10`, 59 of 74 relationships referenced an
  // entity no longer in the bundle, 13 of them at both ends -- and
  // `relationshipsTruncated` reported 0, because nothing had exceeded the
  // relationship budget. The renderer prints those as bare UUIDs, so the damage
  // was invisible.
  //
  // The backend already guarantees this on its side (`trimSlice` keeps an edge
  // only when both endpoints survive); this stops the CLI from undoing it.
  // Dropping the dangling edge rather than pulling its endpoint back in keeps
  // `--max-entities` meaning exactly what it says.
  const keptEntityIds = new Set(bundle.entities.map((e) => e.id));
  const connected = relationships.filter(
    (r) => keptEntityIds.has(r.src) && keptEntityIds.has(r.dst),
  );
  const relLimit = Math.min(connected.length, budgets.maxRelationships);
  bundle.relationships = connected.slice(0, relLimit);
  // Count everything the caller does not get back, whichever budget cost it --
  // the entity cut and the relationship cut both drop relationships, and
  // reporting only the second is what made an 80%-dangling bundle look clean.
  bundle.truncation.relationshipsTruncated = relationships.length - relLimit;

  // Evidence is ordered by relevance, so keep the highest-priority prefix and
  // drop the tail when either the count or the character budget is exceeded.
  // Each item is sized by the text its renderer prints (the llm `evidence`
  // line, the two prose lines, or the item's JSON), so `--max-tokens` is
  // charged for what is emitted rather than for a serialization nobody sees.
  // For llm the header, diagnostics and `next` lines are charged too; for json
  // the budget bounds the evidence list only (entities and relationships have
  // their own count budgets).
  const sizeOf = (item: EvidenceItem): number =>
    format === "llm" ? evidenceRecord(undefined)(item).length + 1
      : format === "text" ? textEvidenceLines(item).reduce((sum, line) => sum + line.length + 1, 0)
        : JSON.stringify(item).length;
  const sizedEvidence = evidence.map((item) => ({ item, size: sizeOf(item) }));
  // keptSize[n] = summed size of the first n items, so a cut at any count knows
  // its `charactersTruncated` (full minus kept, in the sizing unit of the
  // format) without a rescan.
  const keptSize = [0];
  for (const entry of sizedEvidence) keptSize.push(keptSize[keptSize.length - 1]! + entry.size);
  const fullChars = keptSize[sizedEvidence.length]!;
  // Every counter the llm header prints is set here, including
  // `truncated_chars`, so each measurement below sees the digits that will
  // actually be emitted for that cut.
  const applyCut = (count: number): void => {
    bundle.evidence = evidence.slice(0, count);
    bundle.truncation.evidenceTruncated = evidence.length - count;
    bundle.truncation.charactersTruncated = fullChars - keptSize[count]!;
    const cut = summariseCut(evidence.slice(count));
    if (cut.length > 0) bundle.truncation.cut = cut;
    else delete bundle.truncation.cut;
  };
  // The llm output at the current cut, with the `next` rows looked up rather
  // than recomputed: this is measured once per fitting step.
  const nextAt = format === "llm" ? llmNextByCut(bundle, evidence) : undefined;
  const llmSize = (): number => bundleLlmLines(bundle, nextAt!(bundle.evidence.length)).join("\n").length;
  let overhead = 0;
  if (format === "llm") {
    applyCut(0);
    overhead = llmSize();
  } else if (format === "text") {
    overhead = TEXT_HEADER_ESTIMATE;
  }
  const evidenceBudget = budgets.maxChars - overhead;
  let chars = 0;
  let kept = 0;
  for (const entry of sizedEvidence) {
    // The first row is the target and always survives, however small the budget.
    if (kept >= budgets.maxEvidence || (kept > 0 && chars + entry.size > evidenceBudget)) break;
    chars += entry.size;
    kept += 1;
  }
  applyCut(kept);
  if (format === "llm") {
    // The header digits, the bundle_truncated diagnostic and the `next` lines
    // all depend on the cut, so settle it by measuring the real output.
    while (kept > 1 && llmSize() > budgets.maxChars) {
      kept -= 1;
      applyCut(kept);
    }
    // The overhead was measured with a truncation diagnostic reserved, which a
    // bundle that fits whole does not carry. Grow back while the real output
    // still fits.
    const limit = Math.min(sizedEvidence.length, budgets.maxEvidence);
    // A complete bundle drops the truncation diagnostic, so it can fit where
    // the nearly-complete ones do not: try the whole list before growing.
    if (kept < limit) {
      applyCut(limit);
      if (llmSize() <= budgets.maxChars) {
        kept = limit;
      } else {
        applyCut(kept);
      }
    }
    while (kept < limit) {
      applyCut(kept + 1);
      if (llmSize() > budgets.maxChars) {
        applyCut(kept);
        break;
      }
      kept += 1;
    }
  }

  // `conflicts[]` was the one list with no budget at all, and it is the one the
  // backend can hand back by the dozen: it reached 12,922 of 23,030 JSON bytes
  // on a recorded bundle. The evidence budgets never bounded it because they
  // bound `evidence`. Cap it at a fixed depth -- a caller who wants the full
  // set has `ix conflicts`, which is the command that renders them properly.
  const conflictLimit = Math.min(bundle.conflicts.length, MAX_CONFLICTS);
  bundle.truncation.conflictsTruncated = bundle.conflicts.length - conflictLimit;
  bundle.conflicts = bundle.conflicts.slice(0, conflictLimit);

  return bundle;
}

/**
 * Evidence tiers. A row's score is `tier * TIER_WIDTH + its place in the tier`,
 * so no tier can run into the next: structural rows were `10 + index`, and from
 * the eleventh on they interleaved with claims (20) and relationships (30+).
 */
const TIER = { target: 0, issue: 1, structural: 2, claims: 3, relationships: 4, provenance: 5 } as const;
const TIER_WIDTH = 1000;
const tierScore = (tier: number, index = 0): number => tier * TIER_WIDTH + Math.min(index, TIER_WIDTH - 1);

/** Deterministic evidence ranking: tier, then a stable id tiebreaker. */
function rankEvidence(input: {
  resolved: { id: string; name: string; kind: string };
  facts: ContextFacts;
  context: StructuredContext;
  relationships: Array<{ src: string; dst: string; predicate: string }>;
  prov: Record<string, unknown>;
  entities: ContextBundle["entities"];
  issue?: IssueBundleInput;
}): EvidenceItem[] {
  const items: EvidenceItem[] = [];

  const target = input.resolved;
  items.push({
    id: `target:${target.id}`,
    kind: "target",
    source: "resolution",
    title: `${target.name} (${target.kind})`,
    score: 0,
    reason: "resolved target — the bundle is centered on this entity",
    refs: [target.id],
    ...locationField(targetLocation(input.facts)),
  });
  // Straight after the target, ahead of everything structural: a file target
  // with many members fills the default budget before score 10 runs out, and
  // these two rows are what `--from-issue` exists to deliver.
  if (input.issue) items.push(...issueEvidence(input.issue));

  // Each entity gets one row. The rows below are pushed in rank order, and a
  // row about something already shown is dropped (or, for a row that lists
  // several, loses that entry): the same file as an import and a dependent, or
  // a member restated by its CONTAINS edge, cost the budget twice for one fact.
  // The target is exempt -- every edge in the bundle touches it.
  const shown = new Set<string>([target.id]);
  for (const s of input.issue?.startingPoints ?? []) if (s.id) shown.add(s.id);
  const fresh = (id: string | undefined): boolean => id === undefined || !shown.has(id);
  const show = (ids: string[]) => { for (const id of ids) shown.add(id); };

  type Structural = Omit<EvidenceItem, "kind" | "score">;
  const structural: Structural[] = [];
  const pushOne = (item: Structural, ref: EntityLocation | undefined) => {
    if (!fresh(ref?.id)) return;
    if (ref) show([ref.id]);
    structural.push(item);
  };
  // Keyed by entity id, not name: two members called `render` were one id.
  const rowId = (prefix: string, name: string, ref: EntityLocation | undefined) => `${prefix}:${ref?.id ?? name}`;
  if (input.facts.container) {
    const container = input.facts.container;
    pushOne({
      id: rowId("container", container.name, container),
      source: "facts.container",
      title: `container ${container.name} (${container.kind})`,
      reason: "contains the target",
      refs: [container.id],
      ...locationField(container),
    }, container);
  }
  // Names alone when the facts carry no locations, so a caller that builds its
  // own facts (or an older collector) still gets the structural evidence.
  const related = (
    names: string[],
    refs: EntityLocation[] | undefined,
    limit: number,
  ): Array<{ name: string; ref?: EntityLocation }> =>
    (refs ? refs.map((ref) => ({ name: ref.name, ref })) : names.map((name) => ({ name }))).slice(0, limit);

  const leadingMembers = related(input.facts.members, input.facts.memberRefs, LEADING_MEMBERS);
  const pushMembers = (members: typeof leadingMembers) => {
    for (const { name, ref } of members) {
      pushOne({
        id: rowId("member", name, ref), source: "facts.members", title: `member ${name}`,
        reason: ref ? memberReason(ref) : "defined in the target", refs: ref ? [ref.id] : [], ...locationField(ref),
      }, ref);
    }
  };
  // The most-used members first, the rest last. A file target's evidence at
  // the default budget was the target and its first ten members and nothing
  // else -- the part of a bundle an agent sees anyway the moment it opens the
  // target. Measured on ix-bench, 0.55 of the expected files were in the
  // bundle and 0.32 in the text an agent is shown.
  pushMembers(leadingMembers.slice(0, MEMBERS_BEFORE_OUTWARD));
  // Two steps out: a neighbour's import, or a file that depends on what the
  // target depends on. Before the imports, which the target's own header
  // lists; these are the files a one-hop bundle cannot name at all.
  //
  // One row for all of them. As a row each, five related files cost as much
  // of the evidence budget as five imports, and at the default budget the
  // imports then fell off the end instead: the files moved, the count the
  // agent could see did not.
  const relatedRefs = (input.facts.relatedRefs ?? []).filter((ref) => fresh(ref.id));
  if (relatedRefs.length > 0) {
    show(relatedRefs.map((ref) => ref.id));
    structural.push({
      id: "related-files", source: "facts.related",
      title: `related files: ${relatedRefs.map((ref) => ref.path ?? ref.name).join(", ")}`,
      reason: `two steps from the target, ranked; ${relatedRefs.map(relatedClause).join("; ")}`,
      refs: relatedRefs.map((ref) => ref.id),
    });
  }
  // What uses the target: callers, then the dependents not already among them,
  // as one row whose title carries the total. Ahead of the imports and the
  // neighbours: as a row each, after them, they missed the default budget on
  // nearly every file target -- and they are what an edit has to keep working.
  const usedBy = usedByRow(input.facts, fresh);
  if (usedBy) {
    show(usedBy.refs);
    structural.push(usedBy);
  }
  // What happened to the target's file lately. The subjects carry what a
  // one-hop bundle cannot: that the sibling commands were already fixed for
  // the same condition, or that the same bug was fixed next door.
  const commits = input.facts.recentCommits ?? [];
  if (commits.length > 0) {
    const file = (input.facts.path ?? "").split("/").pop();
    structural.push({
      id: "recent-commits", source: "git.history",
      title: `recent commits to ${file}: ${commits.map((c) => `${c.sha} ${c.subject}`).join("; ")}`,
      reason: `newest first (${commits.map((c) => c.date).join(", ")}); \`git show <sha>\` for the change`,
      refs: [],
    });
  }
  // Then outward. The file an answer lives in is most often one the target
  // imports: measured on the benchmark task set, 6 of 19 tasks' answers are a
  // direct import of their entry point, and none were in the bundle. These go
  // after the target's own members, not before: the evidence budget is 25
  // items, and a file with many imports (resolve.ts) pushed all 27 of its own
  // members out of the bundle entirely.
  for (const ref of (input.facts.importRefs ?? []).slice(0, SHOWN_IMPORTS)) {
    pushOne({
      id: rowId("imports", ref.name, ref), source: "facts.imports", title: `imports ${ref.name}`,
      reason: "the target imports this", refs: [ref.id], ...locationField(ref),
    }, ref);
  }
  for (const ref of input.facts.calleeRefs ?? []) {
    pushOne({
      id: rowId("calls", ref.name, ref), source: "facts.callees", title: `calls ${ref.name}`,
      reason: "the target calls this", refs: [ref.id], ...locationField(ref),
    }, ref);
  }
  for (const ref of (input.facts.neighbourRefs ?? []).slice(0, SHOWN_NEIGHBOUR_MEMBERS)) {
    const where = ref.path ? ref.path.split("/").pop() : undefined;
    pushOne({
      id: rowId("defines", ref.name, ref), source: "facts.neighbours",
      title: `${where ?? "a neighbouring file"} defines ${ref.name}`,
      reason: "defined in a file next to the target", refs: [ref.id], ...locationField(ref),
    }, ref);
  }
  pushMembers(leadingMembers.slice(MEMBERS_BEFORE_OUTWARD));
  structural.forEach((item, index) => {
    // Recent commits are provenance -- where the file's current shape came
    // from -- and keep to the stable kinds consumers already route on.
    items.push({
      ...item,
      kind: item.source === "git.history" ? "provenance" : "structural",
      score: tierScore(TIER.structural, index),
    });
  });

  // Claims, decisions and intents share a tier, in that order; within each,
  // the id tiebreaker below orders them.
  for (const scored of input.context.claims) {
    items.push({
      id: `claim:${scored.claim.id}`,
      kind: "claim",
      source: "context.claims",
      title: scored.claim.statement,
      score: tierScore(TIER.claims, 0),
      reason: `context claim (relevance ${scored.relevance}, confidence ${scored.confidence?.score ?? "n/a"})`,
      refs: [scored.claim.entityId],
    });
  }
  for (const decision of input.context.decisions) {
    items.push({
      id: `decision:${decision.title}`,
      kind: "decision",
      source: "context.decisions",
      title: decision.title,
      score: tierScore(TIER.claims, 1),
      reason: decision.rationale,
      refs: decision.entityId ? [decision.entityId] : [],
    });
  }
  // Conflicts are deliberately NOT evidence. A report names its two claims by
  // uuid, which is nothing an agent can act on, and ranked between decisions
  // and intents they outranked every relationship: on recorded bundles they
  // were taking 12 to 17 of the 25 slots and truncating away the members and
  // imports that answer the question. The count is carried in the bundle
  // header and the reports themselves stay in `conflicts[]` for a caller that
  // wants them; `ix conflicts` renders them.
  for (const intent of input.context.intents) {
    items.push({
      id: `intent:${intent.id}`,
      kind: "intent",
      source: "context.intents",
      title: intent.statement,
      score: tierScore(TIER.claims, 2),
      reason: `intent status ${intent.status}`,
      refs: [],
    });
  }

  // A relationship row is kept only when it names something no earlier row
  // does: `config.ts --CONTAINS--> getEndpoint` under a `member getEndpoint`
  // row restates it, and so does an edge to an entity an earlier edge named.
  const label = entityLabeller(input.entities);
  let relationshipIndex = 0;
  for (const edge of input.relationships.slice(0, 50)) {
    const ends = [...new Set([edge.src, edge.dst])].filter((id) => id !== target.id);
    if (ends.length === 0 || !ends.every((id) => fresh(id))) continue;
    show(ends);
    items.push({
      id: `relationship:${edge.src}:${edge.dst}:${edge.predicate}`,
      kind: "relationship",
      source: "context.edges",
      title: `${label(edge.src)} --${edge.predicate}--> ${label(edge.dst)}`,
      score: tierScore(TIER.relationships, relationshipIndex++),
      reason: "graph relationship from the context service",
      refs: [edge.src, edge.dst],
    });
  }

  items.push({
    id: `provenance:${target.id}`,
    kind: "provenance",
    source: "provenance + facts.history",
    title: `history length ${input.facts.historyLength}, introduced rev ${input.facts.introducedRev ?? "unknown"}`,
    score: tierScore(TIER.provenance),
    reason: `provenance ${input.prov.sourceType ?? "unknown"}, extractor ${input.prov.extractor ?? "unknown"}`,
    refs: [target.id],
  });

  // Stable full ordering: score, then id.
  return items.sort((a, b) => a.score - b.score || cmp(a.id, b.id));
}

/** Named callers and dependents shown in the "used by" row, at most. */
const SHOWN_USED_BY = 6;

/**
 * The one "used by" row: the target's callers, then its dependents that are not
 * already among them, each list ranked by the facts collector. The title says
 * how many of how many; `count` carries the same two numbers for a caller that
 * wants them without parsing.
 */
function usedByRow(
  facts: ContextFacts, fresh: (id: string | undefined) => boolean,
): Omit<EvidenceItem, "kind" | "score"> | undefined {
  const named = (names: string[], refs: EntityLocation[] | undefined) =>
    refs ?? names.map((name) => ({ id: "", name, kind: "unknown" }) as EntityLocation);
  const callers = named(facts.topCallers, facts.topCallerRefs);
  const dependents = named(facts.topDependents, facts.topDependentRefs);
  const picked: EntityLocation[] = [];
  const ids = new Set<string>();
  const names = new Set<string>();
  for (const ref of [...callers, ...dependents]) {
    if (picked.length >= SHOWN_USED_BY) break;
    // A name-only entry (no ref) is matched by name; a located one by id.
    if (ref.id ? ids.has(ref.id) || !fresh(ref.id) : names.has(ref.name)) continue;
    if (ref.id) ids.add(ref.id);
    names.add(ref.name);
    picked.push(ref);
  }
  if (picked.length === 0) return undefined;
  const total = Math.max(
    facts.usedByCount ?? Math.max(facts.callerCount, facts.dependentCount),
    picked.length,
  );
  const short = (ref: EntityLocation) => {
    const file = ref.path?.split("/").pop();
    return file && file !== ref.name ? `${ref.name} (${file})` : ref.name;
  };
  // Locations only: the title already names each entry and its file, and the
  // row is sized against the evidence budget like any other.
  const where = picked.filter((ref) => ref.path).map((ref) => formatLocation(locationFields(ref) as EvidenceLocation));
  const anyCaller = picked.some((ref) => callers.includes(ref));
  return {
    id: "used-by",
    // `facts.callers` when the row holds a caller, so a budget that cuts it
    // names `ix callers` as the way back; `ix impact` for dependents alone.
    source: anyCaller ? "facts.callers" : "facts.dependents",
    title: `used by (${picked.length} of ${total}): ${picked.map(short).join(", ")}`,
    reason: `calls, imports or references the target, most relevant first${where.length > 0 ? `; ${where.join(", ")}` : ""}`,
    refs: picked.flatMap((ref) => (ref.id ? [ref.id] : [])),
    count: { shown: picked.length, total },
    ...locationField(picked.find((ref) => ref.path)),
  };
}

/** Ranked files named in the evidence row; the JSON bundle carries the rest. */
const SHOWN_RANKED_FILES = 10;

/**
 * The `--from-issue` rows: where the bundle starts and why, then the files to
 * read, ranked against the issue's text.
 */
function issueEvidence(issue: IssueBundleInput): EvidenceItem[] {
  const items: EvidenceItem[] = [];
  const starts = issue.startingPoints;
  if (starts.length > 0) {
    const unresolved = issue.unresolved.length > 0
      ? `; unresolved: ${issue.unresolved.slice(0, 8).join(", ")}${issue.unresolved.length > 8 ? ", ..." : ""}`
      : "";
    const why = starts.map((s) => `${s.token}: ${s.via}`).join("; ");
    items.push({
      id: "issue-starts",
      kind: "target",
      source: "issue.starts",
      title: `starting points: ${starts.map((s) => `${s.name} (${formatLocation(locationFields(s) as EvidenceLocation)})`).join(", ")}`,
      score: tierScore(TIER.issue, 0),
      reason: (issue.fallback
        ? "no code name in the issue resolved to a definition; starting from the file BM25 ranks first against the issue text; "
        : "") + why + unresolved,
      refs: starts.flatMap((s) => (s.id ? [s.id] : [])),
      ...locationField(starts[0]),
    });
  }
  const shown = issue.rankedFiles.slice(0, SHOWN_RANKED_FILES);
  if (shown.length > 0) {
    items.push({
      id: "issue-ranked-files",
      kind: "structural",
      source: "issue.ranking",
      title: `ranked files: ${shown.map((f) => f.path).join(", ")}`,
      score: tierScore(TIER.issue, 1),
      reason: `starting points first, then bm25 against the issue text, graph neighbours of a starting point boosted up to ${Math.round(CLOSENESS_BOOST * 100)}%; `
        + shown.map((f) => `${f.path.split("/").pop()} (${f.reason})`).join("; "),
      refs: [],
    });
  }
  return items;
}

/**
 * The `next` lines `--format llm` closes with, for the bundle's evidence as it
 * stands. Draws only on the first few rows with a readable range; see
 * {@link llmNextByCut}.
 */
export function llmNextLines(bundle: ContextBundle): string[] {
  return forMcp()
    ? nextToolCalls(bundle, onDiskSymbolCheck())
      .map((step) => llmLine("next", { cmd: step.cmd, why: step.why, stale: step.stale, reanchor: step.reanchor }))
    : renderedNextReads(bundle).map((row) => llmLine("next", { cmd: row.cmd, stale: row.stale || undefined }));
}

/**
 * Indexes of the first `limit` evidence rows with a distinct readable range
 * (path, start and end line), in evidence order. These are the only rows
 * {@link nextReads} and {@link nextToolCalls} read, so the `next` lines can
 * only change at a cut that drops one of them.
 */
function readableRowIndexes(evidence: EvidenceItem[], limit: number): number[] {
  const seen = new Set<string>();
  const out: number[] = [];
  for (let i = 0; i < evidence.length && out.length < limit; i++) {
    const loc = evidence[i]!.location;
    if (!loc?.path || loc.lineStart === undefined || loc.lineEnd === undefined) continue;
    const range = `${loc.path}:${loc.lineStart}-${loc.lineEnd}`;
    if (seen.has(range)) continue;
    seen.add(range);
    out.push(i);
  }
  return out;
}

/**
 * The `next` lines for every cut of `evidence`, computed once per bundle.
 *
 * The budget-fitting loop in `buildBundle` measures the llm output at many cut
 * counts. Recomputing the `next` rows at each would repeat whatever they cost
 * (a stale-row check that reads files, say) once per iteration. They only
 * change at the cuts that drop one of the first three readable rows, so they
 * are computed for those few prefixes, up front, and looked up by count after.
 */
export function llmNextByCut(bundle: ContextBundle, evidence: EvidenceItem[]): (count: number) => string[] {
  // Each breakpoint is a prefix length at which the next lines can change.
  const breaks = [0, ...readableRowIndexes(evidence, 3).map((i) => i + 1)];
  const table = breaks.map((at) => llmNextLines({ ...bundle, evidence: evidence.slice(0, at) }));
  return (count) => {
    let k = 0;
    while (k + 1 < breaks.length && breaks[k + 1]! <= count) k += 1;
    return table[k]!;
  };
}

/**
 * The lines `--format llm` prints, in order. Pure, so `buildBundle` can measure
 * exactly what a budget will be charged for. `next` is the closing lines when
 * the caller already has them (`buildBundle` takes them from
 * {@link llmNextByCut}); otherwise they are computed from the bundle.
 */
export function bundleLlmLines(bundle: ContextBundle, next: string[] = llmNextLines(bundle)): string[] {
  // Every line through `llmLine`, none through a template literal: see the
  // history of this block. Absent sections are null and filtered out.
  const lines: Array<string | null> = [
      llmLine("context", {
        target: bundle.target.name,
        target_kind: bundle.target.kind,
        target_path: bundle.target.path,
        // Not on a degraded graph: `stale=false` there reads as a clean bill
        // of health for a bundle the graph has hollowed out.
        graph: bundle.graph ? String(bundle.graph.status) : undefined,
        stale: bundle.graph ? undefined : bundle.freshness.stale,
        classification: bundle.freshness.classification,
        entities: bundle.entities.length,
        relationships: bundle.relationships.length,
        claims: bundle.claims.length,
        decisions: bundle.decisions.length,
        conflicts: bundle.conflicts.length + bundle.truncation.conflictsTruncated,
        intents: bundle.intents.length,
        evidence: bundle.evidence.length,
        truncated_entities: bundle.truncation.entitiesTruncated,
        truncated_relationships: bundle.truncation.relationshipsTruncated,
        truncated_evidence: bundle.truncation.evidenceTruncated,
        truncated_chars: bundle.truncation.charactersTruncated,
      }),
      // First after the header: everything below is drawn from this graph.
      bundle.graph ? llmLine("graph", {
        status: asString(bundle.graph.status),
        reason: asString(bundle.graph.reason),
        message: asString(bundle.graph.message),
        fix: asString(bundle.graph.fix),
      }) : null,
      // What the budget dropped, and the cheapest command that gets it back.
      // The header's `truncated_*` counters say how much went; without this the
      // caller's only move is a bigger budget for the same query, which is the
      // most expensive one available.
      truncationAdvice(bundle)
        ? llmLine("diagnostic", { code: "bundle_truncated", message: truncationAdvice(bundle) })
        : null,
      bundle.issue?.fallback
        ? llmLine("diagnostic", { code: "issue_fallback", message: ISSUE_FALLBACK_NOTE })
        : null,
      // Evidence only, as before. The entity, relationship and claim lists are
      // deliberately still counts here: `--format llm` is the token-minimal
      // surface, the ranked evidence is what it exists to deliver, and
      // `--format json` carries the rest for a caller that wants it.
      ...bundle.evidence.map(evidenceRecord(undefined)),
      // Last, so it reads as the closing instruction it is.
      ...next,
  ];
  return lines.filter((line): line is string => line !== null);
}

/** The two prose lines `--format text` prints for one evidence item. */
export function textEvidenceLines(item: EvidenceItem): string[] {
  const where = item.location ? `${formatLocation(item.location)} — ` : "";
  return [`  [${item.score}] ${item.kind} — ${item.title}`, `         ${where}${item.reason}`];
}

/** Rough size of the prose header, charged before the evidence in `--format text`. */
const TEXT_HEADER_ESTIMATE = 600;

export function renderBundle(bundle: ContextBundle, format: string): void {
  if (format === "json") {
    printJson(bundle);
    return;
  }
  if (format === "llm") {
    // Every line through `llmLine`, none through a template literal. This block
    // built `target=${name}` and `evidence 30 relationship <title>` by
    // interpolation: the first breaks on any name containing a space or an `=`,
    // and the second is positional, unquoted, and breaks on every title, which
    // is a sentence. `ix context --diff --format llm` emits the keyed form for
    // the same record kinds, so a consumer routing on `evidence` from the same
    // command was handed two grammars.
    printLlmLines(bundleLlmLines(bundle));
    return;
  }

  renderSection(`Context: ${bundle.target.name}`);
  console.log(`  kind:          ${bundle.target.kind}`);
  if (bundle.target.path) console.log(`  path:          ${bundle.target.path}`);
  console.log(`  classification:${bundle.freshness.classification}`);
  console.log(`  entities:      ${bundle.entities.length}`);
  console.log(`  relationships: ${bundle.relationships.length}`);
  console.log(`  claims:        ${bundle.claims.length}`);
  console.log(`  decisions:     ${bundle.decisions.length}`);
  // Named, not listed: see rankEvidence. The hint is what makes the count
  // actionable, since the reports are no longer in the evidence list.
  const conflictCount = bundle.conflicts.length + bundle.truncation.conflictsTruncated;
  console.log(
    `  conflicts:     ${conflictCount}${conflictCount > 0 ? " (run ix conflicts to inspect)" : ""}`,
  );
  console.log(`  intents:       ${bundle.intents.length}`);
  if (bundle.issue) {
    console.log(
      `  from issue:    ${bundle.issue.startingPoints.length} starting point(s), ${bundle.rankedFiles?.length ?? 0} ranked files`,
    );
    if (bundle.issue.fallback) renderNote(ISSUE_FALLBACK_NOTE);
  }
  if (bundle.graph) {
    const g = bundle.graph;
    renderWarning(
      `Graph is ${String(g.status)}. ${g.message ? String(g.message) : ""}${g.fix ? ` Fix: ${String(g.fix)}` : ""}`.trim(),
    );
  }
  if (bundle.freshness.stale) {
    renderWarning("Source has changed since last ingest. Run ix map to update.");
  }

  if (bundle.evidence.length > 0) {
    renderSection("Evidence (highest relevance first)");
    for (const item of bundle.evidence) {
      for (const line of textEvidenceLines(item)) console.log(line);
    }
  }

  const reads = renderedNextReads(bundle);
  if (reads.length > 0) {
    renderSection("Next");
    for (const row of reads) {
      console.log(`  ${row.cmd}${row.stale ? "  (stale: changed since last ingest; ix map to update)" : ""}`);
    }
  }

  const trunc = bundle.truncation;
  if (trunc.entitiesTruncated + trunc.relationshipsTruncated + trunc.evidenceTruncated > 0) {
    const advice = truncationAdvice(bundle);
    renderNote(
      `Truncated: ${trunc.entitiesTruncated} entities, ${trunc.relationshipsTruncated} relationships, ${trunc.evidenceTruncated} evidence items.`
      + (advice ? ` ${advice}` : " Raise --max-tokens for more."),
    );
  }
  console.log();
}

/**
 * Evidence sources, as the word a hint can put a number in front of.
 *
 * Keyed on `source` rather than `kind`: `kind` is `structural` for members,
 * imports, calls, callers and dependents alike, and "cut: 48 structural" is the
 * uninformative sentence this exists to replace.
 */
/** Said wherever a bundle's start came from BM25 rather than from the issue's names. */
const ISSUE_FALLBACK_NOTE =
  "Nothing the issue names resolved to a definition; the bundle starts from the file whose text matches the issue best (BM25).";

const CUT_LABELS: Record<string, string> = {
  "issue.starts": "starting points row",
  "issue.ranking": "ranked files row",
  "facts.container": "container",
  "facts.members": "member",
  "facts.imports": "import",
  "facts.callees": "call",
  "facts.neighbours": "neighbouring definition",
  "facts.related": "related file",
  "git.history": "recent commits",
  "facts.callers": "caller",
  "facts.dependents": "dependent",
  "context.claims": "claim",
  "context.decisions": "decision",
  "context.conflicts": "conflict",
  "context.intents": "intent",
  "context.edges": "relationship",
};

/** Group the evidence a budget dropped by category, largest first. */
function summariseCut(dropped: EvidenceItem[]): Array<{ what: string; count: number }> {
  const counts = new Map<string, number>();
  for (const item of dropped) {
    const what = CUT_LABELS[item.source] ?? item.kind;
    counts.set(what, (counts.get(what) ?? 0) + 1);
  }
  return [...counts.entries()]
    .map(([what, count]) => ({ what, count }))
    .sort((a, b) => b.count - a.count || a.what.localeCompare(b.what));
}

/**
 * The cheapest command that gets back what the budget dropped.
 *
 * Target-specific because the answer is: a file that lost its own members wants
 * one of those members as a target, not a bigger budget for the file; a symbol
 * that lost callers wants `ix callers`, which is bounded and ranked and costs a
 * fraction of a bundle. `--max-tokens` is named last, as the lever that works
 * for anything and pays for everything.
 */
function cutLever(bundle: ContextBundle, top: { what: string }): string {
  if (forMcp()) return mcpCutLever(bundle, top);
  const name = bundle.target.name;
  const container = CONTAINER_TARGET_KINDS.includes(bundle.target.kind.toLowerCase());
  switch (top.what) {
    case "member":
      return container
        ? `run ix context on one of them, or raise --max-tokens`
        : `ix contains ${name}, or raise --max-tokens`;
    case "caller":
      return `ix callers ${name}, or raise --max-tokens`;
    case "dependent":
      return `ix impact ${name}, or raise --max-tokens`;
    case "import":
      return `ix imports ${name}, or raise --max-tokens`;
    case "call":
      return `ix callees ${name}, or raise --max-tokens`;
    case "relationship":
      return `ix depends ${name}, or raise --max-tokens`;
    case "claim":
    case "conflict":
      return `ix conflicts ${name}, or raise --max-tokens`;
    default:
      return `raise --max-tokens`;
  }
}

const CONTAINER_TARGET_KINDS: readonly string[] = ["file", "module", "class", "object", "trait", "interface"];

/**
 * {@link cutLever} for an MCP caller: only core tools, and `max_tokens` for
 * the budget, since `ix_context` takes no flags. `ix contains`, `ix depends`
 * and `ix conflicts` have no core tool, so those cuts fall back to the nearest
 * one that does exist, or to the budget alone.
 */
function mcpCutLever(bundle: ContextBundle, top: { what: string }): string {
  const { name, path } = bundle.target;
  const container = CONTAINER_TARGET_KINDS.includes(bundle.target.kind.toLowerCase());
  const pin = container ? {} : { path };
  const budget = "raise max_tokens (default 3000)";
  switch (top.what) {
    case "member":
      return container ? `call ix_context on one of them, or ${budget}` : budget;
    case "caller":
      return `${suggest.neighbors(name, "callers", pin)}, or ${budget}`;
    case "dependent":
    case "relationship":
      return `${suggest.impact(name, pin)}, or ${budget}`;
    case "import":
      return `${suggest.neighbors(name, "imports", pin)}, or ${budget}`;
    case "call":
      return `${suggest.neighbors(name, "callees", pin)}, or ${budget}`;
    default:
      return budget;
  }
}

/** One sentence naming what was cut and the cheapest way to get it back. */
export function truncationAdvice(bundle: ContextBundle): string | undefined {
  const cut = bundle.truncation.cut ?? [];
  if (cut.length === 0) return undefined;
  const named = cut
    .slice(0, 3)
    .map((c) => `${c.count} ${c.what}${c.count === 1 ? "" : "s"}`)
    .join(", ");
  return `cut: ${named} — ${cutLever(bundle, cut[0])}`;
}

/** Members placed ahead of the backend's context nodes; the evidence shows as many. */
const LEADING_MEMBERS = 10;

/** Imports named in the evidence. The rest still enter the bundle as entities,
 * where they cost a line each and can carry the answer's file. */
const SHOWN_IMPORTS = 8;

/** Members of neighbouring files named in the evidence; the rest are entities. */
const SHOWN_NEIGHBOUR_MEMBERS = 6;
/** Members shown before anything outside the target; the rest close the list. */
const MEMBERS_BEFORE_OUTWARD = 5;

type Located = { path?: string; lineStart?: number; lineEnd?: number };

/** `path`, `lineStart` and `lineEnd`, omitting the unknown ones rather than writing `undefined`. */
function locationFields(ref: Located): Located {
  return {
    ...(ref.path ? { path: ref.path } : {}),
    ...(ref.lineStart !== undefined ? { lineStart: ref.lineStart } : {}),
    ...(ref.lineEnd !== undefined ? { lineEnd: ref.lineEnd } : {}),
  };
}

/** An evidence `location`, or nothing when the path is unknown. */
/** The target's own `path:start-end`, or just its path when it has no range. */
function targetLocation(facts: ContextFacts): Located | undefined {
  if (!facts.path) return undefined;
  return { path: facts.path, lineStart: facts.lineStart, lineEnd: facts.lineEnd };
}

/** One suggested read: the command, and whether its file changed since the last ingest. */
export interface NextRead {
  cmd: string;
  stale: boolean;
}

/**
 * A name or path a shell passes through unquoted and unsplit. No `$` (it
 * expands), no leading `#` (it starts a comment) and no leading `-` (it reads
 * as an option); anything else falls back to the range form.
 */
const SHELL_SAFE_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
const SHELL_SAFE_PATH = /^[A-Za-z0-9_./][A-Za-z0-9_./-]*$/;

/** Whether `ix read <name> --path <file>` reads `name` and nothing else; see `readsOneSymbol`. */
export type SymbolReadCheck = (name: string, path: string) => boolean;

/**
 * One on-disk check per workspace root (`symbolReadChecker`: one workspace
 * walk, each row's answer kept), shared by every bundle rendered against that
 * root within SYMBOL_CHECK_TTL_MS. Keyed on the root, not the bundle object,
 * so a render that sizes several copies of a bundle (a budget-fitting loop
 * measuring prefixes) still walks once. The short lifetime keeps a long-lived
 * `ix mcp` process from answering from a stale walk after files change.
 */
const SYMBOL_CHECK_TTL_MS = 5_000;
const symbolChecksByRoot = new Map<string, { check: SymbolReadCheck; at: number }>();

/** `readsOneSymbol` against this workspace's files, as they are on disk now, memoised per root. */
function onDiskSymbolCheck(): SymbolReadCheck {
  // Lazy: the workspace root is resolved only when a stale row asks, so a
  // bundle with no stale rows never loads workspace config for this.
  let check: SymbolReadCheck | undefined;
  return (name, path) => (check ??= checkerForRoot(resolveWorkspaceRoot()))(name, path);
}

function checkerForRoot(root: string): SymbolReadCheck {
  const now = Date.now();
  const cached = symbolChecksByRoot.get(root);
  if (cached && now - cached.at < SYMBOL_CHECK_TTL_MS) return cached.check;
  const check = symbolReadChecker(root);
  symbolChecksByRoot.set(root, { check, at: now });
  return check;
}

/** The `next` rows renderBundle prints: `nextReads` with the on-disk check, cheap to call again. */
export function renderedNextReads(bundle: ContextBundle): NextRead[] {
  return nextReads(bundle, 3, onDiskSymbolCheck());
}

/**
 * The reads worth making next, most valuable first.
 *
 * The evidence rows carry `path:start-end` and the caller still has to decide
 * which of them to open — so the bundle ends by saying so, as commands rather
 * than coordinates. The saving this exists for is the whole-file read: on the
 * benchmark set one avoided 34-61k-character read is worth more than every
 * byte the bundle spends, and an agent handed a path with no range opens the
 * file.
 *
 * `stale` says the row's file changed since the last ingest, from the flags
 * the bundle already carries. There the range is from the last ingest and
 * points at the wrong lines, so a stale row that names a symbol is suggested
 * as `ix read <name> --path <file>`, which re-anchors to where the name is
 * declared on disk now. A fresh row keeps the range: it is exact, and it never
 * fails, where a symbol read can (live, `ix read add --path
 * core-ingestion/src/role-classifier.ts` exited 1: the resolver's name search
 * never returned that `add`). The range form also stays for a row with no
 * named symbol, a file or module, a name the shell would split, a name the
 * bundle shows twice in one file, and a name `symbolRead` rejects. The bundle's
 * entities are only the target's neighbours, so a second `save` in the same
 * file need not be among them: renderBundle passes `onDiskSymbolCheck`, which
 * asks the file itself (see `readsOneSymbol`), once per workspace root.
 *
 * Deduped, because a caller and a dependent are frequently the same function,
 * and taken in evidence order, which is already the ranking — the target first,
 * then its members, what it reaches, and what reaches it.
 */
export function nextReads(
  bundle: ContextBundle,
  limit = 3,
  symbolRead: SymbolReadCheck = () => true,
): NextRead[] {
  const rows = rowFreshness(bundle);
  const seen = new Set<string>();
  const reads: NextRead[] = [];
  for (const item of bundle.evidence) {
    const loc = item.location;
    if (!loc?.path || loc.lineStart === undefined || loc.lineEnd === undefined) continue;
    const range = `${loc.path}:${loc.lineStart}-${loc.lineEnd}`;
    if (seen.has(range)) continue;
    seen.add(range);
    const { stale, symbol } = rows(item, loc.path, symbolRead);
    reads.push({ cmd: symbol ? `ix read ${symbol} --path ${loc.path}` : `ix read ${range}`, stale });
    if (reads.length === limit) break;
  }
  return reads;
}

/**
 * For one evidence row at `path`: whether its file changed since the last
 * ingest, and, for a stale row, the symbol name `read <name> --path <path>`
 * re-anchors to — undefined wherever the range form must stand (see
 * {@link nextReads} for each condition). Shared by the CLI and MCP closes.
 */
function rowFreshness(
  bundle: ContextBundle,
): (item: EvidenceItem, path: string, symbolRead: SymbolReadCheck) => { stale: boolean; symbol?: string } {
  // `?? []`: a bundle restored from an older save, or built by hand, may carry
  // evidence alone.
  const entities = bundle.entities ?? [];
  const byId = new Map<string, { id: string; name: string; kind: string; path?: string; stale?: boolean }>();
  for (const e of entities) byId.set(e.id, e);
  const target = bundle.target;
  if (target?.id && !byId.has(target.id)) byId.set(target.id, target);
  const stalePaths = new Set<string>();
  for (const e of entities) if (e.stale && e.path) stalePaths.add(e.path);
  const sameNameInFile = new Map<string, number>();
  for (const e of byId.values()) {
    if (!e.path) continue;
    const key = `${e.path}\n${e.name}`;
    sameNameInFile.set(key, (sameNameInFile.get(key) ?? 0) + 1);
  }
  return (item, path, symbolRead) => {
    const ref = item.refs?.[0];
    const entity = ref ? byId.get(ref) : undefined;
    const stale = entity?.stale === true
      || stalePaths.has(path)
      || (path === target?.path && bundle.freshness?.stale === true);
    const kind = entity?.kind.toLowerCase();
    const named = stale
      && entity !== undefined
      && entity.name !== ""
      && kind !== "file"
      && kind !== "module"
      && entity.path === path
      && SHELL_SAFE_NAME.test(entity.name)
      && SHELL_SAFE_PATH.test(path)
      && sameNameInFile.get(`${path}\n${entity.name}`) === 1
      // Last: the only check that may touch the disk.
      && symbolRead(entity.name, path);
    return named ? { stale, symbol: entity.name } : { stale };
  };
}

/** One MCP next step; `stale` and `reanchor` appear only on a stale read (see {@link nextToolCalls}). */
export interface NextToolCall {
  cmd: string;
  why: string;
  stale?: true;
  reanchor?: string;
}

/** Longest range a suggested read may span; past it the read covers its head only. */
export const NEXT_READ_MAX_LINES = 120;

/**
 * The next calls worth making, for an MCP caller.
 *
 * {@link nextReads} closes a CLI bundle with `ix read path:a-b`, which over MCP
 * is the one suggestion an agent's own Read tool already covers — and the
 * recorded agents that did follow the bundle never once asked the graph the
 * questions only it answers. So the MCP close leads with those: who calls (or
 * imports) the target across files, and what a change to it reaches. A read of
 * the target's own range comes last, capped so a 558-line class does not turn
 * into a 558-line suggestion.
 *
 * Every call names core tools only, and pins the target's file with `path=` so
 * an ambiguous name resolves to the entity this bundle was built for.
 *
 * The read step carries `stale: true` when its file changed since the last
 * ingest (its range is from the last ingest), and then, if the symbol re-anchors
 * safely (the same checks as {@link nextReads}), `reanchor`: an `ix_read
 * symbol=<name> path=<file>` call that lands on where the name is now.
 */
export function nextToolCalls(
  bundle: ContextBundle,
  symbolRead: SymbolReadCheck = () => true,
): NextToolCall[] {
  const { name, kind, path } = bundle.target;
  const steps: NextToolCall[] = [];
  const isFile = kind.toLowerCase() === "file";
  // A file resolves by its path; a symbol by name, pinned to its file.
  const symbol = isFile ? (path ?? name) : name;
  const pin = isFile ? {} : { path };

  steps.push(
    isFile
      ? { cmd: suggest.neighbors(symbol, "imported_by", pin), why: "every file that imports this one" }
      : { cmd: suggest.neighbors(symbol, "callers", pin), why: "every call site across files, from the graph rather than a name match" },
  );
  steps.push({ cmd: suggest.impact(symbol, pin), why: "what a change here reaches, before you edit it" });

  const readItem = bundle.evidence.find(
    (item) => item.location?.path && item.location.lineStart !== undefined && item.location.lineEnd !== undefined,
  );
  const read = readItem?.location;
  if (readItem && read?.lineStart !== undefined && read.lineEnd !== undefined) {
    const end = Math.min(read.lineEnd, read.lineStart + NEXT_READ_MAX_LINES - 1);
    // Additive: the range call is unchanged; a stale file adds `stale` and,
    // where the name re-anchors safely, the symbol form beside it.
    const { stale, symbol } = rowFreshness(bundle)(readItem, read.path, symbolRead);
    steps.push({
      cmd: toolCall("ix_read", { symbol: `${read.path}:${read.lineStart}-${end}` }),
      why: end < read.lineEnd
        ? `first ${NEXT_READ_MAX_LINES} of ${read.lineEnd - read.lineStart + 1} lines of the top-ranked evidence`
        : "the top-ranked evidence",
      ...(stale ? { stale: true as const } : {}),
      ...(symbol ? { reanchor: toolCall("ix_read", { symbol, path: read.path }) } : {}),
    });
  }
  return steps;
}

function locationField(ref: Located | undefined): { location?: EvidenceLocation } {
  if (!ref?.path) return {};
  return { location: { ...locationFields(ref), path: ref.path } };
}

function lineRange(location: EvidenceLocation): string | undefined {
  const { lineStart, lineEnd } = location;
  if (lineStart === undefined) return undefined;
  return lineEnd !== undefined && lineEnd !== lineStart ? `${lineStart}-${lineEnd}` : `${lineStart}`;
}

function formatLocation(location: EvidenceLocation): string {
  const lines = lineRange(location);
  return lines ? `${location.path}:${lines}` : location.path;
}

/** `rank.ts via listByKind, resolveWorkspaceId`, or just `rank.ts`. */
function relatedClause(ref: RelatedRef): string {
  const name = (ref.path ?? ref.name).split("/").pop();
  if (ref.named) return `${name} (${ref.named})`;
  return ref.via.length > 0 ? `${name} via ${ref.via.join(", ")}` : `${name} directly`;
}

function memberReason(ref: EntityLocation): string {
  if (ref.usedBy === undefined) return "defined in the target";
  if (ref.usedBy === 0) return "defined in the target; no recorded uses";
  const files = ref.usedFromFiles ?? 0;
  const where = files > 0 ? ` across ${files} other file${files === 1 ? "" : "s"}` : " within this file";
  return `defined in the target; used by ${ref.usedBy}${ref.usedByCapped ? "+" : ""}${where}`;
}

/**
 * Names for relationship endpoints. Relationship evidence used to print raw
 * ids -- `264cc04d-... --CONTAINS--> d1898d46-...` -- which an agent cannot use.
 * A name shared by two entities is qualified with its path, since several
 * files are routinely named `config.ts` or `README.md`; an id the bundle knows
 * nothing about stays an id.
 */
function entityLabeller(entities: ContextBundle["entities"]): (id: string) => string {
  const byId = new Map(entities.map((e) => [e.id, e]));
  const nameCounts = new Map<string, number>();
  for (const e of entities) nameCounts.set(e.name, (nameCounts.get(e.name) ?? 0) + 1);
  return (id) => {
    const e = byId.get(id);
    if (!e) return id;
    return (nameCounts.get(e.name) ?? 0) > 1 && e.path ? `${e.name} (${e.path})` : e.name;
  };
}

/**
 * The source record of a `/v1/provenance` response.
 *
 * The endpoint answers `{ entityId, chain: [{ rev, source: { uri, extractor,
 * ... } }] }`, and this used to read `sourceUri` and `extractor` off the top
 * level, where they never are -- so every bundle reported "provenance unknown,
 * extractor unknown". The newest chain entry is the one that describes the
 * current node. A flat record is still accepted as-is.
 */
function provenanceSource(provenance: unknown): Record<string, unknown> {
  const record = asRecord(provenance);
  const chain = Array.isArray(record.chain) ? record.chain.map(asRecord) : undefined;
  if (!chain) return record;
  if (chain.length === 0) return {};
  const latest = chain.reduce((a, b) =>
    (typeof b.rev === "number" ? b.rev : -Infinity) > (typeof a.rev === "number" ? a.rev : -Infinity) ? b : a);
  const source = asRecord(latest.source);
  return {
    sourceUri: source.uri ?? source.sourceUri,
    sourceHash: source.sourceHash,
    extractor: source.extractor,
    sourceType: source.sourceType,
    observedAt: latest.observedAt ?? source.observedAt,
  };
}

function orderedNodes<T extends { id: string; kind: string; name: string }>(nodes: T[]): T[] {
  return [...nodes].sort((a, b) => cmp(a.kind, b.kind) || cmp(a.name, b.name) || cmp(a.id, b.id));
}

function asRecord(value: unknown): Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

function asString(value: unknown): string | undefined {
  return typeof value === "string" ? value : undefined;
}

function cmp(a: string, b: string): number {
  return a < b ? -1 : a > b ? 1 : 0;
}