@jr2/orchestrator 0.5.1 → 0.6.0

package/src/sandbox-kube.ts

@@ -43,7 +43,7 @@
 // containers:
 //
 //   volume        runtime     the kit's Harness image, as an `image` volume → /opt/jr2
-//   volume        conversations  an emptyDir → /conversations, the Harness container's alone
+//   volume        conversations  an emptyDir → /run/jr2/conversations, the Harness container's alone
 //                             (ADR-0031: a Harness restart inside the pod keeps its conversations)
 //   initContainer preflight   the USER'S image + that volume → ADR-0037's probe, the thing that
 //                             proves a registry ref, whose first appearance is this provision
@@ -83,11 +83,14 @@ import {
   custodianBootstrap,
   custodianComposition,
   custodianScript,
+  CREDENTIAL_KEYS,
+  heldStandInKey,
   CUSTODIAN_BOOTSTRAP_KEY,
   CUSTODIAN_SCRIPT_KEY,
   type CustodianComposition,
 } from "./custodian.ts";
-import { readHeldManifest, workspaceHeldPod, type HeldManifest } from "./held-secrets.ts";
+import { heldStandIn, readHeldManifest, workspaceHeldPod, type HeldManifest } from "./held-secrets.ts";
+import { markHarnessEnv } from "./harness-env.ts";
 import {
   effectorManifestKey,
   readSandboxEffectorManifest,
@@ -133,10 +136,14 @@ import {
   type SandboxObject,
   type SandboxWatch,
 } from "./sandbox-watch.ts";
-import { effectorKey, harnessToken, harnessTokenDigest, sandboxToken } from "./tokens.ts";
+import { controlStandIn, controlToken, effectorKey, harnessToken, harnessTokenDigest, sandboxToken } from "./tokens.ts";
 import type { AttachError, AttachRequest, AttachResponse } from "./wire.ts";
 import type { Continuity, MemoryKill, PlacingWait, ProvisionedRepo, SandboxLoss, SandboxPort } from "./workspace.ts";
 
+/** A Secret's `data`: each value base64'd. */
+const base64Values = (values: Record<string, string>): Record<string, string> =>
+  Object.fromEntries(Object.entries(values).map(([k, v]) => [k, Buffer.from(v).toString("base64")]));
+
 /** Where jr2's runtime lands in every container that gets it (ADR-0037). `/opt/jr2` and not `/app`
  * because a stranger's base may already use `/app`, and one layout must serve both the stock
  * Harness image and an arbitrary Sandbox Image. It is a PUBLISHED surface: `bin/` beside `lib/`
@@ -156,11 +163,21 @@ const RUNTIME_VOLUME_MOUNT = { name: RUNTIME_VOLUME, mountPath: RUNTIME_MOUNT, s
 /** The primary container's command (ADR-0037). Absolute, so it never depends on the image's
  * `WORKDIR`, and identical to the stock Harness image's own `CMD` — one runtime, two placements.
  * `tini` is PID 1 (ADR-0061): the Agent's processes are the Harness's children, and a tree the
- * memory guard kills must leave no zombies behind. */
+ * memory guard kills must leave no zombies behind. The Harness holds the Stand-ins in its memory,
+ * and below Landlock ABI 6 a confined child can still signal it (ADR-0076): `effector nocore`
+ * starts it with no core file, so a dumping signal writes nothing a child reads, and
+ * `--disable-sigusr1` keeps SIGUSR1 from opening Node's inspector, which would run a child's code
+ * in the Harness. `--harness-env` gives the Harness process only the names jr2 composed, less each
+ * name that loads code from a path, and the domain the whole start env (`harness-env.ts`). */
 const HARNESS_COMMAND = [
   `${RUNTIME_MOUNT}/bin/tini`,
   "--",
+  `${RUNTIME_MOUNT}/bin/effector`,
+  "nocore",
+  "--harness-env",
+  "--",
   `${RUNTIME_MOUNT}/bin/node`,
+  "--disable-sigusr1",
   `${RUNTIME_MOUNT}/src/main.ts`,
 ];
 
@@ -834,8 +851,14 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
         // Never empty: the Custodian's address is unconditional. The seat's own vars (the fallback
         // `HOME`) come FIRST, so the instance's `harness.env` can still override them the way it
         // overrides anything the image set.
-        env: [...seat.env, ...harnessEnv(req.name, custodian, cpuHintEnv())],
-        ...(cfg().envFrom?.length ? { envFrom: cfg().envFrom } : {}),
+        // Marked (`harness-env.ts`, ADR-0076): the Harness's start tells jr2's names from the image's.
+        ...(() => {
+          const marked = markHarnessEnv(
+            [...seat.env, ...harnessEnv(req.name, custodian, cpuHintEnv())],
+            cfg().envFrom ?? [],
+          );
+          return { env: marked.env, ...(marked.envFrom.length ? { envFrom: marked.envFrom } : {}) };
+        })(),
         // What the AGENT gets: an address on its own loopback and a Stand-in for every credential,
         // and no credential anywhere. The Custodian beside it holds them (ADR-0013, ADR-0059).
         sidecars,
@@ -902,7 +925,7 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
    * `data`, not `stringData`: a server-side apply owns the fields it names, and `stringData` is
    * write-only — it never reads back as the field applied.
    */
-  const applyTokenSecret = async (name: string, owner: KubeObject): Promise<void> => {
+  const applyTokenSecret = async (name: string, owner: KubeObject, manifest: HeldManifest): Promise<void> => {
     if (!opts.signingKey) throw new Error("kubeSandbox: a Custodian needs a signingKey to mint its Sandbox token");
     const uid = owner.metadata?.uid;
     if (!uid) throw new Error(`Sandbox "${name}": the CR's apply answered with no uid to own its token Secret`);
@@ -925,7 +948,19 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
         ],
       },
       type: "Opaque",
-      data: { JR2_SANDBOX_TOKEN: Buffer.from(sandboxToken(opts.signingKey, name)).toString("base64") },
+      // The pod's credentials (ADR-0076, C1, C1b): its fetch token and its control token, which the
+      // Custodian alone mounts; its secret control Stand-in; and one secret Stand-in per held secret
+      // the pod's manifest names, which the Custodian (for its swap) and the Harness container (as
+      // files under `/run/jr2/`) mount. Every one a signed name, so a re-provision re-applies the
+      // same values. Never a ConfigMap, the CR, an env, an event or a log line.
+      data: base64Values({
+        [CREDENTIAL_KEYS.fetchToken]: sandboxToken(opts.signingKey, name),
+        [CREDENTIAL_KEYS.controlToken]: controlToken(opts.signingKey, name),
+        [CREDENTIAL_KEYS.controlStandIn]: controlStandIn(opts.signingKey, name),
+        ...Object.fromEntries(
+          manifest.secrets.map((s) => [heldStandInKey(s.name), heldStandIn(opts.signingKey!, name, s.name)]),
+        ),
+      }),
     });
   };
 
@@ -1030,7 +1065,7 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
       },
       data: {
         [CUSTODIAN_BOOTSTRAP_KEY]: JSON.stringify(custodianBootstrap(manifest, orchestrator)),
-        [CUSTODIAN_SCRIPT_KEY]: custodianScript(manifest),
+        [CUSTODIAN_SCRIPT_KEY]: custodianScript(manifest, { fetch: true }),
       },
     });
   };
@@ -1257,8 +1292,9 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
         image: refs.custodian,
         pod,
         config: sandboxCustodianConfigMap(req.name),
-        token: { secret: secretName(req.name), key: "JR2_SANDBOX_TOKEN" },
+        credentials: { secret: secretName(req.name) },
         sandbox: req.name,
+        ...(req.secrets?.length ? { granted: req.secrets } : {}),
         caBundle: cfg().caBundle === true,
         resources: split.custodian,
       });
@@ -1287,7 +1323,7 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
       sandboxes();
       const applied = await kube().apply(SANDBOXES, ns, cr).catch(noOperator(req.name, "Sandbox"));
       // After the CR: its uid owns both, so they go when it goes.
-      await applyTokenSecret(req.name, applied);
+      await applyTokenSecret(req.name, applied, manifest);
       await applyCustodianConfig(req.name, applied, manifest);
       if (effectorManifest) {
         await applyEffectorKey(req.name, applied);
@@ -1403,12 +1439,10 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
           const { identity, key } = repoIdentity(r.url);
           return { slot: r.slot, url: r.url, identity, key, ...(r.ref !== undefined ? { ref: r.ref } : {}) };
         }),
-        branch: req.spec.branch,
-        ...(req.spec.reviewSha ? { reviewSha: req.spec.reviewSha } : {}),
       };
-      const { repos, review } = await postAttach(req.name, endpoint, body);
+      const { repos, bases } = await postAttach(req.name, endpoint, body);
       const stale = staleSlots(req.repos, staleByName.get(req.name));
-      return { repos, ...(review ? { review } : {}), ...(stale ? { stale } : {}) };
+      return { repos, bases, ...(stale ? { stale } : {}) };
     },
 
     leaseIntervalMs,
@@ -1458,7 +1492,20 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
     async destroy(name) {
       staleByName.delete(name);
       // The token Secret is the CR's child from birth, so deleting the CR reaps it (ADR-0001).
-      await kube().delete(SANDBOXES, ns, name);
+      await kube().delete(SANDBOXES, ns, name, { foreground: true });
+      // A retry of the same invoke id takes the same name, and the pod takes it too: a new Sandbox
+      // must not find the old pod on its way out, and read `Lost` (ADR-0075). So the wait is
+      // for the pod as well: foreground keeps the CR until the pod is gone. Bounded: a stuck finalizer
+      // is the operator's to report, and the run does not wait on it for ever.
+      for (let i = 0; i < 120; i++) {
+        if (
+          (await kube()
+            .get<SandboxObject>(SANDBOXES, ns, name)
+            .catch(() => undefined)) === undefined
+        )
+          return;
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
     },
   };
 }

package/src/secret-placement.ts

@@ -151,8 +151,8 @@ export function refuseEffectSecrets(config: JR2Config, walk: PlacementWalk): voi
 /**
  * A Workspace with no Repo Slot (ADR-0051) has no branch and no commit, so the two Sandbox Effector kinds that
  * run on a commit of a slot's branch have none: a `push`, and a `command` with an Effect secret
- * (ADR-0067). Refused here, before anything is built, as the invoke would refuse them mid-run. A
- * file-body `http` reads `/work` and stays.
+ * (ADR-0067). A `worktree()` has no clone to cut from (ADR-0075). Refused here, before anything is
+ * built, as the invoke would refuse them mid-run. A file-body `http` reads `/work` and stays.
  */
 function refuseWithNoSlot(ws: PlacedWorkspace): void {
   if (!ws.pod.noSlot) return;
@@ -165,6 +165,13 @@ function refuseWithNoSlot(ws: PlacedWorkspace): void {
         `Slot: ${why} (ADR-0051)`,
     );
   }
+  const [cut] = ws.pod.cuts ?? [];
+  if (cut !== undefined) {
+    throw new Error(
+      `workflow "${ws.workflow}": worktree "${cut}" runs in ${workspaceLabel(ws)}, which has no Repo Slot: ` +
+        `${needsASlot("worktree")} (ADR-0075)`,
+    );
+  }
 }
 
 /**

package/src/setup.ts

@@ -29,6 +29,7 @@ import { randomUUID } from "node:crypto";
 import {
   setup,
   type ActionFunction,
+  type ActorLogic,
   type AnyActorRef,
   type AnyStateMachine,
   type DelayConfig,
@@ -39,6 +40,7 @@ import {
   type NonReducibleUnknown,
   type ParameterizedObject,
   type SetupReturn,
+  type Snapshot,
   type UnknownActorLogic,
 } from "xstate";
 import type { z } from "zod";
@@ -46,11 +48,12 @@ import { eventMap, type EventDef, type EventFrom, type Sender } from "@jr2/agent
 import type { AgentRunInput, AgentTurnInput, FaultTelemetry } from "./actor.ts";
 import { isAgent } from "./agent.ts";
 import { isEffect } from "./effect.ts";
-import { effectChecks } from "./effect-checks.ts";
+import type { AnyFramePath, FramePath, WorktreePath, WorktreeReady } from "./worktree.ts";
+import { effectChecks, refuseUnroutedOutcome } from "./effect-checks.ts";
 import { gate } from "./gate.ts";
 import { attachLent, isOpenBody, openBodyDeclarationOf, type LentParts } from "./open-body.ts";
 import { refuseInlineParts } from "./parts.ts";
-import { partyWarnings, refuseUnknownSentBy, SENT_BY, sentByGuard } from "./party.ts";
+import { partyWarnings, refuseSlotActiveTwice, refuseUnknownSentBy, SENT_BY, sentByGuard } from "./party.ts";
 import { refuseLostOutput } from "./run-output.ts";
 import { refuseUnroutedAgentFault } from "./mechanism-routes.ts";
 import { boundEpoch, boundRunId, continuedIid } from "./registration.ts";
@@ -130,6 +133,74 @@ type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
   [K in keyof TActors & string]: { src: K; logic: TActors[K]; id: string | undefined };
 }[keyof TActors & string];
 
+// The types below carry the body's Repo Slots to every Worktree input.
+/** @internal */
+type NoHandles = { readonly noHandles: true };
+/** `S`, the slots of the body, or {@link NoHandles} when its input and context hold no handles.
+ * @internal */
+type RepoSlotsOf<TInput, TContext> = TInput extends { workspace: { repos: infer R } }
+  ? keyof R & string
+  : TContext extends { workspace: { repos: infer R } }
+    ? keyof R & string
+    : NoHandles;
+/** The Worktrees of the slots `S` that this key takes: a `push({ slot })` keeps to its own slot.
+ * @internal */
+type PathIn<W, S> = S extends string ? (`/work/${S}/x` extends NonNullable<W> ? WorktreePath<S> : never) : never;
+/** One arm of an input. A key that names a Worktree or a Frame is REQUIRED under a body with Repo
+ * Slots, so that no mix of `cwd`, `worktree` and `path` lands in `/work`. Under a body with none,
+ * `worktree` goes: there is no Worktree. A Turn's arm that carries no kit path (the run's own form)
+ * and every other key stay.
+ * @internal */
+type BindArm<I, S> = I extends object
+  ? "worktree" extends keyof I
+    ? [S] extends [never]
+      ? Omit<I, "worktree"> & { worktree?: never }
+      : Omit<I, "worktree"> & { worktree: PathIn<I["worktree"], S> }
+    : "cwd" extends keyof I
+      ? [NonNullable<I["cwd"]>] extends [AnyFramePath]
+        ? [S] extends [never]
+          ? I
+          : Omit<I, "cwd"> & { cwd: FramePath<S & string> }
+        : I
+      : "path" extends keyof I
+        ? [S] extends [never]
+          ? I
+          : Omit<I, "path"> & { path: PathIn<I["path"], S> }
+        : I
+  : I;
+/** Does this input name a Worktree? @internal */
+type NamesWorktree<I> = I extends object ? ("worktree" extends keyof I ? true : never) : never;
+/** @internal */
+type BindInput<I, S> = [NamesWorktree<I>] extends [never]
+  ? BindArm<I, S>
+  : [S] extends [never]
+    ? BindArm<I, S>
+    : Exclude<BindArm<I, S>, void | undefined>;
+/** A cut's `ready` output with the body's slots. @internal */
+type BindOutput<O, S> = O extends WorktreeReady ? WorktreeReady<S & string> : O;
+/** @internal */
+type BindSnapshot<Snap, S> = Snap extends { output: infer O }
+  ? [O] extends [BindOutput<O, S>]
+    ? Snap
+    : Omit<Snap, "output"> & { output: BindOutput<O, S> }
+  : Snap;
+/** @internal */
+type BindLogic<L extends UnknownActorLogic, S> = L extends AnyStateMachine
+  ? L
+  : ([S] extends [never] ? false : [S] extends [NoHandles] ? true : false) extends true
+    ? L
+    : L extends { readonly definition: { readonly workspace: "none" } }
+      ? L
+      : L extends ActorLogic<infer Snap, infer Ev, infer I, infer Sys, infer Em>
+        ? BindSnapshot<Snap, S> extends infer B extends Snapshot<unknown>
+          ? Omit<L, keyof ActorLogic<Snap, Ev, I, Sys, Em>> & ActorLogic<B, Ev, BindInput<I, S>, any, Em>
+          : never
+        : L;
+/** @internal */
+type BindActors<A extends Record<string, UnknownActorLogic>, TInput, TContext> = {
+  [K in keyof A]: BindLogic<A[K], RepoSlotsOf<TInput, TContext>>;
+};
+
 /**
  * Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`. Write a Machine
  * with it when an Agent or a Gate sends events into the Machine, or when the Machine declares a
@@ -321,7 +392,7 @@ export function jr2Setup<
 ): SetupReturn<
   TContext,
   WorkflowEvent<TDefs>,
-  MergedActors<TActors>,
+  MergedActors<BindActors<TActors, TInput, TContext>>,
   {},
   TActions,
   TGuards & SentByGuards,
@@ -411,13 +482,20 @@ export function jr2Setup<
     // (ADR-0074): the run would wait for ever. Not in a compiled Chart: there the route is optional,
     // and the Open body sends the event that no transition takes to the Machine that invoked it (ADR-0070).
     if (compiledChart !== true) refuseUnroutedAgentFault(machine);
+    // An Effect's `onDone` with no last arm that always matches (ADR-0075): the run would stay in the
+    // state and show no fault. A compiled Chart comes here too, so the door refuses it.
+    refuseUnroutedOutcome(machine);
     refuseParallelBelowAgents(machine, def.actors ?? {});
+    // One slot, two Turns at once (ADR-0015): one sender and one conversation cannot hold both.
+    refuseSlotActiveTwice(machine);
     refuseUnknownSentBy(machine);
     // Before the Effect checks: they ask who may send a writing (`mayTake`), which reads its audience.
     attachVocabulary(machine, defs);
     // The Effect checks (ADR-0067): a pick param nothing reads, a `fill` that overwrites one, a
     // `fromPick` of another pick — refused; a mapper the probe cannot run — warned.
-    const effects = effectChecks(machine, def.actors ?? {}, defs);
+    // A Chart's door reads each reference itself (rule 7), and it refuses every load warning: the
+    // walk's "I could not run this" says nothing of a Chart's `{{...}}` mapper or its `set`.
+    const effects = effectChecks(machine, def.actors ?? {}, defs, compiledChart === true);
     if (effects.errors.length) throw new Error(`machine "${machine.id}": ${effects.errors.join("; ")}`);
 
     const idOf = (path: readonly string[]): string => stateAt(machine, path).id;
@@ -441,7 +519,7 @@ export function jr2Setup<
   return { ...inner, createMachine } as unknown as SetupReturn<
     TContext,
     WorkflowEvent<TDefs>,
-    MergedActors<TActors>,
+    MergedActors<BindActors<TActors, TInput, TContext>>,
     {},
     TActions,
     TGuards & SentByGuards,
@@ -1066,7 +1144,7 @@ function refuseUnknownKeys(consumer: object, agentName: string): void {
 /** Wrap an Agent slot's invoke input: name the Agent (the slot key), append the state's derived set
  * and the Agent's Menu, and finalize the mechanism fields. */
 function wrapAgentInput(orig: unknown, derived: string[], agentName: string, menuOf: (agentName: string) => string[]) {
-  return (args: InputArgs): AgentRunInput => {
+  const wrapped = (args: InputArgs): AgentRunInput => {
     const consumer = resolveInput(orig, args) as Partial<AgentTurnInput & AgentRunInput>;
     refuseUnknownKeys(consumer, agentName);
     return {
@@ -1097,6 +1175,8 @@ function wrapAgentInput(orig: unknown, derived: string[], agentName: string, men
       menu: menuOf(agentName),
     };
   };
+  // The walk reads what the author wrote: `workspace()`, for a literal `cwd`.
+  return Object.assign(wrapped, { consumerInput: orig });
 }
 
 /** Wrap a gate invoke input: append the derived accepted set. */

package/src/tokens.ts

@@ -17,17 +17,20 @@
 //                   (`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 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 Custodian holds one signed for that placement's Service name
-//                   (ADR-0031), scoping it to the Menu-only registrations placed there.
+//   Sandbox token   the Custodian's credentials, two of them, each valid on its own routes alone
+//                   (ADR-0076). Both are signed names of a POD hosting Turns — a Sandbox, or the
+//                   Instance Harness's Service name (ADR-0031) — and both live in the Custodian
+//                   container ALONE, which no Workspace code reaches (ADR-0059):
+//     control token   `agent:<pod>.<sig>`. Delivers to `kind: "agent"` registrations whose pod is
+//                   THIS one, and only for the slot the Harness states (`X-Jr2-Slot`), on the
+//                   four agent routes. The Harness process alone holds its secret Stand-in.
+//     fetch token     `<pod>.<sig>`. Asks for a fetch for THIS Sandbox (ADR-0053), on
+//                   `POST /sandboxes/<pod>/fetch` alone. Its Stand-in is public: it can do
+//                   nothing else.
+//                   Neither is ever a Gate's (a compromised Agent must not approve its own review),
+//                   and neither reaches another pod (`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).
 //
 // And one bearer the other way (ADR-0058), which is no principal here because this server never
 // checks it:
@@ -53,17 +56,53 @@ export type Principal =
   /** `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 };
+  /** One Sandbox's fetch token (ADR-0053, ADR-0076): asks for a fetch for that Sandbox, and does
+   * nothing else. */
+  | { kind: "sandbox"; sandbox: string }
+  /** One pod's control token (ADR-0076), with the slot the Harness stated for the conversation
+   * (`X-Jr2-Slot`): speaks on the agent routes for that slot's registrations in that pod, and for no
+   * other. */
+  | { kind: "agent"; sandbox: string; slot: string };
 
-/** Resolve a bearer token to a principal; undefined = not a token we minted (→ 401). */
-export type Authenticator = (bearer: string | undefined) => Principal | undefined;
+/** The header the Harness states a control request's slot in (ADR-0076): the Agent's actor path
+ * and agent name, its continued conversation's Instance ID without the run id. */
+export const SLOT_HEADER = "x-jr2-slot";
 
-/** The Sandbox token for one Sandbox: its name, signed. Same name + key → same token, always. */
+/** Resolve a bearer token, and the slot a control request states, to a principal; undefined = not a
+ * token we minted, or a control token with no slot (→ 401). */
+export type Authenticator = (bearer: string | undefined, slot?: string) => Principal | undefined;
+
+/** The fetch token for one Sandbox: its name, signed. Same name + key → same token, always. The
+ * bare form of ADR-0013's Sandbox token; since ADR-0076 it opens the fetch route alone. */
 export function sandboxToken(key: Buffer, sandbox: string): string {
   return `${sandbox}.${sign(key, sandbox)}`;
 }
 
+/** The domain of a control token's signed name (ADR-0076). No DNS label holds a `:`, so a control
+ * token is never read as a fetch token, nor the reverse. */
+const CONTROL_PREFIX = "agent:";
+
+/**
+ * The control token for one pod (ADR-0076): what the Custodian puts in place of the secret control
+ * Stand-in on the agent routes. A signed name like the fetch token — same key, same deterministic
+ * re-mint — in its own `agent:` domain. No slot is inside it: the Harness states the slot on each
+ * request, and the Orchestrator checks it against the registration's.
+ */
+export function controlToken(key: Buffer, pod: string): string {
+  const name = `${CONTROL_PREFIX}${pod}`;
+  return `${name}.${sign(key, name)}`;
+}
+
+/**
+ * The secret control Stand-in for one pod (ADR-0076, ADR-0059): the bearer the Harness process
+ * alone holds, as a file under `/run/jr2/` that no confined child can read, and that the Custodian
+ * swaps for {@link controlToken} on the agent routes. A 43-character base64url HMAC, so no
+ * Workspace code can guess it. Its own `control-standin:` domain keeps it apart from every token.
+ */
+export function controlStandIn(key: Buffer, pod: string): string {
+  return sign(key, `control-standin:${pod}`);
+}
+
 /**
  * The Harness bearer for one placement (ADR-0058): what the Orchestrator presents on every Harness
  * wire call — admit, stream, abort, echo — to the Harness in the pod `placement` names (a
@@ -138,37 +177,65 @@ export function createAuthenticator(opts: {
   /** The publish token (ADR-0069). Absent → no bearer resolves to the publisher. */
   publishToken?: string;
 }): Authenticator {
-  return (bearer) => {
+  return (bearer, slot) => {
     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);
-    if (!constantTimeEqual(bearer.slice(cut + 1), sign(opts.signingKey, sandbox))) return undefined;
-    return { kind: "sandbox", sandbox };
+    const name = bearer.slice(0, cut);
+    if (!constantTimeEqual(bearer.slice(cut + 1), sign(opts.signingKey, name))) return undefined;
+    // A control token (ADR-0076), read BEFORE the bare form. A control request states its slot; one
+    // that states none is refused like an unknown token, so no route ever sees a control principal
+    // without a slot.
+    if (name.startsWith(CONTROL_PREFIX)) {
+      const pod = name.slice(CONTROL_PREFIX.length);
+      if (!isPodName(pod) || !slot) return undefined;
+      return { kind: "agent", sandbox: pod, slot };
+    }
+    // The bare fetch token, in its own domain alone: a name in any other domain (`harness:`,
+    // `control-standin:`, `held-standin:` …) is not a Sandbox's, whatever key signed it.
+    if (!isPodName(name)) return undefined;
+    return { kind: "sandbox", sandbox: name };
   };
 }
 
+/** A pod's name as a token signs it: a DNS-1123 name, so it holds no `:` and no `/` — the marks of
+ * every other signed domain (ADR-0076). */
+function isPodName(name: string): boolean {
+  return /^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(name);
+}
+
 /**
- * May this principal deliver to this agent registration? The Instance token may (it is the
- * operator). A Sandbox token may only when the registration records ITS name — which is why
- * an Agent registration carries `sandbox` at all (ADR-0013). The recorded name is the pod hosting the Turn:
- * a Workspace's Sandbox, or `jr2-instance-harness` for a Menu-only registration (ADR-0031). An
- * agent registration with NO name at all is an explicit-`endpoint` run (the stub Harness on the
- * host, in no pod): no Sandbox token can claim it.
+ * May this principal speak on this agent registration's routes — its surface, a pick, a delivery's
+ * poll, a notice's acknowledgment? The Instance token may (it is the operator). A control token may
+ * only when the registration records ITS pod — which is why an Agent registration carries `sandbox`
+ * at all (ADR-0013) — AND the slot the Harness stated is the registration's (ADR-0076). The recorded
+ * pod is the one hosting the Turn: a Workspace's Sandbox, or `jr2-instance-harness` for a Menu-only
+ * registration (ADR-0031). An agent registration with NO pod at all is an explicit-`endpoint` run
+ * (the stub Harness on the host, in no pod): no pod's token can claim it. A fetch token never may:
+ * it opens the fetch route alone.
+ *
+ * The slot check finds a routing fault. It is not the boundary: only the Harness process holds the
+ * control Stand-in, so only the Harness can state a slot at all (ADR-0076).
  */
-export function mayDeliverToAgent(principal: Principal, registrationSandbox: string | undefined): boolean {
+export function mayDeliverToAgent(principal: Principal, registration: { sandbox?: string; slot?: string }): boolean {
   if (principal.kind === "instance") return true;
-  if (principal.kind !== "sandbox") return false;
-  return registrationSandbox !== undefined && registrationSandbox === principal.sandbox;
+  if (principal.kind !== "agent") return false;
+  return (
+    registration.sandbox !== undefined &&
+    registration.sandbox === principal.sandbox &&
+    registration.slot !== undefined &&
+    registration.slot === principal.slot
+  );
 }
 
 /**
- * May this principal ask for a fetch on this Sandbox (ADR-0053)? A Sandbox token may ask for its
+ * May this principal ask for a fetch on this Sandbox (ADR-0053)? A fetch 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. The publish token may not: it opens the publish door and no other (ADR-0069).
+ * the operator. A control token may not: it opens the agent routes alone (ADR-0076). 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;
@@ -176,7 +243,15 @@ export function mayAskForSandbox(principal: Principal, sandbox: string): boolean
   return principal.sandbox === sandbox;
 }
 
-function sign(key: Buffer, value: string): string {
+/** Whether a principal is an Agent's — a control token or a fetch token. A Gate refuses every one
+ * (ADR-0013, ADR-0076): an Agent never reaches a Gate. */
+export function isAgentPrincipal(principal: Principal): boolean {
+  return principal.kind === "agent" || principal.kind === "sandbox";
+}
+
+/** An HMAC of `value` under the signing key, base64url (43 characters). Exported so every signed
+ * name and Stand-in derives one way. */
+export function sign(key: Buffer, value: string): string {
   return createHmac("sha256", key).update(value).digest("base64url");
 }
 

package/src/vocabulary.ts

@@ -101,6 +101,27 @@ export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined
   return inputSchemas.get(machine.config);
 }
 
+/**
+ * The door of a wrapper under a parent (ADR-0033). No other door reads a parent's input, so the
+ * wrapper parses it, and the parsed shape is what it uses: defaults are applied and unknown keys
+ * go. A key in `beside` is no one's to send, so it stays out of the parse and rides beside the
+ * result. A value that is wrong is a defect of the parent's Machine: a throw, and its `onError`.
+ *
+ * @param refusal - the start of the error, which says what the refusal saved
+ * @internal
+ */
+export function parsedNestedDoor(
+  door: z.ZodObject,
+  value: Record<string, unknown>,
+  beside: readonly string[],
+  refusal: string,
+): Record<string, unknown> {
+  const kept = Object.entries(value).filter(([key, v]) => beside.includes(key) && v !== undefined);
+  const parsed = door.safeParse(Object.fromEntries(Object.entries(value).filter(([key]) => !beside.includes(key))));
+  if (!parsed.success) throw new Error(`${refusal}: ${parsed.error.message}`);
+  return { ...(parsed.data as Record<string, unknown>), ...Object.fromEntries(kept) };
+}
+
 /** A zod schema, by its shape: the Instance can resolve a zod of its own, so `instanceof` does not
  * tell. */
 export function isZodSchema(value: unknown): boolean {
@@ -187,10 +208,8 @@ export function loadWarningsOf(machine: AnyStateMachine): string[] {
  *
  * Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
  * that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
- * `workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`.
- *
- * The `spec` of a root `workspace()` also gets it, and the type of its input shows it:
- * ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``.
+ * `workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`. For example, a cut
+ * can name a branch for each run: `` branch: `fix/${context.instanceId}` ``.
  *
  * It is not the run id. Use it, for example, to give each run a branch of its own.
  *

package/src/wire.ts

@@ -267,18 +267,18 @@ export type EchoRequest = { events: EchoEvent[] };
 /** 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. */
+ * the push url (ADR-0005); `ref` is the base that `default/` stays on and a new 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` accepts: the slots in declaration order. The Workspace only clones, so the
+ * request names no branch and no commit (ADR-0075). */
+export type AttachRequest = { slots: AttachSlot[] };
 
-/** 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 `POST /attach` answers (200): the folder of each slot, and the base that each slot's
+ * `default/` holds. 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>; bases: 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. */
@@ -312,7 +312,7 @@ export type SyncAnswer =
 
 /** 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 };
+export type ExecRequest = { argv: string[]; cwd?: string; root?: true; timeoutMs: number; tail: number };
 
 /** How an exec ended. Every one is output; none is a fault. */
 export type ExecOutcome =