@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/machines.md

@@ -119,7 +119,6 @@ import { body, type TaskInput } from "@jr2/machines";
 
 const fixed = workspace(body, {
   repos: { app: { url: "https://github.com/you/app.git" } },
-  spec: ({ input }: { input: TaskInput }) => ({ branch: input.branch ?? "jr2/fix" }),
 });
 
 export const machine = customize(fixed, {

package/docs/why.md

@@ -47,7 +47,8 @@ cannot be the right one for each of them.
 
 The You band of the diagram holds the clients of jr2. The [Orchestrator](reference/glossary.md#orchestrator) is an HTTP
 API. The [jr2 CLI](reference/glossary.md#jr2-cli) and the [Console](reference/glossary.md#console) are its clients, and
-your own app, such as a webhook, can be one too. For example, a client can start a run with
+your own app, such as a CI job or a bridge to a chat service, can be one too. An outside service, such as a forge, sends
+its deliveries to a [Hook](reference/glossary.md#hook). For example, a client can start a run with
 [`POST /workflows/:name/runs`](reference/http-api.md#post-workflows-name-runs). In the diagram, a
 [Gate](reference/glossary.md#gate) in the state `approval` asks you, and you answer from any of these clients, with
 [`POST /runs/:runId/gates/:gate/events`](reference/http-api.md#post-runs-runid-gates-gate-events).
@@ -115,8 +116,8 @@ It talks to the model, and it runs the tools of the Agent. The Agent can run eac
 Agent that needs only its Menu has no Sandbox. Its Turns run on the
 [Instance Harness](reference/glossary.md#instance-harness).
 
-The Harness container holds no credential, so a command that an Agent runs cannot read one. jr2 keeps each credential in
-one of the two containers beside it:
+The Harness runs each command of an Agent confined with Landlock, so the command cannot read a credential, and it cannot
+send a pick for a different Agent. jr2 keeps each credential in one of the two containers beside the Harness:
 
 - The [Custodian](reference/glossary.md#custodian) holds each [Held secret](reference/glossary.md#held-secret): a key
   that the Agents can use, but cannot read. The Harness holds only a [Stand-in](reference/glossary.md#stand-in) for it.
@@ -192,8 +193,9 @@ These steps follow one run of the example Machine in the diagram. You write a Ma
 1. **You start a run.** You run `jr2 run feature`, with the ticket as the input of the run. The Machine starts in its
    first state, `code`.
 2. **The coder works in a Sandbox.** The state `code` is in a Workspace, so jr2 makes a Sandbox for it. The Sandbox
-   holds a [Worktree](reference/glossary.md#worktree) of your Repo, on the branch of the run. The coder edits the files,
-   runs the tests and commits. Then it picks `finish`, and the Machine moves to `review`.
+   holds a clone of your Repo, and the Machine cuts a [Worktree](reference/glossary.md#worktree) on the branch of the
+   run. The coder edits the files, runs the tests and commits. Then it picks `finish`, and the Machine moves to
+   `review`.
 3. **The reviewer gets a Turn.** The state `review` gives the reviewer a prompt and its Menu: `approved` and `changes`.
    The reviewer reads the change in the same Sandbox.
 4. **The reviewer picks.** If it picks `approved`, the Machine moves to `approval`. If it picks `changes`, the Machine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "The jr2 Orchestrator: xstate runtime, HTTP API and Console, and the kit pieces a Workflow imports.",
   "license": "MIT",
   "private": false,
@@ -31,6 +31,12 @@
   "exports": {
     ".": "./src/index.ts",
     "./internal": "./src/internal.ts",
+    "./hooks": "./src/hook-kinds/index.ts",
+    "./hooks/github": "./src/hook-kinds/github.ts",
+    "./hooks/gitlab": "./src/hook-kinds/gitlab.ts",
+    "./hooks/slack": "./src/hook-kinds/slack.ts",
+    "./hooks/discord": "./src/hook-kinds/discord.ts",
+    "./hooks/webhook": "./src/hook-kinds/webhook.ts",
     "./tsconfig.instance.json": "./tsconfig.instance.json"
   },
   "types": "./src/index.ts",
@@ -38,15 +44,16 @@
     "@hono/node-server": "^2.0.6",
     "elkjs": "^0.11.1",
     "hono": "^4.12.27",
+    "jose": "^6.2.3",
     "preact": "^10.29.8",
     "ts-blank-space": "^0.9.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/agent-protocol": "0.5.1"
+    "@jr2/agent-protocol": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.5.1"
+    "@jr2/harness": "0.7.0"
   },
   "files": [
     "bin",

package/src/actor.ts

@@ -50,14 +50,21 @@ import {
   type ThinkingLevel,
   type WorkspaceAccess,
 } from "./agent.ts";
+import type { AnyFramePath } from "./worktree.ts";
 import { ambientHandlesFor, type AmbientHandles } from "./ambient.ts";
 import type { HarnessRestarts, MemoryKill } from "./workspace.ts";
 import { INSTANCE_HARNESS_SERVICE } from "./names.ts";
 import { SENDER_KEY } from "@jr2/agent-protocol";
-import { agentAddress, continuedIid, allowedPicks, resolveAccepts, runBindingOf } from "./registration.ts";
-import type { NoticeScope } from "./notices.ts";
+import { agentAddress, agentSlot, continuedIid, allowedPicks, resolveAccepts, runBindingOf } from "./registration.ts";
+import type { LedgerBody, NoticeScope } from "./notices.ts";
 import { restOf } from "./rest.ts";
-import { SUBMISSION_HARNESS_RESTARTED, SUBMISSION_RUNAWAY, type Notice, type PodMemoryKill } from "./wire.ts";
+import {
+  SUBMISSION_HARNESS_RESTARTED,
+  SUBMISSION_RUNAWAY,
+  type Notice,
+  type PodMemoryKill,
+  type SteeringMessage,
+} from "./wire.ts";
 import type { AbortCause } from "./wire.ts";
 
 /**
@@ -122,6 +129,14 @@ export type AgentAdmission = {
    */
   agent?: string;
   endpoint?: string;
+  /**
+   * The pod and the slot of the conversation (ADR-0076) — stamped by the ACTOR at ledger time, like
+   * `agent`. The kept conversation's route takes entries for this conversation only from this pod's
+   * control token, for this slot (ADR-0023). It reads the ledger and not the live registration,
+   * because the ledger outlives the Turn and the run.
+   */
+  sandbox?: string;
+  slot?: string;
 };
 
 /**
@@ -143,15 +158,15 @@ export type AgentTurnInput = {
   /**
    * The other half of the FRAME (ADR-0057) — WHERE this Turn works: the absolute directory the
    * Harness roots the Working tools at. Per Turn by nature, which is why no definition names one:
-   * a Worktree path (`/work/<slot>/<branch>`) exists only once a run has a branch.
+   * a Worktree path (`/work/<slot>/<name>`) exists only once a Machine has cut it (ADR-0075).
    *
-   * Absent, the actor resolves it before admission: a `workspace: "none"` Agent frames no
-   * directory (it has no Working tools to root — ADR-0028), a Workspace with ONE Repo Slot frames
-   * that slot's Worktree, a Workspace with more REFUSES the Turn (the kit gives no slot a meaning
-   * — ADR-0051 — so the state must say which), and a run with no Workspace at all frames nothing
-   * and the Harness keeps `/work`. A relative path is refused at admission, by the Harness.
+   * Required under Repo Slots: a Turn with no `cwd` there is REFUSED before admission, and a Turn
+   * that wants `/work` states it. A `workspace: "none"` Agent frames no directory (it has no Working
+   * tools to root — ADR-0028), and a Workspace with no Repo Slot, or a run with no Workspace at all,
+   * frames nothing and the Harness keeps `/work`. A relative path is refused at admission, by the
+   * Harness.
    */
-  cwd?: string;
+  cwd?: AnyFramePath;
   /**
    * This turn's DIALS (ADR-0018) — how hard to run, layered over the definition's own
    * values. One definition value may be carried by several Machines, so the same persona
@@ -358,10 +373,16 @@ export interface AgentRunPort {
  * Machine edit that changed it. */
 export type AgentAdmitOptions = {
   definition: AgentDefinition;
+  /** This Agent's slot (ADR-0076): the actor path of its Machine and its agent name — the
+   * registration's. The Harness keeps it with the conversation and states it on each control
+   * request; it never derives it from an Instance ID, whose actor ids may hold a `/`. */
+  slot: string;
   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[];
+  /** The Steering messages held for this Agent slot (ADR-0002), delivered by the rules of a notice. */
+  steering?: SteeringMessage[];
   /** The admission is for a conversation that `holds` said the Harness keeps (ADR-0062): the
    * re-admission after a cut, and a continued Turn. That "kept" can be a timeout's, so a Harness
    * that keeps none refuses it and seats none; `admit` then rejects with an error whose `notKept`
@@ -555,20 +576,15 @@ const READMIT_PROMPT =
  * an ABSENT one, and a directory a state named is never second-guessed — a Menu-only Agent handed
  * one simply has no Working tools to root there (ADR-0028/0031).
  *
- * Absent, a Menu-only Agent frames no directory; a Workspace with ONE Repo Slot frames that
- * slot's Worktree, which privileges nothing because there is nothing to choose between (ADR-0051);
- * a Workspace with more REFUSES the Turn, naming the slots in declaration order and the line that
- * ends it, because the kit gives no slot a meaning and a wrong guess is the silent failure
- * ADR-0057 was written for; and a Workspace with no Repo Slot, or a run outside any Workspace,
- * frames nothing, so the Harness keeps `/work`, the folder a slotless Workspace's steps share.
+ * Absent, a Menu-only Agent frames no directory, and a Workspace with no Repo Slot, or a run outside
+ * any Workspace, frames nothing, so the Harness keeps `/work`, the folder a slotless Workspace's
+ * steps share. Under Repo Slots the Workspace only clones, so no Worktree exists for a default to
+ * name, and the kit gives no slot a meaning: an absent `cwd` is REFUSED, because a wrong guess is
+ * the silent failure ADR-0057 was written for (ADR-0075).
  *
- * Resolution counts SLOTS, and a slot's Worktree is the writable branch checkout. The detached
- * review Worktree (`AmbientHandles.review`, ADR-0028's reviewer seat) is never resolved to: it is
- * per review round, so only the reviewing state knows which one, and it frames it (ADR-0028 hands
- * the reviewer its path as "cwd and prompt"). A `workspace: "read"` Agent that frames nothing
- * under a one-slot Workspace therefore works in the branch checkout with `write`/`edit` withheld
- * and `bash` kept — the tool layer's hint, not containment (ADR-0028): containment is the
- * detached review Worktree, and only a reviewing state that requested one can frame it.
+ * `workspace: "read"` withholds `write`/`edit` and keeps `bash`: the tool layer's hint, not
+ * containment (ADR-0028). The containment is a detached Worktree that the state cuts and names as
+ * its `cwd`.
  *
  * The refusal throws at invoke, like the Open-model fence: loudly, at the first Turn, before a
  * surface is registered or a pod is spent.
@@ -583,12 +599,11 @@ function frameCwd(
   if (workspace === "none") return undefined;
   const slots = Object.keys(ambient?.repos ?? {});
   if (slots.length === 0) return undefined;
-  if (slots.length === 1) return ambient!.repos[slots[0]!];
+  // A default here is ADR-0057's incident: an Agent's search hits `default/`, and a relative write
+  // lands outside each Worktree. An author who wants `/work` states it.
   throw new Error(
-    `turn ${instanceId}: agent "${input.agentName}" works under a Workspace carrying more than one ` +
-      `Repo Slot (${slots.join(", ")}) and its Turn framed no \`cwd\` — say which Worktree it works ` +
-      `in (\`cwd: context.workspace.repos.<slot>\`, one of those), because the kit gives no slot a ` +
-      `meaning (ADR-0051) and a Turn's Frame is where it works (ADR-0057)`,
+    `turn ${instanceId}: agent "${input.agentName}" works under a Workspace with Repo Slots (${slots.join(", ")}) ` +
+      'and its Turn framed no `cwd`: say where it works, a Worktree, or `cwd: "/work"` above them (ADR-0057)',
   );
 }
 
@@ -701,7 +716,7 @@ export function agentActorWith(
 
     // The Frame's other half (ADR-0057): WHERE this Turn works. Resolved HERE, before any surface
     // is registered and before a pod is spent, because the answer is a fact about the run — a
-    // Worktree path exists only once a run has a branch, so no definition could have named it.
+    // Worktree exists only once a run has cut it, so no definition could have named it.
     const cwd = frameCwd(instanceId, input, workspace, ambient);
     const framed: AgentRunInput = cwd === undefined ? input : { ...input, cwd };
 
@@ -732,8 +747,18 @@ export function agentActorWith(
     // 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);
+    // This Agent's slot (ADR-0076): the same identity without the run id. The Harness states it on
+    // every control request, and the Orchestrator speaks here only for it.
+    const slot = agentSlot(self._parent, input.agentName);
     // The iids whose surface the Harness has read (see `carried` below).
     const served = new Set<string>();
+    // Per iid, the notices a step boundary's surface read reserved and the Harness has not yet
+    // acknowledged (ADR-0062): by the id the read named, every id it stands for — equal notices
+    // are said once — and what each was raised as, for `reraiseUnheard`.
+    const boundary = new Map<
+      string,
+      Map<string, Array<{ id: string; raised: { notice: LedgerBody; source?: string } }>>
+    >();
     const registerSurface = (iid: string) =>
       disposers.push(
         binding.table.register({
@@ -744,6 +769,9 @@ export function agentActorWith(
           defs,
           menu,
           sandbox,
+          slot,
+          boundaryNotices: () => readBoundary(iid),
+          noticesHeard: (ids) => boundaryHeard(iid, ids),
           deliver: (event) => {
             signaled = true;
             // The settlement-pick marker (ADR-0023), BEFORE the delivery moves the Machine: the pick
@@ -824,7 +852,8 @@ export function agentActorWith(
     // LIVE conversation stamped on the record, so a restore settle-follows the live submission
     // 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[]) =>
+    // The conversation is a member of its Workspace's audiences from this save on (ADR-0062).
+    const ledger = (admission: AgentAdmission, delivered: readonly string[], taker: string) =>
       binding.recordAdmission?.(
         instanceId,
         {
@@ -832,9 +861,15 @@ export function agentActorWith(
           instanceId: currentIid,
           agent: input.agentName,
           endpoint,
+          ...(sandbox === undefined ? {} : { sandbox }),
+          slot,
           ...(input.turnId === undefined ? {} : { turnId: input.turnId }),
         },
         delivered,
+        taker,
+        noticeWorkspace === undefined
+          ? undefined
+          : { workspace: noticeWorkspace, slot, continued: Boolean(input.continuation) && taker === conversationIid() },
       );
 
     // Where this Turn hears notices (ADR-0062). Its continued conversation's — the base id the
@@ -845,7 +880,11 @@ export function agentActorWith(
     const noticeScope: NoticeScope = {
       ...(input.continuation ? { conversation } : {}),
       ...(noticeWorkspace !== undefined ? { workspace: noticeWorkspace } : {}),
+      slot,
     };
+    // The Instance ID of the continued conversation this Turn rides — its epoch's spelling, which
+    // the minted `instanceId` is. A fresh Turn has none.
+    const conversationIid = (): string | undefined => (input.continuation ? instanceId : undefined);
     // No `agent`: the notice names no Turn — what the pod's list says (below).
     // No `limit`: the sizes read were not sizes, and the notice says none.
     const memoryLimit = ({ limit, peak, agent }: { limit?: string; peak?: string; agent?: string }): Notice => ({
@@ -859,12 +898,15 @@ export function agentActorWith(
     // Turn's Agent. A stopped actor's last poll names nothing: the state that asked for the Turn has
     // exited, and the pod's list carries the kill. Keyed by the kill's id, so a second running
     // conversation's stream, or the pod's list, adds nothing.
+    // The kill cut this Turn (D4 rule 2): its Agent's next Turn retries the broken work, and hears it.
     const onMemoryLimit = (kill: StreamedKill): void => {
       if (stopped || noticeWorkspace === undefined) return;
       binding.raiseNotice?.(
         memoryLimit({ limit: kill.limit, peak: kill.peak, agent: input.agentName }),
         noticeWorkspace,
         kill.legacy ? kill.id : guardSource(noticeWorkspace, kill.id),
+        [],
+        { retry: { slot, cut: currentIid }, at: new Date().toISOString() },
       );
     };
     // …but a stream is not every kill's path. A kill while no Submission ran — a process an earlier
@@ -906,6 +948,8 @@ export function agentActorWith(
         memoryLimit({ limit: kill.limit }),
         noticeWorkspace,
         kernelSource(noticeWorkspace, kill.at),
+        [],
+        { at: kill.at },
       );
     };
     let killMark = input.attach?.killMark;
@@ -937,7 +981,9 @@ export function agentActorWith(
         noticeWorkspace,
         guardSource(noticeWorkspace, newest.id),
         kills.slice(0, -1).map((kill) => guardSource(noticeWorkspace, kill.id)),
+        { at: newest.at, told: newest.told.map((t) => t.instanceId) },
       );
+      applyTold(kills);
       const toldHere = (kill: ListedKill): boolean =>
         kill.told.some((t) => t.agent === input.agentName && t.instanceId === currentIid);
       // The first kill after the Turn's mark. A mark no longer in the bounded list is older than
@@ -956,6 +1002,86 @@ export function agentActorWith(
       };
     };
 
+    // The conversations each listed kill's `bash` answer told leave its audience (D4 rule 3) — a
+    // kill raised off a stream before its answer returned is found here too.
+    const applyTold = (kills: readonly ListedKill[]): void => {
+      if (noticeWorkspace === undefined) return;
+      const told = kills
+        .filter((kill) => kill.told.length > 0)
+        .map((kill) => ({ source: guardSource(noticeWorkspace, kill.id), takers: kill.told.map((t) => t.instanceId) }));
+      if (told.length > 0) binding.noticesTold?.(told);
+    };
+    // The step boundary's read (ADR-0062): this conversation's pending notices in their audience,
+    // reserved for this Turn until the Harness acknowledges the append. A guard kill's audience
+    // leaves out the conversations its `bash` answer told, which only the pod's list says — so when
+    // one is among them, the list is read first, and a read that could not tell takes no guard kill.
+    const readBoundary = async (iid: string): Promise<Array<{ id: string; notice: LedgerBody }>> => {
+      if (stopped || iid !== currentIid || binding.takeNotices === undefined) return [];
+      const scope: NoticeScope = { ...noticeScope, taker: iid };
+      if (noticeWorkspace !== undefined) {
+        const guard = guardSource(noticeWorkspace, "");
+        if ((binding.peekNotices?.(scope) ?? []).some((p) => p.source?.startsWith(guard))) {
+          let kills: ListedKill[] | undefined;
+          try {
+            kills = await client.memoryKills({
+              signal: AbortSignal.any([controller.signal, AbortSignal.timeout(memoryKillsReadMs)]),
+            });
+          } catch {
+            kills = undefined;
+          }
+          if (kills === undefined) scope.exceptPrefix = guard;
+          else applyTold(kills);
+        }
+      }
+      if (stopped || iid !== currentIid) return [];
+      const taken = binding.takeNotices(scope);
+      const held = boundary.get(iid) ?? new Map();
+      const said = new Map<string, string>();
+      const out: Array<{ id: string; notice: LedgerBody }> = [];
+      taken.ids.forEach((id, i) => {
+        const raised = taken.raised?.[i] ?? { notice: taken.notices[i]! };
+        const key = JSON.stringify(raised.notice);
+        const first = said.get(key);
+        if (first === undefined) {
+          said.set(key, id);
+          held.set(id, [{ id, raised }]);
+          out.push({ id, notice: raised.notice });
+        } else held.get(first)!.push({ id, raised });
+      });
+      if (held.size > 0) boundary.set(iid, held);
+      return out;
+    };
+    // A step boundary whose notices the Harness did not append — a stopped model with no Allowed
+    // picks, or a Turn ending as it read (`between-steps.ts`) — holds them until the next admission
+    // of the conversation, which takes them again: a wake or a nudge carries them (ADR-0062).
+    const releaseBoundary = (iid: string): void => {
+      const held = boundary.get(iid);
+      if (held === undefined) return;
+      boundary.delete(iid);
+      binding.releaseNotices?.(
+        [...held.values()].flatMap((hs) => hs.map((h) => h.id)),
+        iid,
+      );
+    };
+    // The Harness appended them: heard in this conversation, in one save. An id this read did not
+    // name changes nothing.
+    const boundaryHeard = (iid: string, ids: readonly string[]): number => {
+      const held = boundary.get(iid);
+      if (held === undefined) return 0;
+      const heard = ids.flatMap((id) => held.get(id) ?? []);
+      for (const id of ids) held.delete(id);
+      if (held.size === 0) boundary.delete(iid);
+      if (heard.length === 0) return 0;
+      binding.acknowledgeNotices?.(
+        heard.map((h) => h.id),
+        iid,
+      );
+      const bucket = carriedBy.get(iid) ?? { heard: [], unheard: [], task: false, fresh: [] };
+      bucket.heard.push(...heard.map((h) => h.raised));
+      carriedBy.set(iid, bucket);
+      return ids.filter((id) => heard.some((h) => h.id === id)).length;
+    };
+
     // 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 and a wake's carry only the guard
     // kills of this Turn that came after its own `bash` call's last kill verdict (`hearPodKills`):
@@ -973,7 +1099,7 @@ export function agentActorWith(
     // the Harness last read its surface, `heard` before that — and whether an unheard one carried
     // the Turn's task. Collected across the Turn, so a re-admission onto a lost conversation tells
     // the Agent all of them again.
-    type Raised = { notice: Notice; source?: string };
+    type Raised = { notice: LedgerBody; source?: string };
     // `fresh`: a fresh Turn's "this conversation is new", which rides an admission as `extra` and so
     // is kept in no ledger — an unread one is carried again by the next re-admission.
     const carriedBy = new Map<string, { heard: Raised[]; unheard: Raised[]; task: boolean; fresh: Notice[] }>();
@@ -996,26 +1122,34 @@ export function agentActorWith(
     ) => {
       await hearKernelKill();
       const { known, unsaid, said } = await hearPodKills();
+      releaseBoundary(turn.instanceId);
+      // The conversation that takes a Workspace notice (ADR-0062): the one this admission rides, its
+      // Instance ID. A continued Turn's is the continued conversation's; a fresh Turn's, a reroll's
+      // and a burned conversation's successor's are each a new conversation, which has heard none.
+      // A Workspace notice is delivered once in each, so every conversation in the Workspace hears
+      // it — each child of a Pool has its own — and no conversation hears it twice.
+      const taker = turn.instanceId;
       // A read that could not tell leaves the same Turn no way to know which kills its own `bash`
       // reported: it takes none, as a nudge takes none then, and they stay for the next Turn.
       const sameTurn: NoticeScope = known
-        ? { ...noticeScope, except: said }
+        ? { ...noticeScope, taker, except: said }
         : {
             ...noticeScope,
+            taker,
             ...(noticeWorkspace === undefined ? {} : { exceptPrefix: guardSource(noticeWorkspace, "") }),
           };
       const scope: NoticeScope | undefined =
         opts.notices === "turn"
-          ? noticeScope
+          ? { ...noticeScope, taker, turn: true }
           : opts.notices === "same-turn"
             ? sameTurn
             : unsaid.length > 0
-              ? { workspace: noticeWorkspace, only: unsaid }
+              ? { workspace: noticeWorkspace, taker, only: unsaid }
               : undefined;
-      const none = { ids: [] as string[], notices: [] as Notice[], raised: [] as Raised[] };
+      const none = { ids: [] as string[], notices: [] as LedgerBody[], raised: [] as Raised[] };
       const restored =
         opts.include && opts.include.length > 0
-          ? (binding.takeNotices?.({ ...noticeScope, only: opts.include }) ?? none)
+          ? (binding.takeNotices?.({ ...noticeScope, taker, only: opts.include }) ?? none)
           : none;
       const main = (scope ? binding.takeNotices?.(scope) : undefined) ?? none;
       const taken = {
@@ -1030,12 +1164,16 @@ export function agentActorWith(
       // cut pick never got (ADR-0031), whose one path to the model is this admission. One "this
       // conversation is new" is enough, whichever path brought it.
       let fresh = false;
-      const notices = [...taken.notices, ...(opts.extra ?? [])].filter((n) => {
+      const bodies = [...taken.notices, ...(opts.extra ?? [])].filter((n) => {
         if (n.kind !== "conversation-new") return true;
         if (fresh) return false;
         fresh = true;
         return true;
       });
+      // The two kinds of body ride the admission apart (ADR-0062): a notice is a fact, and a
+      // Steering message an author's text, which the Harness frames by its author.
+      const notices = bodies.filter((n): n is Notice => n.kind !== "steering");
+      const steering = bodies.filter((n): n is SteeringMessage => n.kind === "steering");
       // `served` is per Instance ID, and a nudge or a wake reuses the Turn's: it must be read again
       // before this admission counts as heard (`reraiseUnheard`). An admission that fails puts the
       // mark back — what an earlier one carried was heard.
@@ -1045,12 +1183,14 @@ export function agentActorWith(
       try {
         admission = await client.admit(turn, {
           definition,
+          slot,
           signal: controller.signal,
           ...(notices.length ? { notices } : {}),
+          ...(steering.length ? { steering } : {}),
           ...(opts.kept ? { kept: true } : {}),
         });
       } catch (err) {
-        binding.releaseNotices?.(taken.ids);
+        binding.releaseNotices?.(taken.ids, taker);
         if (heard) served.add(turn.instanceId);
         throw err;
       }
@@ -1071,7 +1211,7 @@ export function agentActorWith(
           ...(killMark === undefined ? {} : { killMark }),
         };
       }
-      ledger(admission, taken.ids);
+      ledger(admission, taken.ids, taker);
       const bucket = carriedBy.get(turn.instanceId) ?? { heard: [], unheard: [], task: false, fresh: [] };
       if (heard) {
         bucket.heard.push(...bucket.unheard);
@@ -1099,10 +1239,12 @@ export function agentActorWith(
         if (gone) bucket.heard = [];
         if (!read) bucket.unheard = [];
         for (const { notice, source } of again) {
-          const to = notice.scope === "conversation" ? conversation : noticeWorkspace;
+          const to = notice.scope === "conversation" ? conversation : notice.scope === "slot" ? slot : noticeWorkspace;
           if (to === undefined) continue;
-          if (binding.restoreNotice) binding.restoreNotice(notice, to, source);
-          else binding.raiseNotice?.(notice, to);
+          // A Workspace notice is pending again for the conversation that carried it, which did not
+          // hear it; the others it reached keep theirs.
+          if (binding.restoreNotice) binding.restoreNotice(notice, to, source, iid);
+          else if (notice.kind !== "steering") binding.raiseNotice?.(notice, to);
           if (source !== undefined) restored.push(source);
         }
       }
@@ -1122,7 +1264,14 @@ 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;
+      // A step boundary's notices the Harness never acknowledged are pending again (ADR-0062).
+      for (const iid of [...boundary.keys()]) releaseBoundary(iid);
       reraiseUnheard();
+      // The Turn ended: a fresh conversation leaves every audience in its Workspace, a continued one
+      // waits for its next Turn (ADR-0062).
+      if (noticeWorkspace !== undefined) {
+        binding.noticeTurnEnded?.(noticeWorkspace, [...new Set([...carriedBy.keys(), currentIid])]);
+      }
       // 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.
@@ -1548,10 +1697,13 @@ export function agentActorWith(
         const kill = lostHarness && sandbox !== undefined ? await memoryFault(sandbox) : undefined;
         if (stopped) return;
         if (kill !== undefined && noticeWorkspace !== undefined) {
+          // The kill cut this Turn (D4 rule 2): its Agent's next Turn retries the work, and hears it.
           binding.raiseNotice?.(
             memoryLimit({ limit: kill.limit, agent: input.agentName }),
             noticeWorkspace,
             kill.at === undefined ? undefined : kernelSource(noticeWorkspace, kill.at),
+            [],
+            { retry: { slot, cut: currentIid }, ...(kill.at === undefined ? {} : { at: kill.at }) },
           );
         }
         // A restart the Harness came back from keeps the conversation (ADR-0031); a 404 does not.

package/src/agent.ts

@@ -58,9 +58,47 @@ export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhi
  * tells what each value gives. */
 export type WorkspaceAccess = "write" | "read" | "none";
 
+// One entry of an Agent's `mcp` list (ADR-0079): a server of the config's `mcp` block, by its name,
+// and the allowlist. An object, so that `resources` can join `tools` later. The TYPE cannot say
+// which servers take a list: that is the config's (remote or stdio), so `jr2 up` says it.
+/**
+ * One MCP server that an Agent uses, and the tools that it may call there.
+ *
+ * - `server` is a name of the `mcp` block of `jr2.config.ts`. `jr2 up` refuses a name that the
+ *   block does not declare, and prints the `customize()` line that binds the Agent to one it does.
+ * - `tools` is the allowlist. A remote server needs it: a list of tool names, or `"*"` for every
+ *   tool. The Harness offers and runs only those tools. When Workspace code in the Agent's Sandbox
+ *   can spend the server's secret, `jr2 up` takes only `"*"`, because a list would then not be a
+ *   limit. A stdio server takes no `tools`: the Agent gets every tool of the server.
+ *
+ * The model reads each tool as `mcp__<server>__<tool>`. A tool name in the list must keep that name
+ * within `[A-Za-z0-9_-]` and 128 characters.
+ *
+ * @example
+ * ```ts
+ * import { agent } from "@jr2/orchestrator";
+ *
+ * export const triage = agent({
+ *   model: "anthropic/claude-haiku-5-5",
+ *   instructions: "You read the ticket and post a summary to the channel.",
+ *   workspace: "none",
+ *   mcp: [{ server: "slack-acme", tools: ["post_message", "read_channel"] }],
+ * });
+ * ```
+ *
+ * @see docs/reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md
+ */
+export type AgentMcpServer = {
+  /** A server name of the `mcp` block of `jr2.config.ts`. */
+  server: string;
+  /** The allowlist: tool names of the server, or `"*"` for every tool. Required for a remote
+   * server; absent for a stdio server. */
+  tools?: readonly string[] | "*";
+};
+
 // The plain-data Agent definition (ADR-0018): IDENTITY plus one default. A Turn's Frame — what it
-// is about and where it works — is not here and cannot be (ADR-0057): a Worktree path exists only
-// once a run has a branch, so no definition written before the run could name one.
+// is about and where it works — is not here and cannot be (ADR-0057): a Worktree exists only
+// once a run has cut it, so no definition written before the run could name one.
 //
 // Must stay JSON-serializable: the definition rides the Turn to the Harness (ADR-0049), so
 // anything non-serializable would be silently lost — grow this contract deliberately. ADR-0028
@@ -119,17 +157,29 @@ export type AgentDefinition = {
    * level in the invoke's `input`. */
   thinkingLevel?: ThinkingLevel;
   // The persona in one word (ADR-0028), deliberately not `tools` (that names the control-plane
-  // Menu, what it may SAY). `"read"` states intent and stops the honest path: bash stays, and the
-  // detached review worktree is the containment. `"none"` frames no directory — only Working tools
+  // Menu, what it may SAY). `"read"` states intent and stops the honest path: bash stays, and a
+  // detached Worktree is the containment. `"none"` frames no directory — only Working tools
   // consume one — and places the Turn on the Instance Harness (ADR-0031).
   /** What the Agent may do to the Workspace. Default: `"write"`.
    * - `"write"`: all the Working tools (read, write, edit, bash, grep, glob).
    * - `"read"`: no write or edit tool. The Agent keeps bash, so `"read"` does not stop a command
-   *   that writes. To keep the Agent from changing the branch, frame its Turn in the review
-   *   Worktree: `reviewSha` in the spec, then `cwd: context.workspace.review?.<slot>`.
+   *   that writes. To keep the Agent from changing the branch, frame its Turn in a detached
+   *   Worktree: cut it with `{ path, detach: sha }`, then give that `path` as `cwd`.
    * - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
    *   runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it. */
   workspace?: WorkspaceAccess;
+  // Reach for tools (ADR-0079): names only. The url and the secret are the Instance's, in the
+  // config's `mcp` block, so a packaged Machine ships no credential and a composer rebinds the list.
+  /** The MCP servers whose tools the Agent gets, each with its allowlist: see
+   * {@link AgentMcpServer}. The tools join the Agent's tools, after its Working tools and before
+   * its Menu. A call to one is not a pick, and the Turn goes on after it. Default: none. A composer
+   * replaces the whole list with `customize(machine, { agents: { <slot>: { mcp: [...] } } })`. */
+  mcp?: readonly AgentMcpServer[];
+  // Read by the Orchestrator alone (ADR-0002): the admission strips it, and the model never reads it.
+  /** May a Caller send this Agent a Steering message? Default: `true`. With `false`,
+   * `POST /runs/:runId/steering` and `jr2 steer` refuse it, and `GET /runs/:runId/agents` says
+   * `steerable: false`. The Machine can still steer the Agent with the `steer` action. */
+  steerable?: boolean;
 };
 
 // The Agent as an author DECLARES it (ADR-0054): the definition, except that `model` may be Open —

package/src/ambient.ts

@@ -21,14 +21,12 @@ import type { AnyActorRef } from "xstate";
 export type AmbientHandles = {
   endpoint: string;
   sandbox: string;
-  /** Every Repo Slot's branch-worktree path, by slot (ADR-0051). */
+  /** Every Repo Slot's folder, `/work/<slot>`, by slot (ADR-0051). */
   repos: Record<string, string>;
   /** Every Repo Slot's Binding url, by slot (ADR-0051): where a push goes. */
   bindings?: Record<string, string>;
-  /** The branch the Worktrees are on. Absent for a Workspace with no Repo Slot (ADR-0051). */
-  branch?: string;
-  /** Detached review-worktree paths, when the spec carried `reviewSha` (ADR-0028). */
-  review?: Record<string, string>;
+  /** Each Repo Slot's Binding base, where the Binding names one: a cut with no `from` starts here. */
+  bases?: Record<string, string>;
 };
 
 const byRef = new WeakMap<AnyActorRef, AmbientHandles>();