@intentius/chant 0.50.0 → 0.52.0

package/src/cli/handlers/search-drift.test.ts

@@ -0,0 +1,263 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
+import { createMockPlugin } from "../../../../test-utils/src/mock-plugin";
+
+// #1268 — query-scoped drift: `chant search --at latest --check-live` (and its
+// reverse, `--live --check-snapshot`) compares the matched rows against the
+// observation the primary answer did NOT use, reusing `diffLive` — the same
+// engine `lifecycle diff --live` uses — scoped to just those rows.
+
+const discoverMock = vi.fn();
+vi.mock("../../discovery/index", () => ({
+  discover: (...a: unknown[]) => discoverMock(...a),
+}));
+const loadPluginsMock = vi.fn();
+const resolveLexMock = vi.fn();
+vi.mock("../plugins", async () => {
+  const actual = await vi.importActual<typeof import("../plugins")>("../plugins");
+  return {
+    ...actual,
+    loadPlugins: (...a: unknown[]) => loadPluginsMock(...a),
+    resolveProjectLexicons: (...a: unknown[]) => resolveLexMock(...a),
+  };
+});
+const replaySnapshotsMock = vi.fn();
+const hasSnapshotMock = vi.fn((..._a: unknown[]) => Promise.resolve(false));
+vi.mock("../../lifecycle/replay", () => ({
+  replaySnapshots: (...a: unknown[]) => replaySnapshotsMock(...a),
+  hasSnapshot: (...a: unknown[]) => hasSnapshotMock(...a),
+}));
+const loadChantConfigMock = vi.fn();
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: (...a: unknown[]) => loadChantConfigMock(...a) };
+});
+const buildResultMock = vi.fn();
+vi.mock("../../build", async () => {
+  const actual = await vi.importActual<typeof import("../../build")>("../../build");
+  return {
+    ...actual,
+    build: (...a: unknown[]) => Promise.resolve(buildResultMock(...a)),
+    buildProject: (...a: unknown[]) => Promise.resolve(buildResultMock(...a)),
+  };
+});
+
+const { runSearch } = await import("./search");
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+const entities = new Map<string, Declarable>([
+  ["webServer", decl({ lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} })],
+  ["launchTemplateServer", decl({ lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} })],
+  ["dbServer", decl({ lexicon: "aws", entityType: "AWS::RDS::Instance", props: {} })],
+]);
+
+function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return {
+    command: "search", path: "kind:Instance",
+    format: "", fix: false, watch: false, verbose: false, help: false, live: false, env: "dev",
+    ...overrides,
+  };
+}
+
+describe("search query-scoped drift (#1268)", () => {
+  let out: string[];
+  let err: string[];
+
+  beforeEach(() => {
+    out = [];
+    err = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { err.push(s); });
+    discoverMock.mockReset();
+    discoverMock.mockResolvedValue({ entities, errors: [], sourceFiles: [] });
+    buildResultMock.mockReset();
+    buildResultMock.mockReturnValue({ errors: [], entities, outputs: new Map([["aws", ""]]), warnings: [] });
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveLexMock.mockReset();
+    resolveLexMock.mockResolvedValue(["aws"]);
+    hasSnapshotMock.mockReset();
+    hasSnapshotMock.mockResolvedValue(false);
+    replaySnapshotsMock.mockReset();
+  });
+
+  test("--check-live without --at is refused", async () => {
+    const exit = await runSearch({ args: makeArgs({ checkLive: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(err.join("\n")).toContain("--check-live needs --at");
+  });
+
+  test("--check-snapshot without --live is refused", async () => {
+    const exit = await runSearch({ args: makeArgs({ checkSnapshot: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(err.join("\n")).toContain("--check-snapshot needs --live");
+  });
+
+  test("--fail-on-drift without a check flag is refused", async () => {
+    const exit = await runSearch({ args: makeArgs({ failOnDrift: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(err.join("\n")).toContain("--fail-on-drift needs --check-live or --check-snapshot");
+  });
+
+  test("--at --check-live: drift only for matched rows, using diffLive's categories", async () => {
+    replaySnapshotsMock.mockResolvedValue({
+      observations: [{
+        lexicon: "aws",
+        resources: {
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK", attributes: { SubnetId: "subnet-old" } },
+          launchTemplateServer: { type: "AWS::EC2::Instance", physicalId: "i-2", status: "OK", attributes: {} },
+        },
+      }],
+      commit: "a1b2c3d4e5f6", timestamp: "2026-08-01T03:15:00.000Z", depth: "identity",
+    });
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => ({
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK", attributes: { SubnetId: "subnet-new" } },
+          launchTemplateServer: { type: "AWS::EC2::Instance", physicalId: "i-2", status: "OK", attributes: {} },
+          dbServer: { type: "AWS::RDS::Instance", physicalId: "db-1", status: "OK" },
+        }),
+      }),
+    ]);
+    const exit = await runSearch({
+      args: makeArgs({ path: "kind:EC2::Instance", at: "latest", checkLive: true }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(0);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("webServer  attributes.SubnetId: subnet-old → subnet-new — drifted");
+    expect(stdout).toContain("checked against a live read · 1 of 2 matched drifted");
+    // dbServer isn't matched by kind:EC2::Instance and must never enter the diff.
+    expect(stdout).not.toContain("dbServer");
+  });
+
+  test("--fail-on-drift exits non-zero when the scoped check finds drift", async () => {
+    replaySnapshotsMock.mockResolvedValue({
+      observations: [{ lexicon: "aws", resources: { webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" } } }],
+      commit: "a1b2c3d", timestamp: "t", depth: "identity",
+    });
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => ({
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "UPDATING" },
+        }),
+      }),
+    ]);
+    const exit = await runSearch({
+      args: makeArgs({ path: "kind:EC2::Instance", at: "latest", checkLive: true, failOnDrift: true }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(1);
+  });
+
+  test("no drift exits 0 even with --fail-on-drift", async () => {
+    replaySnapshotsMock.mockResolvedValue({
+      observations: [{ lexicon: "aws", resources: { webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" } } }],
+      commit: "a1b2c3d", timestamp: "t", depth: "identity",
+    });
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => ({
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" },
+        }),
+      }),
+    ]);
+    const exit = await runSearch({
+      args: makeArgs({ path: "webServer", at: "latest", checkLive: true, failOnDrift: true }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(0);
+    expect(out.join("\n")).toContain("no drift across 1 matched");
+  });
+
+  test("--live --check-snapshot: a resource newly observed since the snapshot", async () => {
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => ({
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" },
+        }),
+      }),
+    ]);
+    replaySnapshotsMock.mockResolvedValue({
+      observations: [{ lexicon: "aws", resources: {} }],
+      commit: "a1b2c3d", timestamp: "t", depth: "identity",
+    });
+    const exit = await runSearch({
+      args: makeArgs({ path: "webServer", live: true, checkSnapshot: true }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(0);
+    expect(out.join("\n")).toContain("webServer — newly observed since the recorded snapshot");
+  });
+
+  test("--check-snapshot with nothing recorded is a note, not a failure", async () => {
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => ({
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" },
+        }),
+      }),
+    ]);
+    replaySnapshotsMock.mockResolvedValue({ error: `No snapshots found for environment "dev"` });
+    const exit = await runSearch({
+      args: makeArgs({ path: "kind:EC2::Instance", live: true, checkSnapshot: true }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(0);
+    expect(err.join("\n")).toContain("--check-snapshot: No snapshots found");
+    expect(out.join("\n")).not.toContain("checked against");
+  });
+
+  test("a live read that fails during --check-live reports unobserved, never missing (#1089)", async () => {
+    replaySnapshotsMock.mockResolvedValue({
+      observations: [{ lexicon: "aws", resources: { webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" } } }],
+      commit: "a1b2c3d", timestamp: "t", depth: "identity",
+    });
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => { throw new Error("ECONNREFUSED"); },
+      }),
+    ]);
+    const exit = await runSearch({
+      args: makeArgs({ path: "kind:EC2::Instance", at: "latest", checkLive: true }),
+      plugins: [], serializers: [],
+    });
+    // The check-live read itself failed, which is the existing --live failure
+    // path (#1263) — a real problem distinct from any drift verdict.
+    expect(exit).toBe(1);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("? webServer");
+    expect(stdout).not.toContain("missing");
+  });
+
+  test("depth note: a deep-recorded snapshot compared here at identity says so", async () => {
+    replaySnapshotsMock.mockResolvedValue({
+      observations: [{ lexicon: "aws", resources: { webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" } } }],
+      commit: "a1b2c3d", timestamp: "t", depth: "deep",
+    });
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => ({
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK" },
+        }),
+      }),
+    ]);
+    const exit = await runSearch({
+      args: makeArgs({ path: "webServer", at: "latest", checkLive: true }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(0);
+    expect(out.join("\n")).toContain("snapshot recorded at deep depth, compared here at identity");
+  });
+});

package/src/cli/handlers/search.ts

@@ -8,7 +8,11 @@ import { discover } from "../../discovery/index";
 
 import { observeResources } from "../../lifecycle/observe";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
+import { diffLive, type LiveDiffResult } from "../../lifecycle/live-diff";
 import type { LiveObservation } from "../../graph-ir";
+import type { ResourceMetadata } from "../../lexicon";
+import type { ObservationDepth } from "../../lifecycle/types";
+import { formatUnobserved } from "../../observation";
 import { loadChantConfig, matchesDeclaredEnvironment } from "../../config";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { formatError, formatWarning } from "../format";
@@ -56,6 +60,31 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   }
   const show = parseShow(args);
 
+  // Query-scoped drift (#1268): --check-live checks a snapshot answer against
+  // a live read, --check-snapshot checks a live answer against the recorded
+  // snapshot — the direction each needs is the source it does NOT already have.
+  if (args.checkLive && !args.at) {
+    console.error(formatError({
+      message: "chant search --check-live needs --at <ref>",
+      hint: "answer from a snapshot and check the matched rows against a live read: --at latest --check-live --env <name>",
+    }));
+    return 1;
+  }
+  if (args.checkSnapshot && !args.live) {
+    console.error(formatError({
+      message: "chant search --check-snapshot needs --live",
+      hint: "answer live and check the matched rows against the recorded snapshot: --live --check-snapshot --env <name>",
+    }));
+    return 1;
+  }
+  if (args.failOnDrift && !args.checkLive && !args.checkSnapshot) {
+    console.error(formatError({
+      message: "chant search --fail-on-drift needs --check-live or --check-snapshot",
+      hint: "it fails the check those flags run, so it is meaningless without one",
+    }));
+    return 1;
+  }
+
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath);
 
@@ -73,6 +102,14 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   let ambientKinds: string[] = [];
   // Set only on a replay: whether the recording itself holds ambient resources.
   let replayAmbient: { recordedAmbient: boolean } | undefined;
+  // Query-scoped drift (#1268): the OTHER observation, read only when
+  // --check-live/--check-snapshot asked for one — the declared canvas to
+  // classify against, and whether the exit code should reflect what it found.
+  let checkObservations: LiveObservation[] | undefined;
+  let primaryObservations: LiveObservation[] | undefined;
+  let declaredForDrift: GraphIR | undefined;
+  let snapshotDepth: ObservationDepth | undefined;
+  let driftFailure = false;
   if (args.live || args.at) {
     const environment = args.env;
     if (!environment) {
@@ -126,6 +163,21 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
         ),
       };
       source = { kind: "snapshot", commit: replay.commit, timestamp: replay.timestamp };
+      snapshotDepth = replay.depth;
+      if (args.checkLive) {
+        // A fresh live read, additional to the snapshot the answer itself came
+        // from — this is what the matched rows get checked against.
+        const liveCheck = await observeResources(environment, observing, buildResult, {
+          owned: true,
+          stacks,
+          ambient: args.ambient === true,
+        });
+        for (const e of liveCheck.errors) {
+          liveFailures.push(e);
+          console.error(formatError({ message: `live read failed — ${e}` }));
+        }
+        checkObservations = liveCheck.observations;
+      }
     } else {
       const observed = await observeResources(environment, observing, buildResult, {
         owned: true,
@@ -142,7 +194,22 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
       observations = observed.observations;
       liveNotes = observed.notes ?? [];
       source = { kind: "live" };
+      if (args.checkSnapshot) {
+        // The reverse direction: answer live, check the matched rows against
+        // the most recently recorded snapshot. Missing entirely is not a
+        // failure of THIS command — the live answer already stands — so it is
+        // a note, not an error.
+        const scoped = new Set(stacks.filter((st) => st.src).map((st) => st.name));
+        const checkReplay = await replaySnapshots(environment, "latest", scoped);
+        if ("error" in checkReplay) {
+          console.error(formatWarning({ message: `--check-snapshot: ${checkReplay.error}` }));
+        } else {
+          checkObservations = checkReplay.observations;
+          snapshotDepth = checkReplay.depth;
+        }
+      }
     }
+    primaryObservations = observations;
     let live = buildLiveGraphIr(observations);
     // Containment edges, kept aside until after the overlay (see below).
     let containmentEdges: IREdge[] = [];
@@ -206,6 +273,7 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
       stacks.length > 0
         ? await buildDeclaredPerStack(stacks, projectPath)
         : buildGraphIr((await discover(resolve(args.src ?? config.sourceDir ?? "."))).entities, projectPath);
+    declaredForDrift = declared;
     // Carry the NOT-OBSERVED half of the tri-state (#1089) onto the rows, so a
     // declared entity nobody could read is painted `_unobserved` and a row can
     // say so instead of printing blank where a physical id would go (#1263).
@@ -279,6 +347,29 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   // Qualifies the provenance line, so it sits with it: one line per distinct
   // note for the whole run, not one per stack, and after the rows (#1265).
   for (const n of liveNotes) console.error(formatWarning({ message: n }));
+  // Query-scoped drift (#1268): the matched rows, and only the matched rows,
+  // checked against the observation the primary answer did NOT use. Scoping
+  // both sides of diffLive() to the matched ids is what keeps a query-scoped-
+  // out resource from reading as `missing` or `unobserved` — it was never
+  // asked about, which is a third thing from both.
+  if (checkObservations && declaredForDrift && primaryObservations) {
+    const declaredIds = new Set(declaredForDrift.nodes.map((n) => n.id));
+    const matchedIds = new Set(matches.map((n) => n.id));
+    const nowObservations = args.checkLive ? checkObservations : primaryObservations;
+    const thenObservations = args.checkLive ? primaryObservations : checkObservations;
+    const driftCount = renderDrift(
+      diffLive({
+        declared: new Set([...matchedIds].filter((id) => declaredIds.has(id))),
+        observedNow: pickResources(mergeResources(nowObservations), matchedIds),
+        observedThen: pickResources(mergeResources(thenObservations), matchedIds),
+        unobserved: pickResources(collectUnobserved(nowObservations), matchedIds),
+      }),
+      matches.length,
+      args.checkLive ? "live" : "snapshot",
+      snapshotDepth,
+    );
+    if (args.failOnDrift && driftCount > 0) driftFailure = true;
+  }
   ambientHint(matches, ambientKinds, args.ambient === true, replayAmbient);
   showMiss(matches, show);
   regionSpread(terms, matches, show);
@@ -297,6 +388,7 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
     }));
     return 1;
   }
+  if (driftFailure) return 1;
   return 0;
 }
 
@@ -463,6 +555,63 @@ function provenance(matches: IRNode[], source: AnswerSource, recorded?: string,
   console.log(`— observed from snapshot${at}${taken} · bound ${bound}/${matches.length}`);
 }
 
+/** Union `LiveObservation.resources` across lexicons into one name-keyed map. */
+function mergeResources(observations: LiveObservation[]): Record<string, ResourceMetadata> {
+  const out: Record<string, ResourceMetadata> = {};
+  for (const o of observations) Object.assign(out, o.resources);
+  return out;
+}
+
+/** Restrict a name-keyed map to the matched ids — the whole of "query-scoped". */
+function pickResources<T>(map: Record<string, T>, ids: Set<string>): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const id of ids) if (id in map) out[id] = map[id];
+  return out;
+}
+
+/**
+ * Render the query-scoped drift check (#1268) — one line per matched resource
+ * whose {@link diffLive} verdict is not `unchanged`, then a summary.
+ *
+ * Reuses `diffLive` unmodified, so every category means exactly what it means
+ * in `lifecycle diff --live`: `missing`/`orphan`/`disappeared`/`drifted` count
+ * as drift, the same set `lifecycle diff` totals; `newlyObserved` and runtime
+ * children are reported but do not, and `unobserved` — a read that could not
+ * look — stays distinct from both, the same #1089 tri-state everywhere else.
+ */
+function renderDrift(
+  diff: LiveDiffResult,
+  checked: number,
+  direction: "live" | "snapshot",
+  depth?: ObservationDepth,
+): number {
+  for (const name of diff.missing) console.log(`⚠ ${name} — missing (declared, not found by this check)`);
+  for (const name of diff.orphan) console.log(`⚠ ${name} — orphan (observed, not declared)`);
+  for (const name of diff.disappeared) console.log(`⚠ ${name} — disappeared since the recorded snapshot`);
+  for (const drift of diff.driftedSinceSnapshot) {
+    for (const change of drift.changes) {
+      console.log(`⚠ ${drift.name}  ${change.path}: ${formatValue(change.oldValue)} → ${formatValue(change.newValue)} — drifted`);
+    }
+  }
+  for (const name of diff.newlyObserved) console.log(`  · ${name} — newly observed since the recorded snapshot`);
+  for (const r of diff.runtimeChildren) console.log(`  · ${r.name} (${r.type}) — runtime, owned by ${r.owner}`);
+  for (const u of diff.unobserved) console.log(`  ? ${formatUnobserved(u.name, u)}`);
+  const driftCount = diff.missing.length + diff.orphan.length + diff.disappeared.length + diff.driftedSinceSnapshot.length;
+  const label = direction === "live" ? "a live read" : "the recorded snapshot";
+  const depthNote = depth === "deep" ? " · snapshot recorded at deep depth, compared here at identity" : "";
+  console.log(
+    `— checked against ${label} · ${driftCount > 0 ? `${driftCount} of ${checked} matched drifted` : `no drift across ${checked} matched`}${depthNote}`,
+  );
+  return driftCount;
+}
+
+function formatValue(v: unknown): string {
+  if (v === undefined) return "<unset>";
+  if (typeof v === "string") return v.length > 60 ? v.slice(0, 57) + "..." : v;
+  const json = JSON.stringify(v);
+  return json.length > 60 ? json.slice(0, 57) + "..." : json;
+}
+
 /**
  * Name the facts chant computed for the kinds in this result that the query did not use.
  *
@@ -815,4 +964,4 @@ function formatRow(n: IRNode, show: string[]): string {
 }
 
 /** Internals exposed for unit tests. */
-export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss, provenance };
+export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss, provenance, renderDrift, mergeResources, pickResources };

package/src/cli/main.ts

@@ -83,6 +83,9 @@ const BOOLEAN_FLAGS = new Set([
   "--yes",
   "--confirm-prod",
   "--once",
+  "--check-live",
+  "--check-snapshot",
+  "--fail-on-drift",
 ]);
 
 /**
@@ -305,6 +308,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.at = args[++i];
     } else if (arg === "--ambient") {
       result.ambient = true;
+    } else if (arg === "--check-live") {
+      result.checkLive = true;
+    } else if (arg === "--check-snapshot") {
+      result.checkSnapshot = true;
+    } else if (arg === "--fail-on-drift") {
+      result.failOnDrift = true;
     } else if (arg === "--run-examples") {
       result.runExamples = true;
     } else if (arg === "--pinned-digest") {
@@ -615,6 +624,8 @@ Options:
                         OR with a path arg: SARIF report destination (migrate)
                         OR '--report gitlab-mr': emit the GitLab MR plan-widget
                         JSON (lifecycle plan)
+                        OR '--report markdown': emit a reviewer-facing markdown
+                        render, holes and disruption included (lifecycle plan)
   --from <name>         Source lexicon for migrate (default: github)
   --to <name>           Target lexicon for migrate (default: gitlab)
   --emit <fmt>          Migration output format: yaml (default) or ts

package/src/cli/mcp/op-tools.ts

@@ -1,8 +1,9 @@
 import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
-import { resolveWorkflowId } from "../handlers/run-client";
+import { resolveWorkflowId, fetchNormalizedHistory } from "../handlers/run-client";
 import { generateReport } from "../handlers/run-report";
+import { extractStepRecords, countActivities, queryGateState } from "../handlers/op-progress";
 import type { ToolRegistration } from "./lifecycle-tools";
 
 function workflowFnName(opName: string): string {
@@ -117,14 +118,22 @@ export function createOpStatusTool(): ToolRegistration {
       const name = params.name as string;
       const profile = params.profile as string | undefined;
 
+      const { ops } = await discoverOps();
+      const config = ops.get(name)?.config;
+
       const { client } = await makeTemporalClient(profile, resolve("."));
       const handle = client.workflow.getHandle(resolveWorkflowId(name));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
 
-      const events = history.events ?? [];
-      const activitiesCompleted = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-      const activitiesScheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+      const { completed: activitiesCompleted, scheduled: activitiesScheduled } = countActivities(history);
+      // Per-phase progress (#1676) — the same StepRecord shape `chant run
+      // <name> --json` uses locally, so a consumer renders one way
+      // regardless of executor. Only buildable when the Op's config was
+      // discoverable (a *.op.ts file on disk); absent otherwise rather than
+      // guessed at.
+      const progress = config ? extractStepRecords(config, history, { final: Boolean(desc.closeTime) }) : undefined;
+      const gate = await queryGateState(handle);
 
       return {
         workflowId: desc.workflowId,
@@ -135,6 +144,8 @@ export function createOpStatusTool(): ToolRegistration {
         taskQueue: desc.taskQueue,
         activitiesCompleted,
         activitiesScheduled,
+        ...(progress ? { progress } : {}),
+        gate: gate ?? null,
       };
     },
   };
@@ -196,7 +207,7 @@ export function createOpReportTool(): ToolRegistration {
       const { client } = await makeTemporalClient(profile, resolve("."));
       const handle = client.workflow.getHandle(resolveWorkflowId(name));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
 
       return generateReport(name, config, desc, history);
     },

package/src/cli/mcp/resource-handlers.ts

@@ -5,7 +5,8 @@ import { getContext } from "./resources/context";
 import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
 import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
-import { resolveWorkflowId } from "../handlers/run-client";
+import { resolveWorkflowId, fetchNormalizedHistory } from "../handlers/run-client";
+import { extractStepRecords, countActivities, queryGateState } from "../handlers/op-progress";
 import { loadOkfBundle } from "../../okf-read";
 import { loadChantConfigUpward, resolveKnowledgeDir } from "../../config";
 
@@ -177,11 +178,16 @@ export async function handleResourcesRead(
   if (uri.startsWith("chant://ops/") && uri.endsWith("/runs/latest")) {
     const name = uri.replace("chant://ops/", "").replace("/runs/latest", "");
     try {
+      const { ops } = await discoverOps();
+      const config = ops.get(name)?.config;
+
       const { client } = await makeTemporalClient(undefined, resolve("."));
       const handle = client.workflow.getHandle(resolveWorkflowId(name));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
-      const events = history.events ?? [];
+      const history = await fetchNormalizedHistory(handle);
+      const { completed: activitiesCompleted, scheduled: activitiesScheduled } = countActivities(history);
+      const progress = config ? extractStepRecords(config, history, { final: Boolean(desc.closeTime) }) : undefined;
+      const gate = await queryGateState(handle);
       const result = {
         workflowId: desc.workflowId,
         runId: desc.runId,
@@ -189,8 +195,10 @@ export async function handleResourcesRead(
         startTime: desc.startTime,
         closeTime: desc.closeTime ?? null,
         taskQueue: desc.taskQueue,
-        activitiesCompleted: events.filter((e) => e.eventType === "ActivityTaskCompleted").length,
-        activitiesScheduled: events.filter((e) => e.eventType === "ActivityTaskScheduled").length,
+        activitiesCompleted,
+        activitiesScheduled,
+        ...(progress ? { progress } : {}),
+        gate: gate ?? null,
       };
       return {
         contents: [{ uri, mimeType: "application/json", text: JSON.stringify(result, null, 2) }],

package/src/cli/registry.ts

@@ -26,7 +26,20 @@ export interface ParsedArgs {
   temporal?: boolean;
   /** `chant run` — emit the structured OpRunResult as JSON on stdout. */
   json?: boolean;
-  /** `chant run --components <name|all> --progress-json` — stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts) per line to stdout while the run executes (local executor only), so a consumer can render live wave/component/phase/step progress instead of tailing raw logs. Purely additive: run semantics, ordering, and exit code are unchanged; omitted (undefined, not false) when the flag isn't passed. */
+  /**
+   * `chant run --components <name|all> --progress-json` (local executor) —
+   * stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts)
+   * per line to stdout while the run executes, so a consumer can render live
+   * wave/component/phase/step progress instead of tailing raw logs.
+   *
+   * `chant run <name> --temporal --progress-json` (chant #1676) — the same
+   * flag on an Op's durable path streams one NDJSON `StepRecord`
+   * (../../op/local-executor.ts, reconstructed from workflow history by
+   * ../handlers/op-progress.ts) per settled step instead.
+   *
+   * Both are purely additive: run semantics, ordering, and exit code are
+   * unchanged; omitted (undefined, not false) when the flag isn't passed.
+   */
   progressJson?: boolean;
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
@@ -185,6 +198,25 @@ export interface ParsedArgs {
    * what is declared, which is a broader read and a different claim.
    */
   ambient?: boolean;
+  /**
+   * `chant search "<q>" --at <ref> --check-live --env <name>` (#1268) —
+   * additionally read the estate live and diff the matched rows against the
+   * snapshot the answer came from, reusing `diffLive` (the same engine
+   * `lifecycle diff --live` uses) scoped to just those rows. Requires `--at`.
+   */
+  checkLive?: boolean;
+  /**
+   * `chant search "<q>" --live --check-snapshot --env <name>` (#1268) — the
+   * reverse of `--check-live`: answer live, diff the matched rows against the
+   * most recently recorded snapshot. Requires `--live`.
+   */
+  checkSnapshot?: boolean;
+  /**
+   * `chant search "<q>" --check-live|--check-snapshot --fail-on-drift`
+   * (#1268) — exit non-zero when the scoped check finds drift, so it is usable
+   * as a CI gate. Meaningless without one of the two flags above.
+   */
+  failOnDrift?: boolean;
 
   /** `chant dev surface-diff --run-examples` — also run the example build harness */
   runExamples?: boolean;