@intentius/chant 0.52.2 → 0.53.1

package/src/cli/handlers/carve.ts

@@ -3,17 +3,18 @@ import { formatError } from "../format";
 import type { CommandContext } from "../registry";
 
 /**
- * `chant carve advise --from <terraform-dir> [--json] [--report <path>]`
+ * `chant carve advise --from <terraform-dir | cdk.out> [--json] [--report <path>]`
  *
- * Read-only. Reuses `--from` (shared with migrate/import) for the estate dir.
- * Loads no chant project and no lexicon plugins — pure analysis of a foreign
- * Terraform tree.
+ * Read-only. Reuses `--from` (shared with migrate/import) for the source dir,
+ * and works out which source it is by looking at the directory (#1056) rather
+ * than adding a second flag. Loads no chant project and no lexicon plugins —
+ * pure analysis of a foreign tree.
  */
 export async function runCarveAdvise(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 
   const result = await carveAdvise({
-    from: args.migrateFrom, // `--from <terraform-dir>`
+    from: args.migrateFrom, // `--from <terraform-dir | cdk.out>`
     statePath: args.statePath, // `--state <tfstate>`
     reportFile: args.reportFile, // `--report <path>`
   });
@@ -21,7 +22,7 @@ export async function runCarveAdvise(ctx: CommandContext): Promise<number> {
   if (!result.ok) {
     console.error(formatError({
       message: result.error ?? "carve advise failed",
-      hint: "chant carve advise --from ./path/to/terraform",
+      hint: "chant carve advise --from ./path/to/terraform   (or ./cdk.out)",
     }));
     return 1;
   }
@@ -38,7 +39,7 @@ export async function runCarveAdvise(ctx: CommandContext): Promise<number> {
 export async function runCarveUnknown(_ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: "Unknown carve subcommand",
-    hint: "chant carve advise --from <terraform-dir>   (read-only peelability report)",
+    hint: "chant carve advise --from <terraform-dir | cdk.out>   (read-only peelability report)",
   }));
   return 1;
 }

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

@@ -53,7 +53,7 @@ vi.mock("../../config", async () => {
   };
 });
 
-const { runLifecycleDiff, runLifecyclePlan, runLifecycleSnapshot, runLifecycleShow, runLifecycleLog, runLifecycleTeardown, runLifecycleUnknown } = await import("./lifecycle");
+const { runLifecycleDiff, runLifecyclePlan, runLifecycleSnapshot, runLifecycleShow, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } = await import("./lifecycle");
 
 function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
   return {
@@ -1673,3 +1673,189 @@ describe("runLifecycleTeardown (#1222 — plan only)", () => {
     expect(parsed.entries).toHaveLength(1);
   });
 });
+
+describe("runLifecycleWhoami (#1982)", () => {
+  let stdoutBuf: string[];
+  let stderrBuf: string[];
+
+  beforeEach(() => {
+    stdoutBuf = [];
+    stderrBuf = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: { environments: ["prod"] } });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.AWS_ENDPOINT_URL;
+  });
+
+  function whoamiCtx(plugins: LexiconPlugin[], overrides: Partial<ParsedArgs> = {}) {
+    return {
+      args: makeArgs({ command: "lifecycle", path: "whoami", extraPositional: "prod", ...overrides }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    };
+  }
+
+  const awsIdentity = createMockPlugin({
+    name: "aws",
+    describeIdentity: async () => ({
+      identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      scope: "491500000000 us-east-1",
+      source: "env AWS_ACCESS_KEY_ID",
+      endpoint: "https://sts.us-east-1.amazonaws.com/",
+    }),
+  });
+
+  test("missing environment arg → exit 1", async () => {
+    const exit = await runLifecycleWhoami(whoamiCtx([], { extraPositional: undefined }));
+    expect(exit).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("Environment is required");
+  });
+
+  test("environment not in config → exit 1", async () => {
+    const exit = await runLifecycleWhoami(whoamiCtx([], { extraPositional: "nope" }));
+    expect(exit).toBe(1);
+    expect(stderrBuf.join("\n")).toContain('Unknown environment "nope"');
+  });
+
+  test("one row per configured lexicon, and --json emits the same rows", async () => {
+    const plugins: LexiconPlugin[] = [
+      awsIdentity,
+      createMockPlugin({
+        name: "k8s",
+        describeIdentity: async () => ({ unresolved: { reason: "no-binding", detail: "no context" } }),
+      }),
+      createMockPlugin({ name: "github" }),
+    ];
+
+    expect(await runLifecycleWhoami(whoamiCtx(plugins))).toBe(0);
+    const table = stdoutBuf.join("\n");
+    expect(table).toContain("arn:aws:sts::491500000000:assumed-role/deploy/ci");
+    expect(table).toContain("k8s");
+    expect(table).toContain("github");
+
+    stdoutBuf.length = 0;
+    expect(await runLifecycleWhoami(whoamiCtx(plugins, { json: true }))).toBe(0);
+    const parsed = JSON.parse(stdoutBuf.join("\n")) as {
+      environment: string;
+      identities: Array<{ lexicon: string; status: string; identity?: string; reason?: string }>;
+    };
+    expect(parsed.environment).toBe("prod");
+    expect(parsed.identities.map((r) => [r.lexicon, r.status])).toEqual([
+      ["aws", "reported"],
+      ["k8s", "unresolved"],
+      ["github", "not-reported"],
+    ]);
+    expect(parsed.identities[1].reason).toBe("no-binding");
+  });
+
+  test("a lexicon that implements nothing reads as 'not reported', never an empty identity", async () => {
+    const exit = await runLifecycleWhoami(whoamiCtx([createMockPlugin({ name: "helm" })]));
+    expect(exit).toBe(0);
+    expect(stdoutBuf.join("\n")).toContain("not reported");
+  });
+
+  test("an unresolved identity exits 0 by default and nonzero only under --strict", async () => {
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "aws",
+        describeIdentity: async () => ({ unresolved: { reason: "no-credentials" } }),
+      }),
+    ];
+    expect(await runLifecycleWhoami(whoamiCtx(plugins))).toBe(0);
+    expect(await runLifecycleWhoami(whoamiCtx(plugins, { strict: true }))).toBe(1);
+  });
+
+  test("--strict does not fail on a lexicon that simply does not implement the capability", async () => {
+    const exit = await runLifecycleWhoami(whoamiCtx([createMockPlugin({ name: "github" })], { strict: true }));
+    expect(exit).toBe(0);
+  });
+
+  test("the positional lexicon filter narrows the report", async () => {
+    const plugins: LexiconPlugin[] = [awsIdentity, createMockPlugin({ name: "k8s" })];
+    expect(await runLifecycleWhoami(whoamiCtx(plugins, { extraPositional2: "aws", json: true }))).toBe(0);
+    const parsed = JSON.parse(stdoutBuf.join("\n")) as { identities: Array<{ lexicon: string }> };
+    expect(parsed.identities.map((r) => r.lexicon)).toEqual(["aws"]);
+  });
+
+  test("an unconfigured lexicon filter → exit 1", async () => {
+    const exit = await runLifecycleWhoami(whoamiCtx([awsIdentity], { extraPositional2: "gcp" }));
+    expect(exit).toBe(1);
+    expect(stderrBuf.join("\n")).toContain('Lexicon "gcp" is not configured');
+  });
+
+  test("the environment's declared endpoint is applied for the identity query, exactly as for a live read", async () => {
+    // #1166 parity: without this, whoami reports the identity of real AWS
+    // while `describeResources` reads the emulator — the wrong-target answer
+    // this command exists to surface.
+    loadChantConfigMock.mockResolvedValue({
+      config: { environments: [{ name: "prod", endpoint: "http://localhost:4566" }] },
+    });
+    let seenEndpoint: string | undefined;
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "aws",
+        emulator: awsEmulatorStub,
+        describeIdentity: async () => {
+          seenEndpoint = process.env.AWS_ENDPOINT_URL;
+          return { identity: "arn:x", scope: "s", source: "env" };
+        },
+      }),
+    ];
+    expect(await runLifecycleWhoami(whoamiCtx(plugins))).toBe(0);
+    expect(seenEndpoint).toBe("http://localhost:4566");
+    // Restored after the call, so it never leaks into a later invocation.
+    expect(process.env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("a single declared stack region is handed to the lexicon; disagreeing regions are not guessed", async () => {
+    const seen: Array<string | undefined> = [];
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeIdentity: async (options) => {
+        seen.push(options.region);
+        return { identity: "arn:x", scope: "s", source: "env" };
+      },
+    });
+    loadChantConfigMock.mockResolvedValue({
+      config: { environments: ["prod"], stacks: [{ name: "a", src: "src/a", region: "eu-west-1" }] },
+    });
+    await runLifecycleWhoami(whoamiCtx([plugin]));
+    loadChantConfigMock.mockResolvedValue({
+      config: {
+        environments: ["prod"],
+        stacks: [
+          { name: "a", src: "src/a", region: "eu-west-1" },
+          { name: "b", src: "src/b", region: "us-east-1" },
+        ],
+      },
+    });
+    await runLifecycleWhoami(whoamiCtx([plugin]));
+    expect(seen).toEqual(["eu-west-1", undefined]);
+  });
+
+  test("no credential value survives into the rendered rows", async () => {
+    process.env.CHANT_TEST_API_TOKEN = "tok_averyrealtokenvalue";
+    try {
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          describeIdentity: async () => ({
+            identity: "arn:aws:iam::1:user/ci",
+            scope: "us-east-1",
+            source: "tok_averyrealtokenvalue",
+          }),
+        }),
+      ];
+      expect(await runLifecycleWhoami(whoamiCtx(plugins, { json: true }))).toBe(0);
+      expect(stdoutBuf.join("\n")).not.toContain("tok_averyrealtokenvalue");
+      expect(stdoutBuf.join("\n")).toContain("[redacted]");
+    } finally {
+      delete process.env.CHANT_TEST_API_TOKEN;
+    }
+  });
+});

package/src/cli/handlers/lifecycle.ts

@@ -30,6 +30,7 @@ import {
   type NormalizedObservation,
   type UnobservedEntity,
 } from "../../observation";
+import { describeIdentities, identityStatusText, type IdentityRow } from "../../identity";
 import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 import { affectedStacks } from "../../lifecycle/affected";
@@ -1583,13 +1584,136 @@ export async function runLifecycleLog(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * The region core hands `describeIdentity` — the one the environment's stacks
+ * declare, when they declare exactly one (#1261's `stacks[].region`).
+ *
+ * Stacks that declare none, or that disagree, resolve to `undefined`, and the
+ * lexicon then resolves the region its own read path would. Guessing one of
+ * several would report a binding half the estate does not use, which is the
+ * failure this command exists to prevent.
+ */
+function singleDeclaredRegion(targets: readonly StackTarget[]): string | undefined {
+  const regions = new Set(targets.map((t) => t.region).filter((r): r is string => Boolean(r)));
+  return regions.size === 1 ? [...regions][0] : undefined;
+}
+
+/**
+ * chant lifecycle whoami <environment> [lexicon] [--json] [--strict]
+ *
+ * Read-only pre-flight (#1982): who chant would act as in each configured
+ * lexicon, and what that principal is scoped to, before it acts. Never
+ * mutates, never gates — `--strict` is the only way this exits non-zero on an
+ * unresolved row, and a lexicon that answers for nothing is reported as such
+ * rather than as an empty identity.
+ */
+export async function runLifecycleWhoami(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+
+  if (!environment) {
+    console.error(formatError({
+      message: "Environment is required: chant lifecycle whoami <environment> [lexicon] [--json] [--strict]",
+    }));
+    return 1;
+  }
+
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath);
+  const declaredEnvNames = environmentNames(config.environments);
+  if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
+    console.error(formatError({
+      message: `Unknown environment "${environment}"`,
+      hint: `Defined environments: ${declaredEnvNames.join(", ")}`,
+    }));
+    return 1;
+  }
+
+  const targetPlugins = lexiconFilter ? plugins.filter((p) => p.name === lexiconFilter) : plugins;
+  if (targetPlugins.length === 0) {
+    console.error(formatError({
+      message: `Lexicon "${lexiconFilter}" is not configured for this project`,
+      hint: `Configured: ${plugins.map((p) => p.name).join(", ") || "(none)"}`,
+    }));
+    return 1;
+  }
+
+  // The environment's declared endpoint applies here exactly as it does to a
+  // `--live` read (#1166). Without it whoami would report the identity of real
+  // AWS while `describeResources` reads the emulator — the wrong-target answer
+  // this command exists to make visible.
+  const endpointResult = applyLiveEndpoint(config.environments, environment, targetPlugins);
+  if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
+
+  const region = singleDeclaredRegion(resolveStackTargets(args, config));
+  let rows: IdentityRow[];
+  try {
+    rows = await describeIdentities(targetPlugins, {
+      environment,
+      ...(region ? { region } : {}),
+      cwd: projectPath,
+    });
+  } finally {
+    endpointResult.restore();
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({ environment, identities: rows }, null, 2));
+  } else {
+    printIdentityTable(rows);
+  }
+
+  // Never a gate by default: an unresolved identity is a report, and a
+  // pre-flight command that fails the build has stopped being pre-flight.
+  const unresolved = rows.filter((r) => r.status === "unresolved");
+  if (args.strict && unresolved.length > 0) {
+    console.error(formatError({
+      message: `--strict: ${unresolved.length} lexicon(s) could not resolve an identity: ${unresolved.map((r) => r.lexicon).join(", ")}`,
+    }));
+    return 1;
+  }
+  return 0;
+}
+
+function printIdentityTable(rows: IdentityRow[]): void {
+  if (rows.length === 0) {
+    console.error(formatWarning({ message: "No lexicons are configured for this project" }));
+    return;
+  }
+  const width = (pick: (r: IdentityRow) => string): number =>
+    Math.max(...rows.map((r) => pick(r).length));
+  const lexWidth = Math.max(width((r) => r.lexicon), "LEXICON".length);
+  const idWidth = Math.max(width((r) => r.identity ?? identityStatusText(r)), "IDENTITY".length);
+  const scopeWidth = Math.max(width((r) => r.scope ?? ""), "SCOPE".length);
+
+  console.log(
+    "LEXICON".padEnd(lexWidth + 2) + "IDENTITY".padEnd(idWidth + 2) + "SCOPE".padEnd(scopeWidth + 2) + "SOURCE",
+  );
+  for (const row of rows) {
+    const identity = row.status === "reported" ? (row.identity ?? "") : identityStatusText(row);
+    console.log(
+      row.lexicon.padEnd(lexWidth + 2) +
+        identity.padEnd(idWidth + 2) +
+        (row.scope ?? "").padEnd(scopeWidth + 2) +
+        (row.source ?? ""),
+    );
+  }
+  // The resolved address and the reason's detail are both sentences, so they
+  // go under the table rather than widening a column every row pays for.
+  for (const row of rows) {
+    if (row.endpoint) console.error(`  ${row.lexicon}: resolved endpoint ${row.endpoint}`);
+    if (row.detail) console.error(`  ${row.lexicon}: ${row.detail}`);
+  }
+}
+
 /**
  * Fallback for unknown state subcommands.
  */
 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 teardown, chant lifecycle log",
+    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle whoami, chant lifecycle teardown, chant lifecycle log",
   }));
   return 1;
 }

package/src/cli/handlers/op-progress.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect } from "vitest";
-import { extractStepRecords, countActivities, queryGateState } from "./op-progress";
+import { extractStepRecords, extractIndexedStepRecords, stepRecordEmitter, countActivities, queryGateState } from "./op-progress";
+import type { StepRecord } from "../../op/local-executor";
 import type { OpConfig } from "../../op/types";
 import type { EffectReceiptRef } from "../../op/receipt-store";
 import type { WorkflowHistoryRaw, HistoryEvent } from "./run-client";
@@ -171,6 +172,71 @@ describe("extractStepRecords", () => {
   });
 });
 
+describe("stepRecordEmitter", () => {
+  // chant #2032. Declared order is main phases then `onFailure` reversed, so an
+  // unreached main phase sits *before* an `onFailure` phase that ran. The live
+  // poll therefore returns [Main(fail), Comp(ok)] and the terminal `final: true`
+  // pass returns [Main(fail), Never(skipped), Comp(ok)] — an insertion, not an
+  // append. The old emitted-count watermark sliced at 2 and re-shipped Comp
+  // while dropping Never entirely. The #1676 coverage above misses this because
+  // in those configs the skipped record lands last, where insert and append are
+  // the same operation.
+  const config: OpConfig = {
+    name: "op", overview: "o",
+    phases: [
+      { name: "Main", steps: [{ kind: "activity", fn: "boom" }] },
+      { name: "Never", steps: [{ kind: "activity", fn: "never" }] },
+    ],
+    onFailure: [{ name: "Comp", steps: [{ kind: "activity", fn: "comp" }] }],
+  };
+  // Main fails, Never is never reached, compensation runs and succeeds.
+  const history: WorkflowHistoryRaw = {
+    events: [
+      scheduled("1", "boom", sec(0)),
+      failed("1", sec(1), "boom"),
+      scheduled("2", "comp", sec(2)),
+      completed("2", sec(3)),
+    ],
+  };
+
+  const MAIN: StepRecord = { phase: "Main", fn: "boom", status: "fail", durationMs: 1000, error: "boom" };
+  const NEVER: StepRecord = { phase: "Never", fn: "never", status: "skipped", durationMs: 0 };
+  const COMP: StepRecord = { phase: "Comp", fn: "comp", status: "ok", durationMs: 1000 };
+
+  test("the final pass inserts rather than appends, so list position is not an identity", () => {
+    expect(extractIndexedStepRecords(config, history)).toEqual([
+      { index: 0, record: MAIN },
+      { index: 2, record: COMP },
+    ]);
+    expect(extractIndexedStepRecords(config, history, { final: true })).toEqual([
+      { index: 0, record: MAIN },
+      { index: 1, record: NEVER },
+      { index: 2, record: COMP },
+    ]);
+  });
+
+  test("each record ships exactly once across the poll passes and the final pass", () => {
+    const emitted: StepRecord[] = [];
+    const emit = stepRecordEmitter((r) => emitted.push(r));
+
+    emit(extractIndexedStepRecords(config, history)); // a poll while the workflow closes
+    emit(extractIndexedStepRecords(config, history)); // an identical re-poll adds nothing
+    emit(extractIndexedStepRecords(config, history, { final: true }));
+
+    expect(emitted).toEqual([MAIN, COMP, NEVER]);
+  });
+
+  test("an empty first poll does not shift what a later pass ships", () => {
+    const emitted: StepRecord[] = [];
+    const emit = stepRecordEmitter((r) => emitted.push(r));
+
+    emit(extractIndexedStepRecords(config, { events: [] }));
+    expect(emitted).toEqual([]);
+    emit(extractIndexedStepRecords(config, history, { final: true }));
+    expect(emitted).toEqual([MAIN, NEVER, COMP]);
+  });
+});
+
 describe("countActivities", () => {
   test("counts scheduled and completed events", () => {
     const history: WorkflowHistoryRaw = {

package/src/cli/handlers/op-progress.ts

@@ -113,34 +113,55 @@ function terminalOutcomes(events: HistoryEvent[]): Map<string, TerminalOutcome>
   return out;
 }
 
+/**
+ * A step record paired with the position of the declared step it came from.
+ *
+ * `index` is an offset into `declaredStepOrder(config)`, which depends only
+ * on the Op config — not on the history — so it is the record's identity
+ * and is stable across polls. The record *list* is not: a mid-run poll omits
+ * every step that hasn't settled yet, and the terminal `final: true` pass
+ * inserts a `"skipped"` record at each such step's declared position, which
+ * shifts every later record's list offset (chant #2032). Anything tracking
+ * what it has already seen must key on `index`, never on how many records
+ * the previous call returned.
+ */
+export interface IndexedStepRecord {
+  index: number;
+  record: StepRecord;
+}
+
 /**
  * Reconstruct per-step progress records from a workflow's history, in
- * declared order. Only settled steps (matched to a scheduled event that has
- * since completed or failed) produce a record — a step that hasn't been
- * scheduled yet simply isn't in the result, so a live poll only ever
- * appends. Pass `final: true` once the workflow has reached a terminal
+ * declared order, each tagged with its declared-step `index`. Only settled
+ * steps (matched to a scheduled event that has since completed or failed)
+ * produce a record — a step that hasn't been scheduled yet simply isn't in
+ * the result. Pass `final: true` once the workflow has reached a terminal
  * status to also emit a `"skipped"` record for every declared step that
  * never got a matching scheduled event (an untaken effect branch, or an
  * `onFailure` phase on a run that succeeded) — never before, or a
  * still-running Op would show its not-yet-reached steps as skipped.
  */
-export function extractStepRecords(
+export function extractIndexedStepRecords(
   config: OpConfig,
   history: WorkflowHistoryRaw,
   opts: { final?: boolean } = {},
-): StepRecord[] {
+): IndexedStepRecord[] {
   const events = history.events ?? [];
   const queues = scheduledQueues(events);
   const terminals = terminalOutcomes(events);
   const nextIndex = new Map<string, number>();
 
-  const records: StepRecord[] = [];
-  for (const step of declaredStepOrder(config)) {
+  const records: IndexedStepRecord[] = [];
+  const declared = declaredStepOrder(config);
+  for (let index = 0; index < declared.length; index++) {
+    const step = declared[index];
     const queue = queues.get(step.fn);
     const idx = nextIndex.get(step.fn) ?? 0;
     const entry = queue?.[idx];
     if (!entry) {
-      if (opts.final) records.push({ phase: step.phase, fn: step.fn, status: "skipped", durationMs: 0 });
+      if (opts.final) {
+        records.push({ index, record: { phase: step.phase, fn: step.fn, status: "skipped", durationMs: 0 } });
+      }
       continue;
     }
     nextIndex.set(step.fn, idx + 1);
@@ -151,16 +172,51 @@ export function extractStepRecords(
     const durationMs =
       entry.scheduledAt && terminal.at ? terminal.at.getTime() - entry.scheduledAt.getTime() : 0;
     records.push({
-      phase: step.phase,
-      fn: step.fn,
-      status: terminal.status,
-      durationMs,
-      ...(terminal.error ? { error: terminal.error } : {}),
+      index,
+      record: {
+        phase: step.phase,
+        fn: step.fn,
+        status: terminal.status,
+        durationMs,
+        ...(terminal.error ? { error: terminal.error } : {}),
+      },
     });
   }
   return records;
 }
 
+/** `extractIndexedStepRecords` without the indices — the plain declared-order record list. */
+export function extractStepRecords(
+  config: OpConfig,
+  history: WorkflowHistoryRaw,
+  opts: { final?: boolean } = {},
+): StepRecord[] {
+  return extractIndexedStepRecords(config, history, opts).map((r) => r.record);
+}
+
+/**
+ * A sink that forwards each declared step's record exactly once, however many
+ * times the poll loop re-derives the list.
+ *
+ * `--progress-json` calls this per poll with the whole list so far, plus once
+ * more with the terminal `final: true` list. Deduplicating by declared-step
+ * `index` is what makes that safe: an emitted-count watermark assumed the list
+ * was append-only, and the `final` pass's inserted `"skipped"` records break
+ * that assumption — with an unreached phase declared before an `onFailure`
+ * phase that ran, the insertion shifted the tail, so the last record shipped
+ * twice and the skipped one never shipped at all (chant #2032).
+ */
+export function stepRecordEmitter(emit: (record: StepRecord) => void): (records: IndexedStepRecord[]) => void {
+  const seen = new Set<number>();
+  return (records) => {
+    for (const { index, record } of records) {
+      if (seen.has(index)) continue;
+      seen.add(index);
+      emit(record);
+    }
+  };
+}
+
 /** `{completed, scheduled}` activity counts for the summary line `chant run status`/`op-status` show alongside the full record list. */
 export function countActivities(history: WorkflowHistoryRaw): { completed: number; scheduled: number } {
   const events = history.events ?? [];