@jr2/orchestrator 0.6.0 → 0.7.0

package/src/steer.ts

@@ -0,0 +1,111 @@
+// The Machine's Steering message (ADR-0002): free text to one Agent of the Machine, which the Agent
+// hears once, at a step boundary of its open Turn or at its next Turn's admission. The run's notice
+// ledger keeps it (ADR-0062); this module is only the action an author writes.
+
+import type { ActionFunction, EventObject, MachineContext, ParameterizedObject, ProvidedActor } from "xstate";
+import type { Sender } from "@jr2/agent-protocol";
+import { boundRun } from "./registration.ts";
+
+/** The most text one Steering message carries, in UTF-8 bytes: the bound of
+ * `POST /runs/:runId/steering`, whose larger text is 413. The `steer` action cuts a longer text. */
+export const STEERING_TEXT_MAX = 16 * 1024;
+
+/** What `steer` adds to the end of a text that it cut at {@link STEERING_TEXT_MAX}. */
+const CUT_MARK = "\n[jr2 cut this message at 16 KiB]";
+
+/** A text, cut to {@link STEERING_TEXT_MAX} UTF-8 bytes with the cut mark when it is longer. */
+export function boundSteeringText(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  if (bytes.length <= STEERING_TEXT_MAX) return text;
+  const room = STEERING_TEXT_MAX - new TextEncoder().encode(CUT_MARK).length;
+  // `fatal: false` drops a character that the cut split in two.
+  const head = new TextDecoder("utf-8", { fatal: false }).decode(bytes.slice(0, room)).replace(/�$/, "");
+  return `${head}${CUT_MARK}`;
+}
+
+/** The arguments a `steer` text or `from` function gets: the Machine's context and the event that
+ * the transition takes. */
+type SteerArgs<TContext, TEvent> = { context: TContext; event: TEvent };
+
+/**
+ * Send a Steering message to one Agent of this Machine: an action for a transition. The Agent hears
+ * the text once, without an interrupt. When a Turn of the Agent is open, its Harness adds the text
+ * at the Turn's next step boundary. Otherwise the text waits for the Agent's next Turn in this
+ * Machine instance. When this Machine instance ends first, the message is not delivered.
+ *
+ * A Steering message is not an event: no guard reads it, and no Gate takes it. The Agent decides
+ * what to do with it, and acts on the workflow only by its picks.
+ *
+ * Use it to relay what one Agent says to another. Give `from` the Sender of the event (the
+ * `sender` field that the Orchestrator writes on it): the Agent then reads the text as the word of
+ * a peer, not as an order. When the Sender is a Gate, the Agent reads the text as what the Gate
+ * received, not as an order. With no `from`, the Agent reads the text as the workflow's own.
+ *
+ * `agent` is the name of an Agent in this Machine's `actors`. A text longer than 16 KiB is cut.
+ * The Machine can steer an Agent whose definition says `steerable: false`: that refuses Callers
+ * only.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { agent, defineEvent, jr2Setup, steer } from "@jr2/orchestrator";
+ *
+ * const done = defineEvent({ name: "done", description: "The draft is ready.", input: z.object({}) });
+ * const note = defineEvent({
+ *   name: "note",
+ *   description: "Send the draft back to the writer, with what to change.",
+ *   input: z.object({ text: z.string().min(1) }),
+ * });
+ *
+ * export const machine = jr2Setup({
+ *   events: [done, note],
+ *   actors: {
+ *     writer: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You write.", workspace: "none" }),
+ *     reviewer: agent({ model: "anthropic/claude-haiku-5-5", instructions: "You review.", workspace: "none" }),
+ *   },
+ * }).createMachine({
+ *   initial: "writing",
+ *   states: {
+ *     writing: {
+ *       invoke: { src: "writer", input: { prompt: "Write the notes.", continue: true } },
+ *       on: { done: "reviewing" },
+ *     },
+ *     reviewing: {
+ *       invoke: { src: "reviewer", input: { prompt: "Review the notes." } },
+ *       on: {
+ *         // The writer's next Turn hears the note as the reviewer's word, not as an order.
+ *         note: {
+ *           target: "writing",
+ *           actions: steer("writer", ({ event }) => event.text, { from: ({ event }) => event.sender }),
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/guides/steer-an-agent.md
+ * @see docs/concepts/agents-and-turns.md
+ * @see docs/reference/decisions/0002-duplex-streaming-actor.md
+ */
+export function steer<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject["params"] | undefined,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+>(
+  agent: string,
+  text: string | ((args: SteerArgs<TContext, TExpressionEvent>) => string),
+  opts: { from?: Sender | ((args: SteerArgs<TContext, TExpressionEvent>) => Sender | undefined) } = {},
+): ActionFunction<TContext, TExpressionEvent, TEvent, TParams, TActor, never, never, never, never> {
+  return ({ context, event, self }) => {
+    const binding = boundRun(self.system);
+    // Outside a RunHost there is no ledger, and no Agent to hear it.
+    if (binding?.steer === undefined) return;
+    const said = typeof text === "function" ? text({ context, event }) : text;
+    if (typeof said !== "string" || said.length === 0) return;
+    const from = typeof opts.from === "function" ? opts.from({ context, event }) : opts.from;
+    binding.steer(self, agent, boundSteeringText(said), from);
+  };
+}

package/src/stub-harness.ts

@@ -7,7 +7,7 @@
 //
 // Wire (ADR-0027 — the normative model of the conversation endpoints; `@jr2/harness` serves it for
 // real), and the pod's memory kills, which a stub never has (ADR-0062):
-//   POST /agents/:name/:id  {message, cwd?, definition, model?, thinkingLevel?, notices?, kept?} → 200 { streamUrl, offset, submissionId }
+//   POST /agents/:name/:id  {message, cwd?, definition, model?, thinkingLevel?, notices?, steering?, kept?} → 200 { streamUrl, offset, submissionId }
 //     (`message` and `cwd` are the Turn's Frame — what it is about and where it works, ADR-0057;
 //     `kept` admits as any POST does, because the stub keeps every conversation — the real Harness
 //     answers 404 when it keeps none, ADR-0062)
@@ -38,7 +38,7 @@
 
 import { createServer } from "node:http";
 import type { AddressInfo, Socket } from "node:net";
-import type { Notice } from "./wire.ts";
+import type { Notice, SteeringMessage } from "./wire.ts";
 
 /** One admission of an Agent: which slot, which durable exchange, this Turn's FRAME (the prompt
  * and where it works — ADR-0057), the DEFINITION the Machine's slot carried here (ADR-0049), and
@@ -58,6 +58,8 @@ export type Admission = {
   thinkingLevel?: string;
   /** The notices the admission carried (ADR-0062). Absent when it carried none. */
   notices?: Notice[];
+  /** The Steering messages the admission carried (ADR-0002). Absent when it carried none. */
+  steering?: SteeringMessage[];
 };
 
 /** One settled submission, in the shape `history()` reports it. The stub settles submissions for
@@ -165,6 +167,7 @@ export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<R
               model?: string;
               thinkingLevel?: string;
               notices?: Notice[];
+              steering?: SteeringMessage[];
             }
           | undefined;
         const admission: Admission = {
@@ -178,6 +181,7 @@ export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<R
           ...(sent?.model ? { model: sent.model } : {}),
           ...(sent?.thinkingLevel ? { thinkingLevel: sent.thinkingLevel } : {}),
           ...(sent?.notices?.length ? { notices: sent.notices } : {}),
+          ...(sent?.steering?.length ? { steering: sent.steering } : {}),
         };
         admissions.push(admission);
         const submissionId = `stub-${++submissionSeq}`;

package/src/tokens.ts

@@ -6,10 +6,12 @@
 // 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.
+//   Instance token  the human/CLI credential: the Caller `token/instance` (ADR-0078), with every
+//                   scope, and the one credential of the routes no scope names. 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.
+//                   The other Callers (named `jr2c_` tokens, JWTs) are below, under Callers:
+//                   each acts within its scopes.
 //
 //   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
@@ -23,7 +25,7 @@
 //                   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.
+//                   five 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.
@@ -46,13 +48,229 @@
 // 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 { readFileSync, unwatchFile, watchFile } from "node:fs";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
+import { configMapDigest } from "./mount-digest.ts";
+import { SCOPES, type AnswerGrant, type Scope, type Scopes } from "./config.ts";
+
+// ---- Callers (ADR-0078) -----------------------------------------------------------------------
+// A Caller acts on the Instance from outside its Machines: the CLI, a CI job, a bridge, a person in
+// the Console. One seam makes it: an ORDERED list of authenticators. Each one takes the bearer and
+// answers a Caller, "not mine", or "mine, and bad". The first that claims the bearer decides, so a
+// bearer that one claims and finds bad is 401 and never falls through to the next. The Instance
+// token is the first authenticator, the named `jr2c_` tokens the second, and the JWT issuers
+// (callers.ts) the third. The principals inside the Orchestrator (the publish token, the control and fetch tokens)
+// are outside the seam: no authenticator makes a Caller from one of them.
+
+/** A request's Caller (ADR-0078): who acts, through which authenticator, and what it may do. */
+export type Caller = {
+  /** The authenticator that made the Caller: `token` (the Instance token or a named token), `jwt`
+   * or `hook`. */
+  via: "token" | "jwt" | "hook";
+  /** The Caller's name for that authenticator: `instance`, a named token's name, a JWT's `sub`, a
+   * Hook's name. */
+  name: string;
+  /** The name that jr2 shows, when it is not `name` (a JWT's `email`). */
+  shown?: string;
+  /** What the Caller may do. */
+  may: Scopes;
+  /** The Caller's claim about the party it acts for. jr2 records it and never checks it. */
+  onBehalfOf?: string;
+};
+
+/** The header in which a Caller states the party it acts for (ADR-0078). A claim: jr2 records it
+ * and shows it, and never checks it. */
+export const ON_BEHALF_OF_HEADER = "jr2-on-behalf-of";
+
+/** The longest `jr2-on-behalf-of` the guarded band takes: a user name, not a document. */
+export const ON_BEHALF_OF_MAX = 256;
+
+/** The prefix of a named Caller token's value (ADR-0078). It lets the seam say "not mine" with no
+ * lookup, and lets a secret scanner find a value that leaked. */
+export const CALLER_TOKEN_PREFIX = "jr2c_";
+
+/** Every scope, for every Workflow: the Instance token's grant. */
+const EVERY_SCOPE: Scopes = Object.fromEntries(SCOPES.map((s) => [s, "all"])) as Scopes;
+
+/** The Instance token's Caller (ADR-0078): `token/instance`, with every scope for every Workflow. */
+export function instanceCaller(): Caller {
+  return { via: "token", name: "instance", may: { ...EVERY_SCOPE } };
+}
+
+/** Whether a Caller is the Instance token's. The config refuses a named token called `instance`,
+ * so the pair names it alone. */
+export function isInstanceCaller(caller: Caller): boolean {
+  return caller.via === "token" && caller.name === "instance";
+}
+
+/** Whether a list item's Workflow name opens `workflow`. A wrapper's name opens each of its named
+ * Charts (`plan` opens `plan/weekly`), because a named Chart runs its wrapper's Machine (ADR-0070). */
+function nameOpens(name: string, workflow: string): boolean {
+  if (name === workflow) return true;
+  const cut = workflow.indexOf("/");
+  return cut > 0 && name === workflow.slice(0, cut);
+}
+
+/** Whether `grant` opens `workflow`: for the `answer` scope, at least one Gate of it (ADR-0078). */
+export function grantOpens(grant: AnswerGrant | undefined, workflow: string): boolean {
+  if (grant === undefined) return false;
+  if (grant === "all") return true;
+  return grant.some((item) => nameOpens(typeof item === "string" ? item : item.workflow, workflow));
+}
+
+/** Whether an `answer` grant opens the Gate named `gate` (its invoke id, ADR-0011) of `workflow`:
+ * a bare Workflow name opens each of its Gates, and a `{ workflow, gates }` item the Gates that it
+ * names (ADR-0078). */
+export function grantOpensGate(grant: AnswerGrant | undefined, workflow: string, gate: string): boolean {
+  if (grant === undefined) return false;
+  if (grant === "all") return true;
+  return grant.some((item) =>
+    typeof item === "string"
+      ? nameOpens(item, workflow)
+      : nameOpens(item.workflow, workflow) && item.gates.includes(gate),
+  );
+}
+
+/** Whether a Caller has `scope` for `workflow`. For `answer`, that is at least one Gate of it:
+ * {@link callerMayAnswer} asks for one Gate. */
+export function callerMay(caller: Caller, scope: Scope, workflow: string): boolean {
+  return grantOpens(caller.may[scope], workflow);
+}
+
+/** Whether a Caller may answer the Gate named `gate` (its invoke id) of a run of `workflow`
+ * (ADR-0078). */
+export function callerMayAnswer(caller: Caller, workflow: string, gate: string): boolean {
+  return grantOpensGate(caller.may.answer, workflow, gate);
+}
+
+/** Whether a Caller has `scope` for at least one Workflow. */
+export function callerHasScope(caller: Caller, scope: Scope): boolean {
+  const grant = caller.may[scope];
+  return grant !== undefined && (grant === "all" || grant.length > 0);
+}
+
+/** Whether `workflow` is in any scope of a Caller: what `GET /runs/resolve` answers for. */
+export function callerMayAny(caller: Caller, workflow: string): boolean {
+  return SCOPES.some((s) => callerMay(caller, s, workflow));
+}
+
+/** One authenticator's answer: a Caller; `{ refused }`, which is "mine, and bad" (401, and it never
+ * falls through); or `undefined`, which is "not mine". */
+export type CallerAnswer = Caller | { refused: string } | undefined;
+
+/** One authenticator of the seam. An authenticator that must fetch (a JWT issuer's keys) answers
+ * with a Promise. */
+export type CallerAuthenticator = (bearer: string) => CallerAnswer | Promise<CallerAnswer>;
+
+/** The Instance token's authenticator (ADR-0078). */
+export function instanceTokenAuthenticator(instanceToken: string): CallerAuthenticator {
+  return (bearer) => (constantTimeEqual(bearer, instanceToken) ? instanceCaller() : undefined);
+}
+
+/** A named token's entry as the Orchestrator holds it: its name, the sha-256 of its value, and its
+ * scopes. Never the value (ADR-0078). */
+export type NamedToken = { name: string; digest: string; may: Scopes };
+
+/** The digest of a named token's value, as `jr2 up` gives it to the Orchestrator: sha-256, hex. */
+export function callerTokenDigest(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/** Make a named token's value: `jr2c_` and 32 random bytes in base64url (ADR-0078). */
+export function mintCallerToken(): string {
+  return CALLER_TOKEN_PREFIX + randomBytes(32).toString("base64url");
+}
+
+/**
+ * The named tokens' authenticator (ADR-0078). It claims every bearer with the `jr2c_` prefix, so a
+ * value that no entry knows is 401 here, never a bearer for the next authenticator. `tokens` is read
+ * on each request: a rotation or a new config applies with no restart.
+ */
+export function namedTokenAuthenticator(tokens: () => readonly NamedToken[]): CallerAuthenticator {
+  return (bearer) => {
+    if (!bearer.startsWith(CALLER_TOKEN_PREFIX)) return undefined;
+    const digest = callerTokenDigest(bearer);
+    // Each entry is compared, in constant time: the digest is not secret, but the loop does not
+    // stop early, so the time does not say which entry is near.
+    let found: NamedToken | undefined;
+    for (const entry of tokens()) if (constantTimeEqual(digest, entry.digest)) found = entry;
+    if (!found) return { refused: "no named Caller token has this value — it was rotated, or never made" };
+    return { via: "token", name: found.name, may: found.may };
+  };
+}
+
+/**
+ * Join the named tokens that the config declares with the digests that `jr2 up` gave the
+ * Orchestrator (ADR-0078). A declared name with no digest has no value yet, and a digest whose name
+ * the config does not declare opens nothing.
+ */
+export function namedTokens(
+  declared: Readonly<Record<string, { may: Scopes }>> | undefined,
+  digests: Readonly<Record<string, string>>,
+): NamedToken[] {
+  return Object.entries(declared ?? {}).flatMap(([name, { may }]) => {
+    const digest = digests[name];
+    return typeof digest === "string" && digest !== "" ? [{ name, digest, may }] : [];
+  });
+}
+
+/**
+ * The digests of the named tokens, by name, from the file that `jr2 up` mounts into the
+ * Orchestrator (`{ "<name>": "<sha-256 hex>" }`). The file is read again when it changes, so a
+ * rotation needs no restart: the kubelet updates a mounted Secret on its own period, about a
+ * minute, and until then the old value works (ADR-0078). `loaded` tells which content the process
+ * holds, so `jr2 up` and `jr2 caller rotate` wait for it. An absent file reads as no digests. A file
+ * that does not parse is logged, and the digests read last stay.
+ */
+export function watchCallerDigests(path: string, opts: { intervalMs?: number } = {}) {
+  let digests: Record<string, string> = {};
+  // The text that gave `digests`, so that `loaded` tells what the process holds now.
+  let text: string | undefined;
+  const read = () => {
+    try {
+      const raw = readFileSync(path, "utf8");
+      const parsed = JSON.parse(raw) as unknown;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not a JSON object");
+      digests = Object.fromEntries(
+        Object.entries(parsed as Record<string, unknown>).filter(
+          (e): e is [string, string] => typeof e[1] === "string",
+        ),
+      );
+      text = raw;
+    } catch (err) {
+      // Absent is the ordinary case for an Instance that declares no named token: no digest. A file
+      // that does not parse keeps the digests read last, so a write seen half done stops no Caller.
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        digests = {};
+        text = undefined;
+      } else console.error(`caller digests at ${path} not read: ${err instanceof Error ? err.message : err}`);
+    }
+  };
+  read();
+  // A poll of the file's stat, not `fs.watch`: the kubelet swaps a symlink above the file, which an
+  // inotify watch on the old target never sees. `persistent: false` holds no process alive.
+  const listener = () => read();
+  watchFile(path, { interval: opts.intervalMs ?? 2000, persistent: false }, listener);
+  return {
+    /** The digests now. */
+    current: (): Readonly<Record<string, string>> => digests,
+    /**
+     * The digest of the file content that gave the digests now, keyed by the file's name as a
+     * mount's digest is (`configMapDigest`), so that `jr2 up` and `jr2 caller rotate` can wait
+     * until a value they wrote works (ADR-0078). Undefined when no file was read.
+     */
+    loaded: (): string | undefined => (text === undefined ? undefined : configMapDigest({ [basename(path)]: text })),
+    /** Read the file now (a test does not wait for the poll). */
+    reload: read,
+    stop: () => unwatchFile(path, listener),
+  };
+}
 
 /** Who a request is, once its bearer token checks out. */
 export type Principal =
-  /** The instance's own operator: the CLI, a human, a webhook translator holding the token. */
-  | { kind: "instance" }
+  /** A Caller (ADR-0078): the Instance token, a named token, or a JWT. */
+  | { kind: "caller"; caller: Caller }
   /** `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" }
@@ -70,7 +288,7 @@ export const SLOT_HEADER = "x-jr2-slot";
 
 /** 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;
+export type Authenticator = (bearer: string | undefined, slot?: string) => Promise<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. */
@@ -167,24 +385,47 @@ export async function loadSigningKey(dir: string): Promise<Buffer> {
 }
 
 /**
- * The instance's authenticator: the Instance token, plus any Sandbox token this key signed.
- * 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.
+ * The instance's authenticator: the principals inside the Orchestrator (the publish token, and any
+ * Sandbox token this key signed), then the Caller seam (ADR-0078) in its order — the Instance
+ * token, the named tokens, then `callers`. 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.
+ *
+ * The principals come first because each is an exact value or a signed name: no Caller credential
+ * has the form of one (a named token holds no `.`), so the order changes no answer, and no
+ * authenticator of the seam ever sees a principal's token.
  */
 export function createAuthenticator(opts: {
   instanceToken: string;
   signingKey: Buffer;
   /** The publish token (ADR-0069). Absent → no bearer resolves to the publisher. */
   publishToken?: string;
+  /** The named tokens, read on each request (ADR-0078). Absent → none. */
+  namedTokens?: () => readonly NamedToken[];
+  /** More authenticators of the seam, after the named tokens: the JWT issuers (callers.ts). */
+  callers?: readonly CallerAuthenticator[];
 }): Authenticator {
-  return (bearer, slot) => {
+  const seam: CallerAuthenticator[] = [
+    instanceTokenAuthenticator(opts.instanceToken),
+    ...(opts.namedTokens ? [namedTokenAuthenticator(opts.namedTokens)] : []),
+    ...(opts.callers ?? []),
+  ];
+  const caller = async (bearer: string): Promise<Principal | undefined> => {
+    for (const authenticate of seam) {
+      const answer = await authenticate(bearer);
+      if (answer === undefined) continue;
+      // Claimed: the first claim decides, and a bad one never falls through.
+      return "refused" in answer ? undefined : { kind: "caller", caller: answer };
+    }
+    return undefined;
+  };
+  return async (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;
+    if (cut <= 0) return caller(bearer);
     const name = bearer.slice(0, cut);
-    if (!constantTimeEqual(bearer.slice(cut + 1), sign(opts.signingKey, name))) return undefined;
+    if (!constantTimeEqual(bearer.slice(cut + 1), sign(opts.signingKey, name))) return caller(bearer);
     // 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.
@@ -220,7 +461,7 @@ function isPodName(name: string): boolean {
  * control Stand-in, so only the Harness can state a slot at all (ADR-0076).
  */
 export function mayDeliverToAgent(principal: Principal, registration: { sandbox?: string; slot?: string }): boolean {
-  if (principal.kind === "instance") return true;
+  if (isInstancePrincipal(principal)) return true;
   if (principal.kind !== "agent") return false;
   return (
     registration.sandbox !== undefined &&
@@ -238,15 +479,15 @@ export function mayDeliverToAgent(principal: Principal, registration: { sandbox?
  * 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 (isInstancePrincipal(principal)) return true;
   if (principal.kind !== "sandbox") return false;
   return principal.sandbox === sandbox;
 }
 
-/** 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";
+/** Whether a principal is the Instance token's Caller: the operator, which the routes that no
+ * scope names take alone (ADR-0014). A named token is never it, whatever its scopes. */
+export function isInstancePrincipal(principal: Principal): boolean {
+  return principal.kind === "caller" && isInstanceCaller(principal.caller);
 }
 
 /** An HMAC of `value` under the signing key, base64url (43 characters). Exported so every signed

package/src/wire.ts

@@ -152,6 +152,23 @@ export type PickAnswerNotice = {
 
 export type Notice = MemoryLimitNotice | ConversationNewNotice | PickAnswerNotice;
 
+// ---- Steering messages (ADR-0002, ADR-0062) ----------------------------------------------------
+// Free text to one Agent slot, with its author. Not a notice: a notice is a fact with no author,
+// and the model weighs a Steering message by who wrote it. The two ride one ledger and one
+// transport, and the Harness frames each message by its author.
+
+/** Who wrote a Steering message. `caller`: a Caller sent it from outside the run (ADR-0078), with
+ * the name jr2 shows and the party it says it acts for. `machine`: the Machine sent it with its
+ * `steer` action; `from` is the party whose words it relays, when it relays some. */
+export type SteeringAuthor =
+  | { kind: "caller"; via: "token" | "jwt" | "hook"; name: string; onBehalfOf?: string }
+  | { kind: "machine"; from?: { party: "agent" | "gate"; id: string } };
+
+/** One Steering message, as the admission and the surface read carry it. `scope: "slot"` is the
+ * address kind it uses in the ledger. `at`: when it was sent (ISO). The Harness writes the frame;
+ * `text` is the author's. */
+export type SteeringMessage = { kind: "steering"; scope: "slot"; text: string; author: SteeringAuthor; at: string };
+
 /** Response header: the offset to resume the stream from (every stream read carries it). */
 export const STREAM_NEXT_OFFSET_HEADER = "stream-next-offset";
 

package/src/workspace.ts

@@ -295,6 +295,9 @@ export type PlaceRequest = {
   name: string;
   runId: string;
   workflow: string;
+  /** The Workspace's path in the run's Machine: the wrapper's actor ids joined by `/` (ADR-0012).
+   * The port writes it on the CR, where the `jr2 workspace` verbs read it (ADR-0009). */
+  path: string;
   /** The placement route from the registered Machine to this `workspace()` (`actorRoute`). With
    * `workflow`, it names the pod whose Held secrets and Sandbox Effector `jr2 up` placed (ADR-0059). */
   route: PlacementRoute;
@@ -327,9 +330,10 @@ export type ProvisionedRepo = { slot: string; url: string; ref?: string; perRun:
  */
 export interface SandboxPort {
   /**
-   * Write the Sandbox (its token Secret, then the CR, labeled with its run for `jr2 ls`) and wait,
-   * with NO deadline, until the operator says its pod is scheduled (ADR-0064). `image`/`user` are
-   * the wrapper's static image options (ADR-0037/0005/0049) — a `file:` context or a registry ref,
+   * Write the Sandbox (its token Secret, then the CR, labeled with its run, its Workflow and its
+   * path for `jr2 workspace ls`) and wait, with NO deadline, until the operator says its pod is
+   * scheduled (ADR-0064). `image`/`user` are the wrapper's static image options
+   * (ADR-0037/0005/0049) — a `file:` context or a registry ref,
    * the port resolves both, and a context the last converge did not build fails here rather than
    * converge-time. `repos` are the wrapper's slots, resolved, in declaration order (ADR-0051): the
    * port names each Repo on the CR so the cluster mounts its cache, and refuses a per-run url no
@@ -367,6 +371,20 @@ export interface SandboxPort {
    * the next renewal is minutes away and the idle timeout is thirty.
    */
   renew(name: string): Promise<void>;
+  /**
+   * Mark the Sandbox as held by no run (ADR-0021): the Lease stopped for the body's final state, a
+   * fault, a cancel or a parent that left the Workspace — never for a park or a process shutdown.
+   * `jr2 workspace rm` reads the mark with the cluster alone (ADR-0009). A write, and only that; a
+   * failure rejects and the caller shrugs.
+   */
+  releaseHold(name: string): Promise<void>;
+  /**
+   * Mark every Sandbox of a run as held by no run (ADR-0021), found by its `jr2.dev/run` label: a
+   * restore ended the run `drifted` or `lost` without hosting it, so no Lease runs to release them.
+   * A write for each, and only that; a failure rejects and the caller shrugs. Optional: a port
+   * with no cluster has nothing to mark.
+   */
+  releaseRun?(runId: string): Promise<void>;
   /**
    * Hear this workspace's Continuity from the watch (ADR-0021, ADR-0063): once the watch has
    * listed, what it holds now, then again on every change the cluster reports — a Sandbox gone, or
@@ -1359,6 +1377,7 @@ function buildWorkspaceMachine(body: AnyStateMachine): AnyStateMachine {
         name,
         runId: binding.runId,
         workflow: binding.workflow,
+        path: child || input.wsId,
         route,
         // The image strings straight through (ADR-0037/0005) — the port owns resolution, and the
         // work group's default (ADR-0005 puts it in pod composition, where the pod is built).
@@ -1522,10 +1541,22 @@ function buildWorkspaceMachine(body: AnyStateMachine): AnyStateMachine {
       let timer: ReturnType<typeof setTimeout>;
       const schedule = (ms: number) => {
         timer = setTimeout(() => {
+          if (stopped) return;
           // A Workspace that ended in error stopped processing without stopping its children (xstate
-          // does not), and a parent that handled the error only stops what still processes: the
-          // lease asks, and asserts nothing for a Workspace that is over.
-          if (stopped || self._parent?.getSnapshot().status !== "active") return;
+          // does not), and a parent that handled the error only stops what still processes: so this
+          // lease is never stopped, and its cleanup below never runs. The lease asks, asserts nothing
+          // for a Workspace that is over, and releases the hold mark here, once: no run holds the
+          // Sandbox now (ADR-0021). A host that stops writes nothing, as below.
+          if (self._parent?.getSnapshot().status !== "active") {
+            if (runBindingOf(system).hostStopping) return;
+            stopped = true;
+            unsubscribe();
+            // A parent that caught the defect can invoke the same Machine again: the new Workspace
+            // has the same invoke id, so the same Sandbox name, and its own Lease holds it now.
+            if (runBindingOf(system).heldSandboxes?.().has(name)) return;
+            port.releaseHold(name).catch(() => {});
+            return;
+          }
           // A failed renewal is unknown, never lost: the next one is an interval away, well inside
           // the idle timeout, and loss is the watch's to report. Before the CR's write lands it is a
           // 404, and the same shrug.
@@ -1539,6 +1570,19 @@ function buildWorkspaceMachine(body: AnyStateMachine): AnyStateMachine {
         stopped = true;
         clearTimeout(timer);
         unsubscribe();
+        // The hold mark (ADR-0021). A park writes nothing, so the CR stays `held` and the restored
+        // run's Lease renews it. Else the stop is a step of the wrapper or its end: read the wrapper
+        // once its stop or its transition is over. Still active, it is in a next state with a Lease
+        // of its own, or deletes the Sandbox; over (a cancel, a fault, a parent that left it), no
+        // run holds the Sandbox now.
+        if (runBindingOf(system).hostStopping) return;
+        queueMicrotask(() => {
+          if (runBindingOf(system).hostStopping) return;
+          if (self._parent?.getSnapshot().status === "active") return;
+          // A live Workspace of the same name (a re-invoke after a caught defect) holds it now.
+          if (runBindingOf(system).heldSandboxes?.().has(name)) return;
+          port.releaseHold(name).catch(() => {});
+        });
       };
     },
   );

package/src/worktree.ts

@@ -124,7 +124,7 @@ export type WorktreeInput =
       expect?: never;
     };
 
-/** What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work;
+/** What a cut found. `held`: a cut made this Worktree earlier, so what is in it is earlier work;
  * `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no
  * upstream; `commit`, a detached cut. Open: a later value does not break an author's code. */
 export type WorktreeFound = "held" | "local" | "remote" | "none" | "commit" | (string & {});
@@ -143,8 +143,8 @@ export type WorktreeReady<S extends string = string> = {
   stale?: string;
 };
 
-/** No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does
- * not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
+/** No Worktree, and nothing changed. The cause is a bad path, a name git or the push refuses, a
+ * re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
  * name that the remote cannot confirm. */
 export type WorktreeRefused = { outcome: "refused"; reason: string };