@jr2/orchestrator 0.5.1 → 0.6.0

package/src/http-effect.ts

@@ -77,6 +77,7 @@ import {
   type WireBody,
 } from "./effector-wire.ts";
 import { boundRun, type AnyActorSystem } from "./registration.ts";
+import type { AnyWorktreePath } from "./worktree.ts";
 import { open } from "./open.ts";
 import { effectBindingShape, openEffectLogic, openPartsOf, type OpenOf } from "./open-effect.ts";
 import { httpFileWith, sandboxEffectorPort } from "./sandbox-effect.ts";
@@ -169,13 +170,25 @@ const openSecretOf = new WeakMap<object, object>();
  *
  * @example
  * ```ts
- * import { command, fail, jr2Setup, secret, workspace, type Workspaced } from "@jr2/orchestrator";
+ * import {
+ *   command,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   secret,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
  *
  * type Input = Workspaced<{}, "app">;
  *
+ * const deployTree = (context: Input) => `${context.workspace.repos.app}/deploy` as const;
+ *
  * const body = jr2Setup({
  *   types: {} as { context: Input; input: Input },
  *   actors: {
+ *     cut: worktree(),
  *     // The command reads the file at $KUBECONFIG. The Agent never reads the secret.
  *     deploy: command(["kubectl", "apply", "-f", "k8s/"], {
  *       env: { KUBECONFIG: secret("kube").path },
@@ -186,17 +199,26 @@ const openSecretOf = new WeakMap<object, object>();
  *   id: "deploy",
  *   context: ({ input }) => input,
  *   on: { "workspace.lost": ".lost" },
- *   initial: "deploying",
+ *   initial: "cutting",
  *   states: {
- *     deploying: { invoke: { src: "deploy", onDone: "done" } },
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: deployTree(context), branch: "deploy" }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "deploying" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     deploying: {
+ *       invoke: { src: "deploy", input: ({ context }) => ({ worktree: deployTree(context) }), onDone: "done" },
+ *     },
  *     done: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
  *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  *   },
  * });
  *
  * export const machine = workspace(body, {
  *   repos: { app: { url: "https://github.com/you/app.git" } },
- *   spec: () => ({ branch: "deploy" }),
  * });
  * ```
  *
@@ -501,15 +523,12 @@ function asText(v: string | Secret | Text): Text {
 /** A value of a file body's part: as written, or from the Effect's input. */
 export type FromInput<S, T> = T | ((input: S extends z.ZodType ? z.infer<S> : void) => T);
 
-/** `file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body. */
+/** `file(path, { segments?, contentType? })`: a Worktree file as an `http` body. */
 export type FileBody<S extends z.ZodType | undefined = undefined> = {
   readonly file: {
-    /** The file, relative to the Repo Slot's Worktree, or to `/work` in a Workspace with no Repo
-     * Slot. */
+    /** The file, relative to the Worktree that `worktree` of the Effect's input names, or to `/work`
+     * in a Workspace with no Repo Slot. */
     readonly path: FromInput<S, string>;
-    /** The Repo Slot whose Worktree holds it. Write it only when the Workspace has more than one.
-     */
-    readonly slot?: string;
     /** Path segments that jr2 adds to the end of the url, as `path` of `request` does for a json
      * or text body. */
     readonly segments?: FromInput<S, readonly string[]>;
@@ -521,14 +540,18 @@ export type FileBody<S extends z.ZodType | undefined = undefined> = {
 
 /**
  * Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`. The Effect
- * then runs in the Sandbox Effector of the Workspace whose body invokes it. That Effector opens the
- * file in the Worktree and sends it. In a Workspace with no Repo Slot, the path is relative to
+ * then runs in the Sandbox Effector of the Workspace whose body invokes it. Under a Workspace with
+ * Repo Slots, the invoke's input names the Worktree: `input: { worktree: "/work/app/fix" }`. It is a
+ * Worktree that a cut of this run made. That Effector opens the file in that Worktree and sends it.
+ * In a Workspace with no Repo Slot, the input names no `worktree`, and the path is relative to
  * `/work`, the folder that its steps share. Use it with `PUT`, `POST` or `PATCH`. `path` and
  * `segments` can be functions of the input of the Effect.
  *
- * Some paths and files give the output `refused`, and then nothing is sent. The path has a symlink
- * in it, has `..`, or is absolute. Or the file is a FIFO, a directory, or a file with more than one
- * link.
+ * Some inputs, paths and files give the output `refused`, and then nothing is sent. The `worktree`
+ * has no cut in this Sandbox: `no cut made <path> in this Sandbox: cut it with worktree(); nothing
+ * was sent`. Or the input names a `worktree` in a Workspace with no Repo Slot. Or the path has a
+ * symlink in it, has `..`, or is absolute. Or the file is a FIFO, a directory, or a file with more
+ * than one link.
  *
  * It refuses, when you call it:
  * - a path that is not a string or a function: `file(path): the path is a string, or a function of
@@ -548,8 +571,13 @@ export type FileBody<S extends z.ZodType | undefined = undefined> = {
  * there is no Worktree to read; invoke it from a workspace()'s body, or send a json or text body
  * (ADR-0068)`.
  *
- * @param path - The file, relative to the Worktree of the Repo Slot, or to `/work` in a Workspace
- *   with no Repo Slot: a string, or a function of the input of the Effect that gives one.
+ * And when it starts, under a Workspace with Repo Slots, an input with no `worktree`: ``http
+ * "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its input names no
+ * `worktree` ``.
+ *
+ * @param path - The file, relative to the Worktree that `worktree` of the input names, or to
+ *   `/work` in a Workspace with no Repo Slot: a string, or a function of the input of the Effect
+ *   that gives one.
  * @param options - Optional. Each field says what it does.
  * @returns The `body` of an `http` Effect.
  *
@@ -561,17 +589,22 @@ export type FileBody<S extends z.ZodType | undefined = undefined> = {
  *   fail,
  *   file,
  *   http,
+ *   isReady,
  *   jr2Setup,
  *   secret,
  *   workspace,
+ *   worktree,
  *   type Workspaced,
  * } from "@jr2/orchestrator";
  *
  * type Input = Workspaced<{}, "app">;
  *
+ * const reportTree = (context: Input) => `${context.workspace.repos.app}/report` as const;
+ *
  * const body = jr2Setup({
  *   types: {} as { context: Input; input: Input },
  *   actors: {
+ *     cut: worktree(),
  *     build: command(["npm", "run", "report"]),
  *     upload: http({
  *       method: "PUT",
@@ -588,18 +621,29 @@ export type FileBody<S extends z.ZodType | undefined = undefined> = {
  *   id: "report",
  *   context: ({ input }) => input,
  *   on: { "workspace.lost": ".lost" },
- *   initial: "building",
+ *   initial: "cutting",
  *   states: {
- *     building: { invoke: { src: "build", onDone: "uploading" } },
- *     uploading: { invoke: { src: "upload", onDone: "done" } },
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: reportTree(context), branch: "report" }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     building: {
+ *       invoke: { src: "build", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "uploading" },
+ *     },
+ *     uploading: {
+ *       invoke: { src: "upload", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "done" },
+ *     },
  *     done: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
  *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  *   },
  * });
  *
  * export const machine = workspace(body, {
  *   repos: { app: { url: "https://github.com/you/app.git" } },
- *   spec: () => ({ branch: "report" }),
  * });
  * ```
  *
@@ -610,9 +654,6 @@ export type FileBody<S extends z.ZodType | undefined = undefined> = {
 export function file<S extends z.ZodType | undefined = undefined>(
   path: FromInput<S, string>,
   options: {
-    /** The Repo Slot whose Worktree holds the file. Write it only when the Workspace has more than
-     * one. */
-    slot?: string;
     /**
      * Path segments that jr2 adds to the end of the url, as `path` does in `request` for a json or
      * text body. A list of strings, or a function of the input of the Effect that gives one.
@@ -633,7 +674,6 @@ export function file<S extends z.ZodType | undefined = undefined>(
   return {
     file: {
       path,
-      ...(options.slot !== undefined ? { slot: options.slot } : {}),
       ...(options.segments !== undefined ? { segments: options.segments } : {}),
       ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
     },
@@ -723,10 +763,13 @@ export type HttpDefinition<S extends z.ZodType | undefined = undefined> = {
   request?: (input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts;
   // A file body is an ADR-0067 Effect: the Sandbox Effector of the Workspace sends it.
   /**
-   * A Worktree file as the body: `file(path, { slot?, segments?, contentType? })`. The Effect then
-   * runs in the Sandbox Effector of its Workspace. Do not write `request` beside it: the `segments`
+   * A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+   * runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+   * input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+   * it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+   * input names no `worktree` ``. Do not write `request` beside it: the `segments`
    * of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
-   * slot?, segments?, contentType? }) — json and text come from `request` ``.
+   * segments?, contentType? }) — json and text come from `request` ``.
    */
   body?: FileBody<S>;
   /**
@@ -755,6 +798,11 @@ export type HttpDefinition<S extends z.ZodType | undefined = undefined> = {
 /** @internal */
 export type HttpInput<S> = S extends z.ZodType ? z.infer<S> : void;
 
+/** The input of an `http` Effect with a Worktree file as its body. Under a Workspace with Repo
+ * Slots, `worktree` names the Worktree. In a Workspace with no Repo Slot, the input has no
+ * `worktree`, and the path is relative to `/work`. */
+export type HttpFileInput<S> = (S extends z.ZodType ? z.infer<S> : unknown) & { worktree?: AnyWorktreePath };
+
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_BODY = 65_536;
 /** How long a re-asked request waits, at most, after a transport failure. */
@@ -830,7 +878,7 @@ export function httpParts<S extends z.ZodType | undefined>(def: HttpDefinition<S
   const body = def.body?.file;
   if (def.body !== undefined && (typeof body !== "object" || body === null)) {
     throw new Error(
-      "http({ body }): a body is file(path, { slot?, segments?, contentType? }) — json and text come from `request`",
+      "http({ body }): a body is file(path, { segments?, contentType? }) — json and text come from `request`",
     );
   }
   if (body && !FILE_METHODS.includes(def.method)) {
@@ -866,7 +914,6 @@ export function httpParts<S extends z.ZodType | undefined>(def: HttpDefinition<S
     ...(body
       ? {
           file: {
-            ...(body.slot !== undefined ? { slot: body.slot } : {}),
             ...(body.contentType !== undefined ? { contentType: body.contentType } : {}),
           },
         }
@@ -1347,8 +1394,9 @@ function parseDuration(d: Duration): number {
  * src: "comment" }`.
  *
  * It runs in the Instance Effector, which `jr2 up` deploys when a Machine has an `http` Effect.
- * With `body: file(...)`, it runs in the Sandbox Effector of the Workspace whose body invokes it.
- * The Effector makes the call. The Orchestrator holds no secret.
+ * With `body: file(...)`, it runs in the Sandbox Effector of the Workspace whose body invokes it,
+ * and under Repo Slots its input names the Worktree in `worktree`. The Effector makes the call. The
+ * Orchestrator holds no secret.
  *
  * Every outcome is output (`HttpOutput`): `response`, `unreachable`, `refused` or `unknown`. A 4xx
  * or 5xx status is output too. jr2 sends the call at most one time, unless you mark it
@@ -1402,6 +1450,14 @@ function parseDuration(d: Duration): number {
  * @see docs/reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md
  * @see docs/reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md
  */
+export function http<
+  S extends z.ZodType | undefined = undefined,
+  const U extends HttpDefinition<S>["url"] = string,
+  const A extends HttpDefinition<S>["auth"] = undefined,
+  const H extends HttpDefinition<S>["headers"] = undefined,
+>(
+  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H; body: FileBody<S> },
+): EffectLogic<HttpFileInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>;
 export function http<
   S extends z.ZodType | undefined = undefined,
   const U extends HttpDefinition<S>["url"] = string,

package/src/http.ts

@@ -61,7 +61,14 @@ import {
 } from "./registration.ts";
 import type { RepoStatus } from "./repos.ts";
 import { UnmountedRepoError, type FetchAnswer } from "./repo-fetch.ts";
-import { mayAskForSandbox, mayDeliverToAgent, type Authenticator, type Principal } from "./tokens.ts";
+import {
+  isAgentPrincipal,
+  mayAskForSandbox,
+  mayDeliverToAgent,
+  SLOT_HEADER,
+  type Authenticator,
+  type Principal,
+} from "./tokens.ts";
 import {
   DispatchKeyConflictError,
   keyAnswer,
@@ -387,8 +394,9 @@ export const HTTP_ROUTES: readonly HttpRoute[] = [
     method: "GET",
     path: "/agents/:instanceId/surface",
     band: "authenticated",
-    summary: "An Agent's Menu and this Turn's Allowed picks. A Sandbox token reads only its own Sandbox's.",
-    response: "AgentSurfaceView",
+    summary:
+      "An Agent's Menu, this Turn's Allowed picks and the conversation's pending notices. A control token reads only its own pod's, for the slot it states.",
+    response: "AgentSurfaceView & { notices: Array<{ id, notice }> }",
     stream: false,
     adrs: ["0013", "0029"],
   },
@@ -411,11 +419,21 @@ export const HTTP_ROUTES: readonly HttpRoute[] = [
     stream: false,
     adrs: ["0013", "0024"],
   },
+  {
+    method: "POST",
+    path: "/agents/:instanceId/notices",
+    band: "authenticated",
+    summary: "Acknowledge the notices a step boundary appended to the Turn: they are heard in its conversation.",
+    body: "{ heard: string[] }",
+    response: "{ heard: number }",
+    stream: false,
+    adrs: ["0062", "0076"],
+  },
   {
     method: "POST",
     path: "/sandboxes/:name/fetch",
     band: "authenticated",
-    summary: "Ask the node cache to fetch one Repo that this Sandbox mounts. A Sandbox token asks only for its own.",
+    summary: "Ask the node cache to fetch one Repo that this Sandbox mounts. A fetch token asks only for its own.",
     body: "{ identity }",
     response: "FetchAnswer: { fetched } | { stale, asOf }",
     stream: false,
@@ -828,7 +846,8 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
    * hand every Agent in the cluster a delivery API, which is the hole this ADR exists to close. */
   const authenticated: MiddlewareHandler<JR2Env> = async (c, next) => {
     if (!auth) return next(); // no authenticator configured: tests only (see the doc comment)
-    const principal = auth(bearerOf(c));
+    // The slot a control request states (ADR-0076): a control token without one resolves to nothing.
+    const principal = auth(bearerOf(c), c.req.header(SLOT_HEADER));
     if (!principal) return c.json({ error: "unauthorized" }, 401);
     if (principal.kind === "publisher") return c.json({ error: PUBLISHER_ONLY }, 403);
     c.set("principal", principal);
@@ -847,7 +866,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
    */
   const instanceOnly: MiddlewareHandler<JR2Env> = async (c, next) => {
     if (!auth) return next(); // no authenticator configured: tests only (see the doc comment)
-    const principal = auth(bearerOf(c));
+    const principal = auth(bearerOf(c), c.req.header(SLOT_HEADER));
     if (!principal) return c.json({ error: "unauthorized" }, 401);
     if (principal.kind === "publisher") return c.json({ error: PUBLISHER_ONLY }, 403);
     if (principal.kind !== "instance") {
@@ -1288,11 +1307,11 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // the gated state. Unknown gate (never opened, state exited, run settled) → 404; a name the gate
   // doesn't accept, or a payload failing its schema → 400 naming what IS accepted.
   //
-  // A Gate is a HUMAN's decision (or a webhook's, or CI's). An Agent holding a Sandbox token is
-  // refused here unconditionally — this is the exact line between "the Agent reports an outcome"
-  // and "the Agent approves its own PR" (ADR-0013).
+  // A Gate is a HUMAN's decision (or a webhook's, or CI's). Every Agent principal — a control
+  // token or a fetch token — is refused here unconditionally: this is the exact line between "the
+  // Agent reports an outcome" and "the Agent approves its own PR" (ADR-0013, ADR-0076).
   app.post("/runs/:runId/gates/:gate/events", authenticated, async (c) => {
-    if (principalOf(c).kind === "sandbox") {
+    if (isAgentPrincipal(principalOf(c))) {
       return c.json({ error: "a Sandbox token cannot deliver to a gate — gates are not on the Agent's surface" }, 403);
     }
     const body = await readJson(c.req.text());
@@ -1419,7 +1438,9 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // and delivery are implemented once, in `registration.ts`.
 
   /** Guard: the surface must exist, and this principal must be allowed to speak for it. */
-  const agentRegistration = (c: Context<JR2Env, "/agents/:instanceId/surface" | "/agents/:instanceId/events">) => {
+  const agentRegistration = (
+    c: Context<JR2Env, "/agents/:instanceId/surface" | "/agents/:instanceId/events" | "/agents/:instanceId/notices">,
+  ) => {
     const instanceId = c.req.param("instanceId");
     // Only a Turn that is over answers 404 (ADR-0026). While the host is stopping its runs are
     // parked for restore, not over, so every `/agents/*` call answers 503: the Harness re-asks a
@@ -1442,9 +1463,10 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
     // iid) → there is no surface to serve. 404 BEFORE the scope check — a caller with a valid
     // token learns nothing from it that it did not already know.
     if (!surface) return { error: c.json({ error: `no live agent surface for instance "${instanceId}"` }, 404) };
-    if (!mayDeliverToAgent(principalOf(c), surface.sandbox)) {
-      // A Sandbox token for a DIFFERENT Sandbox (or for a workspace-less run, which no Sandbox
-      // owns). This is the check that keeps one feature's coder out of another's reviewer.
+    if (!mayDeliverToAgent(principalOf(c), surface)) {
+      // A control token for a DIFFERENT pod (or for a workspace-less run, which no pod owns), a
+      // stated slot that is not this registration's (ADR-0076), or a fetch token. The first is the
+      // check that keeps one feature's coder out of another's reviewer.
       return { error: c.json({ error: `this token cannot speak for instance "${instanceId}"` }, 403) };
     }
     return { surface };
@@ -1454,11 +1476,28 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
   // semantics, fixed for the conversation — and this Turn's Allowed picks (ADR-0029). A transition
   // swaps the registration, which swaps the Allowed picks, never the Menu; the Harness reads both
   // per Submission and needs no `list_changed`.
-  app.get("/agents/:instanceId/surface", authenticated, (c) => {
+  // The same read at a step boundary carries the conversation's pending notices in its audience
+  // (ADR-0062), reserved for this read: the Harness appends them and acknowledges them below.
+  app.get("/agents/:instanceId/surface", authenticated, async (c) => {
     const { surface, error } = agentRegistration(c);
     if (error) return error;
     host.agentSurfaceServed(c.req.param("instanceId"));
-    return c.json(surface);
+    const notices = await host.boundaryNotices(c.req.param("instanceId"));
+    return c.json({ ...surface, notices });
+  });
+
+  // The Harness appended a step boundary's notices to the Turn (ADR-0062, ADR-0076): they are heard
+  // in that conversation, ledgered in one save. An id this conversation did not reserve is ignored,
+  // so the call says nothing a caller did not already know.
+  app.post("/agents/:instanceId/notices", authenticated, async (c) => {
+    const { error } = agentRegistration(c);
+    if (error) return error;
+    const body = await readJson(c.req.text());
+    const heard = (body as { heard?: unknown }).heard;
+    if (!Array.isArray(heard) || heard.some((id) => typeof id !== "string")) {
+      return c.json({ error: "an acknowledgment names the notices heard: { heard: string[] }" }, 400);
+    }
+    return c.json({ heard: host.noticesHeard(c.req.param("instanceId"), heard as string[]) });
   });
 
   // The Agent's pick, delivered into the state that invoked it. The receipt describes itself
@@ -1514,7 +1553,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
       return c.json({ error: restorePendingMessage(`delivery "${deliveryId}"`) }, 503);
     }
     if (!scope) return c.json({ error: `no delivery "${deliveryId}" for instance "${instanceId}"` }, 404);
-    if (!mayDeliverToAgent(principalOf(c), scope.sandbox)) {
+    if (!mayDeliverToAgent(principalOf(c), scope)) {
       return c.json({ error: `this token cannot speak for instance "${instanceId}"` }, 403);
     }
     const receipt = await host.awaitDelivery(instanceId, deliveryId, opts.deliveryWaitMs, c.req.raw.signal);

package/src/index.ts

@@ -33,12 +33,25 @@ export type { Binding, RepoSlot } from "./parts.ts";
 // Effects: work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071),
 // and what an author writes between a pick and that work.
 export { arg } from "./effect.ts";
-export type { CommandOutput } from "./effect.ts";
+export type { CommandOutput, LaterOutcome } from "./effect.ts";
 export { command } from "./harness-client.ts";
 export { basic, bearer, file, http, secret, text } from "./http-effect.ts";
 export type { HttpOutput } from "./effector-wire.ts";
 export { push } from "./sandbox-effect.ts";
 export type { PushOutput } from "./sandbox-effect.ts";
+export { branchName, isReady, readyOf, worktree } from "./worktree.ts";
+export type {
+  AnyFramePath,
+  AnyWorktreePath,
+  FramePath,
+  WorktreeFound,
+  WorktreeInput,
+  WorktreeOptions,
+  WorktreeOutput,
+  WorktreePath,
+  WorktreeReady,
+  WorktreeRefused,
+} from "./worktree.ts";
 export { dispatch } from "./dispatch-effect.ts";
 export type { DispatchOutput } from "./effect.ts";
 export { answer, fromPick, paramsOf } from "./pick.ts";
@@ -51,6 +64,7 @@ export type { Customize } from "./customize.ts";
 export type { EffectBinding } from "./open-effect.ts";
 export type { Size, UserContainer } from "./size.ts";
 export { pool, source } from "./pool.ts";
+export type { PoolNextInput } from "./pool.ts";
 
 // Charts: the Open body a Chart wrapper places in `actors`, and the grammar a planner's pick
 // declares, whole or narrowed to one wrapper (ADR-0070).

package/src/internal.ts

@@ -59,6 +59,7 @@ export * from "./secret-placement.ts";
 export * from "./git-push.ts";
 export * from "./git-clone.ts";
 export * from "./custodian.ts";
+export * from "./harness-env.ts";
 export * from "./sandbox-kube.ts";
 export {
   effectorManifestKey,

package/src/kube-client.ts

@@ -108,7 +108,7 @@ export interface KubeClient {
   /** Create; an existing object is a {@link KubeError} with status 409. */
   create<T extends KubeObject>(kind: KubeKind, namespace: string, body: T): Promise<T & KubeObject>;
   /** Delete; true when there was one to delete, false when it was already gone. */
-  delete(kind: KubeKind, namespace: string, name: string): Promise<boolean>;
+  delete(kind: KubeKind, namespace: string, name: string, opts?: { foreground?: boolean }): Promise<boolean>;
   /** A JSON merge patch — `null` removes a key. `status` patches the status subresource. Answers
    * the object as it stands after the patch. */
   patch<T extends KubeObject>(
@@ -216,9 +216,12 @@ export function kubeClient(opts: KubeClientOptions = {}): KubeClient {
       });
     },
 
-    delete(kind: KubeKind, ns: string, name: string) {
+    delete(kind: KubeKind, ns: string, name: string, opts: { foreground?: boolean } = {}) {
       return writes(async () => {
-        const res = await send("DELETE", pathOf(kind, ns, name));
+        // Foreground: the object stays until its dependents, a Sandbox's pod, are gone.
+        const res = await send("DELETE", pathOf(kind, ns, name), {
+          ...(opts.foreground ? { query: { propagationPolicy: "Foreground" } } : {}),
+        });
         if (res.status === 404) {
           await res.body?.cancel();
           return false;

package/src/machine-doc.ts

@@ -42,9 +42,9 @@ export type MachineTransitionDoc = {
 };
 
 /** An Effect slot's parts, as the doc carries them (ADR-0067): a command's argv (an argv slot reads
- * `<name>`), its timeout, and the Repo Slot whose Worktree is its cwd, when it names one. */
+ * `<name>`) and its timeout. Its input names its Worktree, so the doc does not (ADR-0075). */
 export type EffectDoc =
-  | { kind: "command"; argv: string[]; timeoutMs: number; slot?: string; secrets?: string[]; pin?: true }
+  | { kind: "command"; argv: string[]; timeoutMs: number; secrets?: string[]; pin?: true }
   /** An http Effect (ADR-0068): its method, its fixed target, the secrets it names — never a value
    * — and `file` when its body is a Worktree file (ADR-0067). */
   | {
@@ -422,12 +422,11 @@ function effectDoc(parts: EffectParts): EffectDoc {
       timeoutMs,
     };
   }
-  const { argv, timeoutMs, slot, secrets, pin } = parts;
+  const { argv, timeoutMs, secrets, pin } = parts;
   return {
     kind: "command",
     argv: argvText(argv),
     timeoutMs,
-    ...(slot ? { slot } : {}),
     ...(secrets?.length ? { secrets: [...secrets] } : {}),
     ...(pin ? { pin } : {}),
   };

package/src/model-keys.ts

@@ -50,3 +50,27 @@ export const SIGNING_CREDENTIALS: readonly string[] = [
   "AWS_PROFILE",
   "GOOGLE_APPLICATION_CREDENTIALS",
 ];
+
+/**
+ * Names whose value is the path of a credential or trust file that the Harness PROCESS reads (the
+ * AWS SDK, Google's library), when `harness.env` or `harness.envFrom` sets one (ADR-0076). The
+ * Harness runs with the control Stand-in in its memory, so such a file must be one that the Agent's
+ * code cannot write: `~/.aws/config` can name a `credential_process`, which the SDK runs. `jr2 up`
+ * refuses a path that the domain writes for certain (`DOMAIN_WRITABLE_ROOTS`), and warns on any
+ * other, because whether the Sandbox's uid can write a path of the image is the image's, which jr2
+ * cannot read. An image's own `ENV` never reaches the Harness process.
+ */
+export const CREDENTIAL_FILES: readonly string[] = [
+  "AWS_CONFIG_FILE",
+  "AWS_SHARED_CREDENTIALS_FILE",
+  "AWS_WEB_IDENTITY_TOKEN_FILE",
+  "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
+  "AWS_CA_BUNDLE",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  "GOOGLE_API_CERTIFICATE_CONFIG",
+  "CLOUDSDK_CONFIG",
+];
+
+/** Folders of a Sandbox's Harness container that the domain writes in every pod: the Worktree root,
+ * the temporary folders, `/dev/shm`, and the HOME that jr2 gives an image with no `USER`. */
+export const DOMAIN_WRITABLE_ROOTS: readonly string[] = ["/work", "/tmp", "/var/tmp", "/dev/shm", "/home/jr2"];

package/src/names.ts

@@ -25,8 +25,10 @@ export const EFFECTOR_PORT = 8082;
 
 /** Where a Harness persists its conversations, and the env var that tells it so (ADR-0031): one
  * fixed path in both placements — the Instance Harness's PersistentVolumeClaim (deploy.ts) and a
- * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. */
-export const CONVERSATIONS_DIR = "/conversations";
+ * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. It is under
+ * `/run/jr2`, as each path that the Harness holds alone is, so no process that the Harness confines
+ * can read an Agent's history or write into it (ADR-0076). */
+export const CONVERSATIONS_DIR = "/run/jr2/conversations";
 export const CONVERSATIONS_DIR_ENV = "JR2_CONVERSATIONS_DIR";
 export const CONVERSATIONS_VOLUME = "conversations";
 
@@ -98,12 +100,23 @@ export const sandboxCustodianConfigMap = (sandbox: string): string => `${sandbox
  * (`workspaceHeldPod`), so the two cannot collide. */
 export const INSTANCE_HARNESS_HELD_POD = "instance";
 
-/** The Custodian's listeners (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
- * HTTPS proxy on loopback, the kubelet's probe, and the control listener the Menu and the ask ride
- * to the Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). */
+/** The Custodian's ports (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
+ * HTTPS proxy on loopback, the kubelet's probe, and the fetch listener that the ask rides to the
+ * Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). The agent routes are not
+ * on a port: they are on the control socket ({@link CUSTODIAN_CONTROL_SOCKET}, ADR-0076). */
 export const CUSTODIAN_PORT = 15001;
 export const CUSTODIAN_HEALTH_PORT = 15021;
-export const CUSTODIAN_CONTROL_PORT = 8081;
+export const CUSTODIAN_FETCH_PORT = 8081;
+
+/** The folder of the Custodian's control socket (ADR-0076): an emptyDir that the Harness container
+ * and the Custodian container alone mount, at this path in both. It is under `/run/jr2`, so no
+ * process that the Harness confines can make a socket here, and none can take the control
+ * listener's place while the Custodian restarts. The Custodian writes it; the Harness mounts it
+ * read-only, which still lets it connect to the socket. */
+export const CUSTODIAN_SOCKET_DIR = "/run/jr2/custodian";
+/** The control socket: the Custodian's listener for the four agent routes, which carry the control
+ * Stand-in (ADR-0059, ADR-0076). */
+export const CUSTODIAN_CONTROL_SOCKET = `${CUSTODIAN_SOCKET_DIR}/control.sock`;
 
 /** The scaffold's default deploy-key Secret name (ADR-0047/0051): what `jr2 init`'s wildcard
  * `git.credentials` entry names as its `sshKey`, and what `jr2 up`'s ssh offer generates into when