@jr2/orchestrator 0.4.1 → 0.6.0

package/src/chart.ts

@@ -19,10 +19,12 @@
 // (open-body.ts), so that `jr2Setup`'s own refusals and load warnings are lines of the same report.
 
 import { createHash } from "node:crypto";
+import { posix } from "node:path";
 import { z } from "zod";
 import { defineEvent, type EventAudience, type EventDef } from "@jr2/agent-protocol";
 import type { AgentDefinition, ThinkingLevel, WorkspaceAccess } from "./agent.ts";
-import { inputKeysOf, isEffect } from "./effect.ts";
+import { inputKeysOf, inputShapeOf, isEffect, type InputShape } from "./effect.ts";
+import { FAILURE_GUARD } from "./fail.ts";
 import { compileChart, durationMs, type LentParts, type OpenBodyDeclaration } from "./open-body.ts";
 import { SENT_BY } from "./party.ts";
 import { loadWarningsOf } from "./vocabulary.ts";
@@ -38,7 +40,8 @@ export type ChartJson = string | number | boolean | null | ChartJson[] | { [key:
  */
 export type ChartValue = ChartJson;
 
-/** A guard: a lent guard by name, with or without params, `jr2.sentBy`, or `not`/`and`/`or`. */
+/** A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or
+ * `not`/`and`/`or`. */
 export type ChartGuard =
   | string
   | { type: string; params?: ChartValue }
@@ -71,7 +74,7 @@ export type ChartTransition =
 /** One transition or a list, in xstate's order. */
 export type ChartTransitions = ChartTransition | ChartTransition[];
 
-/** An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate`. */
+/** An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`. */
 export type ChartInvoke = {
   src: string;
   id?: string;
@@ -138,6 +141,10 @@ const MECHANISM_EVENTS: Record<string, { fields: Record<string, boolean> }> = {
  * placement; see {@link checkAgentInput}). */
 const AGENT_INPUT_KEYS = ["prompt", "cwd", "continue", "model", "thinkingLevel"] as const;
 
+/** The kit's test for a cut that settled `ready`, in every Chart beside `jr2.failure`: a cut's own
+ * outcomes are output, so a Chart routes on them, and a Chart has no other way to read one. */
+export const READY_GUARD = "jr2.ready";
+
 /**
  * The Chart briefing (ADR-0070): jr2's text on how a Chart runs, for whoever writes one. It is the
  * grammar's root description, so it rides `GET /workflows/<wrapper>/chart-schema` and a pick's tool
@@ -158,6 +165,20 @@ export function chartBriefing(narrow?: Narrow): string {
     ? ' `src: "gate"` is the kit\'s Gate: the Chart waits there for an outside answer (a human, a webhook), ' +
       'one of its `events` with `audience: "external"`, not an Agent\'s Turn.'
     : "";
+  const fail = narrow?.fail
+    ? ' `src: "fail"` with `input: { reason }` ends the run as a Failure: work that did not succeed, with ' +
+      `the reason for a person; an \`onError\` with the guard \`${FAILURE_GUARD}\` catches it. A final state means done.`
+    : "";
+  // A declaration is names alone, so this says "a lent Effect that cuts".
+  const cut =
+    narrow === undefined || narrow.lendsEffects
+      ? ' In a Workspace with Repo Slots, work happens in a Worktree. A lent Effect that cuts one takes `input: { path: "/work/<slot>/<name>", ' +
+        'branch: "<branch>" }`: `<name>` is one folder name that you choose, and it is not the branch. The Open body sets the cut\'s `expect`, ' +
+        "so its input has no `expect`. Give its `onDone` two edges: the guard " +
+        `\`${READY_GUARD}\` on the one that goes on, and one with no guard for a refused cut. Then write that same literal path as \`cwd\` in an ` +
+        "Agent's `input` and as `worktree` in an Effect's `input`: each Turn and each Effect there must say where it works. " +
+        "The slot's folder `/work/<slot>` is not a Worktree."
+      : "";
   const agents = mints
     ? `A state runs an Agent with \`invoke: { src, input: { prompt } }\`: \`src\` is a lent Agent's name${lent}. ` +
       "This Chart mints no Agent of its own: there is no `agents`."
@@ -165,7 +186,7 @@ export function chartBriefing(narrow?: Narrow): string {
       "a key of `agents`; a lent Agent needs no entry in `agents`, which mints new ones.";
   return (
     `A Chart is a workflow written as data: states, the events its Agents pick${mints ? "" : ", and the Agents it mints"}. ` +
-    `${agents}${gate} An Agent's Turn ends only when it ` +
+    `${agents}${gate}${fail}${cut} An Agent's Turn ends only when it ` +
     "picks one of the Chart's `events`: declare each pick in `events` with an `input` schema " +
     '(`{ "type": "object", "properties": { "<field>": { "type": "string" } }, "required": ["<field>"] }`; a field not in ' +
     "`required` may be absent), and " +
@@ -232,7 +253,9 @@ export function pathSegments(path: string): Array<string | number> {
 type Narrow = {
   srcs: string[];
   lentAgents: string[];
+  lendsEffects: boolean;
   gate: boolean;
+  fail: boolean;
   guards: string[];
   actions: string[];
   delays: string[];
@@ -353,16 +376,25 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     })
     .describe('A context path without the "context." root, like "round" or "ticket.notes".');
 
-  // `jr2.sentBy` is the kit's routing guard (ADR-0015), and the one guard that is never lent.
+  // `jr2.sentBy` is the kit's routing guard (ADR-0015), and `jr2.failure` its test for a Failure on
+  // an `onError` (ADR-0073): every Chart has both, and neither is lent.
   const sentByArm = z.strictObject({ type: z.literal(SENT_BY), params: z.strictObject({ id: z.string() }) });
+  const failureArm = z.strictObject({ type: z.union([z.literal(FAILURE_GUARD), z.literal(READY_GUARD)]) });
   const lentGuardName = narrow
-    ? enumOf(narrow.guards)
+    ? enumOf([...narrow.guards, FAILURE_GUARD, READY_GUARD])
     : z.string().refine((t) => t !== SENT_BY, { message: `"${SENT_BY}" takes params { id }` });
+  const paramGuardName = narrow
+    ? enumOf(narrow.guards)
+    : z
+        .string()
+        .refine((t) => t !== SENT_BY, { message: `"${SENT_BY}" takes params { id }` })
+        .refine((t) => t !== FAILURE_GUARD && t !== READY_GUARD, { message: "that guard takes no params" });
   const guard: z.ZodType<ChartGuard> = z
     .union([
       lentGuardName,
       sentByArm,
-      z.strictObject({ type: lentGuardName, params: template.optional() }),
+      failureArm,
+      z.strictObject({ type: paramGuardName, params: template.optional() }),
       z.strictObject({
         get not() {
           return guard;
@@ -381,7 +413,7 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     ])
     .meta({
       id: `${ID_PREFIX}ChartGuard`,
-      description: "A lent guard by name, `jr2.sentBy`, or not/and/or of guards.",
+      description: `A lent guard by name, \`jr2.sentBy\`, \`${FAILURE_GUARD}\`, \`${READY_GUARD}\`, or not/and/or of guards.`,
     }) as never;
 
   const lentActionName = narrow
@@ -425,9 +457,14 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     : z.string();
   const invoke = z
     .strictObject({
+      // A narrowed grammar names `fail` only where the body lends it: a model reads only what it can use.
       src: src.describe(
-        "A lent Agent, Effect or Machine by its name; the kit's `gate` (waits for an outside answer: a human, a " +
-          "webhook) where the body lends it; or a key of this Chart's `agents`.",
+        narrow && !narrow.fail
+          ? "A lent Agent, Effect or Machine by its name; the kit's `gate` (waits for an outside answer: a human, a " +
+              "webhook) where the body lends it; or a key of this Chart's `agents`."
+          : "A lent Agent, Effect or Machine by its name; the kit's `gate` (waits for an outside answer: a human, a " +
+              "webhook) or `fail` (ends the run as a Failure, with `input: { reason }`) where the body lends it; or a " +
+              "key of this Chart's `agents`.",
       ),
       id: name("invoke id").optional(),
       input: template.optional().describe("An Agent takes `{ prompt }`; an Effect or a Machine takes its own input."),
@@ -526,9 +563,17 @@ function grammar(narrow?: Narrow): z.ZodType<ChartText> {
     .describe(chartBriefing(narrow)) as unknown as z.ZodType<ChartText>;
 }
 
+// A door field or a pick param that IS this schema is a Chart field: `isChartSchema` tells, and
+// jr2 reads a Chart wrapper's one-shot door off it (ADR-0070).
 /**
- * The Chart grammar (ADR-0070), as zod. A door field or a pick param that IS this schema is a
- * Chart field: `isChartSchema` tells, and jr2 reads a Chart wrapper's one-shot door off it.
+ * The Chart grammar, as a zod schema. Make a field of the run input of a Chart wrapper this schema,
+ * as in `z.object({ topic: z.string(), chart: chartSchema })`. Then a run input can carry a Chart,
+ * and the wrapper can keep Charts under names: Chart files in `workflows/<wrapper>/`, and runtime
+ * Charts. For the pick of a planner, use `chartSchemaFor`, which knows the names that the Open body
+ * lends.
+ *
+ * @see docs/guides/run-a-chart-by-name.md
+ * @see docs/concepts/charts.md
  */
 export const chartSchema: z.ZodType<ChartText> = guarded(grammar());
 
@@ -578,13 +623,38 @@ export function chartBriefingOf(schema: unknown): string | undefined {
 
 const narrowedSchemas = new WeakMap<OpenBodyDeclaration, z.ZodType<ChartText>>();
 
+// Either way it is a Chart field (`isChartSchema`), and the door still admits the Chart against
+// the lent set the body has at its start. One schema per declaration (ADR-0070).
 /**
- * The Chart grammar as zod, narrowed to one Open body (ADR-0070): the lent `src` names, guard,
- * action and delay names, and the allowed models and Workspace accesses are enums. A planner's
- * pick whose field is this schema gets the narrowed grammar as its tool parameters, so the model
- * is constrained when it writes the Chart; a Chart wrapper's door may take it too. Either way it
- * is a Chart field (`isChartSchema`), and the door still admits the Chart against the lent set the
- * body has at its start. One schema per declaration.
+ * The Chart grammar for one Open body, as a zod schema. The names that the Open body lends, and the
+ * models and the Workspace accesses that it allows, are the only values that the schema takes.
+ * Make it the parameter of the pick of a planner. The model then gets the grammar as the
+ * parameters of its tool, and the Briefing tells it how a Chart runs. The door still checks each
+ * Chart before it runs.
+ *
+ * @param decl - The declaration of the Open body that the Chart binds.
+ * @returns The schema of a Chart for that Open body.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { chartSchemaFor, defineEvent, type OpenBodyDeclaration } from "@jr2/orchestrator";
+ *
+ * const declaration: OpenBodyDeclaration = {
+ *   lends: { agents: ["writer"], gate: true },
+ *   allows: { models: ["anthropic/claude-haiku-5-5"], workspace: ["none"] },
+ *   ceilings: { turns: 12, wallClock: "30m", transitions: 500, fanOut: 2, size: 65536 },
+ * };
+ *
+ * export const runChart = defineEvent({
+ *   name: "run_chart",
+ *   description: "Run this Chart. Its outcome is the answer to this call.",
+ *   input: z.object({ chart: chartSchemaFor(declaration) }),
+ * });
+ * ```
+ *
+ * @see docs/guides/let-an-agent-write-a-chart.md
+ * @see docs/concepts/charts.md
  */
 export function chartSchemaFor(decl: OpenBodyDeclaration): z.ZodType<ChartText> {
   const hit = narrowedSchemas.get(decl);
@@ -607,6 +677,7 @@ function lendsOf(decl: OpenBodyDeclaration) {
     actions: decl.lends.actions ?? [],
     delays: decl.lends.delays ?? [],
     gate: decl.lends.gate === true,
+    fail: decl.lends.fail === true,
   };
 }
 
@@ -624,9 +695,11 @@ export function narrowedChartSchema(decl: OpenBodyDeclaration): Record<string, u
 function narrowOf(decl: OpenBodyDeclaration): Narrow {
   const l = lendsOf(decl);
   return {
-    srcs: [...l.agents, ...l.effects, ...l.machines, ...(l.gate ? ["gate"] : [])],
+    srcs: [...l.agents, ...l.effects, ...l.machines, ...(l.gate ? ["gate"] : []), ...(l.fail ? ["fail"] : [])],
     lentAgents: l.agents,
+    lendsEffects: l.effects.length > 0,
     gate: l.gate,
+    fail: l.fail,
     guards: l.guards,
     actions: l.actions,
     delays: l.delays,
@@ -782,6 +855,17 @@ export type AdmittedChart = {
   size: number;
 };
 
+/**
+ * Why a Chart's `cwd` is not a place to work, or undefined when it can be: a Repo Slot's folder is no
+ * Worktree. There, an Agent's search hits `default/`, and a relative write lands outside each
+ * Worktree (ADR-0057, ADR-0075).
+ */
+export function slotFolderFault(cwd: string, slots: readonly string[]): string | undefined {
+  const slot = posix.normalize(cwd).match(/^\/work\/([^/]+)\/?$/)?.[1];
+  if (slot === undefined || !slots.includes(slot)) return undefined;
+  return `"${cwd}" is a Repo Slot's folder, not a Worktree; \`cwd\` is a Worktree that a cut made, "/work/${slot}/<name>", or "/work/${slot}/default" to read, or "/work"`;
+}
+
 /** What the door knows beyond the declaration and the lent set. */
 export type AdmitOptions = {
   /**
@@ -790,6 +874,11 @@ export type AdmitOptions = {
    * `input.<key>` reference is checked against it; absent, `input` references are not checked.
    */
   inputKeys?: readonly string[];
+  /** The Repo Slots of the Workspace around the Open body, where the door can read them. Given and
+   * not empty, a Turn's `cwd` and an Effect's `worktree` are required, a literal path's slot is
+   * checked, and a literal `cwd` cannot be a slot's folder. Absent: the start of a Turn or an Effect
+   * says the same of a missing `cwd`, of a Worktree path, and of a `cwd` that is a slot's folder. */
+  repoSlots?: readonly string[];
 };
 
 const MAX_STATES = 200;
@@ -867,6 +956,9 @@ function issueLines(
 
 const pathText = (path: readonly PropertyKey[]): string => (path.length ? path.map(String).join(".") : "(chart)");
 
+/** What an invoke's `src` names (rule 3). */
+type InvokeKind = "agent" | "minted" | "effect" | "machine" | "gate" | "fail";
+
 /** One state of the Chart, indexed for the checks. */
 type Node = {
   key: string;
@@ -932,6 +1024,13 @@ export function admitChart(
   return new Door(chart, decl, lent, options).admit(size);
 }
 
+/** What an Effect's input takes, for a line of the door. */
+function shapeText(shape: InputShape): string {
+  const need = [...shape.required, ...(shape.oneOf ? [`exactly one of ${shape.oneOf.join(", ")}`] : [])].join(", ");
+  const may = shape.optional.length ? `${need ? ", and " : ""}optionally ${shape.optional.join(", ")}` : "";
+  return need || may ? `${need}${may}` : "nothing";
+}
+
 /** The checks from rule 3 on, over a Chart the grammar admitted. */
 class Door {
   private readonly lines: Line[] = [];
@@ -1064,11 +1163,12 @@ class Door {
   private lentText(): string {
     const actors = this.lentActors().map((a) => `${a.name} (${a.kind})`);
     const minted = Object.keys(this.chart.agents ?? {});
-    return `lent: ${names(actors)}; kit: ${this.lends.gate ? "gate" : "none"}; minted: ${names(minted)}`;
+    const kit = [...(this.lends.gate ? ["gate"] : []), ...(this.lends.fail ? ["fail"] : [])];
+    return `lent: ${names(actors)}; kit: ${kit.length ? kit.join(", ") : "none"}; minted: ${names(minted)}`;
   }
 
   /** What an invoke's `src` names, or undefined after a refusal line. */
-  private srcKind(src: string, path: string): "agent" | "minted" | "effect" | "machine" | "gate" | undefined {
+  private srcKind(src: string, path: string): InvokeKind | undefined {
     const lentNow = (name: string) => name in this.lent.actors;
     const declared = [...this.lends.agents, ...this.lends.effects, ...this.lends.machines];
     if (declared.includes(src) && !lentNow(src)) {
@@ -1089,6 +1189,14 @@ class Door {
       );
       return undefined;
     }
+    if (src === "fail") {
+      if (this.lends.fail) return "fail";
+      this.fail(
+        3,
+        `${path}: "fail" is the kit's Part that ends the run as a Failure, and this Open body does not lend it (\`lends.fail: true\` would); ${this.lentText()}`,
+      );
+      return undefined;
+    }
     if (Object.hasOwn(this.chart.agents ?? {}, src)) return "minted";
     this.fail(3, `${path}: "${src}" is not a lent actor or an Agent of this Chart; ${this.lentText()}`);
     return undefined;
@@ -1103,11 +1211,16 @@ class Door {
       this.sentBys.push({ id: (guard.params as { id: string }).id, path: `${path}.params.id` });
       return;
     }
+    if (guard.type === FAILURE_GUARD || guard.type === READY_GUARD) {
+      if (guard.params !== undefined) this.fail(3, `${path}.params: "${guard.type}" takes no params`);
+      return;
+    }
     this.checkGuardName(guard.type, `${path}.type`);
     if (guard.params !== undefined) this.checkRefs(guard.params, `${path}.params`, scope);
   }
 
   private checkGuardName(name: string, path: string): void {
+    if (name === FAILURE_GUARD || name === READY_GUARD) return;
     const lent = this.lends.guards.filter((g) => g in this.lent.guards);
     if (this.lends.guards.includes(name) && !(name in this.lent.guards)) {
       this.fail(
@@ -1117,7 +1230,7 @@ class Door {
     } else if (!this.lends.guards.includes(name)) {
       this.fail(
         3,
-        `${path}: "${name}" is not a lent guard; lent guards: ${names(lent)} (and ${SENT_BY} with params { id })`,
+        `${path}: "${name}" is not a lent guard; lent guards: ${names(lent)} (and ${SENT_BY} with params { id }, ${FAILURE_GUARD} and ${READY_GUARD})`,
       );
     }
   }
@@ -1262,7 +1375,7 @@ class Door {
   // --- rule 5: minted Agents ------------------------------------------------------------------------
 
   private checkAgents(): void {
-    const lentNames = new Set([...this.lends.agents, ...this.lends.effects, ...this.lends.machines, "gate"]);
+    const lentNames = new Set([...this.lends.agents, ...this.lends.effects, ...this.lends.machines, "gate", "fail"]);
     for (const [slot, a] of Object.entries(this.chart.agents ?? {})) {
       const path = `agents.${slot}`;
       if (lentNames.has(slot)) {
@@ -1607,6 +1720,7 @@ class Door {
   private checkParties(): void {
     const agents = new Set<string>();
     const gates = new Set<string>();
+    const slotStates = new Map<string, Node[]>();
     for (const node of this.nodes) {
       const invokes = listAt(node.state.invoke, `${node.doc}.invoke`);
       // A Gate's invoke id, as jr2Setup names an unnamed one: the state's key path.
@@ -1621,6 +1735,7 @@ class Door {
         if (kind === "gate") gates.add(inv.id ?? (unnamed > 1 ? `${key}.${ordinal++}` : key));
         if (kind !== "agent" && kind !== "minted") continue;
         agents.add(inv.src);
+        slotStates.set(inv.src, [...(slotStates.get(inv.src) ?? []), node]);
         if (inv.onDone !== undefined) {
           this.fail(
             6,
@@ -1642,6 +1757,25 @@ class Door {
         }
       }
     }
+    // One Agent, two Turns at once: one sender and one conversation cannot hold both.
+    // One line for each Agent: every state of it that can be active with another of them.
+    for (const [slot, states] of slotStates) {
+      const clash = new Set<Node>();
+      for (let i = 0; i < states.length; i++) {
+        for (let j = i + 1; j < states.length; j++) {
+          const [a, b] = [states[i]!, states[j]!];
+          const together =
+            a === b || isAncestorOrSelf(a, b) || isAncestorOrSelf(b, a) || nearestCommon(a, b)?.kind === "parallel";
+          if (together) clash.add(a).add(b);
+        }
+      }
+      if (clash.size === 0) continue;
+      const docs = [...clash].map((n) => n.doc).join(", ");
+      this.fail(
+        6,
+        `${docs}: Agent "${slot}" would run two Turns at once: these states invoke it and can be active together (in parallel regions, one inside the other, or one state twice); an Agent runs one Turn at a time: invoke another Agent in one of them`,
+      );
+    }
     for (const { id, path } of this.sentBys) {
       if (id.includes("{{")) {
         this.fail(3, `${path}: a sentBy id is a literal party name, never a reference`);
@@ -1835,15 +1969,12 @@ class Door {
 
   // --- rule 8: lent input shapes --------------------------------------------------------------------
 
-  private checkInvokeInput(
-    inv: ChartInvoke,
-    kind: "agent" | "minted" | "effect" | "machine" | "gate",
-    path: string,
-  ): void {
+  private checkInvokeInput(inv: ChartInvoke, kind: InvokeKind, path: string): void {
     const ipath = `${path}.input`;
     const input = inv.input;
     const isObject = typeof input === "object" && input !== null && !Array.isArray(input) && !("$ref" in input);
     if (kind === "machine") return;
+    if (kind === "fail") return this.checkFailInput(input, isObject, ipath);
     if (kind === "gate") {
       if (input === undefined) return;
       if (!isObject) return this.fail(8, `${ipath}: a Gate's input is an object of gate (a name) and meta`);
@@ -1863,38 +1994,166 @@ class Door {
     }
     if (kind === "effect") {
       const logic = this.lent.actors[inv.src];
-      const keys = isEffect(logic) ? inputKeysOf(logic.effect) : undefined;
+      const parts = isEffect(logic) ? logic.effect : undefined;
+      const keys = parts ? inputKeysOf(parts) : undefined;
+      if (keys === undefined && parts?.kind === "dispatch") {
+        // A dispatch with no input schema has no keys to hold the Chart to: its input is the run's
+        // body, and the callee's door is the check (ADR-0071). Its values are what any Effect's
+        // input slot takes.
+        if (input === undefined) return;
+        if (!isObject) {
+          return this.fail(
+            8,
+            `${ipath}: the lent dispatch "${inv.src}" takes an object, the run's body — the callee's door checks it`,
+          );
+        }
+        for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+          if (typeof v !== "string" && !isRef(v))
+            this.fail(8, `${ipath}.${k}: an Effect's input slot takes a string or a reference`);
+        }
+        return;
+      }
       if (keys === undefined) {
         return this.fail(
           8,
           `${ipath}: the lent Effect "${inv.src}" has no input keys the door can read (an Open argv nobody bound)`,
         );
       }
-      if (input === undefined && keys.length === 0) return;
-      if (!isObject) {
-        return this.fail(8, `${ipath}: the lent Effect "${inv.src}" takes an object of exactly ${names(keys)}`);
+      const shape = this.shapeHere(parts!);
+      // A cut's `expect` is static, and a Chart cannot state it: an unstated one would let a planner's
+      // name land on someone else's branch.
+      if (parts?.kind === "command" && parts.cut && parts.cut.expect === undefined) {
+        const fresh = this.lentNewCuts();
+        this.fail(
+          8,
+          `${ipath}: the lent cut "${inv.src}" does not state \`expect\`, so a Chart cannot use it; ` +
+            (fresh.length
+              ? `use a lent cut with \`expect: "new"\`: ${names(fresh)}`
+              : `the Open body must state it (\`worktree({ expect: "new" })\` would); ${this.lentText()}`),
+        );
+      }
+      // A push publishes the branch of a cut's row, which stays in the run's ledger, so a Chart that
+      // cuts and a later Chart that pushes are the same pair: the test is what is lent, not what this
+      // Chart invokes.
+      const force = this.lentForcePush();
+      if (parts?.kind === "command" && parts.cut?.expect === "existing" && force !== undefined) {
+        const fresh = this.lentNewCuts();
+        this.fail(
+          8,
+          `${ipath}: the lent cut "${inv.src}" states \`expect: "existing"\` beside the lent force push "${force}", and together they can force-push any existing branch; ` +
+            (fresh.length
+              ? `use a lent cut with \`expect: "new"\`: ${names(fresh)}`
+              : `this Open body lends no cut with \`expect: "new"\`, so a Chart cannot cut here (\`worktree({ expect: "new" })\` would); ${this.lentText()}`),
+        );
       }
+      if (input === undefined && shape.required.length === 0 && !shape.oneOf) return;
+      const takes = shapeText(shape);
+      if (!isObject) return this.fail(8, `${ipath}: the lent Effect "${inv.src}" takes an object: ${takes}`);
       const given = Object.keys(input);
-      const missing = keys.filter((k) => !given.includes(k));
+      const missing = shape.required.filter((k) => !given.includes(k));
       const extra = given.filter((k) => !keys.includes(k));
-      if (missing.length || extra.length) {
+      const ofOne = shape.oneOf?.filter((k) => given.includes(k)).length ?? 1;
+      if (missing.length || extra.length || ofOne !== 1) {
         this.fail(
           8,
-          `${ipath}: the lent Effect "${inv.src}" takes exactly ${names(keys)}` +
+          `${ipath}: the lent Effect "${inv.src}" takes ${takes}` +
             (missing.length ? `; missing: ${missing.join(", ")}` : "") +
-            (extra.length ? `; not its input: ${extra.join(", ")}` : ""),
+            (extra.length ? `; not its input: ${extra.join(", ")}` : "") +
+            (ofOne !== 1 ? `; give one of ${shape.oneOf!.join(", ")}` : ""),
         );
       }
+      if (parts?.kind === "command" && parts.cut && given.includes("detach") && given.includes("from")) {
+        this.fail(8, `${ipath}: a detached cut takes no \`from\``);
+      }
       for (const k of given.filter((g) => keys.includes(g))) {
         const v = (input as Record<string, unknown>)[k];
         if (typeof v !== "string" && !isRef(v))
           this.fail(8, `${ipath}.${k}: an Effect's input slot takes a string or a reference`);
+        else if ((k === "worktree" || k === "path") && typeof v === "string") this.checkLiteralPath(v, `${ipath}.${k}`);
       }
       return;
     }
     this.checkAgentInput(inv.src, kind, input, isObject, ipath);
   }
 
+  /** An Effect's shape here: where the door knows the Workspace has Repo Slots, `worktree` is
+   * required on what can name one. Elsewhere the start says so (`drive`). */
+  private shapeHere(parts: Parameters<typeof inputShapeOf>[0]): InputShape {
+    const shape = inputShapeOf(parts)!;
+    if (!this.options.repoSlots?.length || !shape.optional.includes("worktree")) return shape;
+    return {
+      ...shape,
+      required: [...shape.required, "worktree"],
+      optional: shape.optional.filter((k) => k !== "worktree"),
+    };
+  }
+
+  /** The lent Effects, each with its parts. */
+  private lentEffects(): Array<{ name: string; parts: Parameters<typeof inputShapeOf>[0] }> {
+    return this.lends.effects.flatMap((name) => {
+      const logic = this.lent.actors[name];
+      return isEffect(logic) ? [{ name, parts: logic.effect }] : [];
+    });
+  }
+
+  /** The name of a lent push that forces, if one is lent. */
+  private lentForcePush(): string | undefined {
+    return this.lentEffects().find(({ parts }) => parts.kind === "push" && parts.force)?.name;
+  }
+
+  /** The names of the lent cuts that make only a new branch. */
+  private lentNewCuts(): string[] {
+    return this.lentEffects()
+      .filter(({ parts }) => parts.kind === "command" && parts.cut?.expect === "new")
+      .map(({ name }) => name);
+  }
+
+  /** A literal Worktree path: a wrong slot costs no pod. A path with a reference waits for its start. */
+  private checkLiteralPath(value: string, path: string): void {
+    if (referencesOf(value).length) return;
+    const match = value.match(/^\/work\/([^/]+)\/([^/.-][^/]*)$/);
+    const slots = this.options.repoSlots;
+    if (match === null) this.fail(8, `${path}: "${value}" is not a Worktree path: /work/<slot>/<name>`);
+    else if (slots !== undefined && !slots.includes(match[1]!)) {
+      this.fail(8, `${path}: "${value}" names no Repo Slot of this Workspace; its Repo Slots: ${names([...slots])}`);
+    }
+  }
+
+  /** A literal `cwd`, see {@link slotFolderFault}. A `cwd` with a reference waits for its value: the
+   * Open body asks the same question when the Turn starts. */
+  private checkCwd(value: string, path: string): void {
+    if (referencesOf(value).length) return;
+    const fault = slotFolderFault(value, this.options.repoSlots ?? []);
+    if (fault !== undefined) this.fail(8, `${path}: ${fault}`);
+  }
+
+  /** The input of `fail` (ADR-0073): `{ reason, detail? }`, `reason` a text for a person (a string
+   * or a reference), `detail` any value. */
+  private checkFailInput(input: unknown, isObject: boolean, ipath: string): void {
+    if (!isObject) {
+      return this.fail(8, `${ipath}: \`fail\` takes { reason, detail? }: reason is a text for a person`);
+    }
+    for (const key of Object.keys(input as Record<string, unknown>)) {
+      if (key !== "reason" && key !== "detail") {
+        this.fail(8, `${ipath}.${key}: \`fail\` takes reason and detail only`);
+      }
+    }
+    const reason = (input as Record<string, unknown>).reason;
+    if (reason === undefined) this.fail(8, `${ipath}.reason: \`fail\` needs a reason, a text for a person`);
+    else if ((typeof reason !== "string" || reason === "") && !isRef(reason)) {
+      this.fail(8, `${ipath}.reason: a reason is a string that is not empty, or a reference`);
+    }
+  }
+
+  /** Does this Agent read `/work`? A `workspace: "none"` one frames nothing. */
+  private worksInWorkspace(src: string, kind: "agent" | "minted"): boolean {
+    if (kind === "agent") {
+      const logic = this.lent.actors[src] as { definition?: { workspace?: unknown } } | undefined;
+      return logic?.definition?.workspace !== "none";
+    }
+    return (this.chart.agents?.[src] as { workspace?: unknown } | undefined)?.workspace !== "none";
+  }
+
   /**
    * An Agent invoke's input is a Turn's Frame and Dials (ADR-0057): `prompt` (a string), and
    * optionally `cwd`, `continue: true`, a `model` the Open body allows, and a `thinkingLevel`.
@@ -1928,6 +2187,13 @@ class Door {
     else if (typeof obj.prompt !== "string")
       this.fail(8, `${ipath}.prompt: a prompt is a string (placeholders inside it are fine)`);
     if (obj.cwd !== undefined && typeof obj.cwd !== "string") this.fail(8, `${ipath}.cwd: a cwd is a string`);
+    if (obj.cwd === undefined && this.options.repoSlots?.length && this.worksInWorkspace(src, kind)) {
+      this.fail(
+        8,
+        `${ipath}: ${who} works under a Workspace with Repo Slots, and a Turn there says where: \`cwd\` is a Worktree, or "/work"`,
+      );
+    }
+    if (typeof obj.cwd === "string" && this.worksInWorkspace(src, kind)) this.checkCwd(obj.cwd, `${ipath}.cwd`);
     if (obj.continue !== undefined && obj.continue !== true)
       this.fail(8, `${ipath}.continue: \`continue\` is true or absent`);
     if (obj.model !== undefined) {
@@ -1953,9 +2219,10 @@ class Door {
  * The JSON Schema keywords a Chart event's payload may use (ADR-0070, rule 4). The Orchestrator
  * checks every pick against this schema in its own process, before the Allowed check, so a keyword
  * whose cost the door cannot bound is refused by name: `pattern` (a backtracking regex),
- * `patternProperties`, `$ref`, the combinators and the conditionals.
+ * `patternProperties`, `$ref`, the combinators and the conditionals. It is also the subset a
+ * dispatch's slot schema and its callee's door are compared within (ADR-0071, door-compat.ts).
  */
-const PAYLOAD_KEYWORDS = new Set([
+export const PAYLOAD_KEYWORDS: ReadonlySet<string> = new Set([
   "type",
   "properties",
   "required",
@@ -1981,6 +2248,39 @@ const PAYLOAD_KEYWORDS = new Set([
  * the payload name the event a Chart receives (registration.ts builds `{ type, ...payload }`).
  */
 function payloadSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; message: string }> {
+  const out = subsetFaults(
+    schema,
+    (key) =>
+      `"${key}" is not a keyword a Chart event's payload may use; it may use ${[...PAYLOAD_KEYWORDS].join(", ")}`,
+  );
+  const props = (schema as { properties?: unknown } | null)?.properties;
+  if (typeof props === "object" && props !== null && Object.hasOwn(props, "type")) {
+    out.push({
+      path: ["properties", "type"],
+      message: "a payload field named `type` is refused: jr2 writes the event's type, and the payload never names it",
+    });
+  }
+  return out;
+}
+
+/**
+ * The faults of a door's JSON Schema, or of a dispatch slot's (ADR-0071): every keyword not in
+ * {@link PAYLOAD_KEYWORDS} and a list-form `items` — the payload rules without the Chart's own one
+ * (a field named `type` is a door's to have). A schema with a fault is reported "not compared":
+ * outside the subset, a comparison would be a guess.
+ */
+export function doorSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; message: string }> {
+  return subsetFaults(
+    schema,
+    (key) => `"${key}" is outside the JSON Schema subset jr2 compares (${[...PAYLOAD_KEYWORDS].join(", ")})`,
+  );
+}
+
+/** The subset's faults: `outside` words the fault of a keyword not in it, for whose rule it is. */
+function subsetFaults(
+  schema: unknown,
+  outside: (key: string) => string,
+): Array<{ path: PropertyKey[]; message: string }> {
   const out: Array<{ path: PropertyKey[]; message: string }> = [];
   const walk = (node: unknown, path: PropertyKey[]): void => {
     if (typeof node === "boolean" && path.length && path[path.length - 1] === "additionalProperties") return;
@@ -1993,7 +2293,7 @@ function payloadSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; mess
       if (!PAYLOAD_KEYWORDS.has(key)) {
         out.push({
           path: [...path, key],
-          message: `"${key}" is not a keyword a Chart event's payload may use; it may use ${[...PAYLOAD_KEYWORDS].join(", ")}`,
+          message: outside(key),
         });
         continue;
       }
@@ -2012,13 +2312,6 @@ function payloadSchemaFaults(schema: unknown): Array<{ path: PropertyKey[]; mess
     }
   };
   walk(schema, []);
-  const props = (schema as { properties?: unknown } | null)?.properties;
-  if (typeof props === "object" && props !== null && Object.hasOwn(props, "type")) {
-    out.push({
-      path: ["properties", "type"],
-      message: "a payload field named `type` is refused: jr2 writes the event's type, and the payload never names it",
-    });
-  }
   return out;
 }
 
@@ -2032,6 +2325,12 @@ function wholeRefOf(v: unknown): string | undefined {
   return isRef(v) ? (v as { $ref: string }).$ref : undefined;
 }
 
+/** The nearest state at or above both `a` and `b`. */
+function nearestCommon(a: Node, b: Node): Node | undefined {
+  for (let n: Node | undefined = a; n; n = n.parent) if (isAncestorOrSelf(n, b)) return n;
+  return undefined;
+}
+
 /** Is `a` the state `b` or a state above it? */
 function isAncestorOrSelf(a: Node, b: Node): boolean {
   for (let n: Node | undefined = b; n; n = n.parent) if (n === a) return true;