pum-agent 0.2.20-beta.1 → 0.2.21-beta.1

package/README.md

@@ -38,7 +38,14 @@ empty prompt to see every control.
 
 </details>
 
-Both are real OpenTUI renders, not mockups — `bun run scripts/capture-screenshots.tsx`
+<details>
+<summary><strong>Controls panel</strong></summary>
+
+![PUM's controls panel, showing prompt, agent, session, command, and application shortcuts](docs/images/pum-controls.svg)
+
+</details>
+
+These are real OpenTUI renders, not mockups. `bun run scripts/capture-screenshots.tsx`
 drives the actual TUI and converts the captured cells to SVG.
 
 ## What it does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pum-agent",
-  "version": "0.2.20-beta.1",
+  "version": "0.2.21-beta.1",
   "description": "A compact terminal coding agent powered by pi and OpenTUI.",
   "license": "MIT",
   "type": "module",

package/src/app.tsx

@@ -626,6 +626,7 @@ export function App({
   sandboxWarningSource,
   forcedSandboxMode,
   forcedCheckPaths = [],
+  initialRelocation,
   initialCwd,
   userBashOperations,
 }: {
@@ -666,6 +667,8 @@ export function App({
   /** Process-local sandbox floor that does not overwrite persisted user settings. */
   forcedSandboxMode?: NonNullable<PumSettings["sandboxMode"]>;
   forcedCheckPaths?: readonly string[];
+  /** Relocation created before the TUI mounted, such as a `pum worktree` launch. */
+  initialRelocation?: RelocationRecord;
   /** Directory the session starts in. Defaults to the process working directory. */
   initialCwd?: string;
   /** User commands bypass Check mode but use this native sandbox execution path. */
@@ -1990,7 +1993,7 @@ export function App({
   }, [activeAgent?.id, activeAgent?.status, activeAgent?.runStartedAt, visibleBusy]);
 
   const [relocation, setRelocation] = useState(
-    () => loadRelocation(initialSession.sessionFile),
+    () => loadRelocation(initialSession.sessionFile) ?? initialRelocation ?? null,
   );
   const relocationRef = useRef(relocation);
   relocationRef.current = relocation;
@@ -2135,7 +2138,6 @@ export function App({
     if (!record || record.location !== "worktree") return;
     if (restoredRelocationRef.current === record.id) return;
     restoredRelocationRef.current = record.id;
-    if (pathIdentity(cwdRef.current) === pathIdentity(record.worktreePath)) return;
     void (async () => {
       const trusted = relocationPathsTrusted(record, {
         worktreeExists: existsSync(record.worktreePath),
@@ -2143,16 +2145,42 @@ export function App({
         sourceRoot: record.sourceRoot,
       });
       if (!trusted) {
+        const alreadyInWorktree = pathIdentity(cwdRef.current) === pathIdentity(record.worktreePath);
+        if (alreadyInWorktree && onRelocate) {
+          const moved = await onRelocate(record.sourceRoot).catch(() => null);
+          if (moved) {
+            applyRelocation({
+              ...record,
+              generation: record.generation + 1,
+              location: "source",
+              updatedAt: Date.now(),
+            });
+            appendMainLine({
+              kind: "text",
+              role: "error",
+              text: `worktree ${record.name} no longer matches ${record.branch}; returned to ${record.sourceRoot}`,
+            });
+            return;
+          }
+        }
         relocationRef.current = null;
         setRelocation(null);
         saveRelocation(session.sessionFile, null);
         appendMainLine({
           kind: "text",
           role: "error",
-          text: `worktree ${record.name} no longer matches ${record.branch}; staying in ${record.sourceRoot}`,
+          text: alreadyInWorktree
+            ? `worktree ${record.name} no longer matches ${record.branch}; its relocation record was removed`
+            : `worktree ${record.name} no longer matches ${record.branch}; staying in ${record.sourceRoot}`,
         });
         return;
       }
+      // A CLI worktree launch resumes in the recorded checkout already. It
+      // still needs trust validation and the source root in the live roots.
+      if (pathIdentity(cwdRef.current) === pathIdentity(record.worktreePath)) {
+        applyRelocation(record);
+        return;
+      }
       if (!onRelocate) return;
       const moved = await onRelocate(record.worktreePath).catch(() => null);
       if (moved) applyRelocation(record);

package/src/index.tsx

@@ -70,7 +70,7 @@ if (result.kind === "help") {
     process.stdout.write(`${worktreeStartMessage(started)}\n`);
     process.chdir(started.worktree.path);
     const { start } = await import("./main");
-    await start(result.options, { worktreeSourceRoot: started.sourceRoot });
+    await start(result.options, { worktreeStart: started });
   } catch (error) {
     process.stderr.write(formatCliError(errorMessage(error)));
     process.exitCode = 1;

package/src/main.tsx

@@ -69,14 +69,16 @@ import {
   ManagedShellLifecycleController,
   lifecycleEventFromSnapshot,
 } from "./shells/lifecycle";
+import { initializeWorktreeLaunchRelocation, type RelocationRecord } from "./relocation";
+import type { WorktreeStart } from "./worktree-start";
 
 /**
  * Process-local launch context. These are facts about how this process was
  * started, never user settings, so nothing here reaches pum.json.
  */
 export type LaunchContext = {
-  /** Source repository of a `pum worktree` launch, authorized as a writable root. */
-  worktreeSourceRoot?: string;
+  /** Generated checkout and source repository from a `pum worktree` launch. */
+  worktreeStart?: WorktreeStart;
 };
 
 export async function start(
@@ -98,7 +100,7 @@ export async function start(
   // learn about it.
   const forcedCheckPaths = [
     ...(outerSandbox ? outerSandboxAdditionalRoots(outerSandbox, process.cwd()) : []),
-    ...(context.worktreeSourceRoot ? [context.worktreeSourceRoot] : []),
+    ...(context.worktreeStart ? [context.worktreeStart.sourceRoot] : []),
   ];
   const sandboxController = new SandboxController({
     mode: outerSandbox ? "off" : settings.sandboxMode ?? "auto",
@@ -314,6 +316,15 @@ export async function start(
   statsManager.bindMainSession(sessionRuntime.session);
   if (sessionRuntime.modelFallbackMessage) console.error(sessionRuntime.modelFallbackMessage);
 
+  // `pum worktree` creates the checkout before the session exists. Persist it
+  // now so return and resume use the ordinary relocation path.
+  const initialRelocation: RelocationRecord | undefined = context.worktreeStart
+    ? initializeWorktreeLaunchRelocation(
+      sessionRuntime.session.sessionManager.getSessionFile(),
+      context.worktreeStart,
+    )
+    : undefined;
+
   const renderer = await createCliRenderer({ exitOnCtrlC: false });
   const terminalTitle = new TerminalTitleController((title) => renderer.setTerminalTitle(title));
   const selectionClipboard = installSelectionClipboard(renderer);
@@ -431,6 +442,7 @@ export async function start(
       }}
       forcedSandboxMode={outerSandbox ? "off" : undefined}
       forcedCheckPaths={forcedCheckPaths}
+      initialRelocation={initialRelocation}
       sandboxWarningSource={sandboxController}
       loginRequired={loginRequired}
       triggerManager={triggerManager}

package/src/relocation.ts

@@ -1,5 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { companionFileFor, readCompanion, writeCompanion } from "./session-companion";
 import { isPathInsideOrSame, pathIdentity } from "./platform";
+import type { WorktreeStart } from "./worktree-start";
 
 /**
  * Where a relocated session is currently running, and what move it still owes.
@@ -76,6 +78,34 @@ export function saveRelocation(
   writeCompanion(sessionFile, RELOCATION_SUFFIX, record);
 }
 
+/**
+ * Persist the generated worktree that a `pum worktree` CLI launch entered.
+ *
+ * The CLI creates the checkout before the session exists. This bridges that
+ * launch fact into the same companion record used by in-session start/return.
+ */
+export function initializeWorktreeLaunchRelocation(
+  sessionFile: string | undefined,
+  start: WorktreeStart,
+  now = Date.now(),
+): RelocationRecord {
+  const record: RelocationRecord = {
+    id: `reloc-${randomUUID().slice(0, 8)}`,
+    generation: 1,
+    sourceRoot: start.sourceRoot,
+    worktreePath: start.worktree.path,
+    name: start.worktree.name,
+    branch: start.worktree.branch,
+    baseBranch: start.worktree.baseBranch,
+    baseCommit: start.worktree.baseCommit,
+    location: "worktree",
+    createdAt: now,
+    updatedAt: now,
+  };
+  saveRelocation(sessionFile, record);
+  return record;
+}
+
 export type RelocationGuardInput = {
   relocation: RelocationRecord | null;
   /** True while the main agent is working. A move mid-turn would change its roots. */