@jr2/orchestrator 0.2.1 → 0.4.1

package/src/actor.ts

@@ -4,13 +4,13 @@
 //   1. REGISTERS the invocation's event surface: `tools` names are resolved against the
 //      INVOKING MACHINE's vocabulary (per-Machine scoping — an unlisted name fails at invoke time)
 //      and registered in the host's table under the instance's agent address, with a deliver
-//      closure over THIS invocation's `sendBack`. The Agent's domain tool calls arrive from its
-//      Adapter (`/agents/<iid>/events` — ADR-0013), are validated by the table, and land on the
+//      closure over THIS invocation's `sendBack`. The Agent's domain tool calls arrive through its
+//      pod's Custodian (`/agents/<iid>/events` — ADR-0013), are validated by the table, and land on the
 //      state that invoked the agent — at any nesting depth, no routing, no `instanceId` on
 //      domain events (the closure IS the provenance). `/agents/<iid>/surface` serves exactly
-//      this registration, so menus are state-scoped by lifecycle (ADR-0006's dynamic
-//      advertisement, for free — and, per ADR-0013, with no `list_changed` needed: the
-//      Harness re-lists per Submission).
+//      this registration: the Agent's Menu, fixed for the conversation, and the Allowed picks,
+//      state-scoped by lifecycle (ADR-0029 — with no `list_changed` needed, per ADR-0013: the
+//      Harness re-reads per Submission).
 //
 //   2. ADMITS the run over the Harness at `input.endpoint` — the port is constructed
 //      per-invocation from serializable input (ADR-0007/0011 doctrine), and a dev stub is just
@@ -51,8 +51,13 @@ import {
   type WorkspaceAccess,
 } from "./agent.ts";
 import { ambientHandlesFor, type AmbientHandles } from "./ambient.ts";
+import type { HarnessRestarts, MemoryKill } from "./workspace.ts";
 import { INSTANCE_HARNESS_SERVICE } from "./names.ts";
-import { agentAddress, continuedIid, resolveAccepts, runBindingOf } from "./registration.ts";
+import { SENDER_KEY } from "@jr2/agent-protocol";
+import { agentAddress, continuedIid, allowedPicks, resolveAccepts, runBindingOf } from "./registration.ts";
+import type { NoticeScope } from "./notices.ts";
+import { restOf } from "./rest.ts";
+import { SUBMISSION_HARNESS_RESTARTED, SUBMISSION_RUNAWAY, type Notice } from "./wire.ts";
 
 /**
  * One admitted Submission — the durable re-attach handle (ADR-0016). The wire fields are
@@ -75,6 +80,21 @@ export type AgentAdmission = {
    * aborts the LIVE conversation, never the dead original the ledger is keyed by.
    */
   instanceId?: string;
+  /**
+   * The Harness container's restart count when this admission was answered (ADR-0021) — stamped by
+   * the ACTOR, for a Turn in a Sandbox Workspace whose watch had spoken. A count above it means
+   * the process holding the conversation died; a restore holds the re-attached Turn to the same
+   * mark.
+   */
+  harnessRestarts?: number;
+  /**
+   * The Agent and the Harness base URL this admission was answered by — stamped by the ACTOR at
+   * ledger time, like `instanceId`. Together with `instanceId` they name the conversation on its
+   * Harness, which is what the live set is built from (ADR-0031): the host states the Instance
+   * Harness's live conversations from these ledger entries alone.
+   */
+  agent?: string;
+  endpoint?: string;
 };
 
 /**
@@ -131,7 +151,8 @@ export type AgentTurnInput = {
    * share a conversation (the name is in the id), and two Pool children never collide (each
    * worker is its own Machine instance). A conversation jr2 has faulted is never continued: the
    * next `continue` lands on a virgin one (ADR-0035, ADR-0057) — and re-briefing that Turn is the
-   * author's, because jr2 cannot write that prompt.
+   * author's, because jr2 cannot write that prompt. A Harness restart is the exception: it cut the
+   * Turn, and the rebuilt Harness holds the conversation (ADR-0031).
    */
   continue?: true;
 };
@@ -150,7 +171,7 @@ export type AgentTurnInput = {
 export type AgentTurnPlacement = {
   /** The Harness base URL this Turn is admitted over. */
   endpoint?: string;
-  /** The Sandbox whose Adapter token may deliver this Turn's picks (ADR-0013). */
+  /** The Sandbox whose token (held by that pod's Custodian) may deliver this Turn's picks (ADR-0013). */
   sandbox?: string;
 };
 
@@ -202,8 +223,16 @@ export type AgentRunInput = {
    *     fresh invocation, which already mints its own conversation.
    */
   continuation?: boolean;
-  /** Event names (from the invoking Machine's vocabulary) this invocation accepts over MCP. */
+  /** Event names (from the invoking Machine's vocabulary) this invocation accepts: the invoking
+   * state's derived set, which delivery validates against and the Allowed picks narrow. */
   tools: readonly string[];
+  /**
+   * The Agent's MENU (ADR-0029): the union of `tools` over every state of this Machine that invokes
+   * an Agent of this name, in a fixed order — what the surface serves as the tools block, the same
+   * for every Turn of the conversation. `jr2Setup` always sets it; absent (a plain `setup()`
+   * machine passing finalized input), `tools` is the Menu.
+   */
+  menu?: readonly string[];
 };
 
 /** Telemetry sent up when the run is out of options: the Submission settled failed/aborted
@@ -240,7 +269,14 @@ export interface AgentRunPort {
    * Follow an admitted submission until it settles. Resolving means the submission completed;
    * rejecting means it settled failed/aborted (or the conversation is gone).
    */
-  settle(admission: AgentAdmission, opts?: { signal?: AbortSignal }): Promise<void>;
+  settle(admission: AgentAdmission, opts?: AgentSettleOptions): Promise<void>;
+  /**
+   * Does the Harness still hold this conversation (ADR-0062)? Asked before a continued Turn whose
+   * conversation was admitted before: a Harness that restarted between the Turns lost it with no
+   * fault to say so, and the Turn is told its conversation is new. Answers `true` whenever it
+   * cannot tell — unknown is never loss.
+   */
+  holds(agentName: string, instanceId: string, opts?: { signal?: AbortSignal }): Promise<boolean>;
   /**
    * End the instance's in-flight (and queued) work — the turn is over (ADR-0024). Resolving means
    * the intent is RECORDED, not that the submission has settled; jr2 never observes that outcome,
@@ -255,7 +291,25 @@ export interface AgentRunPort {
  * plus the local abandon signal. Not part of {@link AgentRunInput} on purpose — that shape is
  * PERSISTED as the child's input, and a definition frozen into a snapshot would outlive the
  * Machine edit that changed it. */
-export type AgentAdmitOptions = { definition: AgentDefinition; signal?: AbortSignal };
+export type AgentAdmitOptions = {
+  definition: AgentDefinition;
+  signal?: AbortSignal;
+  /** The pending notices in this admission's scope (ADR-0062), for the Briefing's Turn part. Not
+   * on the persisted input either: they are the Orchestrator's, and delivered once. */
+  notices?: Notice[];
+};
+
+/** A memory kill by the Harness's own guard (ADR-0061, layer 4), as the updates stream reports it:
+ * the guard's `peak` and `limit`, and `source` — where on which conversation's stream the event
+ * sits, so a replayed read of it is the same kill. */
+export type GuardKill = { peak: string; limit: string; source: string };
+
+/** What following a settlement may be told beside the settlement itself. */
+export type AgentSettleOptions = {
+  signal?: AbortSignal;
+  /** The Harness's guard killed the Agent's processes during this Submission (ADR-0061). */
+  onMemoryLimit?: (kill: GuardKill) => void;
+};
 
 /** Build a port for one invocation from its serializable input (ADR-0011 static-import doctrine),
  * plus the Harness bearer for the placement that input resolved to (ADR-0058) — absent where no
@@ -285,26 +339,93 @@ export type AgentRunOptions = {
 
 /**
  * The runaway settlement class (ADR-0035), read STRUCTURALLY off a settle rejection: the wire
- * client's `SettlementFault` carries the Settlement, but this module is wire-free (see header),
- * so the literal is restated (`SUBMISSION_RUNAWAY` in `./wire.ts`) and the shape
- * duck-typed. A lost conversation (404) carries no settlement, so it stays terminal like every
- * other class.
+ * client's `SettlementFault` carries the Settlement, but this module never loads the wire client
+ * (see header), so the shape is duck-typed. The literal is the wire's own `SUBMISSION_RUNAWAY` —
+ * `./wire.ts` is shapes and constants, nothing a test load path pays for — and wire-types.test.ts
+ * holds it to the Harness's. A lost conversation (404) carries no settlement, so it stays
+ * terminal like every other class.
  */
 function runawayReason(err: unknown): string | undefined {
   if (typeof err !== "object" || err === null) return undefined;
   const error = (err as { settlement?: { error?: { type?: string; message?: string } } }).settlement?.error;
-  return error?.type === "runaway" ? (error.message ?? "runaway") : undefined;
+  return error?.type === SUBMISSION_RUNAWAY ? (error.message ?? SUBMISSION_RUNAWAY) : undefined;
 }
 
-/** The forced-final-pick re-prompt (ADR-0006, absorbed here by ADR-0016). */
-function nudgePrompt(tools: readonly string[]): string {
-  return (
-    `Your previous turn ended without calling one of the required workflow tools. ` +
-    `You MUST end your turn by calling exactly one of: ${tools.join(", ")}. ` +
-    `Pick the one that matches the true state of your work and call it now.`
-  );
+/** The Harness's fixed prefix for a provider that refused the load (ADR-0064), restated like the
+ * runaway literal: `PROVIDER_LIMIT` in `@jr2/harness`. */
+const PROVIDER_LIMIT = "provider limit";
+
+/**
+ * A provider limit (ADR-0064), read STRUCTURALLY like {@link runawayReason}: the Settlement's own
+ * message, unwrapped, so the fault reason STARTS with the fixed prefix — as a memory kill's does
+ * (ADR-0061) — and the Machine and `jr2 status` can key on it.
+ */
+function providerLimitReason(err: unknown): string | undefined {
+  if (typeof err !== "object" || err === null) return undefined;
+  const message = (err as { settlement?: { error?: { message?: unknown } } }).settlement?.error?.message;
+  return typeof message === "string" && message.startsWith(PROVIDER_LIMIT) ? message : undefined;
+}
+
+/** The kubelet's reason for a container the kernel killed at its memory limit (ADR-0061). */
+const OOM_KILLED = "OOMKilled";
+
+/** Why a Turn failed when its Harness restarted under it (ADR-0021), in the kubelet's words. */
+function harnessRestartReason(seen: HarnessRestarts): string {
+  const last = seen.lastTerminated;
+  return `Turn lost (Harness restarted: ${last?.reason ?? "unknown"}, exit ${last?.exitCode ?? "?"})`;
+}
+
+/**
+ * A Submission the Harness settled `failed` because it restarted under it (ADR-0031): the rebuilt
+ * stream says so, so the Orchestrator reads a Settlement, not a 404. Read STRUCTURALLY off the
+ * Settlement's typed error, like {@link runawayReason} — the wire's `SUBMISSION_HARNESS_RESTARTED`,
+ * held to the Harness's by wire-types.test.ts — and the message is only what the fault quotes.
+ * It can reach the actor BEFORE the watch's restart count does, and it is the only restart signal
+ * an Instance Harness gives — the watch does not see that pod.
+ */
+function settledByRestart(err: unknown): string | undefined {
+  if (typeof err !== "object" || err === null) return undefined;
+  const settlement = (err as { settlement?: { outcome?: unknown; error?: { type?: unknown; message?: unknown } } })
+    .settlement;
+  if (settlement?.outcome !== "failed" || settlement.error?.type !== SUBMISSION_HARNESS_RESTARTED) return undefined;
+  const message = settlement.error.message;
+  return typeof message === "string" ? message : "Harness restarted";
 }
 
+const errorMessage = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/**
+ * A lost conversation (ADR-0027), read STRUCTURALLY like {@link runawayReason}: the wire client's
+ * `SettlementFault` marks a 404 `lost`, and this module is wire-free. The one fault class a
+ * memory kill can hide behind (ADR-0061).
+ */
+function isLostConversation(err: unknown): boolean {
+  return typeof err === "object" && err !== null && (err as { lost?: unknown }).lost === true;
+}
+
+/**
+ * The nudge (ADR-0006, absorbed here by ADR-0016). It names no picks: the Harness writes the Turn
+ * part after it, stating the Allowed picks in the model's own tool names and narrowed by the guards
+ * (ADR-0029, ADR-0062) — a list here would be a second one, in other names, that a closed guard
+ * makes wrong. Its first sentence stays true after a pick that left the Turn open, and for the
+ * wake: the ask-again rule asks whenever picks are allowed after a settle, picked or not, at once
+ * or when they open.
+ */
+const NUDGE_PROMPT =
+  `Your previous turn ended, and the workflow is still waiting for your pick. ` +
+  `You MUST end your turn by calling exactly one of the workflow tools allowed below. ` +
+  `Pick the one that matches the true state of your work and call it now.`;
+
+/**
+ * The re-admission after a Harness restart cut the Turn while the workflow was busy (ADR-0031). The
+ * Harness writes a cut call's history result itself ("its result comes in the next message") and the
+ * answer rides this admission as a `pick-answer` notice in the Briefing's Turn part, with the Allowed
+ * picks after it; this prompt says only what happened to the Turn.
+ */
+const READMIT_PROMPT =
+  `Your previous turn was cut: the process that ran you restarted while the workflow was busy. ` +
+  `The workflow did not stop. Continue your task from here.`;
+
 /**
  * Where this Turn works — the Frame's other half (ADR-0057), resolved before admission.
  *
@@ -435,7 +556,7 @@ export function agentActorWith(
       }
       endpoint = binding.instanceHarness;
       // The registration records the PLACEMENT's name as its delivery scope — ADR-0013's
-      // doctrine, extended to the second placement: the Instance Harness Adapter bears a token
+      // doctrine, extended to the second placement: the Instance Harness's Custodian holds a token
       // signed for this name (deploy.ts), so it may speak for the Turns hosted there and for no
       // Workspace's. The Instance token still may (it is the operator, tokens.ts).
       sandbox = INSTANCE_HARNESS_SERVICE;
@@ -460,8 +581,10 @@ export function agentActorWith(
     // Register this invocation's event surface (throws on a name outside the INVOKING MACHINE's
     // vocabulary — ADR-0011's invoke-time check, scoped to `self._parent.logic` because names are
     // per-Machine — which errors the run loudly at the invoking state).
-    // `signaled` is the no-signal detector: a delivered menu event means the Agent ended its
-    // turn the intended way, so a completed settlement needs no nudge. ONE invocation can hold
+    // `signaled`: a Menu pick was delivered in this invocation. It closes the runaway REROLL gate
+    // (below): replaying the identical prompt would deliver it again. It does not decide the nudge
+    // — the ask-again rule does, from the Allowed picks after the settle, because a delivered pick
+    // may leave the Turn open (a mode change, a pick with no target). ONE invocation can hold
     // more than one surface: a runaway reroll (ADR-0035) is a fresh conversation whose menu
     // dials `/mcp/<derived iid>`, so its address must be live too — same defs, same deliver,
     // because whichever conversation answers, it answers THIS invocation.
@@ -473,7 +596,17 @@ export function agentActorWith(
     // already ended.
     let currentIid = input.attach?.instanceId ?? instanceId;
     const defs = resolveAccepts(self, input.tools);
+    // The Menu (ADR-0029): resolved against the same vocabulary, and served as the tools block.
+    const menu = resolveAccepts(self, input.menu ?? input.tools);
     const disposers: Array<() => void> = [];
+    // Who this Turn's picks are from (ADR-0015): the slot, written on every event it delivers; and
+    // the invoke id that finds its state in the Machine. Both static, so a restore recomputes them.
+    const seat = { sender: { party: "agent", id: input.agentName } as const, invokeId: self.id };
+    // This Agent's continued conversation in this Machine (ADR-0057) — the base id the epoch ledger
+    // burns. This Turn is PART of it only when it continues it: a fresh Turn is new by definition.
+    const conversation = continuedIid(self._parent, binding.runId, input.agentName);
+    // The iids whose surface the Harness has read (see `carried` below).
+    const served = new Set<string>();
     const registerSurface = (iid: string) =>
       disposers.push(
         binding.table.register({
@@ -482,13 +615,15 @@ export function agentActorWith(
           kind: "agent",
           id: iid,
           defs,
+          menu,
           sandbox,
           deliver: (event) => {
             signaled = true;
             // The settlement-pick marker (ADR-0023), BEFORE the delivery moves the Machine: the pick
             // must land on the feed ahead of the status delta it causes, or the narrative reads
-            // effect-then-cause.
-            const { type, ...payload } = event;
+            // effect-then-cause. The sender is the Orchestrator's field, not the pick's payload: the
+            // printed conversation shows what the Agent picked, nothing more.
+            const { type, [SENDER_KEY]: _sender, ...payload } = event;
             binding.marker?.({
               kind: "pick",
               agent: input.agentName,
@@ -498,27 +633,145 @@ export function agentActorWith(
             });
             sendBack(event);
           },
+          // The Harness read this Turn's surface: it has the Turn in hand, and prompts it.
+          served: () => served.add(iid),
           // The state that invoked us — the machine the menu derived from, so the only one whose
           // guards can say whether a pick would move anything (ADR-0029). Same `_parent` the ambient
           // walk above uses; structural, so a sibling's snapshot is unreachable.
           invoker: self._parent,
+          ...seat,
+          // Where a pick's answer goes when its route leaves the Agent's state (ADR-0024): the
+          // conversation this Turn continues, and none for a fresh Turn — no later Turn heard it.
+          ...(input.continuation ? { conversation } : {}),
         }),
       );
     registerSurface(currentIid);
 
     // The Harness bearer (ADR-0058) is derived from the SAME name the registration records as its
-    // delivery scope: the pod hosting this Turn. One name, both directions — the Adapter there may
+    // delivery scope: the pod hosting this Turn. One name, both directions — the Custodian there may
     // speak for these picks, and only this bearer may drive the conversation there.
     const client = portFactory(endpoint, sandbox === undefined ? undefined : binding.harnessBearer?.(sandbox));
-    const controller = new AbortController();
+    // When this Turn started: a memory kill that ended the Harness before it is not this Turn's
+    // (ADR-0061). Undefined from a backend that cannot see the container — and never throws:
+    // naming the fault is a courtesy, the fault itself lands either way.
+    const turnStarted = new Date();
+    const memoryFault = (name: string): Promise<MemoryKill | undefined> =>
+      binding.sandbox?.memoryFault(name, turnStarted).catch(() => undefined) ?? Promise.resolve(undefined);
+    // Replaced after a Harness restart that cut the Turn while its state was busy: the cut aborted it.
+    let controller = new AbortController();
+
     // Shared per run, created on demand so the ordering guarantee holds for any binding.
     const pendingAborts = (binding.pendingAborts ??= new Map<string, Promise<void>>());
     let stopped = false;
+
+    // A Harness restart ends its Turns (ADR-0021): the Submission it held is cut (ADR-0031 keeps
+    // the conversation, not the Turn), and a Harness that crash-loops only ever refuses
+    // connections, so `wait` would reconnect forever. The watch sees the restart count pass its value at this Turn's
+    // admission, and the Turn fails at once — not its Workspace: the pod and `/work` survive.
+    // Sandbox Workspaces only: the Instance Harness is a StatefulSet the watch does not see, and
+    // its rebuilt stream settles the Turn `failed` instead (ADR-0031, `settledByRestart`).
+    let heardRestarts: HarnessRestarts | undefined;
+    let restartMark = input.attach?.harnessRestarts;
+    let restarted: HarnessRestarts | undefined;
+    // Whether a Harness has answered an admission of this Turn — before that there is nothing to
+    // lose, and nothing to hold a restart count against.
+    let admitted = input.attach !== undefined;
+    if (workspace !== "none" && sandbox !== undefined && binding.sandbox !== undefined) {
+      disposers.push(
+        binding.sandbox.harnessRestarts(sandbox, (seen) => {
+          heardRestarts = seen;
+          if (stopped || restarted !== undefined || !admitted) return;
+          if (restartMark === undefined) {
+            restartMark = seen.restartCount;
+            return;
+          }
+          if (seen.restartCount > restartMark) {
+            restarted = seen;
+            controller.abort(new Error("the Harness restarted"));
+          }
+        }),
+      );
+    }
     // Ledgered under the ORIGINAL iid — the persisted input's key, like a nudge's — with the
     // LIVE conversation stamped on the record, so a restore settle-follows the live submission
-    // AND re-addresses it (see `currentIid` above).
-    const ledger = (admission: AgentAdmission) =>
-      binding.recordAdmission?.(instanceId, { ...admission, instanceId: currentIid });
+    // AND re-addresses it (see `currentIid` above). The notices the admission carried are
+    // delivered by this same write (ADR-0062).
+    const ledger = (admission: AgentAdmission, delivered: readonly string[]) =>
+      binding.recordAdmission?.(
+        instanceId,
+        { ...admission, instanceId: currentIid, agent: input.agentName, endpoint },
+        delivered,
+      );
+
+    // Where this Turn hears notices (ADR-0062). Its continued conversation's — the base id the
+    // epoch ledger burns — only when it CONTINUES one: a fresh Turn is new by definition, and the
+    // notice waits for the `continue` whose context is gone. Its Workspace's only when it works in
+    // one: a Menu-only Agent hears conversation notices alone.
+    const noticeWorkspace = workspace !== "none" ? sandbox : undefined;
+    const noticeScope: NoticeScope = {
+      ...(input.continuation ? { conversation } : {}),
+      ...(noticeWorkspace !== undefined ? { workspace: noticeWorkspace } : {}),
+    };
+    const memoryLimit = (limit: string, peak?: string): Notice => ({
+      kind: "memory-limit",
+      scope: "workspace",
+      agent: input.agentName,
+      ...(peak === undefined ? {} : { peak }),
+      limit,
+    });
+    // The Harness's guard killed this Workspace's processes during the Turn (ADR-0061, layer 4):
+    // the Agent heard it in its `bash` answer; the next Turn in the Workspace hears it here.
+    const onMemoryLimit = (kill: GuardKill): void => {
+      if (noticeWorkspace === undefined) return;
+      binding.raiseNotice?.(memoryLimit(kill.limit, kill.peak), noticeWorkspace, kill.source);
+    };
+
+    // The Turn's admission and a reroll's carry the pending notices in scope — a reroll's
+    // conversation is fresh, and has heard nothing. A nudge's does not: it re-prompts the Turn
+    // within itself (ADR-0016), whose Agent read a guard kill in its own `bash` answer, and a notice
+    // spent there never reaches the next Turn in the Workspace it is for (ADR-0062). Reserved
+    // first, so no concurrent admission carries them too; delivered by the ledger write; released
+    // when the admission fails, for the next one to carry.
+    //
+    // What the last carrying admission took, and under which iid: delivered is not HEARD. If this
+    // actor ends the Turn before the Harness reads that iid's surface, the Harness finds the Turn
+    // over and settles it with no model asked (ADR-0026) — so `abandon` raises them again.
+    let carried: { iid: string; notices: Notice[] } | undefined;
+    const admitTurn = async (turn: AgentRunInput, opts: { notices: boolean; extra?: Notice[] } = { notices: true }) => {
+      const taken = (opts.notices ? binding.takeNotices?.(noticeScope) : undefined) ?? { ids: [], notices: [] };
+      // `extra`: a notice this admission carries straight from the actor, never kept — the answer a
+      // cut pick never got (ADR-0031), whose one road to the model is this admission.
+      const notices = [...taken.notices, ...(opts.extra ?? [])];
+      let admission: AgentAdmission;
+      try {
+        admission = await client.admit(turn, {
+          definition,
+          signal: controller.signal,
+          ...(notices.length ? { notices } : {}),
+        });
+      } catch (err) {
+        binding.releaseNotices?.(taken.ids);
+        throw err;
+      }
+      // The mark is taken once the Harness has ANSWERED: a restart before the answer took the
+      // admission with it, and the conversation's 404 says so; a restart after it is this Turn's.
+      // Unheard yet (the watch has not listed), the first count heard is the mark.
+      admitted = true;
+      restartMark = heardRestarts?.restartCount;
+      if (restartMark !== undefined) admission = { ...admission, harnessRestarts: restartMark };
+      ledger(admission, taken.ids);
+      if (taken.notices.length) carried = { iid: turn.instanceId, notices: taken.notices };
+      return admission;
+    };
+    // The notices an unheard admission carried, pending again for the next Turn in their scope.
+    const reraiseUnheard = (): void => {
+      if (carried === undefined || served.has(carried.iid)) return;
+      for (const notice of carried.notices) {
+        const to = notice.scope === "conversation" ? conversation : noticeWorkspace;
+        if (to !== undefined) binding.raiseNotice?.(notice, to);
+      }
+      carried = undefined;
+    };
 
     const abandon = () => {
       if (stopped) return;
@@ -531,6 +784,7 @@ export function agentActorWith(
       // Pool cancelling a child. The one exception is the host stopping the run for its own
       // reasons, which ADR-0007's restore re-attaches to.
       if (binding.hostStopping) return;
+      reraiseUnheard();
       // Fire-and-forget, and unreportable BY CONSTRUCTION: this actor is stopped, so there is no
       // `agent.fault` left to raise. An orphan that survives a failed abort 404s on every tool
       // call and settles on its own.
@@ -542,6 +796,125 @@ export function agentActorWith(
       });
     };
 
+    // The Allowed picks NOW (ADR-0029), read as the surface reads them: one list for the surface,
+    // the receipts, the nudge and the wake.
+    const allowedNow = (): string[] => allowedPicks({ defs, menu, invoker: self._parent, ...seat });
+    // Resolves with the Allowed picks the first time they are not empty — read a microtask after
+    // every snapshot of the invoking Machine, so a Gate's answer, an outside event, a settled child
+    // or a timer each count — or with `[]` once this actor stops. Never inside the subscriber: a
+    // snapshot between macrosteps (a state that sends to itself) is not Rest until the mailbox
+    // drains (rest.ts), and a wake with an empty list spends the nudge's budget for nothing. Its own
+    // disposer, so `abandon` ends the wait.
+    const picksOpen = (): Promise<string[]> =>
+      new Promise((resolve) => {
+        let done = false;
+        let sub: { unsubscribe(): void } | undefined;
+        const finish = (allowed: string[]): void => {
+          if (done) return;
+          done = true;
+          const at = disposers.indexOf(dispose);
+          if (at >= 0) disposers.splice(at, 1);
+          sub?.unsubscribe();
+          resolve(allowed);
+        };
+        const dispose = (): void => finish([]);
+        const check = (): void => {
+          if (stopped) return finish([]);
+          const allowed = allowedNow();
+          if (allowed.length > 0) finish(allowed);
+        };
+        disposers.push(dispose);
+        check();
+        if (done) return;
+        sub = self._parent?.subscribe({ next: () => queueMicrotask(check), error: dispose, complete: dispose });
+        if (sub === undefined) finish([]);
+      });
+
+    // Resolves once the Agent's state is back at Rest — its outstanding pick answered, or nothing
+    // running below it — or has been left, or with nothing once this actor stops. Read a microtask
+    // after each snapshot of the invoking Machine: the mailbox has drained (rest.ts).
+    const agentState = { invoker: self._parent, invokeId: self.id };
+    const untilRest = (): Promise<void> =>
+      new Promise((resolve) => {
+        let done = false;
+        let sub: { unsubscribe(): void } | undefined;
+        const finish = (): void => {
+          if (done) return;
+          done = true;
+          const at = disposers.indexOf(finish);
+          if (at >= 0) disposers.splice(at, 1);
+          sub?.unsubscribe();
+          resolve();
+        };
+        const check = (): void => {
+          if (stopped) return finish();
+          const held = binding.outstandingOf?.(currentIid);
+          if (held !== undefined && !held.fetched && !held.answered) return;
+          if (restOf(agentState) !== "busy") finish();
+        };
+        disposers.push(finish);
+        check();
+        if (done) return;
+        sub = self._parent?.subscribe({ next: () => queueMicrotask(check), error: finish, complete: finish });
+        if (sub === undefined) finish();
+      });
+
+    // A Harness restart cut this Turn (ADR-0031). It is NOT an `agent.fault` when the Agent's state is
+    // busy — something it started runs below it — or its pick's answer has not reached the model:
+    // faulting would route the Machine out of the state and stop the work the Turn did not want
+    // stopped. jr2 waits for Rest, then re-admits the Agent on the same conversation, which the
+    // rebuilt Harness holds, with the answer as a notice. Undefined: not this case, the caller faults.
+    let cuts = 0;
+    const readmitAfterCut = async (err: unknown): Promise<AgentAdmission | "stopped" | undefined> => {
+      if (stopped) return "stopped";
+      if (restarted === undefined && settledByRestart(err) === undefined) return undefined;
+      const unread = (): boolean => {
+        const held = binding.outstandingOf?.(currentIid);
+        return held !== undefined && !held.fetched;
+      };
+      if (restOf(agentState) !== "busy" && !unread()) return undefined;
+      await untilRest();
+      if (stopped) return "stopped";
+      const held = binding.outstandingOf?.(currentIid);
+      const notice: Notice[] =
+        held !== undefined && !held.fetched && held.answered && !held.turnComplete
+          ? [
+              {
+                kind: "pick-answer",
+                scope: "conversation",
+                pick: held.pick,
+                cut: true,
+                ...(held.answer !== undefined ? { answer: held.answer } : {}),
+              },
+            ]
+          : [];
+      cuts++;
+      binding.telemetry?.({
+        kind: "retry",
+        child: self._parent?.id ?? self.id,
+        attempt: cuts,
+        reason: "re-admitted after a Harness restart",
+      });
+      restarted = undefined;
+      controller = new AbortController();
+      // The rebuilt Harness may not read the conversation back: then this Turn lands on a new one,
+      // and is told (ADR-0062), as the continue path tells it below.
+      if (!(await client.holds(input.agentName, currentIid, { signal: controller.signal }))) {
+        binding.raiseNotice?.(
+          { kind: "conversation-new", scope: "conversation", reason: "the Harness no longer holds it" },
+          conversation,
+        );
+      }
+      if (stopped) return "stopped";
+      // The notices pending for this Turn ride the re-admission, with the cut pick's answer after them.
+      const admission = await admitTurn(
+        { ...framed, attach: undefined, instanceId: currentIid, prompt: READMIT_PROMPT },
+        { notices: true, extra: notice },
+      );
+      binding.heldAnswerDelivered?.(currentIid);
+      return admission;
+    };
+
     // Down-channel: interrupts only (ADR-0002 split-channel model).
     receive((event) => {
       if (event.type === "CANCEL") abandon();
@@ -555,8 +928,9 @@ export function agentActorWith(
     //   - INFRA faults: provider retries run inside the turn, Harness-side, and the wire
     //     client reconnects transparently — so a `settle` rejection means the Submission settled
     //     failed/aborted, or the conversation is lost (ADR-0027). Terminal, no jr2 re-run.
-    //   - NO-SIGNAL: the Submission settles COMPLETED but no menu tool was called. The Harness
-    //     calls that a normal turn, so jr2 owns a budgeted re-prompt on the SAME iid (the conversation
+    //   - NO-SIGNAL: the Submission settles COMPLETED with the Turn still open and Allowed picks
+    //     left (the ask-again rule, below). The Harness calls that a normal Submission, so jr2 owns
+    //     a budgeted re-prompt on the SAME iid (the conversation
     //     continues; each nudge is a fresh admission, ledgered like any other).
     //   - RUNAWAY: the Harness ended a turn that would not conclude and settled it failed with
     //     the typed "runaway" error (ADR-0035). The degenerate context is poisoned, so the
@@ -564,13 +938,16 @@ export function agentActorWith(
     //     admitting the identical prompt — closed to continuations, which opted out of exactly that.
     // Any budget exhausting emits the ONE terminal `agent.fault { reason }`.
     void (async () => {
-      const fault = (reason: string) => {
+      const fault = (reason: string, opts: { conversationKept?: boolean } = {}) => {
         if (stopped) return;
         // Burn the conversation before the fault lands (ADR-0057): the state the fault routes to
         // may invoke this Agent again in the same macrostep, and its mapper must already read the
         // bumped epoch. Continuations only — a fresh invocation mints its own conversation, so
-        // there is nothing to burn.
-        if (input.continuation) binding.bumpEpoch?.(continuedIid(self._parent, binding.runId, input.agentName));
+        // there is nothing to burn. Not when a Harness restart cut the Turn: the rebuilt Harness
+        // holds the conversation (ADR-0031), so only the Turn was lost and the next `continue`
+        // lands on it; that Turn's `holds` check tells it if the rebuild could not read it (ADR-0062).
+        // The fault's reason is the next Turn's news: it is why that conversation starts empty.
+        if (input.continuation && !opts.conversationKept) binding.bumpEpoch?.(conversation, reason);
         sendBack({ type: "agent.fault", instanceId, reason } satisfies FaultTelemetry);
       };
       try {
@@ -581,8 +958,20 @@ export function agentActorWith(
         await pendingAborts.get(instanceId);
         let admission = input.attach;
         if (!admission) {
-          admission = await client.admit(framed, { definition, signal: controller.signal });
-          ledger(admission);
+          // A continued conversation admitted before may be gone with no fault to say so: its
+          // Harness restarted between the Turns. Then this Turn lands on a new one, and is told
+          // (ADR-0062). A conversation never admitted has nothing to lose, so nothing is asked.
+          if (
+            input.continuation &&
+            binding.admissionOf?.(instanceId) !== undefined &&
+            !(await client.holds(input.agentName, instanceId, { signal: controller.signal }))
+          ) {
+            binding.raiseNotice?.(
+              { kind: "conversation-new", scope: "conversation", reason: "the Harness no longer holds it" },
+              conversation,
+            );
+          }
+          admission = await admitTurn(framed);
           // The admission marker (ADR-0023): the Turn and its framing, once — a re-attach
           // continues a Turn already announced, and a nudge (below) is mechanism, not narrative
           // (its telemetry already rides the feed).
@@ -592,7 +981,7 @@ export function agentActorWith(
         let rerolls = 0;
         for (;;) {
           try {
-            await client.settle(admission, { signal: controller.signal });
+            await client.settle(admission, { signal: controller.signal, onMemoryLimit });
           } catch (err) {
             // The reroll gate closes on `signaled` like the nudge gate below: a delivered pick
             // means the workflow already holds this turn's signal, so replaying the identical
@@ -600,6 +989,14 @@ export function agentActorWith(
             // settlement). It also closes when restore dropped `prompt` (`attach` rides instead):
             // there is nothing identical to replay, and the thrown settlement still carries the
             // legible runaway reason.
+            // A Harness restart that cut the Turn while its state was busy (ADR-0031): no fault. The
+            // workflow did not stop, so neither does the Turn — it waits for Rest, then re-admits.
+            const readmitted = await readmitAfterCut(err);
+            if (readmitted === "stopped") return;
+            if (readmitted !== undefined) {
+              admission = readmitted;
+              continue;
+            }
             const reason = stopped || signaled ? undefined : runawayReason(err);
             if (reason === undefined || input.continuation || input.prompt === undefined || rerolls >= runawayBudget)
               throw err;
@@ -615,16 +1012,30 @@ export function agentActorWith(
             // `/mcp/<currentIid>`, so its address must be live before the Harness can run it.
             currentIid = `${instanceId}-r${rerolls}`;
             registerSurface(currentIid);
-            admission = await client.admit(
-              { ...framed, attach: undefined, instanceId: currentIid },
-              { definition, signal: controller.signal },
-            );
-            ledger(admission);
+            admission = await admitTurn({ ...framed, attach: undefined, instanceId: currentIid });
             continue;
           }
-          if (stopped || signaled || input.tools.length === 0) return; // the turn ended as intended
+          // THE ASK-AGAIN RULE (ADR-0016): while the Turn is open, a model that stopped is asked again
+          // once its Allowed picks are not empty — and never with an empty list. One rule, three
+          // moments:
+          //   - inside the Submission, the Harness's step boundary (`between-steps.ts`) restates the
+          //     Turn part when the list changed since the model last read it; that message keeps the
+          //     engine's loop going, and costs no Submission;
+          //   - after it settles with picks LEFT, the NUDGE, here;
+          //   - after it settles with NONE left (the Turn waits on a Gate, a child's invoke, a timer),
+          //     the WAKE: this actor watches the invoking Machine and asks the first time a pick
+          //     opens. A Turn that was never meant to pick waits until its state exits.
+          // The nudge and the wake are one Submission kind — the same text, the same conversation,
+          // the same budget — so a Machine that opens and closes picks under a stopped model cannot
+          // ask it without bound. A Turn whose pick left the Agent's state is over: the invoke was
+          // stopped, and nothing is asked.
+          if (stopped) return;
+          let allowed = allowedNow();
+          const woken = allowed.length === 0;
+          if (woken) allowed = await picksOpen();
+          if (stopped || allowed.length === 0) return;
           if (nudges >= nudgeBudget) {
-            fault(`agent completed its turn without calling any of: ${input.tools.join(", ")}`);
+            fault(`agent completed its turn without a pick that ends it; still allowed: ${allowed.join(", ")}`);
             return;
           }
           nudges++;
@@ -632,17 +1043,59 @@ export function agentActorWith(
             kind: "retry",
             child: self._parent?.id ?? self.id,
             attempt: nudges,
-            reason: "no-signal nudge",
+            reason: woken ? "picks allowed again" : "no-signal nudge",
           });
-          admission = await client.admit(
-            { ...framed, attach: undefined, instanceId: currentIid, prompt: nudgePrompt(input.tools) },
-            { definition, signal: controller.signal },
+          admission = await admitTurn(
+            {
+              ...framed,
+              attach: undefined,
+              instanceId: currentIid,
+              prompt: NUDGE_PROMPT,
+            },
+            { notices: false },
           );
-          ledger(admission);
         }
       } catch (err) {
         if (stopped) return;
-        fault(err instanceof Error ? err.message : String(err));
+        // The Harness restarted under this Turn (ADR-0021): whatever the stream said as it was cut,
+        // the restart is why.
+        // A Settlement that names the restart is the same fault in the Harness's words (ADR-0021
+        // wording, ADR-0031's rebuilt stream), so it carries the same `Turn lost` prefix.
+        const restartSettled = restarted === undefined ? settledByRestart(err) : undefined;
+        const message =
+          restarted !== undefined
+            ? harnessRestartReason(restarted)
+            : restartSettled !== undefined
+              ? `Turn lost (${restartSettled})`
+              : (providerLimitReason(err) ?? errorMessage(err));
+        // A lost conversation may be a memory kill (ADR-0061): the kernel's group kill took the
+        // Harness with the Agent's processes. The operator publishes the container's last end on
+        // the Sandbox, so the fault is NAMED — the fixed prefix `memory limit` — instead of
+        // "Turn lost", and the Machine's policy can tell the two apart.
+        //
+        // The fault reaches the Machine (ADR-0016); the next Agent in this Workspace is told
+        // through the Briefing, never through the Frame (ADR-0057, ADR-0062) — a notice raised
+        // BEFORE the fault, because the state it routes to may admit in the same macrostep. Keyed
+        // by the kill itself, so every Turn the one kill ended raises one notice between them.
+        // A restart the Settlement reported before the watch did may still be a memory kill: the
+        // Sandbox is asked, as for a 404.
+        const lostHarness =
+          restarted !== undefined
+            ? restarted.lastTerminated?.reason === OOM_KILLED
+            : isLostConversation(err) || restartSettled !== undefined;
+        const kill = lostHarness && sandbox !== undefined ? await memoryFault(sandbox) : undefined;
+        if (stopped) return;
+        if (kill !== undefined && noticeWorkspace !== undefined) {
+          binding.raiseNotice?.(
+            memoryLimit(kill.limit ?? "unknown"),
+            noticeWorkspace,
+            kill.at === undefined ? undefined : `${noticeWorkspace}@${kill.at}`,
+          );
+        }
+        // A restart the Harness came back from keeps the conversation (ADR-0031); a 404 does not.
+        fault(kill !== undefined ? `${kill.reason}\n  ${message}` : message, {
+          conversationKept: restarted !== undefined || restartSettled !== undefined,
+        });
       }
     })();