@intentius/chant 0.1.7 → 0.1.8

package/src/cli/main.test.ts

@@ -198,6 +198,7 @@ describe("resolveCommand", () => {
       watch: false,
       verbose: false,
       help: false,
+      live: false,
       ...overrides,
     };
   }

package/src/cli/main.ts

@@ -36,6 +36,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     help: false,
     profile: undefined,
     report: undefined,
+    live: false,
   };
 
   let i = 0;
@@ -64,6 +65,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.profile = args[++i];
     } else if (arg === "--report") {
       result.report = true;
+    } else if (arg === "--live") {
+      result.live = true;
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -114,6 +117,7 @@ State:
   state snapshot <env>  Query API, save metadata to orphan branch
   state show <env>      Show latest state snapshot
   state diff <env>      Compare current build against last snapshot
+                        --live: query cloud now and detect drift
   state log [env]       History of state snapshots
 
 Lexicon development:

package/src/cli/mcp/tools/search.ts

@@ -52,7 +52,12 @@ export function createSearchHandler(
 
     for (const plugin of candidates) {
       const resources = plugin.mcpResources?.() ?? [];
-      const catalog = resources.find((r) => r.uri === "resource-catalog");
+      // Catalog URIs were unscoped ("resource-catalog") before lexicon
+      // namespacing landed; new lexicons emit "<lexicon>:resource-catalog"
+      // to avoid cross-lexicon collision. Support both.
+      const catalog = resources.find(
+        (r) => r.uri === "resource-catalog" || r.uri.endsWith(":resource-catalog"),
+      );
       if (!catalog) continue;
 
       let entries: CatalogEntry[];

package/src/cli/registry.ts

@@ -20,6 +20,7 @@ export interface ParsedArgs {
   help: boolean;
   profile?: string;
   report?: boolean;
+  live: boolean;
 }
 
 /**

package/src/lexicon-plugin-helpers.ts

@@ -61,15 +61,18 @@ export function createSkillsLoader(
 /**
  * Create an MCP diff tool contribution for a lexicon.
  *
- * All lexicons (except Azure) expose an identical "diff" tool that compares
- * current build output against previous output using the lexicon's serializer.
+ * All lexicons (except Azure) expose an identical-shape "diff" tool that
+ * compares current build output against previous output using the lexicon's
+ * serializer. The tool name is namespaced by `lexiconName` (e.g. `gcp:diff`)
+ * so multiple lexicons loaded together don't collide on the same tool key.
  */
 export function createDiffTool(
   serializer: Serializer,
   description: string,
+  lexiconName: string,
 ): McpToolContribution {
   return {
-    name: "diff",
+    name: `${lexiconName}:diff`,
     description,
     inputSchema: {
       type: "object" as const,
@@ -96,21 +99,26 @@ export function createDiffTool(
 /**
  * Create an MCP resource that serves the lexicon's meta.json as a catalog.
  *
- * Most lexicons expose a "resource-catalog" resource with identical structure.
+ * Most lexicons expose a "resource-catalog" resource with identical
+ * structure. The URI is namespaced by `lexiconName` (e.g.
+ * `gcp:resource-catalog`) so multiple lexicons loaded together don't
+ * collide on the same resource key.
  *
  * @param importMetaUrl — The plugin's import.meta.url (used to locate generated JSON)
  * @param name — Display name (e.g. "AWS Resource Catalog")
  * @param description — Resource description
  * @param lexiconJsonFile — Filename of the generated lexicon JSON (e.g. "lexicon-aws.json")
+ * @param lexiconName — Short lexicon name (e.g. "aws", "gcp"). Becomes the URI prefix.
  */
 export function createCatalogResource(
   importMetaUrl: string,
   name: string,
   description: string,
   lexiconJsonFile: string,
+  lexiconName: string,
 ): McpResourceContribution {
   return {
-    uri: "resource-catalog",
+    uri: `${lexiconName}:resource-catalog`,
     name,
     description,
     mimeType: "application/json",

package/src/lexicon.ts

@@ -195,12 +195,48 @@ export interface LexiconPlugin {
   mcpResources?(): McpResourceContribution[];
 
   // State
-  /** Query deployed resources and return API metadata. Opt-in. */
+  /**
+   * Query deployed resources and return API metadata. Opt-in.
+   *
+   * Use this when each chant entity has a 1:1 cloud equivalent — e.g. an
+   * AWS CFN resource, a K8s object, an ARM resource, a Temporal namespace.
+   *
+   * `entities` carries the chant-side entity declarations for this lexicon,
+   * keyed by chant entity name (e.g. the export name from a `*.ts` file).
+   * Implementations that need to map cloud-side names back to chant entity
+   * names (e.g. Temporal — server-side namespace `prod` ↔ chant entity `ns`
+   * declared with `name: "prod"`) read this; implementations that already
+   * have name parity (e.g. AWS CloudFormation logical IDs == chant entity
+   * names) can ignore it.
+   *
+   * `entityNames` is preserved as a convenience for the simple case.
+   */
   describeResources?(options: {
     environment: string;
     buildOutput: string;
     entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
   }): Promise<Record<string, ResourceMetadata>>;
+
+  /**
+   * List runtime artifacts in the given environment. Opt-in.
+   *
+   * Use this for lexicons whose chant entities describe *authoring*
+   * primitives rather than 1:1 cloud resources — e.g. Helm (charts vs
+   * releases), Docker (Compose vs running containers), Flyway (migration
+   * scripts vs applied migrations). The contract is context-keyed: given an
+   * environment, list all artifacts visible there. There is no `declared`
+   * comparison axis — `state diff --live` reports added/removed/changed
+   * between snapshots, not vs. declared.
+   *
+   * `entities` is passed for cases where the lexicon needs to know what
+   * was declared in order to enumerate (e.g. Flyway needs the declared
+   * `Flyway::Environment` entities to know which DBs to query).
+   */
+  listArtifacts?(options: {
+    environment: string;
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  }): Promise<Record<string, ArtifactMetadata>>;
 }
 
 /**
@@ -219,6 +255,26 @@ export interface ResourceMetadata {
   attributes?: Record<string, unknown>;
 }
 
+/**
+ * Metadata about a runtime artifact, returned by listArtifacts. Same shape
+ * as ResourceMetadata; the conceptual distinction is whether the lexicon's
+ * chant entities have 1:1 runtime equivalents (resources) or whether the
+ * runtime artifacts are created by tooling outside chant's entity model
+ * (artifacts — e.g. Helm releases, Docker containers, Flyway migrations).
+ */
+export interface ArtifactMetadata {
+  /** Artifact type (e.g. Helm::Release, Docker::Container) */
+  type: string;
+  /** Server-side identifier */
+  physicalId?: string;
+  /** Provider-specific status string */
+  status: string;
+  /** ISO timestamp of last update */
+  lastUpdated?: string;
+  /** Provider-specific properties */
+  attributes?: Record<string, unknown>;
+}
+
 /**
  * Type guard to check if a value is a LexiconPlugin.
  * Checks for required lifecycle methods in addition to name/serializer.

package/src/lint/config.test.ts

@@ -641,4 +641,25 @@ describe("loadConfig", () => {
     const config = loadConfig(subDir);
     expect(config).toEqual(DEFAULT_CONFIG);
   });
+
+  test("accepts ChantConfig-shape nested lint key in chant.config.json", () => {
+    const configPath = join(TEST_DIR, "chant.config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        lexicons: ["aws"],
+        lint: {
+          rules: {
+            "test-rule": "error",
+            "noisy-rule": "off",
+          },
+        },
+      }),
+    );
+
+    const config = loadConfig(TEST_DIR);
+
+    expect(config.rules?.["test-rule"]).toBe("error");
+    expect(config.rules?.["noisy-rule"]).toBe("off");
+  });
 });

package/src/lint/config.ts

@@ -223,18 +223,34 @@ function loadConfigFile(configPath: string, visited: Set<string> = new Set()): L
     throw new Error(`Failed to read config file ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
   }
 
-  let config: LintConfig;
+  let raw: unknown;
   try {
-    config = JSON.parse(content);
+    raw = JSON.parse(content);
   } catch (err) {
     throw new Error(`Failed to parse config file ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
   }
 
   // Validate config structure
-  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error(`Invalid config file ${configPath}: must be an object`);
   }
 
+  // Accept both shapes: lint fields at top level (legacy) OR nested under a
+  // "lint" key (matches chant.config.ts ChantConfig shape). When the JSON has
+  // both a top-level "rules"/"extends"/etc AND a "lint": {...}, prefer the
+  // nested one — that matches the explicit ChantConfig contract.
+  const rawObj = raw as Record<string, unknown>;
+  let config: LintConfig;
+  if (
+    rawObj.lint &&
+    typeof rawObj.lint === "object" &&
+    !Array.isArray(rawObj.lint)
+  ) {
+    config = rawObj.lint as LintConfig;
+  } else {
+    config = rawObj as LintConfig;
+  }
+
   // Validate with Zod schema
   const parseResult = LintConfigSchema.safeParse(config);
   if (!parseResult.success) {

package/src/op/types.ts

@@ -46,6 +46,19 @@ export interface ActivityStep {
    * Default: "fastIdempotent"
    */
   profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate";
+  /**
+   * Surface this activity's return value as a workflow search attribute.
+   *
+   * The serializer captures the awaited result into a temporary, then emits
+   * `upsertSearchAttributes({ <name>: [String(<from-path>)] })` immediately
+   * after. Useful for filtering runs by outcome (e.g. `Drift: "true"/"false"`
+   * from a stateDiff activity).
+   *
+   * `from` is a dot-path into the return value (e.g. `"drifted"` for
+   * `{ drifted: boolean }`); when omitted, the whole return value is
+   * stringified.
+   */
+  outcomeAttribute?: { name: string; from?: string };
 }
 
 export interface GateStep {

package/src/state/digest.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from "vitest";
+import { computeBuildDigest, diffDigests, hashProps } from "./digest";
+import type { BuildResult } from "../build";
+import type { BuildDigest } from "./types";
+
+function makeBuildResult(entitiesByLexicon: Record<string, Array<{ name: string; type: string; props: unknown }>>): BuildResult {
+  const entities = new Map();
+  for (const [lexicon, list] of Object.entries(entitiesByLexicon)) {
+    for (const item of list) {
+      entities.set(item.name, { lexicon, entityType: item.type, props: item.props });
+    }
+  }
+  return {
+    outputs: new Map(Object.keys(entitiesByLexicon).map((l) => [l, "{}"])),
+    entities,
+    dependencies: new Map(),
+    errors: [],
+    warnings: [],
+    manifest: {
+      lexicons: Object.keys(entitiesByLexicon),
+      outputs: {},
+      deployOrder: Object.keys(entitiesByLexicon),
+    },
+    sourceFileCount: 1,
+  } as unknown as BuildResult;
+}
+
+describe("hashProps", () => {
+  test("produces the same hash for identical props", () => {
+    expect(hashProps({ a: 1, b: 2 })).toBe(hashProps({ a: 1, b: 2 }));
+  });
+
+  test("is order-independent (sorted JSON serialization)", () => {
+    expect(hashProps({ a: 1, b: 2 })).toBe(hashProps({ b: 2, a: 1 }));
+  });
+
+  test("produces different hashes for different props", () => {
+    expect(hashProps({ a: 1 })).not.toBe(hashProps({ a: 2 }));
+  });
+});
+
+describe("computeBuildDigest", () => {
+  test("emits one entry per entity with type, lexicon, and propsHash", () => {
+    const buildResult = makeBuildResult({
+      aws: [{ name: "bucket", type: "AWS::S3::Bucket", props: { name: "data" } }],
+    });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.resources["bucket"]).toMatchObject({
+      type: "AWS::S3::Bucket",
+      lexicon: "aws",
+      propsHash: expect.any(String),
+    });
+  });
+
+  test("missing props default to empty object", () => {
+    const buildResult = makeBuildResult({ aws: [{ name: "x", type: "T", props: undefined }] });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.resources["x"].propsHash).toBe(hashProps({}));
+  });
+
+  test("mirrors the build manifest's deployOrder and outputs", () => {
+    const buildResult = makeBuildResult({
+      aws: [{ name: "b", type: "T", props: {} }],
+      gcp: [{ name: "g", type: "T", props: {} }],
+    });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.deployOrder).toEqual(["aws", "gcp"]);
+    expect(digest.outputs).toEqual({});
+  });
+});
+
+describe("diffDigests", () => {
+  function makeDigest(resources: Record<string, string>): BuildDigest {
+    const out: BuildDigest["resources"] = {};
+    for (const [name, propsHash] of Object.entries(resources)) {
+      out[name] = { type: "T", lexicon: "aws", propsHash };
+    }
+    return { resources: out, dependencies: {}, outputs: {}, deployOrder: [] };
+  }
+
+  test("no previous digest → everything is added", () => {
+    const result = diffDigests(makeDigest({ a: "x", b: "y" }), undefined);
+    expect(result.added).toEqual(["a", "b"]);
+    expect(result.removed).toEqual([]);
+    expect(result.changed).toEqual([]);
+    expect(result.unchanged).toEqual([]);
+  });
+
+  test("identical digests → all unchanged", () => {
+    const d = makeDigest({ a: "x" });
+    const result = diffDigests(d, d);
+    expect(result.unchanged).toEqual(["a"]);
+    expect(result.added).toEqual([]);
+    expect(result.changed).toEqual([]);
+    expect(result.removed).toEqual([]);
+  });
+
+  test("different propsHash → changed", () => {
+    const result = diffDigests(makeDigest({ a: "x2" }), makeDigest({ a: "x1" }));
+    expect(result.changed).toEqual(["a"]);
+  });
+
+  test("resource gone from current → removed", () => {
+    const result = diffDigests(makeDigest({}), makeDigest({ a: "x" }));
+    expect(result.removed).toEqual(["a"]);
+  });
+
+  test("mixed: added + removed + changed + unchanged", () => {
+    const previous = makeDigest({ a: "x1", b: "y", c: "z" });
+    const current = makeDigest({ a: "x2", b: "y", d: "w" });
+    const result = diffDigests(current, previous);
+    expect(result.added.sort()).toEqual(["d"]);
+    expect(result.changed.sort()).toEqual(["a"]);
+    expect(result.unchanged.sort()).toEqual(["b"]);
+    expect(result.removed.sort()).toEqual(["c"]);
+  });
+});

package/src/state/git.test.ts

@@ -0,0 +1,191 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  writeSnapshot,
+  readSnapshot,
+  readEnvironmentSnapshots,
+  listSnapshots,
+  getHeadCommit,
+  pushState,
+  StaleStateBranchError,
+} from "./git";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  // Need at least one commit so HEAD exists.
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+describe("state/git", () => {
+  test("writeSnapshot creates the orphan branch and writes JSON addressable by readSnapshot", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const json = JSON.stringify({ resources: { bucket: { type: "T", status: "OK" } } });
+      const sha = await writeSnapshot("prod", "aws", json, { cwd: dir });
+      expect(sha).toMatch(/^[0-9a-f]{40}$/);
+
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(out).not.toBeNull();
+      expect(JSON.parse(out!)).toEqual(JSON.parse(json));
+    });
+  });
+
+  test("readSnapshot returns null for missing env/lexicon", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(out).toBeNull();
+    });
+  });
+
+  test("subsequent writes preserve other env+lexicon entries", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "gcp", JSON.stringify({ b: 2 }), { cwd: dir });
+      await writeSnapshot("staging", "aws", JSON.stringify({ c: 3 }), { cwd: dir });
+
+      expect(await readSnapshot("prod", "aws", { cwd: dir })).toBeTruthy();
+      expect(await readSnapshot("prod", "gcp", { cwd: dir })).toBeTruthy();
+      expect(await readSnapshot("staging", "aws", { cwd: dir })).toBeTruthy();
+    });
+  });
+
+  test("re-writing the same env+lexicon updates the entry rather than duplicating", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 2 }), { cwd: dir });
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(JSON.parse(out!)).toEqual({ v: 2 });
+    });
+  });
+
+  test("readEnvironmentSnapshots returns all lexicons for an env", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "gcp", JSON.stringify({ b: 2 }), { cwd: dir });
+      const all = await readEnvironmentSnapshots("prod", { cwd: dir });
+      expect([...all.keys()].sort()).toEqual(["aws", "gcp"]);
+    });
+  });
+
+  test("listSnapshots returns commit history of the orphan branch", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 2 }), { cwd: dir });
+      const log = await listSnapshots({ cwd: dir });
+      expect(log.length).toBe(2);
+      expect(log[0].commit).toMatch(/^[0-9a-f]{40}$/);
+    });
+  });
+
+  test("getHeadCommit returns the working-branch HEAD sha", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const head = await getHeadCommit({ cwd: dir });
+      expect(head).toMatch(/^[0-9a-f]{40}$/);
+    });
+  });
+
+  // ── Concurrent push rejection (#30) ─────────────────────────────────────────
+
+  /**
+   * Build a "remote ↔ clone" pair where `clone` has `remote` configured as
+   * `origin`. Returns the clone path; the caller writes snapshots there.
+   */
+  async function setupClonePair(): Promise<{ clonePath: string; remotePath: string; cleanup: () => Promise<void> }> {
+    const remotePath = join(import.meta.dirname ?? "/tmp", `chant-state-remote-${Date.now()}-${Math.random()}`);
+    const clonePath = join(import.meta.dirname ?? "/tmp", `chant-state-clone-${Date.now()}-${Math.random()}`);
+    const { mkdir, rm } = await import("node:fs/promises");
+    await mkdir(remotePath, { recursive: true });
+    git(["init", "-q", "--bare", "-b", "main"], remotePath);
+    git(["clone", "-q", remotePath, clonePath], import.meta.dirname ?? "/tmp");
+    git(["config", "user.email", "test@chant.dev"], clonePath);
+    git(["config", "user.name", "Test"], clonePath);
+    writeFileSync(join(clonePath, "README.md"), "fixture\n");
+    git(["add", "README.md"], clonePath);
+    git(["commit", "-q", "-m", "init"], clonePath);
+    git(["push", "-q", "origin", "main"], clonePath);
+    return {
+      clonePath,
+      remotePath,
+      cleanup: async () => {
+        await rm(remotePath, { recursive: true, force: true });
+        await rm(clonePath, { recursive: true, force: true });
+      },
+    };
+  }
+
+  test("first push to remote succeeds (no remote ref yet)", async () => {
+    const { clonePath, cleanup } = await setupClonePair();
+    try {
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
+      const ok = await pushState({ cwd: clonePath });
+      expect(ok).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("subsequent push from same clone (after fetch) succeeds via lease", async () => {
+    const { clonePath, cleanup } = await setupClonePair();
+    try {
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
+      expect(await pushState({ cwd: clonePath })).toBe(true);
+
+      // Pull the remote ref into local remote-tracking, then commit + push again
+      git(["fetch", "-q", "origin", "+refs/heads/chant/state:refs/remotes/origin/chant/state"], clonePath);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 2 }), { cwd: clonePath });
+      expect(await pushState({ cwd: clonePath })).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("concurrent write rejected: second push throws StaleStateBranchError", async () => {
+    // Simulate two concurrent operators by setting up two clones of the same remote.
+    const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
+    const cloneB = join(import.meta.dirname ?? "/tmp", `chant-state-clone-b-${Date.now()}-${Math.random()}`);
+    try {
+      git(["clone", "-q", remotePath, cloneB], import.meta.dirname ?? "/tmp");
+      git(["config", "user.email", "test@chant.dev"], cloneB);
+      git(["config", "user.name", "Test"], cloneB);
+
+      // Operator A writes + pushes first.
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
+      expect(await pushState({ cwd: cloneA })).toBe(true);
+
+      // Operator B writes from the same baseline (chant/state doesn't exist
+      // on cloneB's remote-tracking yet) and tries to push — should fail
+      // with StaleStateBranchError because A's push moved the remote ref.
+      await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
+      await expect(pushState({ cwd: cloneB })).rejects.toBeInstanceOf(StaleStateBranchError);
+    } finally {
+      await cleanup();
+      const { rm } = await import("node:fs/promises");
+      await rm(cloneB, { recursive: true, force: true });
+    }
+  });
+
+  test("StaleStateBranchError carries the expected SHA used as the lease", async () => {
+    const err = new StaleStateBranchError(null, "stale info: ...");
+    expect(err.name).toBe("StaleStateBranchError");
+    expect(err.expected).toBeNull();
+    expect(err.message).toContain("moved");
+  });
+});

package/src/state/git.ts

@@ -22,13 +22,8 @@ export async function writeSnapshot(
   const rt = getRuntime();
   const cwd = opts?.cwd;
 
-  // 1. Write blob
-  const hashResult = await rt.spawn(
-    ["git", "hash-object", "-w", "--stdin"],
-    { cwd },
-  );
-  // hash-object reads from stdin, but spawn doesn't support piping directly.
-  // Use a shell pipeline instead.
+  // 1. Write blob — hash-object reads from stdin, but spawn() doesn't expose
+  // a stdin handle, so we run via a shell pipeline (`echo … | git hash-object`).
   const blobResult = await rt.spawn(
     ["sh", "-c", `echo '${json.replace(/'/g, "'\\''")}' | git hash-object -w --stdin`],
     { cwd },
@@ -179,20 +174,77 @@ export async function listSnapshots(
 }
 
 /**
- * Push the state branch to remote.
+ * Thrown by pushState when the remote chant/state branch has moved since
+ * the local snapshot was prepared — i.e. another snapshot for this or a
+ * different env was pushed concurrently. The caller should fetch and retry.
+ */
+export class StaleStateBranchError extends Error {
+  readonly expected: string | null;
+  constructor(expected: string | null, stderr: string) {
+    super(
+      "chant/state remote branch has moved since this run started — " +
+      "another snapshot was pushed concurrently. " +
+      `git stderr: ${stderr.trim()}`,
+    );
+    this.name = "StaleStateBranchError";
+    this.expected = expected;
+  }
+}
+
+/**
+ * Look up the remote-tracking SHA for chant/state, if any. Returns null when
+ * the remote ref doesn't exist locally yet (e.g. first-ever snapshot).
+ */
+export async function getRemoteStateBranchSha(
+  remote: string,
+  opts?: { cwd?: string },
+): Promise<string | null> {
+  const rt = getRuntime();
+  const ref = `refs/remotes/${remote}/${STATE_BRANCH}`;
+  const result = await rt.spawn(["git", "rev-parse", "--verify", ref], { cwd: opts?.cwd });
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim() || null;
+}
+
+/**
+ * Push the state branch to remote with --force-with-lease.
+ *
+ * If the remote chant/state ref has advanced past the local remote-tracking
+ * SHA captured at the start of this push, the push is rejected and we throw
+ * StaleStateBranchError so the caller can surface a recovery hint.
+ *
+ * Returns false (without throwing) only when no remote is configured at all.
  */
 export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
   const rt = getRuntime();
-  // Check if remote exists
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
   if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
 
   const remote = remoteResult.stdout.trim().split("\n")[0];
+
+  // Capture the lease SHA — if null, the remote ref doesn't exist yet
+  // (first-time push) and we send `--force-with-lease=ref:` (empty SHA),
+  // which git interprets as "ref does not exist on remote".
+  const expected = await getRemoteStateBranchSha(remote, opts);
+  const lease = `refs/heads/${STATE_BRANCH}:${expected ?? ""}`;
+
   const pushResult = await rt.spawn(
-    ["git", "push", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
+    ["git", "push", `--force-with-lease=${lease}`, remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
     { cwd: opts?.cwd },
   );
-  return pushResult.exitCode === 0;
+
+  if (pushResult.exitCode !== 0) {
+    const stderr = pushResult.stderr ?? "";
+    if (
+      stderr.includes("stale info") ||
+      stderr.includes("rejected") ||
+      stderr.includes("non-fast-forward")
+    ) {
+      throw new StaleStateBranchError(expected, stderr);
+    }
+    return false;
+  }
+  return true;
 }
 
 /**