@intentius/chant 0.124.39 → 0.124.41

package/src/lifecycle/target-lock.test.ts

@@ -0,0 +1,195 @@
+/**
+ * #4293: target locks a pull request holds, `_locks/<gate>.json` on
+ * `chant/lifecycle`, in one clone and across clones through a bare remote.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  describeHeldTargetLocks,
+  heldTargetLocks,
+  parseTargetLocks,
+  readTargetLocks,
+  releaseTargetLocks,
+  renderTargetLocks,
+  takeTargetLocks,
+  targetLockGateProblem,
+  targetLockPath,
+  type TargetLock,
+} from "./target-lock";
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+function tmp(prefix: string): string {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+  dirs.push(d);
+  return d;
+}
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function configure(dir: string): void {
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  git(dir, "config", "commit.gpgsign", "false");
+}
+
+function initRepo(): string {
+  const dir = tmp("chant-target-lock-");
+  git(dir, "init", "-q", "-b", "main");
+  configure(dir);
+  writeFileSync(join(dir, "README.md"), "# t\n");
+  git(dir, "add", "README.md");
+  git(dir, "commit", "-q", "-m", "init");
+  return dir;
+}
+
+const holder = (pr: number, stage: TargetLock["stage"], by = "alice"): TargetLock => ({ pr, by, at: "2026-10-22T10:00:00.000Z", stage, head: "a".repeat(40) });
+
+describe("the lock file", () => {
+  test("parses a version 1 file and drops malformed entries; anything else holds no locks", () => {
+    const text = JSON.stringify({ version: 1, locks: { web: holder(1, "plan"), bad: { pr: "x" }, api: { pr: 2, by: "b", at: "t", stage: "nope" } } });
+    expect(parseTargetLocks(text)).toEqual({ version: 1, locks: { web: holder(1, "plan") } });
+    expect(parseTargetLocks("not json")).toEqual({ version: 1, locks: {} });
+    expect(parseTargetLocks(JSON.stringify({ version: 2, locks: {} }))).toEqual({ version: 1, locks: {} });
+    expect(parseTargetLocks(null)).toEqual({ version: 1, locks: {} });
+  });
+
+  test("renders targets sorted, so the same locks are the same blob", () => {
+    const a = renderTargetLocks({ version: 1, locks: { web: holder(1, "plan"), api: holder(2, "lock") } });
+    const b = renderTargetLocks({ version: 1, locks: { api: holder(2, "lock"), web: holder(1, "plan") } });
+    expect(a).toBe(b);
+    expect(Object.keys(JSON.parse(a).locks)).toEqual(["api", "web"]);
+  });
+
+  test("the path is _locks/<gate>.json under the member prefix, and a gate name must be a file name", () => {
+    expect(targetLockPath("pr-apply")).toBe("_locks/pr-apply.json");
+    expect(targetLockPath("pr-apply", "_members/api/")).toBe("_members/api/_locks/pr-apply.json");
+    expect(targetLockGateProblem("pr-apply")).toBeNull();
+    expect(targetLockGateProblem("../x")).toMatch(/not a lock file name/);
+  });
+
+  test("describes held locks by pull request, with how they were taken", () => {
+    const text = describeHeldTargetLocks([
+      { target: "api", ...holder(7, "plan", "bob") },
+      { target: "web", ...holder(7, "plan", "bob") },
+      { target: "db", ...holder(9, "lock", "carol") },
+    ], (n) => `merge request !${n}`);
+    expect(text).toBe("api, web are locked by merge request !7 (planned by bob); db is locked by merge request !9 (locked with chant lock by carol)");
+  });
+});
+
+describe("target locks in one clone", () => {
+  test("a pull request takes free targets; another is refused with the holder named; unlock frees them", async () => {
+    const cwd = initRepo();
+    const first = await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    expect(first).toEqual({ ok: true, taken: ["api", "web"], released: [], expired: [], pushed: false });
+    expect(JSON.parse(git(cwd, "show", "chant/lifecycle:_locks/pr-apply.json")).locks.web.pr).toBe(1);
+
+    const second = await takeTargetLocks("pr-apply", ["web", "db"], holder(2, "plan", "bob"), { cwd });
+    expect(second).toEqual({ ok: false, held: [{ target: "web", ...holder(1, "plan") }] });
+    // Nothing of the refused pull request was written.
+    expect(Object.keys((await readTargetLocks("pr-apply", { cwd })).locks)).toEqual(["api", "web"]);
+
+    expect(await heldTargetLocks("pr-apply", ["web", "db"], 2, { cwd })).toHaveLength(1);
+    expect(await heldTargetLocks("pr-apply", ["web", "db"], 1, { cwd })).toEqual([]);
+    expect(await heldTargetLocks("pr-apply", ["web"], null, { cwd })).toHaveLength(1);
+
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd, targets: ["api"] })).toEqual({ released: ["api"], pushed: false });
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd })).toEqual({ released: ["web"], pushed: false });
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd })).toEqual({ released: [], pushed: false });
+    expect(await takeTargetLocks("pr-apply", ["web", "db"], holder(2, "plan", "bob"), { cwd })).toMatchObject({ ok: true, taken: ["db", "web"] });
+  });
+
+  test("a lock whose pull request merged or closed is taken over and dropped", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    const isOpen = async (pr: number) => pr !== 1;
+    const taken = await takeTargetLocks("pr-apply", ["web"], holder(2, "lock", "bob"), { cwd, isOpen });
+    expect(taken).toMatchObject({ ok: true, taken: ["web"], expired: ["api", "web"] });
+    expect((await readTargetLocks("pr-apply", { cwd })).locks).toEqual({ web: holder(2, "lock", "bob") });
+    expect(await heldTargetLocks("pr-apply", ["web"], 3, { cwd, isOpen: async () => false })).toEqual([]);
+  });
+
+  test("a plan keeps the pull request's own lock and apply locks; an apply takes over its plan locks", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web"], holder(1, "lock"), { cwd });
+    await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    let locks = (await readTargetLocks("pr-apply", { cwd })).locks;
+    expect(locks.web.stage).toBe("lock");
+    expect(locks.api.stage).toBe("plan");
+    await takeTargetLocks("pr-apply", ["api"], holder(1, "apply"), { cwd });
+    locks = (await readTargetLocks("pr-apply", { cwd })).locks;
+    expect(locks.api.stage).toBe("apply");
+  });
+
+  test("a plan with releaseStalePlan drops its plan locks on targets the head no longer reaches", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    await takeTargetLocks("pr-apply", ["db"], holder(1, "lock"), { cwd });
+    const again = await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd, releaseStalePlan: true });
+    expect(again).toMatchObject({ ok: true, taken: ["web"], released: ["api"] });
+    expect(Object.keys((await readTargetLocks("pr-apply", { cwd })).locks)).toEqual(["db", "web"]);
+  });
+
+  test("each gate keeps its own file", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd });
+    expect(await takeTargetLocks("staging-apply", ["web"], holder(2, "plan"), { cwd })).toMatchObject({ ok: true });
+    expect(git(cwd, "ls-tree", "--name-only", "chant/lifecycle", "_locks/").split("\n").sort()).toEqual(["_locks/pr-apply.json", "_locks/staging-apply.json"]);
+  });
+});
+
+describe("target locks across clones, through a bare remote", () => {
+  function setup(): { root: string; remote: string; a: string; b: string } {
+    const root = tmp("chant-target-lock-remote-");
+    const remote = join(root, "remote.git");
+    git(root, "init", "-q", "--bare", "-b", "main", remote);
+    const a = join(root, "a");
+    git(root, "clone", "-q", remote, a);
+    configure(a);
+    writeFileSync(join(a, "README.md"), "# t\n");
+    git(a, "add", "README.md");
+    git(a, "commit", "-q", "-m", "init");
+    git(a, "push", "-q", "origin", "main");
+    const b = join(root, "b");
+    git(root, "clone", "-q", remote, b);
+    configure(b);
+    return { root, remote, a, b };
+  }
+
+  test("a lock reaches the remote, the other clone is refused, and an unlock there frees it", async () => {
+    const { remote, a, b } = setup();
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd: a })).toMatchObject({ ok: true, pushed: true });
+    expect(JSON.parse(git(remote, "show", "chant/lifecycle:_locks/pr-apply.json")).locks.web.pr).toBe(1);
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(2, "plan"), { cwd: b })).toMatchObject({ ok: false, held: [{ target: "web", pr: 1 }] });
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd: b })).toEqual({ released: ["web"], pushed: true });
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(2, "plan"), { cwd: a })).toMatchObject({ ok: true, taken: ["web"], pushed: true });
+  });
+
+  test("a push the remote refuses is dropped and decided again: two clones can't both lock one target", async () => {
+    const { root, remote, a, b } = setup();
+    // A writes its lock locally only, with no remote, then pushes it from B's pre-push hook,
+    // so B's first push lands after A's and is refused.
+    git(a, "remote", "remove", "origin");
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd: a })).toMatchObject({ ok: true, pushed: false });
+    git(a, "remote", "add", "origin", remote);
+    const marker = join(root, "raced");
+    const hook = join(b, ".git", "hooks", "pre-push");
+    writeFileSync(hook, `#!/bin/sh\nif [ ! -e "${marker}" ]; then touch "${marker}"; git -C "${a}" push -q origin chant/lifecycle:chant/lifecycle; fi\nexit 0\n`);
+    chmodSync(hook, 0o755);
+
+    const lost = await takeTargetLocks("pr-apply", ["web", "api"], holder(2, "plan", "bob"), { cwd: b });
+    expect(lost).toEqual({ ok: false, held: [{ target: "web", ...holder(1, "plan") }] });
+    // B's refused commit is gone: its branch is the remote's, which holds only A's lock.
+    expect(git(b, "rev-parse", "chant/lifecycle")).toBe(git(remote, "rev-parse", "chant/lifecycle"));
+    expect(Object.keys(JSON.parse(git(remote, "show", "chant/lifecycle:_locks/pr-apply.json")).locks)).toEqual(["web"]);
+  });
+});

package/src/lifecycle/target-lock.ts

@@ -0,0 +1,347 @@
+/**
+ * Target locks (#4293): a pull request holds a lock on each target its
+ * change reaches, so no other pull request applies or locks those targets
+ * until it merges or closes, or someone runs `chant unlock` on it.
+ *
+ * A target is a name the caller picks: a component, a workspace member, or
+ * a lexicon's own unit such as a Terraform root. The locks of one gate live
+ * in one file, `_locks/<gate>.json` on `chant/lifecycle`, under the member's
+ * ledger prefix in a workspace member (./git.ts `ledgerDir`). The gate is
+ * the pull-request loop's, `pr-apply` unless the pipeline names another, so
+ * two pipelines with their own gates keep their own locks.
+ *
+ * Every change is a new commit on the branch, written with the read-then-CAS
+ * the other ledgers use and then pushed. A lock counts only once the remote
+ * has it: when the push is refused because another writer moved the branch,
+ * the local commit is dropped, the branch is read again and the decision is
+ * made again. So two jobs that lock the same target at once cannot both win.
+ * A repository with no remote is one machine, and the local write decides.
+ *
+ * A lock held by a pull request that is no longer open is released: the
+ * holder merged or closed. The caller says which pull requests are open
+ * (`isOpen`, from the forge). Without it every lock counts as held, and only
+ * `chant unlock` releases one.
+ *
+ * The file is coordination, not a record of work. ws-074 holds: the
+ * repository is the database, and the file is one more ledger on the
+ * branch, so any clone can read who holds what.
+ */
+import { getRuntime } from "../runtime-adapter";
+import {
+  fetchLifecycleStatus,
+  pushLifecycleStatus,
+  readBlobBySha,
+  readPathSha,
+  RefCASConflictError,
+  writeBlobToPath,
+} from "./git";
+import { resolveMemberLedger } from "./member-ledger";
+
+/** The directory on `chant/lifecycle` that holds the lock files. */
+export const LOCKS_DIR = "_locks";
+
+const STATE_BRANCH = "chant/lifecycle";
+/** A scratch ref this module owns, for reading the remote tip after a refused push. */
+const PROBE_REF = "refs/chant/target-lock-probe";
+const ATTEMPTS = 5;
+
+/**
+ * How a lock was taken. `plan`: the pull request's plan took it (`ci.locks:
+ * plan`). `apply`: its apply took it. `lock`: someone ran `chant lock`.
+ */
+export type TargetLockStage = "plan" | "apply" | "lock";
+
+export const TARGET_LOCK_STAGES = ["plan", "apply", "lock"] as const satisfies readonly TargetLockStage[];
+
+/** One target's lock: the pull request that holds it, who took it, when, how, and the head it took it at. */
+export interface TargetLock {
+  pr: number;
+  by: string;
+  at: string;
+  stage: TargetLockStage;
+  /** The pull request's head commit when the lock was taken. Absent when the caller did not say. */
+  head?: string;
+}
+
+/** `_locks/<gate>.json`. */
+export interface TargetLockFile {
+  version: 1;
+  locks: Record<string, TargetLock>;
+}
+
+/** A lock another open pull request holds on a target the caller needs. */
+export interface HeldTargetLock extends TargetLock {
+  target: string;
+}
+
+/** Says whether pull request `pr` is still open. */
+export type PullRequestOpen = (pr: number) => Promise<boolean>;
+
+export interface TargetLockOptions {
+  cwd?: string;
+  /** Whether a holder is still open. Absent: every holder counts as open. */
+  isOpen?: PullRequestOpen;
+}
+
+export type TakeTargetLocksResult =
+  | {
+      ok: true;
+      /** The targets now locked, sorted. */
+      taken: string[];
+      /** Plan locks of the same pull request on targets it no longer reaches, released (`releaseStalePlan`). */
+      released: string[];
+      /** Locks of merged or closed pull requests that this write dropped. */
+      expired: string[];
+      /** Whether the remote has the write. False with no remote, or when recording is off. */
+      pushed: boolean;
+    }
+  | { ok: false; held: HeldTargetLock[] };
+
+/** The path of `gate`'s lock file on `chant/lifecycle`, under a member's prefix when it has one. */
+export function targetLockPath(gate: string, memberPrefix = ""): string {
+  return `${memberPrefix}${LOCKS_DIR}/${gate}.json`;
+}
+
+/** A gate name that is safe as a file name. */
+export function targetLockGateProblem(gate: string): string | null {
+  return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(gate) ? null : `the gate name ${JSON.stringify(gate)} is not a lock file name: letters, digits, '.', '_' and '-', starting with a letter or digit`;
+}
+
+const isStage = (v: unknown): v is TargetLockStage => typeof v === "string" && (TARGET_LOCK_STAGES as readonly string[]).includes(v);
+
+/** Parse a lock file. Anything that is not a version 1 file with a map of locks reads as no locks; a malformed entry is dropped. */
+export function parseTargetLocks(text: string | null): TargetLockFile {
+  if (!text) return { version: 1, locks: {} };
+  try {
+    const doc = JSON.parse(text) as { version?: unknown; locks?: unknown };
+    if (doc?.version === 1 && doc.locks && typeof doc.locks === "object" && !Array.isArray(doc.locks)) {
+      const locks: Record<string, TargetLock> = {};
+      for (const [target, raw] of Object.entries(doc.locks as Record<string, Record<string, unknown>>)) {
+        if (!raw || !Number.isInteger(raw.pr) || typeof raw.by !== "string" || typeof raw.at !== "string" || !isStage(raw.stage)) continue;
+        locks[target] = { pr: raw.pr as number, by: raw.by, at: raw.at, stage: raw.stage, ...(typeof raw.head === "string" ? { head: raw.head } : {}) };
+      }
+      return { version: 1, locks };
+    }
+  } catch {
+    // An unreadable file holds no locks.
+  }
+  return { version: 1, locks: {} };
+}
+
+/** The file's text: targets sorted, so two writes of the same locks are the same blob. */
+export function renderTargetLocks(file: TargetLockFile): string {
+  const locks = Object.fromEntries(Object.keys(file.locks).sort().map((t) => [t, file.locks[t]]));
+  return `${JSON.stringify({ version: 1, locks }, null, 2)}\n`;
+}
+
+/** Fetch `chant/lifecycle`, refusing a ledger this checkout cannot read: a lock decided on a stale branch is no lock. */
+async function fetchForLocks(cwd?: string): Promise<void> {
+  const fetched = await fetchLifecycleStatus({ cwd });
+  if (fetched.status === "diverged") throw new Error(`the local ${STATE_BRANCH} has forked from ${fetched.remote}'s, so the locks cannot be read: ${fetched.stderr}`);
+  if (fetched.status === "unreachable") throw new Error(`cannot fetch ${STATE_BRANCH} from ${fetched.remote}, so the locks cannot be read${fetched.stderr ? `: ${fetched.stderr}` : ""}`);
+}
+
+async function readCurrent(gate: string, cwd?: string): Promise<{ sha: string | null; file: TargetLockFile }> {
+  const sha = await readPathSha(LOCKS_DIR, `${gate}.json`, { cwd });
+  return { sha, file: parseTargetLocks(sha ? await readBlobBySha(sha, { cwd }) : null) };
+}
+
+/** The locks of `gate` as the remote holds them now, fetched first. */
+export async function readTargetLocks(gate: string, opts: { cwd?: string } = {}): Promise<TargetLockFile> {
+  const problem = targetLockGateProblem(gate);
+  if (problem) throw new Error(problem);
+  await fetchForLocks(opts.cwd);
+  return (await readCurrent(gate, opts.cwd)).file;
+}
+
+/** A memo of `isOpen`, so one decision asks the forge about each pull request once. */
+function openMemo(isOpen?: PullRequestOpen): PullRequestOpen {
+  const seen = new Map<number, Promise<boolean>>();
+  return (pr) => {
+    if (!isOpen) return Promise.resolve(true);
+    if (!seen.has(pr)) seen.set(pr, isOpen(pr));
+    return seen.get(pr)!;
+  };
+}
+
+/** The locks on `targets` that an open pull request other than `pr` holds, by target. */
+async function heldIn(file: TargetLockFile, targets: readonly string[], pr: number | null, open: PullRequestOpen): Promise<HeldTargetLock[]> {
+  const held: HeldTargetLock[] = [];
+  for (const target of [...new Set(targets)].sort()) {
+    const l = file.locks[target];
+    if (l && l.pr !== pr && (await open(l.pr))) held.push({ target, ...l });
+  }
+  return held;
+}
+
+/**
+ * The locks on `targets` that an open pull request other than `pr` holds.
+ * Reads only: an apply calls this to refuse a target another pull request
+ * holds. `pr` null (an apply of a green commit) counts every open holder.
+ */
+export async function heldTargetLocks(gate: string, targets: readonly string[], pr: number | null, opts: TargetLockOptions = {}): Promise<HeldTargetLock[]> {
+  if (targets.length === 0) return [];
+  const file = await readTargetLocks(gate, opts);
+  return heldIn(file, targets, pr, openMemo(opts.isOpen));
+}
+
+/** The local tip of `chant/lifecycle`, or "" when there is none. */
+async function localTip(cwd?: string): Promise<string> {
+  const out = await getRuntime().spawn(["git", "rev-parse", "--verify", "--quiet", `refs/heads/${STATE_BRANCH}`], { cwd });
+  return out.exitCode === 0 ? out.stdout.trim() : "";
+}
+
+/**
+ * After a refused push: drop the lock commit `ours` from the local branch by
+ * moving it to the remote's tip, so the next attempt reads what the other
+ * writer pushed. Done only when `parent`, the tip before the write, is in
+ * the remote's history, so no other local commit is lost. Throws otherwise.
+ */
+async function dropRefusedWrite(remote: string, ours: string, parent: string, cwd?: string): Promise<void> {
+  const rt = getRuntime();
+  const env = { LC_ALL: "C", LANGUAGE: "" };
+  const probe = await rt.spawn(["git", "fetch", "--force", remote, `${STATE_BRANCH}:${PROBE_REF}`], { cwd, env });
+  if (probe.exitCode !== 0) throw new Error(`the push of the locks was refused and ${STATE_BRANCH} could not be read again from ${remote}: ${probe.stderr.trim()}`);
+  try {
+    if (parent) {
+      const contains = await rt.spawn(["git", "merge-base", "--is-ancestor", parent, PROBE_REF], { cwd, env });
+      if (contains.exitCode !== 0) throw new Error(`the push of the locks was refused, and the local ${STATE_BRANCH} holds commits ${remote} does not; push or fetch ${STATE_BRANCH} and lock again`);
+    }
+    const tip = (await rt.spawn(["git", "rev-parse", "--verify", PROBE_REF], { cwd, env })).stdout.trim();
+    const moved = await rt.spawn(["git", "update-ref", `refs/heads/${STATE_BRANCH}`, tip, ours], { cwd, env });
+    if (moved.exitCode !== 0) throw new Error(`could not drop the refused lock commit from ${STATE_BRANCH}: ${moved.stderr.trim()}`);
+    await rt.spawn(["git", "update-ref", `refs/remotes/${remote}/${STATE_BRANCH}`, tip], { cwd, env });
+  } finally {
+    await rt.spawn(["git", "update-ref", "-d", PROBE_REF], { cwd, env });
+  }
+}
+
+/**
+ * Write `next` over the file read at `sha`, then push. Returns null when the
+ * branch moved under the write (locally or on the remote), so the caller
+ * reads and decides again.
+ */
+async function writeAndPush(gate: string, sha: string | null, next: TargetLockFile, message: string, cwd?: string): Promise<{ pushed: boolean } | null> {
+  const parent = await localTip(cwd);
+  let commit: string;
+  try {
+    commit = await writeBlobToPath(LOCKS_DIR, `${gate}.json`, renderTargetLocks(next), message, { cwd, expectPriorPathSha: sha });
+  } catch (err) {
+    if (err instanceof RefCASConflictError) return null;
+    throw err;
+  }
+  const push = await pushLifecycleStatus({ cwd });
+  switch (push.status) {
+    case "pushed":
+      return { pushed: true };
+    case "no-remote":
+    case "not-recorded":
+      return { pushed: false };
+    case "stale":
+      await dropRefusedWrite(push.remote, commit, parent, cwd);
+      await fetchForLocks(cwd);
+      return null;
+    case "failed":
+      throw new Error(`the locks were written but the push of ${STATE_BRANCH} to ${push.remote} failed, so they do not count yet: ${push.stderr}`);
+  }
+}
+
+/**
+ * Lock `targets` for pull request `holder.pr`. A target locked by another
+ * pull request that is still open is held, and nothing is locked. A target
+ * locked by one that merged or closed is taken over, and its lock dropped.
+ * Targets this pull request already holds stay its own, with the new head.
+ * An apply or a `chant lock` takes over the pull request's own plan locks;
+ * a plan keeps its own apply and `chant lock` locks as they are. With
+ * `releaseStalePlan`, the pull request's plan locks on targets it no longer
+ * reaches are released.
+ */
+export async function takeTargetLocks(
+  gate: string,
+  targets: readonly string[],
+  holder: TargetLock,
+  opts: TargetLockOptions & { releaseStalePlan?: boolean } = {},
+): Promise<TakeTargetLocksResult> {
+  const problem = targetLockGateProblem(gate);
+  if (problem) throw new Error(problem);
+  for (const t of targets) if (t.trim() === "") throw new Error("a lock target is a non-empty name");
+  const wanted = [...new Set(targets)].sort();
+  const open = openMemo(opts.isOpen);
+  await fetchForLocks(opts.cwd);
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+    const { sha, file } = await readCurrent(gate, opts.cwd);
+    const held = await heldIn(file, wanted, holder.pr, open);
+    if (held.length > 0) return { ok: false, held };
+
+    const next: TargetLockFile = { version: 1, locks: {} };
+    const released: string[] = [];
+    const expired: string[] = [];
+    for (const [target, l] of Object.entries(file.locks)) {
+      if (l.pr === holder.pr) {
+        if (opts.releaseStalePlan && l.stage === "plan" && !wanted.includes(target)) {
+          released.push(target);
+          continue;
+        }
+      } else if (opts.isOpen && !(await open(l.pr))) {
+        expired.push(target);
+        continue;
+      }
+      next.locks[target] = l;
+    }
+    for (const target of wanted) {
+      const own = file.locks[target];
+      next.locks[target] = holder.stage === "plan" && own?.pr === holder.pr && own.stage !== "plan" ? own : holder;
+    }
+    const done = { ok: true as const, taken: wanted, released: released.sort(), expired: expired.sort() };
+    if (renderTargetLocks(next) === renderTargetLocks(file) && sha !== null) return { ...done, pushed: false };
+    if (wanted.length === 0 && released.length === 0 && expired.length === 0) return { ...done, pushed: false };
+    const wrote = await writeAndPush(gate, sha, next, `Lock ${wanted.length} target${wanted.length === 1 ? "" : "s"} of ${gate} for pull request ${holder.pr} (${holder.stage})`, opts.cwd);
+    if (wrote) return { ...done, pushed: wrote.pushed };
+  }
+  throw new Error(`could not write the locks of ${gate}: ${STATE_BRANCH} kept moving; lock again`);
+}
+
+/**
+ * Release the locks pull request `pr` holds on `gate`: every one, or only
+ * those on `targets`. Returns the targets released, sorted.
+ */
+export async function releaseTargetLocks(
+  gate: string,
+  pr: number,
+  opts: { cwd?: string; targets?: readonly string[] } = {},
+): Promise<{ released: string[]; pushed: boolean }> {
+  const problem = targetLockGateProblem(gate);
+  if (problem) throw new Error(problem);
+  await fetchForLocks(opts.cwd);
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+    const { sha, file } = await readCurrent(gate, opts.cwd);
+    const mine = Object.keys(file.locks)
+      .filter((t) => file.locks[t].pr === pr && (!opts.targets || opts.targets.includes(t)))
+      .sort();
+    if (mine.length === 0) return { released: [], pushed: false };
+    const next: TargetLockFile = { version: 1, locks: Object.fromEntries(Object.entries(file.locks).filter(([t]) => !mine.includes(t))) };
+    const wrote = await writeAndPush(gate, sha, next, `Unlock ${mine.length} target${mine.length === 1 ? "" : "s"} of ${gate} held by pull request ${pr}`, opts.cwd);
+    if (wrote) return { released: mine, pushed: wrote.pushed };
+  }
+  throw new Error(`could not write the locks of ${gate}: ${STATE_BRANCH} kept moving; unlock again`);
+}
+
+/** The lock file's path for the project at `cwd`, for messages. */
+export async function targetLockPathAt(gate: string, cwd?: string): Promise<string> {
+  const { prefix } = await resolveMemberLedger(cwd ?? process.cwd());
+  return targetLockPath(gate, prefix);
+}
+
+const STAGE_WORDS: Record<TargetLockStage, string> = { plan: "planned", apply: "applied", lock: "locked with chant lock" };
+
+/**
+ * One line naming the targets others hold, for a refusal or a note.
+ * `name` says how the forge names a holder (GitLab: `merge request !7`).
+ */
+export function describeHeldTargetLocks(held: readonly HeldTargetLock[], name: (pr: number) => string = (pr) => `pull request ${pr}`): string {
+  const byPr = new Map<number, HeldTargetLock[]>();
+  for (const h of held) byPr.set(h.pr, [...(byPr.get(h.pr) ?? []), h]);
+  return [...byPr]
+    .map(([pr, hs]) => `${hs.map((h) => h.target).join(", ")} ${hs.length === 1 ? "is" : "are"} locked by ${name(pr)} (${STAGE_WORDS[hs[0].stage]} by ${hs[0].by})`)
+    .join("; ");
+}

package/src/live-endpoint.ts

@@ -145,3 +145,34 @@ export function zeroResourcesWarning(
   if (Object.keys(observed.unobserved).length > 0) return undefined;
   return `${lexicon}: 0 live resources for env "${environment}" (${declaredCount} declared) — check the endpoint/credentials`;
 }
+
+/**
+ * Run `run` with `environment`'s declared endpoint applied, as
+ * {@link applyLiveEndpoint} applies it to a `--live` read, and restored after
+ * (#4281). The component plan and apply paths (`components pr-plan`,
+ * `pr-apply`, `pr-record`, `fan-out`, `promote`, `rollback`, `redeploy` and
+ * `chant run --components`) run capabilities that honor the same ambient vars:
+ * azure's `arm-deploy` reads `AZURE_ENDPOINT_URL`, gcp's `gcp-apply`
+ * `GCP_ENDPOINT_URL`, aws's `cfn-deploy` `AWS_ENDPOINT_URL`. Without this, a
+ * plan for an environment declared against an emulator went to the real cloud
+ * unless the shell exported the var by hand.
+ *
+ * `lexicons` is called only when the environment declares an endpoint, so a
+ * caller that has to load its plugins pays for that only then.
+ */
+export async function withEnvironmentEndpoint<T>(
+  environments: EnvironmentDeclaration[] | undefined,
+  environment: string,
+  lexicons: () => Promise<readonly EndpointLexicon[]> | readonly EndpointLexicon[],
+  run: () => Promise<T>,
+  options: { warn?: (message: string) => void; env?: NodeJS.ProcessEnv } = {},
+): Promise<T> {
+  if (!environmentEndpoint(environments, environment)) return run();
+  const applied = applyLiveEndpoint(environments, environment, await lexicons(), options.env);
+  if (applied.notice) options.warn?.(applied.notice);
+  try {
+    return await run();
+  } finally {
+    applied.restore();
+  }
+}

package/src/op/activities/activity-contracts.ts

@@ -141,6 +141,37 @@ export const behaviourFindingContract = activityContract(
   }),
 );
 
+/**
+ * The review agent (#4299). `changeSet` is `composeChangeSet`'s document,
+ * checked only for the fields the prompt reads. `returns` names what a later
+ * step may read; no gate reads it.
+ */
+export const reviewAgentContract = activityContract(
+  "reviewAgent",
+  z.strictObject({
+    op: z.string(),
+    changeSet: z.object({ digest: z.string(), entries: z.array(z.unknown()) }).passthrough().optional(),
+    changeSetFile: z.string().optional(),
+    mode: z.enum(["comment", "report"]).optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    base: z.string().optional(),
+    instructions: z.string().optional(),
+    command: z.string().optional(),
+    keyEnv: z.string().optional(),
+    timeout: z.number().positive().optional(),
+  }),
+  z.object({
+    mode: z.enum(["comment", "report"]),
+    risk: z.enum(["low", "medium", "high", "unknown"]),
+    exitCode: z.number().nullable(),
+    summary: z.string(),
+    commentUrl: z.string().optional(),
+    pullRequest: z.string().optional(),
+    mergeRequest: z.string().optional(),
+  }),
+);
+
 /**
  * The propose-only template upgrade (#2550, ws-032). `args` mirrors
  * `ProposeWorkspaceUpgradeArgs` without its test hooks. `returns` names what

package/src/op/activities/index.ts

@@ -161,6 +161,12 @@ export type {
   BaseCheckout,
 } from "./predict-behaviour";
 
+// The review agent (#4299): a model reviews the change set against the pull
+// request's own text and posts one sticky note. Only the activity and its
+// marker are re-exported, since the registry collects every exported function.
+export { reviewAgent, reviewMarker } from "./review-agent";
+export type { ReviewAgentArgs, ReviewAgentResult, ReviewAgentMode, ReviewRisk } from "./review-agent";
+
 // The propose-only template upgrade (#2550). Loads the workspace code on first
 // call only, so importing this module loads nothing under `workspace/`.
 export { proposeWorkspaceUpgrade } from "./propose-upgrade";