@intentius/chant 0.124.22 → 0.124.24

package/src/op/op-waves.ts

@@ -67,6 +67,7 @@
  */
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
+import type { CiRunner } from "../ci-jobs";
 import { gatePointProblems, type GatePoint } from "./gate-point";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
 import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout";
@@ -197,6 +198,51 @@ export interface OpWaveRun {
   op?: string;
 }
 
+/**
+ * Where a wave's jobs run (#3914): a runner label, a list of labels the
+ * runner must all carry, or on GitHub a runner group with optional labels.
+ * Rendered as `runs-on` on GitHub and Forgejo and as `tags` on GitLab; a
+ * runner group on GitLab or Forgejo is a spec error.
+ */
+export type OpWaveRunner = CiRunner;
+
+/**
+ * One job group of a wave (#3914): the runs it applies, and the job that
+ * applies them, with its own runner, forge environment, variables, setup and
+ * id tokens. The wave's deciding job plans every run and decides the wave's
+ * one gate; the group's job plans its own runs again and applies those whose
+ * plan has not moved since.
+ */
+export interface OpWaveJobGroup {
+  /** The group's name, in its job's name (`wave-<k>-<wave>-<name>`). Lowercase letters, digits, `-` and `_`. */
+  name: string;
+  /**
+   * The runs it applies: targets, or patterns where `*` matches within one
+   * path segment and `**` across segments. Each run of the wave is in exactly
+   * one group. On a `discover` wave the deciding job checks this once the
+   * runs are found.
+   */
+  runs: string[];
+  /** Split the group's runs across this many jobs, as a wave's `shares` does. Default 1. */
+  shares?: number;
+  /** The group's runner. Default: the wave's, else the spec's. */
+  runner?: OpWaveRunner;
+  /** The forge deployment environment of the group's jobs (GitHub and GitLab; a spec error on Forgejo). Default: the wave's. */
+  environment?: OpEnvironment;
+  /** Variables for the group's jobs, over the wave's own. */
+  variables?: Record<string, string>;
+  /** Steps the group's jobs run after the wave's setup. */
+  setup?: OpSetupStep[];
+  /**
+   * The OIDC tokens the group's jobs get, as `{ <variable>: <audience> }`, in
+   * place of the wave's. GitLab declares them as the job's `id_tokens:`.
+   * GitHub and Forgejo give the job `id-token: write` and the audience as
+   * `<variable>_AUDIENCE`, since there the audience is chosen when the token
+   * is requested.
+   */
+  idTokens?: Record<string, string>;
+}
+
 /** One wave: runs that apply together, behind one gate. */
 export interface OpWave {
   /** The wave's name, usually its environment. Lowercase letters, digits, `-` and `_`. */
@@ -247,6 +293,21 @@ export interface OpWave {
   setup?: OpSetupStep[];
   /** This wave's stage hooks (#3762), run after the spec's own. Read at the base commit. */
   hooks?: OpWaveHooks;
+  /** Where this wave's jobs run (#3914). Default: the spec's `runner`. */
+  runner?: OpWaveRunner;
+  /**
+   * The OIDC tokens this wave's jobs get (#3914), as `{ <variable>: <audience> }`;
+   * see {@link OpWaveJobGroup.idTokens}. With `jobs`, these are the deciding
+   * job's, and a group's own replace them.
+   */
+  idTokens?: Record<string, string>;
+  /**
+   * Split the wave's apply into job groups (#3914): a deciding job, which
+   * runs with the wave's own settings, plans every run and decides the gate,
+   * and a job per group (per share of a group), each applying its runs. Not
+   * with the wave's own `shares` (a group has its own) or `rest`.
+   */
+  jobs?: OpWaveJobGroup[];
 }
 
 /**
@@ -279,6 +340,12 @@ export interface OpWavesSpec {
   neverOverMcp?: boolean;
   /** Branches whose pushes run the waves. Default `["main"]`. */
   branches?: string[];
+  /**
+   * Where every job the spec renders runs unless a wave or a job group names
+   * another (#3914). Default: the forge's default runner (`ubuntu-latest` on
+   * GitHub, the dialect's label on Forgejo, no `tags` on GitLab).
+   */
+  runner?: OpWaveRunner;
   /**
    * The commit the gate policy is read from. Default `HEAD^1`, the first
    * parent: on a merge or squash onto the branch, the branch before the change.
@@ -423,8 +490,10 @@ export interface OpWaveJob {
   waveName: string;
   /** `wave`: plan, decide and apply. `decide`: plan and decide. `share`: apply one slice. */
   kind: "wave" | "decide" | "share";
-  /** 1-based, on a share job. */
+  /** 1-based, on a share job (and a group's job when the group has shares). */
   share?: number;
+  /** On a job group's job (#3914): the group's name. Its kind is `share`. */
+  group?: string;
   /** Jobs this one waits on. */
   needs: string[];
   /** The job's command, as argv. */
@@ -508,6 +577,7 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
     if (problems.length > 0) throw new Error(`${where}: ${problems.join("; ")}.`);
   }
   if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean") throw new Error(`${where}: neverOverMcp must be true or false.`);
+  if (spec.runner !== undefined) assertOpWaveRunner(where, "runner", spec.runner);
   if (spec.notify !== undefined) {
     const problem = notifyConfigProblem(spec.notify, "notify");
     if (problem) throw new Error(`${where}: ${problem}`);
@@ -530,6 +600,9 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       const problems = opWavePointProblems(wave.point);
       if (problems.length > 0) throw new Error(`${where}: wave "${wave.name}": ${problems.join("; ")}.`);
     }
+    if (wave.runner !== undefined) assertOpWaveRunner(where, `wave "${wave.name}" runner`, wave.runner);
+    if (wave.idTokens !== undefined) assertOpWaveIdTokens(where, `wave "${wave.name}" idTokens`, wave.idTokens);
+    if (wave.jobs !== undefined) assertOpWaveJobGroups(where, wave);
     if (wave.discover !== undefined && typeof wave.discover !== "boolean") throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
     if (wave.rest !== undefined && typeof wave.rest !== "boolean") throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
     if (wave.discover) {
@@ -560,7 +633,109 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
     if (shares > wave.runs.length) {
       throw new Error(`${where}: wave "${wave.name}" has ${shares} shares for ${wave.runs.length} runs, so a share would apply nothing.`);
     }
+    if (wave.jobs !== undefined) {
+      const problem = opWaveGroupsProblem(wave, wave.runs.map((r) => r.target));
+      if (problem) throw new Error(`${where}: ${problem}.`);
+    }
+  }
+}
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Refuse a `runner` no forge could read (#3914). */
+function assertOpWaveRunner(where: string, field: string, runner: unknown): void {
+  const labels = (value: unknown): boolean => Array.isArray(value) && value.length > 0 && value.every((l) => typeof l === "string" && l.trim() !== "");
+  if (typeof runner === "string" && runner.trim() !== "") return;
+  if (labels(runner)) return;
+  if (runner !== null && typeof runner === "object" && !Array.isArray(runner)) {
+    const { group, labels: l, ...rest } = runner as Record<string, unknown>;
+    const extra = Object.keys(rest)[0];
+    if (extra !== undefined) throw new Error(`${where}: ${field}.${extra} is not a setting; a runner group is { "group": "<name>", "labels"?: [...] }.`);
+    if (typeof group === "string" && group.trim() !== "" && (l === undefined || labels(l))) return;
+  }
+  throw new Error(`${where}: ${field} must be a runner label, a non-empty list of labels, or { "group": "<name>", "labels"?: [...] } (GitHub only).`);
+}
+
+/** Refuse `idTokens` that are not `{ <variable>: <audience> }` (#3914). */
+function assertOpWaveIdTokens(where: string, field: string, idTokens: unknown): void {
+  if (idTokens === null || typeof idTokens !== "object" || Array.isArray(idTokens) || Object.keys(idTokens).length === 0) {
+    throw new Error(`${where}: ${field} must be { "<variable>": "<audience>" }, with at least one token.`);
+  }
+  for (const [name, aud] of Object.entries(idTokens as Record<string, unknown>)) {
+    if (!ENV_NAME.test(name)) throw new Error(`${where}: ${field} names "${name}", which is not a variable name (letters, digits and "_", not starting with a digit).`);
+    if (typeof aud !== "string" || aud.trim() === "") throw new Error(`${where}: ${field}.${name} must be an audience, a non-empty string.`);
+  }
+}
+
+/** Refuse a wave's `jobs` no pipeline could render (#3914). Which runs each group holds is {@link opWaveGroupsProblem}'s. */
+function assertOpWaveJobGroups(where: string, wave: OpWave): void {
+  const at = `wave "${wave.name}"`;
+  if (!Array.isArray(wave.jobs) || wave.jobs.length === 0) throw new Error(`${where}: ${at} jobs must be a non-empty list of job groups.`);
+  if ((wave.shares ?? 1) > 1) throw new Error(`${where}: ${at} has jobs and shares; split each job group with its own shares.`);
+  if (wave.rest) throw new Error(`${where}: ${at} has jobs and rest; the waves after it run in its one job, so its apply cannot be split into groups.`);
+  const names = new Set<string>();
+  wave.jobs.forEach((group, i) => {
+    if (group === null || typeof group !== "object") throw new Error(`${where}: ${at} jobs[${i}] must be { "name", "runs", ... }.`);
+    const field = `${at} jobs[${i}]${typeof group.name === "string" ? ` (${group.name})` : ""}`;
+    if (typeof group.name !== "string" || !NAME.test(group.name)) throw new Error(`${where}: ${field} must be named with lowercase letters, digits, "-" and "_".`);
+    if (group.name === "decide" || /^share-\d+$/.test(group.name)) throw new Error(`${where}: ${field} is named like the wave's own jobs (decide, share-<i>); name it another way.`);
+    if (names.has(group.name)) throw new Error(`${where}: ${at} names job group "${group.name}" twice.`);
+    names.add(group.name);
+    const known = new Set(["name", "runs", "shares", "runner", "environment", "variables", "setup", "idTokens"]);
+    const extra = Object.keys(group).find((key) => !known.has(key));
+    if (extra !== undefined) throw new Error(`${where}: ${field}.${extra} is not a setting; a job group takes ${[...known].join(", ")}.`);
+    if (!Array.isArray(group.runs) || group.runs.length === 0 || !group.runs.every((r) => typeof r === "string" && r.trim() !== "")) {
+      throw new Error(`${where}: ${field} runs must be a non-empty list of targets or patterns.`);
+    }
+    const shares = group.shares ?? 1;
+    if (!Number.isInteger(shares) || shares < 1) throw new Error(`${where}: ${field} has shares ${group.shares}; use a whole number from 1.`);
+    if (group.runner !== undefined) assertOpWaveRunner(where, `${field} runner`, group.runner);
+    if (group.idTokens !== undefined) assertOpWaveIdTokens(where, `${field} idTokens`, group.idTokens);
+    if (group.variables !== undefined && (group.variables === null || typeof group.variables !== "object" || Array.isArray(group.variables) || !Object.values(group.variables).every((v) => typeof v === "string"))) {
+      throw new Error(`${where}: ${field} variables must be { "<name>": "<value>" }.`);
+    }
+    if (group.setup !== undefined && !Array.isArray(group.setup)) throw new Error(`${where}: ${field} setup must be a list of steps.`);
+    if (group.environment !== undefined && (group.environment === null || typeof group.environment !== "object" || typeof group.environment.name !== "string")) {
+      throw new Error(`${where}: ${field} environment must be { "name", "url"? }.`);
+    }
+  });
+}
+
+/**
+ * True when `target` matches a job group's `runs` entry (#3914): the target
+ * itself, or a pattern where `*` matches within one `/` segment and `**`
+ * across segments.
+ */
+export function opWaveRunMatches(pattern: string, target: string): boolean {
+  if (!pattern.includes("*")) return pattern === target;
+  let re = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]!;
+    if (c === "*" && pattern[i + 1] === "*") {
+      re += ".*";
+      i++;
+    } else if (c === "*") re += "[^/]*";
+    else re += c.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
   }
+  return new RegExp(`^${re}$`).test(target);
+}
+
+/** The runs of `runs` that job group `group` holds (#3914). */
+export function opWaveGroupRuns<T extends { target: string }>(group: Pick<OpWaveJobGroup, "runs">, runs: readonly T[]): T[] {
+  return runs.filter((run) => group.runs.some((pattern) => opWaveRunMatches(pattern, run.target)));
+}
+
+/**
+ * What is wrong with how a wave's job groups hold `targets` (#3914): a run in
+ * two groups, or in none. Undefined when each run is in exactly one.
+ */
+export function opWaveGroupsProblem(wave: Pick<OpWave, "name" | "jobs">, targets: readonly string[]): string | undefined {
+  for (const target of targets) {
+    const holders = (wave.jobs ?? []).filter((group) => group.runs.some((pattern) => opWaveRunMatches(pattern, target))).map((g) => `"${g.name}"`);
+    if (holders.length > 1) return `wave "${wave.name}" jobs: run "${target}" is in job groups ${holders.join(" and ")}; each run is in exactly one`;
+    if (holders.length === 0) return `wave "${wave.name}" jobs: run "${target}" is in no job group; each run is in exactly one`;
+  }
+  return undefined;
 }
 
 function assertArgv(where: string, field: string, argv: unknown): void {
@@ -655,7 +830,7 @@ export function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[] {
     const command = ["chant", "run", "wave", "--spec", specFile, "--wave", String(k), ...(spec.base ? ["--base", spec.base] : [])];
     const prefix = `wave-${k}-${wave.name}`;
     const shares = wave.shares ?? 1;
-    if (shares === 1) {
+    if (shares === 1 && wave.jobs === undefined) {
       jobs.push({ jobName: prefix, wave: k, waveName: wave.name, kind: "wave", needs: previous, command });
       previous = [prefix];
       return;
@@ -664,6 +839,26 @@ export function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[] {
     const decide = `${prefix}-decide`;
     jobs.push({ jobName: decide, wave: k, waveName: wave.name, kind: "decide", needs: previous, command: [...command, "--decide"], record });
     const shareJobs: string[] = [];
+    if (wave.jobs !== undefined) {
+      // #3914: a job per group, or per share of a group, each applying its runs under the deciding job's decision.
+      for (const group of wave.jobs) {
+        const groupShares = group.shares ?? 1;
+        const groupCommand = [...command, "--group", group.name];
+        if (groupShares === 1) {
+          const jobName = `${prefix}-${group.name}`;
+          shareJobs.push(jobName);
+          jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, needs: [decide], command: groupCommand, record });
+          continue;
+        }
+        for (let share = 1; share <= groupShares; share++) {
+          const jobName = `${prefix}-${group.name}-share-${share}`;
+          shareJobs.push(jobName);
+          jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, share, needs: [decide], command: [...groupCommand, "--share", String(share)], record });
+        }
+      }
+      previous = shareJobs;
+      return;
+    }
     for (let share = 1; share <= shares; share++) {
       const jobName = `${prefix}-share-${share}`;
       shareJobs.push(jobName);
@@ -674,6 +869,11 @@ export function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[] {
   return jobs;
 }
 
+/** The job group a job applies (#3914), or undefined for a wave's own jobs. */
+export function opWaveGroupOf(spec: OpWavesSpec, job: Pick<OpWaveJob, "wave" | "group">): OpWaveJobGroup | undefined {
+  return job.group === undefined ? undefined : spec.waves[job.wave - 1]?.jobs?.find((g) => g.name === job.group);
+}
+
 /** The wave a job belongs to. */
 export function opWaveOf(spec: OpWavesSpec, job: Pick<OpWaveJob, "wave">): OpWave {
   return spec.waves[job.wave - 1]!;

package/src/op/runtimes/local.ts

@@ -22,6 +22,7 @@ import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { loadActivities, loadProfiles } from "../activity-registry";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "../local-executor";
+import { stepHeartbeatMs } from "../step-console";
 import { runComponents } from "../../components/cli-support";
 import { discoverOps } from "../discover";
 import { readRunLedger, runEnvOf, DEFAULT_RUN_ENV } from "../../lifecycle/run-ledger";
@@ -172,6 +173,11 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
                     `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`,
                 ),
               ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+              // #3956: a running step's output, and a still-running line while
+              // it is quiet, on stderr as they happen; stdout stays the
+              // `--json` record's and `--progress-json`'s.
+              stepOutput: (line) => process.stderr.write(`${line}\n`),
+              stepHeartbeatMs: stepHeartbeatMs(process.env, (message) => process.stderr.write(`warning: ${message}\n`)),
               ...(startOpts.work ? { work: startOpts.work } : {}),
               onWorkLeaseWarning: (message) =>
                 process.stderr.write(`warning: "${op.name}" could not renew its work lease, retrying at the next beat: ${message}\n`),

package/src/op/step-console.test.ts

@@ -0,0 +1,150 @@
+/**
+ * A running step's console (#3956): a step's output is printed as it
+ * arrives, each line carrying its phase and step, and a quiet step says it
+ * is still running.
+ */
+
+import { describe, test, expect, vi } from "vitest";
+import { shellCmd, type ShellCmdArgs } from "./activities/shell";
+import { activity, phase, shell } from "./builders";
+import { ACTIVITY_PROFILES } from "./activity-profiles";
+import { runOpLocally } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import type { ActivityFn } from "./activity-registry";
+import { DEFAULT_STEP_HEARTBEAT_MS, stepHeartbeatMs, stepLabel } from "./step-console";
+
+const shellFn: ActivityFn = (args, signal) => shellCmd(args as unknown as ShellCmdArgs, signal);
+
+/** A writer that keeps each line with when it arrived. */
+function recorder() {
+  const lines: Array<{ at: number; text: string }> = [];
+  return { lines, write: (text: string) => void lines.push({ at: Date.now(), text }) };
+}
+
+// A command that writes a line, waits, and writes another on stderr, then a
+// last line on stdout with no newline.
+const SLOW = `node -e "console.log('first'); setTimeout(() => { console.error('second'); process.stdout.write('third'); }, 600)"`;
+
+describe("a step's output streams as it arrives (#3956)", () => {
+  test("the first line is printed before the command exits, prefixed with its phase and step", async () => {
+    const out = recorder();
+    let ended = 0;
+    const timed: ActivityFn = async (args, signal) => {
+      try {
+        return await shellFn(args, signal);
+      } finally {
+        ended = Date.now();
+      }
+    };
+    const result = await runOpLocally(
+      { name: "seed", overview: "", phases: [phase("Seed", [shell(SLOW, { id: "wait-agent" })])] },
+      new Map([["shellCmd", timed]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 0 },
+    );
+
+    expect(result.status).toBe("ok");
+    expect(out.lines.map((l) => l.text)).toEqual([
+      "[Seed] wait-agent | first",
+      "[Seed] wait-agent | second",
+      "[Seed] wait-agent | third",
+    ]);
+    // The first line arrived well before the command ended, not with it.
+    expect(ended - out.lines[0]!.at).toBeGreaterThan(300);
+  });
+
+  test("a step without an id is named by its call, as the run's render names it", async () => {
+    const out = recorder();
+    await runOpLocally(
+      { name: "hello", overview: "", phases: [phase("Go", [shell("echo hi")])] },
+      new Map([["shellCmd", shellFn]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 0 },
+    );
+    expect(out.lines.map((l) => l.text)).toEqual(["[Go] shellCmd(cmd=echo hi) | hi"]);
+  });
+
+  test("a failing command's output is printed too, before the failure", async () => {
+    const out = recorder();
+    await expect(
+      runOpLocally(
+        { name: "broken", overview: "", phases: [phase("Go", [shell(`node -e "console.error('no such table'); process.exit(2)"`, { id: "migrate" })])] },
+        new Map([["shellCmd", shellFn]]),
+        ACTIVITY_PROFILES,
+        undefined,
+        { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 0 },
+      ),
+    ).rejects.toThrow();
+    expect(out.lines.map((l) => l.text)).toEqual(["[Go] migrate | no such table"]);
+  });
+
+  test("without a writer nothing is printed while the step runs, and stdout is not echoed", async () => {
+    const written = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const logged = vi.spyOn(console, "error").mockImplementation(() => {});
+    const result = await runOpLocally(
+      { name: "quiet", overview: "", phases: [phase("Go", [shell("echo hi", { id: "say" })])] },
+      new Map([["shellCmd", shellFn]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort() },
+    ).finally(() => {
+      written.mockRestore();
+      logged.mockRestore();
+    });
+    expect(result.status).toBe("ok");
+    expect(written).not.toHaveBeenCalled();
+    expect(logged).not.toHaveBeenCalled();
+  });
+});
+
+describe("a quiet step says it is still running (#3956)", () => {
+  test("an activity that only returns a value gets a still-running line each interval", async () => {
+    const out = recorder();
+    const slow: ActivityFn = () => new Promise((r) => setTimeout(() => r({ done: true }), 280));
+    await runOpLocally(
+      { name: "wait", overview: "", phases: [phase("Deploy", [activity("waitForAgent", {}, { id: "agent" })])] },
+      new Map([["waitForAgent", slow]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 100 },
+    );
+    expect(out.lines.map((l) => l.text.replace(/\d+s$/, "Ns"))).toEqual([
+      "[Deploy] agent: still running after Ns",
+      "[Deploy] agent: still running after Ns",
+    ]);
+  });
+
+  test("a step printing output is not interrupted by the still-running line", async () => {
+    const out = recorder();
+    const chatty = `node -e "let n = 0; const t = setInterval(() => { console.log('tick ' + n); if (++n === 6) clearInterval(t); }, 40)"`;
+    await runOpLocally(
+      { name: "chatty", overview: "", phases: [phase("Go", [shell(chatty, { id: "ticks" })])] },
+      new Map([["shellCmd", shellFn]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort(), stepOutput: out.write, stepHeartbeatMs: 100 },
+    );
+    expect(out.lines.filter((l) => l.text.includes("still running"))).toEqual([]);
+    expect(out.lines.map((l) => l.text)).toContain("[Go] ticks | tick 5");
+  });
+
+  test("CHANT_STEP_HEARTBEAT sets the interval, and 0 or off turns it off", () => {
+    expect(stepHeartbeatMs({})).toBe(DEFAULT_STEP_HEARTBEAT_MS);
+    expect(stepHeartbeatMs({ CHANT_STEP_HEARTBEAT: "30s" })).toBe(30_000);
+    expect(stepHeartbeatMs({ CHANT_STEP_HEARTBEAT: "5m" })).toBe(300_000);
+    expect(stepHeartbeatMs({ CHANT_STEP_HEARTBEAT: "0" })).toBe(0);
+    expect(stepHeartbeatMs({ CHANT_STEP_HEARTBEAT: "off" })).toBe(0);
+    const warnings: string[] = [];
+    expect(stepHeartbeatMs({ CHANT_STEP_HEARTBEAT: "soon" }, (m) => warnings.push(m))).toBe(DEFAULT_STEP_HEARTBEAT_MS);
+    expect(warnings).toHaveLength(1);
+  });
+
+  test("a long call is cut to a readable label", () => {
+    const label = stepLabel("shellCmd", { cmd: "x".repeat(200) });
+    expect(label.length).toBeLessThanOrEqual(60);
+    expect(label.endsWith("...)")).toBe(true);
+    expect(stepLabel("shellCmd", { cmd: "echo hi" }, "say")).toBe("say");
+  });
+});

package/src/op/step-console.ts

@@ -0,0 +1,155 @@
+/**
+ * A running step's console (#3956): its output as it arrives, and a
+ * "still running" line while it is quiet.
+ *
+ * The run's own render (`./local-output.ts`) is printed once the run
+ * settles, so before this a 15-minute step printed nothing for 15 minutes and
+ * a watchdog reading the output killed a healthy run. When the caller hands
+ * the executor a writer (`RunOpOptions.stepOutput`, which the local runtime
+ * passes, writing to stderr), each activity step runs with a console:
+ *
+ * - an activity that runs a process (`shellCmd`) passes each line the process
+ *   writes, stdout and stderr alike, through {@link stepOutputLine}, and it is
+ *   printed at once as `[<phase>] <step> | <line>`;
+ * - a step that prints nothing for `heartbeatMs` (an activity that only
+ *   returns a value, or a command that is quiet) gets
+ *   `[<phase>] <step>: still running after <n>s` each time that much passes.
+ *
+ * `<step>` is the step's id when it has one, else its call as the run's
+ * render names it, `fn(arg=value, ...)`, cut to a readable length. Without a
+ * writer there is no console, and `shellCmd` prints a command's stderr when it
+ * ends, as it did before.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { parseDuration } from "./duration";
+
+/** How long a step may be quiet before the runner says it is still running. */
+export const DEFAULT_STEP_HEARTBEAT_MS = 60_000;
+
+/** The environment variable that sets the interval: a duration ("30s", "5m"), or `0` / `off`. */
+export const STEP_HEARTBEAT_ENV = "CHANT_STEP_HEARTBEAT";
+
+/** The longest step label a line carries before it is cut. */
+const MAX_LABEL = 60;
+
+interface StepConsole {
+  line(text: string): void;
+}
+
+/** Where a run's step lines go, and how often a quiet step says it is still running. */
+export interface RunConsole {
+  write: (line: string) => void;
+  heartbeatMs?: number;
+}
+
+const store = new AsyncLocalStorage<StepConsole>();
+const runStore = new AsyncLocalStorage<RunConsole>();
+
+/** Run `fn` as a run whose steps print through `run`. Without one, steps get no console. */
+export function withRunConsole<T>(run: RunConsole | undefined, fn: () => Promise<T>): Promise<T> {
+  return run ? runStore.run(run, fn) : fn();
+}
+
+function formatArgs(args: Record<string, unknown>): string {
+  return Object.entries(args)
+    .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+    .join(", ");
+}
+
+/** The name a step's lines carry: its id, else `fn(args)` on one line, cut to {@link MAX_LABEL}. */
+export function stepLabel(fn: string, args: Record<string, unknown>, id?: string): string {
+  if (id) return id;
+  const call = `${fn}(${formatArgs(args)})`.replace(/\s+/g, " ");
+  return call.length > MAX_LABEL ? `${call.slice(0, MAX_LABEL - 4)}...)` : call;
+}
+
+/**
+ * Run `fn` with a console for one step, when the run has one
+ * ({@link withRunConsole}). The heartbeat timer is stopped when `fn`
+ * settles; it never holds the process open on its own.
+ */
+export async function withStepConsole<T>(opts: { phase: string; label: string }, fn: () => Promise<T>): Promise<T> {
+  const run = runStore.getStore();
+  if (!run) return fn();
+  const { write } = run;
+  const prefix = `[${opts.phase}] ${opts.label}`;
+  const started = Date.now();
+  let spoke = false;
+  const sink: StepConsole = {
+    line(text) {
+      spoke = true;
+      write(`${prefix} | ${text}`);
+    },
+  };
+  const every = run.heartbeatMs ?? DEFAULT_STEP_HEARTBEAT_MS;
+  const timer = every > 0
+    ? setInterval(() => {
+        if (spoke) {
+          spoke = false;
+          return;
+        }
+        write(`${prefix}: still running after ${Math.round((Date.now() - started) / 1000)}s`);
+      }, every)
+    : undefined;
+  timer?.unref();
+  try {
+    return await store.run(sink, fn);
+  } finally {
+    if (timer) clearInterval(timer);
+  }
+}
+
+/** Whether the calling activity runs under a step console, so its output is printed as it arrives. */
+export function hasStepConsole(): boolean {
+  return store.getStore() !== undefined;
+}
+
+/** Print one line of the calling step's output. A no-op outside a step console. */
+export function stepOutputLine(text: string): void {
+  store.getStore()?.line(text);
+}
+
+/**
+ * A sink for a stream's chunks that prints whole lines to the calling step's
+ * console as they complete; `end()` prints what is left. The console is the
+ * one current when the splitter is made, since a stream's `data` events need
+ * not run in the step's async context.
+ */
+export function stepLineSplitter(): { push(chunk: string | Buffer): void; end(): void } {
+  const sink = store.getStore();
+  let pending = "";
+  const emit = (line: string) => sink?.line(line.endsWith("\r") ? line.slice(0, -1) : line);
+  return {
+    push(chunk) {
+      pending += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      let at = pending.indexOf("\n");
+      while (at >= 0) {
+        emit(pending.slice(0, at));
+        pending = pending.slice(at + 1);
+        at = pending.indexOf("\n");
+      }
+    },
+    end() {
+      if (pending !== "") emit(pending);
+      pending = "";
+    },
+  };
+}
+
+/**
+ * The heartbeat interval `CHANT_STEP_HEARTBEAT` sets, or the default. `0` and
+ * `off` turn it off. A value that is not a duration falls back to the default
+ * and says so through `warn`.
+ */
+export function stepHeartbeatMs(env: NodeJS.ProcessEnv = process.env, warn?: (message: string) => void): number {
+  const raw = env[STEP_HEARTBEAT_ENV]?.trim();
+  if (!raw) return DEFAULT_STEP_HEARTBEAT_MS;
+  if (raw === "0" || raw.toLowerCase() === "off") return 0;
+  try {
+    return parseDuration(raw);
+  } catch {
+    warn?.(`${STEP_HEARTBEAT_ENV}="${raw}" is not a duration (such as 30s or 5m) or off; using ${DEFAULT_STEP_HEARTBEAT_MS / 1000}s`);
+    return DEFAULT_STEP_HEARTBEAT_MS;
+  }
+}

package/src/point-decision-bundle.test.ts

@@ -51,6 +51,7 @@ describe("the point-decision bundle", () => {
       "packages/core/src/intrinsic.ts",
       "packages/core/src/lifecycle/gate-ledger-select.ts",
       "packages/core/src/lifecycle/gate-pending.ts",
+      "packages/core/src/lifecycle/no-record.ts",
       "packages/core/src/lifecycle/plan-digest.ts",
       "packages/core/src/op/duration.ts",
       "packages/core/src/op/gate-point.ts",

package/src/point-decision.ts

@@ -37,6 +37,7 @@ import type { GateLedgerPort } from "./op/gate";
 import { DEFAULT_GATE_POINT_PASS, defaultGatePointStore, gatePointInputs, gateSubject, type GatePoint, type GatePointFacts, type GatePointStore } from "./op/gate-point";
 import type { WaitingPoint } from "./op/steward-points";
 import { resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
+import { refuseGateWithoutRecording } from "./lifecycle/no-record";
 
 export {
   DEFAULT_GATE_POINT_PASS,
@@ -170,6 +171,8 @@ function resolvedByOf(q: GatePointQuestion): string {
 
 /** Decide a gate that asks a point: ask it, then record the pending fact or the resolution that cites the answer. */
 export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePointAsker, input: PointGateInput): Promise<PointGateCheck> {
+  // #3955: refused before the point is asked, which would itself write to the ledger.
+  refuseGateWithoutRecording(input.op, input.gate);
   const now = input.now ?? new Date().toISOString();
   const facts: GatePointFacts = { component: input.op, name: input.gate, env: input.env ?? null, planDigest: input.planDigest ?? null };
   const q = await asker.ask({ point: input.point.name, inputs: input.inputs ?? {}, facts, subject: gateSubject(input.op, input.gate, input.env), ...(input.point.store ? { store: input.point.store } : {}) });

package/src/wave-loop-golden.test.ts

@@ -43,6 +43,9 @@ beforeEach(() => {
   // A CI job's locator would land on every pending fact.
   vi.stubEnv("GITHUB_ACTIONS", "");
   vi.stubEnv("GITLAB_CI", "");
+  // A pull request's address would land on every pending fact too.
+  vi.stubEnv("GITHUB_REF_NAME", "");
+  vi.stubEnv("CI_MERGE_REQUEST_IID", "");
 });
 afterEach(() => vi.unstubAllEnvs());