@jr2/orchestrator 0.1.4 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.1.4",
+  "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.1.4"
+    "@jr2/agent-protocol": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.1.4"
+    "@jr2/harness": "0.2.1"
   },
   "files": [
     "bin",

package/src/actor.ts

@@ -43,10 +43,16 @@
 // at all, and restore is a fresh process, so there is nothing to infer it from.
 
 import { fromCallback, type CallbackActorLogic } from "xstate";
-import { requireBoundAgent, type AgentDeclaration, type AgentDefinition, type ThinkingLevel } from "./agent.ts";
-import { ambientHandlesFor } from "./ambient.ts";
+import {
+  requireBoundAgent,
+  type AgentDeclaration,
+  type AgentDefinition,
+  type ThinkingLevel,
+  type WorkspaceAccess,
+} from "./agent.ts";
+import { ambientHandlesFor, type AmbientHandles } from "./ambient.ts";
 import { INSTANCE_HARNESS_SERVICE } from "./names.ts";
-import { agentAddress, resolveAccepts, runBindingOf } from "./registration.ts";
+import { agentAddress, continuedIid, resolveAccepts, runBindingOf } from "./registration.ts";
 
 /**
  * One admitted Submission — the durable re-attach handle (ADR-0016). The wire fields are
@@ -72,19 +78,33 @@ export type AgentAdmission = {
 };
 
 /**
- * What a WORKFLOW writes on an Agent slot's invoke (ADR-0015/0016/0049): this turn's prompt —
- * everything else is derived. The AGENT is not written here at all: the slot key is its name
- * (`actors: { coder: agent(def) }`, `src: "coder"`), so a name the Machine does not carry is a
- * compile error on `src` instead of a runtime miss. `jr2Setup.createMachine` wraps the invoke
- * input to finalize it into {@link AgentRunInput}: the slot key lands as `agentName`, the tool
- * menu derives from the invoking state's transitions, the instance id is minted (fresh session by
- * default; `session: "continue"` or a `conversation` pin derives a deterministic id so
- * re-invocations continue one conversation), and endpoint/sandbox resolve ambiently from the
- * enclosing `workspace()`.
+ * What a WORKFLOW writes on an Agent slot's invoke (ADR-0015/0016/0049/0057): this Turn's FRAME,
+ * its DIALS, and whether it CONTINUES — nothing else. The AGENT is not written here at all: the
+ * slot key is its name (`actors: { coder: agent(def) }`, `src: "coder"`), so a name the Machine
+ * does not carry is a compile error on `src` instead of a runtime miss.
+ *
+ * `jr2Setup.createMachine` wraps the invoke input to finalize it into {@link AgentRunInput}: the
+ * slot key lands as `agentName`, the tool menu derives from the invoking state's transitions, the
+ * instance id is MINTED (never written here — fresh by default; `continue: true` derives the
+ * Agent's one conversation in this Machine instance), and endpoint/sandbox resolve ambiently from
+ * the enclosing `workspace()`.
  */
 export type AgentTurnInput = {
-  /** This turn's task framing — lands as the conversation's next user message. */
+  /** Half this Turn's FRAME (ADR-0057) — what it is about: the prompt lands as the conversation's
+   * next user message. Neither identity nor a Dial. */
   prompt: string;
+  /**
+   * The other half of the FRAME (ADR-0057) — WHERE this Turn works: the absolute directory the
+   * Harness roots the Working tools at. Per Turn by nature, which is why no definition names one:
+   * a Worktree path (`/work/<slot>/<branch>`) exists only once a run has a branch.
+   *
+   * Absent, the actor resolves it before admission: a `workspace: "none"` Agent frames no
+   * directory (it has no Working tools to root — ADR-0028), a Workspace with ONE Repo Slot frames
+   * that slot's Worktree, a Workspace with more REFUSES the Turn (the kit gives no slot a meaning
+   * — ADR-0051 — so the state must say which), and a run with no Workspace at all frames nothing
+   * and the Harness keeps `/work`. A relative path is refused at admission, by the Harness.
+   */
+  cwd?: string;
   /**
    * This turn's DIALS (ADR-0018) — how hard to run, layered over the definition's own
    * values. One definition value may be carried by several Machines, so the same persona
@@ -92,38 +112,46 @@ export type AgentTurnInput = {
    * and the same reviewer on an architecture change want identical instructions and different
    * effort.
    *
-   * IDENTITY is deliberately absent — no `instructions`, `workspace` or `cwd` here. A call site
-   * that rewrote those would make the Agent's name a lie, and `workspace` in particular carries
+   * IDENTITY is deliberately absent — no `instructions` or `workspace` here. A call site that
+   * rewrote those would make the Agent's name a lie, and `workspace` in particular carries
    * ADR-0028's containment claim, which per-invocation escalation would void.
    */
   model?: string;
   thinkingLevel?: ThinkingLevel;
   /**
-   * Session continuity (ADR-0016). Absent = FRESH: every invocation is a new conversation
-   * (jr's lossy handoff — revision agents read notes + code, never the prior conversation).
-   * `"continue"` = the same `(state path, agent, scope)` re-invocation continues ONE
-   * conversation; the prompt lands as its next user turn.
-   */
-  session?: "continue";
-  /** Distinguishes conversations that would otherwise share a `continue` identity (e.g. a
-   * reviewer fresh per task: `scope: task.id`). */
-  scope?: string;
-  /**
-   * Pin the conversation to a workflow-chosen name — the CROSS-MACHINE continue (ADR-0016's
-   * opt-in continuation, where `session: "continue"` cannot reach: its derived id carries the
-   * invoking actor's path, so it only spans states of one machine). Invocations naming the same
-   * `conversation` derive ONE deterministic, run-scoped instance id (`<runId>/<name>/<agent>`)
-   * wherever in the actor tree they sit — a triage state before the `workspace()` and an assess
-   * state inside its body continue one conversation, the prompt landing as its next user turn.
-   * Only sound where every invocation lands on the same Harness, because a conversation is an
-   * Instance ID on ONE server: a `workspace: "none"` Agent (always the Instance Harness —
-   * definition-wins, ADR-0031) or a fixed explicit `endpoint`.
+   * Continue this Agent's ONE conversation in this Machine instance (ADR-0016, ADR-0057) — the
+   * whole continuation surface. Absent, every invocation is a FRESH conversation (jr's lossy
+   * handoff — revision agents read notes + code, never the prior conversation). Present, the
+   * prompt lands as the next user turn of that conversation, whichever state of the Machine
+   * invokes it: states differ by Menu (a coder in `implement` offers `finish`; the same coder in
+   * `fix` offers `finish` and `dispute`) and the conversation is wanted across them.
+   *
+   * It names nothing, because the id is STRUCTURAL — `<runId>/<machine actor path>/<agent>` — and
+   * a caller-chosen key could only restate that, or contradict it. Two Agents therefore never
+   * share a conversation (the name is in the id), and two Pool children never collide (each
+   * worker is its own Machine instance). A conversation jr2 has faulted is never continued: the
+   * next `continue` lands on a virgin one (ADR-0035, ADR-0057) — and re-briefing that Turn is the
+   * author's, because jr2 cannot write that prompt.
    */
-  conversation?: string;
-  /** Workspace-less runs only (stub Harness): explicit endpoint, no ambient resolution. */
+  continue?: true;
+};
+
+/**
+ * MECHANISM, not authoring surface (ADR-0057): where a Turn's Harness is and which Sandbox scopes
+ * its deliveries, STATED instead of resolved. It is the seat the stub tier sits in — a
+ * mechanics-tier test has no `workspace()` to resolve from, and a dev Harness is just a URL
+ * (ADR-0011) — so it is exported for those tests and for nothing else.
+ *
+ * A real run states neither: a Sandbox Agent resolves both ambiently from the enclosing
+ * `workspace()` (ADR-0016), and a `workspace: "none"` Agent lands on the Instance Harness
+ * (ADR-0031). Stated, it wins over both, because a URL a test wrote is the one thing no ambient
+ * walk can know about.
+ */
+export type AgentTurnPlacement = {
+  /** The Harness base URL this Turn is admitted over. */
   endpoint?: string;
-  /** Escape hatch: override the derived menu. */
-  tools?: readonly string[];
+  /** The Sandbox whose Adapter token may deliver this Turn's picks (ADR-0013). */
+  sandbox?: string;
 };
 
 /** What the actor is invoked with AFTER jr2Setup finalization: the durable handle, this turn's
@@ -149,6 +177,9 @@ export type AgentRunInput = {
    */
   sandbox?: string;
   prompt?: string;
+  /** The other half of this Turn's Frame (ADR-0057): where the Working tools are rooted. Rides the
+   * admit body beside the prompt; absent, the Harness keeps `/work`. */
+  cwd?: string;
   /** This turn's dials, passed through from {@link AgentTurnInput}. Plain strings, so they ride
    * the persisted child input; on restore the Submission already exists server-side with its
    * model fixed, so a re-attach never re-resolves them. */
@@ -160,20 +191,15 @@ export type AgentRunInput = {
    */
   attach?: AgentAdmission;
   /**
-   * This invocation is closed to the ADR-0035 reroll — set by the input mapper for
-   * `session: "continue"` and a `conversation` pin (both name an EXISTING conversation, and
-   * the runaway's one recovery is a fresh one — exactly what they opted out of), and for a
-   * caller-passed `instanceId` (fresh on its first invocation, but jr2 did not mint the id and
-   * must not derive reroll identity from one it does not own — ADR-0016's minting doctrine).
-   * A gated runaway goes straight to the terminal fault.
+   * This invocation CONTINUES an existing conversation — set by the input mapper from
+   * `continue: true` alone (ADR-0057), and nothing else. Two things hang off it:
    *
-   * A continuation carries NO check that it continues the same persona (ADR-0049, closing
-   * consequence, open): two Machines that each carry a `coder` slot and pin the same
-   * `conversation` continue one conversation under two definitions, and the second Turn gets its
-   * own instructions and Working-tool filter over the first's context. The ledger holds no
-   * definition to compare against, and adding a digest would refuse an edited-`instructions`
-   * redeploy too, which ADR-0030 lets continue — so the refusal waits on a persona identity that
-   * survives a retune.
+   *   - it is closed to the ADR-0035 reroll: the runaway's one recovery is a fresh conversation,
+   *     which is exactly what a continuation opted out of, and a continued Turn's prompt
+   *     ("Continue.") is meaningless replayed fresh. A gated runaway goes straight to the fault;
+   *   - a terminal `agent.fault` BURNS the conversation (ADR-0057): the epoch bumps in the host
+   *     ledger, so the next `continue` on this Agent mints a virgin id. Nothing is burned for a
+   *     fresh invocation, which already mints its own conversation.
    */
   continuation?: boolean;
   /** Event names (from the invoking Machine's vocabulary) this invocation accepts over MCP. */
@@ -231,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 = {
@@ -277,6 +305,50 @@ function nudgePrompt(tools: readonly string[]): string {
   );
 }
 
+/**
+ * Where this Turn works — the Frame's other half (ADR-0057), resolved before admission.
+ *
+ * The state's own `cwd` IS the Frame and wins outright, for every Agent: what is resolved here is
+ * an ABSENT one, and a directory a state named is never second-guessed — a Menu-only Agent handed
+ * one simply has no Working tools to root there (ADR-0028/0031).
+ *
+ * Absent, a Menu-only Agent frames no directory; a Workspace with ONE Repo Slot frames that
+ * slot's Worktree, which privileges nothing because there is nothing to choose between (ADR-0051);
+ * a Workspace with more REFUSES the Turn, naming the slots in declaration order and the line that
+ * ends it, because the kit gives no slot a meaning and a wrong guess is the silent failure
+ * ADR-0057 was written for; and a run outside any Workspace frames nothing, so the Harness keeps
+ * `/work`.
+ *
+ * Resolution counts SLOTS, and a slot's Worktree is the writable branch checkout. The detached
+ * review Worktree (`AmbientHandles.review`, ADR-0028's reviewer seat) is never resolved to: it is
+ * per review round, so only the reviewing state knows which one, and it frames it (ADR-0028 hands
+ * the reviewer its path as "cwd and prompt"). A `workspace: "read"` Agent that frames nothing
+ * under a one-slot Workspace therefore works in the branch checkout with `write`/`edit` withheld
+ * and `bash` kept — the tool layer's hint, not containment (ADR-0028): containment is the
+ * detached review Worktree, and only a reviewing state that requested one can frame it.
+ *
+ * The refusal throws at invoke, like the Open-model fence: loudly, at the first Turn, before a
+ * surface is registered or a pod is spent.
+ */
+function frameCwd(
+  instanceId: string,
+  input: AgentRunInput,
+  workspace: WorkspaceAccess,
+  ambient: AmbientHandles | undefined,
+): string | undefined {
+  if (input.cwd !== undefined) return input.cwd;
+  if (workspace === "none") return undefined;
+  const slots = Object.keys(ambient?.repos ?? {});
+  if (slots.length === 0) return undefined;
+  if (slots.length === 1) return ambient!.repos[slots[0]!];
+  throw new Error(
+    `turn ${instanceId}: agent "${input.agentName}" works under a Workspace carrying more than one ` +
+      `Repo Slot (${slots.join(", ")}) 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)`,
+  );
+}
+
 /** One Agent slot's logic: the run-lifecycle actor closed over ONE definition and BRANDED with it
  * (ADR-0049). The brand is the whole resolution mechanism — the actor reads its definition off its
  * own closure, `jr2Setup` recognizes the slot by `isAgent`, and a `.provide()` that swaps the slot
@@ -285,7 +357,10 @@ function nudgePrompt(tools: readonly string[]): string {
  * The brand is a RUNTIME property, read back through `isAgent`, and deliberately NOT part of this
  * type: the unit-test seam is `provide({ actors: { coder: fake } })` (ADR-0049), and a required
  * `definition` here would make every fake carry a definition it never uses. */
-export type AgentLogic = CallbackActorLogic<AgentRunReceiveEvent, AgentTurnInput | AgentRunInput>;
+export type AgentLogic = CallbackActorLogic<
+  AgentRunReceiveEvent,
+  AgentTurnInput | (AgentTurnInput & AgentTurnPlacement) | AgentRunInput
+>;
 
 /**
  * Build one Agent slot's actor logic over an injected port factory — the seam `agent()` (bound to
@@ -313,7 +388,10 @@ export function agentActorWith(
   // Typed as the union so BOTH shapes typecheck on an invoke: jr2Setup machines write
   // AgentTurnInput (and the config wrapper finalizes it before the actor ever runs); plain
   // setup() machines must pass the finalized shape themselves — checked loudly below.
-  const logic = fromCallback<AgentRunReceiveEvent, AgentTurnInput | AgentRunInput>((args) => {
+  const logic = fromCallback<
+    AgentRunReceiveEvent,
+    AgentTurnInput | (AgentTurnInput & AgentTurnPlacement) | AgentRunInput
+  >((args) => {
     const { system, self, sendBack, receive } = args;
     const input = args.input as AgentRunInput;
     const { instanceId } = input;
@@ -339,6 +417,9 @@ export function agentActorWith(
     // are unreachable (ADR-0013).
     const binding = runBindingOf(system);
     const workspace = definition.workspace ?? "write";
+    // The enclosing workspace()'s handles, walked structurally up the actor parent chain — the
+    // Harness coordinates below and the Frame's `cwd` both read them (ADR-0013/0016/0057).
+    const ambient = ambientHandlesFor(self);
     let endpoint: string;
     let sandbox: string | undefined;
     if (input.endpoint) {
@@ -359,7 +440,6 @@ export function agentActorWith(
       // Workspace's. The Instance token still may (it is the operator, tokens.ts).
       sandbox = INSTANCE_HARNESS_SERVICE;
     } else {
-      const ambient = ambientHandlesFor(self);
       if (!ambient?.endpoint) {
         throw new Error(
           `turn ${instanceId}: agent "${input.agentName}" has workspace: "${workspace}" — ` +
@@ -371,6 +451,12 @@ export function agentActorWith(
       sandbox = input.sandbox ?? ambient.sandbox;
     }
 
+    // The Frame's other half (ADR-0057): WHERE this Turn works. Resolved HERE, before any surface
+    // is registered and before a pod is spent, because the answer is a fact about the run — a
+    // Worktree path exists only once a run has a branch, so no definition could have named it.
+    const cwd = frameCwd(instanceId, input, workspace, ambient);
+    const framed: AgentRunInput = cwd === undefined ? input : { ...input, cwd };
+
     // Register this invocation's event surface (throws on a name outside the INVOKING MACHINE's
     // vocabulary — ADR-0011's invoke-time check, scoped to `self._parent.logic` because names are
     // per-Machine — which errors the run loudly at the invoking state).
@@ -420,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>>());
@@ -476,17 +565,23 @@ export function agentActorWith(
     // Any budget exhausting emits the ONE terminal `agent.fault { reason }`.
     void (async () => {
       const fault = (reason: string) => {
-        if (!stopped) sendBack({ type: "agent.fault", instanceId, reason } satisfies FaultTelemetry);
+        if (stopped) return;
+        // Burn the conversation before the fault lands (ADR-0057): the state the fault routes to
+        // may invoke this Agent again in the same macrostep, and its mapper must already read the
+        // bumped epoch. Continuations only — a fresh invocation mints its own conversation, so
+        // there is nothing to burn.
+        if (input.continuation) binding.bumpEpoch?.(continuedIid(self._parent, binding.runId, input.agentName));
+        sendBack({ type: "agent.fault", instanceId, reason } satisfies FaultTelemetry);
       };
       try {
         // Queue behind any abort still in flight for this iid (ADR-0024). Non-trivial only under
-        // `session: "continue"`, which is the only way two invocations share an instance id — and
+        // `continue: true`, which is the only way two invocations share an instance id — and
         // there it is mandatory: the Harness queues per conversation and an abort settles what
         // is queued behind it, so losing this race would kill the new turn before it ran, silently.
         await pendingAborts.get(instanceId);
         let admission = input.attach;
         if (!admission) {
-          admission = await client.admit(input, { definition, signal: controller.signal });
+          admission = await client.admit(framed, { definition, signal: controller.signal });
           ledger(admission);
           // The admission marker (ADR-0023): the Turn and its framing, once — a re-attach
           // continues a Turn already announced, and a nudge (below) is mechanism, not narrative
@@ -521,7 +616,7 @@ export function agentActorWith(
             currentIid = `${instanceId}-r${rerolls}`;
             registerSurface(currentIid);
             admission = await client.admit(
-              { ...input, attach: undefined, instanceId: currentIid },
+              { ...framed, attach: undefined, instanceId: currentIid },
               { definition, signal: controller.signal },
             );
             ledger(admission);
@@ -540,7 +635,7 @@ export function agentActorWith(
             reason: "no-signal nudge",
           });
           admission = await client.admit(
-            { ...input, attach: undefined, instanceId: currentIid, prompt: nudgePrompt(input.tools) },
+            { ...framed, attach: undefined, instanceId: currentIid, prompt: nudgePrompt(input.tools) },
             { definition, signal: controller.signal },
           );
           ledger(admission);

package/src/agent.ts

@@ -30,7 +30,11 @@ export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhi
  * (ADR-0031): the value the Agent actor reads off its own slot's definition to place the Turn. */
 export type WorkspaceAccess = "write" | "read" | "none";
 
-/** The plain-data Agent definition (ADR-0018). Must stay JSON-serializable: the definition rides
+/** The plain-data Agent definition (ADR-0018): IDENTITY plus one default. A Turn's Frame — what
+ * it is about and where it works — is not here and cannot be (ADR-0057): a Worktree path exists
+ * only once a run has a branch, so no definition written before the run could name one.
+ *
+ * Must stay JSON-serializable: the definition rides
  * the Turn to the Harness (ADR-0049), so anything non-serializable would be silently lost — grow
  * this contract deliberately. ADR-0028 added a restriction vocabulary (`workspace`), not an
  * extension one: custom tool implementations stay out of the contract. */
@@ -45,9 +49,6 @@ export type AgentDefinition = {
   instructions: string;
   /** Optional static description — observability, never sent to the model. */
   description?: string;
-  /** Working directory inside the Sandbox. Default `/work` — the pod volume the attach step put
-   * the worktrees on (ADR-0005); override only for non-Workspace layouts. */
-  cwd?: string;
   /** Reasoning effort. Omitted → the runtime's default. An invocation may override it for one
    * Turn (`AgentTurnInput.thinkingLevel`) — effort is a property of the task's difficulty, so the
    * same persona legitimately runs at different settings in different Machines. */
@@ -56,9 +57,9 @@ export type AgentDefinition = {
    * not `tools` (that names the control-plane Menu, what it may SAY). `"read"` withholds the
    * write/edit Working tools; bash stays, so this states intent and stops the honest path — the
    * detached review worktree is the containment. `"none"` withholds the ENTIRE Working toolset:
-   * the Menu-only Agent converses and picks from its Menu, nothing else (`cwd` is moot — only
-   * Working tools consume it) — and places the Turn on the Instance Harness (ADR-0031).
-   * Default `"write"`. */
+   * the Menu-only Agent converses and picks from its Menu, nothing else (so its Turn frames no
+   * directory — only Working tools consume one) — and places the Turn on the Instance Harness
+   * (ADR-0031). Default `"write"`. */
   workspace?: WorkspaceAccess;
 };
 

package/src/gate.ts

@@ -46,7 +46,7 @@ export const gate = fromCallback<DeliveredEvent, GateInput | undefined>(({ input
   const binding = runBindingOf(system);
   // The derived id is deterministic from machine structure, so recomputing it on every (re)start
   // is restore-stable and needs no input-mapper persistence — the mapper is only load-bearing
-  // where minting has a random component (mintIid's fresh-session suffix, ADR-0016).
+  // where minting has a random component (mintIid's fresh-Turn suffix, ADR-0016).
   const path = actorPath(self);
   const id = input.gate ?? path.join(".");
   if (!id) {

package/src/harness-client.ts

@@ -49,16 +49,21 @@ import {
 /** The three-verb wire client (the injectable seam — structurally what `@flue/sdk`'s
  * `agents.{send,wait,abort}` was, minus the SDK). */
 export type HarnessClient = {
-  /** `POST /agents/:name/:id {message, definition, model?, thinkingLevel?}` → the Admission, with
-   * `streamUrl` resolved absolute. The DEFINITION is the slot's, carried by the Machine and sent
-   * with every admission (ADR-0049) — the Harness keeps no roster, so `:name` alone would name
-   * nothing there. The optional dials are this Submission's override layer (ADR-0018); omitted,
-   * the Harness runs the definition's own values. */
+  /** `POST /agents/:name/:id {message, cwd?, definition, model?, thinkingLevel?}` → the Admission,
+   * with `streamUrl` resolved absolute. The FRAME is `message` and `cwd` — what this Turn is about
+   * and where it works (ADR-0057), flat siblings on the body. The DEFINITION is the slot's,
+   * carried by the Machine and sent with every admission (ADR-0049) — the Harness keeps no roster,
+   * so `:name` alone would name nothing there — and it travels as IDENTITY alone, because this
+   * verb strips `description` (ADR-0057; see {@link admittedDefinition}). The optional dials are this Submission's override
+   * layer (ADR-0018); omitted, the Harness runs the definition's own values. */
   send(
     agentName: string,
     instanceId: string,
     options: {
       message: string;
+      /** Where the Working tools are rooted for this Turn (ADR-0057). Omitted, the Harness keeps
+       * `/work` — the stub-Harness run with no Workspace. */
+      cwd?: string;
       definition: AgentDefinition;
       model?: string;
       thinkingLevel?: ThinkingLevel;
@@ -75,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`;
@@ -120,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();
@@ -187,12 +197,21 @@ 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
+            // UNSET, and the Harness keeps `/work`; anything else — including the empty string a
+            // miscomputed worktree path would produce — travels, because a `cwd` the Harness
+            // cannot read as an absolute path is a 400 there. Dropping it here would hand that
+            // Turn the `/work` default instead: the silent wrong directory ADR-0057 exists for.
+            ...(sendOptions.cwd === undefined ? {} : { cwd: sendOptions.cwd }),
             // The Agent this Turn runs (ADR-0049) — plain data, validated at admission by the
             // Harness, which 400s naming the slot rather than settling a Submission `failed`.
-            definition: sendOptions.definition,
+            // IDENTITY only: `description` is stripped here (ADR-0057). It is Console material —
+            // `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),
             // Omitted when unset, so an admission with no dials is byte-identical to before.
             ...(sendOptions.model ? { model: sendOptions.model } : {}),
             ...(sendOptions.thinkingLevel ? { thinkingLevel: sendOptions.thinkingLevel } : {}),
@@ -224,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})`);
           }
@@ -260,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) {
@@ -271,6 +299,15 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
   };
 }
 
+/** The definition as the ADMISSION carries it (ADR-0057): identity alone. `description` is
+ * Console material the Orchestrator strips before admission — the Harness has no use for it and
+ * no longer validates it. Every other field travels, so a field added to the definition reaches
+ * the Harness without a change here. */
+function admittedDefinition(definition: AgentDefinition): Omit<AgentDefinition, "description"> {
+  const { description: _description, ...identity } = definition;
+  return identity;
+}
+
 /** Build an `AgentRunPort` over an injected wire client. Stateless — the admission IS the handle. */
 export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
   return {
@@ -280,6 +317,10 @@ export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
       }
       return await client.send(input.agentName, input.instanceId, {
         message: input.prompt,
+        // The Frame's other half (ADR-0057) — absent on a workspace-less run, where `/work` is
+        // what the Harness keeps. Absent means UNSET: a cwd the mapper computed travels as it is,
+        // to the Harness's refusal if it is not a path.
+        ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
         definition: opts.definition,
         model: input.model,
         thinkingLevel: input.thinkingLevel,
@@ -307,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> {
@@ -329,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 });
@@ -359,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 {