@intentius/chant 0.50.0 → 0.51.0

package/src/cli/handlers/run.test.ts

@@ -50,6 +50,9 @@ vi.mock("./run-client", () => ({
   connectionOptions: (profile: { address: string }) => ({ address: profile.address }),
   resolveProfile: (...args: unknown[]) => resolveProfileMock(...args),
   resolveWorkflowId: (name: string) => `chant-op-${name}`,
+  // Test fixtures already use the short event-type form fetchNormalizedHistory
+  // produces (see mock-temporal-client.ts) — a passthrough keeps them valid.
+  fetchNormalizedHistory: (handle: { fetchHistory(): Promise<unknown> }) => handle.fetchHistory(),
 }));
 vi.mock("node:fs", async () => {
   const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
@@ -297,6 +300,54 @@ describe("runOpStatus", () => {
     expect(out).toContain("COMPLETED");
     expect(out).toContain("1/2 completed");
   });
+
+  test("a pending gate prints a Gate line via the gateState query (#1676)", async () => {
+    setupTemporalClient(createMockTemporalClient({
+      describeByWorkflowId: {
+        "chant-op-alb-deploy": {
+          workflowId: "chant-op-alb-deploy", runId: "r1",
+          status: { name: "RUNNING" },
+          startTime: new Date("2026-05-01T00:00:00Z"),
+          taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+        },
+      },
+      historyByWorkflowId: { "chant-op-alb-deploy": [] },
+      queryResultByWorkflowId: {
+        "chant-op-alb-deploy:gateState": {
+          signalName: "gate-dns-delegation",
+          description: "Approve DNS delegation",
+          since: "2026-05-01T00:05:00.000Z",
+        },
+      },
+    }));
+    const stdout = makeStdoutSpy();
+    const exit = await runOpStatus({ args: makeArgs({ extraPositional: "alb-deploy" }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    const out = stdout.join("\n");
+    expect(out).toContain("Gate");
+    expect(out).toContain("gate-dns-delegation");
+    expect(out).toContain("Approve DNS delegation");
+    expect(out).toContain("2026-05-01T00:05:00.000Z");
+  });
+
+  test("an Op with no pending gate (query unregistered or answers null) prints no Gate line", async () => {
+    setupTemporalClient(createMockTemporalClient({
+      describeByWorkflowId: {
+        "chant-op-alb-deploy": {
+          workflowId: "chant-op-alb-deploy", runId: "r1",
+          status: { name: "COMPLETED" },
+          startTime: new Date("2026-05-01T00:00:00Z"),
+          closeTime: new Date("2026-05-01T01:00:00Z"),
+          taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+        },
+      },
+      historyByWorkflowId: { "chant-op-alb-deploy": [] },
+    }));
+    const stdout = makeStdoutSpy();
+    const exit = await runOpStatus({ args: makeArgs({ extraPositional: "alb-deploy" }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(stdout.join("\n")).not.toContain("Gate");
+  });
 });
 
 // ── chant run status <name> --components (#599) ─────────────────────────────
@@ -731,6 +782,99 @@ describe("runOp", () => {
     }
   });
 
+  // ── --progress-json (#1676) ──────────────────────────────────────────────
+
+  test("--progress-json streams one NDJSON StepRecord per settled step, plus a final skipped record", async () => {
+    vi.useFakeTimers();
+    try {
+      discoverOpsMock.mockResolvedValue({
+        ops: new Map([[
+          "alb-deploy",
+          {
+            config: {
+              name: "alb-deploy", overview: "o",
+              phases: [
+                { name: "Build", steps: [{ kind: "activity", fn: "build" }] },
+                { name: "Deploy", steps: [{ kind: "activity", fn: "deploy" }] },
+              ],
+            },
+          },
+        ]]),
+        errors: [],
+      });
+      setupTemporalClient(createMockTemporalClient({
+        describeByWorkflowId: {
+          "chant-op-alb-deploy": {
+            workflowId: "chant-op-alb-deploy", runId: "r1",
+            status: { name: "COMPLETED" }, startTime: new Date(),
+            taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+          },
+        },
+        historyByWorkflowId: {
+          "chant-op-alb-deploy": [
+            { eventId: "1", eventType: "ActivityTaskScheduled", activityTaskScheduledEventAttributes: { activityId: "1", activityType: { name: "build" } } },
+            { eventType: "ActivityTaskCompleted", activityTaskCompletedEventAttributes: { scheduledEventId: "1" } },
+          ],
+        },
+      }));
+      existsSyncMock.mockReturnValue(true);
+      const { proc } = makeFakeChildProcess();
+      spawnChildMock.mockReturnValue(proc);
+      generateReportMock.mockReturnValue("# Report");
+      writeReportMock.mockReturnValue("/tmp/report.md");
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+      const stdoutLines: string[] = [];
+      const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => { stdoutLines.push(String(chunk)); return true; });
+
+      const promise = runOp({ args: makeArgs({ path: "alb-deploy", progressJson: true }), plugins: [], serializers: [] });
+      await vi.advanceTimersByTimeAsync(5000);
+      const exit = await promise;
+
+      expect(exit).toBe(0);
+      const records = stdoutLines.filter((l) => l.trim()).map((l) => JSON.parse(l));
+      expect(records).toEqual([
+        { phase: "Build", fn: "build", status: "ok", durationMs: 0 },
+        { phase: "Deploy", fn: "deploy", status: "skipped", durationMs: 0 },
+      ]);
+      stdoutSpy.mockRestore();
+    } finally {
+      vi.useRealTimers();
+    }
+  }, 10_000);
+
+  test("without --progress-json, nothing is written to stdout during the poll loop", async () => {
+    vi.useFakeTimers();
+    try {
+      discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("alb-deploy")]), errors: [] });
+      setupTemporalClient(createMockTemporalClient({
+        describeByWorkflowId: {
+          "chant-op-alb-deploy": {
+            workflowId: "chant-op-alb-deploy", runId: "r1",
+            status: { name: "COMPLETED" }, startTime: new Date(),
+            taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+          },
+        },
+        historyByWorkflowId: { "chant-op-alb-deploy": [] },
+      }));
+      existsSyncMock.mockReturnValue(true);
+      const { proc } = makeFakeChildProcess();
+      spawnChildMock.mockReturnValue(proc);
+      generateReportMock.mockReturnValue("# Report");
+      writeReportMock.mockReturnValue("/tmp/report.md");
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+      const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+
+      const promise = runOp({ args: makeArgs({ path: "alb-deploy" }), plugins: [], serializers: [] });
+      await vi.advanceTimersByTimeAsync(5000);
+      await promise;
+
+      expect(stdoutSpy).not.toHaveBeenCalled();
+      stdoutSpy.mockRestore();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   test("workflow ends in FAILED → exit 1, worker still killed", async () => {
     vi.useFakeTimers();
     try {

package/src/cli/handlers/run.ts

@@ -5,7 +5,7 @@ import { spawn as spawnChild, type ChildProcess } from "node:child_process";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
 import { discoverOps } from "../../op/discover";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
-import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure } from "../../op/local-executor";
+import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure, type StepRecord } from "../../op/local-executor";
 import { renderHuman, renderJson } from "../../op/local-output";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
@@ -15,11 +15,13 @@ import {
   connectionOptions,
   resolveWorkflowId,
   resolveProfile,
+  fetchNormalizedHistory,
   type WorkflowHandleRaw,
   type WorkflowExecutionDescription,
   type WorkflowHistoryRaw,
 } from "./run-client";
 import { generateReport, writeReport } from "./run-report";
+import { extractStepRecords, countActivities, queryGateState } from "./op-progress";
 import { runComponents, resolveComponentTargets, findComponentGate, listComponents } from "../../components/cli-support";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
@@ -250,12 +252,12 @@ export async function runOpStatus(ctx: CommandContext): Promise<number> {
   if (ctx.args.components) return runComponentStatus(ctx, name);
 
   const projectPath = resolve(".");
-  let client, desc: WorkflowExecutionDescription, history: WorkflowHistoryRaw;
+  let client, desc: WorkflowExecutionDescription, history: WorkflowHistoryRaw, handle: WorkflowHandleRaw;
   try {
     ({ client } = await makeTemporalClient(ctx.args.profile, projectPath));
-    const handle = client.workflow.getHandle(resolveWorkflowId(name));
+    handle = client.workflow.getHandle(resolveWorkflowId(name));
     desc = await handle.describe();
-    history = await handle.fetchHistory();
+    history = await fetchNormalizedHistory(handle);
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
@@ -269,13 +271,19 @@ export async function runOpStatus(ctx: CommandContext): Promise<number> {
   console.log(`  Started     : ${desc.startTime.toISOString()}`);
   if (desc.closeTime) console.log(`  Closed      : ${desc.closeTime.toISOString()}`);
 
-  const events = history.events ?? [];
-  const completed = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-  const scheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+  const { completed, scheduled } = countActivities(history);
   if (scheduled > 0) {
     console.log(`  Activities  : ${completed}/${scheduled} completed`);
   }
 
+  // Queryable gate state (#1676) — undefined means the query itself failed
+  // (an ungated Op never registers a "gateState" handler), so print nothing;
+  // null means the query answered "no gate pending" — also nothing to print.
+  const gate = await queryGateState(handle);
+  if (gate) {
+    console.log(`  Gate        : ${gate.signalName}${gate.description ? ` — ${gate.description}` : ""} (waiting since ${gate.since})`);
+  }
+
   return 0;
 }
 
@@ -293,7 +301,7 @@ async function runComponentStatus(ctx: CommandContext, name: string): Promise<nu
     ({ client } = await makeTemporalClient(ctx.args.profile, projectPath));
     const handle = client.workflow.getHandle(componentWorkflowId(name));
     desc = await handle.describe();
-    history = await handle.fetchHistory();
+    history = await fetchNormalizedHistory(handle);
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
@@ -307,9 +315,7 @@ async function runComponentStatus(ctx: CommandContext, name: string): Promise<nu
   console.log(`  Started     : ${desc.startTime.toISOString()}`);
   if (desc.closeTime) console.log(`  Closed      : ${desc.closeTime.toISOString()}`);
 
-  const events = history.events ?? [];
-  const completed = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-  const scheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+  const { completed, scheduled } = countActivities(history);
   if (scheduled > 0) {
     console.log(`  Activities  : ${completed}/${scheduled} completed`);
   }
@@ -528,9 +534,7 @@ async function waitForTemporalServer(address: string, maxWaitMs = 30_000): Promi
 }
 
 function renderProgress(opName: string, history: WorkflowHistoryRaw): void {
-  const events = history.events ?? [];
-  const completed = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-  const scheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+  const { completed, scheduled } = countActivities(history);
   process.stderr.write(
     `\r${formatInfo(`[${opName}]`)} ${completed}/${scheduled} activities completed`,
   );
@@ -954,7 +958,7 @@ async function runComponentTemporal(
     while (true) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
       renderProgress(component.name, history);
       if (TERMINAL_STATUSES.has(desc.status.name)) {
         process.stderr.write("\n");
@@ -1160,7 +1164,7 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
       ({ client } = await makeTemporalClient(ctx.args.profile, projectPath));
       const handle = client.workflow.getHandle(resolveWorkflowId(opName));
       desc = await handle.describe();
-      history = await handle.fetchHistory();
+      history = await fetchNormalizedHistory(handle);
     } catch (err) {
       console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
       return 1;
@@ -1248,7 +1252,23 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  // Poll for progress until terminal state
+  // Poll for progress until terminal state.
+  //
+  // `--progress-json` (chant #1676): stream one NDJSON StepRecord per line to
+  // stdout as each declared step settles — the durable-path counterpart to
+  // `chant run <name> --json`'s local-executor record shape (op-progress.ts).
+  // Purely additive: when the flag is absent `emitProgress` stays undefined
+  // and every `emitProgress?.(...)` call is a no-op, so poll-loop behavior
+  // is unchanged. `extractStepRecords` is stable and append-only across
+  // polls (same declared order, a growing history), so a plain emitted-count
+  // watermark is enough to emit only what's new each round.
+  const emitProgress = ctx.args.progressJson ? ndjsonProgressSink<StepRecord>() : undefined;
+  let emittedCount = 0;
+  const emitNewRecords = (records: StepRecord[]) => {
+    for (const record of records.slice(emittedCount)) emitProgress?.(record);
+    emittedCount = records.length;
+  };
+
   let finalDesc: WorkflowExecutionDescription | undefined;
   let finalHistory: WorkflowHistoryRaw | undefined;
 
@@ -1256,12 +1276,14 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
     while (true) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
 
       renderProgress(opName, history);
+      if (emitProgress) emitNewRecords(extractStepRecords(config, history));
 
       if (TERMINAL_STATUSES.has(desc.status.name)) {
         process.stderr.write("\n");
+        if (emitProgress) emitNewRecords(extractStepRecords(config, history, { final: true }));
         finalDesc = desc;
         finalHistory = history;
         break;

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");
+  });
+});