delegation-layer 0.1.28 → 0.1.29

package/scripts/installer/filesystem.mjs

@@ -0,0 +1,97 @@
+import { lstat, mkdir, readdir, readFile, copyFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+export async function existingPath(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function assertNoSymlinkComponents(path) {
+  let current = resolve(path);
+  while (true) {
+    const stat = await existingPath(current);
+    if (stat?.isSymbolicLink()) {
+      throw new Error(`skill destination must not contain symlink components: ${current}`);
+    }
+    const parent = dirname(current);
+    if (parent === current) return;
+    current = parent;
+  }
+}
+
+export async function skillFiles(directory, relative = "") {
+  const entries = await readdir(join(directory, relative), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const child = join(relative, entry.name);
+    const path = join(directory, child);
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`skill source or destination must not contain symlinks: ${path}`);
+    }
+    if (stat.isDirectory()) {
+      files.push(...(await skillFiles(directory, child)));
+      continue;
+    }
+    if (!stat.isFile()) throw new Error(`skill entry must be a regular file: ${path}`);
+    files.push(child);
+  }
+  return files.sort();
+}
+
+export async function validateSkillSource(sourceDirectory) {
+  const files = await skillFiles(sourceDirectory);
+  if (!files.includes("SKILL.md")) {
+    throw new Error(`skill package is missing SKILL.md: ${sourceDirectory}`);
+  }
+  return files;
+}
+
+export async function skillTreeMatches(sourceDirectory, target, files) {
+  for (const relative of files) {
+    const destination = join(target, relative);
+    await assertNoSymlinkComponents(destination);
+    const stat = await existingPath(destination);
+    if (!stat?.isFile() || stat.isSymbolicLink()) return false;
+    const [source, existing] = await Promise.all([
+      readFile(join(sourceDirectory, relative)),
+      readFile(destination),
+    ]);
+    if (!source.equals(existing)) return false;
+  }
+  return true;
+}
+
+export async function skillTreeHasExistingFiles(target, files) {
+  for (const relative of files) {
+    const destination = join(target, relative);
+    await assertNoSymlinkComponents(destination);
+    if (await existingPath(destination)) return true;
+  }
+  return false;
+}
+
+export async function copySkillTree(sourceDirectory, target, files, force) {
+  for (const relative of files) {
+    const destination = join(target, relative);
+    await assertNoSymlinkComponents(destination);
+    await mkdir(dirname(destination), { recursive: true });
+    const stat = await existingPath(destination);
+    if (stat?.isSymbolicLink()) {
+      throw new Error(`existing skill file must not be a symlink: ${destination}`);
+    }
+    if (stat && !stat.isFile()) {
+      throw new Error(`existing skill entry is not a regular file: ${destination}`);
+    }
+    if (stat && !force) {
+      throw new Error(`skill files already exist; use --force to replace them: ${target}`);
+    }
+    await copyFile(join(sourceDirectory, relative), destination);
+  }
+}

package/scripts/installer/paths.mjs

@@ -0,0 +1,14 @@
+import { isAbsolute, join } from "node:path";
+
+export function normalizeAbsolute(value) {
+  if (!isAbsolute(value)) throw new Error("Expected an absolute path");
+  return join(value, ".");
+}
+
+export function resolveFrom(base, value) {
+  if (isAbsolute(value)) return normalizeAbsolute(value);
+  if (typeof base !== "string" || !isAbsolute(base)) {
+    throw new Error("A relative configuration path requires an absolute working directory");
+  }
+  return join(base, value, ".");
+}

package/scripts/installer/picker-state.mjs

@@ -0,0 +1,46 @@
+export function createPickerState({ initialValues = [], multiple = false }) {
+  return {
+    index: 0,
+    multiple,
+    selectedValues: [...new Set(initialValues)],
+    error: undefined,
+  };
+}
+
+export function transitionPicker(state, action, optionValues) {
+  if (action === "cancel") {
+    return { state: { ...state, error: undefined }, done: true, value: null };
+  }
+  if (action === "up" || action === "down") {
+    if (optionValues.length === 0) return { state, done: false };
+    const offset = action === "up" ? -1 : 1;
+    const index = (state.index + optionValues.length + offset) % optionValues.length;
+    return { state: { ...state, index, error: undefined }, done: false };
+  }
+  if (action === "toggle" && state.multiple && optionValues[state.index] !== undefined) {
+    const value = optionValues[state.index];
+    const selectedValues = state.selectedValues.includes(value)
+      ? state.selectedValues.filter((selected) => selected !== value)
+      : [...state.selectedValues, value];
+    return { state: { ...state, selectedValues, error: undefined }, done: false };
+  }
+  if (action === "all" && state.multiple) {
+    return { state: { ...state, selectedValues: [...new Set(optionValues)], error: undefined }, done: false };
+  }
+  if (action === "none" && state.multiple) {
+    return { state: { ...state, selectedValues: [], error: undefined }, done: false };
+  }
+  if (action === "enter") {
+    if (state.multiple && state.selectedValues.length === 0) {
+      return {
+        state: { ...state, error: "Select at least one harness, or press q to cancel." },
+        done: false,
+      };
+    }
+    const value = state.multiple
+      ? optionValues.filter((option) => state.selectedValues.includes(option))
+      : optionValues[state.index];
+    return { state: { ...state, error: undefined }, done: true, value };
+  }
+  return { state, done: false };
+}

package/scripts/installer/routing-rules.mjs

@@ -0,0 +1,99 @@
+import { join } from "node:path";
+import { resolveFrom } from "./paths.mjs";
+
+const ROUTING_EVENTS = ["SessionStart", "SubagentStart"];
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function shellQuote(value) {
+  return "'" + value.replaceAll("'", "'\\''") + "'";
+}
+
+function hookCommand(target, event) {
+  return `/bin/sh ${shellQuote(join(target, "scripts", "delegate-routing-context.sh"))} ${event}`;
+}
+
+export function routingPath(name, { scope, cwd, home, claudeConfigDir, codexHome }) {
+  if (name === "claude") {
+    return scope === "global"
+      ? join(resolveFrom(cwd, claudeConfigDir || join(home, ".claude")), "settings.json")
+      : join(cwd, ".claude", "settings.local.json");
+  }
+  if (name === "codex") {
+    return join(scope === "global" ? resolveFrom(cwd, codexHome || join(home, ".codex")) : join(cwd, ".codex"), "hooks.json");
+  }
+  return null;
+}
+
+export function validateHookConfig(config, path) {
+  if (!isObject(config) || (config.hooks !== undefined && !isObject(config.hooks))) {
+    throw new Error(`expected a JSON object with an optional hooks object: ${path}`);
+  }
+  for (const groups of Object.values(config.hooks ?? {})) {
+    if (!Array.isArray(groups) || groups.some((group) => !isObject(group)
+      || !Array.isArray(group.hooks) || group.hooks.some((hook) => !isObject(hook) || typeof hook.type !== "string"))) {
+      throw new Error(`invalid hook configuration; no routing changes written: ${path}`);
+    }
+  }
+}
+
+export function countRoutingEvents(config, target) {
+  const hooks = config.hooks ?? {};
+  return ROUTING_EVENTS.filter((event) => {
+    const expected = hookCommand(target, event);
+    return (hooks[event] ?? []).some((group) => group.hooks.some(
+      (hook) => hook.type === "command" && hook.command === expected,
+    ));
+  }).length;
+}
+
+export function createRoutingPlan({ name, path, target, before, config, mode, action, assetsPresent = true }) {
+  validateHookConfig(config, path);
+  const nextConfig = { ...config };
+  const hooks = { ...(config.hooks ?? {}) };
+  let changed = false;
+  let present = 0;
+
+  for (const event of ROUTING_EVENTS) {
+    const command = hookCommand(target, event);
+    const groups = hooks[event] ?? [];
+    const matches = groups.flatMap((group) => group.hooks)
+      .filter((hook) => hook.type === "command" && hook.command === command);
+    if (matches.length) present += 1;
+    if (action === "disable") {
+      if (!matches.length) continue;
+      hooks[event] = groups.flatMap((group) => {
+        const remaining = group.hooks.filter((hook) => hook.type !== "command" || hook.command !== command);
+        if (remaining.length === group.hooks.length) return [group];
+        return remaining.length ? [{ ...group, hooks: remaining }] : [];
+      });
+      if (!hooks[event].length) delete hooks[event];
+      changed = true;
+    } else if (action === "enable" && !matches.length) {
+      hooks[event] = [...groups, { hooks: [{ type: "command", command }] }];
+      changed = true;
+    }
+  }
+
+  if (!["enable", "disable", "status"].includes(action)) {
+    throw new Error(`unsupported routing action: ${action}`);
+  }
+  if (changed) nextConfig.hooks = hooks;
+  return {
+    name,
+    path,
+    target,
+    before,
+    after: changed ? `${JSON.stringify(nextConfig, null, 2)}\n` : before,
+    mode,
+    status: action === "disable"
+      ? "disabled"
+      : action === "enable" || (present === 2 && assetsPresent)
+        ? "configured"
+        : present
+          ? "incomplete"
+          : "not-configured",
+  };
+}

package/scripts/installer/routing-store.mjs

@@ -0,0 +1,151 @@
+import { open, mkdir, readFile, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getHarness } from "./catalog.mjs";
+import { assertNoSymlinkComponents, existingPath } from "./filesystem.mjs";
+import { countRoutingEvents, createRoutingPlan, routingPath, validateHookConfig } from "./routing-rules.mjs";
+import { targetFor } from "./selection.mjs";
+
+export async function prepareRouting(selected, action, { environment, platform, sourceDirectory }) {
+  const plans = [];
+  for (const name of new Set(selected.harnessNames)) {
+    const path = routingPath(name, {
+      scope: selected.scope,
+      cwd: selected.cwd,
+      home: selected.home,
+      claudeConfigDir: environment.CLAUDE_CONFIG_DIR,
+      codexHome: environment.CODEX_HOME,
+    });
+    if (!path || platform === "win32") {
+      plans.push({ name, status: "unsupported-host" });
+      continue;
+    }
+
+    await assertNoSymlinkComponents(path);
+    const stat = await existingPath(path);
+    if (stat && !stat.isFile()) throw new Error(`routing configuration must be a regular file: ${path}`);
+    const before = stat ? await readFile(path, "utf8") : null;
+    let config;
+    try {
+      config = before === null ? {} : JSON.parse(before);
+    } catch {
+      throw new Error(`invalid JSON; routing configuration left unchanged: ${path}`);
+    }
+    validateHookConfig(config, path);
+    const harness = getHarness(name);
+    if (!harness) throw new Error(`cannot prepare routing for unknown harness: ${name}`);
+    const target = targetFor(harness, selected.scope, selected.cwd, selected.home, environment);
+    let assetsPresent = true;
+    if (action === "status" && countRoutingEvents(config, target) > 0) {
+      for (const relative of ["SKILL.md", "scripts/delegate-routing-context.sh", "references/routing-rule.json"]) {
+        const asset = await existingPath(join(target, relative));
+        if (!asset?.isFile() || asset.isSymbolicLink()) assetsPresent = false;
+      }
+    }
+    plans.push(createRoutingPlan({
+      name,
+      path,
+      target,
+      before,
+      config,
+      mode: stat ? stat.mode & 0o777 : 0o600,
+      action,
+      assetsPresent,
+    }));
+  }
+  return plans;
+}
+
+async function replaceRoutingConfig(plan, before, after) {
+  await assertNoSymlinkComponents(plan.path);
+  await mkdir(dirname(plan.path), { recursive: true });
+  const lockPath = plan.path + ".delegation-layer.lock";
+  let lock;
+  try {
+    lock = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+      throw new Error(`routing configuration is locked: ${lockPath}; verify no other installer is running before removing a stale lock`);
+    }
+    throw error;
+  }
+  const suffix = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const temporary = plan.path + `.delegation-layer-stage-${suffix}`;
+  try {
+    const stat = await existingPath(plan.path);
+    if (stat && (!stat.isFile() || stat.isSymbolicLink())) {
+      throw new Error(`routing configuration changed during installation: ${plan.path}`);
+    }
+    const current = stat ? await readFile(plan.path, "utf8") : null;
+    if (current !== before) throw new Error(`routing configuration changed during installation; retry: ${plan.path}`);
+    if (before !== null) {
+      const backup = await open(plan.path + `.delegation-layer-backup-${suffix}`, "wx", 0o600);
+      try {
+        await backup.writeFile(before);
+        await backup.sync();
+      } finally {
+        await backup.close();
+      }
+    }
+    if (after === null) {
+      await unlink(plan.path);
+      return;
+    }
+    const staged = await open(temporary, "wx", plan.mode);
+    try {
+      await staged.writeFile(after);
+      await staged.sync();
+    } finally {
+      await staged.close();
+    }
+    await rename(temporary, plan.path);
+  } finally {
+    try {
+      try {
+        await unlink(temporary);
+      } catch (error) {
+        if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) throw error;
+      }
+    } finally {
+      try {
+        await lock.close();
+      } finally {
+        await unlink(lockPath);
+      }
+    }
+  }
+}
+
+export async function applyRouting(plans) {
+  const applied = [];
+  try {
+    for (const plan of plans) {
+      if (!plan.path || plan.before === plan.after) continue;
+      await replaceRoutingConfig(plan, plan.before, plan.after);
+      applied.push(plan);
+    }
+  } catch (error) {
+    const failures = [];
+    for (const plan of applied.reverse()) {
+      try {
+        await replaceRoutingConfig(plan, plan.after, plan.before);
+      } catch (rollbackError) {
+        failures.push(rollbackError instanceof Error ? rollbackError.message : String(rollbackError));
+      }
+    }
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`${reason}${failures.length ? `; rollback needs attention: ${failures.join("; ")}` : "; earlier routing changes rolled back"}`);
+  }
+}
+
+export function printRouting(plan, action, report) {
+  if (!plan.path) {
+    report(`${plan.name}: unsupported-host for automatic routing; skill-only guidance remains available.`);
+    return;
+  }
+  report(`${plan.name}: ${plan.status} (${plan.path}).`);
+  if (plan.status === "configured") {
+    report("Activation not verified: start or resume a session and check the native hook output. Installation is not proof of model compliance.");
+    if (plan.name === "codex") report("Codex: review and trust the hooks using /hooks. New or changed definitions are skipped until trusted.");
+  }
+  if (action === "disable") report("Only this installer's matching hooks were removed; plugin hooks are managed by the host plugin manager.");
+}

package/scripts/installer/selection.mjs

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { resolveFrom } from "./paths.mjs";
+
+export function defaultHarnessNames(detections) {
+  const detected = detections
+    .filter(({ harness, reasons }) => harness.name !== "universal" && reasons.length > 0)
+    .map(({ harness }) => harness.name);
+  return detected.length > 0 ? detected : ["universal"];
+}
+
+export function formatDetected(reasons) {
+  return reasons.length > 0 ? ` (detected: ${reasons.join(", ")})` : "";
+}
+
+export function resolveInstallSelection({ force, harnessNames, scope, routing, cwd, home, detections }) {
+  return {
+    routing: routing ?? "skill-only",
+    cwd,
+    force,
+    harnessNames: harnessNames ?? defaultHarnessNames(detections),
+    home,
+    scope: scope ?? "global",
+  };
+}
+
+export function targetFor(harness, scope, cwd, home, environment = {}) {
+  if (!harness) throw new Error("cannot resolve an install target for an unknown harness");
+  if (scope === "global" && harness.name === "claude" && environment.CLAUDE_CONFIG_DIR) {
+    return join(resolveFrom(cwd, environment.CLAUDE_CONFIG_DIR), "skills", "agent-integration");
+  }
+  const root = scope === "global" ? home : cwd;
+  const relativePath = scope === "global" ? harness.globalPath : harness.projectPath;
+  return join(root, ...relativePath, "agent-integration");
+}

package/scripts/installer/skill-store.mjs

@@ -0,0 +1,33 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  assertNoSymlinkComponents,
+  copySkillTree,
+  existingPath,
+  skillFiles,
+  skillTreeHasExistingFiles,
+  skillTreeMatches,
+} from "./filesystem.mjs";
+
+export async function installSkill({ sourceDirectory, target, force, report }) {
+  await assertNoSymlinkComponents(target);
+  const targetStat = await existingPath(target);
+  if (targetStat?.isSymbolicLink()) {
+    throw new Error(`target directory must not be a symlink: ${target}`);
+  }
+  if (targetStat && !targetStat.isDirectory()) {
+    throw new Error(`target must be a directory: ${target}`);
+  }
+
+  const files = await skillFiles(sourceDirectory);
+  await mkdir(target, { recursive: true });
+  if (!force && (await skillTreeMatches(sourceDirectory, target, files))) {
+    report(`Skill already installed: ${join(target, "SKILL.md")}`);
+    return;
+  }
+  if (!force && (await skillTreeHasExistingFiles(target, files))) {
+    throw new Error(`skill files already exist; use --force to replace them: ${target}`);
+  }
+  await copySkillTree(sourceDirectory, target, files, force);
+  report(`Installed agent integration skill: ${join(target, "SKILL.md")}`);
+}

package/scripts/installer/terminal.mjs

@@ -0,0 +1,104 @@
+import { emitKeypressEvents } from "node:readline";
+import { createPickerState, transitionPicker } from "./picker-state.mjs";
+
+function renderPicker({ error, index, multiple, options, selectedValues, title }, output) {
+  const selected = new Set(selectedValues);
+  const lines = [title, ""];
+  options.forEach((option, optionIndex) => {
+    const current = optionIndex === index;
+    const marker = multiple ? (selected.has(option.value) ? "[x]" : "[ ]") : "";
+    const cursor = current ? "❯" : " ";
+    const color = current ? "\u001b[36m" : "";
+    const reset = current ? "\u001b[0m" : "";
+    lines.push(`${color}${cursor} ${marker ? `${marker} ` : ""}${option.label}${reset}`);
+    if (option.description) lines.push(`      ${option.description}`);
+  });
+  lines.push("");
+  lines.push(multiple
+    ? "↑↓ move  Space select  Enter continue  a all  n none  q cancel"
+    : "↑↓ move  Enter select  q cancel");
+  if (error) lines.push(`\u001b[31m${error}\u001b[0m`);
+  output.write(`\u001b[2J\u001b[H${lines.join("\n")}\n`);
+}
+
+export function pickOptions({ initialValues = [], multiple = false, options, title, input, output }) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") return null;
+
+  return new Promise((resolve, reject) => {
+    let state = createPickerState({ initialValues, multiple });
+    let settled = false;
+
+    const cleanup = () => {
+      const failures = [];
+      try { input.off("keypress", onKeypress); } catch (error) { failures.push(error); }
+      try { input.setRawMode(false); } catch (error) { failures.push(error); }
+      try { input.pause(); } catch (error) { failures.push(error); }
+      try { output.write("\u001b[?25h\u001b[0m"); } catch (error) { failures.push(error); }
+      if (failures.length) {
+        const details = failures.map((failure) => failure instanceof Error ? failure.message : String(failure));
+        throw new Error(`terminal cleanup failed: ${details.join("; ")}`);
+      }
+    };
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      try {
+        cleanup();
+        resolve(value);
+      } catch (error) {
+        reject(error);
+      }
+    };
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      try {
+        cleanup();
+      } catch (cleanupError) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const cleanupReason = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+        reject(new Error(`${reason}; ${cleanupReason}`));
+        return;
+      }
+      reject(error);
+    };
+
+    const draw = () => renderPicker({ ...state, options, title }, output);
+    const onKeypress = (character, key = {}) => {
+      try {
+        let action;
+        if ((key.ctrl && key.name === "c") || key.name === "escape" || key.name === "q") action = "cancel";
+        else if (key.name === "up" || key.name === "k") action = "up";
+        else if (key.name === "down" || key.name === "j") action = "down";
+        else if (multiple && (key.name === "space" || character === " ")) action = "toggle";
+        else if (multiple && key.name === "a") action = "all";
+        else if (multiple && key.name === "n") action = "none";
+        else if (key.name === "return" || key.name === "enter") action = "enter";
+        else return;
+
+        const result = transitionPicker(state, action, options.map((option) => option.value));
+        state = result.state;
+        if (result.done) {
+          finish(result.value);
+        } else {
+          draw();
+        }
+      } catch (error) {
+        fail(error);
+      }
+    };
+
+    try {
+      emitKeypressEvents(input);
+      input.setRawMode(true);
+      input.resume();
+      input.on("keypress", onKeypress);
+      output.write("\u001b[?25l");
+      draw();
+    } catch (error) {
+      fail(error);
+    }
+  });
+}

package/skills/agent-integration/SKILL.md

@@ -34,7 +34,7 @@ Do not inspect, authenticate, install, or repair provider CLIs to bypass a
 Delegate blocker.
 
 A reported blocker is a valid final response to a delegation request. It does
-not turn that request into an environment-repair task. The one lifecycle
+not turn that request into an environment-repair task. The supervisor recovery
 exception is `failure.code: "supervisor_upgrade_required"` with
 `next_action: "run_supervisor_migrate"`: run Delegate's own
 `supervisor migrate` command once with the exact same state root, then retry the
@@ -47,6 +47,9 @@ not Pueue administration. Never run `pueue`, `pueued`, socket inspection,
 process searches, root deletion, or a provider CLI during recovery. Executable
 path or hash drift alone is handled by normal adoption and does not require
 this command.
+Managed admission also permits the two explicit `watch_workspace` responses
+in the task-record table below. They keep the exact admission command and
+inputs, including `continue`; they do not authorize environment repair.
 When a response says `failure.next_action: "stop_and_report"`, that attempt is
 finished. Include its failure in your final response without opening a
 clarification dialog to choose a fallback. For `task_record: not_created`,
@@ -72,7 +75,9 @@ tasks may proceed; the failed attempt must remain reported as failed or blocked.
 3. Give every turn an absolute workspace, an explicit permission mode, and a
    finite budget. Keep the state root outside the workspace. Reuse a supplied
    `DELEGATE_ROOT` for all providers and tasks; do not invent per-provider or
-   per-task state roots. Task IDs separate work within that root.
+   per-task state roots. Task IDs separate work within that root. Managed Git
+   workspaces are optional; read [managed workspace guidance](references/workspaces.md)
+   before creating or attaching one.
 4. Use `--json` and save each response separately with its requested destination,
    model, effort, workspace, and returned `task_id`. Never merge concurrent
    responses into an unlabeled output stream. Read `admission`, `liveness`,
@@ -119,8 +124,10 @@ tasks may proceed; the failed attempt must remain reported as failed or blocked.
 11. The model chooses ordinary-task fan-out by issuing independent `dispatch`
     commands concurrently. The private supervisor does not impose a task-count
     or CPU-based limit. Use this for independent investigation, debate, review,
-    or provider comparison. Concurrent write tasks must use separate workspaces
-    or explicit coordination to avoid file conflicts.
+    or provider comparison. For independent parallel writes, choose
+    `--isolation git-worktree` automatically unless the user explicitly chooses
+    shared coordination; the model chooses fan-out and task scope. A read-only
+    review may attach a retained workspace with `--workspace ID`.
 
 For an explicit Codex code review, use the discoverable `codex:review` profile
 with one persisted target: `--review-target uncommitted`,
@@ -131,6 +138,13 @@ provider to edit files; the review profile is for Codex's native review
 operation and keeps the reviewed Git state explicit. The brief is retained as
 task evidence; the review target supplies Codex's review scope because its
 native command does not accept a prompt with the target flag.
+For a complete managed-workspace turn, review the recorded initial base against
+its captured tree through an ordinary read-only task. Include both sealed refs
+and an explicit `git diff BASE TREE` scope. A native `uncommitted` review covers
+current staged, unstaged, and untracked changes; it excludes worker commits.
+Do not pass a tree as a native branch target. Preserve an explicitly requested
+native review target and state its narrower scope. See [workspace review
+guidance](references/workspaces.md#recovery-and-review-scope).
 
 ## Operating procedure
 
@@ -152,7 +166,7 @@ If no destination was named, use automatic selection directly. If the user
 named a harness (for example, “Codex”), resolve its exact provider ID from:
 
 ```sh
-delegate providers --json
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" providers --json
 ```
 
 Use the matching catalog ID with `--provider`; do not silently substitute
@@ -287,6 +301,7 @@ for **each attempt**, including requests issued together:
 | Usage error, no JSON response | Correct the reported syntax using Delegate help or `providers --json`, then invoke that request again. Parsing failed before admission. |
 | `task_record: not_created`, `failure.code: supervisor_upgrade_required`, and `failure.next_action: run_supervisor_migrate` | Run `delegate --root "<the exact absolute state root used by the failed command>" supervisor migrate --json` once. Retry the exact original admission argv once only after `supervisor_control.state: migrated` and `supervisor_control.next_action: retry_dispatch`; otherwise stop and report the migration response. Preserve an explicit custom root exactly. A failed `continue` must be retried as the same `continue`; never replace it with a fresh `dispatch` or a direct provider call. |
 | `task_record: not_created` and `failure.next_action: correct_request` | Correct that request and retry it. |
+| `task_record: not_created`, `failure.code: workspace_provision_pending` or `workspace_busy`, and `failure.next_action: watch_workspace` | Follow [managed workspace recovery](references/result-handling.md#managed-workspace-results) using the same root and workspace. Once ready, retry the exact admission command and inputs. A failed `continue` remains that same `continue`, never a new dispatch. |
 | `task_record: not_created` with any other next action | Report that attempt's failure and stop it. Do not diagnose provider setup or substitute an integration. |
 | `task_record: created` | Use `status` before taking any other action. Do not dispatch again. |
 | `task_record: unknown` or an ambiguous response | Stop and report; do not retry an uncertain task creation. |
@@ -352,10 +367,14 @@ recruit more agents unless that is explicitly part of the task.
   admission, publication, authentication, errors, or exit codes.
 - Read [continuation](references/continuation.md) for timeout recovery or an
   exact-session follow-up.
+- Read [managed workspaces](references/workspaces.md) for optional Git
+  worktrees, capture, review scope, release, and forgetting.
 - Use [read-only example](examples/read-only-task.md),
-  [write example](examples/workspace-write-task.md), and
-  [JSON examples](examples/json-results.md) when constructing a task or parsing
-  unfamiliar output. Do not load every reference for a routine dispatch.
+  [write example](examples/workspace-write-task.md),
+  [JSON examples](examples/json-results.md), and
+  [managed workspace example](examples/managed-workspace.md) when constructing
+  a task or parsing unfamiliar output. Do not load every reference for a
+  routine dispatch.
 
 ## Completion report