@jr2/orchestrator 0.5.1 → 0.6.0

package/src/effector-wire.ts

@@ -14,6 +14,7 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { lookup } from "node:dns/promises";
 import { z } from "zod";
+import type { LaterOutcome } from "./effect.ts";
 
 // --- The request (POST /effects/<id>) ------------------------------------------------------------
 //
@@ -104,10 +105,10 @@ export const PairShape = z.strictObject({
 });
 export type Pair = z.infer<typeof PairShape>;
 
-/** A `push` start: the Workspace's branch to the Repo Slot's Binding, with the push credential of
+/** A `push` start: a cut Worktree's branch to the Repo Slot's Binding, with the push credential of
  * the `git.credentials` entry the url falls under — the Effector's config holds the entries, and
  * matches the url as the fence does (`credential` names one by its `match` instead). `pin` is the
- * commit; absent, the Effector reads the Agent's branch tip and its answer carries it (`pinned`).
+ * commit; absent, the Effector reads the branch's tip and its answer carries it (`pinned`).
  */
 export const PushStartShape = z.strictObject({
   kind: z.literal("push"),
@@ -259,6 +260,8 @@ export const HttpOutputShape = z.union([
  * - `unknown`: the call can have gone out, but no answer came, or jr2 cannot tell after a restart.
  *   `reason` tells why. jr2 does not send it again unless it is marked `idempotent`.
  *
+ * The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+ *
  * @example
  * ```ts
  * import { fail, http, jr2Setup, type HttpOutput } from "@jr2/orchestrator";
@@ -291,7 +294,7 @@ export const HttpOutputShape = z.union([
  * @see docs/guides/run-a-command-or-call-a-url.md
  * @see docs/reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md
  */
-export type HttpOutput = z.infer<typeof HttpOutputShape>;
+export type HttpOutput = z.infer<typeof HttpOutputShape> | LaterOutcome;
 
 /**
  * A `push` Effect's output (ADR-0067). `pushed`: the published commit, its source (the Agent's

package/src/fail.ts

@@ -87,24 +87,37 @@ export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL
  * @example
  * ```ts
  * import { z } from "zod";
- * import { command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ * import { command, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
  *
  * const runInput = z.object({ branch: z.string() });
+ * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+ *
+ * const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
  *
  * const body = jr2Setup({
- *   types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
+ *   types: {} as { input: BodyInput; context: BodyInput },
  *   actors: {
+ *     cut: worktree(),
  *     tests: command(["npm", "test"], { timeout: "15m" }),
  *     fail: fail(),
  *   },
  * }).createMachine({
  *   id: "check",
+ *   context: ({ input }) => input,
  *   on: { "workspace.lost": ".lost" },
- *   initial: "testing",
+ *   initial: "cutting",
  *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+ *       },
+ *     },
  *     testing: {
  *       invoke: {
  *         src: "tests",
+ *         input: ({ context }) => ({ worktree: testTree(context) }),
  *         onDone: [
  *           {
  *             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -117,6 +130,7 @@ export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL
  *     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
  *     failing: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
  *     passed: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
  *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  *   },
  * });
@@ -124,7 +138,6 @@ export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL
  * export const machine = workspace(body, {
  *   input: runInput,
  *   repos: { app: "https://github.com/you/app.git" },
- *   spec: ({ input }) => ({ branch: input.branch }),
  * });
  * ```
  *

package/src/harness-client.ts

@@ -107,6 +107,9 @@ export type HarnessClient = {
        * `/work` — the stub-Harness run with no Workspace. */
       cwd?: string;
       definition: AgentDefinition;
+      /** The Agent's slot (ADR-0076), which the Harness states on each control request for this
+       * conversation. Omitted only by a caller that drives no Machine (a test of the wire). */
+      slot?: string;
       model?: string;
       thinkingLevel?: ThinkingLevel;
       /** The pending notices in this admission's scope (ADR-0062). Omitted when there are none. */
@@ -382,6 +385,8 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
             // `machine-doc.ts` and the surface read it — and the Harness neither validates nor
             // uses it, so it has no business on the Turn's wire.
             definition: admittedDefinition(sendOptions.definition),
+            // Who the conversation is (ADR-0076): the Harness states it on each control request.
+            ...(sendOptions.slot === undefined ? {} : { slot: sendOptions.slot }),
             // Omitted when unset, so an admission with no dials is byte-identical to before.
             ...(sendOptions.model ? { model: sendOptions.model } : {}),
             ...(sendOptions.thinkingLevel ? { thinkingLevel: sendOptions.thinkingLevel } : {}),
@@ -629,6 +634,7 @@ export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
         // to the Harness's refusal if it is not a path.
         ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
         definition: opts.definition,
+        slot: opts.slot,
         model: input.model,
         thinkingLevel: input.thinkingLevel,
         ...(opts.notices?.length ? { notices: opts.notices } : {}),
@@ -751,8 +757,9 @@ export function createLiveSetPush(options: {
  * `invoke: { src: "coder", input: { prompt } }`. The key is the Agent's name.
  *
  * The invoke's `input` is the Turn: `prompt` (required), `cwd`, `model`, `thinkingLevel` and
- * `continue`. `cwd` is the absolute directory where the Working tools work. Absent, it is the
- * Worktree of the Workspace's one Repo Slot. `continue: true` continues the Agent's conversation
+ * `continue`. `cwd` is the absolute directory where the Working tools work. Under Repo Slots it
+ * is required: a Worktree that a cut made, `<slot>/default` to read, or `/work`. An Agent with
+ * `workspace: "none"`, and a Workspace with no Repo Slot, need no `cwd`. `continue: true` continues the Agent's conversation
  * in this Machine. Absent, each Turn starts a new conversation. `continue` is the literal `true`,
  * not a `boolean`. A Turn can join only a conversation that an earlier Turn started with
  * `continue: true`. Thus in a retry loop, put `continue: true` on each Turn, also on the first, so
@@ -778,10 +785,9 @@ export function createLiveSetPush(options: {
  * - a key in `input` that a Turn does not have: ``agent "<slot>": the Turn's input carries
  *   `<key>`, which a Turn has no use for — its input is its Frame (`prompt`, `cwd`), its Dials
  *   (`model`, `thinkingLevel`), and `continue` (ADR-0057)``
- * - no `cwd` under a Workspace with more than one Repo Slot: ``turn <id>: agent "<slot>" works
- *   under a Workspace carrying more than one Repo Slot (<slots>) and its Turn framed no `cwd` —
- *   say which Worktree it works in (`cwd: context.workspace.repos.<slot>`, one of those), because
- *   the kit gives no slot a meaning (ADR-0051) and a Turn's Frame is where it works (ADR-0057)``
+ * - no `cwd` under Repo Slots: ``turn <id>: agent "<slot>" works under a Workspace with Repo Slots
+ *   (<slots>) and its Turn framed no `cwd`: say where it works, a Worktree, or `cwd: "/work"` above
+ *   them (ADR-0057)``
  * - a `cwd` that is not an absolute path: ``agent "<slot>": the Turn's Frame carries a `cwd` that
  *   is not an absolute path — the Frame says WHERE this Turn works (ADR-0057), and a Turn rooted
  *   anywhere else would work in the wrong directory silently``. The Harness makes this refusal
@@ -801,7 +807,16 @@ export function createLiveSetPush(options: {
  * @example
  * ```ts
  * import { z } from "zod";
- * import { agent, defineEvent, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ * import {
+ *   agent,
+ *   defineEvent,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
  *
  * const finish = defineEvent({
  *   name: "finish",
@@ -811,6 +826,8 @@ export function createLiveSetPush(options: {
  * const runInput = z.object({ branch: z.string() });
  * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
  *
+ * const fixTree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+ *
  * const body = jr2Setup({
  *   types: {} as { input: BodyInput; context: BodyInput },
  *   events: [finish],
@@ -819,26 +836,35 @@ export function createLiveSetPush(options: {
  *       model: "anthropic/claude-haiku-5-5",
  *       instructions: "You fix failing tests. You change no test.",
  *     }),
+ *     cut: worktree(),
  *     fail: fail(),
  *   },
  * }).createMachine({
  *   id: "fix",
  *   context: ({ input }) => input,
  *   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
- *   initial: "coding",
+ *   initial: "cutting",
  *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: fixTree(context), branch: context.branch }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+ *       },
+ *     },
  *     coding: {
  *       invoke: {
  *         src: "coder",
  *         input: ({ context }) => ({
  *           prompt: "Make `node --test` pass, then commit.",
- *           cwd: context.workspace.repos.app,
+ *           cwd: fixTree(context),
  *           thinkingLevel: "high",
  *         }),
  *       },
  *       on: { finish: "done" },
  *     },
  *     done: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
  *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
  *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  *   },
@@ -847,7 +873,6 @@ export function createLiveSetPush(options: {
  * export const machine = workspace(body, {
  *   input: runInput,
  *   repos: { app: "https://github.com/you/app.git" },
- *   spec: ({ input }) => ({ branch: input.branch }),
  * });
  * ```
  *
@@ -856,6 +881,9 @@ export function createLiveSetPush(options: {
  * @see docs/reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md
  * @see docs/reference/decisions/0057-a-turn-is-its-frame-its-dials-and-whether-it-continues.md
  */
+export function agent<const D extends AgentDeclaration>(
+  declaration: D,
+): AgentLogic & (D extends { workspace: "none" } ? { readonly definition: { readonly workspace: "none" } } : unknown);
 export function agent(declaration: AgentDeclaration): AgentLogic {
   // THE authoring surface for an Agent (ADR-0049): one definition in, one actor slot out. The
   // slot key is the Agent's name (the Harness route, the minted iid, the markers), so a name the
@@ -956,8 +984,8 @@ export function createExecPort(options: {
  *
  * Where it runs:
  * - With no Effect secret in `env`, in the Harness container of the enclosing Workspace's Sandbox.
- *   It runs in the Worktree of a Repo Slot, or in `/work` in a Workspace with no Repo Slot. The
- *   Agent's Working tools also run in this container.
+ *   It runs in the Worktree that `worktree` of the invoke's input names, or in `/work` in a
+ *   Workspace with no Repo Slot. The Agent's Working tools also run in this container.
  * - With an Effect secret in `env`, in the Sandbox Effector, against a commit of the branch. This
  *   is the branch tip when it starts, or with `pin: true` the commit that the invoke's `input.sha`
  *   names. The output then says `dirty: true` when the Worktree held edits that the command did
@@ -994,11 +1022,9 @@ export function createExecPort(options: {
  * And when it starts, with no Effect secret in `env`:
  * - outside a `workspace()`: `command "<slot>" runs in the Harness container of a Workspace, and
  *   its state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
- * - no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
- *   Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it
- *   runs in: command(argv, { slot: "<slot>" }) (ADR-0051)`
- * - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
- *   its Workspace does not carry (<slots>)`
+ * - no `worktree` under Repo Slots: `` command "<slot>" runs under a Workspace with Repo Slots
+ *   (<slots>) and its input names no `worktree`: say which, a Worktree that a cut gave or
+ *   `<slot>/default` ``
  * - an `arg()` with no string in `input`: `command "<slot>": argv slot <<name>> has no string
  *   value in its input (got <type>) — map it in the invoke's input`. The angle brackets around the
  *   arg's name are in the text: `argv slot <file>`. `<type>` is `nothing` when `input` has no such
@@ -1007,15 +1033,13 @@ export function createExecPort(options: {
  * And when it starts, with an Effect secret in `env`:
  * - outside a `workspace()`: `command "<slot>" runs in the Sandbox Effector of a Workspace, and its
  *   state is not inside a workspace() — invoke it from a Workspace's body (ADR-0067)`
- * - no `slot` under a Workspace with more than one Repo Slot: `command "<slot>" runs under a
- *   Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" }
- *   (ADR-0051)`
  * - a Workspace with no Repo Slot: `command "<slot>" runs under a Workspace with no Repo Slot: a
  *   command with an Effect secret runs against one commit of a Repo Slot's branch, and there is
  *   none — declare a Repo Slot, or name no secret in its env, and it runs in /work beside the Agent
  *   (ADR-0051)`. `jr2 up` refuses it first, with the same reason
- * - a `slot` that the Workspace does not have: `command "<slot>" names Repo Slot "<name>", which
- *   its Workspace does not carry (<slots>)`
+ * - a `worktree` that no cut made in this Sandbox: the output is `exited` 127, with `no cut made
+ *   <path> in this Sandbox: cut it with worktree()` in its tail. A detached Worktree gets the same
+ *   form
  * - `pin: true` and an `input.sha` that is not a full commit id: `command "<slot>" (pin): its
  *   input's sha is not a full commit id`
  * - an `arg()` with no string in `input`: the same text as above.
@@ -1023,8 +1047,7 @@ export function createExecPort(options: {
  * @param argv - The program and its arguments: strings and `arg("name")` entries. Or `open`, in a
  *   Machine that you publish as a package, for the Instance that registers it to bind with
  *   `customize()`.
- * @param options - Optional. `slot`: the Repo Slot whose Worktree the command runs in; needed only
- *   where the Workspace has more than one. `timeout`: `"90s"`, `"10m"` or `"1h"`, default
+ * @param options - Optional. `timeout`: `"90s"`, `"10m"` or `"1h"`, default
  *   `"10m"`; when it expires, the output is `timeout`. `tail`: how many characters of the end of
  *   the output stream to keep, default 4096. `env`: environment variables. Each value is
  *   `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a
@@ -1035,26 +1058,46 @@ export function createExecPort(options: {
  * @example
  * ```ts
  * import { z } from "zod";
- * import { arg, command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ * import {
+ *   arg,
+ *   command,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
  *
  * const runInput = z.object({ branch: z.string() });
  * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
  *
+ * const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
+ *
  * const body = jr2Setup({
- *   types: {} as { input: BodyInput },
+ *   types: {} as { input: BodyInput; context: BodyInput },
  *   actors: {
+ *     cut: worktree(),
  *     tests: command(["node", "--test", arg("file")], { timeout: "5m" }),
  *     fail: fail(),
  *   },
  * }).createMachine({
  *   id: "check",
+ *   context: ({ input }) => input,
  *   on: { "workspace.lost": ".lost" },
- *   initial: "testing",
+ *   initial: "cutting",
  *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+ *       },
+ *     },
  *     testing: {
  *       invoke: {
  *         src: "tests",
- *         input: { file: "test/greet.test.js" },
+ *         input: ({ context }) => ({ file: "test/greet.test.js", worktree: testTree(context) }),
  *         onDone: [
  *           {
  *             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -1067,6 +1110,7 @@ export function createExecPort(options: {
  *     passed: { type: "final" },
  *     // Not final states: each one fails the run, and the run ends `failed`.
  *     failed: { invoke: { src: "fail", input: { reason: "the test did not pass" } } },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
  *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  *   },
  * });
@@ -1074,7 +1118,6 @@ export function createExecPort(options: {
  * export const machine = workspace(body, {
  *   input: runInput,
  *   repos: { app: "https://github.com/you/app.git" },
- *   spec: ({ input }) => ({ branch: input.branch }),
  * });
  * ```
  *
@@ -1086,7 +1129,7 @@ export function createExecPort(options: {
 export function command<const A extends readonly (string | Arg)[], const Opt extends CommandOptions = CommandOptions>(
   argv: A,
   options?: Opt,
-): EffectLogic<CommandInput<A, Opt["pin"]>, CommandOutput> & OpenOf<EnvOpenParts<Opt>>;
+): EffectLogic<CommandInput<A, Opt["pin"], Opt>, CommandOutput> & OpenOf<EnvOpenParts<Opt>>;
 /**
  * Make a `command` Effect whose argv is Open: `command(open, options)`, in a Machine that you
  * publish as a package. The Instance that registers the Machine binds the argv one time:
@@ -1103,7 +1146,7 @@ export function command<const A extends readonly (string | Arg)[], const Opt ext
 export function command<const Opt extends CommandOptions = CommandOptions>(
   argv: typeof open,
   options?: Opt,
-): EffectLogic<OpenCommandInput<Opt["pin"]>, CommandOutput> & OpenEffect<"argv" | EnvOpenParts<Opt>>;
+): EffectLogic<OpenCommandInput<Opt["pin"], Opt>, CommandOutput> & OpenEffect<"argv" | EnvOpenParts<Opt>>;
 export function command(
   argv: readonly (string | Arg)[] | typeof open,
   options: CommandOptions = {},

package/src/harness-env.ts

@@ -0,0 +1,33 @@
+// What a Harness container's env tells its start (ADR-0076): which names jr2 composed. The Harness
+// starts as `effector nocore --harness-env -- node …`, and that gives the Harness PROCESS only the
+// names jr2 composed, less each name that loads code from a path (`NODE_OPTIONS`, `LD_*`,
+// `OPENSSL_CONF` …), because the image's `ENV` can name a file that Workspace code writes. The
+// domain, where the Agent's programs run, still gets the container's whole start env.
+//
+// Two marks make the names jr2 composed visible inside the container:
+//   - `JR2_HARNESS_ENV_NAMES`: the names of the container's `env`, comma-separated.
+//   - The prefix `JR2_ENVFROM_` before each `envFrom` key (with a source's own prefix after it):
+//     its keys are not known here, a user's Secret or ConfigMap among them. The start puts each key
+//     back under its own name, below a name of `env`, as Kubernetes orders them.
+
+/** The env name that lists the names of the Harness container's `env`. */
+export const HARNESS_ENV_NAMES_ENV = "JR2_HARNESS_ENV_NAMES";
+
+/** The prefix before each `envFrom` key of a Harness container. */
+export const HARNESS_ENVFROM_PREFIX = "JR2_ENVFROM_";
+
+/** The Harness container's `env` with `JR2_HARNESS_ENV_NAMES` last, and its `envFrom` with the
+ * prefix `JR2_ENVFROM_`. Both Harness placements use it: a Sandbox's and the Instance Harness. */
+export function markHarnessEnv<E extends { name: string }, F extends { prefix?: string }>(
+  env: readonly E[],
+  envFrom: readonly F[],
+): { env: (E | { name: string; value: string })[]; envFrom: F[] } {
+  const names = [...new Set(env.map((v) => v.name))].filter((n) => n !== HARNESS_ENV_NAMES_ENV);
+  return {
+    env: [
+      ...env.filter((v) => v.name !== HARNESS_ENV_NAMES_ENV),
+      { name: HARNESS_ENV_NAMES_ENV, value: names.join(",") },
+    ],
+    envFrom: envFrom.map((f) => ({ ...f, prefix: `${HARNESS_ENVFROM_PREFIX}${f.prefix ?? ""}` })),
+  };
+}

package/src/held-secrets.ts

@@ -9,7 +9,8 @@
 //
 // This module is the pure half, shared by every seat that needs it:
 //
-//   standIn(name)        the value the Harness sees — deterministic and public
+//   heldStandIn(...)     a held secret's Stand-in, minted per pod by the pod's maker — secret
+//   standIn(name)        the fetch Stand-in's form — deterministic and public, for that one alone
 //   heldSecretsOf(...)   `jr2 up`'s normalization of the claimed entries: every refusal (R1–R13),
 //                        every warning, and the engine-neutral bindings each pod's manifest
 //                        (`held-<pod>.json`) takes its own from
@@ -23,23 +24,46 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { isIP } from "node:net";
 import type { JR2Config, HarnessEnvVar } from "./config.ts";
-import { MODEL_KEYS, MODEL_KEY_PROVIDERS, SIGNING_CREDENTIALS } from "./model-keys.ts";
-import { HELD_CA_SECRET, HELD_SECRETS_SECRET, HELD_TLS_SECRET, INSTANCE_EFFECTOR, INSTANCE_SECRET } from "./names.ts";
+import {
+  CREDENTIAL_FILES,
+  DOMAIN_WRITABLE_ROOTS,
+  MODEL_KEYS,
+  MODEL_KEY_PROVIDERS,
+  SIGNING_CREDENTIALS,
+} from "./model-keys.ts";
+import {
+  HELD_CA_SECRET,
+  HELD_SECRETS_SECRET,
+  HELD_TLS_SECRET,
+  INSTANCE_EFFECTOR,
+  INSTANCE_HARNESS_SERVICE,
+  INSTANCE_SECRET,
+} from "./names.ts";
 import type { PlacementRoute } from "./parts.ts";
+import { sign } from "./tokens.ts";
 
 /** The kit's Secrets no Harness container may read (R13): the Instance token and signing key, each
  * pod's literal held values, the leaves, the CA, and every Effector's (ADR-0068) — the Instance
  * Effector's Effect secrets and key, each Workspace's Sandbox Effector Secret (`jr2-effector-<pod>`),
  * each Sandbox's Effector key (`<sandbox>-effector`), and each `git.credentials` entry's clone and
- * push Secrets (`jr2-git-<hash>`, `jr2-git-push-<hash>`, ADR-0051). */
-const KIT_SECRETS: readonly string[] = [INSTANCE_SECRET, HELD_TLS_SECRET, HELD_CA_SECRET, INSTANCE_EFFECTOR];
+ * push Secrets (`jr2-git-<hash>`, `jr2-git-push-<hash>`, ADR-0051) — and each pod's own credentials
+ * (ADR-0076): the Instance Harness's (`jr2-instance-harness-token`) and each Sandbox's
+ * (`<sandbox>-token`), which hold the real control token beside the Stand-ins. */
+const KIT_SECRETS: readonly string[] = [
+  INSTANCE_SECRET,
+  HELD_TLS_SECRET,
+  HELD_CA_SECRET,
+  INSTANCE_EFFECTOR,
+  `${INSTANCE_HARNESS_SERVICE}-token`,
+];
 const KIT_SECRET_PREFIXES: readonly string[] = [`${HELD_SECRETS_SECRET}-`, "jr2-effector-", "jr2-git-"];
 const isKitSecret = (name: string): boolean =>
   KIT_SECRETS.includes(name) ||
   name === HELD_SECRETS_SECRET ||
   KIT_SECRET_PREFIXES.some((p) => name.startsWith(p)) ||
-  // A Sandbox's own Effector key: every Sandbox's name starts `ws-` (`workspaceName`).
-  (name.startsWith("ws-") && name.endsWith("-effector"));
+  // A Sandbox's own Effector key and its credentials: every Sandbox's name starts `ws-`
+  // (`workspaceName`).
+  (name.startsWith("ws-") && (name.endsWith("-effector") || name.endsWith("-token")));
 
 /**
  * The pod key of one Workspace (ADR-0059): its registered workflow and the placement route to its
@@ -70,18 +94,36 @@ export function providerClaims(config: JR2Config, models: readonly string[]): st
 }
 
 /**
- * The Stand-in for one held secret: what its env var holds in the Harness container.
- *
- * Deterministic and public — it is not a secret, the Agent reads it from its env, and it means
- * something only to the Custodian and only toward a bound host. Unique per name, so one request can
- * carry two secrets' Stand-ins and the Custodian can tell them apart. ASCII letters, digits, `-`
- * and `_` only, so it is a valid header and env value; and it never contains `sk-ant-oat`, which pi
- * reads as an Anthropic OAuth token and answers with different auth headers.
+ * The PUBLIC Stand-in form, `jr2-held-<NAME>`. Since ADR-0076 one Stand-in alone takes it: the fetch
+ * Stand-in, `standIn("JR2_SANDBOX_TOKEN")`, which `jr2-upload-pack` holds as a constant and the
+ * Custodian swaps on the fetch route alone. Every other Stand-in is secret ({@link heldStandIn}).
  */
 export function standIn(name: string): string {
   return `jr2-held-${name}`;
 }
 
+/** What a Stand-in must never contain (ADR-0059): pi reads a key with it as an Anthropic OAuth
+ * token, and answers with different auth headers. */
+const OAUTH_MARK = "sk-ant-oat";
+
+/**
+ * The SECRET Stand-in of one held secret in one pod (ADR-0059, ADR-0076): what the Harness process
+ * holds for it, as the file `/run/jr2/standins/<NAME>`, and what the Custodian of that pod swaps for
+ * the value. `jr2-held-<NAME>.<hmac>` — the readable prefix keeps a log scrub's pattern, and the
+ * HMAC under the signing key makes it unguessable, so Workspace code can spend only the secrets its
+ * `workspace()` grants. `pod` is the Sandbox's name, or `instance` for the Instance Harness. The
+ * pod's maker mints it: the Orchestrator for a Sandbox, `jr2 up` for the Instance Harness and a
+ * check pod. ASCII letters, digits, `-`, `_` and `.` only, so it is a valid header and env value,
+ * and it never contains `sk-ant-oat`: a signature that would is signed again under a counter.
+ */
+export function heldStandIn(key: Buffer, pod: string, name: string): string {
+  for (let n = 0; ; n++) {
+    const domain = `held-standin:${pod}/${name}${n === 0 ? "" : `#${n}`}`;
+    const value = `${standIn(name)}.${sign(key, domain)}`;
+    if (!value.includes(OAUTH_MARK)) return value;
+  }
+}
+
 /** The request headers a Stand-in is swapped in when a held secret names none — the four places a
  * model API carries its key: `Authorization: Bearer` (OpenAI-compatible, `ANTHROPIC_AUTH_TOKEN`),
  * `x-api-key` (Anthropic), `x-goog-api-key` (Gemini), `api-key` (Azure). */
@@ -99,10 +141,15 @@ export const CREDENTIAL_HEADERS: readonly string[] = [...DEFAULT_CREDENTIAL_HEAD
 /** The env var the custom provider's key rides as (ADR-0018) — held since ADR-0059, and the kit's. */
 export const PROVIDER_KEY_NAME = "JR2_PROVIDER_API_KEY";
 
-/** The Sandbox token's env var (ADR-0013) — a held secret of the kit's own, bound to the
- * Orchestrator (ADR-0059). The Harness container holds its Stand-in; the Custodian holds the token. */
+/** The fetch token's held name (ADR-0013, ADR-0076) — a held secret of the kit's own, bound to the
+ * Orchestrator's fetch route (ADR-0059). Its Stand-in is the public `jr2-held-JR2_SANDBOX_TOKEN`,
+ * which `jr2-upload-pack` holds; the Custodian holds the token. */
 export const SANDBOX_TOKEN_NAME = "JR2_SANDBOX_TOKEN";
 
+/** The control token's held name (ADR-0076) — the kit's own, bound to the agent routes. Its Stand-in
+ * is secret: the Harness process alone holds it, as `/run/jr2/control/standin`. */
+export const CONTROL_TOKEN_NAME = "JR2_CONTROL_TOKEN";
+
 /** The env names the mechanism owns on a Harness container (ADR-0059): the proxy, the trust
  * bundles, and every `JR2_` name. A held secret may not choose them, and while a held secret exists,
  * `harness.env` may not either — the Custodian cannot chain to a second proxy yet (R11). */
@@ -233,6 +280,35 @@ export function heldSecretsOf(
     catalogHosts.set(id, target.port === 443 ? target.host : `${target.host}:${target.port}`);
   }
 
+  // jr2's own names (ADR-0076): the Harness's start takes a `JR2_` name from jr2's composition alone,
+  // and refuses to start on an envFrom key that starts with `JR2_` (`effector nocore --harness-env`).
+  // A user's `JR2_MENU_ONLY` or `JR2_START_ENV` would turn the domain off or replace its env.
+  for (const [i, v] of env.entries()) {
+    if (v.name.startsWith("JR2_")) {
+      throw new Error(
+        `harness.env[${i}] sets ${v.name}: JR2_ names are jr2's own, and the Harness takes them from jr2 alone ` +
+          "(ADR-0076). Name the env var your program reads.",
+      );
+    }
+  }
+  for (const [i, ref] of (harness.envFrom ?? []).entries()) {
+    const lookup = ref.secretRef
+      ? `secret/${ref.secretRef.name}`
+      : ref.configMapRef
+        ? `configmap/${ref.configMapRef.name}`
+        : "";
+    const own = (lookups.envFromKeys?.get(lookup) ?? [])
+      .map((key) => (ref.prefix ?? "") + key)
+      .find((key) => key.startsWith("JR2_"));
+    if (own !== undefined) {
+      const where = ref.secretRef ? `Secret "${ref.secretRef.name}"` : `ConfigMap "${ref.configMapRef?.name}"`;
+      throw new Error(
+        `harness.envFrom[${i}] loads ${where}, which carries ${own}: JR2_ names are jr2's own, and the Harness ` +
+          "does not start with one from envFrom (ADR-0076). Drop the key, or give the source a prefix.",
+      );
+    }
+  }
+
   // R1: a known model key the Agent could read.
   for (const [i, v] of env.entries()) {
     if (!(v.name in MODEL_KEYS)) continue;
@@ -268,6 +344,39 @@ export function heldSecretsOf(
     }
   }
 
+  // A credential file that the Harness process reads (ADR-0076): never one that the domain writes.
+  for (const [i, v] of env.entries()) {
+    if (!CREDENTIAL_FILES.includes(v.name)) continue;
+    const path = v.value;
+    if (path !== undefined) {
+      const writable = DOMAIN_WRITABLE_ROOTS.find((root) => path === root || path.startsWith(`${root}/`));
+      if (!path.startsWith("/") || writable !== undefined || path.split("/").includes("..")) {
+        throw new Error(
+          `harness.env[${i}] sets ${v.name} to "${path}", ${writable !== undefined ? `which is in ${writable}, a folder the Agent's code writes` : "which is not an absolute path"}: the Harness process reads that file, and code that writes it acts outside the Agent's confinement (ADR-0076). Point it at a file of the image that the Sandbox's user cannot write.`,
+        );
+      }
+    }
+    warnings.push(
+      `harness.env sets ${v.name}: the Harness process reads ${path !== undefined ? `"${path}"` : "the file it names"}, ` +
+        "so the Sandbox's user must not be able to write it — a folder of the image that the user owns is one the " +
+        "Agent's code writes (ADR-0076)",
+    );
+  }
+  for (const [i, ref] of (harness.envFrom ?? []).entries()) {
+    const lookup = ref.secretRef
+      ? `secret/${ref.secretRef.name}`
+      : ref.configMapRef
+        ? `configmap/${ref.configMapRef.name}`
+        : "";
+    for (const key of (lookups.envFromKeys?.get(lookup) ?? []).map((k) => (ref.prefix ?? "") + k)) {
+      if (!CREDENTIAL_FILES.includes(key)) continue;
+      warnings.push(
+        `harness.envFrom[${i}] sets ${key}: the Harness process reads the file it names, so the Sandbox's user must ` +
+          "not be able to write it — a folder of the image that the user owns is one the Agent's code writes (ADR-0076)",
+      );
+    }
+  }
+
   type Entry = {
     at: string;
     name: string;

package/src/holds.ts

@@ -38,6 +38,9 @@ export type Hold = {
   /** The Sandbox whose token may read the answer (ADR-0013) — the registration's, kept because the
    * answer outlives a registration that a route out of the Agent's state ends. */
   sandbox?: string;
+  /** The slot whose stated control requests may read the answer (ADR-0076) — the registration's,
+   * kept with `sandbox` for the same reason. */
+  slot?: string;
   /** The invoke id of the Agent's state when the pick was made: a re-registration of the same
    * address by another state is another Turn. */
   invokeId?: string;