@intentius/chant 0.118.1 → 0.120.0

package/src/cli/handlers/emulator.ts

@@ -1,10 +1,12 @@
-import { exec } from "node:child_process";
+import { exec, execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { emulatorLifecycle, emulatorsOf } from "../../op";
+import { emulatorLifecycle, emulatorsOf, type EmulatorCapability } from "../../op";
+import type { LexiconPlugin } from "../../lexicon";
 import { formatError, formatWarning, formatSuccess } from "../format";
 import type { CommandContext } from "../registry";
 
 const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 /** One emulator's state — the machine-readable `--json` unit (#920). */
 export interface EmulatorReport {
@@ -15,18 +17,143 @@ export interface EmulatorReport {
   endpoint: string;
   /** Env that points the SDK / `chant graph --live` / a triggered Op at it. */
   env: Record<string, string>;
+  /**
+   * `status` only (#3673): the container runs, but its endpoint reaches
+   * another server. `endpoint` and `env` are then empty, so a consumer does
+   * not point tooling at the wrong server.
+   */
+  conflict?: string;
 }
 
 const ACTIONS = new Set(["up", "down", "status"]);
 
-/** True if a container of this name is running. */
-async function isRunning(name: string): Promise<boolean> {
+/** A running container, a stopped one, or docker could not be asked (#3673). */
+type ContainerState = { running: boolean } | { error: string };
+
+/** Whether a container of this name is running, or why docker could not say. */
+async function containerState(name: string): Promise<ContainerState> {
   try {
     const { stdout } = await execAsync(`docker ps -q -f name=${name}`);
-    return Boolean(stdout.trim());
+    return { running: Boolean(stdout.trim()) };
+  } catch (err) {
+    // The shell exits 127 when the command is not on PATH. Reporting that as
+    // "down" told a user with running containers that nothing was running.
+    const e = err as { code?: number | string; stderr?: string; message?: string };
+    if (e.code === 127 || e.code === "ENOENT") return { error: "docker not found on PATH; cannot check the emulator" };
+    const why = (e.stderr || e.message || "").trim().split("\n")[0];
+    return { error: `docker could not list containers${why ? ` (${why})` : ""}; cannot check the emulator` };
+  }
+}
+
+/** The host port Docker publishes `containerPort` on, or undefined when it cannot tell. */
+async function publishedPort(name: string, containerPort: number): Promise<number | undefined> {
+  try {
+    const { stdout } = await execFileAsync("docker", ["port", name, `${containerPort}/tcp`]);
+    const match = /:(\d+)\s*$/m.exec(stdout.trim().split("\n")[0] ?? "");
+    return match ? Number(match[1]) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether `endpoint` reaches this container's server (#3673): the identity
+ * read inside the container against the one read through the endpoint.
+ * Returns the problem, or undefined when they agree or the check cannot run.
+ */
+export async function endpointConflict(
+  lexicon: string,
+  cap: EmulatorCapability,
+  endpoint: string,
+  port: number,
+): Promise<string | undefined> {
+  const identity = cap.spec.identity;
+  if (!identity) return undefined;
+  let inside: string;
+  try {
+    inside = (await execFileAsync("docker", ["exec", cap.spec.name, ...identity.command])).stdout.trim();
   } catch {
-    return false; // docker missing / not running — treat as down
+    return undefined; // the container cannot answer for itself; nothing to compare
+  }
+  const hint =
+    `Run \`chant emulator down --lexicon ${lexicon}\`, then \`chant emulator up --lexicon ${lexicon} --port ${cap.spec.containerPort}=<free port>\`.`;
+  let answered: { id: string; label: string };
+  try {
+    answered = await identity.probe(endpoint);
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return `localhost:${port} does not answer as the emulator (${why}); another ${identity.server} may hold 127.0.0.1:${port}. ${hint}`;
+  }
+  if (answered.id.trim() === inside) return undefined;
+  return `localhost:${port} answers as ${answered.label}, not the emulator; another ${identity.server} holds 127.0.0.1:${port}. ${hint}`;
+}
+
+/**
+ * `--port` values as container port to host port (#3673). A bare number
+ * applies when exactly one emulator is selected.
+ */
+export function parsePortMappings(values: readonly string[], targets: readonly EmulatorCapability[]): Map<number, number> {
+  const ports = new Map<number, number>();
+  for (const value of values) {
+    const pair = /^(\d+)=(\d+)$/.exec(value);
+    const bare = /^(\d+)$/.exec(value);
+    if (pair) {
+      const containerPort = Number(pair[1]);
+      if (!targets.some((t) => t.spec.containerPort === containerPort)) {
+        const known = targets.map((t) => `${t.spec.containerPort} (${t.spec.name})`).join(", ");
+        throw new Error(`--port ${value}: no selected emulator listens on ${containerPort}; the selected ones use ${known || "none"}`);
+      }
+      ports.set(containerPort, Number(pair[2]));
+    } else if (bare) {
+      if (targets.length !== 1) {
+        throw new Error(`--port ${value} is ambiguous with ${targets.length} emulators selected; use --port <container-port>=<host-port>`);
+      }
+      ports.set(targets[0]!.spec.containerPort, Number(bare[1]));
+    } else {
+      throw new Error(`--port ${value}: expected <container-port>=<host-port>, e.g. --port 5432=15432`);
+    }
+  }
+  return ports;
+}
+
+/**
+ * `chant emulator --help` (#3673): the subcommands and flags, and for each
+ * configured lexicon's emulator the port, endpoint and sign-in a client uses.
+ */
+export function formatEmulatorHelp(plugins: readonly LexiconPlugin[]): string {
+  const lines = [
+    "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--json]",
+    "",
+    "Boot, stop or inspect the local emulators of the project's configured lexicons.",
+    "",
+    "Subcommands:",
+    "  up       Boot each emulator, or reuse a running one, and wait until it is ready.",
+    "           Refuses when another process already holds the host port on 127.0.0.1.",
+    "  down     Stop and remove the containers.",
+    "  status   Report whether each emulator runs, and check that its endpoint reaches it.",
+    "           Exits 1 when docker cannot be asked or an endpoint reaches another server.",
+    "",
+    "Flags:",
+    "  --lexicon <name>     Act on one lexicon's emulators only.",
+    "  --port <c>=<h>       up: publish container port <c> on host port <h>; repeatable.",
+    "                       A bare <h> works when one emulator is selected.",
+    "  --json               Print the machine-readable report on stdout.",
+    "",
+  ];
+  const caps = plugins.flatMap((p) => emulatorsOf(p.emulator).map((cap) => ({ lexicon: p.name, cap })));
+  if (caps.length === 0) {
+    lines.push("No lexicon configured for this project has a local emulator.");
+    return lines.join("\n");
   }
+  lines.push("Emulators in this project (default ports):");
+  for (const { lexicon, cap } of caps) {
+    const endpoint = emulatorLifecycle(cap.spec).endpoint(cap.spec.containerPort);
+    lines.push(`  ${lexicon}: ${cap.spec.name}, port ${cap.spec.containerPort}, ${endpoint}`);
+    if (cap.spec.credentials) lines.push(`      sign in: ${cap.spec.credentials}`);
+    const env = Object.entries(cap.env(endpoint)).map(([k, v]) => `${k}=${v}`);
+    if (env.length) lines.push(`      env: ${env.join(" ")}`);
+  }
+  return lines.join("\n");
 }
 
 /**
@@ -44,7 +171,7 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
   // in args.path; the bare `emulator` fallback leaves it as the "." default.
   const action = args.path;
   if (!action || !ACTIONS.has(action)) {
-    console.error(formatError({ message: "Usage: chant emulator <up|down|status> [--lexicon <name>] [--json]" }));
+    console.error(formatError({ message: "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--json]; chant emulator --help lists the ports and sign-in" }));
     return 1;
   }
 
@@ -67,30 +194,60 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
     return 0;
   }
 
+  let ports: Map<number, number>;
+  try {
+    if (args.port?.length && action !== "up") throw new Error("--port applies to `chant emulator up` only");
+    ports = parsePortMappings(args.port ?? [], targets.map((t) => t.cap));
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+
   const reports: EmulatorReport[] = [];
   for (const { lexicon, cap } of targets) {
     const lc = emulatorLifecycle(cap.spec);
     if (action === "up") {
-      const { endpoint } = await lc.up();
-      reports.push({ lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
+      const port = ports.get(cap.spec.containerPort);
+      try {
+        const { endpoint } = await lc.up(port === undefined ? {} : { port });
+        reports.push({ lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
+      } catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+      }
     } else if (action === "down") {
       await lc.down();
       reports.push({ lexicon, name: cap.spec.name, endpoint: "", env: {} });
     } else {
-      const running = await isRunning(cap.spec.name);
-      const endpoint = running ? lc.endpoint(cap.spec.containerPort) : "";
-      reports.push({ lexicon, name: cap.spec.name, endpoint, env: endpoint ? cap.env(endpoint) : {} });
+      const state = await containerState(cap.spec.name);
+      if ("error" in state) {
+        console.error(formatError({ message: state.error }));
+        return 1;
+      }
+      if (!state.running) {
+        reports.push({ lexicon, name: cap.spec.name, endpoint: "", env: {} });
+        continue;
+      }
+      // The port `up` published, which `--port` may have moved off the default.
+      const port = (await publishedPort(cap.spec.name, cap.spec.containerPort)) ?? cap.spec.containerPort;
+      const endpoint = lc.endpoint(port);
+      const conflict = await endpointConflict(lexicon, cap, endpoint, port);
+      reports.push(conflict
+        ? { lexicon, name: cap.spec.name, endpoint: "", env: {}, conflict }
+        : { lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
     }
   }
 
+  const exit = reports.some((r) => r.conflict) ? 1 : 0;
   if (args.json) {
     console.log(JSON.stringify({ emulators: reports }));
-    return 0;
+    return exit;
   }
   for (const r of reports) {
     if (action === "up") console.error(formatSuccess(`${r.lexicon}: ${r.name} up on ${r.endpoint}`));
     else if (action === "down") console.error(formatSuccess(`${r.lexicon}: ${r.name} down`));
+    else if (r.conflict) console.error(formatError({ message: `${r.lexicon}: ${r.name} runs, but ${r.conflict}` }));
     else console.error(`${r.lexicon}: ${r.name} — ${r.endpoint ? `up on ${r.endpoint}` : "down"}`);
   }
-  return 0;
+  return exit;
 }

package/src/cli/handlers/lifecycle.ts

@@ -5,7 +5,7 @@ import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
 import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
 import { deepDiffForLexicon, type DeclaredEntities } from "../../lifecycle/deep-observe";
-import { countUnclaimed, countPropertyDrift, countHeld, suspiciousHeld, type DeepDiffResult, type DeepEntityHeld } from "../../lifecycle/deep-diff";
+import { countUnclaimed, countPending, countPropertyDrift, countHeld, suspiciousHeld, type DeepDiffResult, type DeepEntityHeld } from "../../lifecycle/deep-diff";
 import { describePathOrigin, getPathProvenance, getProvenance, type EntityProvenance } from "../../provenance";
 import { resolveDeepDrift, resolveDriftedField, type FieldReconcile } from "../../fold-provenance";
 import {
@@ -913,7 +913,7 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
           componentStacks: args.componentStacks,
           baseline: baselineForLexicon(args.baseline, lexiconName),
         });
-        totalDrift += countPropertyDrift(deep);
+        totalDrift += countPropertyDrift(deep) + countPending(deep);
         // Only count a deep hole for an entity the thin read *did* resolve —
         // otherwise one unreadable entity is counted twice.
         totalUnobserved += deep.unobserved.filter((u) => !observed.unobserved[u.name]).length;
@@ -1001,8 +1001,10 @@ function renderDeepDiff(
   const drift = countPropertyDrift(deep);
   const unclaimedCount = countUnclaimed(deep);
   const heldCount = countHeld(deep);
+  const pendingCount = countPending(deep);
   if (
     drift === 0 &&
+    pendingCount === 0 &&
     heldCount === 0 &&
     unclaimedCount === 0 &&
     deep.accepted.length === 0 &&
@@ -1017,6 +1019,7 @@ function renderDeepDiff(
   console.log(
     `${drift} property drift across ${deep.drifted.length} resource(s), ` +
       `${acceptedCount} accepted, ${deep.unchanged.length} unchanged` +
+      (pendingCount > 0 ? `, ${pendingCount} pending` : "") +
       (heldCount > 0 ? `, ${heldCount} held` : "") +
       (unclaimedCount > 0 ? `, ${unclaimedCount} unclaimed` : "") +
       (deep.unobserved.length > 0 ? `, ${deep.unobserved.length} unobserved` : ""),
@@ -1064,6 +1067,14 @@ function renderDeepDiff(
       }
     }
   }
+  if (pendingCount > 0) {
+    // #3706: changes an apply would make that no declared property shows
+    // (privileges granted by hand). Printed, so the plan digest moves with them.
+    console.log(formatBold("\nPENDING (changes an apply would make that no declared property shows):"));
+    for (const p of deep.pending ?? []) {
+      console.log(`  ~ ${p.subject}: ${p.change}${p.entities && p.entities.length > 0 ? ` [from: ${p.entities.join(", ")}]` : ""}`);
+    }
+  }
   if (deep.unclaimed.length > 0) {
     // Not drift, and printed after it for that reason (#2160): chant never set
     // these fields, so nothing here is a change chant proposes to make.

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

@@ -63,7 +63,7 @@ vi.mock("../../lifecycle/git", async () => {
   const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
   return {
     ...actual,
-    pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+    pushLifecycleReport: (...args: unknown[]) => pushLifecycleMock(...args),
     // Mocked, not merely defaulted: the real one shells to `git fetch`, and
     // these tests run in the chant checkout itself (#2303).
     requireLifecycleLedger: (...args: unknown[]) => requireLifecycleLedgerMock(...args),
@@ -92,7 +92,7 @@ beforeEach(() => {
   loadActivitiesMock.mockResolvedValue(new Map());
   loadProfilesMock.mockResolvedValue({});
   discoverOpsMock.mockResolvedValue({ ops: new Map([["fountain-apply", {}]]), errors: [] });
-  pushLifecycleMock.mockResolvedValue(true);
+  pushLifecycleMock.mockResolvedValue({ pushed: true });
   requireLifecycleLedgerMock.mockResolvedValue(undefined);
   readGateResolutionsMock.mockResolvedValue({ records: [], malformed: 0 });
   readGateLedgerMock.mockResolvedValue({ resolutions: [], pending: [], malformed: 0 });
@@ -1046,31 +1046,33 @@ describe("runApprove — a push that does not land is reported (#2309 review)",
       commit: "sha",
       record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
     });
-    pushLifecycleMock.mockRejectedValue(new Error("Another snapshot completed for chant/lifecycle"));
+    pushLifecycleMock.mockResolvedValue({ pushed: false, pushWarning: "Another snapshot completed for chant/lifecycle" });
     const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
 
     const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
 
     const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
-    expect(out).toMatch(/push to the remote was rejected/);
+    expect(out).toMatch(/push to the remote did not land: Another snapshot completed/);
     expect(out).toMatch(/local only . the push did not land/);
     // Still exit 0: the local append is a correct local fact.
     expect(code).toBe(0);
     errSpy.mockRestore();
   });
 
-  test("a project with no remote says nothing was pushed", async () => {
+  test("a project with no remote says so quietly, with no warning (#3677)", async () => {
     seedPending("fountain-apply", "rollout-gate", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
       commit: "sha",
       record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
     });
-    pushLifecycleMock.mockResolvedValue(false);
+    pushLifecycleMock.mockResolvedValue({ pushed: false, pushWarning: "recorded locally (no remote for chant/lifecycle)" });
     const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
 
     await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
 
-    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toMatch(/No remote is configured/);
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toMatch(/resolved by alex .*\(recorded locally \(no remote for chant\/lifecycle\)\)/);
+    expect(out).not.toMatch(/push did not land|did not land|No remote is configured/);
     errSpy.mockRestore();
   });
 });

package/src/cli/handlers/operator.ts

@@ -50,7 +50,8 @@ import {
 import { approverOf, tallyGateApprovals } from "../../op/gate";
 import { FAN_OUT_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
 import { PR_GATE_OP } from "../../pr-loop";
-import { pushLifecycle, requireLifecycleLedger } from "../../lifecycle/git";
+import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -818,23 +819,18 @@ const LIFECYCLE_BRANCH = "chant/lifecycle";
  * only in their own checkout.
  *
  * The append is still a correct *local* fact, so this is a warning and not a
- * failure; the exit code is unchanged.
+ * failure; the exit code is unchanged. With no remote at all there is nobody
+ * elsewhere to tell, so that case is a quiet suffix and no warning (#3677).
  */
-async function reportedPush(consequence: string): Promise<boolean> {
-  try {
-    const pushed = await pushLifecycle();
-    if (pushed) return true;
-    console.error(formatWarning({
-      message: `No remote is configured, so nothing was pushed. ${consequence}`,
-    }));
-    return false;
-  } catch (err) {
-    console.error(formatWarning({
-      message: `The push to the remote was rejected: ${err instanceof Error ? err.message : String(err)}`,
-      hint: consequence,
-    }));
-    return false;
-  }
+async function reportedPush(consequence: string): Promise<{ pushed: boolean; suffix: string }> {
+  const { pushed, pushWarning } = await pushLifecycleReport();
+  if (pushed) return { pushed, suffix: "" };
+  if (isLifecycleLocalNote(pushWarning)) return { pushed, suffix: ` (${LIFECYCLE_LOCAL_NOTE})` };
+  console.error(formatWarning({
+    message: `The push to the remote did not land: ${pushWarning ?? "no reason given"}`,
+    hint: consequence,
+  }));
+  return { pushed, suffix: " (local only — the push did not land)" };
 }
 
 export async function runApprove(ctx: CommandContext): Promise<number> {
@@ -873,13 +869,12 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
       expiresAt: now,
       ...(standing.description ? { description: standing.description } : {}),
     });
-    const pushed = await reportedPush(
+    const push = await reportedPush(
       `The expiry is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
         `a run in another checkout still sees the old pending fact.`,
     );
     console.error(formatSuccess(
-      `Gate "${gate}" on "${opName}" expired at ${now} — not approved` +
-        (pushed ? "" : " (local only — the push did not land)"),
+      `Gate "${gate}" on "${opName}" expired at ${now} — not approved` + push.suffix,
     ));
     console.error(formatInfo(
       opName === FAN_OUT_GATE_OP
@@ -1294,7 +1289,7 @@ export async function recordGateApproval(
     origin,
     ...(refusal && opts.allowSameOrigin ? { sameOriginOverride: true } : {}),
   });
-  const pushed = await reportedPush(
+  const push = await reportedPush(
     `The resolution is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
       `a run in another checkout will not see it.`,
   );
@@ -1305,7 +1300,7 @@ export async function recordGateApproval(
       ` at ${record.timestamp}` +
       (record.url ? ` (${record.url})` : "") +
       (record.seal ? `, signed with ${record.seal.key}` : "") +
-      (pushed ? "" : " (local only — the push did not land)"),
+      push.suffix,
   ));
   if (record.planDigest) {
     console.error(formatInfo(
@@ -1319,7 +1314,7 @@ export async function recordGateApproval(
       console.error(formatInfo(line));
     }
   }
-  return { ok: true, record, pushed };
+  return { ok: true, record, pushed: push.pushed };
 }
 
 /**

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

@@ -1877,3 +1877,55 @@ describe("runOpComponents", () => {
     });
   });
 });
+
+/**
+ * chant #3675 — a completed run that found drift exits 0 unless asked to
+ * fail: `--fail-on-drift` on the command line, or `failOn: "drift"` on the Op.
+ * The drift arrives the way a WatchOp's does, as a `Drift` outcome attribute.
+ */
+describe("runOp: --fail-on-drift (#3675)", () => {
+  function driftOp(name: string, drifted: boolean, extra: Record<string, unknown> = {}) {
+    const step = {
+      kind: "activity",
+      fn: "shellCmd",
+      args: { cmd: `echo '{"drifted":${drifted}}'`, json: true },
+      outcomeAttribute: { name: "Drift", from: "json.drifted" },
+    };
+    const [opName, discovered] = localOp(name, [step]);
+    return [opName, { config: { ...discovered.config, ...extra } }] as const;
+  }
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadChantConfigMock.mockReset().mockResolvedValue({ config: {} });
+    loadPluginsMock.mockReset().mockResolvedValue([]);
+  });
+
+  afterEach(() => vi.restoreAllMocks());
+
+  test("drift without the flag or failOn still exits 0", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([driftOp("watch", true)]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    expect(await runOp({ args: makeArgs({ path: "watch" }), plugins: [], serializers: [] })).toBe(0);
+  });
+
+  test("--fail-on-drift exits 2 when the Drift outcome is true, and says why", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([driftOp("watch", true)]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const stderr = makeStderrSpy();
+    expect(await runOp({ args: makeArgs({ path: "watch", failOnDrift: true }), plugins: [], serializers: [] })).toBe(2);
+    expect(stderr.join("\n")).toContain("exiting 2 because --fail-on-drift");
+  });
+
+  test("--fail-on-drift exits 0 when the run found no drift", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([driftOp("watch", false)]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    expect(await runOp({ args: makeArgs({ path: "watch", failOnDrift: true }), plugins: [], serializers: [] })).toBe(0);
+  });
+
+  test("an Op declaring failOn: \"drift\" exits 2 with no flag", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([driftOp("watch", true, { failOn: "drift" })]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    expect(await runOp({ args: makeArgs({ path: "watch" }), plugins: [], serializers: [] })).toBe(2);
+  });
+});

package/src/cli/handlers/run.ts

@@ -4,7 +4,7 @@ import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { loadChantConfig, resolveAutoReleaseDisabled, InvalidChantConfigError, type ChantConfig } from "../../config";
 import { discoverOps, discoverStewards } from "../../op/discover";
 import { stewardWorkHolder } from "../../op/work-lease-run";
-import type { OpConfig } from "../../op/types";
+import { DRIFT_EXIT_CODE, type OpConfig } from "../../op/types";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { runOpLocally, findPolicyGateStep, OpRunFailure, type StepRecord } from "../../op/local-executor";
 import { approveCommand, describeGateMismatch, gateIsSealed } from "../../op/gate";
@@ -22,6 +22,7 @@ import { holdBesideLease } from "../../op/steward-beside";
 import { acquireStewardTurn, STEWARD_TURN_WAIT_MS } from "../../op/operator";
 import { releaseLease, currentHolderId, type AcquireLeaseResult } from "../../lifecycle/lease";
 import { StaleLockError } from "../../lifecycle/git";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
 import { maybeRecordAutoRelease } from "../../components/auto-release";
@@ -67,6 +68,40 @@ function resolveGatedExitCode(ctx: CommandContext): number | undefined {
   return raw;
 }
 
+/**
+ * Whether a settled run's records carry a true `Drift` outcome (#3675) — the
+ * one `lifecycleDiff` surfaces through `outcomeAttribute` on a WatchOp,
+ * ApplyOp, ReconcileOp or ConvergeOp step.
+ */
+export function runFoundDrift(records: readonly StepRecord[] | undefined): boolean {
+  for (const record of records ?? []) {
+    const outcomes = record.outcomes ?? (record.outcome ? [record.outcome] : []);
+    if (outcomes.some((o) => o.name === "Drift" && o.value === true)) return true;
+  }
+  return false;
+}
+
+/**
+ * The exit code for a completed run (#3675): 0, or {@link DRIFT_EXIT_CODE}
+ * when the run found drift and either `--fail-on-drift` or the Op's own
+ * `failOn: "drift"` asked for drift to fail the job. Says why on stderr when
+ * it remaps, since every step in the run succeeded.
+ */
+export function completedRunExitCode(
+  opName: string,
+  config: Pick<OpConfig, "failOn">,
+  failOnDriftFlag: boolean | undefined,
+  records: readonly StepRecord[] | undefined,
+): number {
+  if (!(failOnDriftFlag || config.failOn === "drift")) return 0;
+  if (!runFoundDrift(records)) return 0;
+  const why = failOnDriftFlag ? "--fail-on-drift" : `the Op declares failOn: "drift"`;
+  console.error(formatWarning({
+    message: `Op "${opName}" found drift; exiting ${DRIFT_EXIT_CODE} because ${why}`,
+  }));
+  return DRIFT_EXIT_CODE;
+}
+
 /**
  * What a gated run leaves behind for CI, beyond the stderr block the renderers
  * already print (#2243): the same gate, approve command and ledger path
@@ -976,7 +1011,9 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
     // branch. The gate is still right to stand, but an operator elsewhere
     // cannot see the pending fact to approve it, and nothing else here says
     // why not.
-    if (result.gated.pushed === false) {
+    if (result.gated.pushed === false && isLifecycleLocalNote(result.gated.pushWarning)) {
+      console.error(formatInfo(LIFECYCLE_LOCAL_NOTE));
+    } else if (result.gated.pushed === false) {
       console.error(formatWarning({
         message: `the pending fact was not pushed to the remote: ${result.gated.pushWarning ?? "recorded locally only"}`,
         hint: "an operator working from a clone of the remote cannot approve it until it does",
@@ -1182,7 +1219,10 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
       }
       return gatedExit;
     }
-    return status.state === "completed" ? 0 : 1;
+    if (status.state !== "completed") return 1;
+    // A completed run that found drift exits 2 when asked to (#3675), so a
+    // scheduled drift job turns red without a script that reads the ledger.
+    return completedRunExitCode(opName, config, ctx.args.failOnDrift, status.result?.records ?? status.records);
   } catch (err) {
     if (err instanceof OpRunFailure) {
       const sealed = err.result.gate ? await gateIsSealed(err.result.gate.gate) : false;