@intentius/chant 0.118.1 → 0.121.0

package/src/cli/lexicon-subpath-build.test.ts

@@ -0,0 +1,129 @@
+/**
+ * chant #3648 — a project with no `chant.config.ts` that imports a lexicon only
+ * through a subpath (`@intentius/chant-lexicon-sql/clickhouse`, as every sql
+ * project does) failed with "No lexicon detected in infrastructure files", and
+ * `--lexicon sql` did not help. These tests build the issue's repro for both
+ * sql dialects, and check that `--lexicon` is honoured when resolving the
+ * project's lexicons.
+ */
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveProjectLexicons } from "./plugins";
+import { runCommandInProcess } from "./main";
+import { captureRun } from "../workspace/member-run";
+
+const repoNodeModules = resolve(fileURLToPath(new URL(".", import.meta.url)), "../../../../node_modules");
+
+const REPRO = {
+  clickhouse: {
+    source:
+      'import { table } from "@intentius/chant-lexicon-sql/clickhouse";\n' +
+      "export const events = table`CREATE TABLE events (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY (id, ts)`;\n",
+    ddl: "clickhouse.sql",
+  },
+  postgres: {
+    source:
+      'import { table } from "@intentius/chant-lexicon-sql/postgres";\n' +
+      "export const events = table`CREATE TABLE events (id bigint PRIMARY KEY, ts timestamptz NOT NULL)`;\n",
+    ddl: "postgres.sql",
+  },
+} as const;
+
+let root: string;
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-3648-")));
+  // A package.json stops the config walk at the project root.
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "repro", private: true, type: "module" }));
+  mkdirSync(join(root, "src"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+function writeSource(source: string): void {
+  writeFileSync(join(root, "src", "infra.ts"), source);
+}
+
+describe("resolveProjectLexicons with --lexicon (#3648)", () => {
+  test("a config-less project with no lexicon import resolves to the named lexicon", async () => {
+    writeSource("export const nothing = 1;\n");
+
+    await expect(resolveProjectLexicons(join(root, "src"))).rejects.toThrow("No lexicon detected");
+    expect(await resolveProjectLexicons(join(root, "src"), { lexicon: "sql" })).toEqual(["sql"]);
+  });
+
+  test("the named lexicon joins the detected ones", async () => {
+    writeSource('import { Deployment } from "@intentius/chant-lexicon-k8s";\nexport const x = 1;\n');
+
+    expect(await resolveProjectLexicons(join(root, "src"), { lexicon: "sql" })).toEqual(["k8s", "sql"]);
+    expect(await resolveProjectLexicons(join(root, "src"), { lexicon: "k8s" })).toEqual(["k8s"]);
+  });
+
+  test("the named lexicon joins the config's lexicons", async () => {
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    writeSource("export const nothing = 1;\n");
+
+    expect(await resolveProjectLexicons(join(root, "src"), { lexicon: "sql" })).toEqual(["aws", "sql"]);
+  });
+
+  test("a subpath import resolves with no config and no flag", async () => {
+    writeSource(REPRO.postgres.source);
+
+    expect(await resolveProjectLexicons(join(root, "src"))).toEqual(["sql"]);
+  });
+});
+
+describe("chant build on the #3648 repro", () => {
+  beforeEach(() => {
+    // The repro imports the workspace's sql lexicon, as an installed project would.
+    symlinkSync(repoNodeModules, join(root, "node_modules"), "dir");
+  });
+
+  for (const [dialect, { source, ddl }] of Object.entries(REPRO)) {
+    for (const flags of [[], ["--lexicon", "sql"]]) {
+      test(`${dialect}, ${flags.length ? "--lexicon sql" : "no flag"}: builds with no chant.config`, async () => {
+        writeSource(source);
+        const out = join(root, "dist", "schema.json");
+
+        const run = await captureRun(() => runCommandInProcess(["build", join(root, "src"), ...flags, "-o", out]));
+
+        expect(run.stderr).not.toContain("No lexicon detected");
+        expect(run.exitCode).toBe(0);
+        expect(existsSync(out)).toBe(true);
+        expect(readFileSync(join(root, "dist", ddl), "utf-8")).toContain("CREATE TABLE");
+      }, 60_000);
+    }
+
+    // chant #3738 — the DDL is verbatim but not a secret, so a build with no
+    // --output prints it rather than refusing as if it were ciphertext.
+    test(`${dialect}: builds to stdout with no --output (#3738)`, async () => {
+      writeSource(source);
+      // The build prints through console, which vitest intercepts before it
+      // reaches the stream captureRun replaces.
+      const out: string[] = [];
+      const err: string[] = [];
+      const log = vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => { out.push(a.join(" ")); });
+      const error = vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => { err.push(a.join(" ")); });
+      let run: Awaited<ReturnType<typeof captureRun>>;
+      try {
+        run = await captureRun(() => runCommandInProcess(["build", join(root, "src")]));
+      } finally {
+        log.mockRestore();
+        error.mockRestore();
+      }
+      const stderr = run.stderr + err.join("\n");
+
+      expect(stderr).not.toContain("committed-encrypted");
+      expect(run.exitCode).toBe(0);
+      expect(JSON.parse(out.join("\n"))).toMatchObject({ dialect });
+      expect(stderr).toContain(`--- ${ddl} ---`);
+      expect(stderr).toContain("CREATE TABLE events");
+      expect(existsSync(join(root, ddl))).toBe(false);
+    }, 60_000);
+  }
+});

package/src/cli/main.ts

@@ -38,7 +38,7 @@ import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpApprove, runOpSignalRenamed, runOpCancel, runOpLog } from "./handlers/run";
 import { runOpWaveCommand } from "./handlers/run-wave";
 import { runOperator, runOperatorStatus, runOperatorLog, runApprove } from "./handlers/operator";
-import { runEmulator } from "./handlers/emulator";
+import { runEmulator, formatEmulatorHelp } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
 import type { LexiconPlugin } from "../lexicon";
 
@@ -290,6 +290,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.src = args[++i];
     } else if (arg === "--env") {
       result.env = args[++i];
+    } else if (arg === "--port") {
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--port needs a port: --port <container-port>=<host-port>");
+      (result.port ??= []).push(value);
     } else if (arg === "--promote-to") {
       result.promoteTo = args[++i];
       if (!result.promoteTo || result.promoteTo.startsWith("-")) throw new Error("--promote-to needs an environment: --promote-to <env>");
@@ -920,6 +924,8 @@ Ops:
   run <name>            Run an Op on the resolved runtime (--on; local by default)
                         [--work <id>] [--holder <name>]: the work item an Op
                         with a work lease runs under, and who holds it
+                        --fail-on-drift: exit 2 when the run completes and
+                        its Drift outcome is true (WatchOp failOn: "drift")
   run list              List all Ops with the runtime's state for each
   run status <name>     Show the runtime's state for one Op's latest run
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
@@ -1458,7 +1464,8 @@ Lexicon development:
 
 Local:
   emulator <up|down|status>  Boot/stop/inspect configured lexicons' local
-                           emulators (Floci etc.); --lexicon <name>, --json
+                           emulators (Floci etc.); --lexicon <name>, --json,
+                           --port; \`chant emulator --help\` lists ports and logins
 
 Servers:
   serve lsp             Start the LSP server (stdio)
@@ -1669,10 +1676,12 @@ async function tryPluginCommand(rawArgv: string[]): Promise<number | undefined>
 /**
  * Load lexicon plugins for the given project path, or exit with an error.
  */
-async function loadPluginsOrExit(path: string): Promise<import("../lexicon").LexiconPlugin[]> {
+async function loadPluginsOrExit(path: string, lexicon?: string): Promise<import("../lexicon").LexiconPlugin[]> {
   let plugins;
   try {
-    const lexiconNames = await resolveProjectLexicons(resolve(path));
+    // chant #3648 — `--lexicon <name>` loads that lexicon even when the
+    // project's config and imports name none.
+    const lexiconNames = await resolveProjectLexicons(resolve(path), { lexicon });
     plugins = await loadPlugins(lexiconNames);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
@@ -1771,7 +1780,7 @@ export async function runCommandInProcess(argv: string[]): Promise<number> {
     console.error(formatError({ message: envErr, hint: "Declare it in chant.config `environments`, or omit --env." }));
     return 1;
   }
-  const plugins = match.def.requiresPlugins ? await loadPluginsOrExit(match.compound ? "." : args.path) : [];
+  const plugins = match.def.requiresPlugins ? await loadPluginsOrExit(match.compound ? "." : args.path, args.lexicon) : [];
   return match.def.handler({ args, plugins, serializers: plugins.map((p) => p.serializer) });
 }
 
@@ -1993,6 +2002,15 @@ async function main(): Promise<void> {
     return;
   }
 
+  // #3673 — `chant emulator --help` is the emulator's own usage, with the
+  // ports and sign-in each configured lexicon's emulator uses, not the
+  // global command list it used to print.
+  if (args.help && args.command === "emulator") {
+    console.log(formatEmulatorHelp(await loadPluginsBestEffort().catch(() => [])));
+    await flushAndExit(0);
+    return;
+  }
+
   if (args.help || !args.command) {
     const groups = await loadPluginsBestEffort().then(collectCommandGroups).catch(() => []);
     printHelp(groups);
@@ -2122,7 +2140,7 @@ async function main(): Promise<void> {
       ? await loadPlugins(await resolveProjectLexicons(resolve(projectPath)).catch(() => [])).catch(() => [])
       : match.def.name === "serve mcp" && (await isLexiconlessWorkspaceRoot(projectPath))
         ? [] // #2700 — runServeMcp loads the chant members' lexicons itself.
-        : await loadPluginsOrExit(projectPath)
+        : await loadPluginsOrExit(projectPath, args.lexicon)
     : [];
   const serializers = plugins.map((p) => p.serializer);
   const ctx = { args, plugins, serializers };

package/src/cli/plugins.ts

@@ -8,6 +8,7 @@ import { existsSync, readdirSync, readFileSync, type Dirent } from "node:fs";
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 import { loadChantConfigUpward } from "../config";
 import { findInfraFiles, detectLexicons } from "../index";
+import { isNoLexiconDetected } from "../detectLexicon";
 import { checkConflicts, describeConflict } from "./conflict-check";
 import { prepareProjectCodegen } from "../project-codegen";
 
@@ -317,14 +318,34 @@ export async function loadPlugins(lexiconNames: string[]): Promise<LexiconPlugin
  * loaded but never imported by name in that particular stack's files) would
  * otherwise silently miss it.
  */
-export async function resolveProjectLexicons(projectPath: string): Promise<string[]> {
+export async function resolveProjectLexicons(
+  projectPath: string,
+  options: {
+    /**
+     * chant #3648: the lexicon the command line named (`--lexicon <name>`).
+     * It is always in the result: a project whose config and source name no
+     * lexicon resolves to it alone, instead of failing with "No lexicon
+     * detected", and one that names other lexicons gets it added to them.
+     */
+    lexicon?: string;
+  } = {},
+): Promise<string[]> {
+  const requested = options.lexicon;
   const { config } = await loadChantConfigUpward(projectPath);
 
+  let names: string[];
   if (config.lexicons && config.lexicons.length > 0) {
-    return lexiconNames(config.lexicons);
+    names = lexiconNames(config.lexicons);
+  } else {
+    // Fallback: detect from source imports — a pure text scan, no execution.
+    const files = await findInfraFiles(projectPath);
+    try {
+      names = await detectLexicons(files);
+    } catch (error) {
+      if (requested && isNoLexiconDetected(error)) return [requested];
+      throw error;
+    }
   }
 
-  // Fallback: detect from source imports — a pure text scan, no execution.
-  const files = await findInfraFiles(projectPath);
-  return detectLexicons(files);
+  return requested && !names.includes(requested) ? [...names, requested] : names;
 }

package/src/cli/registry.ts

@@ -163,6 +163,8 @@ export interface ParsedArgs {
   /** `--env <name>` — active environment: sets CHANT_ENV so env-aware source
    * re-evaluates for that environment (`build` + `graph`), and drives policy. */
   env?: string;
+  /** `chant emulator up --port <container-port>=<host-port>`, repeatable (#3673); a bare `<host-port>` when one emulator is selected. */
+  port?: string[];
   /** `chant build --components --generate <lexicon> --promote-to <env>` (#2575) — add a promote job to the generated pipeline. */
   promoteTo?: string;
   /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
@@ -504,6 +506,10 @@ export interface ParsedArgs {
    * `chant search "<q>" --check-live|--check-snapshot --fail-on-drift`
    * (#1268) — exit non-zero when the scoped check finds drift, so it is usable
    * as a CI gate. Meaningless without one of the two flags above.
+   *
+   * `chant run <op> --fail-on-drift` (#3675) — exit 2 instead of 0 when the
+   * run completes and its `Drift` outcome is true, the same as the Op
+   * declaring `failOn: "drift"`. A failed run still returns 1, a gated one 3.
    */
   failOnDrift?: boolean;
 

package/src/components/driver-output.ts

@@ -7,6 +7,7 @@
  */
 
 import type { DriverRunResult, DriverStepRecord } from "./driver";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note";
 
 type Writer = (line: string) => void;
 
@@ -75,7 +76,9 @@ export function renderDriverHuman(result: DriverRunResult, write: Writer = stder
     // #2310: this run's own append reached only the local chant/lifecycle
     // branch. The gate still stands correctly — but an operator elsewhere
     // cannot see the pending fact to approve it.
-    if (result.gatePushed === false) {
+    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/deep-observation.ts

@@ -95,6 +95,24 @@ export interface DeepResourceObservation {
   claimedFields?: readonly string[];
 }
 
+/**
+ * A change an apply would make that no one declared entity's properties show
+ * (#3706): Postgres privileges, which the declarations decide as the access
+ * they add up to rather than one grant at a time, so a privilege granted by
+ * hand is a change to make with no declared property it differs on.
+ *
+ * `lifecycle diff --live` prints these as drift, so the plan digest an
+ * approval binds to moves with them.
+ */
+export interface DeepPendingChange {
+  /** What the change is on, in the lexicon's words: `relation app.orders TO reader`. */
+  subject: string;
+  /** What an apply would do about it: the statements, or a sentence. */
+  change: string;
+  /** The declared entities behind it, where the reader can name them. */
+  entities?: string[];
+}
+
 /**
  * The deep observation envelope. Explicitly versioned and discriminated by
  * `deepObservation: "v1"`, for the same reason {@link
@@ -119,12 +137,16 @@ export interface DeepObservationResult {
    * surface, not a claim about existence.
    */
   unobserved?: Record<string, UnobservedEntity>;
+  /** Changes an apply would make beyond the declared properties (#3706). Omitted when there are none. */
+  pending?: DeepPendingChange[];
 }
 
 /** Normalized form every consumer works with. Both maps always present. */
 export interface NormalizedDeepObservation {
   resources: Record<string, DeepResourceObservation>;
   unobserved: Record<string, UnobservedEntity>;
+  /** As {@link DeepObservationResult.pending}; absent when there are none. */
+  pending?: DeepPendingChange[];
 }
 
 /** True when `value` is the versioned {@link DeepObservationResult} envelope. */
@@ -140,11 +162,13 @@ export function isDeepObservationResult(value: unknown): value is DeepObservatio
 export function deepObservation(
   resources: Record<string, DeepResourceObservation>,
   unobserved?: Record<string, UnobservedEntity>,
+  pending?: DeepPendingChange[],
 ): DeepObservationResult {
   return {
     deepObservation: "v1",
     resources,
     ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
+    ...(pending && pending.length > 0 ? { pending } : {}),
   };
 }
 
@@ -158,7 +182,11 @@ export function normalizeDeepObservation(
   value: DeepObservationResult | undefined,
 ): NormalizedDeepObservation {
   if (!value) return { resources: {}, unobserved: {} };
-  return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {} };
+  return {
+    resources: value.resources ?? {},
+    unobserved: value.unobserved ?? {},
+    ...(value.pending && value.pending.length > 0 ? { pending: value.pending } : {}),
+  };
 }
 
 // ── Normalization pass ──────────────────────────────────────────────────────

package/src/detectLexicon.test.ts

@@ -257,4 +257,42 @@ describe("detectLexicons", () => {
     const result = await detectLexicons([file]);
     expect(result).toEqual(["testdom"]);
   });
+
+  // chant #3648: a project that imports a lexicon only through a subpath,
+  // as every sql project does, was detected as having no lexicon at all.
+  test.each([
+    {
+      dialect: "clickhouse",
+      code: 'import { table } from "@intentius/chant-lexicon-sql/clickhouse";\nexport const events = table`CREATE TABLE events (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY (id, ts)`;',
+    },
+    {
+      dialect: "postgres",
+      code: 'import { table } from "@intentius/chant-lexicon-sql/postgres";\nexport const events = table`CREATE TABLE events (id bigint PRIMARY KEY, ts timestamptz NOT NULL)`;',
+    },
+  ])("detects sql from a $dialect subpath import (#3648)", async ({ code }) => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(file, code);
+
+    expect(await detectLexicons([file])).toEqual(["sql"]);
+  });
+
+  test("detects a lexicon from a nested subpath and a subpath re-export (#3648)", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import { rule } from "@intentius/chant-lexicon-testdom/lint/post-synth";\nexport * from \'@intentius/chant-lexicon-k8s/composites\';',
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result.sort()).toEqual(["k8s", "testdom"]);
+  });
+
+  test("subpath imports of both sql dialects detect sql once (#3648)", async () => {
+    const ch = join(testDir, "ch.ts");
+    const pg = join(testDir, "pg.ts");
+    await writeFile(ch, 'import { table } from "@intentius/chant-lexicon-sql/clickhouse";');
+    await writeFile(pg, 'import { table } from "@intentius/chant-lexicon-sql/postgres";');
+
+    expect(await detectLexicons([ch, pg])).toEqual(["sql"]);
+  });
 });

package/src/detectLexicon.ts

@@ -19,7 +19,8 @@ export function isNoLexiconDetected(error: unknown): boolean {
 
 /**
  * Detects which lexicons are being used by analyzing import statements
- * in the provided infrastructure files. Matches any `@intentius/chant-lexicon-*` package.
+ * in the provided infrastructure files. Matches any `@intentius/chant-lexicon-*` package,
+ * imported by its root or by a subpath (`@intentius/chant-lexicon-sql/postgres`).
  *
  * @param files - Array of file paths to analyze
  * @returns Array of detected lexicon names
@@ -40,7 +41,11 @@ export async function detectLexicons(files: string[]): Promise<string[]> {
     // Match @intentius/chant-lexicon-<name> in import/export statements.
     // Uses [\s\S] instead of . to handle multiline imports like:
     //   import { Foo, Bar } from "@intentius/chant-lexicon-k8s";
-    const regex = /(?:import|export)\s+[\s\S]*?\s+from\s+['"]@intentius\/chant-lexicon-([a-z][\w-]*)['"]/g;
+    // chant #3648: a subpath import names the same lexicon, so
+    // "@intentius/chant-lexicon-sql/clickhouse" detects "sql". A project that
+    // imports a lexicon only through its subpaths (every sql project) has no
+    // other import for this scan to find.
+    const regex = /(?:import|export)\s+[\s\S]*?\s+from\s+['"]@intentius\/chant-lexicon-([a-z][\w-]*)(?:\/[^'"\s]*)?['"]/g;
 
     for (const match of content.matchAll(regex)) {
       detectedLexicons.add(match[1]);

package/src/lifecycle/deep-diff.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { countHeld, countUnclaimed, countPropertyDrift, diffDeep, suspiciousHeld, type DeclaredDeepEntity } from "./deep-diff";
+import { countHeld, countPending, countUnclaimed, countPropertyDrift, diffDeep, suspiciousHeld, type DeclaredDeepEntity } from "./deep-diff";
 import { UNRESOLVED, type NormalizedDeepObservation } from "../deep-observation";
 import { HELD_ELSEWHERE_TAG } from "../held-elsewhere";
 import type { BaselineLexicon } from "./observation-baseline";
@@ -551,4 +551,27 @@ describe("diffDeep — heldElsewhere() (#2162)", () => {
     });
     expect(suspiciousHeld(result)).toEqual([]);
   });
+
+  test("pending changes the reader reports ride through, sorted, and count apart from property drift (#3706)", () => {
+    const result = diffDeep({
+      declared: { t: { type: "T", properties: { A: 1 } } },
+      live: {
+        ...live({ t: { type: "T", properties: { A: 1 } } }),
+        pending: [
+          { subject: "relation b TO r", change: "GRANT SELECT ON TABLE b TO r", entities: ["readB"] },
+          { subject: "relation a TO w", change: "REVOKE INSERT ON TABLE a FROM w" },
+        ],
+      },
+    });
+    expect(result.pending?.map((p) => p.subject)).toEqual(["relation a TO w", "relation b TO r"]);
+    expect(countPending(result)).toBe(2);
+    expect(countPropertyDrift(result)).toBe(0);
+    expect(result.unchanged).toEqual(["t"]);
+  });
+
+  test("no pending changes leave the field out", () => {
+    const result = diffDeep({ declared: {}, live: live({}) });
+    expect(result.pending).toBeUndefined();
+    expect(countPending(result)).toBe(0);
+  });
 });

package/src/lifecycle/deep-diff.ts

@@ -38,6 +38,7 @@ import {
   deepValueEqual,
   flattenDeepProperties,
   type DeepNormalizationHooks,
+  type DeepPendingChange,
   type NormalizedDeepObservation,
 } from "../deep-observation";
 import { claimedFieldsFromPaths, heldBy, isClaimed, type FieldClaimSource } from "../claimed-fields";
@@ -229,6 +230,12 @@ export interface DeepDiffResult {
   unobserved: UnobservedResource[];
   /** Entities the deep reader returned that were never declared. Sorted. */
   undeclaredEntities: string[];
+  /**
+   * Changes an apply would make that no declared property shows (#3706), as
+   * the reader reported them: privileges granted or revoked by hand, say.
+   * Drift, counted by {@link countPending}. Absent when there are none.
+   */
+  pending?: DeepPendingChange[];
 }
 
 /** A declared entity's property tree, already normalized with the lexicon's hooks. */
@@ -421,6 +428,9 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
     unchanged: unchanged.sort(),
     unobserved: unobserved.sort((a, b) => a.name.localeCompare(b.name)),
     undeclaredEntities: undeclaredEntities.sort(),
+    ...(input.live.pending && input.live.pending.length > 0
+      ? { pending: [...input.live.pending].sort((a, b) => a.subject.localeCompare(b.subject) || a.change.localeCompare(b.change)) }
+      : {}),
   };
 }
 
@@ -429,6 +439,11 @@ export function countPropertyDrift(result: DeepDiffResult): number {
   return result.drifted.reduce((n, e) => n + e.changes.length, 0);
 }
 
+/** The pending changes (#3706): drift, though on no one entity's properties. */
+export function countPending(result: DeepDiffResult): number {
+  return result.pending?.length ?? 0;
+}
+
 /** Total live values on paths no declaration claimed, across every entity (#2160). Never added to the drift count. */
 export function countUnclaimed(result: DeepDiffResult): number {
   return result.unclaimed.reduce((n, e) => n + e.fields.length, 0);

package/src/lifecycle/deep-observe.ts

@@ -23,6 +23,7 @@ import {
   normalizeDeepObservation,
   normalizeDeepProperties,
   type DeepNormalizationHooks,
+  type DeepPendingChange,
   type DeepResourceObservation,
   type NormalizedDeepObservation,
 } from "../deep-observation";
@@ -68,12 +69,14 @@ export function mergeDeepObservations(
 ): NormalizedDeepObservation {
   const resources: Record<string, DeepResourceObservation> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
+  const pending: DeepPendingChange[] = [];
   for (const part of parts) {
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
+    pending.push(...(part.pending ?? []));
   }
   for (const name of Object.keys(resources)) delete unobserved[name];
-  return { resources, unobserved };
+  return { resources, unobserved, ...(pending.length > 0 ? { pending } : {}) };
 }
 
 /**
@@ -189,7 +192,7 @@ export function diffDeepObservation(
 
   return diffDeep({
     declared,
-    live: { resources: normalizedLive, unobserved: live.unobserved },
+    live: { resources: normalizedLive, unobserved: live.unobserved, ...(live.pending ? { pending: live.pending } : {}) },
     baseline,
     hooks,
   });

package/src/lifecycle/git.test.ts

@@ -12,6 +12,7 @@ import {
   listSnapshots,
   getHeadCommit,
   pushLifecycle,
+  pushLifecycleReport,
   StaleLifecycleBranchError,
   appendReleaseRecordLine,
   readReleaseLedgerLines,
@@ -30,6 +31,7 @@ import {
   RefCASConflictError,
   StaleLockError,
 } from "./git";
+import { LIFECYCLE_LOCAL_NOTE } from "./local-note";
 
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
   const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
@@ -417,6 +419,22 @@ describe("lifecycle/git", () => {
     }
   });
 
+  // #3677: no remote is a note, not a failure; a push that lands has no warning.
+  test("pushLifecycleReport: no remote reads as the local note, a landed push as pushed", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+      expect(await pushLifecycleReport({ cwd: dir })).toEqual({ pushed: false, pushWarning: LIFECYCLE_LOCAL_NOTE });
+    });
+    const { clonePath, cleanup } = await setupClonePair();
+    try {
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
+      expect(await pushLifecycleReport({ cwd: clonePath })).toEqual({ pushed: true });
+    } finally {
+      await cleanup();
+    }
+  });
+
   test("subsequent push from same clone (after fetch) succeeds via lease", async () => {
     const { clonePath, cleanup } = await setupClonePair();
     try {

package/src/lifecycle/git.ts

@@ -6,6 +6,7 @@
  */
 import { getRuntime } from "../runtime-adapter";
 import { resolveMemberLedger } from "./member-ledger";
+import { LIFECYCLE_LOCAL_NOTE } from "./local-note";
 
 const STATE_BRANCH = "chant/lifecycle";
 
@@ -776,6 +777,30 @@ export function describeLifecyclePush(result: LifecyclePushStatus): string | nul
   }
 }
 
+/**
+ * Push the ledger branch and say, in one line, why it did not land (#2310,
+ * #3677). No remote reads as {@link LIFECYCLE_LOCAL_NOTE}; a push that git
+ * refused or that failed keeps its own reason, so a renderer can warn about
+ * that case alone. Never throws.
+ */
+export async function pushLifecycleReport(opts?: { cwd?: string }): Promise<{ pushed: boolean; pushWarning?: string }> {
+  try {
+    const result = await pushLifecycleStatus(opts);
+    switch (result.status) {
+      case "pushed":
+        return { pushed: true };
+      case "no-remote":
+        return { pushed: false, pushWarning: LIFECYCLE_LOCAL_NOTE };
+      case "stale":
+        return { pushed: false, pushWarning: new StaleLifecycleBranchError(result.expected, result.stderr).message };
+      case "failed":
+        return { pushed: false, pushWarning: describeLifecyclePush(result) ?? "the push did not land" };
+    }
+  } catch (err) {
+    return { pushed: false, pushWarning: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 /**
  * Fetch the state branch from remote.
  */

package/src/lifecycle/local-note.ts

@@ -0,0 +1,17 @@
+/**
+ * What a ledger write shows when the checkout has no remote (#3677), kept
+ * apart from `./git.ts` so the run renderers can name it without loading git.
+ */
+
+/**
+ * The line a write shows when this checkout has no remote for the ledger.
+ * Nothing went wrong: the record is in the local branch, and with no remote
+ * the person who will approve or read it is the one at this machine. A
+ * renderer prints it as a note, never as a warning ({@link isLifecycleLocalNote}).
+ */
+export const LIFECYCLE_LOCAL_NOTE = "recorded locally (no remote for chant/lifecycle)";
+
+/** Whether a push warning is {@link LIFECYCLE_LOCAL_NOTE}: no remote, rather than a push that failed. */
+export function isLifecycleLocalNote(warning: string | undefined): boolean {
+  return warning === LIFECYCLE_LOCAL_NOTE;
+}