@intentius/chant 0.91.0 → 0.94.0

package/src/op/local-executor.ts

@@ -25,10 +25,14 @@ import { resolveActivity, type ActivityFn, type ActivityProfile } from "./activi
 import type { ReceiptReadResult } from "./receipt-store";
 import { isStepOutputRef } from "./step-output-ref";
 import { parseDuration } from "./duration";
+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 type { PendingGateRecord } from "../lifecycle/gate-ledger";
+import { isPointWait, type WaitingPoint } from "./steward-points";
+import { isGateWait } from "./gate-wait";
+import { currentStewardTurn, enterStewardTurn } from "./steward-turn";
 import { appendRunRecord, buildRunRecord } from "../lifecycle/run-ledger";
 import type { OpRunRecord } from "./runtime";
 import { randomUUID } from "node:crypto";
@@ -78,6 +82,18 @@ export interface StepRecord {
    * was applied.
    */
   refusal?: string;
+  /**
+   * Set on an activity step that asked a decision point still open (#2749):
+   * the question the run now waits on. The step's status is `skipped` and the
+   * run's is `waiting`: nothing broke, and a person answers the question.
+   */
+  point?: WaitingPoint;
+  /**
+   * Set on an activity step whose command stopped at a gate of its own
+   * (#2779): the op the gate is recorded under and its name, what `chant
+   * approve` takes. The step's status is `skipped` and the run's is `gated`.
+   */
+  gate?: { op: string; gate: string };
 }
 
 export interface OpRunResult {
@@ -91,11 +107,17 @@ export interface OpRunResult {
    *
    * Written to the run ledger as the record's own `status` (#2118).
    */
-  status: "ok" | "fail" | "gated";
+  status: "ok" | "fail" | "gated" | "waiting";
   /** ISO-8601 start of this run. */
   startedAt: string;
   /** Present when `status === "gated"`: the pending fact the run ended on. */
   gate?: PendingGateRecord;
+  /**
+   * Present when `status === "waiting"` (#2749): the open decision point the
+   * run stopped on. Like a gate, it is a fact and not a wait: a person answers
+   * the question, and the next run reads the answer.
+   */
+  point?: WaitingPoint;
   /**
    * Present when `status === "gated"` and this run's own append tried to push:
    * whether it reached the remote (#2310). Absent when the run stopped on a
@@ -173,6 +195,18 @@ class GateStop extends Error {
   }
 }
 
+/** Internal: a step asked a decision point that is still open (#2749). Not a failure — no compensation follows it. */
+class PointStop extends Error {
+  constructor(
+    public readonly records: StepRecord[],
+    public readonly question: WaitingPoint,
+    public readonly phase: string,
+  ) {
+    super(`waiting on decision point ${question.id}`);
+    this.name = "PointStop";
+  }
+}
+
 /**
  * Internal: a step boundary found the run can't go on under its work lease
  * (#2748). `lost` false is a claim that found nothing to claim: not a
@@ -312,6 +346,8 @@ async function callWithTimeout(
 interface RanStep {
   record: StepRecord;
   result?: unknown;
+  /** The pending fact a step's command stopped at (#2779), when it threw {@link GateWait}. */
+  pending?: PendingGateRecord;
 }
 
 /**
@@ -341,9 +377,16 @@ async function runStep(
   }
 
   const profile = profiles[step.profile ?? DEFAULT_PROFILE] ?? {};
-  const timeoutMs = profile.timeout
-    ? parseDuration(profile.timeout)
-    : FALLBACK_TIMEOUT_MS;
+  // A step's own timeout (#2787) replaces the profile's and keeps its retries.
+  if (step.timeout !== undefined) {
+    const problem = stepTimeoutProblem(step.timeout);
+    if (problem) return { record: { ...base, status: "fail", durationMs: 0, error: problem } };
+  }
+  const timeoutMs = step.timeout !== undefined
+    ? parseDuration(step.timeout)
+    : profile.timeout
+      ? parseDuration(profile.timeout)
+      : FALLBACK_TIMEOUT_MS;
   const maxAttempts =
     profile.retry?.maximumAttempts && profile.retry.maximumAttempts > 0
       ? profile.retry.maximumAttempts
@@ -368,6 +411,17 @@ async function runStep(
       }
       return { record, result };
     } catch (err) {
+      // An open decision point (#2749) is not a failure and not worth a retry:
+      // the answer comes from a person, on a later run.
+      if (isPointWait(err)) {
+        return { record: { ...base, status: "skipped", durationMs: Date.now() - start, point: err.question } };
+      }
+      // Nor is a command that stopped at a gate of its own (#2779): the run
+      // ends `gated` there, and the next run asks the command again.
+      if (isGateWait(err)) {
+        const gate = { op: err.pending.op, gate: err.pending.gate };
+        return { record: { ...base, status: "skipped", durationMs: Date.now() - start, gate }, pending: err.pending };
+      }
       lastErr = err;
       // Stop retrying on abort (Ctrl-C / timeout cascade) or a non-retryable error.
       const fatal =
@@ -640,6 +694,7 @@ async function runEffectStep(
   pending?: PendingGateRecord;
   pushed?: boolean;
   pushWarning?: string;
+  point?: WaitingPoint;
 }> {
   const records: StepRecord[] = [];
 
@@ -705,6 +760,18 @@ async function runEffectStep(
     }
     const ran = await runStep(nested, phaseName, activities, profiles, resultsById, signal);
     pushRecord(records, gates, ran.record);
+    if (ran.pending) {
+      // A command's own gate (#2779): the receipt is left untouched, as for a
+      // pending gate step.
+      skipRest(i + 1);
+      return { records, failed: false, pending: ran.pending };
+    }
+    if (ran.record.point) {
+      // Receipt left untouched, as for a pending gate: the next run re-proposes
+      // the effect and asks the point again, and finds the answer by then.
+      skipRest(i + 1);
+      return { records, failed: false, point: ran.record.point };
+    }
     if (ran.record.status === "fail") {
       // Receipt left untouched (stale) — the next run re-proposes the effect.
       skipRest(i + 1);
@@ -779,12 +846,19 @@ async function runPhase(
       }
     }
     const steps = phase.steps.filter(isActivity);
-    const ran = (
-      await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)))
-    ).map((r) => r.record);
+    const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
+    const ran = settled.map((r) => r.record);
     for (const r of ran) gates.onRecord?.(r);
     const records = gateRecords.concat(ran);
     if (records.some((r) => r.status === "fail")) throw new PhaseFailure(records);
+    // A step whose command stopped at its own gate (#2779) stops the run at
+    // this phase, as a gate step would, once its siblings have finished.
+    const gated = settled.find((r) => r.pending)?.pending;
+    if (gated) throw new GateStop(records, gated, phase.name);
+    // The fan-out has already run, so the siblings of an open decision point
+    // finished; the run still stops at this phase (#2749).
+    const waiting = ran.find((r) => r.point);
+    if (waiting?.point) throw new PointStop(records, waiting.point, phase.name);
     return records;
   }
 
@@ -828,10 +902,14 @@ async function runPhase(
       continue;
     }
     if (isEffect(step)) {
-      const { records: effRecords, failed, pending, pushed, pushWarning } = await runEffectStep(
+      const { records: effRecords, failed, pending, pushed, pushWarning, point } = await runEffectStep(
         step, phase.name, activities, profiles, resultsById, gates, signal,
       );
       records.push(...effRecords); // already emitted by runEffectStep
+      if (point) {
+        skipRemaining(i + 1);
+        throw new PointStop(records, point, phase.name);
+      }
       if (pending) {
         skipRemaining(i + 1);
         throw new GateStop(records, pending, phase.name, pushed, pushWarning);
@@ -842,8 +920,19 @@ async function runPhase(
       }
       continue;
     }
-    const { record } = await runStep(step, phase.name, activities, profiles, resultsById, signal);
+    const { record, pending } = await runStep(step, phase.name, activities, profiles, resultsById, signal);
     pushRecord(records, gates, record);
+    if (pending) {
+      // The step's command stopped at its own gate (#2779): the run ends
+      // `gated` there, as at a pending gate step.
+      skipRemaining(i + 1);
+      throw new GateStop(records, pending, phase.name);
+    }
+    if (record.point) {
+      // An open decision point (#2749) ends the run as a pending gate does.
+      skipRemaining(i + 1);
+      throw new PointStop(records, record.point, phase.name);
+    }
     if (record.status === "fail") {
       // Mark the remaining steps in this phase as skipped, then abort.
       skipRemaining(i + 1);
@@ -890,6 +979,8 @@ export interface RunOpOptions {
    * never promoted into a run failure.
    */
   onLedgerError?: (err: unknown) => void;
+  /** The steward whose turn this run is (#2749), recorded on its ledger record. */
+  steward?: string;
   /**
    * For an Op that declares `workLease` (#2748): the item this run is for
    * (`chant run <op> --work <id>`), which takes the place of the Op's own, and
@@ -907,9 +998,10 @@ export interface RunOpOptions {
  * Resolves with the run result when every phase succeeds (`status: "ok"`), and
  * also when the run stopped at an unapproved gate (`status: "gated"`, with the
  * pending fact on `result.gate`) — a gate is a fact, not an error, so it is not
- * thrown. Rejects with `OpRunFailure` (carrying the partial result) on terminal
- * failure, after running any `onFailure` phases in reverse order; a gated run
- * runs no `onFailure` phase, because nothing failed and nothing was left
+ * thrown. So does an activity's open decision point (`status: "waiting"`, with
+ * the question on `result.point`, #2749). Rejects with `OpRunFailure` (carrying the partial result) on terminal
+ * failure, after running any `onFailure` phases in reverse order; a gated or
+ * waiting run runs no `onFailure` phase, because nothing failed and nothing was left
  * half-applied to compensate for.
  *
  * Whichever of the three ways it settles, the run carries an
@@ -928,6 +1020,27 @@ export async function runOpLocally(
   // The run id is the gate ledger's and the run ledger's alike: a pending gate
   // fact and the record naming that gate carry the same string.
   const runId = options.runId ?? randomUUID();
+  // In a steward's turn (#2749: `chant operator --steward`, or `chant acp
+  // --steward` on Fountain) the run is the steward's: its record names the
+  // steward, and a decision point asked during it names this run.
+  const turn = currentStewardTurn();
+  const steward = options.steward ?? turn?.steward;
+  const restore = turn && turn.run !== runId ? enterStewardTurn({ ...turn, run: runId }) : undefined;
+  try {
+    return await runOpInTurn(config, activities, profiles, signal, { ...options, runId, ...(steward ? { steward } : {}) });
+  } finally {
+    restore?.();
+  }
+}
+
+async function runOpInTurn(
+  config: OpConfig,
+  activities: Map<string, ActivityFn>,
+  profiles: Record<string, ActivityProfile>,
+  signal: AbortSignal | undefined,
+  options: RunOpOptions & { runId: string },
+): Promise<OpRunResult> {
+  const runId = options.runId;
 
   const gates: GateContext = {
     op: config.name,
@@ -1023,13 +1136,18 @@ export async function runOpLocally(
     settled: StepRecord[],
     status: OpRunResult["status"],
     gate?: PendingGateRecord,
+    point?: WaitingPoint,
   ): Promise<OpRunRecord> => {
+    const ended = options.now ?? new Date().toISOString();
     const input = buildRunRecord(config, settled, {
       started: startedAt,
-      ended: options.now ?? new Date().toISOString(),
+      ended,
       status,
       id: runId,
-      ...(gate ? { gate: { name: gate.gate, since: gate.timestamp } } : {}),
+      // A gate recorded under another op (#2779: a command's own gate) names it.
+      ...(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 } : {}),
     });
     const record: OpRunRecord = { version: 1, ...input, id: runId };
     if (!options.ledger) return record;
@@ -1072,6 +1190,24 @@ export async function runOpLocally(
       };
     }
 
+    // An open decision point ends the run the way a pending gate does (#2749):
+    // no later phase and no compensation, and the run is `waiting`.
+    if (err instanceof PointStop) {
+      records.push(...err.records);
+      skipLaterPhases(err.phase);
+      const record = await settle(records, "waiting", undefined, err.question);
+      return {
+        op: config.name,
+        records,
+        totalMs: Date.now() - start,
+        status: "waiting",
+        startedAt,
+        point: err.question,
+        record,
+        ...(await finishWork("waiting")),
+      };
+    }
+
     // A pending gate ends the run where it stands: no later phase, and no
     // `onFailure` compensation — nothing failed, so there is nothing to undo.
     if (err instanceof GateStop) {
@@ -1135,7 +1271,7 @@ export async function runOpLocally(
         try {
           records.push(...(await runPhase(phase, activities, profiles, resultsById, compensation, signal)));
         } catch (compErr) {
-          if (compErr instanceof PhaseFailure || compErr instanceof GateStop) {
+          if (compErr instanceof PhaseFailure || compErr instanceof GateStop || compErr instanceof PointStop) {
             records.push(...compErr.records);
           } else {
             // The same swallow, one level down (#2301): a compensation phase

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

@@ -75,6 +75,23 @@ const GATED: OpRunResult = withRecord({
   ],
 });
 
+/** A gate bound to a plan (#2300), for the --plan tests (#2832). */
+const GATED_WITH_PLAN: OpRunResult = withRecord({
+  op: "prod-apply",
+  totalMs: 300,
+  status: "gated",
+  startedAt: "2026-09-05T12:00:00.000Z",
+  gate: {
+    version: 1, kind: "pending", op: "prod-apply", gate: "rollout-gate",
+    timestamp: "2026-09-05T12:00:00.000Z",
+    expiresAt: "2026-09-07T12:00:00.000Z",
+    planDigest: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  },
+  records: [
+    { phase: "Apply", fn: "gate:rollout-gate", args: {}, status: "skipped", durationMs: 0 },
+  ],
+});
+
 describe("renderHuman — gated (#2119)", () => {
   test("names the gate, the approve line and the expiry, and points at no other runtime", () => {
     const lines: string[] = [];
@@ -88,6 +105,14 @@ describe("renderHuman — gated (#2119)", () => {
     expect(out).not.toContain("--on");
   });
 
+  test("a gate bound to a plan (#2300) carries --plan on the approve line (#2832)", () => {
+    const lines: string[] = [];
+    renderHuman(GATED_WITH_PLAN, (l) => lines.push(l));
+    const out = lines.join("\n");
+    expect(out).toContain(`plan    : ${GATED_WITH_PLAN.gate!.planDigest}`);
+    expect(out).toContain(`approve : chant approve prod-apply rollout-gate --plan ${GATED_WITH_PLAN.gate!.planDigest}`);
+  });
+
   test("shows the approver on a gate that passed", () => {
     const lines: string[] = [];
     renderHuman(withRecord({
@@ -157,6 +182,14 @@ describe("renderJson", () => {
     expect(parsed.approve).toBe("chant approve prod-apply rollout-gate");
   });
 
+  test("a gate bound to a plan (#2300) carries --plan on the approve line (#2832)", () => {
+    const lines: string[] = [];
+    renderJson(GATED_WITH_PLAN, (l) => lines.push(l));
+    const parsed = JSON.parse(lines[0]) as OpRunRecord & { approve: string };
+    expect(parsed.status).toBe("gated");
+    expect(parsed.approve).toBe(`chant approve prod-apply rollout-gate --plan ${GATED_WITH_PLAN.gate!.planDigest}`);
+  });
+
   // #2310: a JSON consumer (CI tooling reading `chant run --json`) needs the
   // same fact the human render shows — not just a silent success.
   test("a gated record whose push failed carries pushed:false and why", () => {

package/src/op/local-output.ts

@@ -50,6 +50,9 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
     if (record.refusal) {
       write(`    [refused] ${record.refusal}`);
     }
+    if (record.point) {
+      write(`    [waiting] decision point ${record.point.point}: ${record.point.id} is ${record.point.state}`);
+    }
     if (record.error) {
       write(`    ${record.error}`);
     }
@@ -73,6 +76,16 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
     write(`Op "${result.op}" completed in ${total}`);
     return;
   }
+  if (result.status === "waiting" && result.point) {
+    // An open decision point (#2749): a fact like a gate. A person answers the
+    // question, through hud or at a shell, and the next run reads the answer.
+    const { point } = result;
+    write(`Op "${result.op}" is waiting on decision point "${point.point}" after ${total}`);
+    write(`  question: ${point.id} (${point.state}) at ${point.path}`);
+    if (point.subject) write(`  subject : ${point.subject}`);
+    write(`  answer  : ${pointAnswerCommand(point.id)}`);
+    return;
+  }
   if (result.status === "fail" || !result.gate) {
     write(`Op "${result.op}" failed after ${total}`);
     return;
@@ -87,7 +100,7 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
   // #2300: the plan the approval will be bound to. Printed before the
   // command, because it is what the command approves.
   if (gate.planDigest) write(`  plan    : ${gate.planDigest}`);
-  write(`  approve : ${approveCommand(gate.op, gate.gate)}`);
+  write(`  approve : ${approveCommand(gate.op, gate.gate, undefined, gate.planDigest)}`);
   if (gate.url) write(`  approve at: ${gate.url}`);
   write(`  expires : ${gate.expiresAt}`);
   // #2310: this run's own append reached only the local chant/lifecycle
@@ -115,7 +128,7 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
  * the gate doesn't have to reassemble it from the op and gate names.
  */
 export function renderJson(result: OpRunResult, write: Writer = stdout): void {
-  const approve = result.gate ? { approve: approveCommand(result.gate.op, result.gate.gate) } : {};
+  const approve = result.gate ? { approve: approveCommand(result.gate.op, result.gate.gate, undefined, result.gate.planDigest) } : {};
   // #2310: whether this run's own append reached the remote — not part of
   // the persisted ledger record (a replay has nothing new to report), but a
   // live run's JSON consumer needs it exactly where the human render shows it.
@@ -126,3 +139,8 @@ export function renderJson(result: OpRunResult, write: Writer = stdout): void {
 }
 
 export type { OpRunResult, StepRecord };
+
+/** The command a person answers an open decision point with (#2749). */
+export function pointAnswerCommand(id: string): string {
+  return `chant workspace points answer ${id} --answer <answer> --by <your name>`;
+}

package/src/op/op-ir.test.ts

@@ -112,6 +112,16 @@ describe("op.json IR", () => {
     expect(serializeOpIR(reconstructed)).toBe(text);
   });
 
+  it("carries a step's own timeout, and round-trips it (#2787)", () => {
+    const original: OpConfig = { name: "dispatch", overview: "o", phases: [phase("Build", [shell("./build.sh", { timeout: "45m" }), shell("echo hi")])] };
+    const ir = buildOpIR(original);
+    const steps = ir.phases[0].steps as { profile: string; timeout?: string }[];
+    expect(steps[0]).toMatchObject({ profile: "atMostOnce", timeout: "45m" });
+    expect(steps[1]).not.toHaveProperty("timeout");
+    const text = serializeOpIR(original);
+    expect(serializeOpIR(opConfigFromIR(JSON.parse(text) as OpIR))).toBe(text);
+  });
+
   it("two serializations of the same config are byte-identical (determinism)", () => {
     const config = representativeOp();
     expect(serializeOpIR(config)).toBe(serializeOpIR(config));

package/src/op/op-ir.ts

@@ -118,6 +118,8 @@ export interface OpIRActivityStep {
   args: Record<string, unknown>;
   /** Resolved to its effective value — `ActivityStep.profile ?? "fastIdempotent"`. */
   profile: string;
+  /** The step's own timeout, replacing its profile's (#2787). Absent when the profile's applies. */
+  timeout?: string;
   /**
    * What this step's effect touches in the estate (#2022): the string values
    * of the args its contract declares as entity-identifying
@@ -240,6 +242,7 @@ function irActivityStep(step: ActivityStep, contracts: ReadonlyMap<string, Activ
     fn: step.fn,
     args: step.args ?? {},
     profile: effectiveProfile(step),
+    ...(step.timeout !== undefined ? { timeout: step.timeout } : {}),
     ...(entities ? { entities } : {}),
     ...(step.outcomeAttribute ? { outcomeAttribute: step.outcomeAttribute } : {}),
   };
@@ -394,6 +397,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       fn: step.fn,
       args: step.args,
       profile: step.profile as ActivityStep["profile"],
+      ...(step.timeout !== undefined ? { timeout: step.timeout } : {}),
       ...(step.outcomeAttribute ? { outcomeAttribute: step.outcomeAttribute } : {}),
     };
   }

package/src/op/op-verb-class.ts

@@ -51,6 +51,7 @@ const READ_ONLY_ACTIVITY_FNS: ReadonlySet<string> = new Set([
   "spriteServiceGet",
   "spriteServiceList",
   "spriteServiceLogs",
+  "spriteServicesObserve",
 ]);
 
 /** Activity function names that always delete/destroy, regardless of args. */