@intentius/chant 0.118.0 → 0.120.0

package/src/op/activities/converge-push.test.ts

@@ -20,11 +20,13 @@ vi.mock("node:child_process", () => ({
     cb(null, { stdout: execMock(cmd) as string, stderr: "" }),
 }));
 
-const pushLifecycle = vi.fn();
+// The outcomes `pushLifecycleReport` maps git's push status to (#3677).
+const pushLifecycleReport = vi.fn();
 vi.mock("../../lifecycle/git", () => ({
   fetchLifecycle: vi.fn(async () => undefined),
-  pushLifecycle: (...args: unknown[]) => pushLifecycle(...args) as Promise<boolean>,
+  pushLifecycleReport: (...args: unknown[]) => pushLifecycleReport(...args),
 }));
+const { LIFECYCLE_LOCAL_NOTE } = await import("../../lifecycle/local-note");
 
 vi.mock("../../lifecycle/converge-ledger", async (orig) => {
   const actual = (await orig()) as Record<string, unknown>;
@@ -55,7 +57,7 @@ describe("a converge tick reports its push outcome (chant#2337)", () => {
   });
 
   test("a push that lands reports pushed, with no warning", async () => {
-    pushLifecycle.mockResolvedValue(true);
+    pushLifecycleReport.mockResolvedValue({ pushed: true });
 
     const result = await tick();
 
@@ -66,7 +68,7 @@ describe("a converge tick reports its push outcome (chant#2337)", () => {
   test("a REJECTED push is reported, not swallowed", async () => {
     // Red before chant#2337: `.catch(() => undefined)` meant the tick returned
     // the same shape whether or not the record left the machine.
-    pushLifecycle.mockRejectedValue(new Error("remote rejected: chant/lifecycle has moved"));
+    pushLifecycleReport.mockResolvedValue({ pushed: false, pushWarning: "remote rejected: chant/lifecycle has moved" });
 
     const result = await tick();
 
@@ -78,7 +80,7 @@ describe("a converge tick reports its push outcome (chant#2337)", () => {
     // `pushLifecycle` returns false rather than throwing when there is no
     // remote. That is not an error, but it is not a push either, and the two
     // reasons are worth telling apart in the warning.
-    pushLifecycle.mockResolvedValue(false);
+    pushLifecycleReport.mockResolvedValue({ pushed: false, pushWarning: LIFECYCLE_LOCAL_NOTE });
 
     const result = await tick();
 
@@ -90,7 +92,7 @@ describe("a converge tick reports its push outcome (chant#2337)", () => {
     // The append is local-first and always lands. A push failure must not make
     // the tick misreport what it observed, or the fix would have traded one
     // wrong answer for another.
-    pushLifecycle.mockRejectedValue(new Error("nope"));
+    pushLifecycleReport.mockResolvedValue({ pushed: false, pushWarning: "nope" });
 
     const result = await tick();
 

package/src/op/activities/converge.ts

@@ -58,7 +58,7 @@ import {
   type ConvergeTickRecord,
 } from "../../lifecycle/converge-ledger";
 import { resolveApprovalUrl } from "../../lifecycle/gate-ledger";
-import { fetchLifecycle, pushLifecycle } from "../../lifecycle/git";
+import { fetchLifecycle, pushLifecycleReport } from "../../lifecycle/git";
 import type { ChangeSet } from "../../lifecycle/change-set";
 import type { ComponentStatusRow } from "../../lifecycle/status";
 
@@ -535,12 +535,7 @@ async function dispatchPlanned(
 
 /** Push the tick's ledger record, and say whether it reached the remote (chant#2337). */
 async function pushTick(): Promise<{ pushed: boolean; pushWarning?: string }> {
-  try {
-    const pushed = await pushLifecycle();
-    return pushed ? { pushed } : { pushed, pushWarning: "no remote is configured for chant/lifecycle — the tick record was recorded locally only" };
-  } catch (err) {
-    return { pushed: false, pushWarning: err instanceof Error ? err.message : String(err) };
-  }
+  return pushLifecycleReport();
 }
 
 /** A tick of a ConvergeOp with an observer step (#2778): the observation is already in `args.observed`. */

package/src/op/activities/lifecycle-gate.test.ts

@@ -0,0 +1,147 @@
+/**
+ * #3712: a `chant lifecycle diff` that fails yields no digest, so an approval
+ * cannot pass a gate for a plan nobody read.
+ *
+ * Before the fix the activity caught the diff's non-zero exit and digested
+ * its error output. Every run whose build failed printed the same lines, so
+ * an approval of one such run's digest matched the next, whatever the
+ * declarations had become, and the Apply phase (which builds on its own)
+ * applied the change.
+ */
+
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+/** What the next `chant lifecycle diff` prints and how it exits. */
+const next = { stdout: "", stderr: "", code: 0 };
+
+vi.mock(import("node:child_process"), async (importOriginal) => ({
+  ...(await importOriginal()),
+  exec: ((_command: string, _options: unknown, callback: (err: unknown, out?: { stdout: string; stderr: string }) => void) => {
+    if (next.code === 0) callback(null, { stdout: next.stdout, stderr: next.stderr });
+    else callback(Object.assign(new Error("exit"), { code: next.code, stdout: next.stdout, stderr: next.stderr }));
+  }) as never,
+}));
+
+const { lifecycleDiff, lifecycleDiffDigest } = await import("./lifecycle");
+const { OpRunFailure, runOpLocally } = await import("../local-executor");
+const { stepOutput } = await import("../step-output-ref");
+type ActivityFn = import("../activity-registry").ActivityFn;
+type ActivityProfile = import("../activity-registry").ActivityProfile;
+type GateLedgerPort = import("../gate").GateLedgerPort;
+type GateResolutionRecord = import("../../lifecycle/gate-ledger").GateResolutionRecord;
+type PendingGateRecord = import("../../lifecycle/gate-ledger").PendingGateRecord;
+type OpConfig = import("../types").OpConfig;
+
+const PROFILES: Record<string, ActivityProfile> = {
+  fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } },
+};
+
+const BUILD_FAILED = "error: Build failed for project — fix errors before diffing";
+const ARGS = { env: "dev", live: true };
+
+function failDiff(): void {
+  Object.assign(next, { stdout: "", stderr: BUILD_FAILED, code: 1 });
+}
+
+function diffPrints(render: string): void {
+  Object.assign(next, { stdout: render, stderr: "", code: 0 });
+}
+
+beforeEach(() => {
+  diffPrints("");
+  vi.spyOn(console, "log").mockImplementation(() => undefined);
+  vi.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+describe("lifecycleDiff on a failed diff (#3712)", () => {
+  test("a build error rejects, naming the command and the error, with no digest", async () => {
+    failDiff();
+    await expect(lifecycleDiff(ARGS)).rejects.toThrow(/chant lifecycle diff dev --live failed \(exit 1\); no plan to digest:\n.*Build failed for project/);
+  });
+
+  test("a diff that succeeds still returns its digest", async () => {
+    diffPrints("MISSING (declared, provider reports not in cloud):\n  - events");
+    const result = await lifecycleDiff(ARGS);
+    expect(result.exitCode).toBe(0);
+    expect(result.drifted).toBe(true);
+    expect(result.planDigest).toBe(lifecycleDiffDigest(ARGS, "MISSING (declared, provider reports not in cloud):\n  - events"));
+  });
+});
+
+describe("ApplyOp's gate over a diff whose build fails (#3712)", () => {
+  function ledger(): GateLedgerPort & { approve(planDigest: string): void } {
+    const resolutions: GateResolutionRecord[] = [];
+    const pending: PendingGateRecord[] = [];
+    return {
+      approve(planDigest) {
+        resolutions.push({ version: 1, op: "apply-dev", gate: "approve-apply-dev", resolvedBy: "alex", timestamp: "2026-10-10T12:05:00.000Z", planDigest });
+      },
+      async read() {
+        return { resolutions: [...resolutions], pending: [...pending] };
+      },
+      async appendPending(input) {
+        const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+        pending.push(record);
+        return { record, pushed: true };
+      },
+    };
+  }
+
+  const statuses = (failure: unknown) =>
+    (failure as InstanceType<typeof OpRunFailure>).result.records.map((r) => [r.fn, r.status]);
+
+  /** ApplyOp's Plan, Approve and Apply phases, with the real `lifecycleDiff` and an apply that records what it applied. */
+  function harness() {
+    const declared = { schema: "A" };
+    const applied: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["lifecycleDiff", (args, signal) => lifecycleDiff(args as { env: string; live?: boolean }, signal)],
+      ["nativeApply", async () => {
+        applied.push(declared.schema);
+      }],
+    ]);
+    const config: OpConfig = {
+      name: "apply-dev",
+      overview: "",
+      phases: [
+        { name: "Plan", steps: [{ kind: "activity", fn: "lifecycleDiff", id: "plan", args: ARGS }] },
+        { name: "Approve", steps: [{ kind: "gate", gate: "approve-apply-dev", plan: stepOutput("plan", "planDigest") }] },
+        { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply" }] },
+      ],
+    };
+    return { declared, applied, activities, config };
+  }
+
+  test("an approval of plan A does not pass for plan B when the diff's build fails both times", async () => {
+    const { declared, applied, activities, config } = harness();
+    const gates = ledger();
+
+    // Plan A: the diff's build fails. The run stops at Plan: nothing reaches the gate.
+    failDiff();
+    const first = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-10-10T12:00:00.000Z" }).catch((e: unknown) => e);
+    expect(first).toBeInstanceOf(OpRunFailure);
+    expect(statuses(first)).toEqual([["lifecycleDiff", "fail"]]);
+    expect(applied).toEqual([]);
+
+    // The digest the diff's error output used to give: someone approves it.
+    gates.approve(lifecycleDiffDigest(ARGS, BUILD_FAILED));
+
+    // Plan B: the declarations change, and the diff's build still fails.
+    declared.schema = "B";
+    const second = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-10-10T12:10:00.000Z" }).catch((e: unknown) => e);
+    expect(second).toBeInstanceOf(OpRunFailure);
+    expect(statuses(second)).toEqual([["lifecycleDiff", "fail"]]);
+    expect(applied).toEqual([]);
+  });
+
+  test("with the build fixed, the run stops at the gate for the plan it read", async () => {
+    const { applied, activities, config } = harness();
+    const gates = ledger();
+    const render = "MISSING (declared, provider reports not in cloud):\n  - events";
+    diffPrints(render);
+    const run = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-10-10T12:00:00.000Z" });
+    expect(run.status).toBe("gated");
+    expect(run.gate?.planDigest).toBe(lifecycleDiffDigest(ARGS, render));
+    expect(applied).toEqual([]);
+  });
+});

package/src/op/activities/lifecycle.test.ts

@@ -28,6 +28,11 @@ describe("detectDrift", () => {
     expect(detectDrift(MISSING)).toBe(true);
   });
 
+  test("a privilege an apply would revoke is drift (PENDING, #3706)", () => {
+    const pending = `${HEAD}0 missing, 0 orphan, 0 disappeared, 0 newly observed, 0 drifted, 3 unchanged\n${"-".repeat(80)}\n\n${BOLD}sql (properties)${RESET}\n0 property drift across 0 resource(s), 0 accepted, 2 unchanged, 1 pending\n${"-".repeat(80)}\n${BOLD}\nPENDING (changes an apply would make that no declared property shows):${RESET}\n  ~ relation app.orders TO writer: REVOKE INSERT ON TABLE app.orders FROM writer`;
+    expect(detectDrift(pending)).toBe(true);
+  });
+
   test("the counts line alone, lower case, is not drift", () => {
     expect(detectDrift("1 property drift across 1 resource(s)")).toBe(false);
   });

package/src/op/activities/lifecycle.ts

@@ -32,7 +32,7 @@ export interface LifecycleDiffArgs {
 export interface LifecycleDiffResult {
   /** Combined stdout + stderr from the chant command. */
   output: string;
-  /** Process exit code (0 = success). */
+  /** Process exit code: always 0, since a diff that exits non-zero throws (#3712). */
   exitCode: number;
   /**
    * True when the diff output contains any drift indicators
@@ -88,6 +88,9 @@ const DRIFT_HEADERS = [
   // An owned resource whose live properties differ from its declaration (the
   // deep read): a sql table's TTL changed out of band, say (#3642).
   "PROPERTY DRIFT",
+  // A change an apply would make that no declared property shows: a
+  // privilege granted by hand on a Postgres table (#3706).
+  "PENDING",
   "ARTIFACTS ADDED",
   "ARTIFACTS REMOVED",
   "ARTIFACTS CHANGED",
@@ -121,18 +124,27 @@ export function lifecycleDiffDigest(args: LifecycleDiffArgs, output: string): st
  * MISSING / ORPHAN / DRIFTED / DISAPPEARED / PROPERTY DRIFT section headers documented in
  * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
  * on a WatchOp activity step to surface drift as the run's `Drift` outcome.
+ *
+ * A diff that exits non-zero (#3712) fails the step and yields no digest.
+ * Its output is an error, not a change set: every failed run printed the
+ * same lines, so a digest over them was one an approval matched whatever
+ * the declarations had become since.
  */
 export async function lifecycleDiff(args: LifecycleDiffArgs, signal?: AbortSignal): Promise<LifecycleDiffResult> {
   const liveFlag = args.live ? " --live" : "";
+  const command = `chant lifecycle diff ${args.env}${liveFlag}`;
+  let stdout: string;
+  let stderr: string;
   try {
-    const { stdout, stderr } = await execAsync(`chant lifecycle diff ${args.env}${liveFlag}`, { signal });
-    const output = `${stdout}${stderr}`.trim();
-    if (output) console.log(output);
-    return { output, exitCode: 0, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
+    ({ stdout, stderr } = await execAsync(command, { signal }));
   } catch (err) {
     const e = err as { code?: number; stdout?: string; stderr?: string };
     const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
     if (output) console.error(output);
-    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
+    const message = `${command} failed (exit ${String(e.code ?? 1)}); no plan to digest${output ? `:\n${output}` : ""}`;
+    throw new Error(message);
   }
+  const output = `${stdout}${stderr}`.trim();
+  if (output) console.log(output);
+  return { output, exitCode: 0, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
 }

package/src/op/composites/composites.test.ts

@@ -25,6 +25,11 @@ function getEntityType(entity: unknown): string {
 // ── WatchOp ──────────────────────────────────────────────────────────
 
 describe("WatchOp: shape", () => {
+  test("failOn: \"drift\" rides on the op; omitted, the op has none (#3675)", () => {
+    expect(getProps(WatchOp({ name: "w", env: "prod", failOn: "drift" }).op).failOn).toBe("drift");
+    expect(getProps(WatchOp({ name: "w", env: "prod" }).op)).not.toHaveProperty("failOn");
+  });
+
   test("returns { op } — the cadence is on the op, not a second resource (#2120)", () => {
     const result = WatchOp({ name: "prod-watch", env: "prod", schedule: "*/15 * * * *" });
     expect(result.op).toBeDefined();

package/src/op/composites/watch-op.ts

@@ -55,6 +55,14 @@ export interface WatchOpConfig {
    * a receipt — the `effect()` step is the sole writer.
    */
   receipts?: EffectReceiptDeclaration[];
+  /**
+   * `"drift"` makes `chant run <name>` exit 2 when the watch finds drift
+   * (#3675), so a scheduled drift job fails without a wrapper that reads the
+   * run ledger. Omitted, a run that finds drift still exits 0 and records
+   * `Drift=true`; `chant run <name> --fail-on-drift` asks for the same exit
+   * code on one invocation.
+   */
+  failOn?: "drift";
 }
 
 export interface WatchOpResources {
@@ -73,6 +81,7 @@ export function WatchOp(config: WatchOpConfig): WatchOpResources {
       Env: config.env,
     },
     ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    ...(config.failOn ? { failOn: config.failOn } : {}),
     phases: [
       phase("Snapshot", [activity("lifecycleSnapshot", { env: config.env })]),
       phase("Diff", [

package/src/op/emulator-lifecycle.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect } from "vitest";
-import { emulatorLifecycle } from "./emulator-lifecycle";
+import { createServer } from "node:net";
+import { emulatorLifecycle, hostPortInUse } from "./emulator-lifecycle";
 
 describe("emulatorLifecycle command builders", () => {
   const emu = emulatorLifecycle({
@@ -62,3 +63,14 @@ describe("an emulator reached by its own client, not over HTTP", () => {
     expect(() => emulatorLifecycle({ name: "x", image: "x:1", containerPort: 1 })).toThrow(/neither a healthPath nor a readyCommand/);
   });
 });
+
+describe("hostPortInUse (#3673)", () => {
+  test("is true while a process listens on 127.0.0.1:<port>, false once it stops", async () => {
+    const server = createServer();
+    await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+    const { port } = server.address() as { port: number };
+    expect(await hostPortInUse(port)).toBe(true);
+    await new Promise<void>((r) => server.close(() => r()));
+    expect(await hostPortInUse(port)).toBe(false);
+  });
+});

package/src/op/emulator-lifecycle.ts

@@ -1,4 +1,5 @@
 import { exec } from "node:child_process";
+import { connect } from "node:net";
 import { promisify } from "node:util";
 import { sleep } from "./activity-runtime";
 
@@ -53,6 +54,47 @@ export interface EmulatorSpec {
     /** `owner/repo` whose latest GitHub release names the current version. */
     repo: string;
   };
+  /**
+   * How to tell this emulator's server from another one answering on the
+   * same host port (#3673).
+   *
+   * On macOS, Docker publishes `0.0.0.0:<port>` even while a native server
+   * holds `127.0.0.1:<port>`, and `localhost` then reaches the native one.
+   * `chant emulator status` runs {@link EmulatorIdentity.command} in the
+   * container and {@link EmulatorIdentity.probe} through the printed endpoint,
+   * and reports a mismatch instead of an endpoint that reaches the wrong server.
+   */
+  identity?: EmulatorIdentity;
+  /** How a client signs in, for `chant emulator --help` (e.g. `user postgres, password chant`). */
+  credentials?: string;
+}
+
+/** A server identity check: one value read inside the container and through the endpoint (#3673). */
+export interface EmulatorIdentity {
+  /** What kind of server it is, for messages: `Postgres`, `ClickHouse`. */
+  server: string;
+  /** Run as `docker exec <name> <command...>`; its trimmed stdout is the server's identity. */
+  command: readonly string[];
+  /** The identity of the server answering at `endpoint`, and a label for it (e.g. `PostgreSQL 16.14`). */
+  probe(endpoint: string): Promise<{ id: string; label: string }>;
+}
+
+/**
+ * True when something accepts TCP connections on 127.0.0.1:`port` (#3673).
+ * `up` asks before `docker run`: a native server there would take every
+ * `localhost` connection meant for the emulator.
+ */
+export function hostPortInUse(port: number, timeoutMs = 1_000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: "127.0.0.1", port });
+    const done = (inUse: boolean): void => {
+      socket.destroy();
+      resolve(inUse);
+    };
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once("connect", () => done(true));
+    socket.once("error", () => done(false));
+  });
 }
 
 /**
@@ -194,6 +236,12 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
       // clean JSON on stdout. runOp/Op activities capture both streams regardless.
       console.error(`emulator container "${name}" already running — reusing`);
     } else {
+      if (await hostPortInUse(port)) {
+        throw new Error(
+          `emulator "${name}": 127.0.0.1:${port} is already held by another process, so localhost:${port} would not reach the emulator. ` +
+            `Stop that process, or publish the emulator on another port (chant emulator up --port ${spec.containerPort}=<free port>).`,
+        );
+      }
       await execAsync(runCommand({ ...args, name, port }), { signal });
     }
 

package/src/op/gate-summary.test.ts

@@ -44,6 +44,12 @@ describe("gatedRunSummaryMarkdown (#2243)", () => {
     expect(md).toContain("cannot see it to approve it");
   });
 
+  test("says it was recorded locally, without the warning, when chant/lifecycle has no remote (#3677)", () => {
+    const md = gatedRunSummaryMarkdown({ ...summary, pushed: false, pushWarning: "recorded locally (no remote for chant/lifecycle)" });
+    expect(md).toContain("The pending fact was recorded locally (no remote for chant/lifecycle).");
+    expect(md).not.toContain("was not pushed");
+  });
+
   test("says nothing extra when the push landed or nothing was pushed this run", () => {
     const md = gatedRunSummaryMarkdown(summary);
     expect(md).not.toContain("was not pushed");

package/src/op/gate-summary.ts

@@ -22,6 +22,7 @@ import { appendFileSync } from "node:fs";
 import { gateLedgerPath } from "../lifecycle/gate-ledger";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
 import { approveCommand } from "./gate";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note";
 
 /** What a gated run knows about the gate it stopped on. */
 export interface GatedRunSummary {
@@ -110,7 +111,9 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
   );
   if (summary.expiresAt) lines.push(`Expires: ${summary.expiresAt}`);
   if (summary.url) lines.push(`Approve at: ${summary.url}`);
-  if (summary.pushed === false) {
+  if (summary.pushed === false && isLifecycleLocalNote(summary.pushWarning)) {
+    lines.push("", `The pending fact was ${LIFECYCLE_LOCAL_NOTE}.`);
+  } else if (summary.pushed === false) {
     lines.push(
       "",
       `**This pending fact was not pushed to the remote** (${summary.pushWarning ?? "no reason given"}). ` +

package/src/op/gate.ts

@@ -50,7 +50,7 @@ import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
 import { isModelAuthored } from "../lifecycle/gate-origin";
 import { sortedJsonReplacer } from "../utils";
 import type { GateApprover, ResolvedGateApproval } from "./gate-approval";
-import { pushLifecycle, requireLifecycleLedger } from "../lifecycle/git";
+import { pushLifecycleReport, requireLifecycleLedger } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 import { resolveGateRunLocator } from "./gate-resume";
 
@@ -69,7 +69,10 @@ export interface PendingGatePush {
    * configured, or the push was rejected — `pushWarning` says which.
    */
   pushed: boolean;
-  /** Set when `pushed` is false. */
+  /**
+   * Set when `pushed` is false. With no remote it is the lifecycle module's
+   * `LIFECYCLE_LOCAL_NOTE`, which renderers show as a note, not a warning (#3677).
+   */
   pushWarning?: string;
 }
 
@@ -131,32 +134,11 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
     },
     async appendResolution(input) {
       const { record } = await appendGateResolution(input, opts);
-      try {
-        const pushed = await pushLifecycle(opts);
-        return pushed ? { record, pushed } : { record, pushed, pushWarning: "no remote is configured for chant/lifecycle — the resolution was recorded locally only" };
-      } catch (err) {
-        return { record, pushed: false, pushWarning: err instanceof Error ? err.message : String(err) };
-      }
+      return { record, ...(await pushLifecycleReport(opts)) };
     },
     async appendPending(input) {
       const { record } = await appendPendingGate(input, opts);
-      try {
-        const pushed = await pushLifecycle(opts);
-        return pushed
-          ? { record, pushed }
-          : {
-              record,
-              pushed,
-              pushWarning:
-                "no remote is configured for chant/lifecycle — the pending fact was recorded locally only",
-            };
-      } catch (err) {
-        return {
-          record,
-          pushed: false,
-          pushWarning: err instanceof Error ? err.message : String(err),
-        };
-      }
+      return { record, ...(await pushLifecycleReport(opts)) };
     },
   };
 }

package/src/op/index.ts

@@ -11,12 +11,12 @@ export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, he
          spritesUp, spritesDown } from "./builders";
 export { OpResource } from "./resource";
 export { sleep } from "./activity-runtime";
-export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-lifecycle";
-export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
+export { emulatorLifecycle, emulatorsOf, endpointEnvVars, hostPortInUse } from "./emulator-lifecycle";
+export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorIdentity, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";
 export type { OpConfig, OpSchedule, OpWorkLease, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep, OutcomeAttribute } from "./types";
-export { outcomeAttributesOf, WORK_LEASE_STEP_ID } from "./types";
+export { outcomeAttributesOf, WORK_LEASE_STEP_ID, DRIFT_EXIT_CODE } from "./types";
 export {
   RunWorkLease, workLeaseOutput, stewardWorkHolder, workLeaseProblems, workLeaseNeedsRunItem, LEASE_LOST, WORK_BRANCH_PREFIX,
 } from "./work-lease-run";

package/src/op/local-output.test.ts

@@ -3,6 +3,7 @@ import type { OpRunResult } from "./local-executor";
 import { buildRunRecord } from "../lifecycle/run-ledger";
 import type { OpRunRecord } from "./runtime";
 import { renderHuman, renderJson } from "./local-output";
+import { LIFECYCLE_LOCAL_NOTE } from "../lifecycle/local-note";
 
 /**
  * Attach the ledger record the executor would have built (#2118), so a fixture
@@ -145,6 +146,17 @@ describe("renderHuman — a gated run whose own push never reached the remote (#
     renderHuman({ ...GATED, gatePushed: true }, (l) => lines.push(l));
     expect(lines.join("\n")).not.toContain("was not pushed");
   });
+
+  // #3677: with no remote at all, the person who approves is the one at this
+  // machine; one quiet line, no warning on every local run.
+  test("prints one quiet note, not a warning, when chant/lifecycle has no remote", () => {
+    const lines: string[] = [];
+    renderHuman({ ...GATED, gatePushed: false, gatePushWarning: LIFECYCLE_LOCAL_NOTE }, (l) => lines.push(l));
+    const out = lines.join("\n");
+    expect(out).toContain("  note    : recorded locally (no remote for chant/lifecycle)");
+    expect(out).not.toContain("warning");
+    expect(out).not.toContain("was not pushed");
+  });
 });
 
 describe("renderJson", () => {

package/src/op/local-output.ts

@@ -6,6 +6,7 @@
 
 import type { OpRunResult, StepRecord } from "./local-executor";
 import { approveCommand } from "./gate";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note";
 
 type Writer = (line: string) => void;
 
@@ -107,7 +108,10 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr, sealed
   // branch, not the remote. The pending fact is still correct — the gate is
   // still right to stand — but an operator working from a clone of the
   // remote cannot see it to approve it, and nothing else here says so.
-  if (result.gatePushed === false) {
+  // #3677: with no remote at all, nobody elsewhere approves; one quiet line.
+  if (result.gatePushed === false && isLifecycleLocalNote(result.gatePushWarning)) {
+    write(`  note    : ${LIFECYCLE_LOCAL_NOTE}`);
+  } else if (result.gatePushed === false) {
     write(
       `  warning : the pending fact was not pushed to the remote — ` +
         (result.gatePushWarning ?? "it exists only in this checkout") +

package/src/op/op-ir.test.ts

@@ -334,3 +334,12 @@ describe("neverOverMcp (chant#3447)", () => {
     expect(opConfigFromIR(buildOpIR({ ...base, neverOverMcp: true })).neverOverMcp).toBe(true);
   });
 });
+
+describe("failOn (chant#3675)", () => {
+  it("survives the IR round trip, and is absent when not declared", () => {
+    const base = { name: "prod-watch", overview: "watch", phases: [] };
+    expect(buildOpIR({ ...base, failOn: "drift" }).failOn).toBe("drift");
+    expect(buildOpIR(base)).not.toHaveProperty("failOn");
+    expect(opConfigFromIR(buildOpIR({ ...base, failOn: "drift" })).failOn).toBe("drift");
+  });
+});

package/src/op/op-ir.ts

@@ -203,6 +203,8 @@ export interface OpIR {
   changesCheckout?: true;
   /** `OpConfig.neverOverMcp`, present only when true. */
   neverOverMcp?: true;
+  /** `OpConfig.failOn` (#3675), present only when set. */
+  failOn?: "drift";
   phases: OpIRPhase[];
   onFailure: OpIRPhase[];
   /** Every activity profile referenced by a step in this Op, keyed by profile name — from the registry passed to {@link buildOpIR}, empty when none was. */
@@ -371,6 +373,7 @@ export function buildOpIR(
     ...(config.workLease ? { workLease: config.workLease } : {}),
     ...(config.changesCheckout ? { changesCheckout: true as const } : {}),
     ...(config.neverOverMcp ? { neverOverMcp: true as const } : {}),
+    ...(config.failOn ? { failOn: config.failOn } : {}),
     phases: config.phases.map((p) => irPhase(p, contractRegistry)),
     onFailure: (config.onFailure ?? []).map((p) => irPhase(p, contractRegistry)),
     activityProfiles: sortedEntries(profiles),
@@ -454,5 +457,6 @@ export function opConfigFromIR(ir: OpIR): OpConfig {
     ...(ir.workLease ? { workLease: ir.workLease } : {}),
     ...(ir.changesCheckout ? { changesCheckout: true } : {}),
     ...(ir.neverOverMcp ? { neverOverMcp: true } : {}),
+    ...(ir.failOn ? { failOn: ir.failOn } : {}),
   };
 }

package/src/op/types.ts

@@ -68,8 +68,19 @@ export interface OpConfig {
    * `chant run` and `chant approve` are unchanged.
    */
   neverOverMcp?: boolean;
+  /**
+   * An outcome that makes `chant run` exit non-zero although every step
+   * succeeded (#3675). `"drift"`: a completed run whose `Drift` outcome is
+   * true exits {@link DRIFT_EXIT_CODE}, so a scheduled drift job turns red
+   * without a wrapper script. Same as passing `chant run <op> --fail-on-drift`.
+   * The run itself, and what it records on the ledger, are unchanged.
+   */
+  failOn?: "drift";
 }
 
+/** The exit code `chant run` returns for a completed run that found drift, under `failOn: "drift"` or `--fail-on-drift` (#3675). */
+export const DRIFT_EXIT_CODE = 2;
+
 /**
  * The id under which a run's work lease is published to its steps (#2748):
  * `stepOutput(WORK_LEASE_STEP_ID, "token")`, or `workLeaseOutput("token")`

package/src/serializer.ts

@@ -69,6 +69,17 @@ export interface SerializerResult {
    * superset).
    */
   verbatimFiles?: string[];
+  /**
+   * Basenames from `files` that hold a secret (committed ciphertext) and so
+   * must be written to disk, never echoed to a terminal. A build with no
+   * `--output` refuses when this is non-empty, naming the flag (chant#3738).
+   *
+   * Separate from {@link verbatimFiles}: "copy these bytes exactly" says
+   * nothing about secrecy. A verbatim file that is not listed here, such as
+   * the sql lexicon's DDL, prints like any other additional file when there
+   * is no `--output`.
+   */
+  secretFiles?: string[];
   /**
    * Non-fatal diagnostics produced during serialization (e.g. a dialect
    * dropping keys the target platform ignores). The build pipeline collects