@intentius/chant 0.44.14 → 0.46.0

package/src/cli/handlers/lifecycle.ts

@@ -30,7 +30,9 @@ import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 import { affectedStacks } from "../../lifecycle/affected";
 import { rollbackToRevision } from "../../lifecycle/rollback";
-import { loadChantConfig, environmentNames } from "../../config";
+import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, resolveOwnershipStack } from "../../config";
+import { unknownEnvError, isProdLikeEnvironment } from "../../env";
+import { planTeardown, executeTeardown, type TeardownPlan, type TeardownReport } from "../../lifecycle/teardown";
 import { collectBuildRootContributors } from "../plugins";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { isResourceDeclarable } from "../../declarable";
@@ -109,7 +111,7 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const declaredParams = await commandBuildParams(config.buildParams, args);
   if (!declaredParams) return 1;
   const declaredEnvNames = environmentNames(config.environments);
-  if (declaredEnvNames && !declaredEnvNames.includes(environment)) {
+  if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
     console.error(formatError({
       message: `Unknown environment "${environment}"`,
       hint: `Defined environments: ${declaredEnvNames.join(", ")}`,
@@ -416,6 +418,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
           buildResult,
           json,
           stack: target.stack,
+          region: target.region,
           componentStacks,
           baseline,
           updateBaseline: args.updateBaseline,
@@ -650,6 +653,11 @@ interface LiveDiffArgs {
   /** Deployed stack name for a multi-stack project (#932); scopes the live
    * observation (which CloudFormation stack to query) and the snapshot read. */
   stack?: string;
+  /** Region that stack is deployed in, from `stacks[].region` (#1264). Same
+   * contract as snapshot (#1261): without it every stack is read against the
+   * ambient region, so a multi-region estate reports its out-of-region stacks
+   * as absent rather than unobserved. */
+  region?: string;
   /** Component projects deploy one CFN stack per component; observe them all and
    * union (the same fix graph/plan use), else every deployed resource reads as
    * "missing". Empty → the single-stack observe path. */
@@ -710,6 +718,9 @@ async function observeLexicon(
     declared: Set<string>;
     entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
     stack?: string;
+    /** Region the stack is deployed in (#1264); the read targets it instead of
+     * the ambient region. */
+    region?: string;
     componentStacks?: string[];
     owned?: boolean;
     /** `--namespace <ns>` (#1629): where to read an entity that declares no
@@ -723,6 +734,7 @@ async function observeLexicon(
     buildOutput: opts.buildOutput,
     entityNames,
     entities: opts.entities,
+    ...(opts.region ? { region: opts.region } : {}),
     ...(opts.owned !== undefined ? { owned: opts.owned } : {}),
     ...(opts.namespace ? { namespace: opts.namespace } : {}),
   };
@@ -746,6 +758,7 @@ async function observeLexicon(
       resources: {},
       unobserved: unobservedAll(entityNames, "read-failed", message, opts.entities),
       queried: {},
+      notes: [],
     };
   }
 }
@@ -811,6 +824,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
         declared,
         entities,
         stack: args.stack,
+        region: args.region,
         componentStacks: args.componentStacks,
         ...(args.namespace ? { namespace: args.namespace } : {}),
       });
@@ -839,6 +853,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
           buildOutput,
           entities,
           stack: args.stack,
+          region: args.region,
           componentStacks: args.componentStacks,
           baseline: baselineForLexicon(args.baseline, lexiconName),
         });
@@ -1181,6 +1196,9 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         // The resolved read address rides every entry, not just unobserved
         // ones — the diff path already passes it (#1620); plan lost it.
         queried: observed.queried,
+      }, {
+        // Attribution survives the flat merge below (#1674).
+        lexicon: lexiconName,
       });
       merged.entries.push(...cs.entries);
       checked++;
@@ -1224,6 +1242,220 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * chant lifecycle teardown <environment> (#1222).
+ *
+ * Enumerates what deleting the environment would remove: every live resource
+ * carrying this project's ownership marker (managed-by + `ownership.stack`)
+ * with the requested env identity. Stateless — live markers only, no build, no
+ * snapshot. Without `--yes` nothing is deleted; with it the planned set is
+ * executed per lexicon with one bounded retry pass over failures, and every
+ * candidate's outcome is reported (deleted / failed / not-prunable / skipped —
+ * never silence). A production-like environment name additionally requires an
+ * interactive confirmation, or `--confirm-prod` non-interactively.
+ */
+export async function runLifecycleTeardown(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle teardown <environment>" }));
+    return 1;
+  }
+
+  const { config } = await loadChantConfig(resolve("."));
+
+  // Refuse an env the project does not declare — a typo here is the difference
+  // between tearing down `dev` and tearing down `prod`. Literal `environments`
+  // entries only (#1221's pattern entries would extend this same check).
+  const envErr = unknownEnvError(environment, config.environments);
+  if (envErr) {
+    console.error(formatError({ message: envErr }));
+    return 1;
+  }
+
+  // Teardown selects on the ownership marker; a project that stamps none has
+  // nothing to key on, and "delete what looks like mine" is not a fallback.
+  const stack = resolveOwnershipStack(config);
+  if (stack === undefined) {
+    console.error(formatError({
+      message: "This project declares no ownership.stack — teardown is marker-scoped and has nothing to select on",
+      hint: 'Set `ownership: { stack: "<name>" }` in chant.config.ts and deploy, so resources carry the marker teardown keys on.',
+    }));
+    return 1;
+  }
+
+  // The prod guard (#1222): a production-like name never falls to `--yes`
+  // alone. Interactive runs re-type the environment name; non-interactive
+  // runs say `--confirm-prod` explicitly. Checked before any live read so a
+  // refused teardown touches nothing at all.
+  if (args.yes && isProdLikeEnvironment(environment) && !args.confirmProd) {
+    if (!process.stdin.isTTY) {
+      console.error(formatError({
+        message: `"${environment}" looks like a production environment — --yes alone is not enough`,
+        hint: "Re-run with --yes --confirm-prod to tear it down non-interactively.",
+      }));
+      return 1;
+    }
+    const confirmed = await promptProdTeardown(environment);
+    if (!confirmed) {
+      console.error(formatError({ message: "Confirmation did not match — nothing was deleted." }));
+      return 1;
+    }
+  }
+
+  // #1166 — teardown is always a live read (and with --yes, a live write), so
+  // an environment's declared endpoint applies here too, unless the ambient
+  // shell already set it.
+  const readingPlugins = plugins.filter((p) => p.teardownOwned || p.describeResources || p.executeTeardown);
+  const endpointResult = applyLiveEndpoint(config.environments, environment, readingPlugins);
+  if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
+
+  let plan: TeardownPlan;
+  let report: TeardownReport | undefined;
+  try {
+    // A multi-stack project's declared stacks, for stack-shaped teardowns
+    // (aws enumerates and deletes whole CloudFormation stacks). A single-stack
+    // project passes nothing and the env-named default convention applies.
+    const deployedStacks = (config.stacks ?? []).map((s) => ({
+      name: s.name,
+      ...(s.region ? { region: s.region } : {}),
+    }));
+    plan = await planTeardown({
+      environment,
+      stack,
+      plugins,
+      ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+    });
+    if (args.yes) {
+      report = await executeTeardown({
+        environment,
+        stack,
+        plugins,
+        plan,
+        ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+      });
+    }
+  } finally {
+    endpointResult.restore();
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(report ?? plan, null, 2));
+    return report && report.outcomes.some((o) => o.outcome === "failed") ? 1 : 0;
+  }
+
+  console.log(formatBold(
+    args.yes
+      ? `Teardown — environment: ${environment}, stack: ${stack}`
+      : `Teardown plan — environment: ${environment}, stack: ${stack} (plan only — nothing is deleted)`,
+  ));
+
+  if (plan.entries.length === 0) {
+    console.error(formatWarning({
+      message: `No live resources carry the marker stack "${stack}" + env "${environment}" — nothing would be deleted.` +
+        (plan.holes.length > 0
+          ? " But this plan has holes (below) — parts of the estate could not be read, so \"nothing\" is a claim about what was readable, not about the environment."
+          : " If this environment is deployed, check that its resources were stamped (ownership marking on, and the env identity resolved at build time)."),
+    }));
+  } else {
+    console.log(`\n${plan.entries.length} resource(s) would be deleted:`);
+    console.log("RESOURCE".padEnd(28) + "TYPE".padEnd(32) + "MARKER".padEnd(24) + "LEXICON");
+    console.log("-".repeat(96));
+    for (const entry of plan.entries) {
+      console.log(
+        entry.name.padEnd(28) +
+        entry.type.padEnd(32) +
+        `${entry.marker.stack}/${entry.marker.env}`.padEnd(24) +
+        entry.lexicon,
+      );
+    }
+  }
+
+  // Holes are loud (#1089): an unreadable kind is unknown, not absent, and the
+  // execution half must not treat this plan as the whole delete set.
+  if (plan.holes.length > 0) {
+    console.error(formatWarning({
+      message: `${plan.holes.length} hole(s) — resources chant may own but could not read. This plan is incomplete, not clean.`,
+    }));
+    console.log(formatBold("\nHOLES (stamped kinds the read could not cover):"));
+    for (const hole of plan.holes) {
+      console.log(`  ? ${hole.lexicon}: ${hole.name}${hole.type ? ` (${hole.type})` : ""} — ${hole.reason}${hole.detail ? `: ${hole.detail}` : ""}`);
+    }
+  }
+
+  if (plan.skipped.length > 0) {
+    console.error(formatWarning({
+      message: `Skipped (no teardown enumeration and no describeResources): ${plan.skipped.join(", ")} — those lexicons' resources are not in this plan.`,
+    }));
+  }
+
+  if (!report) {
+    console.error(formatWarning({ message: "Plan only — re-run with --yes to execute." }));
+    return 0;
+  }
+
+  if (report.outcomes.length > 0) {
+    console.log(formatBold("\nOutcomes:"));
+    console.log("RESOURCE".padEnd(28) + "OUTCOME".padEnd(14) + "LEXICON".padEnd(12) + "DETAIL");
+    console.log("-".repeat(96));
+    for (const o of report.outcomes) {
+      console.log(
+        o.name.padEnd(28) +
+        o.outcome.padEnd(14) +
+        o.lexicon.padEnd(12) +
+        (o.detail ?? "") +
+        (o.retried ? " (after retry)" : ""),
+      );
+    }
+  }
+
+  const counts = { deleted: 0, failed: 0, "not-prunable": 0, skipped: 0 };
+  for (const o of report.outcomes) counts[o.outcome]++;
+  console.log(
+    `\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ${counts.skipped} skipped`,
+  );
+
+  if (report.unimplemented.length > 0) {
+    console.error(formatWarning({
+      message: `Not executed (no teardown execution in these lexicons yet): ${report.unimplemented.join(", ")} — their candidates are reported as skipped, not deleted.`,
+    }));
+  }
+  if (plan.holes.length > 0) {
+    console.error(formatWarning({
+      message: "This teardown ran over an incomplete plan (holes above) — the environment cannot be called clean.",
+    }));
+  }
+  if (counts.failed > 0) {
+    console.error(formatError({
+      message: `${counts.failed} candidate(s) failed to delete after the retry pass — see the outcomes above.`,
+    }));
+    return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * The interactive half of the prod guard: the operator re-types the
+ * environment name. Anything else — including EOF — refuses.
+ */
+async function promptProdTeardown(environment: string): Promise<boolean> {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolvePrompt) => {
+    rl.question(
+      `"${environment}" looks like a production environment. Type the environment name to confirm teardown: `,
+      (answer) => {
+        resolvePrompt(answer.trim() === environment);
+        rl.close();
+      },
+    );
+    // EOF (Ctrl-D) closes the interface without answering — that is a refusal.
+    rl.on("close", () => resolvePrompt(false));
+  });
+}
+
 /**
  * chant lifecycle log [environment]
  */
@@ -1252,7 +1484,7 @@ export async function runLifecycleLog(ctx: CommandContext): Promise<number> {
 export async function runLifecycleUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown state subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
-    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle log",
+    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle teardown, chant lifecycle log",
   }));
   return 1;
 }

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

@@ -101,7 +101,7 @@ function makeOp(name: string, depends: string[] = []): [string, { config: { name
 function setupTemporalClient(mock: ReturnType<typeof createMockTemporalClient>) {
   loadTemporalClientMock.mockResolvedValue({
     Connection: { connect: vi.fn(async () => ({})) },
-    Client: vi.fn(() => mock.client) as unknown as new () => unknown,
+    Client: vi.fn(function () { return mock.client; }) as unknown as new () => unknown,
   });
   loadChantConfigMock.mockResolvedValue({ config: {} });
   resolveProfileMock.mockReturnValue({ address: "localhost:7233", namespace: "default", taskQueue: "q" });
@@ -951,9 +951,9 @@ describe("runOpComponents", () => {
       expect(runComponentsMock).toHaveBeenCalledWith(expect.any(String), "svc", expect.objectContaining({
         buildParams: [{ name: "tier", value: "light", source: "default" }],
       }));
-      // A parameter at its default collapses into the count line now; the
-      // provenance forwarded above is where its value is asserted.
-      expect(stderr.join("\n")).toContain("at their defaults");
+      // The echo is a one-line count (#1424); the provenance forwarded above
+      // is where the value is asserted.
+      expect(stderr.join("\n")).toContain("1 build parameter resolved (1 default)");
     });
 
     test("--param overrides a declared default and is threaded through to runComponents", async () => {
@@ -978,7 +978,7 @@ describe("runOpComponents", () => {
       expect(runComponentsMock).toHaveBeenCalledWith(expect.any(String), "svc", expect.objectContaining({
         buildParams: [{ name: "tier", value: "production", source: "cli" }],
       }));
-      expect(stderr.join("\n")).toContain("[param] tier");
+      expect(stderr.join("\n")).toContain("1 build parameter resolved (1 from cli)");
       vi.restoreAllMocks();
     });
 

package/src/cli/handlers/run.ts

@@ -714,6 +714,7 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
   const paramsResolution = resolveCliBuildParams(config.buildParams, {
     cli: parseParamFlags(ctx.args.param),
     paramsFile: ctx.args.paramsFile,
+    verbose: ctx.args.verbose,
   });
   if (!paramsResolution.success) {
     for (const message of paramsResolution.errors) console.error(message);

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

@@ -0,0 +1,217 @@
+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";
+
+// #1263 — `chant search --live` against an unreachable endpoint returned the
+// declared rows, exit 0, and a footer naming derived facts it never computed.
+// The observe layer already records a thrown read as NOT-OBSERVED
+// (`read-failed`, #1089); these tests pin that the handler carries it through
+// to the rows, the footer, stderr, and the exit code. `observeResources` is
+// real here so the plumbing from a throwing `describeResources` is exercised.
+
+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 hasSnapshotMock = vi.fn((..._a: unknown[]) => Promise.resolve(false));
+vi.mock("../../lifecycle/replay", () => ({
+  replaySnapshots: vi.fn(),
+  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;
+}
+
+function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return {
+    command: "search", path: "kind:Instance",
+    format: "", fix: false, watch: false, verbose: false, help: false, live: true, env: "dev",
+    ...overrides,
+  };
+}
+
+describe("search --live when the live read fails (#1263)", () => {
+  let out: string[];
+  let err: string[];
+  const entities = new Map<string, Declarable>([
+    ["webServer", decl({ lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} })],
+    ["privateServer", decl({ lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} })],
+  ]);
+
+  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);
+  });
+
+  const deadEndpoint = createMockPlugin({
+    name: "aws",
+    describeResources: async () => {
+      throw new Error("connect ECONNREFUSED 127.0.0.1:9999");
+    },
+  });
+
+  test("exits non-zero, names the lexicon and cause, and marks every row unobserved", async () => {
+    loadPluginsMock.mockResolvedValue([deadEndpoint]);
+    const exit = await runSearch({ args: makeArgs(), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    const stderr = err.join("\n");
+    expect(stderr).toContain("aws");
+    expect(stderr).toContain("ECONNREFUSED 127.0.0.1:9999");
+    expect(stderr).toContain("declared-only");
+    const stdout = out.join("\n");
+    expect(stdout).toContain("webServer  AWS::EC2::Instance  (unobserved: read-failed)");
+    expect(stdout).toContain("privateServer  AWS::EC2::Instance  (unobserved: read-failed)");
+    expect(stdout).toContain("live read failed (aws) · 2/2 rows unobserved");
+    // Nothing was read, so no fold over live topology could have run.
+    expect(stdout).not.toContain("also derived");
+  });
+
+  test("points at a recorded snapshot when one exists", async () => {
+    loadPluginsMock.mockResolvedValue([deadEndpoint]);
+    hasSnapshotMock.mockResolvedValue(true);
+    const exit = await runSearch({ args: makeArgs(), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(out.join("\n")).toContain("--at latest");
+    expect(err.join("\n")).toContain("--at latest");
+  });
+
+  test("a working live read still exits 0 with bound rows", async () => {
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async () => ({
+          webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK", owned: true },
+          privateServer: { type: "AWS::EC2::Instance", physicalId: "i-2", status: "OK", owned: true },
+        }),
+      }),
+    ]);
+    const exit = await runSearch({ args: makeArgs(), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("webServer  AWS::EC2::Instance  i-1");
+    expect(stdout).toContain("observed live · bound 2/2");
+    expect(err.join("\n")).not.toContain("live read failed");
+  });
+});
+
+// #1265 — a lexicon's run-level note ("ownership filter unavailable on this
+// path") printed once per stack, ahead of the rows. It is one fact about the
+// read, so it is said once, and it qualifies the answer, so it follows it.
+describe("search --live run-level notes (#1265)", () => {
+  const NOTE =
+    "ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export";
+  let out: string[];
+  let err: string[];
+  // One log of everything, in the order it was written, so the test can see
+  // whether the note came before or after the rows.
+  let all: string[];
+  const entities = new Map<string, Declarable>([
+    ["webServer", decl({ lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} })],
+    ["privateServer", decl({ lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} })],
+  ]);
+  const calls: string[] = [];
+
+  beforeEach(() => {
+    out = [];
+    err = [];
+    all = [];
+    calls.length = 0;
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); all.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { err.push(s); all.push(s); });
+    vi.spyOn(console, "warn").mockImplementation((s: string) => { all.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: { stacks: [{ name: "net" }, { name: "data" }, { name: "app" }, { name: "edge" }] },
+    });
+    resolveLexMock.mockReset();
+    resolveLexMock.mockResolvedValue(["aws"]);
+    hasSnapshotMock.mockReset();
+    hasSnapshotMock.mockResolvedValue(false);
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "aws",
+        describeResources: async (opts: { stack?: string }) => {
+          calls.push(opts.stack ?? "");
+          return {
+            observation: "v1" as const,
+            resources: {
+              webServer: { type: "AWS::EC2::Instance", physicalId: "i-1", status: "OK", ownership: "unknown" as const },
+              privateServer: { type: "AWS::EC2::Instance", physicalId: "i-2", status: "OK", ownership: "unknown" as const },
+            },
+            notes: [NOTE],
+          };
+        },
+      }),
+    ]);
+  });
+
+  test("four stacks, one note, after the rows and the provenance line", async () => {
+    const exit = await runSearch({ args: makeArgs(), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(calls).toEqual(["net", "data", "app", "edge"]);
+    const notes = all.filter((line) => line.includes("ownership filter unavailable"));
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain(`[aws] ${NOTE}`);
+    const noteAt = all.findIndex((line) => line.includes("ownership filter unavailable"));
+    const lastRow = all.findIndex((line) => line.startsWith("privateServer  AWS::EC2::Instance  i-2"));
+    const footer = all.findIndex((line) => line.includes("observed live · bound 2/2"));
+    expect(lastRow).toBeGreaterThanOrEqual(0);
+    expect(footer).toBeGreaterThan(lastRow);
+    expect(noteAt).toBeGreaterThan(footer);
+    // stderr, like every other warning; the rows stay clean on stdout.
+    expect(out.join("\n")).not.toContain("ownership filter unavailable");
+    expect(err.join("\n")).toContain("ownership filter unavailable");
+  });
+
+  test("a miss still says the note, after the miss", async () => {
+    const exit = await runSearch({ args: makeArgs({ path: "kind:Nope" }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    const notes = all.filter((line) => line.includes("ownership filter unavailable"));
+    expect(notes).toHaveLength(1);
+    expect(all.indexOf("(no matches)")).toBeLessThan(all.findIndex((l) => l.includes("ownership filter unavailable")));
+  });
+});

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

@@ -1,7 +1,7 @@
 import { describe, test, expect, vi } from "vitest";
 import { __searchInternals } from "./search";
 
-const { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss } = __searchInternals;
+const { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss, provenance } = __searchInternals;
 
 function node(id: string, kind: string, attrs: Record<string, unknown> = {}) {
   return { id, kind, lexicon: "aws", attrs } as never;
@@ -53,6 +53,13 @@ describe("search formatting", () => {
   test("compact row with live physical id, skipping object placeholders", () => {
     const live = node("webServer", "AWS::EC2::Instance", { physicalId: "i-abc" });
     expect(formatRow(live, [])).toBe("webServer  AWS::EC2::Instance  i-abc");
+  });
+
+  // #1263 — a row nobody could read printed blank where the physical id goes,
+  // which reads as "declared, not provisioned".
+  test("a row the live read could not observe says so in place of the physical id", () => {
+    const n = node("webServer", "AWS::EC2::Instance", { _status: "neutral", _unobserved: "read-failed" });
+    expect(formatRow(n, [])).toBe("webServer  AWS::EC2::Instance  (unobserved: read-failed)");
     const src = node("webServer", "AWS::EC2::Instance", { InstanceId: { $ref: "webServer.InstanceId" } });
     expect(formatRow(src, [])).toBe("webServer  AWS::EC2::Instance");
   });
@@ -353,3 +360,36 @@ describe("--show name matching", () => {
     expect(capture(() => showMiss([n] as never, ["Region"]))).toBe("");
   });
 });
+
+// #1263 — a `--live` read that failed entirely returned the declared rows with
+// the same footer as a working answer and exit 0.
+describe("provenance of a failed live read", () => {
+  const capture = (fn: () => void): string => {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    fn();
+    spy.mockRestore();
+    return lines.join("\n");
+  };
+  const rows = [
+    node("a", "AWS::EC2::Instance", { _unobserved: "read-failed" }),
+    node("b", "AWS::EC2::Instance", { _unobserved: "read-failed" }),
+  ] as never;
+
+  test("names the lexicon and counts the unobserved rows", () => {
+    const out = capture(() => provenance(rows, { kind: "live" }, undefined, ["aws: connect ECONNREFUSED 127.0.0.1:9999"]));
+    expect(out).toContain("live read failed (aws)");
+    expect(out).toContain("2/2 rows unobserved");
+    expect(out).toContain("physical ids unavailable");
+  });
+
+  test("points at a recorded snapshot when one exists", () => {
+    const out = capture(() => provenance(rows, { kind: "live" }, "yes", ["aws: connect ECONNREFUSED"]));
+    expect(out).toContain("--at latest");
+  });
+
+  test("a working live read is unchanged", () => {
+    const bound = [{ id: "a", kind: "AWS::EC2::Instance", lexicon: "aws", attrs: {}, physicalId: "i-1" }] as never;
+    expect(capture(() => provenance(bound, { kind: "live" }))).toBe("— observed live · bound 1/1");
+  });
+});