@jr2/orchestrator 0.2.1 → 0.4.1

package/src/timers.ts

@@ -0,0 +1,178 @@
+// A run's pending timers across a restart (ADR-0007).
+//
+// xstate 5 keeps a delayed event (`after`, a named delay, a delayed `raise` or `sendTo`) on the
+// actor SYSTEM's scheduler, not in the Machine snapshot. `getPersistedSnapshot()` carries no trace
+// of it, and a restored actor runs no entry actions again, so nothing schedules it again: the
+// timer is lost, not restarted. xstate 5 has a `snapshot.scheduler` seam in `createSystem`, but
+// the Actor constructor never passes it.
+//
+// So the run host records each pending timer's absolute DEADLINE beside the snapshot, in the same
+// blob, and schedules it again on the restored system after `start()`. The author writes plain
+// `after`. The scheduled id is xstate's own (`xstate.after.<delay>.<stateId>` for an `after`), so
+// the state's exit `cancel(id)` still cancels a re-armed timer.
+//
+// This reads an xstate INTERNAL: `system.getSnapshot()._scheduledEvents` (typed in xstate's
+// `ActorSystem`, but underscored), `system.scheduler.schedule`, and `system.scheduler.cancel`
+// (wrapped for the length of `start()`). An xstate bump can break it; the raw-xstate tests in
+// test/timers.test.ts are the canary. xstate 6 persists timers in the snapshot and re-arms them
+// itself, with the same deadline and clamp: on xstate 6, delete this module.
+
+import type { AnyActorRef, EventObject } from "xstate";
+
+/** One pending delayed event, JSON-safe. An actor is named by its path of child ids below the
+ * run's root (`[]` is the root). */
+export type PendingTimer = {
+  source: string[];
+  target: string[];
+  /** xstate's scheduled id. */
+  id: string;
+  event: EventObject;
+  /** The delay as last scheduled, ms: the upper bound on what remains (see {@link startAndRearm}). */
+  delay: number;
+  /** Wall-clock ms at which it is due, on the host's clock (`now`). */
+  deadline: number;
+};
+
+function childrenOf(ref: AnyActorRef): Record<string, AnyActorRef> {
+  return (ref.getSnapshot() as { children?: Record<string, AnyActorRef> }).children ?? {};
+}
+
+function pathOf(root: AnyActorRef, ref: AnyActorRef, path: string[] = []): string[] | undefined {
+  if (ref === root) return path;
+  for (const [id, child] of Object.entries(childrenOf(root))) {
+    const found = pathOf(child, ref, [...path, id]);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+function refAt(root: AnyActorRef, path: string[]): AnyActorRef | undefined {
+  let ref: AnyActorRef | undefined = root;
+  for (const id of path) ref = ref && childrenOf(ref)[id];
+  return ref;
+}
+
+/** xstate's key for a scheduled event: one per source actor and id. */
+const keyOf = (source: AnyActorRef, id: string) => `${source.sessionId}.${id}`;
+
+const clamp = (ms: number, delay: number) => Math.min(delay, Math.max(0, ms));
+
+/**
+ * The run's pending timers, read off its actor system. Call at persist time: the scheduler's table
+ * and the snapshot are read in the same tick, so they agree. A timer whose source or target is not
+ * in the run's tree (a delayed send to an actor outside it) is not recorded; jr2 has no such idiom.
+ *
+ * xstate stamps a timer's start with `Date.now()`, so the time that remains is read on that clock;
+ * the deadline is `now + remaining`, on the host's clock. With the default `now` the two are one
+ * clock and the deadline is xstate's own `startedAt + delay`.
+ */
+export function pendingTimers(root: AnyActorRef, now = Date.now()): PendingTimer[] {
+  const wall = Date.now();
+  const out: PendingTimer[] = [];
+  for (const s of Object.values(root.system.getSnapshot()._scheduledEvents)) {
+    const source = pathOf(root, s.source);
+    const target = pathOf(root, s.target);
+    if (!source || !target) continue;
+    const remaining = clamp(s.startedAt + s.delay - wall, s.delay);
+    out.push({ source, target, id: s.id, event: s.event, delay: s.delay, deadline: now + remaining });
+  }
+  return out;
+}
+
+/**
+ * The pending delayed events whose TARGET is `ref`, from any source: what Rest asks (rest.ts) —
+ * an `after`, a named delay, a delayed `raise` or `sendTo(self)`, a child's delayed `sendParent`.
+ * The same table {@link pendingTimers} persists and {@link startAndRearm} re-arms, so Rest reads
+ * the same timers after a restore as before it.
+ */
+export function scheduledFor(ref: AnyActorRef): Array<{ id: string; event: EventObject }> {
+  return Object.values(ref.system.getSnapshot()._scheduledEvents)
+    .filter((s) => s.target === ref)
+    .map((s) => ({ id: s.id, event: s.event }));
+}
+
+/**
+ * Watch a run's actor system for timers that FIRE: the returned function says whether one relayed
+ * event is a timer the system scheduled — an `after`, a named delay, a delayed `raise` or `sendTo` —
+ * and not an event an actor sent at once. Both reach the inspection stream from the same source with
+ * the same shape; only the scheduler knows the difference, and it forgets a timer as it fires it.
+ *
+ * So `scheduler.schedule` and `scheduler.cancel` are wrapped for the life of the system: each armed
+ * timer is kept by its key with the event object xstate relays when it fires (the same object, not
+ * a copy). A relayed event is a fired timer when its source and event object are an armed timer's
+ * and that timer is no longer in the scheduler's table; it is then forgotten. A re-armed timer
+ * (`startAndRearm`) goes through the same `schedule`, so a restored run recognises it too.
+ *
+ * Install it before `start()` (the root's creation event is early enough): a timer armed before the
+ * wrap is not seen. The same xstate internals as the rest of this module; the canary is the same.
+ */
+export function watchTimers(system: AnyActorRef["system"]): (source: unknown, event: unknown) => boolean {
+  const scheduler = system.scheduler;
+  const { schedule, cancel } = scheduler;
+  const armed = new Map<string, { source: AnyActorRef; event: EventObject }>();
+  scheduler.schedule = (source, target, event, delay, id = Math.random().toString(36).slice(2)) => {
+    schedule(source, target, event, delay, id);
+    armed.set(keyOf(source, id), { source, event });
+  };
+  scheduler.cancel = (source, id) => {
+    armed.delete(keyOf(source, id));
+    cancel(source, id);
+  };
+  return (source, event) => {
+    for (const [key, row] of armed) {
+      if (row.event !== event || row.source !== source) continue;
+      if (key in system.getSnapshot()._scheduledEvents) continue;
+      armed.delete(key);
+      return true;
+    }
+    return false;
+  };
+}
+
+/**
+ * Start a restored run, then schedule each recorded timer again on it. One function, so the order
+ * cannot be got wrong: re-armed BEFORE `start()`, a timer is armed twice and fires twice, because
+ * the system's own `start()` schedules whatever is already in its table; and `start()` is where
+ * xstate builds the children, so a child's path resolves only after it.
+ *
+ * `start()` drains the mailbox: a child that sends on start (an author's `fromCallback`) can move
+ * the Machine out of a state before any timer is re-armed. That exit's `cancel(id)` finds nothing
+ * armed yet. So every cancel during `start()` is recorded, and a row it names is not re-armed: a
+ * state exit cancels the timer whether it happens during `start()` or after it.
+ *
+ * A child stopped during `start()` takes its timers with it, but xstate stops a child with
+ * `scheduler.cancelAll`, which walks the table, and the table is still empty: no cancel is seen.
+ * If its parent state is entered again, a NEW child sits at the same path. So each row's actors are
+ * resolved BEFORE `start()` (the restored tree already holds them), and a row is re-armed only on
+ * the same actors after it. A row of a stopped child then fires into nothing, not into its
+ * replacement.
+ *
+ * Remaining time is `deadline - now`, clamped to `[0, delay]`. A deadline that passed while the
+ * Orchestrator was down fires at once. A wall clock that went BACKWARDS cannot push a timer past its
+ * own delay. A wall clock that jumped forwards fires a timer early: only the wall clock survives a
+ * process, so the deadline is a wall-clock time. Rows are scheduled in deadline order, so timers
+ * that are all overdue (remaining 0) fire in the order they fell due, as in an uninterrupted run.
+ */
+export function startAndRearm(root: AnyActorRef, timers: readonly PendingTimer[], now = Date.now()): void {
+  const scheduler = root.system.scheduler;
+  const cancel = scheduler.cancel;
+  const cancelled = new Set<string>();
+  const rows = [...timers]
+    // `sort` is stable: equal deadlines keep the order xstate scheduled them in.
+    .sort((a, b) => a.deadline - b.deadline)
+    .map((t) => ({ t, source: refAt(root, t.source), target: refAt(root, t.target) }));
+  scheduler.cancel = (source, id) => {
+    cancelled.add(keyOf(source, id));
+    cancel(source, id);
+  };
+  try {
+    root.start();
+  } finally {
+    scheduler.cancel = cancel;
+  }
+  for (const { t, source, target } of rows) {
+    if (!source || !target || cancelled.has(keyOf(source, t.id))) continue;
+    if (refAt(root, t.source) !== source || refAt(root, t.target) !== target) continue;
+    scheduler.schedule(source, target, t.event, clamp(t.deadline - now, t.delay), t.id);
+  }
+}

package/src/tokens.ts

@@ -1,24 +1,32 @@
 // Bearer tokens (ADR-0013), because the Sandbox boundary is otherwise theater. The Harness
 // container shares the pod's network namespace, so an Agent can reach the Orchestrator directly;
-// a per-pod NetworkPolicy cannot distinguish its packets from the Adapter's. Only authentication
+// a per-pod NetworkPolicy cannot distinguish its packets from the Custodian's. Only authentication
 // closes this, and only the token bounds what a caller may DO (as opposed to where it may talk).
 //
-// Two principals, and the asymmetry between them is the whole design:
+// Three principals. The asymmetry between the first two is the whole design; the third is a door
+// key, not a seat:
 //
 //   Instance token  the human/CLI credential. Full trust: gates, run control, agent surfaces.
 //                   From the instance Secret (`JR2_INSTANCE_TOKEN`); minted per boot when absent,
 //                   announced once on stdout (fixtures capture it). An Agent never has it — it
 //                   never enters a Sandbox.
 //
-//   Sandbox token   the Adapter's credential. Authorizes exactly: deliver to `kind: "agent"`
+//   Publish token   `jr2 up`'s credential for `PUT /assembly` alone (ADR-0069). A publish imports
+//                   code into the process that holds the ServiceAccount, so it must cost what an
+//                   image roll cost: cluster write access. From the instance Secret
+//                   (`JR2_PUBLISH_TOKEN`), read by `jr2 up` through the kube API only. Every other
+//                   route answers it 403: it is a known token, but not one that route accepts.
+//
+//   Sandbox token   the Custodian's credential. Authorizes exactly: deliver to `kind: "agent"`
 //                   registrations whose Sandbox is THIS one. Never a Gate (a compromised Agent
 //                   must not approve its own review), never another Sandbox (`coding.ts`'s iids
 //                   are derivable and feature ids are readable from the Work Source, so a merely
 //                   run-scoped token would let one feature's coder inject a verdict into another
-//                   feature's reviewer). Delivered as a Secret via the CR's `envFrom` into the
-//                   Adapter container ALONE, which is the one place the Agent cannot read.
+//                   feature's reviewer). Delivered as a Secret mounted into the Custodian
+//                   container ALONE, which the Agent cannot read; the Harness holds its
+//                   Stand-in (ADR-0059).
 //                   The signed name is a POD hosting Turns, not a Sandbox CR per se: the Instance
-//                   Harness's Adapter bears one signed for that placement's Service name
+//                   Harness's Custodian holds one signed for that placement's Service name
 //                   (ADR-0031), scoping it to the Menu-only registrations placed there.
 //
 // And one bearer the other way (ADR-0058), which is no principal here because this server never
@@ -32,7 +40,7 @@
 // verified by recomputing. Three things fall out that a token table would have to work for — the
 // Orchestrator holds no per-Sandbox state, `provision` stays idempotent (re-minting yields the same
 // token, so a re-applied Secret is a no-op), and a token minted before a restart still verifies
-// after one, which is exactly what ADR-0012's re-attach promises the still-running Adapter.
+// after one, which is exactly what ADR-0012's re-attach promises the still-running Custodian.
 
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
@@ -42,7 +50,10 @@ import { join } from "node:path";
 export type Principal =
   /** The instance's own operator: the CLI, a human, a webhook translator holding the token. */
   | { kind: "instance" }
-  /** One Sandbox's Adapter, speaking for the Agent in that pod — and for no one else. */
+  /** `jr2 up`, publishing an Assembly (ADR-0069). Only `PUT /assembly` accepts it: it is not an
+   * Instance principal, so it reads no run and starts none. */
+  | { kind: "publisher" }
+  /** One Sandbox's Custodian, speaking for the Agent in that pod — and for no one else. */
   | { kind: "sandbox"; sandbox: string };
 
 /** Resolve a bearer token to a principal; undefined = not a token we minted (→ 401). */
@@ -76,7 +87,20 @@ export function harnessTokenDigest(key: Buffer, placement: string): string {
   return createHash("sha256").update(harnessToken(key, placement)).digest("base64url");
 }
 
-/** Mint the per-boot Instance token (opaque and random — it names nothing, it just IS the trust). */
+/**
+ * The signing key of one Effector placement (ADR-0068): `HMAC(signing key, "effector:" + placement)`,
+ * as the Harness bearer is derived (ADR-0058). The Orchestrator signs every request to that
+ * Effector with it and verifies every answer; the Effector reads it from a file in its own mount,
+ * which `jr2 up` writes (`instance` → the `jr2-instance-effector` Secret). Derived, not stored: a
+ * restarted Orchestrator derives the key a live Effector already holds. The `effector:` prefix
+ * keeps it apart from every Sandbox token and Harness bearer. The key's bytes are this string's.
+ */
+export function effectorKey(key: Buffer, placement: string): string {
+  return sign(key, `effector:${placement}`);
+}
+
+/** Mint the per-boot Instance token (opaque and random — it names nothing, it just IS the trust).
+ * The publish token is minted the same way when the Secret supplies none (ADR-0069). */
 export function mintInstanceToken(): string {
   return randomBytes(32).toString("base64url");
 }
@@ -85,7 +109,7 @@ export function mintInstanceToken(): string {
  * The instance's HMAC signing key, at `<dir>/.jr2/secret` (0600), created on first use.
  *
  * It MUST outlive the process: an Orchestrator restart leaves live Sandboxes running (ADR-0012 re-attach),
- * and their Adapters still hold tokens minted by the process that died. A fresh key would reject
+ * and their Custodians still hold tokens minted by the process that died. A fresh key would reject
  * every one of them — the Agent would silently lose its only route to its Machine.
  */
 export async function loadSigningKey(dir: string): Promise<Buffer> {
@@ -108,10 +132,16 @@ export async function loadSigningKey(dir: string): Promise<Buffer> {
  * A token we did not mint resolves to nothing, and the caller is refused — there is no anonymous
  * principal, and no route decides for itself whether it needs one.
  */
-export function createAuthenticator(opts: { instanceToken: string; signingKey: Buffer }): Authenticator {
+export function createAuthenticator(opts: {
+  instanceToken: string;
+  signingKey: Buffer;
+  /** The publish token (ADR-0069). Absent → no bearer resolves to the publisher. */
+  publishToken?: string;
+}): Authenticator {
   return (bearer) => {
     if (!bearer) return undefined;
     if (constantTimeEqual(bearer, opts.instanceToken)) return { kind: "instance" };
+    if (opts.publishToken !== undefined && constantTimeEqual(bearer, opts.publishToken)) return { kind: "publisher" };
     const cut = bearer.lastIndexOf(".");
     if (cut <= 0) return undefined;
     const sandbox = bearer.slice(0, cut);
@@ -130,6 +160,7 @@ export function createAuthenticator(opts: { instanceToken: string; signingKey: B
  */
 export function mayDeliverToAgent(principal: Principal, registrationSandbox: string | undefined): boolean {
   if (principal.kind === "instance") return true;
+  if (principal.kind !== "sandbox") return false;
   return registrationSandbox !== undefined && registrationSandbox === principal.sandbox;
 }
 
@@ -137,10 +168,11 @@ export function mayDeliverToAgent(principal: Principal, registrationSandbox: str
  * May this principal ask for a fetch on this Sandbox (ADR-0053)? A Sandbox token may ask for its
  * OWN pod and no other — the scope is the caches that pod mounts, and the route refuses a Repo it
  * does not. The Instance token may, on the same grounds it may deliver to any agent surface: it is
- * the operator. Nothing else can hold either, so there is no third case.
+ * the operator. The publish token may not: it opens the publish door and no other (ADR-0069).
  */
 export function mayAskForSandbox(principal: Principal, sandbox: string): boolean {
   if (principal.kind === "instance") return true;
+  if (principal.kind !== "sandbox") return false;
   return principal.sandbox === sandbox;
 }
 

package/src/vocabulary.ts

@@ -54,10 +54,32 @@ export function vocabularyOf(machine: AnyStateMachine): Map<string, EventDef> |
  * silently accepting a name nobody declared.
  */
 export function invokingMachine(self: AnyActorRef): AnyStateMachine | undefined {
-  const logic = (self._parent as { logic?: unknown } | undefined)?.logic as AnyStateMachine | undefined;
+  // An Open body's actor (ADR-0070) delegates to the Machine compiled from the Chart it binds, and
+  // its own logic is no Machine: the bound Machine is the scope of the Agents and Gates its states
+  // invoke, so it is asked first.
+  const parent = self._parent;
+  const bound = parent ? boundMachines.get(parent) : undefined;
+  if (bound) return bound;
+  const logic = (parent as { logic?: unknown } | undefined)?.logic as AnyStateMachine | undefined;
   return logic?.root ? logic : undefined;
 }
 
+// The Machine an Open body's actor runs (ADR-0070): compiled from the Chart the run bound, per
+// actor, at start and again at restore. Keyed on the ACTOR, not on a config: two runs of one
+// wrapper bind two Charts under the same slot. Kept here, beside the vocabulary, so this module
+// stays a leaf: open-body.ts writes it, and `invokingMachine` reads it.
+const boundMachines = new WeakMap<AnyActorRef, AnyStateMachine>();
+
+/** Record the Machine an Open body's actor runs. jr2-internal: the Open body's logic calls it. */
+export function attachBoundMachine(actor: AnyActorRef, machine: AnyStateMachine): void {
+  boundMachines.set(actor, machine);
+}
+
+/** The Machine an Open body's actor runs, or undefined for any other actor. */
+export function boundMachineFor(actor: AnyActorRef): AnyStateMachine | undefined {
+  return boundMachines.get(actor);
+}
+
 // The declared run input (ADR-0033): the one piece of a machine's vocabulary the event defs
 // missed — what a run of it is STARTED with. Same key choice as the vocabulary above, for the
 // same reasons (per-machine attribution, no global registry, transparent across `.provide()`).
@@ -79,6 +101,49 @@ export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined
   return inputSchemas.get(machine.config);
 }
 
+// Who may send what, per state (ADR-0015): the seats the menu-derivation walk computed. Same key
+// choice as the vocabulary, for the same reasons. The Machine's doc carries them; `jr2 up` and the
+// Console show them, so an author reads the audience rule's answer for their own Machine.
+
+/** One party's seat on one state: the state's id, the party, and the names it may send there —
+ * for an Agent the derived set its guards narrow; for a Gate its accepted set, unless the Gate's
+ * input names `accepts:` itself. */
+export type MachineSeat = { state: string; party: "agent" | "gate"; agent?: string; names: string[] };
+
+const seatTables = new WeakMap<MachineKey, MachineSeat[]>();
+
+/** Attach a Machine's seats. jr2-internal: `jr2Setup.createMachine` calls it. */
+export function attachSeats(machine: AnyStateMachine, seats: MachineSeat[]): void {
+  seatTables.set(machine.config, seats);
+}
+
+/** The seats of a Machine built by `jr2Setup`, in walk order; empty for any other Machine. */
+export function seatsOf(machine: AnyStateMachine): MachineSeat[] {
+  return seatTables.get(machine.config) ?? [];
+}
+
+/** One line per seat — `<state> agent:<slot>: [names]` or `<state> gate: [names]`. */
+export function seatLine(seat: MachineSeat): string {
+  const party = seat.party === "agent" ? `agent:${seat.agent}` : "gate";
+  return `${seat.state} ${party}: [${seat.names.join(", ")}]`;
+}
+
+const loadWarnings = new WeakMap<MachineKey, string[]>();
+
+/** Attach the load warnings `jr2Setup.createMachine` found (ADR-0015). jr2-internal. */
+export function attachLoadWarnings(machine: AnyStateMachine, warnings: string[]): void {
+  loadWarnings.set(machine.config, warnings);
+}
+
+/** What the build found legal and suspect — a mode nothing enters, a pick a Gate above takes from
+ * the Agent below, one name written for two parties on one path. `jr2 up` prints them; the
+ * Machine's doc carries them. A Machine `customize()` bound an Open argv in is rebuilt around a
+ * config of its own, which carries the walk's findings for the bound argv (ADR-0054). Empty for a
+ * Machine not built by `jr2Setup`. */
+export function loadWarningsOf(machine: AnyStateMachine): string[] {
+  return loadWarnings.get(machine.config) ?? [];
+}
+
 /**
  * What the HOST adds to the input of the machine a run STARTS with, beside the door
  * (`RunHost.start`). One field today: the run's seed Instance ID, minted with the run and

package/src/wire.ts

@@ -28,6 +28,11 @@ export const SUBMISSION_ABORTED = "submission_aborted";
  * on the class (one fresh-conversation reroll) without parsing prose. */
 export const SUBMISSION_RUNAWAY = "runaway";
 
+/** `SettlementError.type` for a Submission the Harness admitted but had not settled when it
+ * restarted (ADR-0031): the rebuilt stream settles it `failed`, so a re-attached `wait` reads a
+ * Settlement, not a 404. The Agent actor switches on this type, never on the message's prose. */
+export const SUBMISSION_HARNESS_RESTARTED = "harness_restarted";
+
 /** One settled Submission, in the shape `?view=history`'s `settlements` reports. */
 export type Settlement = {
   submissionId: string;
@@ -51,19 +56,97 @@ export type MessageAppendedEvent = StreamChunk<"message-appended"> & {
  * a parked long-poll. */
 export type SubmissionSettledEvent = StreamChunk<"submission-settled"> & Settlement;
 
+/**
+ * The Harness's memory guard killed the Agent's processes (ADR-0061, layer 4), on the stream of the
+ * conversation whose Turn was running. The Agent heard it in its `bash` answer; this is how the
+ * Orchestrator hears it, so the next Turn in the Workspace is told (ADR-0062). `peak` and `limit`
+ * are the guard's own spellings — carried to the notice as they are, never parsed.
+ */
+export type MemoryLimitEvent = StreamChunk<"memory-limit"> & { peak: string; limit: string };
+
 /** One event on the durable stream (`GET ?offset=…&view=updates` → 200 JSON array). */
-export type StreamEvent = MessageAppendedEvent | SubmissionSettledEvent;
+export type StreamEvent = MessageAppendedEvent | SubmissionSettledEvent | MemoryLimitEvent;
+
+// ---- Notices (ADR-0062) ------------------------------------------------------------------------
+// What happened that the next Turn cannot find out for itself, as DATA: the Orchestrator keeps
+// them and attaches the pending ones in scope to an admission (`AdmissionRequest.notices`); the
+// Harness writes every word of the Briefing's Turn part from them.
+
+/** The Sandbox's processes were killed at its memory limit during `agent`'s Turn — by the
+ * Harness's guard (`peak` known) or by the kernel (`peak` unknown). Workspace scope: the next Turn
+ * of any Agent in that Workspace. */
+export type MemoryLimitNotice = {
+  kind: "memory-limit";
+  scope: "workspace";
+  agent: string;
+  peak?: string;
+  limit: string;
+};
+
+/** This conversation is new; earlier context is gone. Conversation scope: that Agent's next
+ * continued Turn. `reason` says why — the fault that burned the last one, or that the Harness no
+ * longer holds it. */
+export type ConversationNewNotice = { kind: "conversation-new"; scope: "conversation"; reason: string };
+
+/**
+ * What an outstanding pick's answer is (ADR-0024): the LAST reply from below the Agent's state since
+ * the pick — a party's event (a Gate's answer, a nested Agent's pick) with its payload, or a child's
+ * output (a child Machine, an Effect stand-in) — named by who sent it. A child's error is no reply (a
+ * defect, ADR-0024). Absent where nothing replied: the answer carries no reply, and says nothing of
+ * whether work ran. Plain data; the Harness writes the words. `answer`: the value the Machine's
+ * `answer` action set (ADR-0067), which replaces the default.
+ */
+export type PickAnswer =
+  | { kind: "event"; event: string; sender?: { party: "agent" | "gate"; id: string }; payload: Record<string, unknown> }
+  | { kind: "output"; actor: string; output: unknown }
+  | { kind: "answer"; value: unknown };
+
+/**
+ * A pick's answer that did not reach the pick's call (ADR-0024): `cut` — the Harness restarted while
+ * the workflow ran it, and jr2 re-admits the Agent on the same conversation with this notice; or the
+ * route left the Agent's state, and the next Turn of the conversation the picking Turn continued
+ * hears it. Conversation scope.
+ */
+export type PickAnswerNotice = {
+  kind: "pick-answer";
+  scope: "conversation";
+  pick: string;
+  cut: boolean;
+  /** The last reply since the pick — with `stopped`, an earlier link's, kept. */
+  answer?: PickAnswer;
+  /** Something other than the pick's route left the Agent's state while the pick's work ran, and
+   * that exit stopped the work before it finished (ADR-0024). */
+  stopped?: true;
+};
+
+export type Notice = MemoryLimitNotice | ConversationNewNotice | PickAnswerNotice;
 
 /** Response header: the offset to resume the stream from (every stream read carries it). */
 export const STREAM_NEXT_OFFSET_HEADER = "stream-next-offset";
 
-/** `?view=` value the client reads. A read with neither view is `updates`. */
+/** `?view=` values the client reads. A read with neither view is `updates`; `history` is the
+ * conversation snapshot, read only to learn whether the Harness still holds it (ADR-0062). */
 export const VIEW_UPDATES = "updates";
+export const VIEW_HISTORY = "history";
 
 /** `?live=` value: park until a new event or timeout (204 + the same headers). Long-poll is the
  * ONLY wait transport (ADR-0027) — no SSE, no `?wait=result`. */
 export const LIVE_LONG_POLL = "long-poll";
 
+// ---- The live set (`PUT /agents` — ADR-0031) ----------------------------------------------------
+// The Orchestrator states which conversations its live runs hold on the Instance Harness, and the
+// Harness frees every other one that is not busy. The whole set every time (level-triggered), so a
+// missed statement costs nothing.
+
+/** One conversation a live run holds: the `:name` and `:id` of its `/agents/:name/:id` route. */
+export type LiveConversation = { agent: string; instanceId: string };
+
+/** What `PUT /agents` accepts: every conversation the Orchestrator's live runs hold. */
+export type LiveSetRequest = { live: LiveConversation[] };
+
+/** What `PUT /agents` answers (200): how many conversations this statement freed. */
+export type LiveSetResponse = { freed: number };
+
 // ---- The run-narrative echo (`POST /echo` — ADR-0023) ------------------------------------------
 // "Print these events": the Orchestrator — the observation feed's one subscriber (ADR-0022) — tees
 // the owning run's feed to the enclosing Workspace's Harness, which renders it into its own pod log.
@@ -101,3 +184,74 @@ export type EchoEvent = EchoStatusEvent | EchoEmitEvent | EchoAdmissionEvent | E
 /** What `POST /echo` accepts: feed events in feed order. The answer is `{ printed }` — how many
  * lines landed on stdout (an unrenderable event prints nothing; it never errors the batch). */
 export type EchoRequest = { events: EchoEvent[] };
+
+// --- the attach (ADR-0063) ----------------------------------------------------------------------
+// The Workspace's Repos into `/work`, run by the Harness on `POST /attach` — the Orchestrator's
+// call where it once ran a script over `kubectl exec`. Same bearer as every Harness route
+// (ADR-0058); idempotent on the Harness's side.
+
+/** One Repo Slot to attach. The Orchestrator resolves the Repo's `identity` and cache `key`
+ * (repo-identity.ts) — the Harness never re-derives them, so the cache it clones from and the node
+ * cache the operator mounted agree by construction (ADR-0051). `url` is the Binding's own spelling,
+ * the push url (ADR-0005); `ref` is the base the branch starts from, omitted for the Repo's default
+ * branch. */
+export type AttachSlot = { slot: string; url: string; identity: string; key: string; ref?: string };
+
+/** What `POST /attach` accepts: the slots in declaration order, the Workspace's branch, and — for a
+ * reviewer's seat — the sha the detached review worktree is forced to (ADR-0028). */
+export type AttachRequest = { slots: AttachSlot[]; branch: string; reviewSha?: string };
+
+/** What `POST /attach` answers (200): the branch worktree per slot, and the review worktree per
+ * slot when the request named a `reviewSha`. Freshness is the operator's verdict on the Sandbox,
+ * which the Orchestrator reads itself — never the Harness's to report. */
+export type AttachResponse = { repos: Record<string, string>; review?: Record<string, string> };
+
+/** What a failed attach answers: 400 for a body that is not an `AttachRequest`, 500 when a step
+ * failed — `slot` names the Repo Slot, and `error` carries the step and git's own stderr. */
+export type AttachError = { error: string; slot?: string };
+
+// --- the exec (a `command` Effect, ADR-0067) ----------------------------------------------------
+// A `command` Effect runs in the Harness container of its Workspace's Sandbox, named by its
+// Effect's id: one id runs once, whoever asks again. Same bearer as every Harness route (ADR-0058).
+
+// --- the sync (ADR-0067) ------------------------------------------------------------------------
+// After a push whose published commit is not the Agent's own — signed copies of its commits, or
+// one squashed commit, signed or not — the sync moves the Agent's branch to it, here, in the
+// Harness container, with one `update-ref` (files, index, HEAD and stash do not change). The
+// bundle of the published commits travels through the Orchestrator. Same bearer as every Harness route (ADR-0058).
+
+/** What `POST /sync` accepts: the branch Worktree (absolute, under `/work`), the branch, the pair
+ * the push published (`published`, the published tip; `source`, the Agent's commit it re-creates) and,
+ * when the push just ran, the bundle of the published commits (base64). With no bundle the published
+ * commits must already be in the Agent's store (a sync run again). */
+export type SyncRequest = { worktree: string; branch: string; published: string; source: string; bundle?: string };
+
+/** What the sync answers — a report, which the next push never trusts. `synced`: the branch moved
+ * (`replayed` commits the Agent made after the push were copied onto the published tip). `already`:
+ * the branch holds the published tip. `skipped`: the push published the Agent's own commit. `busy`: a rebase, merge,
+ * cherry-pick or revert of the branch is in progress; nothing changed. `not-synced`: the branch
+ * did not move (`reason` says why). */
+export type SyncAnswer =
+  | { sync: "synced"; from: string; to: string; replayed: number; tries: number }
+  | { sync: "already" }
+  | { sync: "skipped" | "busy" | "not-synced"; reason: string };
+
+/** What `POST /exec/:id` accepts: argv (never shell text), an absolute `cwd` or none, the timeout,
+ * and how many characters of the stream's end the output keeps. */
+export type ExecRequest = { argv: string[]; cwd?: string; timeoutMs: number; tail: number };
+
+/** How an exec ended. Every one is output; none is a fault. */
+export type ExecOutcome =
+  | { outcome: "exited"; code: number; tail: string }
+  | { outcome: "timeout"; tail: string }
+  | { outcome: "killed"; signal: string; tail: string };
+
+/** What `GET /exec/:id` answers: the stream from `offset` to `next`, and the output once settled. A
+ * read with no `offset` starts at the end. */
+export type ExecRead = {
+  state: "running" | "settled";
+  stream: string;
+  next: number;
+  dropped?: number;
+  output?: ExecOutcome;
+};