@intentius/chant 0.85.0 → 0.87.0

package/src/workspace/runtimes.ts

@@ -0,0 +1,107 @@
+/**
+ * The runtimes a member's components can deploy on, for `chant workspace
+ * graph --composites` (#2674): the built-in `local` runtime, and every lexicon
+ * the member's `chant.config.ts` configures whose `opRuntime` hosts
+ * `chant run --components`. That is the list `chant run --components <name>
+ * --on <runtime>` accepts in the member's directory (`../cli/handlers/run.ts`),
+ * so a reader such as hud offers these and never guesses a runtime.
+ *
+ * `local` is the default. A configured default (`run.on`) is read once the
+ * config type has one; until then the command without `--on` runs locally.
+ *
+ * The config is read the way `chant run` reads it, from the member's
+ * directory, in the working tree or in the tree `--at` exported. Reading it
+ * runs the member's `chant.config.ts` and imports the lexicons it lists.
+ */
+
+import { join } from "node:path";
+import { lexiconNames } from "../lexicon-module";
+import type { ReasonCode } from "./reason-codes";
+
+/** The runtime core provides, which `chant run` uses without `--on`. */
+export const LOCAL_RUNTIME = "local";
+
+/** Why a member's runtimes list only part of what its config names. Closed: part of the read contract. */
+export const RUNTIME_REASON_CODES = [
+  /** The member's chant.config.ts could not be read, so only local is listed. */
+  "runtimes-config-unreadable",
+  /** A configured lexicon could not be loaded, so it is not listed. */
+  "runtimes-lexicon-unreadable",
+] as const satisfies readonly ReasonCode[];
+export type RuntimeReasonCode = (typeof RUNTIME_REASON_CODES)[number];
+
+export interface RuntimeReason {
+  code: RuntimeReasonCode;
+  message: string;
+}
+
+/** One runtime a component can deploy on. */
+export interface ComponentRuntime {
+  /** What `--on` takes: the lexicon's name, or `local`. */
+  name: string;
+  /** The lexicon that hosts it, or null for `local`. */
+  lexicon: string | null;
+  /** True for the runtime `chant run --components` uses without `--on`. */
+  default: boolean;
+  /** The command that deploys the component on it, run in the member's directory. */
+  command: string;
+}
+
+/** What one member's config says about runtimes. */
+export interface MemberRuntimes {
+  /** Configured lexicons whose `opRuntime` hosts component runs, in config order. */
+  lexicons: string[];
+  /** The default runtime's name. */
+  default: string;
+  reasons: RuntimeReason[];
+}
+
+/** Loads a lexicon plugin by name; `loadPlugin` from the CLI unless a test swaps it. */
+export type PluginLoader = (name: string) => Promise<{ opRuntime?: { runComponents?: unknown } }>;
+
+const firstLine = (err: unknown): string => (err instanceof Error ? err.message : String(err)).split("\n")[0];
+
+/** Read the runtimes a member's config offers. `dir` is the member's directory on disk. */
+export async function readMemberRuntimes(dir: string, load?: PluginLoader): Promise<MemberRuntimes> {
+  const reasons: RuntimeReason[] = [];
+  let names: string[];
+  try {
+    const { loadChantConfig } = await import("../config");
+    names = lexiconNames((await loadChantConfig(dir)).config.lexicons ?? []);
+  } catch (err) {
+    return { lexicons: [], default: LOCAL_RUNTIME, reasons: [{ code: "runtimes-config-unreadable", message: `chant.config.ts: ${firstLine(err)}` }] };
+  }
+  const loader = load ?? (await import("../cli/plugins")).loadPlugin;
+  const lexicons: string[] = [];
+  for (const name of names) {
+    try {
+      const plugin = await loader(name);
+      if (plugin.opRuntime?.runComponents) lexicons.push(name);
+    } catch (err) {
+      reasons.push({ code: "runtimes-lexicon-unreadable", message: `lexicon "${name}": ${firstLine(err)}` });
+    }
+  }
+  return { lexicons, default: LOCAL_RUNTIME, reasons };
+}
+
+/** The runtimes one component can deploy on, `local` first, each with its command line. */
+export function componentRuntimes(component: string, member: MemberRuntimes | undefined): ComponentRuntime[] {
+  const def = member?.default ?? LOCAL_RUNTIME;
+  const entry = (name: string, lexicon: string | null): ComponentRuntime => ({
+    name,
+    lexicon,
+    default: name === def,
+    command: `chant run --components ${component}${name === LOCAL_RUNTIME ? "" : ` --on ${name}`}`,
+  });
+  return [entry(LOCAL_RUNTIME, null), ...(member?.lexicons ?? []).filter((l) => l !== LOCAL_RUNTIME).map((l) => entry(l, l))];
+}
+
+/** Read the runtimes of each member of kind chant, from the tree at `root`. */
+export async function readRuntimesIn(root: string, members: readonly { name: string; dir: string; kind: string }[], load?: PluginLoader): Promise<Map<string, MemberRuntimes>> {
+  const out = new Map<string, MemberRuntimes>();
+  for (const m of members) {
+    if (m.kind !== "chant") continue;
+    out.set(m.name, await readMemberRuntimes(m.dir === "." ? root : join(root, ...m.dir.split("/")), load));
+  }
+  return out;
+}

package/src/workspace/status-contract.test.ts

@@ -19,6 +19,7 @@ import {
   runWorkspaceStatus,
   STATUS_CONTRACT_VERSION,
   STATUS_ERROR_CODES,
+  STATUS_GATE_REASON_CODES,
   STATUS_OUTPUT_SCHEMA_ID,
   STATUS_REASON_CODES,
   workspaceStatus,
@@ -146,6 +147,7 @@ describe("status output schema", () => {
   test("lists exactly the reason and error codes the code can return", () => {
     expect(schema.$defs.environment.properties.reason.oneOf[1].properties!.code.enum).toEqual([...STATUS_REASON_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...STATUS_ERROR_CODES]);
+    expect(schema.$defs.gateLedger.properties.reason.oneOf[1].properties!.code.enum).toEqual([...STATUS_GATE_REASON_CODES]);
   });
 });
 
@@ -296,6 +298,167 @@ describe("chant workspace status on built workspaces", () => {
   });
 });
 
+/** One pending fact, as a run records it. */
+const pending = (op: string, gate: string, timestamp: string, extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ version: 1, kind: "pending", op, gate, timestamp, expiresAt: "2026-12-31T00:00:00.000Z", origin: "cli", ...extra });
+
+/** One approval, as `chant approve` records it. */
+const approval = (op: string, gate: string, resolvedBy: string, timestamp: string, extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ version: 1, kind: "resolution", op, gate, resolvedBy, timestamp, origin: "cli", approver: { kind: "human" }, ...extra });
+
+const NOW = "2026-09-24T00:00:00.000Z";
+
+/**
+ * web writes _members/web/, api and the root member read the flat _gates/.
+ * Each gate is in one state: approved, pending with part of a quorum,
+ * expired, superseded, and an Op gate that records no environment.
+ */
+function gated(): string {
+  const root = twoLayouts();
+  lifecycle(root, {
+    "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("a"), "a".repeat(40))),
+    "_members/web/_gates/web.jsonl": jsonl(
+      pending("web", "deploy", "2026-09-20T00:00:00.000Z", { environment: "staging", planDigest: D("1") }),
+      approval("web", "deploy", "alice", "2026-09-20T01:00:00.000Z", { environment: "staging", planDigest: D("1") }),
+      pending("web", "deploy", "2026-09-21T00:00:00.000Z", { environment: "prod", planDigest: D("2") }),
+      pending("web", "deploy", "2026-09-21T00:00:00.000Z", { environment: "qa", planDigest: D("3") }),
+      // chant approve --expire writes a line with no environment; a run ignores it for an environment-bound gate.
+      pending("web", "deploy", "2026-09-22T00:00:00.000Z", { expiresAt: "2026-09-22T00:00:00.000Z" }),
+      pending("web", "review", "2026-09-20T00:00:00.000Z", { environment: "staging", planDigest: D("4"), approval: { mode: "log-only", quorum: { count: 2 } } }),
+      approval("web", "review", "bob", "2026-09-20T02:00:00.000Z", { environment: "staging", planDigest: D("4") }),
+      approval("web", "review", "unattested", "2026-09-20T03:00:00.000Z", { environment: "staging", planDigest: D("4"), origin: "mcp", approver: { kind: "agent" } }),
+    ),
+    "staging/releases.jsonl": jsonl(release("api", "staging", D("b"), "b".repeat(40))),
+    "_gates/api.jsonl": jsonl(
+      pending("api", "deploy", "2026-09-10T00:00:00.000Z", { environment: "staging", planDigest: D("5"), expiresAt: "2026-09-12T00:00:00.000Z" }),
+      pending("api", "smoke", "2026-09-20T00:00:00.000Z", { environment: "staging", planDigest: D("6") }),
+      approval("api", "smoke", "carol", "2026-09-20T05:00:00.000Z", { environment: "staging", planDigest: D("7") }),
+      "{not json",
+    ),
+    "_gates/nightly.jsonl": jsonl(pending("nightly", "confirm", "2026-09-23T00:00:00.000Z"), approval("nightly", "confirm", "dave", "2026-09-23T01:00:00.000Z")),
+  });
+  return root;
+}
+
+describe("gate state in chant workspace status --json (#2674)", () => {
+  test("each member lists its gates with state, approvals, quorum and the approve line", async () => {
+    const doc = result(await workspaceStatus({ cwd: gated(), env: "staging", compareTo: "prod", now: NOW }));
+    expectValid(doc);
+    const [site, web, api] = doc.members;
+    expect(web.gateLedger).toEqual({ layout: "members", path: "_members/web/_gates", shared: false, malformed: 0, reason: null });
+    expect(web.gates).toEqual([
+      {
+        component: "web",
+        name: "deploy",
+        env: "staging",
+        planDigest: D("1"),
+        state: "approved",
+        recordedAt: "2026-09-20T00:00:00.000Z",
+        expiresAt: "2026-12-31T00:00:00.000Z",
+        approvals: [{ principal: "alice", channel: "cli", at: "2026-09-20T01:00:00.000Z" }],
+        needed: 1,
+        approve: "chant approve web deploy --env staging",
+      },
+      {
+        component: "web",
+        name: "deploy",
+        env: "prod",
+        planDigest: D("2"),
+        state: "pending",
+        recordedAt: "2026-09-21T00:00:00.000Z",
+        expiresAt: "2026-12-31T00:00:00.000Z",
+        approvals: [],
+        needed: 1,
+        approve: "chant approve web deploy --env prod",
+      },
+      {
+        component: "web",
+        name: "review",
+        env: "staging",
+        planDigest: D("4"),
+        state: "pending",
+        recordedAt: "2026-09-20T00:00:00.000Z",
+        expiresAt: "2026-12-31T00:00:00.000Z",
+        // The agent's approval doesn't count toward the quorum.
+        approvals: [{ principal: "bob", channel: "cli", at: "2026-09-20T02:00:00.000Z" }],
+        needed: 2,
+        approve: "chant approve web review --env staging",
+      },
+    ]);
+    // api and the root member both read the flat _gates/.
+    expect(api.gateLedger).toEqual({ layout: "flat", path: "_gates", shared: true, malformed: 1, reason: null });
+    expect(site.gates).toEqual(api.gates);
+    expect(api.gates.map((g) => [g.component, g.name, g.env, g.state, g.approve])).toEqual([
+      ["api", "deploy", "staging", "expired", "chant approve api deploy --env staging"],
+      ["api", "smoke", "staging", "superseded", "chant approve api smoke --env staging"],
+      ["nightly", "confirm", null, "approved", "chant approve nightly confirm"],
+    ]);
+    // The superseding approval named another plan, so it isn't listed as one that counts.
+    expect(api.gates[1].approvals).toEqual([]);
+    expect(api.gates[2]).toMatchObject({ planDigest: null, approvals: [{ principal: "dave", channel: "cli" }] });
+    // Gate reasons and gate states don't change readable or the summary.
+    expect(doc.summary.unreadable).toBe(0);
+  });
+
+  test("only the environments asked for are listed, and the text view doesn't change", async () => {
+    const root = gated();
+    const doc = result(await workspaceStatus({ cwd: root, env: "prod", now: NOW }));
+    expectValid(doc);
+    const web = doc.members.find((m) => m.name === "web")!;
+    expect(web.gates.map((g) => [g.name, g.env])).toEqual([["deploy", "prod"]]);
+    const plain = { ...doc, members: doc.members.map((m) => ({ ...m, gates: [], gateLedger: { ...m.gateLedger, reason: null } })) };
+    expect(formatStatus(doc)).toBe(formatStatus(plain));
+    expect(formatStatus(doc)).not.toContain("deploy");
+  });
+
+  test("a member with no gate ledger, a checkout with no branch, and an unreadable ledger each carry a reason", async () => {
+    const root = twoLayouts();
+    const none = result(await workspaceStatus({ cwd: root, env: "staging", now: NOW }));
+    expectValid(none);
+    expect(none.members.map((m) => [m.name, m.gateLedger.reason?.code, m.gates.length])).toEqual([
+      ["site", "gates-no-gate-ledger", 0],
+      ["web", "gates-no-gate-ledger", 0],
+      ["api", "gates-no-gate-ledger", 0],
+    ]);
+    expect(none.members[1].gateLedger.reason!.message).toBe("_members/web/_gates does not exist on chant/lifecycle: no run has reached a gate");
+
+    const bare = repo({ "chant.workspace.json": declaration([{ name: "web", dir: "web", kind: "chant" }]) });
+    const noBranch = result(await workspaceStatus({ cwd: bare, env: "prod", now: NOW }));
+    expectValid(noBranch);
+    expect(noBranch.members[0].gateLedger).toMatchObject({ layout: "flat", path: "_gates", reason: { code: "gates-no-ledger" } });
+
+    const broken = result(
+      await workspaceStatus({
+        cwd: gated(),
+        env: "staging",
+        now: NOW,
+        readGates: async (dir) => {
+          if (dir === "_members/web/_gates") throw new Error("fatal: bad object\nmore");
+          return null;
+        },
+      }),
+    );
+    expectValid(broken);
+    const web = broken.members.find((m) => m.name === "web")!;
+    expect(web.gateLedger.reason).toEqual({ code: "gates-ledger-unreadable", message: "_members/web/_gates: fatal: bad object" });
+    expect(web.gates).toEqual([]);
+    expect(web.readable).toBe(true);
+  });
+
+  test("the JSON the command prints carries the gates", async () => {
+    const root = gated();
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      expect(await runWorkspaceStatus({ args: { extraPositional: "staging", extraPositional2: root, json: true } } as unknown as CommandContext)).toBe(0);
+      const printed = JSON.parse(String(log.mock.calls.at(-1)?.[0])) as StatusDocument;
+      expectValid(printed);
+      expect(result(printed).members.find((m) => m.name === "web")!.gates.map((g) => g.approve)).toContain("chant approve web deploy --env staging");
+    } finally {
+      log.mockRestore();
+    }
+  });
+});
+
 describe("chant workspace status on the chant repo (#2557)", () => {
   test("validates and lists every declared member", async () => {
     const doc = result(await workspaceStatus({ cwd: join(REPO, "packages", "core"), env: "prod", compareTo: "staging" }));

package/src/workspace/status-gates.ts

@@ -0,0 +1,215 @@
+/**
+ * Gate state for `chant workspace status --json` (#2674): each member's gates
+ * as its gate ledger on `chant/lifecycle` records them, so a reader such as
+ * hud never runs `git show` on the branch itself.
+ *
+ * A member's gate ledger is the `_gates/` directory under its ledger prefix:
+ * `_members/<member>/_gates/<component>.jsonl` for a member that writes the
+ * member layout (#2538), and the flat `_gates/<component>.jsonl` otherwise,
+ * chosen the same way as its release ledger. Each file is keyed by the
+ * component, or by the op for a gate an Op run reached, and holds both the
+ * pending facts a run records and the approvals `chant approve` records
+ * (`../lifecycle/gate-ledger.ts`).
+ *
+ * A gate's state is decided the way a run decides it (`evaluateGate` in
+ * `../op/gate.ts`), without writing anything: the newest pending fact for the
+ * gate in its environment is the anchor, only approvals recorded since it and
+ * for its plan count, and a gate with an `approval` block counts them with
+ * `tallyGateApprovals`, as `describeApprovalProgress` does after an approve.
+ */
+
+import { execFileSync } from "node:child_process";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, parseGateLedger } from "../lifecycle/gate-ledger";
+import { tallyGateApprovals } from "../op/gate";
+import type { ReasonCode } from "./reason-codes";
+
+/** Why a member's gates can't be listed. Closed: a new code is a contract change. */
+export const GATE_REASON_CODES = [
+  /** The checkout has no `chant/lifecycle` branch, so there is no ledger to read gates from. */
+  "gates-no-ledger",
+  /** The branch has no gate ledger for the member: no run of it has reached a gate. */
+  "gates-no-gate-ledger",
+  /** Reading the member's gate ledger failed, so no gate is listed. */
+  "gates-ledger-unreadable",
+] as const satisfies readonly ReasonCode[];
+export type GateReasonCode = (typeof GATE_REASON_CODES)[number];
+
+export type GateState = "pending" | "approved" | "expired" | "superseded";
+
+export interface StatusGateApproval {
+  /** Who recorded it: `chant approve --approver`, or the CI or shell identity. */
+  principal: string;
+  /** The channel it was recorded on (`cli`, `mcp`, `acp`), or null for a record older than chant#2384. */
+  channel: string | null;
+  at: string;
+}
+
+export interface StatusGate {
+  /** The ledger file's key: the component, or the op for a gate an Op run reached. */
+  component: string;
+  /** The gate's name. */
+  name: string;
+  /** The environment the gate was reached in, or null for a gate that records none (an Op gate). */
+  env: string | null;
+  /** The plan the run reached the gate with, or null for a gate that binds no plan. */
+  planDigest: string | null;
+  state: GateState;
+  /** When the run recorded the pending fact the state is read against. */
+  recordedAt: string;
+  expiresAt: string;
+  /** The approvals that count toward the gate for this plan, oldest first. */
+  approvals: StatusGateApproval[];
+  /** How many human approvals the gate needs: its quorum's count, 1 without one. */
+  needed: number;
+  /** The command that approves it, run in the member's directory. */
+  approve: string;
+}
+
+export interface StatusGateLedger {
+  /** `members` for `_members/<member>/_gates`, `flat` for `_gates`. */
+  layout: "members" | "flat";
+  /** The gate ledger directory on the branch. */
+  path: string;
+  /** True when more than one member in this output reads the same flat directory. */
+  shared: boolean;
+  /** Lines that are neither a pending fact nor an approval, skipped. */
+  malformed: number;
+  reason: { code: GateReasonCode; message: string } | null;
+}
+
+/**
+ * Reads the gate ledger files in `dir` on the branch at `commit`: file name
+ * without `.jsonl` to contents. Null when the directory doesn't exist; throws
+ * when it can't be read.
+ */
+export type GateLedgerReader = (dir: string, commit: string, cwd: string) => Promise<Map<string, string> | null>;
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+}
+
+export const defaultGateLedgerReader: GateLedgerReader = async (dir, commit, cwd) => {
+  try {
+    git(cwd, ["rev-parse", "--verify", "--quiet", `${commit}:${dir}`]);
+  } catch {
+    return null;
+  }
+  const files = new Map<string, string>();
+  for (const name of git(cwd, ["ls-tree", "--name-only", `${commit}:${dir}`]).split("\n")) {
+    if (!name.endsWith(".jsonl")) continue;
+    files.set(name.slice(0, -".jsonl".length), git(cwd, ["cat-file", "blob", `${commit}:${dir}/${name}`]));
+  }
+  return files;
+};
+
+/** The exact `chant approve` line for a gate. */
+export function approveCommand(component: string, gate: string, env: string | null): string {
+  return `chant approve ${component} ${gate}${env !== null ? ` --env ${env}` : ""}`;
+}
+
+const approvalOf = (r: GateResolutionRecord): StatusGateApproval => ({ principal: r.resolvedBy, channel: r.origin ?? null, at: r.timestamp });
+
+/** One gate in one environment, decided against its newest pending fact. */
+function decide(component: string, standing: PendingGateRecord, resolutions: GateResolutionRecord[], now: string): StatusGate {
+  const gate = standing.gate;
+  const env = standing.environment ?? null;
+  const since = standing.timestamp;
+  const planDigest = standing.planDigest;
+  // #2574: an approval recorded for another environment doesn't count; one
+  // that records none is kept, so it reads as a mismatch, as a run reads it.
+  const own = env === null ? resolutions : resolutions.filter((r) => r.environment === undefined || r.environment === env);
+
+  let approved: boolean;
+  let approvals: GateResolutionRecord[];
+  let needed = 1;
+  let mismatched: GateResolutionRecord | undefined;
+  if (standing.approval) {
+    const tally = tallyGateApprovals(own, gate, since, planDigest, standing.approval);
+    approved = tally.permit !== undefined || tally.counted.length >= tally.need;
+    approvals = tally.permit && !tally.counted.includes(tally.permit) ? [...tally.counted, tally.permit] : tally.counted;
+    needed = tally.need;
+    mismatched = tally.mismatched;
+  } else {
+    const at = (r: GateResolutionRecord) => new Date(r.timestamp).getTime();
+    approvals = own
+      .filter((r) => r.gate === gate && at(r) >= new Date(since).getTime() && (planDigest === undefined || r.planDigest === planDigest))
+      .sort((a, b) => at(a) - at(b));
+    approved = approvals.length > 0;
+    mismatched = latestResolutionForPlan(own, gate, since, planDigest).mismatched;
+  }
+
+  const state: GateState = approved ? "approved" : isPendingGateExpired(standing, now) ? "expired" : mismatched ? "superseded" : "pending";
+  return {
+    component,
+    name: gate,
+    env,
+    planDigest: planDigest ?? null,
+    state,
+    recordedAt: standing.timestamp,
+    expiresAt: standing.expiresAt,
+    approvals: approvals.map(approvalOf),
+    needed,
+    approve: approveCommand(component, gate, env),
+  };
+}
+
+/**
+ * Every gate in one ledger file, one per gate and environment, for the
+ * environments in `envs`. A gate whose facts record no environment (an Op
+ * gate) is listed whatever `envs` is. A pending fact with no environment on a
+ * gate whose other facts have one is left out, as a run leaves it out: such a
+ * line binds no environment, and `chant approve --expire` writes one.
+ */
+export function gatesInLedger(component: string, content: string, envs: readonly string[], now: string): { gates: StatusGate[]; malformed: number } {
+  const { pending, resolutions, malformed } = parseGateLedger(content);
+  const gates: StatusGate[] = [];
+  for (const gate of [...new Set(pending.map((p) => p.gate))].sort()) {
+    const facts = pending.filter((p) => p.gate === gate);
+    const bound = facts.some((p) => p.environment !== undefined);
+    const byEnv = new Map<string | null, PendingGateRecord[]>();
+    for (const p of facts) {
+      const env = p.environment ?? null;
+      if (bound && env === null) continue;
+      if (env !== null && !envs.includes(env)) continue;
+      byEnv.set(env, [...(byEnv.get(env) ?? []), p]);
+    }
+    for (const env of [...byEnv.keys()].sort((a, b) => envs.indexOf(a ?? "") - envs.indexOf(b ?? ""))) {
+      gates.push(decide(component, latestPendingGate(byEnv.get(env)!, gate)!, resolutions, now));
+    }
+  }
+  return { gates, malformed };
+}
+
+/** Read one member's gate ledger directory at `commit` and list its gates. */
+export async function readMemberGates(
+  dir: string,
+  layout: "members" | "flat",
+  commit: string | null,
+  envs: readonly string[],
+  cwd: string,
+  now: string,
+  read: GateLedgerReader = defaultGateLedgerReader,
+): Promise<{ gates: StatusGate[]; ledger: StatusGateLedger }> {
+  const ledger: StatusGateLedger = { layout, path: dir, shared: false, malformed: 0, reason: null };
+  if (commit === null) {
+    return { gates: [], ledger: { ...ledger, reason: { code: "gates-no-ledger", message: "the checkout has no chant/lifecycle branch, so no gate is recorded in it" } } };
+  }
+  let files: Map<string, string> | null;
+  try {
+    files = await read(dir, commit, cwd);
+  } catch (err) {
+    const message = err instanceof Error ? err.message.split("\n")[0] : String(err);
+    return { gates: [], ledger: { ...ledger, reason: { code: "gates-ledger-unreadable", message: `${dir}: ${message}` } } };
+  }
+  if (files === null) {
+    return { gates: [], ledger: { ...ledger, reason: { code: "gates-no-gate-ledger", message: `${dir} does not exist on chant/lifecycle: no run has reached a gate` } } };
+  }
+  const gates: StatusGate[] = [];
+  for (const component of [...files.keys()].sort()) {
+    const read = gatesInLedger(component, files.get(component)!, envs, now);
+    gates.push(...read.gates);
+    ledger.malformed += read.malformed;
+  }
+  return { gates, ledger };
+}

package/src/workspace/status.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/status/v1/status.schema.json",
   "title": "chant workspace status output",
-  "description": "What `chant workspace status <env> --json` prints, version 1 of the read contract for releases across members (#2524 D15, D19, #2544). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace status <env> --json` prints, version 1 of the read contract for releases across members (#2524 D15, D19, #2544). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`. Each member's gates, read from its gate ledger on the same branch, are in the JSON only (#2674).",
   "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
   "$defs": {
     "result": {
@@ -67,7 +67,7 @@
     },
     "member": {
       "type": "object",
-      "required": ["name", "dir", "kind", "environments", "compare", "readable"],
+      "required": ["name", "dir", "kind", "environments", "compare", "readable", "gateLedger", "gates"],
       "properties": {
         "name": { "type": "string" },
         "dir": { "type": "string", "description": "Relative to the workspace root, with / separators; \".\" is the root member." },
@@ -83,7 +83,73 @@
           "description": "Null without --compare-to.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/compare" }]
         },
-        "readable": { "type": "boolean", "description": "True exactly when no environment has a reason." }
+        "readable": { "type": "boolean", "description": "True exactly when no environment has a reason. A gate ledger reason doesn't change it." },
+        "gateLedger": { "$ref": "#/$defs/gateLedger" },
+        "gates": {
+          "description": "Each gate the member's gate ledger records, one per gate and environment, for env and compareTo. A gate that records no environment (an Op gate) is listed whatever the environment. Sorted by component, then gate. Empty when gateLedger has a reason.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/gate" }
+        }
+      }
+    },
+    "gateLedger": {
+      "type": "object",
+      "required": ["layout", "path", "shared", "malformed", "reason"],
+      "properties": {
+        "layout": {
+          "enum": ["members", "flat"],
+          "description": "members: _members/<member>/_gates. flat: _gates. Chosen as for the member's release ledger."
+        },
+        "path": { "type": "string", "description": "The gate ledger directory on chant/lifecycle. Each file in it is <component>.jsonl, or <op>.jsonl for a gate an Op run reached." },
+        "shared": { "type": "boolean", "description": "True when more than one member in this output reads the flat _gates directory, so they list the same gates." },
+        "malformed": { "type": "integer", "minimum": 0, "description": "Lines that are neither a pending fact nor an approval. They are skipped." },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["gates-no-ledger", "gates-no-gate-ledger", "gates-ledger-unreadable"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "gate": {
+      "type": "object",
+      "required": ["component", "name", "env", "planDigest", "state", "recordedAt", "expiresAt", "approvals", "needed", "approve"],
+      "properties": {
+        "component": { "type": "string", "description": "The ledger file's key: the component, or the op for a gate an Op run reached." },
+        "name": { "type": "string", "description": "The gate's name." },
+        "env": {
+          "description": "The environment the run reached the gate in, or null for a gate that records none.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/env" }]
+        },
+        "planDigest": { "type": ["string", "null"], "description": "The plan the run reached the gate with (#2300), or null for a gate that binds no plan. An approval counts only for this plan." },
+        "state": {
+          "enum": ["pending", "approved", "expired", "superseded"],
+          "description": "Read from the newest pending fact for the gate in env, as a run reads it. approved: the approvals recorded since it, for its plan, pass the gate (its quorum, or a policy permit in enforce mode). expired: not approved, and the pending fact is past expiresAt, so the next run records a fresh one. superseded: not approved, and an approval recorded since it names a different plan, so it doesn't count. pending: none of these."
+        },
+        "recordedAt": { "type": "string", "description": "When the run recorded the pending fact." },
+        "expiresAt": { "type": "string" },
+        "approvals": {
+          "description": "The approvals that count toward the gate for its plan, oldest first.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["principal", "channel", "at"],
+            "properties": {
+              "principal": { "type": "string", "description": "Who recorded it." },
+              "channel": { "type": ["string", "null"], "description": "The channel it was recorded on, such as cli or mcp, or null for a record older than chant#2384." },
+              "at": { "type": "string" }
+            }
+          }
+        },
+        "needed": { "type": "integer", "minimum": 1, "description": "The human approvals the gate needs: its quorum's count, 1 without one." },
+        "approve": { "type": "string", "description": "The chant approve line for the gate, run in the member's directory: chant approve <component> <gate>, with --env <env> when env is not null." }
       }
     },
     "environment": {