pi-odd-worktree 1.1.0 → 1.2.0

package/README.md

@@ -15,7 +15,7 @@ alone; Herdr is optional.
 | `worktree_create` | tool | Creates a branch and its checkout from the **local** `main`, registers it, runs the creation hooks, and copies the pending changes you name. |
 | `worktree_warp` | tool | Queues the session move to another checkout as a `/warp` handoff; the command performs the move when the turn ends. |
 | `worktree_close` | tool | Removes a registered checkout with `git worktree remove`, keeping the branch, and refuses while a live Pi session is working in it. |
-| `/warp` | panel | Moves this session to another checkout: no argument opens the selector (list, create, delete, extended list); `/warp <name>` jumps straight there. |
+| `/warp` | panel | Moves this session to another checkout: no argument opens the selector (list, create, delete, extended list); `/warp <name>` jumps straight there. A session with no conversation yet changes checkout **silently** — no fork, no `Warp · moved` card, nothing to carry — and warping back from it is the same empty case. |
 | `/odd-list` | panel | Two-pane reader of this checkout's `odd/tasks/*.md`: list on the left, styled markdown on the right. |
 | `/issues` | panel | Full-screen reader of this checkout's repository issues — My issues / Assigned / Involved / All — with preview, comments, labels, assignees and close, gated on your repository role. |
 | `/codegraph-hook` | command | **Only when the CodeGraph CLI is installed.** Turns the edit/write sync on or off for the session. |
@@ -34,7 +34,6 @@ interchangeably by `worktree_close`, and by `/warp`.
 | --- | --- |
 | Pi (`@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`) | Peer dependencies at `*`, supplied by the host. The package installs no runtime dependencies. |
 | Node.js >= 18 and `git` | `engines` declares 18 as the floor, and every repository operation is a git child process. |
-| `herdr` — optional | Not required: only `worktree_create` tries a Herdr workspace association, and it falls back to plain `git`. |
 | `gh`, authenticated (`gh auth login`) | `/issues` only. Without it the command stays registered, says once per session what is missing, and never opens. |
 | `codegraph` — optional | Keeps each checkout's index fresh: `codegraph init` when a checkout is created, and a background `codegraph sync` after edits and writes. Absent, both stay off for the whole session. |
 | Gentle Shell — recommended | Supplies the presence and transport records the deletion guard reads to see sessions other than this one. |
@@ -154,6 +153,24 @@ Removal is `git worktree remove <absolute path>`, with `--force` only when the
 caller asked for it. The branch is kept, and **no Herdr workspace is closed,
 opened or removed** on any path.
 
+### A warp waits for this session's own agent tasks
+
+A warp never lands while this session still has running or queued agent tasks.
+The `worktree_warp` tool refuses **before** it queues anything, and `/warp`
+gives the published counters a bounded chance to drain (`ODD_WORKTREE_WARP_BUSY_WAIT_MS`,
+60 s by default) before it refuses: the session stays where it is and the notice
+says how many tasks are running. The counters are read from Gentle Shell's
+presence header for this session, through the same bounded reader the deletion
+guard uses.
+
+That check is **best effort, and it does not see background jobs**:
+
+- Agents publish their task counters in the presence header; a heartbeat older
+  than 15 s is not evidence, and an absent or unreadable store blocks nothing.
+- `bash_background` and `monitor` jobs live in Gentle Shell's in-memory job
+  registry, which publishes nothing durable and is not exposed by the Pi host,
+  so no warp can observe them. Confirm a job finished before warping.
+
 ### `/issues` pins the repository
 
 The repository identity (`<host>/<owner>/<repo>`) is pinned when the list loads,
@@ -238,7 +255,7 @@ This package is the worktree / ODD / issues surface only: no customize panel, no
 plugin-tools toggles, no Herdr plugin management, and no worktree↔issue
 association. There is nothing to configure, and `/warp`, `/odd-list` and
 `/issues` are always on (the three `/codegraph-*` commands follow the CLI).
-Paths, branches and arguments reach `git`, `herdr` and `gh` as fixed argv arrays,
+Paths, branches and arguments reach `git` and `gh` as fixed argv arrays,
 never as a shell string.
 
 ## Tests

package/extensions/odd-worktree-tools.ts

@@ -14,8 +14,7 @@
 // worktree_warp. Create and close prompt for approval when the host offers
 // dialog UI; list never mutates anything; warp hands the move to /warp.
 //
-// Herdr is optional, never required: every Herdr call is attempted first and
-// falls back to plain git, so the package works in Pi alone.
+// Worktree creation and removal use git; no Herdr workspace is opened.
 //
 // The file is plain JavaScript with a .ts extension (// @ts-nocheck, no type
 // annotations), so the test copy-to-.mjs loading pattern keeps working under
@@ -69,54 +68,6 @@ function setWarpTuiLoader(loader) {
   warpTuiLoader = loader;
 }
 
-// The herdr binary honors the documented HERDR_BIN_PATH override (tests),
-// else `herdr` on PATH.
-//
-// lib/worktree-git.js `resolveHerdrBinary` is the SINGLE authority and its
-// answer is propagated verbatim, including its refusal: under the test harness
-// (GENTLE_WORKTREE_LIB_DIR, set only by the test loaders) a value that may be
-// the live binary is refused unless the CURRENT test opted in with
-// GENTLE_WORKTREE_ALLOW_LIVE_HERDR=1. A `catch {}` around that call used to
-// swallow the refusal and then re-apply an inherited HERDR_BIN_PATH here, which
-// handed a test process exactly the live binary the authority had just refused
-// (a real Herdr workspace, created from a test). No fallback in this file may
-// re-decide the binary: the only remaining branch is for a lib that is missing
-// entirely, and it fails closed under the harness.
-function herdrBinary() {
-  let git = null;
-  try {
-    git = libRequire("worktree-git.js");
-  } catch {
-    git = null;
-  }
-  if (git && typeof git.resolveHerdrBinary === "function") {
-    return git.resolveHerdrBinary(process.env);
-  }
-  const harness = process.env.GENTLE_WORKTREE_LIB_DIR;
-  if (typeof harness === "string" && harness.length > 0) {
-    throw new Error(
-      "refusing to run live herdr from a test harness: herdr binary cannot be resolved "
-      + "(lib/worktree-git.js is unavailable, so no binary is injected)",
-    );
-  }
-  const bin = process.env.HERDR_BIN_PATH;
-  if (typeof bin === "string" && bin.length > 0) return bin;
-  return "herdr";
-}
-
-// The texts the authority (and the missing-lib branch above) use to refuse.
-// Matching on text keeps the boundary between lib and extension small: a
-// refusal is a resolved STATE, not an error class shared across it.
-const HERDR_REFUSAL_PATTERN = /refusing to run live herdr|herdr binary is not injected/;
-
-function isHerdrRefusal(err) {
-  return !!(
-    err
-    && typeof err.message === "string"
-    && HERDR_REFUSAL_PATTERN.test(err.message)
-  );
-}
-
 function toolCwd(ctx) {
   if (ctx && typeof ctx.cwd === "string" && ctx.cwd.length > 0) return ctx.cwd;
   return process.cwd();
@@ -543,12 +494,6 @@ function withWorktreeCardRenderer(tool) {
   // Model text and visual cards are independent presentation layers. Keep
   // backend helpers unchanged so runtime callers retain their raw contract.
   //
-  // The same seam turns a herdr resolution REFUSAL into an error result: the
-  // guard's refusal (a test harness handing over a possible live binary, or a
-  // harness with no binary injected) says the resolution failed, not that the
-  // tool crashed. Letting it escape would be an uncaught throw out of a tool
-  // handler, so every refusal is answered with its own text and `isError`, and
-  // every other exception is re-thrown untouched.
   const execute = tool.execute;
   let format = null;
   try {
@@ -559,13 +504,7 @@ function withWorktreeCardRenderer(tool) {
   }
   if (typeof execute === "function") {
     tool.execute = async function (...args) {
-      let result;
-      try {
-        result = await execute.apply(this, args);
-      } catch (err) {
-        if (!isHerdrRefusal(err)) throw err;
-        result = errorResult(`${tool.name}: ${err.message}`, { tool: tool.name, herdrRefused: true });
-      }
+      const result = await execute.apply(this, args);
       if (!format) return result;
       try {
         return format(tool.name, result);
@@ -703,7 +642,7 @@ async function awaitPendingCreationSetups() {
   }
 }
 
-// Core of `worktree_create`: validation (S2, S3) then herdr-first creation
+// Core of `worktree_create`: validation (S2, S3) then git creation
 // with a git fallback. Exported for unit tests; the registered tool calls
 // it with the live Pi context. It only ever CREATES: the branch plus the
 // `changes` selection (S3/S4), and no issue or ODD association is verified,
@@ -711,15 +650,6 @@ async function awaitPendingCreationSetups() {
 async function executeWorktreeCreate(params, ctx, opts) {
   const git = libRequire("worktree-git.js");
   const registry = libRequire("worktree-registry.js");
-  // S53 git-only route (create-from-warp): the wizard creates a plain
-  // git checkout plus the registry row and nothing else — never a Herdr
-  // workspace (`herdr worktree create/open` is what materialized the
-  // stray Herdr worktree the user never asked for). The route reuses
-  // every validation and the registry machinery below; only the
-  // backends change. Subprocesses run through the async runner here so
-  // a hanging child aborts on its bound instead of freezing the
-  // interactive session on the main thread.
-  const gitOnly = !!(opts && opts.gitOnly === true);
   // `backgroundHooks` is the INTERACTIVE create's speed contract: the checkout
   // plus its registry row are all the warp needs, so the slow half of the hooks
   // (install, codegraph) is handed to a tracked background task instead of
@@ -1112,24 +1042,12 @@ async function executeWorktreeCreate(params, ctx, opts) {
   // EXISTING branch with `git worktree add <target> <branch>` — no `-b`,
   // no base, the ref never created, rewritten or deleted — and the result
   // reports `branchCreated: false` plus a warning naming the adopted
-  // branch. Herdr's `worktree create` cannot adopt an existing branch, so
-  // the adopt case goes through git and then associates the Herdr
-  // workspace BEST-EFFORT via `herdr worktree open --path <path>
-  // --cwd <root>`; the checkout succeeding never depends on herdr.
-  // When the ref does not exist, creation keeps the herdr-first path
-  // with a `git worktree add -b` fallback and reports `branchCreated:
-  // true`. Fixed argv only, values as separate elements (herdr rejects
-  // --flag=value). Never --focus, never --trust-repository: trusting a
-  // repository is a human decision these tools never take. The base is
-  // LOCAL MAIN (S2), resolved in (d1) before anything was written: a session
-  // working inside a linked worktree can never seed the new branch with its
-  // own unmerged commits, and a repository without a local `main` was already
-  // refused there instead of falling back to the invoking HEAD.
+  // branch. New branches start at local main; existing branches are adopted
+  // unchanged. Both tool and panel creation use git only.
   const base = baseInfo !== null ? baseInfo.commit : null;
   let createdBy = null;
   let createError = null;
   let branchCreated = null;
-  let herdrAssociated = null;
   const adoptWarnings = [];
   if (branchExists) {
     // Adopt: check out the existing branch at the fresh path. No `-b`
@@ -1142,45 +1060,9 @@ async function executeWorktreeCreate(params, ctx, opts) {
       adoptWarnings.push(
         `adopted existing branch '${branch}' at ${target}: the worktree checks out that branch as-is, the branch ref was left untouched`,
       );
-      // Best-effort Herdr workspace association: reported, never fatal.
-      // Skipped on the git-only route: that checkout is git plus the
-      // registry row by design, so no association is expected.
-      if (!gitOnly) {
-      try {
-        const opened = await runGit(herdrBinary(), git.herdrArgv("open", { cwd: repo.root, path: target }), {
-          cwd: repo.root,
-          timeoutMs: 60000,
-        });
-        herdrAssociated = opened.status === 0;
-      } catch (err) {
-        herdrAssociated = false;
-      }
-      if (herdrAssociated !== true) {
-        adoptWarnings.push(
-          `herdr workspace association failed for ${target} ('herdr worktree open' did not succeed): the checkout itself is fine, associate it by hand when needed`,
-        );
-      }
-      }
     } else {
       createError = ((adopted.stderr || adopted.error || "unknown error") + "").trim();
     }
-  } else {
-  // The git-only route skips the herdr-first attempt outright: no
-  // `herdr worktree create` runs, so no Herdr workspace is ever
-  // materialized from the wizard. The tool path keeps herdr-first
-  // with the git fallback below, byte-identical.
-  let herdrRes = null;
-  if (!gitOnly) {
-  const createParams = { cwd: repo.root, branch, path: target };
-  if (base) createParams.base = base;
-  herdrRes = await runGit(herdrBinary(), git.herdrArgv("create", createParams), {
-    cwd: repo.root,
-    timeoutMs: 120000,
-  });
-  }
-  if (herdrRes !== null && herdrRes.status === 0) {
-    createdBy = "herdr";
-    branchCreated = true;
   } else {
     const fallbackArgv = ["worktree", "add", "-b", branch, target];
     if (base) fallbackArgv.push(base);
@@ -1212,10 +1094,9 @@ async function executeWorktreeCreate(params, ctx, opts) {
       }
     }
   }
-  }
   if (!createdBy) {
     return errorResult(
-      `failed to create worktree for branch '${branch}': ${createError || "herdr and git both failed"}`,
+      `failed to create worktree for branch '${branch}': ${createError || "git failed"}`,
       { branch, path: target, pruned: prunedStale },
     );
   }
@@ -1519,11 +1400,8 @@ async function executeWorktreeCreate(params, ctx, opts) {
   // S6: the ONE CodeGraph fact of this create, read from the hooks that just
   // ran (never re-run, never inferred).
   const codegraph = codegraphStatus(hooks);
-  // S20 adoption reporting: whether the branch was created or adopted,
-  // and (adopt case only) whether the best-effort Herdr workspace
-  // association happened. The checkout succeeding never depends on herdr.
+  // Report whether the branch was created or adopted.
   const adoptionDetails = { branchCreated };
-  if (herdrAssociated !== null) adoptionDetails.herdrAssociated = herdrAssociated;
   // (l) T41/S50 changes registration: register the checkout just
   // created on the CURRENT session through gentle-shell's
   // `session_worktree_register` host tool, but ONLY when that tool is
@@ -3787,6 +3665,17 @@ async function executeWorktreeWarpTool(params, ctx, opts) {
   // `fromName`/`name`/`path`/`branch`), so the card falls back to that line
   // instead of painting a move that has not happened. The one visible "moved"
   // card comes from the switched-to session once the move is real.
+  // S4: this session's own background work is a refusal, not a queue. The
+  // command that performs the move waits for idle — and a session with running
+  // agent tasks IS idle — so queueing here would move the session out from
+  // under work that is still running. Nothing is queued when this refuses.
+  const toolBusy = await warpSessionActivity(ctx);
+  if (toolBusy && toolBusy.busy === true) {
+    return errorResult(`worktree warp: ${warpBusyText(toolBusy)}`, {
+      tool: "worktree_warp", name: displayName, path: targetCwd, branch: displayBranch,
+      kind: resolved.kind, busy: true,
+    });
+  }
   const handoffDispatched = dispatchWarpHandoff(prepareWarpHandoff({
     name: displayName,
     target: targetCwd,
@@ -4203,6 +4092,62 @@ async function sessionManagerClassFor(ctx) {
   return null;
 }
 
+// S4: THIS session's own agent-task counters, read from the presence store the
+// close guard already consumes (lib/worktree-warp-busy.js). Best effort: an
+// absent module or store answers null and blocks nothing. Background jobs are
+// NOT covered — gentle-shell keeps them in memory and publishes no durable
+// evidence — so nothing here claims to see one.
+async function warpSessionActivity(ctx) {
+  let lib = null;
+  try {
+    lib = libRequire("worktree-warp-busy.js");
+  } catch {
+    return null;
+  }
+  if (!lib || typeof lib.sessionActivity !== "function") return null;
+  const sessionId = closeSessionString(ctx, "getSessionId");
+  try {
+    return await lib.sessionActivity({ sessionId });
+  } catch {
+    return null;
+  }
+}
+
+// The one refusal sentence, from the same module that produced the counters. A
+// missing module falls back to a shorter sentence that still names agent tasks
+// only.
+function warpBusyText(activity) {
+  try {
+    const lib = libRequire("worktree-warp-busy.js");
+    if (lib && typeof lib.busyText === "function") return lib.busyText(activity);
+  } catch {
+    // fall through to the fixed sentence
+  }
+  return "this session still has running agent tasks: the warp waits for them to finish (as of the last published heartbeat); background jobs are not visible here, so confirm they finished too";
+}
+
+// The COMMAND front's bounded wait: a warp lands after this turn settles, so it
+// gives the published counters a chance to drain before it refuses. Null when
+// the module or the session identity is unavailable (best effort, blocks
+// nothing).
+async function warpWaitForIdleSession(ctx) {
+  let lib = null;
+  try {
+    lib = libRequire("worktree-warp-busy.js");
+  } catch {
+    return null;
+  }
+  if (!lib || typeof lib.waitForSessionActivity !== "function") return null;
+  const sessionId = closeSessionString(ctx, "getSessionId");
+  try {
+    // The budget travels through the environment so a session can bound its own
+    // wait (ODD_WORKTREE_WARP_BUSY_WAIT_MS); the default keeps a warp short.
+    return await lib.waitForSessionActivity({ sessionId, env: process.env });
+  } catch {
+    return null;
+  }
+}
+
 function warpFail(text, details) {
   return { text, details: details || {}, isError: true };
 }
@@ -4244,6 +4189,16 @@ function warpNoticeText(targetCwd, branch) {
   return `Worktree warp: now in ${to} (branch '${cleanBranch}').`;
 }
 
+// S1 (warp-empty-session): what an EMPTY session's warp reports. It names
+// WHERE the session now is and never a move: nothing was carried, so the
+// `moved:`/`to:` compact — and the card that accompanies it — would claim a
+// transition that did not happen.
+function warpEmptyText(name, targetCwd) {
+  const toName = warpClean(name, 'worktree');
+  const to = warpClean(targetCwd, '(unknown checkout)');
+  return `worktree warp: ${toName} (empty session, nothing to carry; now at ${to})`;
+}
+
 // Deepest live checkout containing a cwd, by resolved identity — the one
 // rule the listing, the selector title and the already-there check share.
 // `extraIds` lets the already-there check keep its target-cwd candidate
@@ -4535,6 +4490,17 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
     );
   }
   await ctx.waitForIdle();
+  // S4: a session with running agent tasks is IDLE for the host, so the wait
+  // above does not wait for that work. This front gives the published counters
+  // a bounded chance to drain and then refuses instead of moving the session
+  // out from under a task that is still running. A store that is absent or
+  // unreadable blocks nothing.
+  const busyWait = await warpWaitForIdleSession(ctx);
+  if (busyWait && busyWait.activity && busyWait.activity.busy === true) {
+    return warpFail(`worktree warp: ${warpBusyText(busyWait.activity)}`, {
+      name, alreadyThere: false, cancelled: false, busy: true,
+    });
+  }
   const fromCwd = typeof ctx.cwd === "string" && ctx.cwd.length > 0 ? ctx.cwd : process.cwd();
   // S21: the same awaited preflight reads as the tool, so a slow repository
   // never freezes the session that is being moved.
@@ -4813,6 +4779,18 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
     }
     if (handoff) await warpConfirm(r, warpHandoffNotice, true);
   };
+  // S1/S3 (warp-empty-session): the switched-to session of an EMPTY warp is
+  // told nothing — no card, and no handoff continuation either, because the
+  // session carries no task yet (the already-there no-op answers a handoff
+  // with text only, for the same reason). The status line stays: it says
+  // WHERE the session is, not what it carried.
+  const warpSilentWithSession = async (r) => {
+    try {
+      r.ui.setStatus("worktree", `${displayName} (${targetCwd})`);
+    } catch {
+      // Status is cosmetic; the silence is the point.
+    }
+  };
   // S43 records. The POINT of a session is its ACTIVE branch (the live
   // leaf's parentId path, never all append-only entries) filtered to
   // entries that are NOT our own bookkeeping — the custom marker, the
@@ -4855,6 +4833,16 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
   const currentPoint = warpSessions.sessionPoint(
     currentEntriesList, typeof currentLeaf === "string" ? currentLeaf : undefined,
   );
+  // S1/S5 (warp-empty-session): an EMPTY session is one whose active branch
+  // carries no conversation — no `message` entry with role user or assistant
+  // outside the warp bookkeeping, so a rename, the session-worktree
+  // registration or a transition marker never counts as content. It has
+  // nothing to carry, so its warp changes PATH instead of moving work: never
+  // a fork (the host refuses a conversation-less source), never a card, never
+  // a "moved:" claim.
+  const sessionEmpty = !warpSessions.hasConversation(
+    currentEntriesList, typeof currentLeaf === "string" ? currentLeaf : undefined,
+  );
   const warpFileOpen = options && typeof options.warpSessionFileOpen === "function"
     ? options.warpSessionFileOpen
     : undefined;
@@ -5023,7 +5011,13 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
           // cached fingerprint. An unreadable destination never resumes.
           // Never throws: any comparison failure reads as "fork".
           const freshDestPoint = warpFreshPoint(recorded.sessionFile);
-          if (freshDestPoint !== null && warpSessions.samePoint(currentPoint, freshDestPoint)) {
+          // An empty source has no point to compare (its own point is empty
+          // by definition), so it RESUMES the destination session whenever
+          // that file is readable — the conversation it already holds (S4)
+          // or its own emptiness — instead of allocating a copy of nothing. A
+          // session with conversation keeps the same-point gate.
+          if (freshDestPoint !== null
+            && (sessionEmpty || warpSessions.samePoint(currentPoint, freshDestPoint))) {
             recordedSession = recorded;
             recordedFreshPoint = freshDestPoint;
           }
@@ -5039,7 +5033,9 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
   if (recordedSessionFile !== null) {
     let resumed;
     try {
-      resumed = await ctx.switchSession(recordedSessionFile, { withSession: warpResumeWithSession });
+      resumed = await ctx.switchSession(recordedSessionFile, {
+        withSession: sessionEmpty ? warpSilentWithSession : warpResumeWithSession,
+      });
     } catch (err) {
       return failAfterCopy(
         `worktree warp: the session switch to ${targetCwd} failed: ${(err && err.message) || err}; the recorded warp session was kept`,
@@ -5066,8 +5062,12 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
     );
     emitOsc7(options.oscStream || process.stdout, targetCwd);
     return {
-      text: moveText,
-      details: { name: displayName, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false, ...handoffCopyDetails() },
+      text: sessionEmpty ? warpEmptyText(name, targetCwd) : moveText,
+      details: {
+        name: displayName, path: targetCwd, branch: displayBranch, kind: resolved.kind,
+        alreadyThere: false, cancelled: false,
+        ...(sessionEmpty ? { emptySession: true } : {}), ...handoffCopyDetails(),
+      },
     };
   }
   const sm = ctx.sessionManager || {};
@@ -5082,7 +5082,11 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
   const leaf = typeof sm.getLeafId === "function" ? safe(() => sm.getLeafId()) : null;
   const sessionDir = typeof sm.getSessionDir === "function" ? safe(() => sm.getSessionDir()) : undefined;
   let carried = [];
-  if (!warpSourceUsable(file, warpFileOpen)) {
+  // S1: an empty session is allowed through without a persisted file or
+  // in-memory entries — the refusal below exists because a session with
+  // nothing to carry had nothing to warp FOR, and the empty path now changes
+  // its path instead of carrying anything.
+  if (!sessionEmpty && !warpSourceUsable(file, warpFileOpen)) {
     const entries = typeof sm.getEntries === "function" ? safe(() => sm.getEntries()) : undefined;
     carried = Array.isArray(entries) ? entries : [];
     if (carried.length === 0) {
@@ -5093,6 +5097,82 @@ async function executeWorktreeWarp(rawName, ctx, opts) {
     }
   }
   const SM = options.sessionManagerClass || await sessionManagerClassFor(ctx);
+  // S3 (warp-empty-session): an empty session changes PATH. There is nothing
+  // to carry, so nothing is forked (`forkFrom` refuses a conversation-less
+  // source anyway) and the in-place move the host would need does not exist —
+  // `switchSession(file)` is the only mount, and a session's cwd comes from
+  // its own header. So the equivalent is used: a FRESH session allocated at
+  // the target cwd through the same create/switch machinery the non-persisted
+  // path uses, with only its header written (`wx`, never clobbering) so the
+  // mount and the record both have a real file. The switch is silent: no
+  // card, no transition entry, no rename — bookkeeping this flow did not earn.
+  if (sessionEmpty) {
+    if (!SM || typeof SM.create !== "function") {
+      return failAfterCopy(
+        "worktree warp is unavailable here: the host SessionManager has no create",
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false },
+      );
+    }
+    let emptyFile = null;
+    try {
+      const allocated = SM.create(targetCwd, sessionDir);
+      const allocatedFile = allocated && typeof allocated.getSessionFile === "function" ? allocated.getSessionFile() : undefined;
+      if (typeof allocatedFile !== "string" || allocatedFile.length === 0) {
+        throw new Error("the host allocated no session file for the target");
+      }
+      const header = typeof allocated.getHeader === "function" ? allocated.getHeader() : null;
+      if (!header) throw new Error("the allocated session has no header");
+      // The file is the header alone: there is no entry to carry, and a file
+      // naming the target cwd is what makes the mount and the fresh point
+      // real. `wx` never clobbers an existing file.
+      fs.writeFileSync(allocatedFile, `${JSON.stringify(header)}\n`, { flag: "wx" });
+      emptyFile = allocatedFile;
+    } catch (err) {
+      return failAfterCopy(
+        `worktree warp: could not change this session's path to ${targetCwd}: ${(err && err.message) || err}`,
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false },
+      );
+    }
+    let changed;
+    try {
+      changed = await ctx.switchSession(emptyFile, { withSession: warpSilentWithSession });
+    } catch (err) {
+      return failAfterCopy(
+        `worktree warp: the session switch to ${targetCwd} failed: ${(err && err.message) || err}; the new session file was kept at ${emptyFile}`,
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: false },
+      );
+    }
+    if (changed && changed.cancelled === true) {
+      try {
+        fs.unlinkSync(emptyFile);
+      } catch {
+        // Best effort: the report below is what matters.
+      }
+      return failAfterCopy(
+        `worktree warp: ${name} cancelled (the session stays in ${fromCwd}; the new session file was removed)`,
+        { name, path: targetCwd, branch: displayBranch, kind: resolved.kind, alreadyThere: false, cancelled: true },
+      );
+    }
+    // Recording is unchanged: both sides are recorded at their own points, so
+    // a later warp finds this destination session again (S2: warping back
+    // from an empty session is the same empty case).
+    try {
+      recordBothSides(
+        targetCwd, emptyFile, warpFreshPoint(emptyFile),
+        sourceIdentity, currentFile, currentPoint,
+      );
+    } catch {
+      // Best effort: the warp already switched.
+    }
+    emitOsc7(options.oscStream || process.stdout, targetCwd);
+    return {
+      text: warpEmptyText(name, targetCwd),
+      details: {
+        name: displayName, path: targetCwd, branch: displayBranch, kind: resolved.kind,
+        alreadyThere: false, cancelled: false, emptySession: true, ...handoffCopyDetails(),
+      },
+    };
+  }
   if (!SM || typeof SM.forkFrom !== "function") {
     return failAfterCopy(
       "worktree warp is unavailable here: the host SessionManager has no forkFrom",
@@ -5851,8 +5931,8 @@ async function warpCreateAndEnter(ctx, git, notify) {
     return { closed: true, created: false, cancelled: true };
   }
   createParams.changes = pending.copy ? 'all' : 'none';
-  // S53: the git-only route — a plain git checkout plus the registry row,
-  // never a Herdr workspace — reusing the same creation path (validations,
+  // S53: the panel's create — a plain git checkout plus the registry row —
+  // reusing the same creation path (validations,
   // refusals, registration), which never prompts. The layout is
   // principal-anchored (S56): the new checkout lands beside the PRINCIPAL
   // checkout even when the panel runs inside a linked worktree, while the
@@ -5865,7 +5945,6 @@ async function warpCreateAndEnter(ctx, git, notify) {
   // can move, or the human would switch into a checkout that is missing the
   // work they just asked to carry.
   const created = await executeWorktreeCreate(createParams, ctx, {
-    gitOnly: true,
     principalLayout: true,
     backgroundHooks: true,
     ...(typeof notify === 'function' ? { notify } : {}),