@falai/agent 4.0.0-alpha.2 → 4.0.0-alpha.21

package/src/core/Runner.ts

@@ -8,13 +8,12 @@
  *   begin ─▶ understandRequest ─(Understand)─▶ decide ─▶ advance ─(Speak)─▶ settle ─▶ finish
  */
 
-import type { AgentOptions, EndReason, TurnInput, TurnResult } from "../types/agent.js";
+import type { AgentOptions, EndReason, PendingWakesInput, ScheduleEntry, TurnBase, TurnInput, TurnResult } from "../types/agent.js";
 import type { TokenUsage } from "../types/ai.js";
 import type { ActionResult, Branch, DoStep, Duration, Flow, IfStep, Next, Pred, PredCtx, Repeat, SayStep, Step, StepBase, TalkStep, Trigger, WaitEventStep, WaitStep } from "../types/flow.js";
 import type { History } from "../types/history.js";
 import type { Run, Session, StepOutcome, StepOutcomeCode, StepOutcomeKind, TriggerKind } from "../types/session.js";
-import { cloneDeep } from "../utils/clone.js";
-import { parseDuration } from "../utils/duration.js";
+import { isDuration, parseDuration } from "../utils/duration.js";
 import { OUTCOME_MESSAGES } from "../utils/outcomes.js";
 import { coerceField, DEFAULT_MAX_ASKS, extractMode, isKnown, pendingFields } from "../utils/schema.js";
 import { render, renderDeep } from "../utils/template.js";
@@ -49,7 +48,7 @@ export type What =
 
 /** The mutable per-turn state. `session` is a deep copy; the input is never touched. */
 export interface Turn<C = unknown, D = unknown> {
-  readonly input: TurnInput<C, D>;
+  readonly input: TurnBase<C, D>;
   readonly what: What;
   readonly kind: InputKind;
   /** Message id, wake key, event key or start key: the trigger key of runs started this turn. */
@@ -62,6 +61,8 @@ export interface Turn<C = unknown, D = unknown> {
   readonly silenced?: string;
   /** The host gate allows the understand call even though the assistant cannot speak. */
   readonly understandAllowed: boolean;
+  /** The host gate only stops messages: a talk or `say` step is skipped and the run goes on. */
+  readonly skipSilenced: boolean;
   /** Set by a short-circuit: the input is a no-op and nothing is saved. */
   ignored: boolean;
   messages: TurnResult<D>["messages"];
@@ -86,6 +87,8 @@ export interface Turn<C = unknown, D = unknown> {
   /** A short `wait` waiting to ride on the next message. */
   afterMs: number;
   talk?: TalkRequest<C, D>;
+  /** Understand's judgment that the lead's message asks something; absent when nothing judged it. */
+  asks?: boolean;
   /** Speak already happened (or was skipped): a talk step reached now waits for the next message. */
   speakDone: boolean;
   /** Runs still to move this phase; `follow` appends children. */
@@ -137,6 +140,13 @@ function talkKind(step: { collect?: readonly string[] }): StepOutcomeKind {
   return step.collect?.length ? "collect" : "prompt";
 }
 
+/** Everything a flow collects: its own `collect`, then each talk step's, once each. */
+function flowFields<C, D>(flow: Flow<C, D>): string[] {
+  const fields = new Set<string>(flow.collect);
+  for (const step of flow.steps) if (isTalk(step)) for (const field of step.collect ?? []) fields.add(field);
+  return [...fields];
+}
+
 function kindOf<C, D>(step: Step<C, D> | undefined): StepOutcomeKind {
   if (!step) return "if";
   if (isTalk(step)) return talkKind(step);
@@ -171,16 +181,31 @@ export class Runner<C = unknown, D = unknown> {
   // ── Load + Ingest ─────────────────────────────────────────────────────
 
   begin(input: TurnInput<C, D>): Turn<C, D> {
-    const now = (this.options.clock ?? (() => new Date()))();
+    const now = this.now();
+    const turn = this.open(input, describe(input, now.toISOString()), now);
+    if (turn.what.kind === "wake" && !input.session) {
+      this.ignore(turn, "no-session", turn.what.key);
+      return turn;
+    }
+    turn.ingesting = true;
+    this.ingest(turn);
+    turn.ingesting = false;
+    return turn;
+  }
+
+  private now(): Date {
+    return (this.options.clock ?? (() => new Date()))();
+  }
+
+  private open(input: TurnBase<C, D>, what: What, now: Date): Turn<C, D> {
     const nowIso = now.toISOString();
-    const what = describe(input, nowIso);
     const silenced = typeof input.silenced === "string" ? input.silenced : input.silenced?.reason;
-    const turn: Turn<C, D> = {
+    return {
       input,
       what,
       kind: what.kind,
       triggerKey: what.kind === "message" ? (what.id ?? what.at) : what.key,
-      session: input.session ? cloneDeep(input.session) : freshSession<D>(input.sessionId),
+      session: input.session ? structuredClone(input.session) : freshSession<D>(input.sessionId),
       original: input.session,
       now,
       nowIso,
@@ -188,6 +213,7 @@ export class Runner<C = unknown, D = unknown> {
       context: input.context as C,
       silenced,
       understandAllowed: typeof input.silenced === "object" && input.silenced.understand === true,
+      skipSilenced: typeof input.silenced === "object" && input.silenced.skip === true,
       ignored: false,
       messages: [],
       schedule: [],
@@ -204,14 +230,17 @@ export class Runner<C = unknown, D = unknown> {
       speakDone: false,
       queue: [],
     };
-    if (what.kind === "wake" && !input.session) {
-      this.ignore(turn, "no-session", what.key);
-      return turn;
-    }
-    turn.ingesting = true;
-    this.ingest(turn);
-    turn.ingesting = false;
-    return turn;
+  }
+
+  /** Every wake the session waits on: each parked run's own, then each silence flow's since the assistant last spoke. */
+  pendingWakes(input: PendingWakesInput<C, D>): ScheduleEntry[] {
+    // No input arrives, so nothing reads `what`: the inert wake shape only fills the field.
+    const turn = this.open({ ...input, sessionId: input.session.id }, { kind: "wake", key: "" }, this.now());
+    // `park` always sets both; the type leaves them optional, so a hand-built blob without them has no wake to give.
+    const parked = turn.session.runs.flatMap(({ status, waiting }) =>
+      status === "waiting" && waiting?.key && waiting.until ? [{ key: waiting.key, at: new Date(waiting.until) }] : [],
+    );
+    return [...parked, ...this.silenceWakes(turn)];
   }
 
   private ingest(turn: Turn<C, D>): void {
@@ -285,6 +314,8 @@ export class Runner<C = unknown, D = unknown> {
       const branch = step.branches?.find((b) => "if" in b && this.holds(b.if, turn, run));
       const target = branch ? branch.then : step.else;
       this.outcome(turn, run, { kind: "wait", status: "ok", code: "replied", next: nextLabel(target) });
+      // The reply is this run's while it moves, so a stay it reaches answers it.
+      if (!turn.floorFromIngest) turn.floorRunId = run.id;
       this.follow(turn, run, flow, step, target);
       this.takeFloor(turn, run);
     }
@@ -323,8 +354,10 @@ export class Runner<C = unknown, D = unknown> {
   /** `silence:<flowId>:<sessionId>:<lastAssistantAtMs>`, honoured only while the blob still shows that silence. */
   private silenceWake(turn: Turn<C, D>, key: string): void {
     const rest = key.slice("silence:".length);
-    const flowId = rest.slice(0, rest.indexOf(":"));
     const ms = Number(rest.slice(rest.lastIndexOf(":") + 1));
+    // A flow id may hold a ":" itself, so cut at the session id rather than at the first ":".
+    const cut = rest.lastIndexOf(`:${turn.session.id}:`);
+    const flowId = rest.slice(0, cut === -1 ? rest.indexOf(":") : cut);
     const { lastAssistantAt } = turn.session;
     const flow = this.flows.get(flowId);
     if (!flow) {
@@ -386,11 +419,8 @@ export class Runner<C = unknown, D = unknown> {
       return null;
     };
     if (opts.trigger?.if && !this.holds(opts.trigger.if, turn, run)) return null;
-    const heldAt = this.claimAt(turn, dedupeKey);
-    if (heldAt !== undefined) {
-      if (typeof repeat === "string") return skip("already-claimed");
-      if (turn.now.getTime() - Date.parse(heldAt) < parseDuration(repeat.cooldown)) return skip("cooldown");
-    }
+    const blocked = this.repeatBlocks(turn, dedupeKey, repeat);
+    if (blocked) return skip(blocked);
     if (hop >= MAX_HOP) return skip("hop-limit");
     const live = session.runs.find((r) => r.flowId === flow.id && r.anchor === anchor);
     if (live) {
@@ -407,9 +437,11 @@ export class Runner<C = unknown, D = unknown> {
     }
     session.runs.push(run);
     turn.started.push({ runId: run.id, flowId: flow.id, anchor, dedupeKey });
-    const after = opts.trigger && "event" in opts.trigger ? opts.trigger.after : undefined;
-    if (after) {
-      const at = this.snap(turn, new Date(turn.now.getTime() + parseDuration(after)), opts.trigger && "event" in opts.trigger ? opts.trigger.businessHours : undefined);
+    const eventTrigger = opts.trigger && "event" in opts.trigger ? opts.trigger : undefined;
+    const after = eventTrigger?.after;
+    const at = this.snap(turn, new Date(turn.now.getTime() + (after ? parseDuration(after) : 0)), eventTrigger?.businessHours);
+    // With no `after`, only a closed hour parks the start: inside working hours the snap returns now.
+    if (after || at.getTime() > turn.now.getTime()) {
       this.park(turn, run, { kind: "timer", key: `${run.id}:start:${at.getTime()}` }, at);
       this.outcome(turn, run, { kind: "wait", status: "waiting", code: "awaiting-trigger", until: at.toISOString() });
     }
@@ -433,10 +465,15 @@ export class Runner<C = unknown, D = unknown> {
 
   private repeatAllows(turn: Turn<C, D>, flow: Flow<C, D>, trigger: Trigger<C, D>, key: string): boolean {
     const repeat = trigger.repeat ?? defaultRepeat(triggerKind(trigger));
-    const heldAt = this.claimAt(turn, `${flow.id}:${this.anchorOf(turn, flow)}:${repeat === "always" ? key : ""}`);
-    if (heldAt === undefined) return true;
-    if (typeof repeat === "string") return false;
-    return turn.now.getTime() - Date.parse(heldAt) >= parseDuration(repeat.cooldown);
+    return !this.repeatBlocks(turn, `${flow.id}:${this.anchorOf(turn, flow)}:${repeat === "always" ? key : ""}`, repeat);
+  }
+
+  /** Why the claim already on `dedupeKey` stops another start, or nothing when there is none or its cooldown has run out. */
+  private repeatBlocks(turn: Turn<C, D>, dedupeKey: string, repeat: Repeat): "already-claimed" | "cooldown" | undefined {
+    const heldAt = this.claimAt(turn, dedupeKey);
+    if (heldAt === undefined) return undefined;
+    if (typeof repeat === "string") return "already-claimed";
+    return turn.now.getTime() - Date.parse(heldAt) < parseDuration(repeat.cooldown) ? "cooldown" : undefined;
   }
 
   /** A run as it would be if started now, for trigger-level predicates. */
@@ -508,8 +545,7 @@ export class Runner<C = unknown, D = unknown> {
     const floorRun = this.floorRun(turn);
     const floorFlow = floorRun && this.flows.get(floorRun.flowId);
     const eligible = this.eligibleMessageFlows(turn);
-    // Exactly one eligible message flow and no floor: it starts without scoring (S9).
-    const messageFlows = !floorRun && eligible.length === 1 ? [] : eligible;
+    const messageFlows = !floorRun && this.startsUnscored(turn, eligible) ? [] : eligible;
     const mentionFlows = this.mentionFlows()
       .filter(({ flow, trigger }) => trigger.mention.length > 0 && this.repeatAllows(turn, flow, trigger, turn.triggerKey))
       .map(({ flow }) => flow);
@@ -522,16 +558,25 @@ export class Runner<C = unknown, D = unknown> {
     }
     const fields: UnderstandRequest<C, D>["fields"] = {};
     const data: Record<string, unknown> = turn.session.data;
+    const harvestable = (field: string): boolean => {
+      const def = this.options.fields[field];
+      return def !== undefined && !isKnown(data[field]) && extractMode(def) === "anywhere";
+    };
     for (const flow of [...(floorFlow ? [floorFlow] : []), ...eligible]) {
-      for (const step of flow.steps) {
-        if (!isTalk(step)) continue;
-        for (const field of step.collect ?? []) {
-          const def = this.options.fields[field];
-          if (def && !isKnown(data[field]) && extractMode(def) === "anywhere") fields[field] = def;
-        }
-      }
+      for (const field of flowFields(flow).filter(harvestable)) fields[field] = this.options.fields[field];
+    }
+    const judging = messageFlows.length > 0 || mentionFlows.length > 0 || branches.length > 0 || Object.keys(fields).length > 0;
+    // With nobody on the floor the catch-all may take this message, and an opening message often says the most. The
+    // fields its first step asks ride on that step's speak call, so alone they spend no call; a fixed question has no speak call.
+    // ponytail: "first step" is steps[0]; a catch-all that opens with a say or an if pays the call for that step's fields too.
+    const fallback = floorRun ? undefined : this.messageFlows(turn, (list) => list.length === 0)[0];
+    if (fallback) {
+      const first = fallback.steps[0];
+      const free = new Set<string>(first && isTalk(first) && first.question === undefined ? first.collect : []);
+      const own = flowFields(fallback).filter(harvestable);
+      if (judging || own.some((field) => !free.has(field))) for (const field of own) fields[field] = this.options.fields[field];
     }
-    if (!messageFlows.length && !mentionFlows.length && !branches.length && !Object.keys(fields).length) return null;
+    if (!judging && !Object.keys(fields).length) return null;
     return {
       text: turn.what.text,
       history: this.historyOf(turn),
@@ -562,6 +607,14 @@ export class Runner<C = unknown, D = unknown> {
     return this.messageFlows(turn, (list) => list.length > 0);
   }
 
+  /**
+   * The lone eligible flow starts without a score only when a low score would have nowhere
+   * else to send the message: no catch-all passes and the idle speaker is silent (S9).
+   */
+  private startsUnscored(turn: Turn<C, D>, eligible: Flow<C, D>[]): boolean {
+    return eligible.length === 1 && this.options.idle === "silent" && this.messageFlows(turn, (list) => list.length === 0).length === 0;
+  }
+
   private messageFlows(turn: Turn<C, D>, accept: (list: string[]) => boolean): Flow<C, D>[] {
     const out: Flow<C, D>[] = [];
     for (const flow of this.flows.values()) {
@@ -590,6 +643,7 @@ export class Runner<C = unknown, D = unknown> {
     if (turn.ignored || turn.what.kind !== "message") return;
     turn.llmCalls += understanding?.llmCalls ?? 0;
     turn.usage = addUsage(turn.usage, understanding?.usage);
+    if (understanding?.asks !== undefined) turn.asks = understanding.asks;
     const key = turn.triggerKey;
     const asker = this.asker(turn);
 
@@ -605,7 +659,7 @@ export class Runner<C = unknown, D = unknown> {
         const current = scores[asker.flowId] ?? 0;
         const top = best(eligible.filter((f) => f.id !== asker.flowId));
         if (top && top.score >= current + ROUTE_STICKY && top.score >= ROUTE_MIN) route = top.flow;
-      } else if (eligible.length === 1) {
+      } else if (this.startsUnscored(turn, eligible)) {
         route = eligible[0];
       } else {
         const top = best(eligible);
@@ -632,6 +686,9 @@ export class Runner<C = unknown, D = unknown> {
       }
     }
 
+    // Unless routing or Ingest moved it, the message is the asker's: written down, so a chain beside it cannot take it.
+    if (asker && !route && !turn.floorFromIngest) turn.floorRunId = asker.id;
+
     for (const [field, raw] of Object.entries(understanding?.fields ?? {})) this.writeField(turn, field, raw);
 
     if (asker && turn.session.runs.includes(asker) && asker.status === "asking") {
@@ -642,8 +699,15 @@ export class Runner<C = unknown, D = unknown> {
   }
 
   private fireBranch(turn: Turn<C, D>, run: Run, flow: Flow<C, D>, step: TalkOf<C, D>, understanding: Understanding | null): void {
+    // Staying, a run does not take an `if` branch back onto a path it has already run: the fact it tests is still true,
+    // so it would re-run that path on every message. A `when` branch is judged on each new message and always counts.
+    // ponytail: "already run" is the target's visit count, so an `if` restart (`{ step, clear }` to a visited step) never fires while staying; write it as a `when`.
+    const ran = (then: Next<D>): boolean =>
+      typeof then === "string" ? then === "end" || (run.visits[then] ?? 0) > 0 : "step" in then && (run.visits[then.step] ?? 0) > 0;
     const hit = (branch: Branch<C, D>, index: number): boolean =>
-      "if" in branch ? this.holds(branch.if, turn, run) : understanding?.branches[`${run.id}/${step.id}/${index}`] === true;
+      "if" in branch
+        ? !(run.staying && ran(branch.then)) && this.holds(branch.if, turn, run)
+        : understanding?.branches[`${run.id}/${step.id}/${index}`] === true;
     const index = (step.branches ?? []).findIndex(hit);
     if (index < 0) return;
     const branch = (step.branches ?? [])[index];
@@ -673,10 +737,60 @@ export class Runner<C = unknown, D = unknown> {
 
   async advance(turn: Turn<C, D>): Promise<TalkRequest<C, D> | IdleRequest<C, D> | null> {
     if (turn.ignored) return null;
-    this.resumeSuspended(turn);
+    this.resume(turn);
     turn.queue = [...turn.session.runs];
     await this.drain(turn);
-    return this.speaker(turn);
+    // An asker that moved on without a word hands the message to the run it suspended, and that one to the next.
+    // Each pass takes a run off the suspended stack, so the stack's size bounds the loop.
+    for (let left = turn.session.runs.length; left > 0; left--) {
+      if (turn.what.kind !== "message" || turn.silenced !== undefined || turn.talk || turn.spokeBy.size > 0) break;
+      const resumed = this.resume(turn);
+      if (!resumed) break;
+      turn.queue.push(resumed);
+      await this.drain(turn);
+    }
+    const speaker = this.speaker(turn);
+    if (!speaker || "idle" in speaker || !this.fixedDue(speaker)) return speaker;
+    // A question the lead asked gets its answer first: the step speaks, and its fixed question follows in settle.
+    // Unjudged counts as asked, and so does the retry of a failed answer: a question sent over the lead's own drops it.
+    const answerFirst = turn.what.kind === "message" ? turn.asks !== false : this.retrying(speaker);
+    if (answerFirst && speaker.step.question !== undefined) {
+      speaker.fixedAfter = render(speaker.step.question, this.scope(turn, speaker.run));
+      return speaker;
+    }
+    this.askFixed(turn, speaker);
+    turn.talk = undefined;
+    return null;
+  }
+
+  /** The step failed at the provider and runs again on its retry wake: deferTalk left `deferred` as its last line. */
+  private retrying({ run, step }: TalkRequest<C, D>): boolean {
+    const last = run.outcomes.at(-1);
+    return last?.status === "deferred" && last.stepId === step.id;
+  }
+
+  /**
+   * The step's fixed question is due: this is its first ask, with every field it collects still unknown and none asked
+   * yet, and the run is not staying (a staying run answers the lead). Otherwise the AI phrases the ask.
+   */
+  private fixedDue({ run, step, pending }: TalkRequest<C, D>): boolean {
+    const { question, collect = [] } = step;
+    if (question === undefined || run.staying) return false;
+    return pending.length === collect.length && pending.every((field) => (run.asked[field] ?? 0) === 0);
+  }
+
+  /** Send the step's fixed question when it is due. It counts as one ask of each field. */
+  private askFixed(turn: Turn<C, D>, talk: TalkRequest<C, D>): boolean {
+    const { run, step, pending } = talk;
+    if (!this.fixedDue(talk) || step.question === undefined) return false;
+    const key = this.stepKey(run, step);
+    turn.messages.push({ text: render(step.question, this.scope(turn, run)), kind: "verbatim", afterMs: turn.afterMs, key, runId: run.id, stepId: step.id });
+    turn.afterMs = 0;
+    turn.spokeBy.add(run.id);
+    turn.spoke = true;
+    for (const field of pending) run.asked[field] = (run.asked[field] ?? 0) + 1;
+    this.outcome(turn, run, { kind: "collect", status: "ok", key, code: "asked-fixed", stepId: step.id });
+    return true;
   }
 
   /**
@@ -700,12 +814,14 @@ export class Runner<C = unknown, D = unknown> {
     const instructions = [...(this.options.instructions ?? []), ...own.instructions].filter((ins) => !ins.if || evaluate(ins.if, ctx, conditions));
     const all = this.options.tools ?? [];
     const allowed = own.tools;
+    const retry = !("idle" in talk) && this.retrying(talk);
     return {
       talk,
-      input: turn.what.kind === "message" ? { kind: turn.kind, text: turn.what.text } : { kind: turn.kind },
+      input: turn.what.kind === "message" ? { kind: turn.kind, text: turn.what.text } : { kind: turn.kind, ...(retry ? { retry } : {}) },
       context: turn.context,
       data: turn.session.data,
       history: this.historyOf(turn),
+      said: [...turn.messages],
       now: turn.now,
       instructions,
       tools: allowed ? all.filter((tool) => allowed.includes(tool.id)) : all,
@@ -746,6 +862,11 @@ export class Runner<C = unknown, D = unknown> {
       return;
     }
     if (!this.premiseHolds(turn, run, flow)) return;
+    // The flow was edited off 'stay' after this run finished its steps: its new `onEnd` decides now.
+    if (run.staying && flow.onEnd !== "stay") {
+      this.finishFlow(turn, run, flow);
+      return;
+    }
     const resuming = run.status === "asking";
     run.status = "running";
     if (run.stepId === null) {
@@ -788,6 +909,12 @@ export class Runner<C = unknown, D = unknown> {
     return ok;
   }
 
+  /** `silenced: { skip: true }`: the message this step would send is dropped, and the run takes `then` as if it had gone out. */
+  private skipSilenced(turn: Turn<C, D>, run: Run, flow: Flow<C, D>, step: Step<C, D>, kind: StepOutcomeKind): void {
+    this.outcome(turn, run, { kind, status: "skipped", key: this.stepKey(run, step), code: "silenced", detail: turn.silenced, next: nextLabel(step.then) });
+    this.follow(turn, run, flow, step, step.then);
+  }
+
   private async execute(turn: Turn<C, D>, run: Run, flow: Flow<C, D>, step: Step<C, D>, resuming: boolean): Promise<void> {
     const data: Record<string, unknown> = turn.session.data;
     const key = this.stepKey(run, step);
@@ -797,7 +924,9 @@ export class Runner<C = unknown, D = unknown> {
       let pending: string[] = [];
       if (step.collect?.length) {
         pending = pendingFields(step, data, run.asked);
-        if (!pending.length) {
+        // A `stay` run answers even with nothing left to collect: answering is what it stays for. It only runs on a message
+        // (asking runs sit out wakes and events), and on a silenced one the check below keeps it asking.
+        if (!pending.length && !run.staying) {
           this.reportMaxAsks(turn, run, step);
           this.outcome(turn, run, resuming
             ? { kind, status: "ok", key, next: nextLabel(step.then) }
@@ -808,6 +937,7 @@ export class Runner<C = unknown, D = unknown> {
       }
       if (turn.silenced !== undefined) {
         if (resuming) run.status = "asking"; // the gate is closed; it speaks when the gate opens
+        else if (turn.skipSilenced) this.skipSilenced(turn, run, flow, step, kind);
         else this.endRun(turn, run, "skipped", "silenced", kind, turn.silenced);
         return;
       }
@@ -818,13 +948,16 @@ export class Runner<C = unknown, D = unknown> {
         }
       }
       run.status = "asking";
+      // Reached after Speak (settle's drain), a talk step waits for the next message; a fixed question costs no call, so it goes out now, as a say would.
       if (!turn.speakDone) turn.talk = { run, flow, step, pending };
+      else this.askFixed(turn, { run, flow, step, pending });
       return;
     }
 
     if (isSay(step)) {
       if (turn.silenced !== undefined) {
-        this.endRun(turn, run, "skipped", "silenced", "say", turn.silenced);
+        if (turn.skipSilenced) this.skipSilenced(turn, run, flow, step, "say");
+        else this.endRun(turn, run, "skipped", "silenced", "say", turn.silenced);
         return;
       }
       if (step.once) {
@@ -870,6 +1003,13 @@ export class Runner<C = unknown, D = unknown> {
           result = { failed: error instanceof Error ? error.message : String(error) };
         }
       }
+      // The handler already ran, so a defer that cannot be parsed must not throw
+      // the turn: every replay would repeat the side effect and fail again.
+      if ("defer" in result && !isDuration(String(result.defer))) {
+        result = {
+          failed: `action "${step.do}" asked to defer by "${String(result.defer)}", which is not a duration. Use a value like "2m" or "1h".`,
+        };
+      }
       if ("ok" in result) {
         if (result.spoke) {
           turn.spokeBy.add(run.id);
@@ -959,18 +1099,22 @@ export class Runner<C = unknown, D = unknown> {
     }
     if ("step" in target) {
       const data: Record<string, unknown> = turn.session.data;
-      for (const field of target.clear ?? []) delete data[field];
+      // Forgetting a field means asking for it from scratch: its ask count goes too, so a fixed question goes out again.
+      for (const field of target.clear ?? []) {
+        delete data[field];
+        delete run.asked[field];
+      }
       this.jump(turn, run, flow, target.step);
       return;
     }
     const childId = render(target.flow, this.scope(turn, run));
     const key = this.stepKey(run, step);
     this.endRun(turn, run, "flow");
-    this.chain(turn, childId, key, target.input ?? run.input, run.hop + 1);
+    this.chain(turn, run, childId, key, target.input ?? run.input, run.hop + 1);
   }
 
-  /** Start a child flow that holds the floor and moves in this same phase. */
-  private chain(turn: Turn<C, D>, flowId: string, key: string, input: unknown, hop: number, keepData = false): void {
+  /** Start a child flow that moves in this same phase. It inherits the floor when its parent held it, or when nobody did. */
+  private chain(turn: Turn<C, D>, parent: Run, flowId: string, key: string, input: unknown, hop: number, keepData = false): void {
     const child = this.flows.get(flowId);
     if (!child) {
       turn.skipped.push({ flowId, anchor: turn.session.id, triggerKey: key, code: "flow-gone", message: OUTCOME_MESSAGES["flow-gone"] });
@@ -978,8 +1122,10 @@ export class Runner<C = unknown, D = unknown> {
     }
     const run = this.startRun(turn, child, "flow", key, { payload: input, hop, keepData });
     if (!run) return;
-    turn.floorRunId = run.id;
-    if (turn.ingesting) turn.floorFromIngest = true;
+    if (turn.floorRunId === undefined || turn.floorRunId === parent.id) {
+      turn.floorRunId = run.id;
+      if (turn.ingesting) turn.floorFromIngest = true;
+    }
     turn.queue.push(run);
   }
 
@@ -994,15 +1140,55 @@ export class Runner<C = unknown, D = unknown> {
     run.visits[stepId] = (run.visits[stepId] ?? 0) + 1;
     run.status = "running";
     delete run.waiting;
+    delete run.staying;
+  }
+
+  /** `onEnd: 'stay'`: the run sits on its last talk step and answers every message from there, each answer a new visit and so a new key. */
+  private stayAt(run: Run, step: Step<C, D>): void {
+    this.enter(run, step.id);
+    run.staying = true;
+    run.status = "asking";
+  }
+
+  /**
+   * Where `stay` answers from: the talk step this run last took, so a branched flow stays on its own path. The flow's last talk step when the log names none.
+   * ponytail: read back from `run.outcomes`, which keeps 50 lines; a tail of 50+ lines after the talk step (a long polling loop) loses it and the run
+   * stays on the flow's last talk step. Upgrade: record the talk step on the run when it talks.
+   */
+  private stayStep(run: Run, flow: Flow<C, D>): TalkOf<C, D> | undefined {
+    for (let i = run.outcomes.length - 1; i >= 0; i--) {
+      const { kind, stepId } = run.outcomes[i];
+      const step = kind === "prompt" || kind === "collect" ? this.stepOf(flow, stepId ?? null) : undefined;
+      if (step && isTalk(step)) return step;
+    }
+    return [...flow.steps].reverse().find(isTalk);
   }
 
   private finishFlow(turn: Turn<C, D>, run: Run, flow: Flow<C, D>): void {
     const onEnd = flow.onEnd ?? "end";
     const last = flow.steps[flow.steps.length - 1];
-    if (onEnd === "stay" && last) {
-      // "repete o último passo": the run stays live at its last step, re-entered so the repetition mints a new key, and runs it on the next message.
-      this.enter(run, last.id);
-      run.status = "asking";
+    const stay = onEnd === "stay" ? this.stayStep(run, flow) : undefined;
+    if (stay) {
+      // The steps after it ran once, on the way here; staying, it only answers.
+      this.stayAt(run, stay);
+      // One asker at a time. A run the lead's message went to holds the conversation and suspends the other asker;
+      // any other run waits behind that asker and resumes when it is done.
+      const others = turn.session.runs.filter((r) => r !== run && r.status === "asking");
+      if (others.length && !(turn.what.kind === "message" && turn.floorRunId === run.id)) {
+        run.status = "suspended";
+        run.suspendedAt = turn.nowIso;
+        return;
+      }
+      for (const other of others) {
+        other.status = "suspended";
+        other.suspendedAt = turn.nowIso;
+        if (turn.talk?.run === other) turn.talk = undefined;
+      }
+      // A message nothing has answered yet gets its answer now. Reached in Ingest, the run stays asking: Decide judges its
+      // branches as the asker's, and it answers when it moves.
+      if (!turn.ingesting && turn.what.kind === "message" && turn.silenced === undefined && !turn.speakDone && turn.spokeBy.size === 0) {
+        run.status = "running";
+      }
       return;
     }
     if (onEnd === "reset" && last) {
@@ -1010,7 +1196,7 @@ export class Runner<C = unknown, D = unknown> {
       // It is a chain into itself, so it costs a hop: a code-only flow that resets forever stops at the hop cap instead of spinning.
       const key = this.stepKey(run, last);
       this.endRun(turn, run, "reset");
-      this.chain(turn, flow.id, key, run.input, run.hop + 1, true);
+      this.chain(turn, run, flow.id, key, run.input, run.hop + 1, true);
       return;
     }
     this.endRun(turn, run, "end");
@@ -1033,9 +1219,20 @@ export class Runner<C = unknown, D = unknown> {
     turn.schedule.push({ key: waiting.key, at });
   }
 
+  /** `resumeSuspended`, and on a message the resumed run's `if` branches are judged before it speaks, as the asker's are in Decide. */
+  private resume(turn: Turn<C, D>): Run | undefined {
+    const run = this.resumeSuspended(turn);
+    if (run && turn.what.kind === "message") {
+      const flow = this.flows.get(run.flowId);
+      const step = flow && this.stepOf(flow, run.stepId);
+      if (flow && step && isTalk(step)) this.fireBranch(turn, run, flow, step, null);
+    }
+    return run;
+  }
+
   /** When nobody asks, the most recently suspended run returns to asking. */
-  private resumeSuspended(turn: Turn<C, D>): void {
-    if (this.asker(turn)) return;
+  private resumeSuspended(turn: Turn<C, D>): Run | undefined {
+    if (this.asker(turn)) return undefined;
     const suspendedAt = (r: Run): string => r.suspendedAt ?? r.startedAt;
     const next = turn.session.runs
       .filter((r) => r.status === "suspended")
@@ -1044,6 +1241,7 @@ export class Runner<C = unknown, D = unknown> {
       next.status = "asking";
       delete next.suspendedAt;
     }
+    return next;
   }
 
   // ── Settle: the one applier after Speak (design §4.7) ─────────────────
@@ -1093,15 +1291,30 @@ export class Runner<C = unknown, D = unknown> {
     Object.assign(turn.session.data, spoken.data);
     this.outcome(turn, run, { kind: talkKind(step), status: "ok", key, llmCalls: spoken.llmCalls, stepId: step.id });
     if (!turn.session.runs.includes(run)) return;
-    if (step.collect?.length) {
-      const pending = pendingFields(step, turn.session.data, run.asked);
-      if (pending.length) {
-        for (const field of pending) run.asked[field] = (run.asked[field] ?? 0) + 1;
+    const pending = step.collect?.length ? pendingFields(step, turn.session.data, run.asked) : [];
+    if (talk.fixedAfter !== undefined) {
+      // The reply only answered the lead; the step's own question goes out after it and counts the ask.
+      if (this.askFixed(turn, { run, flow, step, pending })) {
         run.status = "asking";
         return;
       }
-      this.reportMaxAsks(turn, run, step);
+    } else {
+      for (const field of pending) run.asked[field] = (run.asked[field] ?? 0) + 1;
+    }
+    if (run.staying) {
+      // Each answer is a new visit, so a new key, even while a field is still pending; that field's max-asks is reported once, when it gets there.
+      const maxAsks = step.maxAsks ?? DEFAULT_MAX_ASKS;
+      for (const field of pending) {
+        if (run.asked[field] === maxAsks) this.outcome(turn, run, { kind: "collect", status: "skipped", key, code: "max-asks", detail: field });
+      }
+      this.stayAt(run, step);
+      return;
+    }
+    if (pending.length) {
+      run.status = "asking";
+      return;
     }
+    this.reportMaxAsks(turn, run, step);
     run.status = "running";
     this.follow(turn, run, flow, step, step.then);
     if (turn.session.runs.includes(run) && run.status === "running") turn.queue.push(run);
@@ -1139,14 +1352,21 @@ export class Runner<C = unknown, D = unknown> {
     return new Date(reset !== undefined && reset > ladder ? reset : ladder);
   }
 
-  /** The assistant spoke last: every silence flow passing `if` and `repeat` gets a wake. */
+  /** The assistant spoke this turn: its silence wakes replace the ones its last words set. */
   private armSilence(turn: Turn<C, D>): void {
+    const previous = turn.original?.lastAssistantAt;
+    if (turn.session.lastAssistantAt === previous) return;
+    turn.schedule.push(...this.silenceWakes(turn, previous));
+  }
+
+  /** The assistant spoke last: every silence flow passing `if` and `repeat` gets a wake. */
+  private silenceWakes(turn: Turn<C, D>, previous?: string): ScheduleEntry[] {
     const { session } = turn;
     const { lastAssistantAt, lastUserAt } = session;
-    if (!lastAssistantAt || lastAssistantAt === turn.original?.lastAssistantAt) return;
-    if (lastUserAt && Date.parse(lastUserAt) > Date.parse(lastAssistantAt)) return;
+    if (!lastAssistantAt) return [];
+    if (lastUserAt && Date.parse(lastUserAt) > Date.parse(lastAssistantAt)) return [];
     const ms = Date.parse(lastAssistantAt);
-    const previous = turn.original?.lastAssistantAt;
+    const wakes: ScheduleEntry[] = [];
     for (const flow of this.flows.values()) {
       const trigger = (flow.on ?? []).find((t): t is SilenceTrigger<C, D> => "silence" in t);
       if (!trigger) continue;
@@ -1154,12 +1374,13 @@ export class Runner<C = unknown, D = unknown> {
       if (trigger.if && !this.holds(trigger.if, turn, this.draftRun(turn, flow, "silence", key))) continue;
       if (!this.repeatAllows(turn, flow, trigger, key)) continue;
       const at = this.snap(turn, new Date(ms + parseDuration(trigger.silence)), trigger.businessHours);
-      turn.schedule.push({
+      wakes.push({
         key: `silence:${flow.id}:${session.id}:${ms}`,
         at,
         ...(previous ? { replaces: `silence:${flow.id}:${session.id}:${Date.parse(previous)}` } : {}),
       });
     }
+    return wakes;
   }
 
   // ── Return (design §4.8) ──────────────────────────────────────────────