Worktree V2 Phase 4: isolated conversation forks

AGENTS.md

@@ -51,6 +51,15 @@ Each package has its own agent context file — read it before modifying that pa
 - Commits: Conventional Commits (`feat(scope): summary`). Commit after every logical unit of work.
 - Deferred work: any work deferred during planning, implementation, verification, or testing must be filed as a GitHub issue immediately using the `.github/ISSUE_TEMPLATE/deferred_work.yml` template. Do not leave deferrals only in code comments, chat, or memory.
 
+## Credentials and E2E provider UAT
+
+**This environment is credentialed by default.** Provider-requiring E2E tests run here — never assume "no credentials", never defer UAT to a later issue, and never wire a fake provider seam without asking the user first.
+
+- **Primary credential: codex OAuth.** The app is already authenticated against the codex harness (credentials in `dotfiles/pi/.pi/agent/auth.json`); the `chatgpt-plus` connection is reused without entering a key.
+- **Fallback chain: root `.env`.** `KATA_E2E_AGENT_PROVIDER[_NN]` + `KATA_E2E_AGENT_MODEL[_NN]` select the provider; the matching `KATA_*_API_KEY` supplies the key (`openai-codex` → `KATA_OPENAI_API_KEY`, `opencode-go` → `KATA_OPENCODE_GO_API_KEY`, `openrouter` → `KATA_OPENROUTER_API_KEY`, `deepseek` → `KATA_DEEPSEEK_API_KEY`, `anthropic` → `KATA_ANTHROPIC_API_KEY` — avoid, expensive).
+- The agent E2E specs (`@agent`, `@worktree-v2 fork`, `@worktree-v2 handoff`) walk the whole chain via `runWithAgentProviderFallback` (`e2e/src/flows/agentChat.ts`) and only fail after every option is exhausted, with each attempt logged and the aggregated failure naming every option.
+- Before deferring any UAT tier or claiming credentials are unavailable: check the chain above and **ask the user**. Deterministic adapters (`@kata-sh/shared/agent/testing`) are test doubles only — never import them from production code, and never add `KATA_*_DETERMINISTIC_ADAPTER`-style env seams to production paths.
+
 ## Active context
 
 - **Complete Kata brand transition** is complete. Canonical identity: `@kata-sh/*` packages, `KATA_*` env vars, `~/.kata-agents`, `kataagents://`, `sh.kata.agents`, and `agents.kata.sh`. See `./docs/specs/archive/2026-06-22-complete-kata-brand-transition-design.md` and the verify report `./docs/specs/archive/2026-06-23-complete-kata-brand-transition-verify-report.md`. Verify passed 2026-06-23 (all 12 ACs); fixes included a broken `kata-agent.svg` tool icon, Craft-named `kata-logos` assets, dead `CraftAppIcon` code, a `copy-assets.ts` stale-file hygiene fix, and GitHub org ref reconciliation.

apps/electron/resources/release-notes/next.md

@@ -8,6 +8,7 @@ This file accumulates release notes for the next unreleased version. PRs that ad
 - **Simplified managed worktree settings** — Worktrees settings now uses a compact delete-only list for active checkouts, labels the location **Worktree root**, and defaults **Automatically delete old worktrees** to off. The configurable **Auto-delete limit** still uses snapshot-first pruning so older worktrees remain recoverable on the owning server ([#41](https://github.com/gannonh/kata-agents/issues/41)).
 - **Named managed worktrees and server-owned roots** — With Worktree V2 enabled, new worktrees accept a human-readable name that is normalized to lowercase kebab-case for the exact branch suffix and display name, while the Worktrees settings page configures a server-local materialization root without moving existing checkouts ([#40](https://github.com/gannonh/kata-agents/issues/40)).
 - **Conflict-safe checkout handoff** — Sessions whose provider supports safe execution-CWD rebinding can move between the current checkout and a managed worktree: **Hand off to new worktree**, **Hand off to current checkout**, and **Hand back to worktree** preview the exact source/destination state, typed blockers, and cleanup before confirming; interrupted handoffs surface a snapshot-backed recovery state with a **Recover** action that rolls back exactly the journaled steps. The transcript and provider identity never move ([#42](https://github.com/gannonh/kata-agents/issues/42)).
+- **Isolated conversation forks** — The Branch action now offers **New isolated worktree** next to the default **Shared worktree** for sessions whose provider advertises a strict cross-CWD native fork: the fork previews the source conversation head, branch, HEAD, owners, and destination identity, takes an editable name (`kata-agent/<name>` branch), and commits a child session that copies the conversation through the current head into its own managed worktree and runtime while the source stays untouched. Provider identity stays **Pending** until the child's first message establishes the native fork; a failed establishment leaves one persisted message in a visible retryable state and never duplicates it ([#43](https://github.com/gannonh/kata-agents/issues/43)).
 ## Improvements
 
 ## Bug Fixes

apps/electron/src/renderer/App.tsx

@@ -22,6 +22,7 @@ import { ResetConfirmationDialog } from '@/components/ResetConfirmationDialog'
 import { DeleteSessionDialog } from '@/components/app-shell/DeleteSessionDialog'
 import { resolveDeleteConfirmation } from '@/components/app-shell/worktree-removal'
 import { FEATURE_FLAGS } from '@kata-sh/shared/feature-flags'
+import { WORKTREE_FORK_ERROR_CODE } from '@kata-sh/shared/protocol'
 import { SplashScreen } from '@/components/SplashScreen'
 import { TooltipProvider } from '@kata-sh/ui'
 import { FocusProvider } from '@/context/FocusContext'
@@ -54,6 +55,8 @@ import {
   loadedSessionsAtom,
   forceSessionMessagesReloadAtom,
   backgroundTasksAtomFamily,
+  forkRetryAtomFamily,
+  findPendingForkRetryMessage,
   extractSessionMeta,
   windowWorkspaceIdAtom,
   type SessionMeta,
@@ -500,6 +503,61 @@ export default function App() {
     }
   }, [clearStreamingState, replaceLoadedSession, syncSessionOptionsFromSession, reconcilePermissionModeState, store])
 
+  /**
+   * Poll a fork child's session DTO until its pending fork intent retires
+   * (first-Send establishment succeeded) or the attempts are exhausted. The
+   * send RPC resolves before the establish flow runs, so the renderer cannot
+   * learn establishment success from the RPC alone; a refresh also retires the
+   * PENDING provider identity badge and any retry banner (Phase 4).
+   */
+  const refreshUntilForkEstablished = React.useCallback(
+    (sessionId: string) => {
+      void (async () => {
+        for (const delay of [1500, 3000, 6000]) {
+          await new Promise((resolve) => setTimeout(resolve, delay))
+          const result = await refreshSessionFromServer(sessionId)
+          if (result === 'failed') continue
+          const session = store.get(sessionAtomFamily(sessionId))
+          if (!session?.forkPending) {
+            store.set(forkRetryAtomFamily(sessionId), null)
+            return
+          }
+        }
+      })()
+    },
+    [refreshSessionFromServer, store],
+  )
+
+  /**
+   * Retry a failed isolated-fork establishment: re-send the SAME persisted
+   * user message via existingMessageId (the server reuses the persisted fork
+   * idempotency key, so neither the provider artifact nor the message is ever
+   * duplicated). Clears the banner immediately; a re-failure re-surfaces it
+   * via the typed error event.
+   */
+  const handleRetryForkSend = React.useCallback(
+    async (sessionId: string): Promise<boolean> => {
+      const retry = store.get(forkRetryAtomFamily(sessionId))
+      if (!retry) return false
+      store.set(forkRetryAtomFamily(sessionId), null)
+      try {
+        await window.electronAPI.sendMessage(sessionId, retry.text, undefined, undefined, {
+          existingMessageId: retry.messageId,
+        })
+      } catch (error) {
+        store.set(forkRetryAtomFamily(sessionId), {
+          ...retry,
+          error: error instanceof Error ? error.message : String(error),
+        })
+        return false
+      }
+      refreshUntilForkEstablished(sessionId)
+      return true
+    },
+    [store, refreshUntilForkEstablished],
+  )
+
+
   const loadSessionsFromServer = useCallback(async () => {
     setSessionLoadError(null)
 
@@ -963,6 +1021,20 @@ export default function App() {
         return
       }
 
+      // Phase 4: a typed retryable isolated-fork establishment failure (the
+      // child stays pending with its single persisted user message). Surface
+      // the chat-input retry banner using the durable post-branch user
+      // message so the retry reuses the persisted message.
+      if (event.type === 'error' && event.code === WORKTREE_FORK_ERROR_CODE) {
+        const retryMessage = findPendingForkRetryMessage(store.get(sessionAtomFamily(sessionId)))
+        if (retryMessage) {
+          store.set(forkRetryAtomFamily(sessionId), {
+            ...retryMessage,
+            error: event.error,
+          })
+        }
+      }
+
       const agentEvent = event as unknown as AgentEvent
 
       // Track activity for stale session watchdog
@@ -1473,6 +1545,12 @@ export default function App() {
         badges: badges.length > 0 ? badges : undefined,
         optimisticMessageId: userMessage.id,
       })
+      // First send on a pending fork child: poll until the establish flow
+      // retires forkPending so the PENDING badge clears without a manual
+      // refresh. The RPC resolves before establishment runs.
+      if (store.get(sessionAtomFamily(sessionId))?.forkPending) {
+        refreshUntilForkEstablished(sessionId)
+      }
       // Resolved once the message is persisted/accepted (pre-persist failures
       // reject and land in the catch below). Signals successful submission so
       // callers like the Changes feedback flow can safely clear local state.
@@ -1493,7 +1571,7 @@ export default function App() {
       }))
       return false
     }
-  }, [sessionOptions, updateSessionById, skills, sources, windowWorkspaceId])
+  }, [sessionOptions, updateSessionById, skills, sources, windowWorkspaceId, refreshUntilForkEstablished, store])
 
   /**
    * Unified handler for all session option changes.
@@ -1930,6 +2008,7 @@ export default function App() {
     // Session callbacks
     onCreateSession: handleCreateSession,
     onSendMessage: handleSendMessage,
+    onRetryForkSend: handleRetryForkSend,
     onRenameSession: handleRenameSession,
     onFlagSession: handleFlagSession,
     onUnflagSession: handleUnflagSession,
@@ -1977,6 +2056,7 @@ export default function App() {
     updateDefaultThinkingLevel,
     handleCreateSession,
     handleSendMessage,
+    handleRetryForkSend,
     handleRenameSession,
     handleFlagSession,
     handleUnflagSession,

apps/electron/src/renderer/atoms/__tests__/sessions.test.ts

@@ -11,6 +11,7 @@ import {
   refreshSessionsMetadataAtom,
   initializeSessionsAtom,
   replaceLoadedSessionAtom,
+  findPendingForkRetryMessage,
 } from '../sessions'
 
 function msg(id: string, role: Message['role'] = 'user'): Message {
@@ -33,6 +34,45 @@ function makeSession(overrides: Partial<Session> = {}): Session {
   } as Session
 }
 
+describe('pending fork retry recovery', () => {
+  it('finds the durable user message after the branch point', () => {
+    const session = makeSession({
+      forkPending: true,
+      branchFromMessageId: 'head',
+      messages: [msg('parent-user'), msg('head', 'assistant'), msg('retry-user')],
+    })
+
+    expect(findPendingForkRetryMessage(session)).toEqual({
+      messageId: 'retry-user',
+      text: 'content:retry-user',
+    })
+  })
+
+  it('does not treat copied parent history as a retry message', () => {
+    const session = makeSession({
+      forkPending: true,
+      branchFromMessageId: 'head',
+      messages: [msg('parent-user'), msg('head', 'assistant')],
+    })
+
+    expect(findPendingForkRetryMessage(session)).toBeNull()
+  })
+
+  it('does not skip a structured first user message for a later text message', () => {
+    const structured = {
+      ...msg('structured-user'),
+      content: { kind: 'structured' } as unknown as string,
+    }
+    const session = makeSession({
+      forkPending: true,
+      branchFromMessageId: 'head',
+      messages: [msg('head', 'assistant'), structured, msg('later-user')],
+    })
+
+    expect(findPendingForkRetryMessage(session)).toBeNull()
+  })
+})
+
 describe('session message loading atoms', () => {
   const originalWindow = globalThis.window
 

apps/electron/src/renderer/atoms/sessions.ts

@@ -701,6 +701,47 @@ export const backgroundTasksAtomFamily = atomFamily(
   (a, b) => a === b
 )
 
+/**
+ * Retryable isolated-fork establishment failure surfaced above the chat input
+ * (Phase 4). Set when a fork child's first-Send establish fails with the typed
+ * WORKTREE_FORK_FAILED code; cleared on Retry, manual dismiss, or when the
+ * session DTO stops reporting forkPending. The server message ID lets the retry
+ * reuse the already-persisted user message instead of duplicating it.
+ */
+export interface ForkRetryState {
+  /** Server-persisted user message ID to reuse on retry. */
+  messageId: string
+  /** The message text to re-send. */
+  text: string
+  /** Sanitized server error detail. */
+  error: string
+}
+
+/**
+ * Recover the first-Send message from the durable child transcript. The
+ * branch marker separates copied parent history from the one user message
+ * whose establishment can be retried; no renderer-local send map is needed.
+ */
+export function findPendingForkRetryMessage(
+  session: Pick<Session, 'forkPending' | 'branchFromMessageId' | 'messages'> | null | undefined,
+): Pick<ForkRetryState, 'messageId' | 'text'> | null {
+  if (!session?.forkPending || !session.branchFromMessageId) return null
+  const branchIndex = session.messages.findIndex(
+    (message) => message.id === session.branchFromMessageId,
+  )
+  if (branchIndex < 0) return null
+  const message = session.messages
+    .slice(branchIndex + 1)
+    .find((candidate) => candidate.role === 'user')
+  if (!message || typeof message.content !== 'string') return null
+  return { messageId: message.id, text: message.content }
+}
+
+export const forkRetryAtomFamily = atomFamily(
+  (_sessionId: string) => atom<ForkRetryState | null>(null),
+  (a, b) => a === b
+)
+
 /**
  * Window's current workspace ID — shared between Root (ThemeProvider) and App.
  * Written by App on workspace switch, read by Root to keep the theme in sync.