@intentius/chant 0.101.0 → 0.102.0

package/src/op/emulator-lifecycle.ts

@@ -16,8 +16,25 @@ export interface EmulatorSpec {
   image: string;
   /** Port the emulator listens on inside the container (e.g. 4566, 4280). */
   containerPort: number;
-  /** Health path on the host port (e.g. `/_localstack/health`, `/_mudflaps/health`). */
-  healthPath: string;
+  /**
+   * Health path on the host port (e.g. `/_localstack/health`, `/_mudflaps/health`).
+   * Required unless {@link readyCommand} is set: an emulator is reached over
+   * HTTP or checks itself inside its container, one or the other.
+   */
+  healthPath?: string;
+  /**
+   * A command run inside the container (`docker exec <name> ...`) whose exit
+   * status 0 means ready, for an emulator with no HTTP health endpoint: a
+   * database server answers its own client (`pg_isready`), not a URL. When
+   * set, it replaces the HTTP poll of {@link healthPath}.
+   */
+  readyCommand?: readonly string[];
+  /**
+   * The endpoint a tool connects to, for an emulator that is not reached over
+   * HTTP, e.g. a `postgres://` URL for a database server.
+   * Default: `http://localhost:<port>`.
+   */
+  endpoint?: (port: number) => string;
   /** Readiness predicate over the health body. Default: any 200 response is ready. */
   ready?: (healthBody: string) => boolean;
   /** Extra `docker run` args inserted before the image (e.g. a socket mount). */
@@ -102,6 +119,8 @@ export interface EmulatorLifecycle {
   existsCommand(name: string): string;
   rmCommand(name: string): string;
   healthUrl(port: number): string;
+  /** `docker exec <name> <readyCommand...>`, or undefined for an emulator polled over HTTP. */
+  readyExecCommand(name: string): string | undefined;
   endpoint(port: number): string;
   up(args?: EmulatorUpArgs, signal?: AbortSignal): Promise<{ endpoint: string }>;
   down(args?: { name?: string }, signal?: AbortSignal): Promise<void>;
@@ -116,6 +135,9 @@ export interface EmulatorLifecycle {
  */
 export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
   const ready = spec.ready ?? (() => true);
+  if (spec.healthPath === undefined && !spec.readyCommand?.length) {
+    throw new Error(`emulator "${spec.name}" declares neither a healthPath nor a readyCommand, so nothing can tell when it is ready`);
+  }
 
   const runCommand = (args: EmulatorUpArgs = {}): string => {
     const name = args.name ?? spec.name;
@@ -128,8 +150,30 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
   };
   const existsCommand = (name: string): string => `docker ps -q -f name=${name}`;
   const rmCommand = (name: string): string => `docker rm -f ${name}`;
-  const healthUrl = (port: number): string => `http://localhost:${port}${spec.healthPath}`;
-  const endpoint = (port: number): string => `http://localhost:${port}`;
+  const healthUrl = (port: number): string => `http://localhost:${port}${spec.healthPath ?? ""}`;
+  const endpoint = (port: number): string => (spec.endpoint ? spec.endpoint(port) : `http://localhost:${port}`);
+  const readyExecCommand = (name: string): string | undefined =>
+    spec.readyCommand?.length ? ["docker", "exec", name, ...spec.readyCommand].join(" ") : undefined;
+
+  /** One readiness probe: the in-container command when declared, else the HTTP health path. */
+  async function probe(name: string, port: number, signal?: AbortSignal): Promise<boolean> {
+    const command = readyExecCommand(name);
+    if (command) {
+      try {
+        await execAsync(command, { signal });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    try {
+      const res = await fetch(healthUrl(port), { signal });
+      return res.ok && ready(await res.text());
+    } catch {
+      // Not up yet (connection refused / non-2xx) — retry.
+      return false;
+    }
+  }
 
   async function up(args: EmulatorUpArgs = {}, signal?: AbortSignal): Promise<{ endpoint: string }> {
     const name = args.name ?? spec.name;
@@ -153,19 +197,13 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
       await execAsync(runCommand({ ...args, name, port }), { signal });
     }
 
-    const url = healthUrl(port);
     const deadline = Date.now() + timeoutMs;
     let ok = false;
     while (Date.now() < deadline) {
       if (signal?.aborted) throw new Error(`emulator "${name}" wait aborted`);
-      try {
-        const res = await fetch(url, { signal });
-        if (res.ok && ready(await res.text())) {
-          ok = true;
-          break;
-        }
-      } catch {
-        // Not up yet (connection refused / non-2xx) — retry.
+      if (await probe(name, port, signal)) {
+        ok = true;
+        break;
       }
       await sleep(intervalMs, signal);
     }
@@ -187,5 +225,5 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
     }
   }
 
-  return { runCommand, existsCommand, rmCommand, healthUrl, endpoint, up, down };
+  return { runCommand, existsCommand, rmCommand, healthUrl, readyExecCommand, endpoint, up, down };
 }

package/src/op/gate-approval.test.ts

@@ -191,6 +191,80 @@ describe("gate approval — policy decisions (#2508)", () => {
     expect(check.satisfied).toBe(false);
   });
 
+  test("log-only then enforce: a permit recorded under log-only does not pass the enforced gate (#2512)", async () => {
+    const logOnly: ResolvedGateApproval = { policy: POLICY, mode: "log-only", context: { risk: "low" } };
+    const enforce: ResolvedGateApproval = { ...logOnly, mode: "enforce" };
+    // The pending fact was recorded while the gate was log-only, and the agent's allow was recorded against it.
+    const port = memoryGateLedgerPort({
+      resolutions: [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("log-only") })],
+      pending: [{ ...PENDING, approval: logOnly }],
+    });
+    const check = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: NOW });
+    expect(check.satisfied).toBe(false);
+
+    const tally = tallyGateApprovals(
+      [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("log-only") })],
+      "ship", PENDING.timestamp, PLAN_A, enforce,
+    );
+    expect(tally.permit).toBeUndefined();
+  });
+
+  test("log-only then enforce: a human's approval recorded under log-only still counts toward the quorum (#2512)", async () => {
+    const logOnly: ResolvedGateApproval = { quorum: { count: 1 }, policy: POLICY, mode: "log-only" };
+    const enforce: ResolvedGateApproval = { ...logOnly, mode: "enforce" };
+    const port = memoryGateLedgerPort({
+      resolutions: [approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", policyDecision: allow("log-only") })],
+      pending: [{ ...PENDING, approval: logOnly }],
+    });
+    const check = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: NOW });
+    expect(check.satisfied).toBe(true);
+    if (!check.satisfied) return;
+    expect(check.via).toBe("quorum");
+    expect(check.resolution.resolvedBy).toBe("alex");
+  });
+
+  test("log-only then enforce: the gated run re-records the pending fact under enforce, and only a fresh permit passes (#2512)", async () => {
+    const logOnly: ResolvedGateApproval = { policy: POLICY, mode: "log-only", context: { risk: "low" } };
+    const enforce: ResolvedGateApproval = { ...logOnly, mode: "enforce" };
+    const stale = approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("log-only") });
+    const port = memoryGateLedgerPort({ resolutions: [stale], pending: [{ ...PENDING, approval: logOnly }] });
+
+    const first = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: NOW });
+    expect(first.satisfied).toBe(false);
+    if (first.satisfied) return;
+    // The standing fact described the log-only gate, so a fresh one carries
+    // enforce, and `chant approve` evaluates the next agent approval under it.
+    expect(first.recorded).toBe(true);
+    expect(first.pending.approval?.mode).toBe("enforce");
+
+    // Re-running without a new approval still waits: the stale permit predates the new pending fact as well.
+    const again = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: "2026-09-01T12:30:00.000Z" });
+    expect(again.satisfied).toBe(false);
+
+    const fresh = approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T13:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("enforce") });
+    const after = await evaluateGate(
+      memoryGateLedgerPort({ resolutions: [stale, fresh], pending: [first.pending] }),
+      { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: "2026-09-01T14:00:00.000Z" },
+    );
+    expect(after.satisfied).toBe(true);
+    if (!after.satisfied) return;
+    expect(after.via).toBe("policy");
+    expect(after.resolution.timestamp).toBe(fresh.timestamp);
+  });
+
+  test("enforce: a recorded decision with no mode does not pass the gate (#2512)", async () => {
+    const block: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
+    const { mode: _mode, ...noMode } = allow()!;
+    const { check } = await decide(
+      [approval({
+        resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" },
+        policyDecision: noMode as GateResolutionRecord["policyDecision"],
+      })],
+      block,
+    );
+    expect(check.satisfied).toBe(false);
+  });
+
   test("enforce: a deny-by-default policy keeps the old behaviour, where only a human's approval counts", async () => {
     const block: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
     const deny = { ...allow()!, decision: "deny" as const, determining: ["floor"] };

package/src/op/gate-approval.ts

@@ -119,7 +119,11 @@ export interface GatePolicyAnswer {
 export interface GatePolicyDecision extends GatePolicyAnswer {
   policy: string;
   version: string;
-  /** The gate's mode when the decision was recorded. A run reads the gate's current mode, not this. */
+  /**
+   * The gate's mode when the decision was recorded. A permit passes a gate
+   * only when both this and the gate's current mode are `enforce` (#2512), so
+   * an allow recorded under `log-only` never binds after a switch.
+   */
   mode: GateApprovalMode;
 }
 

package/src/op/gate.ts

@@ -74,6 +74,19 @@ export interface PendingGatePush {
 export interface GateLedgerPort {
   read(op: string): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }>;
   appendPending(input: PendingGateInput): Promise<PendingGatePush>;
+  /**
+   * The rule a workspace sets for approvals of `gate` (#3163, ws-080), or
+   * null when none applies: the declaration's `identity.gates`, read at base.
+   * Absent, every approval is judged as before.
+   */
+  approvalRule?(gate: string): Promise<GateApprovalRule | null>;
+}
+
+/** A workspace's rule for which approvals of a gate count (#3163): a signed approval, from a class when it names one. */
+export interface GateApprovalRule {
+  requirement: { gate: string; class: string | null };
+  /** Why `approval` doesn't count, or null when it does. */
+  refuses(approval: GateResolutionRecord): string | null;
 }
 
 /**
@@ -102,6 +115,11 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { resolutions, pending } = await readGateLedger(op, opts);
       return { resolutions, pending };
     },
+    async approvalRule(gate) {
+      // Loaded on demand: the rule lives in the workspace modules, which import the Op modules.
+      const { gateAdmission } = await import("../workspace/identity");
+      return gateAdmission(opts?.cwd ?? process.cwd(), gate);
+    },
     async appendPending(input) {
       const { record } = await appendPendingGate(input, opts);
       try {
@@ -288,7 +306,7 @@ export interface GateTally {
   counted: GateResolutionRecord[];
   /** The quorum's count, 1 when the gate declares none. */
   need: number;
-  /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, and only under the gate's current policy version. */
+  /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, only for a permit recorded under `enforce`, and only under the gate's current policy version. */
   permit?: GateResolutionRecord;
   /** The newest approval of this gate for a different plan, when the gate binds one. */
   mismatched?: GateResolutionRecord;
@@ -305,8 +323,9 @@ export interface GateTally {
  * Of those, only a human's counts toward the quorum, once per `resolvedBy`,
  * and only with one of the quorum's roles when it names any. An agent counts
  * only through a recorded `allow` in `enforce` mode, evaluated under the
- * policy version the gate declares now. A `log-only` decision never changes
- * the outcome, and a `deny` never removes a human's approval: a policy can add
+ * policy version the gate declares now and recorded while the gate was in
+ * `enforce` (#2512). A `log-only` decision never changes the outcome, even
+ * after the gate switches to `enforce`, and a `deny` never removes a human's approval: a policy can add
  * a way through the gate but cannot take one away.
  */
 export function tallyGateApprovals(
@@ -331,8 +350,12 @@ export function tallyGateApprovals(
     }
 
     const decision = r.policyDecision;
+    // #2512: the decision must also have been recorded under `enforce`. An
+    // allow recorded while the gate was log-only was never binding, and a
+    // later switch to enforce does not make it binding.
     if (
       approval.mode === "enforce" && approval.policy && decision?.decision === "allow" &&
+      decision.mode === "enforce" &&
       decision.version === approval.policy.version && (!permit || at(r) >= at(permit))
     ) {
       permit = r;
@@ -394,10 +417,13 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // a mismatch with a message instead of silently not counting.
   const env = input.environment;
   const pending = env === undefined ? ledger.pending : ledger.pending.filter((p) => p.environment === env);
-  const resolutions =
+  // #3163: a gate the workspace's identity.gates names counts only signed approvals from its class.
+  const rule = (await port.approvalRule?.(input.gate)) ?? null;
+  const resolutions = (
     env === undefined
       ? ledger.resolutions
-      : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env);
+      : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)
+  ).filter((r) => rule === null || r.gate !== input.gate || rule.refuses(r) === null);
 
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;

package/src/op/index.ts

@@ -60,6 +60,8 @@ export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
 export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
+export { currentOpRun, withOpRunContext } from "./run-context";
+export type { OpRunContext, PassedGate } from "./run-context";
 export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch } from "./gate";
 export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch, GateQuorumProgress, GateTally } from "./gate";
 export { tallyGateApprovals, approverOf } from "./gate";

package/src/op/local-executor.test.ts

@@ -232,6 +232,21 @@ describe("runOpLocally — outcomeAttribute", () => {
     expect(result.records[0].outcome).toEqual({ name: "Drift", value: true });
   });
 
+  test("an attribute whose path the result does not hold is left off, not recorded as undefined", async () => {
+    const done: ActivityFn = async () => ({ state: "done", switched: false });
+    const config = op({
+      phases: [{ name: "Switch", steps: [
+        { kind: "activity", fn: "migrationSwitch", outcomeAttribute: [{ name: "OldColumn", from: "oldColumn" }, { name: "State", from: "state" }] },
+        { kind: "activity", fn: "migrationRetain", outcomeAttribute: { name: "RetainUntil", from: "retainUntil" } },
+      ] }],
+    });
+    const result = await runOpLocally(config, new Map([["migrationSwitch", done], ["migrationRetain", done]]), PROFILES);
+    expect(result.records[0].outcomes).toEqual([{ name: "State", value: "done" }]);
+    expect(result.records[0].outcome).toEqual({ name: "State", value: "done" });
+    expect(result.records[1].outcomes).toBeUndefined();
+    expect(result.records[1].outcome).toBeUndefined();
+  });
+
   test("a step with no attribute leaves both fields absent", async () => {
     const noop: ActivityFn = async () => ({ ok: true });
     const config = op({ phases: [{ name: "Plan", steps: [{ kind: "activity", fn: "noop" }] }] });

package/src/op/local-executor.ts

@@ -29,6 +29,7 @@ import { stepTimeoutProblem } from "./activity-profiles";
 import { describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
 import type { ResolvedGateApproval } from "./gate-approval";
+import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isPointWait, type WaitingPoint } from "./steward-points";
 import { isGateWait } from "./gate-wait";
@@ -416,9 +417,11 @@ async function runStep(
       if (step.id) resultsById.set(step.id, result);
       const record: StepRecord = { ...base, status: "ok", durationMs: Date.now() - start };
       const attrs = outcomeAttributesOf(step);
-      if (attrs.length > 0) {
-        record.outcomes = attrs.map((a) => ({ name: a.name, value: resolvePath(result, a.from) }));
-        record.outcome = record.outcomes[0];
+      // An attribute whose path the result does not hold is left off, rather than recorded as undefined.
+      const outcomes = attrs.map((a) => ({ name: a.name, value: resolvePath(result, a.from) })).filter((o) => o.value !== undefined);
+      if (outcomes.length > 0) {
+        record.outcomes = outcomes;
+        record.outcome = outcomes[0];
       }
       return { record, result };
     } catch (err) {
@@ -482,6 +485,8 @@ interface GateContext {
   runId?: string;
   /** Called once per settled step, in production order (#2121) — what `--progress-json` streams from. */
   onRecord?: (record: StepRecord) => void;
+  /** The run context's list of passed gates (#2522). A gate that passes is appended here. */
+  passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
 }
@@ -643,6 +648,17 @@ async function runGateStep(
 
   if (check.satisfied) {
     const { resolution } = check;
+    const passedApproval: NonNullable<StepRecord["approval"]> = {
+      gate: gateName(step),
+      resolvedBy: resolution.resolvedBy,
+      timestamp: resolution.timestamp,
+      ...(resolution.url ? { url: resolution.url } : {}),
+      ...(check.via ? { via: check.via } : {}),
+      ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
+    };
+    // #2522: a later step reads this gate's approval from the run context
+    // rather than re-tallying the ledger, so it sees the decision this run made.
+    gates.passed?.push({ gate: gateName(step), approval: passedApproval });
     return {
       record: {
         phase: phaseName,
@@ -650,14 +666,7 @@ async function runGateStep(
         args: {},
         status: "ok",
         durationMs: Date.now() - start,
-        approval: {
-          gate: gateName(step),
-          resolvedBy: resolution.resolvedBy,
-          timestamp: resolution.timestamp,
-          ...(resolution.url ? { url: resolution.url } : {}),
-          ...(check.via ? { via: check.via } : {}),
-          ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
-        },
+        approval: passedApproval,
       },
     };
   }
@@ -971,6 +980,12 @@ export interface RunOpOptions {
   now?: string;
   /** Identifies this run on any pending fact it records. */
   runId?: string;
+  /**
+   * The environment the run was started for (`--env`, #2522). The executor
+   * only hands it to activities through the run context (`./run-context.ts`).
+   * The run ledger path still comes from the Op's `labels.Env`.
+   */
+  env?: string;
   /**
    * Called once per settled step, in the order the records are produced
    * (#2121) — what the local op runtime (./runtimes/local.ts) feeds
@@ -1039,6 +1054,13 @@ export async function runOpLocally(
   const turn = currentStewardTurn();
   const steward = options.steward ?? turn?.steward;
   const restore = turn && turn.run !== runId ? enterStewardTurn({ ...turn, run: runId }) : undefined;
+  // #2522: every activity in this run can read the run it is in.
+  const run: OpRunContext = {
+    op: config.name,
+    runId,
+    ...(options.env !== undefined ? { env: options.env } : {}),
+    passedGates: [],
+  };
   // A run that writes to the ledger also says what it is doing while it runs
   // (./run-live.ts), and removes that once its record is written.
   const live = options.ledger
@@ -1052,7 +1074,11 @@ export async function runOpLocally(
       })
     : undefined;
   try {
-    return await withLiveRun(live, () => runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }));
+    return await withLiveRun(live, () =>
+      withOpRunContext(run, () =>
+        runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }, run),
+      ),
+    );
   } finally {
     live?.close();
     restore?.();
@@ -1065,6 +1091,7 @@ async function runOpInTurn(
   profiles: Record<string, ActivityProfile>,
   signal: AbortSignal | undefined,
   options: RunOpOptions & { runId: string },
+  run: OpRunContext,
 ): Promise<OpRunResult> {
   const runId = options.runId;
 
@@ -1074,6 +1101,7 @@ async function runOpInTurn(
     ...(options.now ? { now: options.now } : {}),
     runId,
     ...(options.onRecord ? { onRecord: options.onRecord } : {}),
+    passed: run.passedGates,
   };
 
   // Effect steps are ordered (read-compare-run-write): refuse them in a

package/src/op/local-output.ts

@@ -66,7 +66,7 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
       : work.released
         ? `released ${work.outcome}`
         : "not released; it runs out on its own";
-    write(`[work] ${work.item} held by ${work.holder}${work.branch ? ` on ${work.branch}` : ""}: ${end}`);
+    write(`[work] ${work.item} held by ${work.holder}${work.branch ? ` on ${work.branch}` : ""}: ${end}${work.kept ? `; the attempt is kept at ${work.kept}` : ""}`);
   } else if (work?.refusal) {
     write(`[work] nothing claimed: ${work.refusal}`);
   }

package/src/op/operator.ts

@@ -577,6 +577,10 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
     try {
       const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal, {
         runId,
+        // #2522: the environment the operator was started for (`--env`, or a
+        // steward's environment) reaches the activities through the run
+        // context, as `chant run --env` does.
+        ...(opts.env ?? opts.stewardEnv ? { env: opts.env ?? opts.stewardEnv } : {}),
         ...(steward ? { steward: steward.name } : {}),
         ledger: { cwd: opts.cwd },
         // A steward's turn claims work leases as `<steward>/<op>@<holder>`

package/src/op/run-context.test.ts

@@ -0,0 +1,141 @@
+/**
+ * The run context an activity reads (#2522): the Op, the run id the run
+ * ledger records, `--env`, and the gates the run has passed.
+ */
+import { describe, test, expect } from "vitest";
+import type { OpConfig } from "./types";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import { runOpLocally } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import { currentOpRun, type OpRunContext } from "./run-context";
+import { gatePolicyVersion, type GatePolicyRef, type ResolvedGateApproval } from "./gate-approval";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+
+const PROFILES: Record<string, ActivityProfile> = {
+  fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } },
+};
+const NOW = "2026-09-05T12:00:00.000Z";
+
+function op(steps: OpConfig["phases"][number]["steps"]): OpConfig {
+  return { name: "release", overview: "", phases: [{ name: "main", steps }] };
+}
+
+describe("the Op run context (#2522)", () => {
+  test("an activity reads the Op, the run id and --env", async () => {
+    let seen: OpRunContext | undefined;
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", async () => { await Promise.resolve(); seen = currentOpRun(); }],
+    ]);
+    const result = await runOpLocally(op([{ kind: "activity", fn: "deploy" }]), activities, PROFILES, undefined, {
+      runId: "local-123",
+      env: "staging",
+    });
+    expect(seen).toEqual({ op: "release", runId: "local-123", env: "staging", passedGates: [] });
+    expect(result.record?.id).toBe("local-123");
+  });
+
+  test("without --env the context carries none, and outside a run there is no context", async () => {
+    let seen: OpRunContext | undefined;
+    const activities = new Map<string, ActivityFn>([["deploy", async () => { seen = currentOpRun(); }]]);
+    await runOpLocally(op([{ kind: "activity", fn: "deploy" }]), activities, PROFILES, undefined, { runId: "r1" });
+    expect(seen).toEqual({ op: "release", runId: "r1", passedGates: [] });
+    expect(currentOpRun()).toBeUndefined();
+  });
+
+  test("a step after a passed gate reads the gate's approval", async () => {
+    const seen: OpRunContext[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["plan", async () => { seen.push(currentOpRun()!); }],
+      ["apply", async () => { seen.push(currentOpRun()!); }],
+    ]);
+    const port = memoryGateLedgerPort({
+      pending: [{
+        version: 1, kind: "pending", op: "release", gate: "ship",
+        timestamp: "2026-09-05T10:00:00.000Z", expiresAt: "2026-09-07T10:00:00.000Z",
+      }],
+      resolutions: [{ version: 1, op: "release", gate: "ship", resolvedBy: "alex", timestamp: "2026-09-05T11:00:00.000Z" }],
+    });
+    const result = await runOpLocally(
+      op([
+        { kind: "activity", fn: "plan" },
+        { kind: "gate", gate: "ship" },
+        { kind: "activity", fn: "apply" },
+      ]),
+      activities,
+      PROFILES,
+      undefined,
+      { gates: port, now: NOW, runId: "r2" },
+    );
+    expect(result.status).toBe("ok");
+    expect(seen[0]!.passedGates).toEqual([]);
+    expect(seen[1]!.passedGates).toEqual([
+      { gate: "ship", approval: { gate: "ship", resolvedBy: "alex", timestamp: "2026-09-05T11:00:00.000Z" } },
+    ]);
+    expect(seen[1]!.passedGates[0]!.approval).toEqual(result.records.find((r) => r.fn === "gate:ship")?.approval);
+  });
+
+  describe("a policy permit and the gates a run passed (#2512)", () => {
+    const TEXT = 'permit (principal is Chant::Agent, action, resource) when { context.risk == "low" };\n';
+    const POLICY: GatePolicyRef = { kind: "gate-policy", lexicon: "cedar", name: "ship", version: gatePolicyVersion(TEXT), text: TEXT };
+    const enforce: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
+    const permit = (mode: "log-only" | "enforce"): GateResolutionRecord => ({
+      version: 1, op: "release", gate: "ship", resolvedBy: "release-bot", timestamp: "2026-09-05T11:00:00.000Z",
+      approver: { kind: "agent" },
+      policyDecision: { policy: "ship", version: POLICY.version, mode, decision: "allow", determining: ["ship-0"], errors: [] },
+    });
+
+    async function run(mode: "log-only" | "enforce") {
+      const seen: OpRunContext[] = [];
+      const activities = new Map<string, ActivityFn>([["apply", async () => { seen.push(currentOpRun()!); }]]);
+      const port = memoryGateLedgerPort({
+        pending: [{
+          version: 1, kind: "pending", op: "release", gate: "ship",
+          timestamp: "2026-09-05T10:00:00.000Z", expiresAt: "2026-09-07T10:00:00.000Z",
+          approval: { ...enforce, mode },
+        }],
+        resolutions: [permit(mode)],
+      });
+      const result = await runOpLocally(
+        op([
+          { kind: "gate", gate: "ship", approval: { policy: POLICY, mode: "enforce" } },
+          { kind: "activity", fn: "apply" },
+        ]),
+        activities,
+        PROFILES,
+        undefined,
+        { gates: port, now: NOW, runId: "r3" },
+      );
+      return { result, seen };
+    }
+
+    test("an enforce-mode permit passes the gate, and the next step sees it as passed by policy", async () => {
+      const { result, seen } = await run("enforce");
+      expect(result.status).toBe("ok");
+      expect(seen[0]!.passedGates.map((g) => [g.gate, g.approval.via])).toEqual([["ship", "policy"]]);
+    });
+
+    test("a permit recorded under log-only does not pass the enforced gate, so no step sees it as passed", async () => {
+      const { result, seen } = await run("log-only");
+      expect(result.status).toBe("gated");
+      expect(seen).toEqual([]);
+      expect(result.records.find((r) => r.fn === "gate:ship")?.approval).toBeUndefined();
+    });
+  });
+
+  test("two runs in flight at once each see their own context", async () => {
+    const seen = new Map<string, string | undefined>();
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", async () => {
+        await new Promise((r) => setTimeout(r, 5));
+        const ctx = currentOpRun()!;
+        seen.set(ctx.runId, ctx.env);
+      }],
+    ]);
+    const config = op([{ kind: "activity", fn: "deploy" }]);
+    await Promise.all([
+      runOpLocally(config, activities, PROFILES, undefined, { runId: "a", env: "staging" }),
+      runOpLocally(config, activities, PROFILES, undefined, { runId: "b", env: "prod" }),
+    ]);
+    expect(Object.fromEntries(seen)).toEqual({ a: "staging", b: "prod" });
+  });
+});

package/src/op/run-context.ts

@@ -0,0 +1,51 @@
+/**
+ * The run an activity is part of (#2522).
+ *
+ * An activity is called as `fn(args, signal)`, which says nothing about the
+ * run around it. An activity that deploys somewhere needs the environment the
+ * run was asked for, one that appends a ledger record of its own needs the run
+ * id to name the run that made it, and a step after a gate may need to know the
+ * gate passed and who approved it.
+ *
+ * `runOpLocally` (`./local-executor.ts`) sets this for the whole run, and
+ * {@link currentOpRun} reads it from inside an activity. It is backed by
+ * `AsyncLocalStorage`, so it follows the activity through every `await` and is
+ * `undefined` outside a run.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { StepRecord } from "./local-executor";
+
+/** A gate this run has passed, with the approval that passed it. */
+export interface PassedGate {
+  gate: string;
+  approval: NonNullable<StepRecord["approval"]>;
+}
+
+/** What an activity can read about the run it is in. */
+export interface OpRunContext {
+  /** The Op's name. */
+  op: string;
+  /** The run id the run ledger record carries. */
+  runId: string;
+  /** `--env`, as handed to `OpRuntimeProvider.start`. Absent when the run was started without one. */
+  env?: string;
+  /** Every gate this run has passed so far, in the order it passed them. */
+  passedGates: PassedGate[];
+}
+
+const store = new AsyncLocalStorage<OpRunContext>();
+
+/**
+ * The run the calling activity is part of, or `undefined` outside a run.
+ * `passedGates` is a copy taken at the time of the call.
+ */
+export function currentOpRun(): OpRunContext | undefined {
+  const ctx = store.getStore();
+  return ctx ? { ...ctx, passedGates: [...ctx.passedGates] } : undefined;
+}
+
+/** Run `fn` with `ctx` as the current run. The executor calls this. A runtime that calls activities itself can too. */
+export function withOpRunContext<T>(ctx: OpRunContext, fn: () => T): T {
+  return store.run(ctx, fn);
+}