@intentius/chant 0.90.0 → 0.93.0

package/src/lifecycle/git.ts

@@ -1100,34 +1100,70 @@ export async function readBlobBySha(sha: string, opts?: { cwd?: string }): Promi
  * Push one arbitrary ref (e.g. a lease ref) to the remote, guarded the same
  * way {@link pushLifecycle} guards the ledger branch: `--force-with-lease`
  * keyed to the remote SHA last observed locally, so a concurrent push from a
- * second machine is rejected rather than silently clobbered. Plain `--force`
- * underneath that lease — a lease ref's value is a bare blob SHA, not a
- * commit descending from the previous one, so there is no "fast-forward" to
- * preserve, only the CAS the lease guard already provides.
+ * second machine is rejected rather than silently clobbered. The lease alone
+ * lets a push replace a value that is not an ancestor — a lease ref's value is
+ * a bare blob SHA, not a commit descending from the previous one — as long as
+ * the remote still holds the expected value. No `--force` beside it: git lets
+ * `--force` override `--force-with-lease`, which made every lease push
+ * unconditional before #2732.
  *
  * Returns `false` (never throws) when no remote is configured — a
  * remote-less project's lease is local-only by construction (see
  * `./lease.ts`'s module doc), or when the push itself is rejected (the
- * caller re-reads and retries; see `acquireLease`).
+ * caller re-reads and retries; see `acquireLease`). {@link pushRefStatus}
+ * tells those two apart.
  */
-export async function pushRef(ref: string, opts?: { cwd?: string }): Promise<boolean> {
+export async function pushRef(ref: string, opts?: { cwd?: string; expect?: string | null }): Promise<boolean> {
+  return (await pushRefStatus(ref, opts)) === "pushed";
+}
+
+/** What {@link pushRefStatus} did: the remote took the ref, there is no remote, or the remote refused it. */
+export type PushRefStatus = "pushed" | "no-remote" | "rejected";
+
+/**
+ * {@link pushRef}, saying why a push did not land (#2732).
+ *
+ * `opts.expect` is the value the caller last saw the ref at on the remote
+ * (`null`: absent there), and becomes the `--force-with-lease` expectation.
+ * Without it the expectation is `refs/remotes/<remote>/<ref>`, which nothing
+ * fetches a lease ref into, so it reads as "absent" and only a first push
+ * lands. A lease passes the value of its own remote-tracking ref instead
+ * (`./lease.ts`'s `readLease`).
+ *
+ * A ref that no longer exists locally is pushed as a deletion, under the same
+ * expectation, so a released lease is released on the remote too. Deleting a
+ * ref the caller expects to be absent already is a no-op that reports
+ * `pushed`.
+ */
+export async function pushRefStatus(ref: string, opts?: { cwd?: string; expect?: string | null }): Promise<PushRefStatus> {
   const rt = getRuntime();
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return "no-remote";
   const remote = remoteResult.stdout.trim().split("\n")[0];
 
-  const remoteRef = `refs/remotes/${remote}/${ref.replace(/^refs\//, "")}`;
-  const expectedResult = await rt.spawn(["git", "rev-parse", "--verify", remoteRef], { cwd: opts?.cwd });
-  const expected = expectedResult.exitCode === 0 ? expectedResult.stdout.trim() : null;
+  let expected: string | null;
+  if (opts?.expect !== undefined) {
+    expected = opts.expect;
+  } else {
+    const remoteRef = `refs/remotes/${remote}/${ref.replace(/^refs\//, "")}`;
+    const expectedResult = await rt.spawn(["git", "rev-parse", "--verify", remoteRef], { cwd: opts?.cwd });
+    expected = expectedResult.exitCode === 0 ? expectedResult.stdout.trim() : null;
+  }
   const lease = `${ref}:${expected ?? ""}`;
 
+  const local = await readRefSha(ref, opts);
+  if (local === null && expected === null) return "pushed";
+  const refspec = local === null ? `:${ref}` : `${ref}:${ref}`;
   const pushResult = await rt.spawn(
-    ["git", "push", "--force", `--force-with-lease=${lease}`, remote, `${ref}:${ref}`],
+    ["git", "push", `--force-with-lease=${lease}`, remote, refspec],
     { cwd: opts?.cwd },
   );
-  return pushResult.exitCode === 0;
+  return pushResult.exitCode === 0 ? "pushed" : "rejected";
 }
 
+/** What {@link fetchRefIntoStatus} found: the ref fetched, no remote, the remote answered without the ref, or the fetch failed. */
+export type FetchRefStatus = "fetched" | "no-remote" | "missing" | "failed";
+
 /**
  * Fetch one arbitrary remote ref into a local ref of a possibly *different*
  * name (#1959 finding 3). `+` forces the update even when it isn't a
@@ -1145,12 +1181,26 @@ export async function fetchRefInto(
   localRef: string,
   opts?: { cwd?: string },
 ): Promise<boolean> {
+  return (await fetchRefIntoStatus(remoteRef, localRef, opts)) === "fetched";
+}
+
+/**
+ * {@link fetchRefInto}, saying why nothing was fetched (#2732). `missing`
+ * means the remote answered and does not carry the ref, which for a lease is
+ * the news that it was released there.
+ */
+export async function fetchRefIntoStatus(
+  remoteRef: string,
+  localRef: string,
+  opts?: { cwd?: string },
+): Promise<FetchRefStatus> {
   const rt = getRuntime();
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return "no-remote";
   const remote = remoteResult.stdout.trim().split("\n")[0];
-  const fetchResult = await rt.spawn(["git", "fetch", remote, `+${remoteRef}:${localRef}`], { cwd: opts?.cwd });
-  return fetchResult.exitCode === 0;
+  const fetchResult = await rt.spawn(["git", "fetch", remote, `+${remoteRef}:${localRef}`], { cwd: opts?.cwd, env: C_LOCALE_ENV });
+  if (fetchResult.exitCode === 0) return "fetched";
+  return NO_SUCH_REMOTE_REF_RE.test(fetchResult.stderr ?? "") ? "missing" : "failed";
 }
 
 /**

package/src/lifecycle/lease.test.ts

@@ -285,6 +285,28 @@ describe("lifecycle/lease", () => {
       }
     });
 
+    // #2732: pushRef passed `--force` beside `--force-with-lease`, and git
+    // lets `--force` win, so every lease push was unconditional. It now pushes
+    // under the lease alone, expecting the value last fetched, so a renewal
+    // lands and a release deletes the ref on the remote.
+    test("a renewal and a release reach the remote, under the lease the last fetch saw (#2732)", async () => {
+      const { clonePath, remotePath, cleanup } = await setupClonePair();
+      try {
+        const ref = leaseRef("fountain-converge");
+        const first = await acquireLease("fountain-converge", "operator-a", { cwd: clonePath, ttlMs: 60_000 });
+        expect(first.acquired).toBe(true);
+        const renewed = await acquireLease("fountain-converge", "operator-a", { cwd: clonePath, ttlMs: 120_000 });
+        expect(renewed.lease?.token).toBe(first.lease?.token);
+        const local = git(["rev-parse", ref], clonePath).stdout.trim();
+        expect(git(["rev-parse", ref], remotePath).stdout.trim()).toBe(local);
+
+        expect(await releaseLease("fountain-converge", "operator-a", renewed.lease!.token, { cwd: clonePath })).toBe(true);
+        expect(git(["rev-parse", "--verify", ref], remotePath).exitCode).not.toBe(0);
+      } finally {
+        await cleanup();
+      }
+    });
+
     // ── #1959 finding 3 ──────────────────────────────────────────────────
     //
     // `readLease` used to fetch the remote lease ref directly into the same

package/src/lifecycle/lease.ts

@@ -33,7 +33,7 @@
  */
 import { hostname } from "node:os";
 import { randomUUID } from "node:crypto";
-import { readRefSha, updateRefCAS, deleteRefCAS, writeBlob, readBlobBySha, pushRef, fetchRefInto, RefCASConflictError } from "./git";
+import { readRefSha, updateRefCAS, deleteRefCAS, writeBlob, readBlobBySha, pushRefStatus, fetchRefIntoStatus, RefCASConflictError, StaleLockError } from "./git";
 import { resolveMemberLedger } from "./member-ledger";
 
 export const LEASE_REF_PREFIX = "refs/chant/lease/";
@@ -95,7 +95,7 @@ function leaseFreshnessKey(record?: LeaseRecord): string {
   return record ? `${record.acquiredAt} ${record.expiresAt}` : "";
 }
 
-/** One lease's live state — the entire durable record; there is no history, only the current holder (see this module's doc on why no separate ledger). */
+/** One lease's live state: the current holder only. An operator lease keeps no history; a work lease (./work-lease.ts) appends each change to `_leases/<id>.jsonl` beside it. */
 export interface LeaseRecord {
   op: string;
   /** `<hostname>:<pid>:<random>` — a diagnostic identity, not itself the fencing mechanism (`token` is). */
@@ -137,6 +137,23 @@ export interface ReadLeaseResult {
   /** The ref's current SHA (the CAS anchor for the next write), or `null` if no lease has ever been written. */
   sha: string | null;
   record?: LeaseRecord;
+  /**
+   * The value of the remote-tracking ref (`refs/chant/lease-remote/<op>`)
+   * after the fetch: what the remote held when last seen, or `null` when it
+   * held nothing. The `--force-with-lease` expectation of the next push
+   * (#2732).
+   */
+  remoteSha: string | null;
+}
+
+/** Options every lease read and write takes. `cwd` also picks the ledger, and so the member prefix of the refs (./member-ledger.ts). */
+export interface LeaseOptions {
+  cwd?: string;
+}
+
+async function readRecordAt(ref: string, opts?: { cwd?: string }): Promise<{ sha: string | null; record?: LeaseRecord }> {
+  const sha = await readRefSha(ref, opts);
+  return { sha, record: sha ? parseLease((await readBlobBySha(sha, opts)) ?? "") : undefined };
 }
 
 /**
@@ -159,26 +176,76 @@ export interface ReadLeaseResult {
  * against — is always the local ref's own actual value; only the local
  * canonical ref is ever a valid basis for a `updateRefCAS`/`deleteRefCAS`
  * call against it, regardless of what the comparison decided about `record`.
+ *
+ * When the remote answers without the ref, the lease was released there, and
+ * the tracking ref is dropped so a stale copy of it no longer counts (#2732).
+ * A read-only report that must stay off the network reads the refs itself
+ * (`./work-lease.ts`'s `listWorkLeases`).
  */
-export async function readLease(opName: string, opts?: { cwd?: string }): Promise<ReadLeaseResult> {
+export async function readLease(opName: string, opts?: LeaseOptions): Promise<ReadLeaseResult> {
   const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
-  await fetchRefInto(ref, trackingRef, opts).catch(() => undefined);
-
-  const sha = await readRefSha(ref, opts);
-  const localRecord = sha ? parseLease((await readBlobBySha(sha, opts)) ?? "") : undefined;
+  const fetched = await fetchRefIntoStatus(ref, trackingRef, opts).catch(() => "failed" as const);
+  if (fetched === "missing") {
+    const stale = await readRefSha(trackingRef, opts);
+    if (stale) await deleteRefCAS(trackingRef, stale, opts).catch(() => undefined);
+  }
 
-  const remoteSha = await readRefSha(trackingRef, opts);
-  const remoteRecord = remoteSha ? parseLease((await readBlobBySha(remoteSha, opts)) ?? "") : undefined;
+  const { sha, record: localRecord } = await readRecordAt(ref, opts);
+  const { sha: remoteSha, record: remoteRecord } = await readRecordAt(trackingRef, opts);
 
   const record = leaseFreshnessKey(remoteRecord) > leaseFreshnessKey(localRecord) ? remoteRecord : localRecord;
-  return { sha, record };
+  return { sha, record, remoteSha };
 }
 
+/** Why {@link acquireLease} did not acquire (#2732). */
+export type LeaseRefusal =
+  /** Someone holds it live: another holder, or, under `mode: "claim"`, anyone. */
+  | "held"
+  /** `mode: "renew"` and nobody holds it live any more: it expired or was released. */
+  | "not-held"
+  /** `mode: "renew"` and the live lease has another token than the one given. */
+  | "token-mismatch"
+  /** Another writer changed the ref between this call's read and its write. */
+  | "race"
+  /** `requirePush` and the remote refused the push: another clone got there first, or the remote could not be reached. */
+  | "push-rejected";
+
 export interface AcquireLeaseResult {
   acquired: boolean;
   lease?: LeaseRecord;
   /** Present when not acquired: the lease record currently held by someone else. */
   heldBy?: LeaseRecord;
+  /** Present when not acquired: why (#2732). */
+  reason?: LeaseRefusal;
+}
+
+/** Options for {@link acquireLease}. */
+export interface AcquireLeaseOptions extends LeaseOptions {
+  ttlMs?: number;
+  now?: () => Date;
+  /**
+   * `acquire` (the default, the operator's): take it when free or expired,
+   * renew it when `holder` already holds it. `claim`: take it only when free
+   * or expired, and refuse even its own holder. `renew`: only move the expiry
+   * of a live lease `holder` holds (#2732).
+   */
+  mode?: "acquire" | "claim" | "renew";
+  /** With `mode: "renew"`, the token the caller holds; a live lease with another token is refused. */
+  token?: string;
+  /**
+   * Count the write only once the remote has taken it, when there is a
+   * remote. A rejected push undoes the local write and refuses with
+   * `push-rejected`, so two clones racing for one lease cannot both hold it.
+   * The operator leaves it off: its push is best-effort (#2732).
+   */
+  requirePush?: boolean;
+  /**
+   * Wait out a `.lock` another process holds on the ref for up to this long,
+   * retrying, before surfacing it as a {@link StaleLockError}. A lock left by
+   * a killed process outlives the wait; one held by a racing writer does
+   * not. Off (0) by default, as the operator has always had it.
+   */
+  lockWaitMs?: number;
 }
 
 /**
@@ -198,22 +265,42 @@ export interface AcquireLeaseResult {
  * against a lease nobody can ever actually acquire again without manual
  * intervention. It propagates instead, so the caller (`../op/operator.ts`'s
  * `runOperatorRound`) can surface it as its own distinct, diagnosable event
- * rather than a silent, permanent skip.
+ * rather than a silent, permanent skip. `lockWaitMs` waits a racing writer's
+ * lock out first.
+ *
+ * `mode`, `token` and `requirePush` are the work lease's (#2732,
+ * ./work-lease.ts); the operator uses none of them.
  */
 export async function acquireLease(
   opName: string,
   holder: string,
-  opts?: { cwd?: string; ttlMs?: number; now?: () => Date },
+  opts?: AcquireLeaseOptions,
 ): Promise<AcquireLeaseResult> {
+  const deadline = Date.now() + (opts?.lockWaitMs ?? 0);
+  for (;;) {
+    try {
+      return await acquireOnce(opName, holder, opts);
+    } catch (err) {
+      if (!(err instanceof StaleLockError) || Date.now() >= deadline) throw err;
+      await new Promise((r) => setTimeout(r, 20 + Math.floor(Math.random() * 60)));
+    }
+  }
+}
+
+async function acquireOnce(opName: string, holder: string, opts?: AcquireLeaseOptions): Promise<AcquireLeaseResult> {
   const ttlMs = opts?.ttlMs ?? DEFAULT_LEASE_TTL_MS;
   const now = opts?.now?.() ?? new Date();
+  const mode = opts?.mode ?? "acquire";
 
-  const { sha, record: current } = await readLease(opName, opts);
+  const { sha, record: current, remoteSha } = await readLease(opName, opts);
   const expired = !current || isExpired(current, now);
   const ownedByUs = current?.holder === holder;
 
-  if (current && !expired && !ownedByUs) {
-    return { acquired: false, heldBy: current };
+  if (mode === "renew") {
+    if (!current || expired || !ownedByUs) return { acquired: false, reason: current && !expired ? "held" : "not-held", ...(current ? { heldBy: current } : {}) };
+    if (opts?.token !== undefined && current.token !== opts.token) return { acquired: false, reason: "token-mismatch", heldBy: current };
+  } else if (current && !expired && (!ownedByUs || mode === "claim")) {
+    return { acquired: false, heldBy: current, reason: "held" };
   }
 
   const renewing = !!current && ownedByUs && !expired;
@@ -225,21 +312,31 @@ export async function acquireLease(
     expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
   };
 
-  const { ref } = await projectLeaseRefs(opName, opts);
+  const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
   const blobSha = await writeBlob(JSON.stringify(record), opts);
   try {
     await updateRefCAS(ref, blobSha, sha, opts);
   } catch (err) {
     if (err instanceof RefCASConflictError) {
       const retry = await readLease(opName, opts);
-      return { acquired: false, heldBy: retry.record };
+      return { acquired: false, heldBy: retry.record, reason: "race" };
     }
     // A StaleLockError (or any other non-CAS failure) is NOT "someone else
     // has it" — propagate it as its own distinct error rather than folding
     // it into `heldBy`, per this function's doc.
     throw err;
   }
-  await pushRef(ref, opts).catch(() => undefined);
+  const pushed = await pushRefStatus(ref, { ...opts, expect: remoteSha }).catch(() => "rejected" as const);
+  if (pushed === "pushed") {
+    // What the remote holds now; the next push expects it.
+    await updateRefCAS(trackingRef, blobSha, remoteSha, opts).catch(() => undefined);
+  } else if (pushed === "rejected" && opts?.requirePush) {
+    // Undo the local write, which the remote refused, and report who has it there.
+    await (sha === null ? deleteRefCAS(ref, blobSha, opts) : updateRefCAS(ref, sha, blobSha, opts)).catch(() => undefined);
+    const retry = await readLease(opName, opts);
+    const heldBy = retry.record && retry.record.token !== record.token ? retry.record : undefined;
+    return { acquired: false, reason: "push-rejected", ...(heldBy ? { heldBy } : {}) };
+  }
   return { acquired: true, lease: record };
 }
 
@@ -249,23 +346,30 @@ export async function acquireLease(
  * silently drop someone else's. Best-effort courtesy: a lease nobody
  * releases is reclaimed anyway once its TTL passes, so a failed release
  * (returns `false`, never throws) is not itself a correctness problem.
+ *
+ * The deletion is pushed to the remote, expecting the value last fetched
+ * there, so another clone sees the lease free without waiting out its TTL
+ * (#2732).
  */
 export async function releaseLease(
   opName: string,
   holder: string,
   token: string,
-  opts?: { cwd?: string },
+  opts?: LeaseOptions,
 ): Promise<boolean> {
-  const { sha, record } = await readLease(opName, opts);
-  if (!sha || !record || record.holder !== holder || record.token !== token) return false;
-  const { ref } = await projectLeaseRefs(opName, opts);
-  try {
-    await deleteRefCAS(ref, sha, opts);
-  } catch {
-    return false;
+  const { sha, record, remoteSha } = await readLease(opName, opts);
+  if (!record || record.holder !== holder || record.token !== token) return false;
+  const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
+  if (sha) {
+    try {
+      await deleteRefCAS(ref, sha, opts);
+    } catch {
+      return false;
+    }
   }
-  await pushRef(ref, opts).catch(() => undefined);
-  return true;
+  const pushed = await pushRefStatus(ref, { ...opts, expect: remoteSha }).catch(() => "rejected" as const);
+  if (pushed === "pushed" && remoteSha) await deleteRefCAS(trackingRef, remoteSha, opts).catch(() => undefined);
+  return sha !== null || pushed === "pushed";
 }
 
 /**
@@ -278,7 +382,7 @@ export async function stillHoldsLease(
   opName: string,
   holder: string,
   token: string,
-  opts?: { cwd?: string },
+  opts?: LeaseOptions,
 ): Promise<boolean> {
   const { record } = await readLease(opName, opts);
   return record?.holder === holder && record?.token === token;

package/src/lifecycle/member-ledger.ts

@@ -5,8 +5,9 @@
  * A workspace member writes every lifecycle store under
  * `_members/<member>/` on the one existing branch: releases, snapshots, runs,
  * converge records and observation baselines under `<env>/`, gates under
- * `_gates/`, build records under `_builds/`. Its operator leases move the same
- * way, to `refs/chant/lease/_members/<member>/<op>`. Push, fetch, lease and
+ * `_gates/`, build records under `_builds/`, release plans under `_plans/`
+ * (ws-055, #2733). Its operator leases move the same way, to
+ * `refs/chant/lease/_members/<member>/<op>`. Push, fetch, lease and
  * staleness code are untouched: they still see one branch and plain refs.
  *
  * Everything else keeps today's flat layout, byte for byte:

package/src/lifecycle/plan-ledger.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { persistReleasePlan, readReleasePlan, InvalidReleasePlanError, type ReleasePlan } from "./plan-ledger";
+import { readRefSha } 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);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+function makePlan(digest: string, extra: Record<string, unknown> = {}): ReleasePlan {
+  return { digest, release: "r-abc12345", units: [{ id: "w-1", contract: "c-1" }], evidence: [], ...extra };
+}
+
+describe("lifecycle/plan-ledger", () => {
+  describe("persistReleasePlan / readReleasePlan", () => {
+    test("round-trips a plan by its own digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "1".repeat(64));
+
+        const { commit, written } = await persistReleasePlan(plan, { cwd: dir });
+        expect(written).toBe(true);
+        expect(commit).toMatch(/^[0-9a-f]{40}$/);
+
+        const readBack = await readReleasePlan(plan.digest, { cwd: dir });
+        expect(readBack).toEqual(plan);
+      });
+    });
+
+    test("readReleasePlan returns null for an unknown digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readReleasePlan("sha256:doesnotexist", { cwd: dir })).toBeNull();
+      });
+    });
+
+    test("a plan already written is never rewritten: no second commit, content unchanged", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "2".repeat(64));
+
+        const first = await persistReleasePlan(plan, { cwd: dir });
+        expect(first.written).toBe(true);
+        const tipAfterFirst = await readRefSha("refs/heads/chant/lifecycle", { cwd: dir });
+
+        const second = await persistReleasePlan(plan, { cwd: dir });
+        expect(second.written).toBe(false);
+        expect(second.commit).toBeNull();
+        const tipAfterSecond = await readRefSha("refs/heads/chant/lifecycle", { cwd: dir });
+
+        // Not a new commit — the branch tip is unchanged.
+        expect(tipAfterSecond).toBe(tipAfterFirst);
+        expect(await readReleasePlan(plan.digest, { cwd: dir })).toEqual(plan);
+      });
+    });
+
+    test("a plan with a different digest is a separate entry, coexisting with the first", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const planA = makePlan("sha256:" + "a".repeat(64), { release: "r-a" });
+        const planB = makePlan("sha256:" + "b".repeat(64), { release: "r-b" });
+
+        await persistReleasePlan(planA, { cwd: dir });
+        await persistReleasePlan(planB, { cwd: dir });
+
+        expect(await readReleasePlan(planA.digest, { cwd: dir })).toEqual(planA);
+        expect(await readReleasePlan(planB.digest, { cwd: dir })).toEqual(planB);
+      });
+    });
+
+    test("refuses a plan with no digest field", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = { release: "r-nodigest" } as unknown as ReleasePlan;
+        await expect(persistReleasePlan(plan, { cwd: dir })).rejects.toThrow(InvalidReleasePlanError);
+      });
+    });
+
+    test("release ledger and plan store coexist on the same orphan branch", async () => {
+      const { appendReleaseRecord, readReleaseLedger } = await import("./release-ledger");
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "3".repeat(64));
+        await persistReleasePlan(plan, { cwd: dir });
+        await appendReleaseRecord(
+          {
+            component: "svc",
+            env: "prod",
+            digest: plan.digest,
+            gitSha: "deadbeef",
+            runId: "run-1",
+            timestamp: "2026-01-01T00:00:00.000Z",
+            actor: "ci-bot",
+          },
+          { cwd: dir },
+        );
+
+        expect(await readReleasePlan(plan.digest, { cwd: dir })).toEqual(plan);
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(records[0].digest).toBe(plan.digest);
+      });
+    });
+
+    test("a member's plan lives under _members/<member>/_plans/ (#2524 D7), reached via the prefix readReleasePlan takes", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        mkdirSync(join(dir, "apps", "web"), { recursive: true });
+        writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({
+          name: "acme",
+          schema: 1,
+          members: [{ name: "web", dir: "apps/web", kind: "chant" }],
+        }));
+        writeFileSync(join(dir, "apps", "web", "chant.config.ts"), "");
+        git(["add", "-A"], dir);
+        git(["commit", "-q", "-m", "workspace"], dir);
+
+        const plan = makePlan("sha256:" + "4".repeat(64));
+        // Persisted from inside the member's own directory, the way `chant
+        // components release` runs there — writeBlobToPath resolves the
+        // _members/web/ prefix automatically from cwd.
+        const webDir = join(dir, "apps", "web");
+        await persistReleasePlan(plan, { cwd: webDir });
+
+        // readReleasePlan reads it back two ways: with the matching prefix
+        // (as ../workspace/status.ts resolves it for a "members"-layout
+        // release), and directly at the branch path it actually landed on.
+        expect(await readReleasePlan(plan.digest, { cwd: dir, prefix: "_members/web/" })).toEqual(plan);
+        const raw = git(["show", `chant/lifecycle:_members/web/_plans/sha256_${"4".repeat(64)}.json`], dir);
+        expect(raw.exitCode).toBe(0);
+        expect(JSON.parse(raw.stdout)).toEqual(plan);
+      });
+    });
+  });
+});