@jr2/orchestrator 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The jr2 Orchestrator: xstate runtime, HTTP API and Console, and the kit pieces a Workflow imports.",
   "license": "MIT",
   "private": false,
@@ -42,11 +42,11 @@
     "ts-blank-space": "^0.9.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/agent-protocol": "0.2.0"
+    "@jr2/agent-protocol": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.2.0"
+    "@jr2/harness": "0.2.1"
   },
   "files": [
     "bin",

package/src/actor.ts

@@ -257,8 +257,10 @@ export interface AgentRunPort {
  * Machine edit that changed it. */
 export type AgentAdmitOptions = { definition: AgentDefinition; signal?: AbortSignal };
 
-/** Build a port for one invocation from its serializable input (ADR-0011 static-import doctrine). */
-export type AgentRunPortFactory = (endpoint: string) => AgentRunPort;
+/** Build a port for one invocation from its serializable input (ADR-0011 static-import doctrine),
+ * plus the Harness bearer for the placement that input resolved to (ADR-0058) — absent where no
+ * placement is named (the stub path) or the host derives none. */
+export type AgentRunPortFactory = (endpoint: string, bearer?: string) => AgentRunPort;
 
 /** Absorbed-turn-mechanics knobs (ADR-0016): defaulted, never Machine context. */
 export type AgentRunOptions = {
@@ -504,7 +506,10 @@ export function agentActorWith(
       );
     registerSurface(currentIid);
 
-    const client = portFactory(endpoint);
+    // The Harness bearer (ADR-0058) is derived from the SAME name the registration records as its
+    // delivery scope: the pod hosting this Turn. One name, both directions — the Adapter there may
+    // speak for these picks, and only this bearer may drive the conversation there.
+    const client = portFactory(endpoint, sandbox === undefined ? undefined : binding.harnessBearer?.(sandbox));
     const controller = new AbortController();
     // Shared per run, created on demand so the ordering guarantee holds for any binding.
     const pendingAborts = (binding.pendingAborts ??= new Map<string, Promise<void>>());

package/src/harness-client.ts

@@ -80,6 +80,10 @@ export type HarnessClient = {
 export type HarnessClientOptions = {
   /** The Harness base URL — what a workspace publishes, or a stub's `url`. */
   baseUrl: string;
+  /** The Harness bearer for this placement (ADR-0058; `harnessToken` in tokens.ts) — sent on
+   * every call, the long-poll included. Absent only where no placement exists: an explicit-
+   * `endpoint` run against the stub Harness, which checks nothing. */
+  token?: string;
   /** Injectable for socket-free tests. Default: global `fetch`. */
   fetch?: typeof fetch;
   /** Reconnect backoff floor/ceiling (capped exponential, jittered per rung — see `jittered`;
@@ -125,6 +129,7 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
   const backoffMaxMs = options.backoffMaxMs ?? 5_000;
   const admitWindowMs = options.admitWindowMs ?? 90_000;
   const log = options.log ?? ((line: string) => console.warn(line));
+  const authorization: Record<string, string> = options.token ? { authorization: `Bearer ${options.token}` } : {};
 
   const conversationUrl = (agentName: string, instanceId: string) =>
     new URL(`/agents/${encodeURIComponent(agentName)}/${encodeURIComponent(instanceId)}`, baseUrl).toString();
@@ -192,7 +197,7 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
         url,
         {
           method: "POST",
-          headers: { "content-type": "application/json" },
+          headers: { "content-type": "application/json", ...authorization },
           body: JSON.stringify({
             message: sendOptions.message,
             // The other half of the Frame (ADR-0057): where this Turn works. Omitted only when
@@ -238,13 +243,21 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
         let events: StreamEvent[];
         let nextOffset: string | null;
         try {
-          const res = await fetchImpl(url.toString(), { signal });
+          const res = await fetchImpl(url.toString(), { headers: authorization, signal });
           if (res.status === 404) {
             throw new SettlementFault(
               `conversation lost: the harness answered 404 for submission "${admission.submissionId}" — ` +
                 `a conversation lives as long as its Harness process (ADR-0027)`,
             );
           }
+          // Refused, not unreachable: the bearer is derived, so a Harness that rejects it now
+          // rejects it on every retry — reconnecting would park the Turn forever, silently.
+          if (res.status === 401 || res.status === 403) {
+            throw new SettlementFault(
+              `harness refused the stream read (${res.status}) for submission "${admission.submissionId}": ` +
+                `${await errorDetail(res)} — the bearer is not this placement's (ADR-0058)`,
+            );
+          }
           if (!res.ok && res.status !== 204) {
             throw new ReconnectableError(`harness stream read failed (${res.status})`);
           }
@@ -274,6 +287,7 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
     async abort(agentName, instanceId, opts) {
       const res = await fetchImpl(`${conversationUrl(agentName, instanceId)}/abort`, {
         method: "POST",
+        headers: authorization,
         signal: opts?.signal,
       });
       if (!res.ok) {
@@ -334,16 +348,16 @@ export function createHarnessAgentRunClient(options: HarnessClientOptions): Agen
 
 /**
  * The run-narrative echo push (ADR-0023): `POST /echo { events }` against one Workspace Harness,
- * bearing the Instance token (the endpoint is instance-token-gated — the Harness verifies the
- * bearer against the token's sha-256, never holding the token itself). The payload is the
+ * bearing that placement's Harness bearer (ADR-0058 — the Harness verifies it against a sha-256,
+ * never holding it at rest). The payload is the
  * STRUCTURED feed events; the Harness renders. A non-OK answer rejects, and the CALLER treats
  * that as log-and-continue — fire-and-forget lives in the tee (run-host.ts), not here, so a test
  * can still assert a push failed.
  */
 export function createEchoPush(options: {
   baseUrl: string;
-  /** The Instance token — the echo bearer. */
-  token: string;
+  /** The Workspace's Harness bearer (ADR-0058). Absent only against the stub Harness. */
+  token?: string;
   /** Injectable for socket-free tests. Default: global `fetch`. */
   fetch?: typeof fetch;
 }): (events: EchoEvent[]) => Promise<void> {
@@ -356,7 +370,10 @@ export function createEchoPush(options: {
     // `fetch failed` in the pod log is what let that condition hide.
     const res = await fetchImpl(url, {
       method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${options.token}` },
+      headers: {
+        "content-type": "application/json",
+        ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+      },
       body: JSON.stringify({ events }),
     }).catch((err: unknown) => {
       throw new Error(`harness echo to ${url} failed: ${transportDetail(err)}`, { cause: err });
@@ -386,7 +403,10 @@ export function createEchoPush(options: {
  * still an `AgentDefinition`: the actor narrows on start and refuses an Open one there.
  */
 export function agent(declaration: AgentDeclaration): AgentLogic {
-  return agentActorWith((endpoint) => createHarnessAgentRunClient({ baseUrl: endpoint }), declaration);
+  return agentActorWith(
+    (endpoint, bearer) => createHarnessAgentRunClient({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
+    declaration,
+  );
 }
 
 /** A stream read worth retrying (server hiccup) — internal to the reconnect loop, never thrown out. */

package/src/http.ts

@@ -27,9 +27,10 @@
 //                 control.
 //   authenticated any principal we minted a token for. The Agent's surface lives here, scoped
 //                 further per-registration by `mayDeliverToAgent`.
-//   instanceOnly  the Instance token ALONE. Run control and full run state (`/runs*`): a Sandbox
-//                 token authenticates but is refused, because reading another feature's context or
-//                 cancelling a run is not on the Agent's surface any more than a Gate is.
+//   instanceOnly  the Instance token ALONE. Run control — starting a run included (ADR-0058) — and
+//                 full run state (`/runs*`): a Sandbox token authenticates but is refused, because
+//                 starting work, reading another feature's context, or cancelling a run is not on
+//                 the Agent's surface any more than a Gate is.
 
 import { readFile, stat } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -356,8 +357,10 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // Push work: start a run of a registered workflow. Unknown workflow → host.start throws → 404.
   // A body failing the machine's declared input schema (ADR-0033) → 400 naming the accepted
   // shape — the same error class, and the same wire mapping, as a gate delivery failing its
-  // schema (`POST /runs/:id/gates/:gate/events` below).
-  app.post("/workflows/:name/runs", authenticated, async (c) => {
+  // schema (`POST /runs/:id/gates/:gate/events` below). Instance-band (ADR-0058): starting work is
+  // run control, and a Sandbox token's scope is its own agent surface — no Adapter forwarding this
+  // route is what keeps an Agent from starting runs today, and that is not a control.
+  app.post("/workflows/:name/runs", instanceOnly, async (c) => {
     const name = c.req.param("name");
     const input = await readJson(c.req.text());
     try {

package/src/instance.ts

@@ -29,7 +29,7 @@ import { RunHost } from "./run-host.ts";
 import type { RunRecord } from "./run-host.ts";
 import { SqliteSnapshotStore } from "./snapshot-store.ts";
 import type { SnapshotStore } from "./snapshot-store.ts";
-import { createAuthenticator, loadSigningKey, mintInstanceToken } from "./tokens.ts";
+import { createAuthenticator, harnessToken, loadSigningKey, mintInstanceToken } from "./tokens.ts";
 import type { SandboxPort } from "./workspace.ts";
 
 export type InstanceOptions = {
@@ -113,19 +113,25 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   }
   await store.init();
 
-  // Resolved BEFORE the host: the Instance token is also the echo bearer (ADR-0023), so the
-  // host's echo pusher closes over it. Served under in step 4 below, unchanged.
+  // Resolved BEFORE the host, and the signing key with it: the host derives every Harness bearer
+  // from the key (ADR-0058) — admission, stream, abort, echo. The key is loaded from (or minted
+  // into) the instance folder, NOT generated per process: live Sandboxes outlive a restart, their
+  // Adapters still bear tokens this key signed, and their Harnesses still check bearers it derived.
+  // The Instance token is per-boot; the key is not. Both are served under in step 4 below.
   const instanceToken = opts.instanceToken ?? mintInstanceToken();
+  const signingKey = opts.signingKey ?? (await loadSigningKey(opts.dir));
 
   const host = new RunHost({
     store,
     reconcile: opts.reconcile,
     sandbox: opts.sandbox,
     instanceHarness: opts.instanceHarness,
+    harnessBearer: (placement) => harnessToken(signingKey, placement),
     // The run-narrative echo (ADR-0023): tee a run's feed to its enclosing Workspace's Harness,
-    // authenticated as the instance. The wire push is here and the fire-and-forget is the
-    // host's, so a Harness that refuses (or is gone) costs a log line at most.
-    echo: (endpoint) => createEchoPush({ baseUrl: endpoint, token: instanceToken }),
+    // bearing that Workspace's Harness bearer (ADR-0058) — never the Instance token, which would
+    // otherwise pass through a process the Agent executes code beside. The wire push is here and
+    // the fire-and-forget is the host's, so a Harness that refuses (or is gone) costs a log line.
+    echo: (endpoint, bearer) => createEchoPush({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
     // A run left `live` to be retried is otherwise unexplained — the announce line names it, this
     // says why (ADR-0030). stderr, because it is a fault, not the boot's structured result.
     onRestoreError: (runId, err) =>
@@ -153,10 +159,7 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // discoverable by asking after a specific run id nobody knows to ask about.
   const restored = await host.restore();
 
-  // 4. Serve, authenticated (ADR-0013). The signing key is loaded from (or minted into) the
-  // instance folder, NOT generated per process: live Sandboxes outlive a restart, and their
-  // Adapters still bear tokens this key signed. The Instance token is per-boot; the key is not.
-  const signingKey = opts.signingKey ?? (await loadSigningKey(opts.dir));
+  // 4. Serve, authenticated (ADR-0013) — the token and key resolved above.
   const auth = createAuthenticator({ instanceToken, signingKey });
   // The Repos are read PER REQUEST, never snapshotted here: a cache the agent cloned minutes
   // after boot must show as present the next time anyone asks (ADR-0048/0051).

package/src/registration.ts

@@ -246,6 +246,13 @@ export type RunBinding = {
    * absent, a `"none"` Agent without an explicit `endpoint` fails loudly.
    */
   instanceHarness?: string;
+  /**
+   * The Harness bearer for a placement (ADR-0058): `harnessToken(signingKey, placement)`, closed
+   * over the key by the host. The Agent actor asks it for the pod its Turn resolved to; the echo
+   * attach asks it for the Workspace's. Absent (bare unit-test bindings, the stub path), no bearer
+   * is sent — which only a Harness that checks nothing accepts.
+   */
+  harnessBearer?: (placement: string) => string;
   /**
    * Record an Agent invocation's durable admission in the host ledger (ADR-0016): persisted
    * beside the snapshot in the same RunBlob save, keyed by iid (globally unique, so the map is
@@ -283,12 +290,13 @@ export type RunBinding = {
   marker?: (event: TurnMarker) => void;
   /**
    * Attach the run-narrative echo to a Workspace's Harness (ADR-0023): the host replays the
-   * run's feed-so-far to `endpoint`, then tees live; returns the detach. Called by `workspace()`'s
+   * run's feed-so-far to `endpoint` — the Harness in `placement`'s pod, pushed with that
+   * placement's bearer (ADR-0058) — then tees live; returns the detach. Called by `workspace()`'s
    * registrar — the same restore-safe seat the ambient handles ride — and scoped to the OWNING
    * run by construction: the binding is per-run, so a sibling run's feed is unreachable.
    * Host-supplied; absent = no echo.
    */
-  echo?: (endpoint: string) => () => void;
+  echo?: (endpoint: string, placement: string) => () => void;
   /**
    * The HOST is ending this run for its own reasons (ADR-0024). An Agent invocation ending
    * normally ends the Agent's turn — the state stopped waiting — but `RunHost.stop()` is the one

package/src/run-host.ts

@@ -312,13 +312,18 @@ export type RunHostOptions = {
   sandbox?: SandboxPort;
   /** The Instance Harness base URL (ADR-0031) — where `workspace: "none"` Turns are admitted. */
   instanceHarness?: string;
+  /** The Harness bearer for a placement (ADR-0058) — `startInstance` closes `harnessToken` over the
+   * signing key. Handed to every run's binding, and to the echo pusher below. Absent, no Harness
+   * call bears one: only the stub Harness answers such a host. */
+  harnessBearer?: (placement: string) => string;
   /**
    * Build the run-narrative echo pusher for one Workspace's Harness (ADR-0023) — the seam a fake
-   * echo server rides in tests; `startInstance` binds the real wire push (harness-client.ts),
-   * closed over the Instance token. Absent = no echo: a host without it runs identically, because
-   * the echo is a courtesy view of the feed, never a dependency of the run.
+   * echo server rides in tests; `startInstance` binds the real wire push (harness-client.ts).
+   * `bearer` is that Workspace's Harness bearer (ADR-0058), when the host derives one. Absent = no
+   * echo: a host without it runs identically, because the echo is a courtesy view of the feed,
+   * never a dependency of the run.
    */
-  echo?: (endpoint: string) => (events: EchoEvent[]) => Promise<void>;
+  echo?: (endpoint: string, bearer: string | undefined) => (events: EchoEvent[]) => Promise<void>;
 };
 
 /** What we persist per run: the machine snapshot wrapped with the run metadata restore needs.
@@ -383,7 +388,11 @@ export class RunHost {
   private readonly onRestoreError?: (runId: string, err: unknown) => void;
   private readonly sandbox?: SandboxPort;
   private readonly instanceHarness?: string;
-  private readonly echoFactory?: (endpoint: string) => (events: EchoEvent[]) => Promise<void>;
+  private readonly harnessBearer?: (placement: string) => string;
+  private readonly echoFactory?: (
+    endpoint: string,
+    bearer: string | undefined,
+  ) => (events: EchoEvent[]) => Promise<void>;
   private readonly workflowDefs = new Map<string, WorkflowDef>();
   private readonly runs = new Map<string, LiveRun>();
   /**
@@ -401,6 +410,7 @@ export class RunHost {
     this.onRestoreError = opts.onRestoreError;
     this.sandbox = opts.sandbox;
     this.instanceHarness = opts.instanceHarness;
+    this.harnessBearer = opts.harnessBearer;
     this.echoFactory = opts.echo;
   }
 
@@ -883,11 +893,11 @@ export class RunHost {
    * Scoped to the OWNING run's lineage by construction: it reads one run's buffer and listeners
    * and nothing else — a sibling run's events cannot reach this endpoint through here.
    */
-  private attachEcho(runId: string, endpoint: string): () => void {
+  private attachEcho(runId: string, endpoint: string, placement: string): () => void {
     const run = this.runs.get(runId);
     const factory = this.echoFactory;
     if (!run || !factory) return () => {};
-    const push = factory(endpoint);
+    const push = factory(endpoint, this.harnessBearer?.(placement));
     let chain = Promise.resolve();
     let reported = false;
     const enqueue = (events: EchoEvent[]): void => {
@@ -965,6 +975,7 @@ export class RunHost {
       table: this.table,
       sandbox: this.sandbox,
       instanceHarness: this.instanceHarness,
+      ...(this.harnessBearer ? { harnessBearer: this.harnessBearer } : {}),
       // The admission ledger's write half (ADR-0016): the Agent actor reports the durable handle the
       // moment the Harness admits it, and the ledger hits the store in the same RunBlob save. An
       // admission arriving around stop/untrack still lands in `agents` but skips the save,
@@ -999,7 +1010,7 @@ export class RunHost {
         if (run && run.binding === binding) this.feed(run, event);
       },
       // The run-narrative echo attach (ADR-0023), called from `workspace()`'s registrar.
-      echo: (endpoint) => this.attachEcho(record.runId, endpoint),
+      echo: (endpoint, placement) => this.attachEcho(record.runId, endpoint, placement),
     };
     let bound = false;
     const actor = createActor(machine, {

package/src/sandbox-kubectl.ts

@@ -69,7 +69,7 @@ import { readImageRefs, resolveSandboxImage, resolveUserImage, type ImageRefs }
 import { CA_CONFIGMAP, IMAGES_KEY, IMAGES_MOUNT, REPOS_MOUNT } from "./names.ts";
 import { repoIdentity } from "./repo-identity.ts";
 import type { RepoResources } from "./repos.ts";
-import { sandboxToken } from "./tokens.ts";
+import { harnessTokenDigest, sandboxToken } from "./tokens.ts";
 import type { ProvisionedRepo, SandboxPort, WorkspaceSpec } from "./workspace.ts";
 
 /** Run one kubectl invocation to completion. `input` is piped to stdin (`apply -f -`). */
@@ -423,15 +423,23 @@ export function kubectlSandbox(opts: KubectlSandboxOptions = {}): SandboxPort {
   ];
 
   // The Harness container's env: the instance's passthrough (`harness.env` — e.g. model
-  // config) first, then the mechanism-owned vars (the Adapter address, the CA trust path), which
-  // win on collision. Note the asymmetry stands (ADR-0013): user env/envFrom land on the HARNESS
-  // container only — never on the Adapter, whose env is minted here and carries the pod's only
-  // credential.
-  const harnessEnv = (): HarnessEnvVar[] => [
-    ...(opts.env ?? []),
-    { name: "JR2_ADAPTER_URL", value: `http://127.0.0.1:${adapterPort}` },
-    ...(opts.caBundle ? [{ name: "NODE_EXTRA_CA_CERTS", value: `${CA_MOUNT}/ca.crt` }] : []),
-  ];
+  // config) first, then the mechanism-owned vars (the Adapter address, the CA trust path, the
+  // wire's gate), which win on collision. Note the asymmetry stands (ADR-0013): user env/envFrom
+  // land on the HARNESS container only — never on the Adapter, whose env is minted here and
+  // carries the pod's only credential.
+  //
+  // The gate rides LAST (ADR-0058): the digest of the bearer the Orchestrator derives for THIS
+  // Sandbox. A digest because the Agent reads this env; last because a `harness.env` entry of the
+  // same name must not be able to choose the Harness's credential.
+  const harnessEnv = (name: string): HarnessEnvVar[] => {
+    if (!opts.signingKey) throw new Error("kubectlSandbox: a Harness needs a signingKey to check its bearer");
+    return [
+      ...(opts.env ?? []),
+      { name: "JR2_ADAPTER_URL", value: `http://127.0.0.1:${adapterPort}` },
+      ...(opts.caBundle ? [{ name: "NODE_EXTRA_CA_CERTS", value: `${CA_MOUNT}/ca.crt` }] : []),
+      { name: "JR2_HARNESS_TOKEN_SHA256", value: harnessTokenDigest(opts.signingKey, name) },
+    ];
+  };
 
   /**
    * The two init steps, in order (ADR-0037). They are plain container fragments the operator
@@ -573,7 +581,7 @@ export function kubectlSandbox(opts: KubectlSandboxOptions = {}): SandboxPort {
         // this used to carry was unreachable. 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()],
+        env: [...seat.env, ...harnessEnv(req.name)],
         ...(opts.envFrom?.length ? { envFrom: opts.envFrom } : {}),
         // What the AGENT gets: an address on its own loopback, and no credential anywhere. This is
         // the only thing in the pod that tells it how to reach its Machine (ADR-0013).

package/src/server.ts

@@ -25,7 +25,6 @@
 // previous deploy bound — an Instance that drops its last `workspace()` leaves `jr2 gc` able to
 // collect what it stopped using.
 
-import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { loadConfig } from "./config.ts";
 import { loadWorkflows, startInstance, type RunningInstance } from "./instance.ts";
@@ -70,10 +69,7 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
   // by nature, which is what lets live Sandboxes outlive orchestrator restarts (ADR-0013).
   const namespace = env.JR2_NAMESPACE;
 
-  // Resolved HERE, not left for startInstance to mint: every Sandbox Harness gets the token's
-  // sha-256 as its echo gate (ADR-0023, below), so the token must exist before the first
-  // provision. From the instance Secret when deployed; per-boot for a host-booted fixture,
-  // exactly as before.
+  // From the instance Secret when deployed; per-boot for a host-booted fixture.
   const instanceToken = env.JR2_INSTANCE_TOKEN ?? mintInstanceToken();
 
   // The data-plane switch (ADR-0012/0031/0051): a registered Machine COMPOSES a Sandbox — read off
@@ -124,13 +120,6 @@ export async function serverMain(opts: ServerMainOptions): Promise<RunningInstan
             name: "JR2_HARNESS_JSON",
             valueFrom: { configMapKeyRef: { name: HARNESS_CONFIGMAP, key: HARNESS_CONFIG_KEY } },
           },
-          // The echo gate (ADR-0023): the Harness verifies echo bearers against this sha-256. The
-          // digest, never the token — the Agent executes code in the Harness container, and a
-          // digest inverts to nothing (the Instance token itself never enters a Sandbox, ADR-0013).
-          {
-            name: "JR2_ECHO_TOKEN_SHA256",
-            value: createHash("sha256").update(instanceToken).digest("base64url"),
-          },
           ...(config?.harness?.env ?? []).filter((v) => v.valueFrom !== undefined),
         ],
         envFrom: [{ secretRef: { name: HARNESS_ENV_SECRET } }, ...(config?.harness?.envFrom ?? [])],

package/src/tokens.ts

@@ -21,13 +21,20 @@
 //                   Harness's Adapter bears 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
+// checks it:
+//
+//   Harness bearer  what the Orchestrator presents to the Harness in one pod — admit, stream,
+//                   abort, echo. Derived per placement (`harnessToken`); the Harness holds only
+//                   its sha-256 (`harnessTokenDigest`), so it verifies and mints nothing.
+//
 // The Sandbox token is a SIGNED NAME, not a random string in a table: `<sandbox>.<hmac(key, name)>`,
 // 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.
 
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
@@ -46,6 +53,29 @@ export function sandboxToken(key: Buffer, sandbox: string): string {
   return `${sandbox}.${sign(key, sandbox)}`;
 }
 
+/**
+ * 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
+ * Sandbox, or `jr2-instance-harness`). The same signed-name idea as the Sandbox token, turned the
+ * other way: here the Orchestrator is the CALLER. Deterministic for the same reason — a restarted
+ * Orchestrator re-derives the bearer a live Harness already checks against.
+ *
+ * Domain-separated from `sandboxToken` by the `harness:` prefix, which no DNS-label name can
+ * produce, so no Sandbox token ever doubles as a Harness bearer or the reverse.
+ */
+export function harnessToken(key: Buffer, placement: string): string {
+  return sign(key, `harness:${placement}`);
+}
+
+/**
+ * What the Harness in `placement` holds to CHECK its bearer: the sha-256 of it, never the bearer
+ * (ADR-0058). The Agent executes code in that container, and a digest inverts to nothing — so the
+ * Harness can verify its own bearer and can mint none, for itself or for any other pod.
+ */
+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). */
 export function mintInstanceToken(): string {
   return randomBytes(32).toString("base64url");

package/src/workspace.ts

@@ -688,7 +688,7 @@ function buildWorkspaceMachine(body: AnyStateMachine, spec: (args: { input: any
     const wrapperRef = self._parent;
     if (!wrapperRef) return;
     const disposeHandles = registerAmbientHandles(wrapperRef, input.handles);
-    const detachEcho = runBindingOf(system as AnyActorSystem).echo?.(input.handles.endpoint);
+    const detachEcho = runBindingOf(system as AnyActorSystem).echo?.(input.handles.endpoint, input.handles.sandbox);
     return () => {
       detachEcho?.();
       disposeHandles();