openplanr 3.3.0 → 3.5.0

package/lib/host-packages/openai/openplanr/skills/artifact/references/design-sharing.md

@@ -40,8 +40,8 @@ repository notes, credentials or an entire specification into shared context.
 Open the design with `openplanr artifact <design-document.json>` after editing context;
 the route validates and renders it. If it reports a draft error and falls back to
 the previous working revision, fix that error before sharing the changed context.
-When working through an installed design
-skill instead, use its bundled `validate`, `render` and `open` utilities. Inspect
+When working through a design skill instead,
+use `openplanr design validate`, `render` and `open`. Inspect
 Welcome for the correct design title, purpose and review questions, then use the
 explicit Share or Publish action. If browser inspection is unavailable, state
 that the welcome is unverified. Changing the context file alone does not update

package/lib/host-packages/openai/openplanr/skills/delegate/SKILL.md

@@ -68,7 +68,8 @@ digest-acceptance step or permanently frozen setup baseline. See
 
 Use the returned pinned helper for subsequent actions. `dispatch`, bounded `wait`
 and `status` expose the exact session, native progress, inactivity and phase timings.
-Native tools, permissions, configuration and implementation loops remain native.
+Native tools, permissions, configuration and implementation loops remain native, except
+that Claude Code or Codex with no configured permission mode starts in its edit mode.
 Do not add bypass/force/yolo flags, blanket tool exclusions or silent model fallbacks.
 Local backend probes are compatibility diagnostics, not a separate execution policy.
 They read model metadata without submitting inference, loading models or sending

package/lib/host-packages/openai/openplanr/skills/delegate/openplanr.skill.json

@@ -298,7 +298,7 @@
       "executable": false
     },
     {
-      "path": "scripts/integration-transaction.mjs",
+      "path": "scripts/handoff.mjs",
       "kind": "script",
       "hosts": [
         "claude-code",

package/lib/host-packages/openai/openplanr/skills/delegate/references/integration-review.md

@@ -26,32 +26,38 @@ parent host's normal execution controls and configuration. They are not an OpenP
 OS sandbox. Arguments, exits, timings and bounded private failure diagnostics are
 saved separately from native-agent check claims.
 
-Verification normally runs in the prepared owned worktree. Ordinary ignored
-build/cache outputs are allowed. If preparation, a check or generation changes
-reviewable source/tests/configuration/generated files, the old review is invalid:
-inspect the updated candidate and review again before acceptance. If the source
-checkout makes the prepared tree stale, verification uses a fresh candidate only
-when needed, retaining the original native session/worktree.
+`review` commits the worktree's non-ignored state as the run branch tip and reviews
+`git diff base tip`. Verification runs in the owned worktree at that tip: checks see
+HEAD plus the selected files plus the delegate's changes, not the parent checkout's
+other uncommitted files, which the report lists. Ordinary ignored build/cache outputs
+are allowed. If preparation, a check or generation changes reviewable
+source/tests/configuration/generated files, the old review is invalid: inspect the
+updated candidate and review again before acceptance.
 
 Failed checks keep the candidate blocked. `baselineComparison: true` explicitly
-requests a relevant failed-check comparison; it is diagnostic and cannot turn a
-failure into acceptance. Earlier attempt evidence remains private. Narrowing a
+requests a relevant failed-check comparison in a temporary worktree at the base
+commit; it is diagnostic and cannot turn a failure into acceptance. Dependencies are
+not copied there, so include their setup in `preparation`. Earlier attempt evidence remains private. Narrowing a
 previously failed check set requires `checkSelectionReason`. With no applicable
 automated check, `reviewOnlyReason` allows explicitly unverified review-only
 integration; zero checks never produces a verified outcome.
 
 ## Checkout protection and recovery
 
-The integration lock, scope/Preserve checks, reviewed patch identity, destination
-compare-and-swap and recovery journal protect checkout writes. Concurrent user
-edits are never overwritten or rolled back. A source change during checks requires
-reviewing the actual candidate again. The journal records intended states before
-the first source write and recovery touches only helper-written paths that still
-match those states.
+The per-repository lock, scope/Preserve checks and the reviewed tip protect checkout
+writes. `apply` saves a restore point (`git stash create`) under the private ref
+`refs/planr-delegate/<runId>/restore`, then runs `git apply --check` and `git apply`
+with the saved `patch.diff`. A parent edit elsewhere in a changed file merges; an
+overlapping parent edit blocks with its path and leaves the checkout untouched.
+Concurrent user edits are never overwritten or rolled back.
 
-An interrupted source write must use `recover` with rollback (default) or accept
-after inspecting every journaled path. Keep conflicting user edits. Do not bypass
-a rejected helper by manually applying its patch.
+If `git apply` fails without writing, for example after a parent save between its check
+and the write, the run returns to review with the conflicting paths. An apply
+interrupted between its check and completion must use `recover`, which compares each
+patch path with its pre- and post-apply content. A fully applied patch can be accepted;
+rollback (default) restores only paths that match their post-apply content and keeps
+file permissions. Keep conflicting user edits. Do not bypass a rejected helper by manually applying
+its patch.
 
 Successful native integration closes the exact run, saves evidence/report and
 removes only its owned worktree unless retained. `status` recovers the five-field
@@ -61,8 +67,8 @@ deployment are outside this helper.
 Experimental generic protocol-v1 adapters and older pinned helpers retain their
 original check interface and lifecycle; native v2 does not expand their permissions.
 
-Destination publication claims the existing directory entry and compares its bytes before exclusive creation of the replacement. Concurrent replacements block integration. Claimed originals remain in private write custody (Git metadata, or destination-local custody when volumes differ) for crash recovery and writers holding an old inode; conflicts report their retained paths. Rollback uses the same guard and cannot discard a changed claimed original.
+## Process custody and runs pinned to older helpers
 
-Candidate identity is checked across verification and acceptance; a changed owned worktree is retained instead of automatically removed. Guarded writes validate parent-directory identities as well as final entries. The parent host provides filesystem containment: these checks are conflict detection, not an OS sandbox against processes that deliberately rename ancestors between syscalls. Process custody stops the owned process group; intentionally detached services and processes outside that group remain the native harness/operator responsibility. Independent commands must finish their work before returning success.
+Process custody stops the owned process group; intentionally detached services and processes outside that group remain the native harness/operator responsibility. Independent commands must finish their work before returning success. Cleanup checks that the owned worktree is still at the accepted tip after ownership reads, just before removal; a changed worktree is retained for inspection.
 
-Native interruption recovery validates the complete checkout against the journaled candidate identity before accepting saved verification. Cleanup validates accepted worktree contents after ownership reads, just before removal; an already absent owned worktree can still be unregistered. Concurrent editor saves detected at either boundary retain their files and require review or recovery.
+A run prepared by an older helper, without a run branch, finishes review, apply and recovery through that pinned helper. The current helper refuses its custody instead of integrating it.

package/lib/host-packages/openai/openplanr/skills/delegate/references/operator-guide.md

@@ -114,7 +114,31 @@ a GGUF filename or display label is not automatically its request ID. Apply an
 explicit model override only to this run through the existing native options;
 rewrite or enroll a saved profile only when the user requests it.
 
-If a native CLI uses read-only permissions for non-interactive runs, delegation reports attention rather than enabling writes. Resolve access in that CLI’s own configuration or explicitly authorized exact-session invocation, then continue the recorded session. Model summaries are never sufficient evidence of implementation.
+When the CLI's own settings choose no permission mode, dispatch and resume start
+Claude Code with `--permission-mode acceptEdits` and Codex with `--sandbox
+workspace-write`, so a stock install can edit files in its worktree. In
+`acceptEdits`, Claude also runs `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp` and `sed`
+without asking, for paths in the worktree and the added context directory. A
+configured mode always wins: Claude `permissions.defaultMode` in user, project, local
+or managed settings files, or Codex `sandbox_mode` in `config.toml` or the project's
+`.codex/config.toml`, outside an inactive profile. Unreadable or oversized settings
+count as configured. Cursor runs with `--trust`. Other shell commands still follow
+the CLI's allowlist and approval settings, and no bypass flag is passed.
+
+Limits of this check: it reads settings files only, so system or MDM-delivered
+policies and Codex managed configuration are not seen. A Codex profile selected in
+one file but defined in the other is not matched. A project-level Claude
+`defaultMode`, including `"auto"`, counts as configured. The check runs again on each
+`resume`, so a settings change between turns can change the flag.
+
+If the CLI still denies an action, delegation
+reports attention rather than widening access. Resolve access in that CLI’s own configuration or explicitly authorized exact-session invocation, then continue the recorded session. Model summaries are never sufficient evidence of implementation.
+
+Cursor's CLI writes its own state back to `~/.cursor/cli-config.json` when a run
+ends, so `permissions.allow` entries added while a run is active can be lost. Add
+the commands the task needs (for example `Shell(pnpm)`) before `dispatch`. After an
+`E_ADAPTER_PERMISSION` attention state, wait until the run has stopped, edit the
+allowlist, then `resume` the same run.
 
 ## Diagnostics and unused runs
 

package/lib/host-packages/openai/openplanr/skills/delegate/references/run-handoff.md

@@ -1,7 +1,7 @@
 # Run/session lifecycle
 
-Each new run has private v2 records, a complete readable capsule, one owned detached
-worktree and a pinned helper snapshot. Records contain configuration references,
+Each new run has private v3 records, a complete readable capsule, one owned worktree
+on its run branch and a pinned helper snapshot. Records contain configuration references,
 not credential values. Old runs route operations through their unchanged pinned
 helpers; there is no automatic migration or permission expansion.
 

package/lib/host-packages/openai/openplanr/skills/delegate/references/worktree-custody.md

@@ -1,13 +1,21 @@
 # Worktree and context custody
 
-One run owns one detached worktree outside the user's checkout. Copy only selected
-dirty state, preserving starting bytes, deletion and the Git executable bit. Full
-required ignored planning and repository instructions live in the readable capsule.
-The source checkout and unrelated worktrees remain independent.
+One run owns one locked worktree on its own branch, `planr-delegate/<runId>`, outside
+the user's checkout. Only selected dirty state is copied, preserving starting bytes,
+deletion and the Git executable bit, then committed as the run's base commit without
+repository hooks. Full required ignored planning and repository instructions live in
+the readable capsule. The source checkout and unrelated worktrees remain independent.
 
-Custody records bind the run, worktree ownership, starting HEAD/index, selected
-source state and Preserve paths. Commits, staging, Preserve changes, scope violations
-and destination conflicts block acceptance. Integration scope constrains accepted
+Custody records bind the run, worktree ownership, base commit, selected source state,
+Preserve paths and the repository's refs. The delegate may commit; the run branch must
+stay checked out and descend from its base. The branch checked out in the parent at
+prepare may not be deleted or moved to a commit that contains the run's base, and a
+restore ref may not be deleted while its run is still applying or interrupted. Any
+other ref change, such as a branch switch, amend, reset, stash, fetch or tag, is a
+report warning.
+Preserve changes, scope violations, submodule (gitlink) changes, including ones that
+`ignore` settings hide, and patches the parent
+checkout no longer accepts block acceptance. Integration scope constrains accepted
 changes; it does not sandbox every native tool operation. Native tools, hooks,
 plugins and MCP run under the native harness's permissions and trusted configuration.
 
@@ -16,10 +24,10 @@ and join the candidate; no manual digest acceptance or immutable setup-path list
 needed. Ignored dependencies/build/cache outputs are ordinary worktree outputs.
 
 Successful native integration removes only the owned worktree by checking its
-ownership token and Git registration. Retention can be requested before dispatch.
+ownership token and Git registration, then deletes its run branch. Retention can be requested before dispatch.
 Failures/interruption retain custody. The private run keeps context, accepted patch,
 verification evidence, report and exact native session reference after cleanup.
 Old runs continue through their pinned helper; never broaden their policy or migrate
 their records automatically.
 
-Guarded integration keeps original directory entries for recovery and for writers holding the old inode. If Git metadata is on a different filesystem, private ignored write custody stays beside the destination and its location is recorded in the Git metadata before the first source write. Recovery validates that location inside the checkout. Existing metadata-based custody and pinned legacy helpers remain readable.
+Runs prepared by older helpers use detached worktrees and their own integration; they finish through that pinned helper.

package/lib/host-packages/openai/openplanr/skills/delegate/scripts/adapters/claude.mjs

@@ -5,9 +5,9 @@ import { capsuleDirectory } from './capsule.mjs';
 import { AdapterError, destinationFromEndpoint, invokeProcess } from './generic.mjs';
 import {
   createNativeProgress,
+  EDIT_DEFAULT_EXECUTION_POLICY,
   knownDestination,
   NATIVE_CAPABILITIES,
-  NATIVE_EXECUTION_POLICY,
   nativeFailure,
   nativeObserver,
   nativeTurn,
@@ -26,7 +26,7 @@ function routingVariables(env) {
   );
 }
 
-// Keeps only routing variables from settings files; callers expose source labels and origins.
+// Keeps routing variables and whether a default permission mode is set; callers expose source labels.
 async function readClaudeRoutingSettings(profile, env, cwd, options = {}) {
   const managedRoot =
     options.managedRoot ??
@@ -108,6 +108,7 @@ async function readClaudeRoutingSettings(profile, env, cwd, options = {}) {
       inspected.push({
         source,
         env: routingVariables(settings.env ?? {}),
+        ...(settings.permissions?.defaultMode !== undefined ? { defaultMode: true } : {}),
         ...(settings.policyHelper ? { opaqueRouting: true } : {}),
       });
     } catch (error) {
@@ -202,6 +203,16 @@ export async function resolveClaudeRouting(profile, env, cwd, options) {
   };
 }
 
+// Edit access only when no settings file chooses a mode; unreadable settings count as chosen.
+export async function claudeWriteFlags(profile, env, cwd, options) {
+  try {
+    const settings = await readClaudeRoutingSettings(profile, env, cwd, options);
+    return settings.some((entry) => entry.defaultMode) ? [] : ['--permission-mode', 'acceptEdits'];
+  } catch {
+    return [];
+  }
+}
+
 export async function resolveClaudeDestination(profile, env, cwd) {
   return (await resolveClaudeRouting(profile, env, cwd)).destination;
 }
@@ -263,6 +274,7 @@ async function execute({
     profile.executable,
     [
       ...profile.argv,
+      ...(await claudeWriteFlags(profile, env, cwd)),
       '--print',
       '--output-format',
       'stream-json',
@@ -317,7 +329,7 @@ export const claudeAdapter = Object.freeze({
     return {
       capabilities: NATIVE_CAPABILITIES,
       ...routing,
-      executionPolicy: NATIVE_EXECUTION_POLICY,
+      executionPolicy: EDIT_DEFAULT_EXECUTION_POLICY,
     };
   },
   run: execute,

package/lib/host-packages/openai/openplanr/skills/delegate/scripts/adapters/codex.mjs

@@ -1,11 +1,12 @@
+import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { capsuleDirectory } from './capsule.mjs';
 import { AdapterError, invokeProcess } from './generic.mjs';
 import {
   createNativeProgress,
+  EDIT_DEFAULT_EXECUTION_POLICY,
   knownDestination,
   NATIVE_CAPABILITIES,
-  NATIVE_EXECUTION_POLICY,
   nativeFailure,
   nativeObserver,
   nativeTurn,
@@ -31,6 +32,39 @@ export async function resolveCodexDestination(profile, env) {
   return knownDestination(endpoint);
 }
 
+// Any uncommented sandbox_mode key outside an inactive [profiles.<name>] table counts as set.
+function sandboxModeSet(config) {
+  const active = /^\s*profile\s*=\s*["']([^"']+)["']/mu.exec(config.split(/^\s*\[/mu)[0])?.[1];
+  let skipped = false;
+  for (const line of config.split('\n')) {
+    const header = /^\s*\[\s*profiles\.(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))\s*\]/u.exec(line);
+    if (header) skipped = (header[1] ?? header[2] ?? header[3]) !== active;
+    else if (/^\s*\[/u.test(line)) skipped = false;
+    if (!skipped && /^[^#]*\bsandbox_mode["']?\s*=/u.test(line)) return true;
+  }
+  return false;
+}
+
+// Missing config means no sandbox choice; unreadable or oversized config counts as a choice.
+async function codexConfigChoosesSandbox(path) {
+  let config;
+  try {
+    if ((await stat(path)).size > 64 * 1024) return true;
+    config = await readFile(path, 'utf8');
+  } catch (error) {
+    return error.code !== 'ENOENT';
+  }
+  return sandboxModeSet(config);
+}
+
+// Workspace writes only when neither the user nor the project config chooses a sandbox.
+export async function codexWriteFlags(profile, env, cwd) {
+  const home = profile.configDir || env.CODEX_HOME || join(env.HOME ?? '', '.codex');
+  for (const path of [join(home, 'config.toml'), join(cwd, '.codex', 'config.toml')])
+    if (await codexConfigChoosesSandbox(path)) return [];
+  return ['--sandbox', 'workspace-write'];
+}
+
 async function execute({
   profile,
   cwd,
@@ -84,6 +118,8 @@ async function execute({
   const args = [
     ...profile.argv,
     'exec',
+    // `exec resume` takes no sandbox flag of its own; the parent `exec` flag applies.
+    ...(await codexWriteFlags(profile, env, cwd)),
     ...(sessionId ? ['resume'] : []),
     '--json',
     ...(!sessionId ? ['--add-dir', directory] : []),
@@ -141,7 +177,7 @@ export const codexAdapter = Object.freeze({
     return {
       capabilities: NATIVE_CAPABILITIES,
       destination: await resolveCodexDestination(profile, env),
-      executionPolicy: NATIVE_EXECUTION_POLICY,
+      executionPolicy: EDIT_DEFAULT_EXECUTION_POLICY,
     };
   },
   run: execute,

package/lib/host-packages/openai/openplanr/skills/delegate/scripts/adapters/native.mjs

@@ -20,6 +20,11 @@ export const NATIVE_EXECUTION_POLICY = Object.freeze({
   extensions:
     'Trusted native hooks, plugins and MCP may execute code or contact additional services. OpenPlanr does not sandbox these extensions.',
 });
+// Claude Code and Codex start in their edit mode when native settings choose none.
+export const EDIT_DEFAULT_EXECUTION_POLICY = Object.freeze({
+  ...NATIVE_EXECUTION_POLICY,
+  permissions: 'native-managed; edit mode when none is configured',
+});
 export const NATIVE_MANAGED_DESTINATION = Object.freeze({
   class: 'native-managed',
   origin: 'native-managed',

package/lib/host-packages/openai/openplanr/skills/delegate/scripts/custody.mjs

@@ -17,6 +17,7 @@ import {
 } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
+import { readRunRecord } from './run-record.mjs';
 
 const execFileAsync = promisify(execFile);
 export const CUSTODY_SCHEMA_VERSION = '1.0.0';
@@ -68,6 +69,148 @@ async function git(root, args, { allowFailure = false } = {}) {
   }
 }
 
+function gitInput(root, args, input) {
+  return new Promise((resolveOutput, reject) => {
+    const child = execFile(
+      'git',
+      args,
+      { cwd: root, encoding: 'buffer', maxBuffer: 32 * 1024 * 1024 },
+      (error, stdout) => {
+        const operation = args.find((arg) => !arg.startsWith('-'));
+        if (error)
+          reject(
+            new CustodyError('E_CUSTODY_GIT', `Git operation failed: ${operation}`, {
+              operation,
+              exitCode: error.code,
+            }),
+          );
+        else resolveOutput(stdout);
+      },
+    );
+    // Git may exit without reading stdin; its exit status, not the closed pipe, is the result.
+    child.stdin.on('error', (error) => {
+      if (error.code === 'EPIPE') return;
+      const operation = args.find((arg) => !arg.startsWith('-'));
+      reject(
+        new CustodyError('E_CUSTODY_GIT', `Git operation input failed: ${operation}`, {
+          operation,
+          cause: error.code,
+        }),
+      );
+    });
+    child.stdin.end(input);
+  });
+}
+
+export const RUN_BRANCH_PREFIX = 'planr-delegate/';
+// Repository hooks, signing and the user's identity never apply to run commits.
+export const HOOKLESS_COMMIT = [
+  '-c',
+  'core.hooksPath=/dev/null',
+  '-c',
+  'commit.gpgSign=false',
+  '-c',
+  'user.name=planr-delegate',
+  '-c',
+  'user.email=planr-delegate@localhost',
+  'commit',
+  '--no-verify',
+  '--allow-empty',
+  '-q',
+  '-m',
+];
+const RESTORE_REF = /^refs\/planr-delegate\/[^/]+\/restore$/u;
+
+async function refSnapshot(root, branch) {
+  const refs = {};
+  for (const line of (await git(root, ['for-each-ref', '--format=%(refname)%00%(objectname)']))
+    .toString('utf8')
+    .split('\n')) {
+    const [name, oid] = line.split('\0');
+    if (oid && name !== `refs/heads/${branch}`) refs[name] = oid;
+  }
+  return refs;
+}
+
+async function isAncestor(root, ancestor, descendant) {
+  return (
+    (await git(root, ['merge-base', '--is-ancestor', ancestor, descendant], {
+      allowFailure: true,
+    })) !== null
+  );
+}
+
+// A restore ref is gone legitimately once its run applied, recovered or was cleaned up.
+async function unresolvedRun(runDirectory, runId) {
+  if (!runDirectory) return true;
+  try {
+    const { integration } = await readRunRecord(runId, { directory: runDirectory });
+    return ['applying', 'interrupted'].includes(integration?.status);
+  } catch (error) {
+    if (['ENOENT', 'E_RUN_ID'].includes(error.code)) return false;
+    throw error;
+  }
+}
+
+async function branchViolations(root, record) {
+  const violations = [];
+  const head = (await git(root, ['symbolic-ref', '-q', 'HEAD'], { allowFailure: true }))
+    ?.toString('utf8')
+    .trim();
+  const branchRef = `refs/heads/${record.branch}`;
+  if (head !== branchRef)
+    violations.push({ code: 'E_CUSTODY_BRANCH', expected: record.branch, actual: head ?? null });
+  else if (
+    (await git(root, ['show-ref', '--verify', '--quiet', branchRef], { allowFailure: true })) ===
+    null
+  )
+    violations.push({ code: 'E_CUSTODY_BRANCH', expected: record.branch, actual: null });
+  else if (!(await isAncestor(root, record.base, 'HEAD')))
+    violations.push({ code: 'E_CUSTODY_BASE', base: record.base });
+  const parent = record.repositoryRoot;
+  const before = record.refs ?? {};
+  const now = await refSnapshot(parent, record.branch);
+  const reported = new Set([`refs/planr-delegate/${record.runId}/restore`]);
+  const previous = before[record.parentBranch] ?? record.initialHead;
+  const moved = record.parentBranch ? (now[record.parentBranch] ?? null) : undefined;
+  // Owner commits, amends and resets warn; only delegate work descends from base.
+  if (
+    moved === null ||
+    (moved && moved !== previous && (await isAncestor(parent, record.base, moved)))
+  ) {
+    reported.add(record.parentBranch);
+    violations.push({
+      code: 'E_CUSTODY_PARENT_BRANCH',
+      ref: record.parentBranch,
+      expected: previous,
+      actual: moved,
+    });
+  }
+  for (const name of Object.keys(before))
+    if (
+      RESTORE_REF.test(name) &&
+      !reported.has(name) &&
+      !now[name] &&
+      (await unresolvedRun(record.runDirectory, name.split('/')[2]))
+    ) {
+      reported.add(name);
+      violations.push({ code: 'E_CUSTODY_RESTORE_REF', ref: name });
+    }
+  const changed = [...new Set([...Object.keys(now), ...Object.keys(before)])]
+    .filter((name) => !reported.has(name) && now[name] !== before[name])
+    .sort();
+  const warnings = changed.length
+    ? [
+        {
+          code: 'W_CUSTODY_REFS',
+          refs: changed.slice(0, 20),
+          ...(changed.length > 20 ? { omitted: changed.length - 20 } : {}),
+        },
+      ]
+    : [];
+  return { violations, warnings };
+}
+
 function digest(bytes) {
   return createHash('sha256').update(bytes).digest('hex');
 }
@@ -425,6 +568,8 @@ export async function createWorktreeCustody({
   worktreeParent,
   runId = randomUUID(),
   native = false,
+  branch = false,
+  runDirectory,
 } = {}) {
   if (
     !repositoryRoot ||
@@ -504,7 +649,11 @@ export async function createWorktreeCustody({
       JSON.stringify({ runId, custodyToken, repositoryRoot: root, worktreePath }),
       { mode: 0o600, flag: 'wx' },
     );
-    await git(root, ['worktree', 'add', '--detach', '--', worktreePath, initialHead]);
+    const branchName = `${RUN_BRANCH_PREFIX}${runId}`;
+    if (branch) {
+      await git(root, ['worktree', 'add', '-b', branchName, '--', worktreePath, initialHead]);
+      await git(root, ['worktree', 'lock', '--reason', `planr-delegate ${runId}`, worktreePath]);
+    } else await git(root, ['worktree', 'add', '--detach', '--', worktreePath, initialHead]);
     const checkoutFiles = native
       ? await initialCheckoutFiles(worktreePath, initialHead, paths)
       : {};
@@ -526,6 +675,33 @@ export async function createWorktreeCustody({
       }
       startingFiles[path] = await fileState(worktreePath, path);
     }
+    let handoff = {};
+    if (branch) {
+      if (paths.length)
+        await gitInput(
+          worktreePath,
+          [
+            '--literal-pathspecs',
+            'add',
+            '--force',
+            '--pathspec-from-file=-',
+            '--pathspec-file-nul',
+          ],
+          `${paths.join('\0')}\0`,
+        );
+      await git(worktreePath, [...HOOKLESS_COMMIT, `planr-delegate base ${runId}`]);
+      handoff = {
+        handoff: 'branch',
+        branch: branchName,
+        base: (await git(worktreePath, ['rev-parse', 'HEAD'])).toString('utf8').trim(),
+        parentBranch:
+          (await git(root, ['symbolic-ref', '-q', 'HEAD'], { allowFailure: true }))
+            ?.toString('utf8')
+            .trim() || null,
+        refs: await refSnapshot(root, branchName),
+        ...(runDirectory ? { runDirectory } : {}),
+      };
+    }
     const preservedFiles = {};
     for (const path of protectedPaths)
       preservedFiles[path] = await protectedState(worktreePath, path);
@@ -537,6 +713,7 @@ export async function createWorktreeCustody({
       repositoryRoot: root,
       worktreePath,
       initialHead,
+      ...handoff,
       initialIndex: await indexState(worktreePath),
       sourceIndex,
       selectedPaths: paths,
@@ -600,7 +777,7 @@ export async function inspectWorktreeSetup(record, options = {}) {
     const before =
       record.setupFiles?.[path] ??
       record.startingFiles?.[path] ??
-      (await headFileState(record.worktreePath, path, record.initialHead));
+      (await headFileState(record.worktreePath, path, record.base ?? record.initialHead));
     const after = await captureFileState(record.worktreePath, path);
     if (
       !sameGitState(
@@ -621,13 +798,20 @@ export async function validateWorktreeCustody(
     throw new CustodyError('E_CUSTODY_RECORD', 'A custody record is required.');
   const root = await assertRepository(record.worktreePath);
   const violations = [];
+  let warnings = [];
   await assertRepository(record.repositoryRoot);
-  // Source HEAD/index may advance on unrelated paths; integration checks each destination.
-  const head = (await git(root, ['rev-parse', 'HEAD'])).toString('utf8').trim();
-  if (head !== record.initialHead)
-    violations.push({ code: 'E_CUSTODY_HEAD', expected: record.initialHead, actual: head });
-  const currentIndex = await indexState(root);
-  if (currentIndex !== record.initialIndex) violations.push({ code: 'E_CUSTODY_INDEX' });
+  if (record.handoff === 'branch') {
+    const branch = await branchViolations(root, record);
+    violations.push(...branch.violations);
+    warnings = branch.warnings;
+  } else {
+    // Source HEAD/index may advance on unrelated paths; integration checks each destination.
+    const head = (await git(root, ['rev-parse', 'HEAD'])).toString('utf8').trim();
+    if (head !== record.initialHead)
+      violations.push({ code: 'E_CUSTODY_HEAD', expected: record.initialHead, actual: head });
+    const currentIndex = await indexState(root);
+    if (currentIndex !== record.initialIndex) violations.push({ code: 'E_CUSTODY_INDEX' });
+  }
   if (!native && record.engineConfiguration) {
     const currentConfiguration = await captureEngineConfiguration(root);
     for (const path of Object.keys(record.engineConfiguration))
@@ -640,7 +824,7 @@ export async function validateWorktreeCustody(
   // Abandonment supplies its own complete raw-byte filesystem inventory. Avoid
   // Git status there because it may invoke configured clean filters as a side effect.
   const currentStatus = inspectStatus ? await status(root) : { changedPaths: [], stagedPaths: [] };
-  if (currentStatus.stagedPaths.length)
+  if (currentStatus.stagedPaths.length && record.handoff !== 'branch')
     violations.push({ code: 'E_CUSTODY_STAGED', paths: currentStatus.stagedPaths });
   for (const path of record.preservePaths) {
     let now;
@@ -666,7 +850,12 @@ export async function validateWorktreeCustody(
     )
       violations.push({ code: 'E_CUSTODY_SETUP_CHANGED', path });
   }
-  return { valid: violations.length === 0, violations, changedPaths: currentStatus.changedPaths };
+  return {
+    valid: violations.length === 0,
+    violations,
+    warnings,
+    changedPaths: currentStatus.changedPaths,
+  };
 }
 
 export async function cleanupWorktreeCustody(record, { disposition, beforeRemove } = {}) {
@@ -731,12 +920,23 @@ export async function cleanupWorktreeCustody(record, { disposition, beforeRemove
   if (registered) {
     // Validate accepted contents after ownership reads, immediately before native removal.
     if (present) await beforeRemove?.(target);
+    if (record.handoff === 'branch' && worktreeLocked(listed, target))
+      await git(root, ['worktree', 'unlock', target]);
     await git(root, ['worktree', 'remove', '--force', '--', target]);
   } else if (present)
     throw new CustodyError(
       'E_CUSTODY_CLEANUP',
       'Present worktree is not registered to this repository.',
     );
+  if (record.handoff === 'branch')
+    for (const ref of [
+      `refs/heads/${record.branch}`,
+      `refs/planr-delegate/${record.runId}/restore`,
+    ])
+      if (
+        (await git(root, ['show-ref', '--verify', '--quiet', ref], { allowFailure: true })) !== null
+      )
+        await git(root, ['update-ref', '-d', ref]);
   await rm(physicalParent, { recursive: true, force: true });
   return {
     removed: target,
@@ -744,3 +944,10 @@ export async function cleanupWorktreeCustody(record, { disposition, beforeRemove
     ...(!present && !registered ? { alreadyRemoved: true } : {}),
   };
 }
+
+function worktreeLocked(listed, target) {
+  const block = listed.split('\n\n').find((entry) => entry.startsWith(`worktree ${target}\n`));
+  return Boolean(
+    block?.split('\n').some((line) => line === 'locked' || line.startsWith('locked ')),
+  );
+}