@intentius/chant 0.72.3 → 0.72.4

package/src/cli/mcp/server.ts

@@ -17,8 +17,12 @@ import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
  * Protocol versions this server understands, newest first. `initialize` and
  * `server/discover` both negotiate against this list rather than assuming
  * the client's revision (#1194).
+ *
+ * Exported because `docs-parity.test.ts` reads it: `cli/mcp.mdx` states these
+ * revisions in prose, and stating them twice is how the page came to claim
+ * 2024-11-05 for two releases after this list moved past it (#2385).
  */
-const SUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28", "2024-11-05"] as const;
+export const SUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28", "2024-11-05"] as const;
 const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
 
 /**

package/src/cli/mcp-config.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from "vitest";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { initCommand } from "./commands/init";
+import { doctorCommand } from "./commands/doctor";
+import { updateCommand } from "./commands/update";
+import { parseArgs, commandRegistry } from "./main";
+import { MCP_CONFIG_FILENAME, MCP_SETUP_COMMAND, mcpConfigPath } from "./mcp-config";
+
+/**
+ * chant #2383. `chant init` used to write `mcp.json` into the user's home
+ * directory while `chant doctor` looked for `<project>/.mcp.json` and told
+ * you to run `chant agent setup`, a command the registry never had. Three
+ * sites, three answers, and a project chant had just scaffolded failed
+ * chant's own doctor with an unrunnable fix.
+ *
+ * These tests are written against the agreement rather than against today's
+ * string: the round trip below fails if init and doctor ever pick different
+ * paths again, and the registry check fails if the remediation ever names a
+ * command that is not registered. Neither can be satisfied by editing one
+ * site in isolation.
+ */
+describe("MCP config: one location, three agreeing sites (#2383)", () => {
+  test("init then doctor round-trips: mcp-config passes with no manual step", async () => {
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipInstall: true,
+      });
+      expect(result.success).toBe(true);
+
+      const report = await doctorCommand(testDir);
+      const check = report.checks.find((c) => c.name === "mcp-config");
+      expect(check).toBeDefined();
+      expect(check!.status).toBe("pass");
+    });
+  });
+
+  test("init writes the MCP config inside the project it was pointed at", async () => {
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipInstall: true,
+      });
+
+      expect(existsSync(mcpConfigPath(testDir))).toBe(true);
+      expect(result.createdFiles).toContain(MCP_CONFIG_FILENAME);
+
+      const config = JSON.parse(readFileSync(mcpConfigPath(testDir), "utf-8"));
+      expect(config.mcpServers.chant.args).toEqual(["chant", "serve", "mcp"]);
+
+      // Every path init reports as created is relative to the project. A
+      // `~/` or absolute entry means init reached outside the directory it
+      // was handed, which is the half of #2383 worth not regressing.
+      for (const file of result.createdFiles) {
+        expect(file.startsWith("~"), `${file} escapes the project`).toBe(false);
+        expect(file.startsWith("/"), `${file} escapes the project`).toBe(false);
+        expect(file.includes(homedir()), `${file} escapes the project`).toBe(false);
+      }
+    });
+  });
+
+  test("--skip-mcp parses and suppresses the write", async () => {
+    // The flag was documented and typed long before anything parsed it, so
+    // assert the parse and the effect together — either one alone passed
+    // while `chant init --skip-mcp` still wrote the file.
+    expect(parseArgs(["init", ".", "--lexicon", "aws", "--skip-mcp"]).skipMcp).toBe(true);
+    expect(parseArgs(["init", ".", "--lexicon", "aws"]).skipMcp).toBeUndefined();
+
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "aws",
+        skipMcp: true,
+        skipInstall: true,
+      });
+      expect(existsSync(mcpConfigPath(testDir))).toBe(false);
+      expect(result.createdFiles).not.toContain(MCP_CONFIG_FILENAME);
+    });
+  });
+
+  test("the doctor's remediation names a registered command", async () => {
+    // Reconstruct the warning the doctor actually emits, then check that the
+    // command inside it exists. `chant agent setup` satisfied neither.
+    await withTestDir(async (testDir) => {
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      const report = await doctorCommand(testDir);
+      const check = report.checks.find((c) => c.name === "mcp-config");
+      expect(check!.status).toBe("warn");
+      expect(check!.message).toContain(MCP_SETUP_COMMAND);
+
+      const named = check!.message!.match(/run ([a-z][a-z -]*)/)?.[1].trim();
+      expect(named).toBeDefined();
+      expect(named!.startsWith("chant ")).toBe(true);
+      const registered = commandRegistry.map((c) => c.name);
+      expect(registered).toContain(named!.slice("chant ".length));
+    });
+  });
+
+  test("the remediation command restores a deleted config", async () => {
+    await withTestDir(async (testDir) => {
+      // A project that has everything except the MCP config: exactly the
+      // state the doctor warns about. `chant init` refuses this directory
+      // without --force, so the remediation has to be something else.
+      mkdirSync(join(testDir, "src"), { recursive: true });
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(testDir, "package.json"), JSON.stringify({ name: "p", type: "module" }));
+
+      expect(MCP_SETUP_COMMAND).toBe("chant update");
+      const result = await updateCommand({ path: testDir });
+      expect(result.success).toBe(true);
+
+      const report = await doctorCommand(testDir);
+      expect(report.checks.find((c) => c.name === "mcp-config")!.status).toBe("pass");
+    });
+  });
+
+  test("update leaves an existing config alone", async () => {
+    await withTestDir(async (testDir) => {
+      writeFileSync(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(testDir, "package.json"), JSON.stringify({ name: "p", type: "module" }));
+      const hand = JSON.stringify({ mcpServers: { chant: { command: "custom" } } }, null, 2);
+      writeFileSync(mcpConfigPath(testDir), hand);
+
+      await updateCommand({ path: testDir });
+
+      expect(readFileSync(mcpConfigPath(testDir), "utf-8")).toBe(hand);
+    });
+  });
+
+  test("every chant command a doctor check tells you to run is registered", async () => {
+    // Broader than the mcp-config check that prompted #2383: whatever the
+    // doctor prints as `run chant <something>`, the registry has to have it.
+    // `chant agent setup` shipped as advice for a command that never existed;
+    // this fails the moment any check does that again.
+    const registered = commandRegistry.map((c) => c.name);
+    expect(registered).not.toContain("agent");
+    expect(registered).not.toContain("agent setup");
+
+    const messages: string[] = [];
+    await withTestDir(async (empty) => {
+      messages.push(...(await doctorCommand(empty)).checks.flatMap((c) => c.message ?? []));
+    });
+    await withTestDir(async (partial) => {
+      writeFileSync(join(partial, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+      writeFileSync(join(partial, "package.json"), JSON.stringify({ name: "p" }));
+      mkdirSync(join(partial, "src"), { recursive: true });
+      messages.push(...(await doctorCommand(partial)).checks.flatMap((c) => c.message ?? []));
+    });
+
+    const named = messages.flatMap((m) => [...m.matchAll(/run `?(chant [a-z][a-z0-9 -]*)/g)].map((x) => x[1]));
+    expect(named.length).toBeGreaterThan(0);
+    for (const advice of named) {
+      // Drop flags and the trailing prose the regex may have swept up, then
+      // keep the longest registered name that prefixes what was advised.
+      const words = advice.slice("chant ".length).split(/\s+/).filter((w) => w && !w.startsWith("-"));
+      const match = registered.find((name) => {
+        const parts = name.split(" ");
+        return parts.every((p, i) => words[i] === p);
+      });
+      expect(match, `doctor advises "${advice}", which no registered command matches`).toBeDefined();
+    }
+  });
+});

package/src/cli/mcp-config.ts

@@ -0,0 +1,76 @@
+import { existsSync, writeFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * The one place chant decides where a project's MCP server registration
+ * lives, what goes in it, and which command writes it (chant #2383).
+ *
+ * Before this module the three sites disagreed: `chant init` wrote
+ * `mcp.json` into the user's home directory (picking a harness directory
+ * that happened to exist), `chant doctor` looked for `<project>/.mcp.json`,
+ * and the doctor's remediation named `chant agent setup`, which was never
+ * registered in `./main.ts`. A project chant had just scaffolded therefore
+ * failed chant's own doctor, and the fix the warning named could not be run.
+ *
+ * Project scope wins. The file versions with the project it describes, it
+ * keeps `chant init <dir>` from writing outside `<dir>`, and it is already
+ * what `../agents/discover.ts` treats as the project-scope location when
+ * chant audits an agent installation it did not create. Every consumer must
+ * go through the constants here rather than rebuilding the path, so the
+ * three sites cannot drift apart again without the shared test in
+ * ./mcp-config.test.ts noticing.
+ */
+
+/** Filename of the project-scoped MCP server registration. */
+export const MCP_CONFIG_FILENAME = ".mcp.json";
+
+/**
+ * The command a user runs to (re)write a missing {@link MCP_CONFIG_FILENAME}
+ * in an existing project. `chant init` also writes it, but init refuses a
+ * non-empty directory without `--force`, so the remediation an already
+ * scaffolded project needs is `chant update` — which is also what the
+ * doctor's neighbouring skills check tells you to run for the same reason.
+ * Kept as a constant so ./mcp-config.test.ts can assert it is a command
+ * `commandRegistry` actually registers.
+ */
+export const MCP_SETUP_COMMAND = "chant update";
+
+/** Absolute (or caller-relative) path to a project's MCP config. */
+export function mcpConfigPath(projectDir: string): string {
+  return join(projectDir, MCP_CONFIG_FILENAME);
+}
+
+/**
+ * Detect whether a project uses bun or npm, from its lock file. Lives here
+ * because the package manager is the only variable in the generated config.
+ */
+export function detectPackageManager(dir?: string): "bun" | "npm" {
+  if (dir && (existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")))) return "bun";
+  return "npm";
+}
+
+/** The MCP registration chant writes: one stdio server named `chant`. */
+export function generateMcpConfig(pm: "bun" | "npm"): string {
+  const config = {
+    mcpServers: {
+      chant: {
+        command: pm === "bun" ? "bunx" : "npx",
+        args: ["chant", "serve", "mcp"],
+      },
+    },
+  };
+
+  return JSON.stringify(config, null, 2);
+}
+
+/**
+ * Write `<projectDir>/.mcp.json` unless one is already there. Returns the
+ * relative path when a file was created, `undefined` when an existing config
+ * was left alone — callers report that difference to the user.
+ */
+export function writeProjectMcpConfig(projectDir: string): string | undefined {
+  const path = mcpConfigPath(projectDir);
+  if (existsSync(path)) return undefined;
+  writeFileSync(path, generateMcpConfig(detectPackageManager(projectDir)));
+  return MCP_CONFIG_FILENAME;
+}

package/src/cli/registry.ts

@@ -101,6 +101,12 @@ export interface ParsedArgs {
   reportFile?: string;
   /** `chant init --skill <name>` filter (added in #95 commit) */
   skill?: string;
+  /**
+   * `chant init --skip-mcp` (#2383) — scaffold without writing the project's
+   * `.mcp.json`. The option existed on `InitOptions` and was documented long
+   * before anything parsed it, so there was no way to decline the write.
+   */
+  skipMcp?: boolean;
   /** `chant import --type <ResourceType>` selector */
   selectType?: string;
   /** `chant import --name <name>` selector */

package/src/discovery/sandbox/fork-diagnostic.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from "vitest";
+import { fork } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runFallbackFilesSandboxed } from "./run";
+
+/**
+ * chant#2461 — a child that ends without a usable result says which way it did.
+ *
+ * The parent had one sentence for three unrelated situations: `child exited
+ * before reporting results (code N, signal S)`. The one seen in the wild is the
+ * hardest to read — exit code 0, empty stderr, no message — because it reads as
+ * if the child was cut off, and it was not. It ran to completion and sent
+ * nothing.
+ *
+ * These tests pin the two mechanisms that produce that signature, against real
+ * forked children rather than a mock, because the whole question is what Node
+ * actually does:
+ *
+ *   - an `await` that never settles, which drains the loop and exits 0
+ *   - a payload the parent's `isResponse` refuses, which used to be dropped in
+ *     silence and then reported as though nothing had been sent
+ *
+ * A third mechanism was proposed in the issue and is NOT covered, because it
+ * was measured and does not happen: `process.send` racing the child's reap so
+ * that `exit` is dispatched before an already-queued `message`. With the parent
+ * blocked so both were certainly pending, `message` won 60 times out of 60. The
+ * live IPC channel keeps the child alive until the payload flushes, and the
+ * driver has no `process.exit()` to cut that short. The last test here records
+ * that, so the disproof is not lost with the transcript.
+ */
+function runChild(source: string): Promise<{ code: number | null; message: unknown; stderr: string }> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-fork-diag-"));
+  const file = join(dir, "child.mjs");
+  writeFileSync(file, source);
+  return new Promise((resolve) => {
+    const child = fork(file, [], { stdio: ["ignore", "pipe", "pipe", "ipc"] });
+    let stderr = "";
+    let message: unknown;
+    child.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); });
+    child.on("message", (m) => { message = m; });
+    child.on("exit", (code) => {
+      rmSync(dir, { recursive: true, force: true });
+      resolve({ code, message, stderr });
+    });
+  });
+}
+
+describe("why a sandboxed child ends without a result (chant#2461)", () => {
+  test("an await that never settles exits 0, silently, having sent nothing", async () => {
+    // The observed signature, reproduced. `main().catch(...)` catches a
+    // REJECTION; a promise that never settles is not one, so the driver's own
+    // fatal-payload path never runs either.
+    const r = await runChild(
+      'async function main() { await new Promise(() => {}); process.send({ ok: true }); }\n' +
+        "main().catch((e) => process.send({ fatal: String(e) }));\n",
+    );
+
+    expect(r.code).toBe(0);
+    expect(r.message).toBeUndefined();
+    expect(r.stderr.trim()).toBe("");
+  });
+
+  test("a child that sends and falls off the end always gets its message through", async () => {
+    // The disproof, kept as a test. If this ever fails, the race the issue
+    // proposed is real after all and the diagnostic's wording needs revisiting.
+    const results = await Promise.all(
+      Array.from({ length: 12 }, () => runChild("process.send({ ok: true });\n")),
+    );
+
+    for (const r of results) {
+      expect(r.code).toBe(0);
+      expect(r.message).toEqual({ ok: true });
+    }
+  });
+
+  test("a rejection still reaches the parent, so the fatal path is not what broke", async () => {
+    // Establishes the contrast: the driver's catch works. It is specifically an
+    // unsettled promise that escapes it.
+    const r = await runChild(
+      'async function main() { throw new Error("boom"); }\n' +
+        "main().catch((e) => process.send({ fatal: String(e) }));\n",
+    );
+
+    expect(r.message).toEqual({ fatal: "Error: boom" });
+  });
+
+  test("a project file with an unsettled top-level await reproduces it end to end", async () => {
+    // The run path's real mechanism, not a stand-in. `main()` does
+    // `await import(<project file>)` per run-fallback file, module scope is
+    // arbitrary project source, and a top level that awaits something which
+    // never settles makes that import never complete. Nothing keeps the loop
+    // alive, so Node exits 0 having sent nothing.
+    //
+    // This is what the diagnostic's wording is checked against. Before
+    // chant#2461 it said only "child exited before reporting results", which
+    // gave a reader nothing to look at.
+    const root = mkdtempSync(join(tmpdir(), "chant-tla-"));
+    try {
+      mkdirSync(join(root, "src"), { recursive: true });
+      writeFileSync(
+        join(root, "src", "hangs.ts"),
+        "await new Promise<void>(() => {});\nexport const never = { reached: true };\n",
+      );
+
+      const result = await runFallbackFilesSandboxed([join(root, "src", "hangs.ts")], root);
+
+      const message = result.errors.map((e) => e.message).join("\n");
+      expect(message).toContain("child exited before reporting results (code 0, signal null)");
+      expect(message).toContain("drained its loop without sending");
+      expect(message).toContain("top-level");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }, 120_000);
+});

package/src/discovery/sandbox/fork.ts

@@ -125,6 +125,86 @@ function lineBuffered(emit: (line: string) => void) {
  * resolve with the first IPC message that satisfies `isResponse` (or reject
  * on crash / timeout / fork error).
  */
+/**
+ * Why a child ended without a usable result, in terms a reader can act on.
+ *
+ * chant#2461 — this used to be one sentence, `child exited before reporting
+ * results (code N, signal S)`, for three unrelated situations. The one that
+ * was observed in the wild is the hardest to read: exit code 0, empty stderr,
+ * no message. That reads like the child was cut off, and it was not — it ran
+ * to completion and sent nothing.
+ *
+ * Two mechanisms produce it, and the driver decides which is possible.
+ *
+ * The first is an `await` that never settles. `main().catch(...)` catches a
+ * REJECTION, and a promise that never settles is not one, so if nothing keeps
+ * the loop alive Node drains it and exits 0 having sent nothing and written
+ * nothing. Nothing else in the process reports that.
+ *
+ * On the RUN path that is not hypothetical, and it is reproducible: the driver
+ * does `await import(<project file>)` for each run-fallback file, module scope
+ * is arbitrary project source, and a file whose top level awaits something that
+ * never settles makes that import never complete. A fixture doing exactly that
+ * yields this error, which is how the wording here was checked rather than
+ * guessed.
+ *
+ * The second is the payload being lost between `process.send` and exit.
+ *
+ * For the CONFIG driver the first is impossible, which is worth stating because
+ * it was the working hypothesis until the bundle was read. Its `await
+ * import(configPath)` bundles to `await Promise.resolve().then(() =>
+ * (init_chant_config(), chant_config_exports))` — one microtask over
+ * synchronous code — and the bundle has no runtime imports, no dynamic
+ * `import(`, and exactly one `process.send`. There is nothing there to hang on.
+ * So a config child that exits 0 with nothing sent DID send, and the payload
+ * did not arrive.
+ *
+ * The exit/message race originally proposed in chant#2461 is a third thing and
+ * is not it: with the parent blocked so a queued payload and the reap were both
+ * pending, `message` was dispatched first 60 times out of 60, because the live
+ * IPC channel keeps the child alive until the payload flushes.
+ */
+function describeSilentExit(
+  label: string,
+  code: number | null,
+  signal: NodeJS.Signals | null,
+  stderrBuf: string,
+  unrecognised: readonly unknown[],
+): string {
+  const stderr = stderrBuf.trim();
+  const head = `${label}: child exited before reporting results (code ${code}, signal ${signal})`;
+
+  if (unrecognised.length > 0) {
+    // It DID send. The parent refused the shape, which is a bug in one of them
+    // and not the child dying early.
+    const shapes = unrecognised
+      .map((m) => (m && typeof m === "object" ? `{${Object.keys(m as object).join(", ")}}` : typeof m))
+      .join(", ");
+    return (
+      `${head}. It sent ${unrecognised.length} message(s) the parent did not recognise (${shapes}), ` +
+      `so the payload shape and the parent's check disagree` +
+      (stderr ? `: ${stderr}` : "")
+    );
+  }
+
+  if (stderr) return `${head}: ${stderr}`;
+  if (code !== 0 || signal !== null) return head;
+
+  // Exit 0, nothing on stderr, nothing sent. The child finished normally and
+  // the parent has nothing. Two mechanisms produce exactly this, and which one
+  // it is depends on the driver — see this function's doc.
+  return (
+    `${head}. It exited cleanly with nothing on stderr and sent no message, so the child drained ` +
+    `its loop without sending: something it awaited never settled. On the run path the usual ` +
+    `cause is a project file with a top-level \`await\` that does not settle — module scope is ` +
+    `arbitrary project source, and an import of such a file never completes. A promise that ` +
+    `never settles is not a rejection, so the driver's own \`main().catch\` does not see it ` +
+    `either, which is why nothing is written anywhere. The config driver bundles to one ` +
+    `microtask over synchronous code with no runtime I/O, so on THAT path nothing can hang and ` +
+    `the payload was lost between \`process.send\` and exit instead (chant#2461).`
+  );
+}
+
 export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
@@ -144,6 +224,8 @@ export function forkSandboxed<T>(
 
     let settled = false;
     let stderrBuf = "";
+    /** Messages the child sent that `isResponse` refused — see the `message` handler. */
+    const unrecognised: unknown[] = [];
 
     const timeout = setTimeout(() => {
       if (settled) return;
@@ -185,7 +267,15 @@ export function forkSandboxed<T>(
     child.stderr?.on("end", () => stderrForwarder.flush());
 
     child.on("message", (msg: unknown) => {
-      if (settled || !isResponse(msg)) return;
+      if (settled) return;
+      if (!isResponse(msg)) {
+        // chant#2461 — remember it rather than dropping it. A child that sent
+        // something the parent does not recognise is a different failure from
+        // a child that sent nothing, and both used to arrive as "exited before
+        // reporting results" with no way to tell them apart.
+        unrecognised.push(msg);
+        return;
+      }
       settled = true;
       clearTimeout(timeout);
       // chant #1131 — the child's entire job is to send this one message, so
@@ -212,11 +302,7 @@ export function forkSandboxed<T>(
       if (settled) return;
       settled = true;
       clearTimeout(timeout);
-      reject(
-        new Error(
-          `${label}: child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`,
-        ),
-      );
+      reject(new Error(describeSilentExit(label, code, signal, stderrBuf, unrecognised)));
     });
   });
 }

package/src/observation.ts

@@ -57,14 +57,33 @@ export type UnobservedReason =
   | "unsupported-kind"
   | "filtered";
 
-/** Every legal {@link UnobservedReason}, for validation and conformance checks. */
-export const UNOBSERVED_REASONS: readonly UnobservedReason[] = [
-  "read-failed",
-  "no-credentials",
-  "no-binding",
-  "unsupported-kind",
-  "filtered",
-];
+/**
+ * Every legal {@link UnobservedReason}, for validation and conformance checks.
+ *
+ * Derived from a witness keyed off the union rather than written out beside it
+ * (chant#2366). A hand-maintained array is only ever checked for holding legal
+ * members, never for holding ALL of them, so a reason added to the type left
+ * the array silently short — `tsc` clean, every observation test green, and a
+ * value the type permits that `observation-conformance.ts` refuses. A lexicon
+ * could construct a value its own suite rejected.
+ *
+ * Keying a `Record` off the union makes the omission a compile error at the
+ * point of the omission. This is the construction #2365 applied to all four
+ * closed sets in `./behaviour.ts`; `BEHAVIOUR_UNPREDICTED_REASONS` derives from
+ * this very type, so that module was already protected against a change here
+ * while this module was not.
+ */
+const UNOBSERVED_REASON_WITNESS: Record<UnobservedReason, true> = {
+  "read-failed": true,
+  "no-credentials": true,
+  "no-binding": true,
+  "unsupported-kind": true,
+  filtered: true,
+};
+
+export const UNOBSERVED_REASONS: readonly UnobservedReason[] = Object.keys(
+  UNOBSERVED_REASON_WITNESS,
+) as UnobservedReason[];
 
 /** True when `value` is a legal {@link UnobservedReason}. */
 export function isUnobservedReason(value: unknown): value is UnobservedReason {

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

@@ -0,0 +1,101 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+/**
+ * chant#2337 — a converge tick says whether its record reached the remote.
+ *
+ * `convergeTick` ended with `await pushLifecycle().catch(() => undefined)`, the
+ * last instance of the idiom #2310 was filed about. The append is local-first
+ * and always lands, so the tick's own result was correct either way — what was
+ * missing is whether anyone else can see it.
+ *
+ * Softer than the gate's version of the same bug, which #2336 fixed: a lost
+ * tick record is an informational log rather than an approval, so nobody is
+ * left waiting on a fact they cannot see. It is still not success, and a
+ * converge loop reporting a clean tick while its ledger never leaves the
+ * machine is telling an operator something untrue.
+ */
+const execMock = vi.fn();
+vi.mock("node:child_process", () => ({
+  exec: (cmd: string, _opts: unknown, cb: (e: Error | null, r: { stdout: string; stderr: string }) => void) =>
+    cb(null, { stdout: execMock(cmd) as string, stderr: "" }),
+}));
+
+const pushLifecycle = vi.fn();
+vi.mock("../../lifecycle/git", () => ({
+  fetchLifecycle: vi.fn(async () => undefined),
+  pushLifecycle: (...args: unknown[]) => pushLifecycle(...args) as Promise<boolean>,
+}));
+
+vi.mock("../../lifecycle/converge-ledger", async (orig) => {
+  const actual = (await orig()) as Record<string, unknown>;
+  return {
+    ...actual,
+    readConvergeLedger: vi.fn(async () => ({ records: [] })),
+    appendConvergeRecord: vi.fn(async (record: Record<string, unknown>) => ({
+      record: { ...record, id: "tick-1" },
+    })),
+  };
+});
+
+const { convergeTick } = await import("./converge");
+
+/** A tick with nothing to do: no drift, no rules, so only the ledger write matters. */
+async function tick(): Promise<Awaited<ReturnType<typeof convergeTick>>> {
+  return convergeTick({ opName: "demo", env: "prod", rules: [], dial: "report" } as never);
+}
+
+describe("a converge tick reports its push outcome (chant#2337)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    execMock.mockImplementation((cmd: string) =>
+      cmd.includes("lifecycle plan")
+        ? JSON.stringify({ env: "prod", entries: [] })
+        : JSON.stringify([]),
+    );
+  });
+
+  test("a push that lands reports pushed, with no warning", async () => {
+    pushLifecycle.mockResolvedValue(true);
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(true);
+    expect(result.pushWarning).toBeUndefined();
+  });
+
+  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"));
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(false);
+    expect(result.pushWarning).toContain("remote rejected");
+  });
+
+  test("no remote configured is reported too, and says which it is", async () => {
+    // `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);
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(false);
+    expect(result.pushWarning).toMatch(/no remote/i);
+  });
+
+  test("the tick's own findings are unaffected by a failed push", async () => {
+    // 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"));
+
+    const result = await tick();
+
+    expect(result.id).toBe("tick-1");
+    expect(result.drifted).toBe(false);
+    expect(typeof result.log).toBe("string");
+  });
+});