@intentius/chant 0.95.1 → 0.96.0

package/dist/workspace/status-stewards.d.ts

@@ -14,13 +14,25 @@
  * - each Op's last run is the newest record in its run ledger,
  *   `<env>/runs__<op>.jsonl` under the member's ledger prefix, where `<env>`
  *   is the Op's own `labels.Env` or `local`;
+ * - an Op's `inFlight` is the run of it in flight now, from the record a
+ *   run keeps beside the checkout's git directory while it runs
+ *   (`../op/run-live.ts`): its phase and step, the phases it has finished and
+ *   its newest activity lines. Null once the run's ledger record is written,
+ *   or when the process that wrote it is gone;
  * - `waiting` lists the open decision points the steward waits on (#2749):
- *   each Op whose newest run is the steward's own and stopped on a question,
- *   as the run ledger records it. The question's state now is `points`'s.
- *   A run is the steward's when its record names it (`steward`, written for
- *   a run started in the steward's turn or under `CHANT_STEWARD`), so this
- *   also covers the member's other Ops, those no steward lists, that such a
- *   run belongs to, such as an Op the steward's process starts itself;
+ *   each Op whose newest run is the steward's own and stopped on a question
+ *   that is still open. The question's state is read now, the way `points`
+ *   reads it (`readQuestionStates`), not copied from the run ledger, which
+ *   keeps the state the run stopped with. A question answered since, or
+ *   whose record is gone, is not waited on; nor is one whose Op has a newer
+ *   run in flight that has not written its record yet: the Op's lease or one
+ *   of its work leases was taken after the waiting run ended
+ *   (`newerRunInFlight`). When the questions can't be read, the ledger's
+ *   state stands, as the operator's does. A run is the steward's when its
+ *   record names it (`steward`, written for a run started in the steward's
+ *   turn or under `CHANT_STEWARD`), so this also covers the member's other
+ *   Ops, those no steward lists, that such a run belongs to, such as an Op
+ *   the steward's process starts itself;
  * - `lease` is the local steward's own lease ref
  *   (`refs/chant/lease/[<prefix>]_stewards/<name>`), present while a
  *   `chant operator --steward` holds it or until it expires;
@@ -55,16 +67,64 @@ export interface StatusStewardRun {
         op: string;
         approve: string;
     } | null;
-    /** The open decision point the run stopped on, for a `waiting` run (#2749). */
+    /**
+     * The decision point the run stopped on, for a `waiting` run (#2749). Its
+     * state is the question's now, `answered` once a person has answered it.
+     */
     point: StatusStewardWait | null;
+    /** Each phase in execution order, with its wall-clock time, or the sum of its steps' for a record that kept none. */
+    phases: StatusStewardPhase[];
+}
+/** A phase of a run: its verdict and how long it took. */
+export interface StatusStewardPhase {
+    name: string;
+    status: "ok" | "fail" | "skipped";
+    durationMs: number;
+}
+/**
+ * The run of an Op in flight now (../op/run-live.ts): what it is doing while
+ * its ledger record is not yet written.
+ */
+export interface StatusStewardInFlight {
+    id: string;
+    started: string;
+    /** When the run last changed its record. */
+    updated: string;
+    steward: string | null;
+    /** The work item the run's lease holds, once it is claimed. */
+    item: string | null;
+    phase: {
+        name: string;
+        started: string;
+    } | null;
+    step: {
+        name: string;
+        fn: string;
+        started: string;
+    } | null;
+    /** The phases it has finished, in order. */
+    phases: StatusStewardPhase[];
+    /** The newest activity lines its steps reported; `total` counts every line of the run. */
+    activity: {
+        total: number;
+        lines: {
+            seq: number;
+            at: string | null;
+            text: string;
+        }[];
+    };
 }
-/** An open decision point a steward's run stopped on (#2749), as the run ledger records it. */
+/** A decision point a steward's run stopped on (#2749). */
 export interface StatusStewardWait {
     /** The answer record's id: what `points --open` lists and `points answer` names. */
     id: string;
     point: string;
-    /** The question's state when the run stopped. */
-    state: "escalated" | "proposed";
+    /**
+     * The question's state now, as `points` reads it. The state the run
+     * stopped with when the questions can't be read or its record is gone.
+     * Never `answered` in a steward's `waiting`.
+     */
+    state: "escalated" | "proposed" | "answered";
     path: string;
     subject: string | null;
     since: string;
@@ -104,6 +164,8 @@ export interface StatusStewardOp {
     env: string;
     /** The newest run in its run ledger, or null when it has none. */
     lastRun: StatusStewardRun | null;
+    /** The run in flight now, or null when none is. */
+    inFlight: StatusStewardInFlight | null;
     /** For a ConvergeOp, its newest tick on the converge ledger (#2778); null for any other Op, or before its first tick. */
     lastTick: StatusStewardTick | null;
     /** Whether the Op changes the checkout, and so runs under a work lease on a branch of its own (#2748). */
@@ -172,7 +234,8 @@ export interface StatusSteward {
     ops: StatusStewardOp[];
     /**
      * The open decision points the steward waits on (#2749): each Op whose
-     * newest run is the steward's own and stopped on a question. Its declared
+     * newest run is the steward's own and stopped on a question still open,
+     * with no newer run of the Op in flight. Its declared
      * Ops come first, in `ops` order, then any other Op of the member whose
      * newest run names the steward, by Op name.
      */
@@ -188,6 +251,8 @@ export interface MemberStewards {
         message: string;
     }[];
 }
+/** Every question's state in the workspace by id, or null when they can't all be read. */
+export type ReadQuestionStates = (cwd: string) => Promise<Map<string, string> | null>;
 /**
  * The stewards declared in one member, for `env`. `memberDir` is absolute.
  * Only a member of kind `chant` with a config of its own is read.
@@ -197,5 +262,7 @@ export declare function readMemberStewards(memberDir: string, env: string, now:
         name: string;
         broker: string | null;
     }[];
-} | null): Promise<MemberStewards>;
+} | null, deps?: {
+    readQuestions?: ReadQuestionStates;
+}): Promise<MemberStewards>;
 //# sourceMappingURL=status-stewards.d.ts.map

package/dist/workspace/status-stewards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status-stewards.d.ts","sourceRoot":"","sources":["../../src/workspace/status-stewards.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"status-stewards.d.ts","sourceRoot":"","sources":["../../src/workspace/status-stewards.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.95.1",
+  "version": "0.96.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/main.test.ts

@@ -756,6 +756,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace lint",
       "workspace ls",
       "workspace member-run",
+      "workspace patch",
       "workspace points",
       "workspace records",
       "workspace status",
@@ -773,6 +774,21 @@ describe("workspace init and ls (#2534)", () => {
     expect(() => parseArgs(["workspace", "work", "claim", "W-001", "--holder"])).toThrow(/--holder needs a value/);
   });
 
+  test("graph --intent takes --record in place of a region", () => {
+    expect(parseArgs(["workspace", "graph", "--intent", "--record", "studio-008", "--json"])).toMatchObject({ intent: "", record: "studio-008", json: true });
+    expect(parseArgs(["workspace", "graph", "--intent", "app/server.mjs"])).toMatchObject({ intent: "app/server.mjs" });
+    expect(() => parseArgs(["workspace", "graph", "--intent", "--json"])).toThrow(/--intent needs a region/);
+    expect(() => parseArgs(["workspace", "graph", "--intent", "--record"])).toThrow(/--record needs a record id/);
+  });
+
+  test("patch takes a range, --path and --max-bytes", () => {
+    const patch = parseArgs(["workspace", "patch", "main...chant/work/W-001", "--path", "app", "--path", "docs/a.md", "--max-bytes", "4096", "--json"]);
+    expect(patch).toMatchObject({ command: "workspace", path: "patch", extraPositional: "main...chant/work/W-001", paths: ["app", "docs/a.md"], maxBytes: 4096, json: true });
+    expect(resolveCommand(patch, commandRegistry)?.def.name).toBe("workspace patch");
+    expect(() => parseArgs(["workspace", "patch", "HEAD", "--max-bytes", "0"])).toThrow(/--max-bytes needs a whole number/);
+    expect(parseArgs(["workspace", "patch", "--worktree", "--path", "docs/a.md", "--json"])).toMatchObject({ command: "workspace", path: "patch", worktree: true, paths: ["docs/a.md"], json: true });
+  });
+
   test("run takes --work <id> for an Op with a work lease (#2748)", () => {
     expect(parseArgs(["run", "dispatch", "--work", "W-001", "--holder", "box/dispatch@h"])).toMatchObject({ command: "run", path: "dispatch", work: "W-001", holder: "box/dispatch@h" });
     expect(() => parseArgs(["run", "dispatch", "--work"])).toThrow(/--work needs a work item id/);

package/src/cli/main.ts

@@ -377,9 +377,28 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace graph --composites` (#2662)
       result.composites = true;
     } else if (arg === "--intent") {
-      // `chant workspace graph --intent <path[:start-end]>` (#2651)
-      result.intent = args[++i];
-      if (!result.intent || result.intent.startsWith("-")) throw new Error("--intent needs a region: --intent <path[:start-end]>");
+      // `chant workspace graph --intent <path[:start-end]>` (#2651), or `--intent --record <id>` with no region.
+      const value = args[i + 1];
+      if (value !== undefined && !value.startsWith("-")) result.intent = args[++i];
+      else if (args.includes("--record")) result.intent = "";
+      else throw new Error("--intent needs a region: --intent <path[:start-end]>, or --intent --record <id>");
+    } else if (arg === "--record") {
+      // `chant workspace graph --intent --record <id>`
+      result.record = args[++i];
+      if (!result.record || result.record.startsWith("-")) throw new Error("--record needs a record id: --record <id>");
+    } else if (arg === "--path") {
+      // `chant workspace patch <range> --path <p>`, repeatable
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--path needs a path: --path <path>");
+      (result.paths ??= []).push(value);
+    } else if (arg === "--worktree") {
+      // `chant workspace patch [<commit>] --worktree`
+      result.worktree = true;
+    } else if (arg === "--max-bytes") {
+      // `chant workspace patch <range> --max-bytes <n>`
+      const value = Number(args[++i]);
+      if (!Number.isInteger(value) || value < 1) throw new Error("--max-bytes needs a whole number of bytes above 0");
+      result.maxBytes = value;
     } else if (arg === "--changes") {
       // `chant workspace check --changes <base>..<head>` (#2773)
       result.changes = args[++i];
@@ -923,6 +942,12 @@ Workspace (level 1, #2524):
                         --work item and its decisions) lists it in
                         out_of_scope. The declaration's changes block sets
                         the severity (warn by default) and ignore globs
+  workspace patch <base>..<head>|<base>...<head>|<commit> [--path <p>...] [--max-bytes <n>] [--json]
+  workspace patch [<commit>] --worktree [--path <p>...] [--max-bytes <n>] [--json]
+                        The hunks of a diff, file by file: a range, a work
+                        branch, or one commit against its first parent. Each
+                        file's hunk text stops at --max-bytes (64 KiB) and
+                        says it was truncated
   workspace build [dir] [--member <name>] [-o <dir>] [--dry-run]
                         Build every chant member and example project, each with
                         its own chant, one process per toolchain. -o <dir>
@@ -952,6 +977,10 @@ Workspace (level 1, #2524):
                         touched it, the decisions whose constrains cover it,
                         the artifacts they pin, and findings with closed codes.
                         Without --kind, every record kind the declaration names
+  workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]
+                        One decision's intent walk over every path: and member:
+                        entry it constrains: the commits in its window, each
+                        own, worked, within-other or unexplained, with counts
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
@@ -1442,6 +1471,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },
   // #2641 — workspace check reads member configs statically and never runs one.
   { name: "workspace check", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/lineage-check")).runWorkspaceCheck(ctx) },
+  // The hunks of a diff, for a reader that runs no git of its own.
+  { name: "workspace patch", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/patch")).runWorkspacePatch(ctx) },
   // #2537 — per-member commands. Each member runs under its own chant, one
   // process per toolchain identity; `member-run` is that process's entry.
   { name: "workspace build", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "build") },

package/src/cli/registry.ts

@@ -303,8 +303,16 @@ export interface ParsedArgs {
   noCache?: boolean;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
   composites?: boolean;
-  /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */
+  /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. Empty with `--record`. */
   intent?: string;
+  /** `chant workspace graph --intent --record <id>`: walk one decision record over every entry its constrains lists. */
+  record?: string;
+  /** `chant workspace patch <range> --path <p>`: only these paths, from the workspace root. Repeatable. */
+  paths?: string[];
+  /** `chant workspace patch <range> --max-bytes <n>`: the most hunk text printed for one file. */
+  maxBytes?: number;
+  /** `chant workspace patch [<commit>] --worktree`: the working tree against the commit (HEAD unless given). */
+  worktree?: boolean;
   /** `chant workspace check --changes <base>..<head>` (#2773): the diff the forward coverage check maps to records. */
   changes?: string;
   /** `chant workspace check --changes ... --severity off|warn|fail` (#2773): in place of the declaration's `changes.severity`. */

package/src/lifecycle/run-ledger.ts

@@ -87,6 +87,8 @@ export function buildRunRecord(
     gate?: OpRunRecord["gate"];
     point?: OpRunRecord["point"];
     steward?: string;
+    /** Each phase's wall-clock time, by name, as the executor measured it. */
+    phaseDurations?: Record<string, number>;
   },
 ): OpRunRecordInput {
   const phases: OpRunPhaseRecord[] = [];
@@ -113,7 +115,11 @@ export function buildRunRecord(
     });
     if (record.outcome) outcomes[record.outcome.name] = record.outcome.value;
   }
-  for (const phase of phases) phase.status = phaseStatus(phase.steps);
+  for (const phase of phases) {
+    phase.status = phaseStatus(phase.steps);
+    const ms = times.phaseDurations?.[phase.name];
+    if (ms !== undefined) phase.durationMs = ms;
+  }
 
   return {
     ...(times.id !== undefined ? { id: times.id } : {}),

package/src/op/activities/shell.ts

@@ -2,6 +2,7 @@ import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { GateWait, asPendingGate } from "../gate-wait";
 import type { PendingGateRecord } from "../../lifecycle/gate-ledger";
+import { liveRunEnv } from "../run-live";
 
 const execAsync = promisify(exec);
 
@@ -116,7 +117,9 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
   try {
     const { stdout, stderr } = await execAsync(args.cmd, {
       cwd: args.cwd,
-      env: { ...process.env, ...args.env },
+      // In a run that keeps an in-flight record, CHANT_RUN_ACTIVITY names the
+      // file the command appends activity lines to (../run-live.ts).
+      env: { ...process.env, ...liveRunEnv(), ...args.env },
       maxBuffer: MAX_STDOUT_BYTES,
       signal,
     });

package/src/op/index.ts

@@ -135,6 +135,8 @@ export {
   currentStewardTurn, enterStewardTurn, setStewardTurn, resetStewardTurn, STEWARD_ENV,
 } from "./steward-turn";
 export type { StewardTurn } from "./steward-turn";
+export { reportRunActivity, readInFlightRun, RUN_ACTIVITY_ENV, RUN_ID_ENV } from "./run-live";
+export type { InFlightRun, InFlightRecord, InFlightPhase, InFlightActivityLine } from "./run-live";
 export type { DiscoveredSteward, StewardDiscoveryResult } from "./discover";
 export type {
   OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions,

package/src/op/local-executor.ts

@@ -38,6 +38,8 @@ import type { OpRunRecord } from "./runtime";
 import { randomUUID } from "node:crypto";
 import { RunWorkLease, LEASE_LOST, workLeaseProblems, workLeaseNeedsRunItem, type WorkLeaseRunResult } from "./work-lease-run";
 import { WORK_LEASE_STEP_ID } from "./types";
+import { LiveRun, currentLiveRun, withLiveRun } from "./run-live";
+import { runEnvOf } from "../lifecycle/run-ledger";
 
 export { parseDuration } from "./duration";
 
@@ -398,6 +400,15 @@ async function runStep(
     : Infinity;
   const nonRetryable = profile.retry?.nonRetryableErrorTypes ?? [];
 
+  // The in-flight record names the step while it runs.
+  const ended = currentLiveRun()?.stepStarted(step.fn, step.id);
+  try {
+    return await attempts();
+  } finally {
+    ended?.();
+  }
+
+  async function attempts(): Promise<RanStep> {
   let lastErr: unknown;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
@@ -435,6 +446,7 @@ async function runStep(
     }
   }
   return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(lastErr) } };
+  }
 }
 
 // ── Effect steps (#1834) ──────────────────────────────────────────────────────
@@ -518,6 +530,7 @@ async function workBoundary(
       return "unclaimed";
     }
     resultsById.set(WORK_LEASE_STEP_ID, claimed.lease);
+    currentLiveRun()?.item(claimed.lease.item);
     pushRecord(sink, ctx, {
       phase: phaseName,
       fn: "workLease:claim",
@@ -1026,9 +1039,22 @@ export async function runOpLocally(
   const turn = currentStewardTurn();
   const steward = options.steward ?? turn?.steward;
   const restore = turn && turn.run !== runId ? enterStewardTurn({ ...turn, run: runId }) : undefined;
+  // 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
+    ? await LiveRun.open({
+        cwd: options.ledger.cwd ?? options.cwd ?? process.cwd(),
+        env: runEnvOf(config),
+        op: config.name,
+        id: runId,
+        started: options.now ?? new Date().toISOString(),
+        ...(steward ? { steward } : {}),
+      })
+    : undefined;
   try {
-    return await runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) });
+    return await withLiveRun(live, () => runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) }));
   } finally {
+    live?.close();
     restore?.();
   }
 }
@@ -1126,6 +1152,20 @@ async function runOpInTurn(
 
   const records: StepRecord[] = [];
   const start = Date.now();
+  // Each phase's wall-clock time, for the run record and the in-flight one.
+  const phaseDurations: Record<string, number> = {};
+  const timedPhase = async (phase: PhaseDefinition, ctx: GateContext, phaseSignal: AbortSignal | undefined): Promise<StepRecord[]> => {
+    const live = currentLiveRun();
+    const t0 = Date.now();
+    live?.phaseStarted(phase.name);
+    try {
+      const ran = await runPhase(phase, activities, profiles, resultsById, ctx, phaseSignal);
+      live?.phaseEnded(phase.name, phaseVerdict(ran), Date.now() - t0);
+      return ran;
+    } finally {
+      phaseDurations[phase.name] = (phaseDurations[phase.name] ?? 0) + (Date.now() - t0);
+    }
+  };
   const startedAt = options.now ?? new Date(start).toISOString();
 
   /**
@@ -1148,6 +1188,7 @@ async function runOpInTurn(
       ...(gate ? { gate: { name: gate.gate, since: gate.timestamp, ...(gate.op !== config.name ? { op: gate.op } : {}) } } : {}),
       ...(point ? { point: { ...point, since: ended } } : {}),
       ...(options.steward ? { steward: options.steward } : {}),
+      phaseDurations,
     });
     const record: OpRunRecord = { version: 1, ...input, id: runId };
     if (!options.ledger) return record;
@@ -1167,7 +1208,7 @@ async function runOpInTurn(
   try {
     for (const phase of config.phases) {
       if (signal?.aborted) throw new PhaseFailure([]);
-      records.push(...(await runPhase(phase, activities, profiles, resultsById, gates, stepSignal)));
+      records.push(...(await timedPhase(phase, gates, stepSignal)));
     }
     // The last renewal before the run is recorded (#2748): a run whose lease
     // was lost is never recorded as done.
@@ -1269,7 +1310,7 @@ async function runOpInTurn(
     if (!signal?.aborted) {
       for (const phase of [...(config.onFailure ?? [])].reverse()) {
         try {
-          records.push(...(await runPhase(phase, activities, profiles, resultsById, compensation, signal)));
+          records.push(...(await timedPhase(phase, compensation, signal)));
         } catch (compErr) {
           if (compErr instanceof PhaseFailure || compErr instanceof GateStop || compErr instanceof PointStop) {
             records.push(...compErr.records);
@@ -1316,6 +1357,13 @@ async function runOpInTurn(
   };
 }
 
+/** A finished phase's verdict, as the run ledger folds it: `fail`, `skipped` when every step was, else `ok`. */
+function phaseVerdict(records: readonly StepRecord[]): "ok" | "fail" | "skipped" {
+  if (records.some((r) => r.status === "fail")) return "fail";
+  if (records.length > 0 && records.every((r) => r.status === "skipped")) return "skipped";
+  return "ok";
+}
+
 function errMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }

package/src/op/operator.ts

@@ -342,17 +342,8 @@ async function stewardGates(steward: StewardDeclaration, opts: OperatorRoundOpti
 
 /** Every question's state in the workspace, by id, or null when the workspace's points can't be read. */
 async function readQuestionStates(cwd: string): Promise<Map<string, string> | null> {
-  try {
-    const { workspacePoints } = await import("../workspace/points-cli");
-    const doc = await workspacePoints({ cwd });
-    if (!("questions" in doc)) return null;
-    // An answer kind that could not be read might hold the question: say
-    // nothing rather than resume a run whose question may still be open.
-    if (doc.sources.some((s) => s.reason !== null)) return null;
-    return new Map(doc.questions.map((q) => [q.id, q.state]));
-  } catch {
-    return null;
-  }
+  const { readQuestionStates: read } = await import("../workspace/points-cli");
+  return read(cwd);
 }
 
 /** Take or renew a local steward's own lease (#2731). */

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

@@ -0,0 +1,111 @@
+import { execFileSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { LiveRun, inFlightPaths, liveRunEnv, readInFlightRun, reportRunActivity, withLiveRun, RUN_ACTIVITY_ENV } from "./run-live";
+import { runOpLocally } from "./local-executor";
+import { readRunLedger } from "../lifecycle/run-ledger";
+import type { OpConfig } from "./types";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+function checkout(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "run-live-")));
+  dirs.push(dir);
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: dir });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+  return dir;
+}
+
+describe("the in-flight run record", () => {
+  test("is kept under the git directory and read back with the newest activity lines", async () => {
+    const dir = checkout();
+    const live = (await LiveRun.open({ cwd: dir, env: "local", op: "build", id: "r1", started: "2026-09-27T10:00:00.000Z", steward: "s" }))!;
+    expect(live.activityFile.startsWith(join(dir, ".git", "chant", "runs"))).toBe(true);
+    live.phaseStarted("Pick");
+    live.phaseEnded("Pick", "ok", 12);
+    live.phaseStarted("Build");
+    const done = live.stepStarted("shellCmd", "build");
+    live.item("W-1");
+    for (let i = 1; i <= 25; i++) appendFileSync(live.activityFile, `line ${i}\n`);
+
+    const run = (await readInFlightRun(dir, "local", "build"))!;
+    expect(run).toMatchObject({
+      id: "r1",
+      steward: "s",
+      item: "W-1",
+      phase: { name: "Build" },
+      step: { name: "build", fn: "shellCmd" },
+      phases: [{ name: "Pick", status: "ok", durationMs: 12 }],
+    });
+    expect(run.activity.total).toBe(25);
+    expect(run.activity.lines).toHaveLength(20);
+    expect(run.activity.lines[0]).toEqual({ seq: 6, at: null, text: "line 6" });
+
+    done();
+    expect((await readInFlightRun(dir, "local", "build"))!.step).toBeNull();
+    live.close();
+    expect(await readInFlightRun(dir, "local", "build")).toBeNull();
+  });
+
+  test("a record left by a process that is gone is not in flight", async () => {
+    const dir = checkout();
+    const paths = (await inFlightPaths(dir, "local", "build"))!;
+    const live = (await LiveRun.open({ cwd: dir, env: "local", op: "build", id: "r1", started: "2026-09-27T10:00:00.000Z" }))!;
+    const rec = JSON.parse(readFileSync(paths.record, "utf8"));
+    writeFileSync(paths.record, JSON.stringify({ ...rec, pid: 2 ** 22 + 12345 }));
+    expect(await readInFlightRun(dir, "local", "build")).toBeNull();
+    live.close();
+  });
+
+  test("outside a checkout there is none, and a report is a no-op", async () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "run-live-none-")));
+    dirs.push(dir);
+    expect(await LiveRun.open({ cwd: dir, env: "local", op: "x", id: "r", started: "now" })).toBeUndefined();
+    expect(liveRunEnv()).toEqual({});
+    expect(() => reportRunActivity("nothing")).not.toThrow();
+  });
+
+  test("a run hands its steps the activity file, and removes it once its ledger record is written", async () => {
+    const dir = checkout();
+    let seen: Record<string, string> = {};
+    let during: Awaited<ReturnType<typeof readInFlightRun>> = null;
+    const op = {
+      name: "build",
+      overview: "build",
+      phases: [
+        {
+          name: "Build",
+          steps: [{ kind: "activity", fn: "work", id: "build", args: {} }],
+        },
+      ],
+    } as unknown as OpConfig;
+    const activities = new Map([
+      [
+        "work",
+        async () => {
+          seen = liveRunEnv();
+          reportRunActivity("Edit  kit/lobby/box-side.mjs\n");
+          during = await readInFlightRun(dir, "local", "build");
+          return {};
+        },
+      ],
+    ]);
+    const result = await runOpLocally(op, activities as never, {}, undefined, { runId: "r2", ledger: { cwd: dir }, cwd: dir });
+    expect(result.status).toBe("ok");
+    expect(seen[RUN_ACTIVITY_ENV]).toMatch(/local__build\.activity\.jsonl$/);
+    expect(during).toMatchObject({ id: "r2", phase: { name: "Build" }, step: { name: "build" } });
+    expect(during!.activity.lines.map((l) => l.text)).toEqual(["Edit kit/lobby/box-side.mjs"]);
+    expect(existsSync(seen[RUN_ACTIVITY_ENV])).toBe(false);
+    const { records } = await readRunLedger("local", "build", { cwd: dir });
+    expect(records.at(-1)!.phases[0]).toMatchObject({ name: "Build", status: "ok", durationMs: expect.any(Number) });
+  });
+
+  test("withLiveRun without a run just calls through", async () => {
+    expect(await withLiveRun(undefined, async () => liveRunEnv())).toEqual({});
+  });
+});