fix(repos,ui): pin user-supplied default_branch end-to-end + don't reset typed sourceBranch on WebSocket events (#1127)

* fix(core): handle Node 25's broken localStorage global

Node 25 exposes a `globalThis.localStorage` stub that lacks the standard
Storage methods (no `setItem`/`getItem`/etc.), so the Feathers auth
client throws `_a.setItem is not a function` on first authenticate().
This blocks any in-tree daemon / executor / CLI run on a Node 25 host —
`createClient()` configures authentication with that broken storage and
the very first auth attempt blows up.

`createClient()` now treats the global as Storage only when its
`setItem` is callable; otherwise it passes `storage: undefined` and the
Feathers auth client falls back to its in-memory mode (correct for any
non-browser runtime).

Tests:
  - "should reject a localStorage stub without setItem (Node 25)"
  - "should reject a localStorage stub whose setItem is not a function"

Same broken global also bleeds into the agor-ui test runner when the
shell exports NODE_OPTIONS=--localstorage-file=..., displacing jsdom's
real Storage implementation. apps/agor-ui/src/test/setup.ts now
installs an in-memory Storage shim under the same guard, so component
tests that read localStorage.getItem(...) work on Node 25 without
operators having to unset the env var.

* fix(repos): pin user-supplied default_branch end-to-end through clone

The "Add Repository → Default Branch" form lets the operator pick a
non-default base branch (e.g. a long-lived feature branch). Pre-fix,
that field was silently dropped at every layer and the executor wrote
whatever `origin/HEAD` pointed at into the DB record:

  UI sends `default_branch` to /repos/clone
    └─ daemon route declared `{ url, name?, destination? }` only
       └─ ReposService.cloneRepository signature took the same shape
          └─ Executor params did not include `default_branch`
             └─ Executor wrote `cloneResult.defaultBranch`
                = `git symbolic-ref refs/remotes/origin/HEAD` = "main"

Two visible symptoms:
  - Repo's `default_branch` in the DB always equals the upstream's
    HEAD, no matter what the operator typed (and re-opening the edit
    dialog kept showing "main", looking like the edit silently failed).
  - Worktrees created off that repo defaulted to "main" too, so the
    "preserved my typed sourceBranch" UI fix from a sibling commit had
    nothing useful to fall back to either.

There was also a related second-order bug: even when `default_branch`
finally reached the executor, `cloneRepo()` still ran a default
checkout of the remote's HEAD. Repos whose `.agor.yml` lives on a
non-default branch would be cloned with the file missing on disk, and
the daemon's environment-variant ingestion logged "No environment
variants configured" even though the operator had picked the right
branch.

Threads `default_branch` end-to-end:

  - apps/agor-daemon/src/register-routes.ts: add `default_branch?` to
    POST /repos/clone body type.
  - apps/agor-daemon/src/services/repos.ts: pipe `data.default_branch`
    into the executor `git.clone` params (only when set, so existing
    `getDefaultBranch()` fallback is preserved).
  - packages/executor/src/payload-types.ts: add optional `default_branch`
    to `GitClonePayloadSchema.params`.
  - packages/executor/src/commands/git.ts:
    - forward as `branch` to `cloneRepo()` so the working tree lands
      on the pinned branch (fixes the .agor.yml-not-found case);
    - prefer `payload.params.default_branch` when writing the repo DB
      record, falling back to `cloneResult.defaultBranch` only when
      unset (keeps existing behavior for un-pinned clones);
    - echo the field in the dry-run response so callers can verify
      the field actually reached the handler.
  - packages/core/src/git/index.ts: `CloneOptions.branch` opt;
    `cloneRepo()` forwards it as `git clone --branch <name>` and
    sets `defaultBranch` in the result to the pin (so the DB record
    matches what's on disk).

Tests:
  - cloneRepo: should check out the pinned branch when options.branch
    is set / fall back to remote HEAD when it isn't / fail loudly when
    the pin doesn't exist on the remote.
  - GitClonePayloadSchema: accept default_branch in params; treat it
    as optional.
  - executeCommand git.clone: echo user-supplied default_branch in
    dry-run response.

* fix(ui): preserve typed sourceBranch across WebSocket repo updates

Agor real-time-syncs repo metadata over the FeathersJS WebSocket. Every
`repos.patched` event hands the modal/tab a NEW `repoById` Map
reference, which re-fired the form-init `useEffect`. The effect then
called `setFieldsValue({ sourceBranch: repo.default_branch })` and
silently overwrote whatever the operator had typed.

End-user symptom: type a non-default branch, wait a few seconds for any
`repos.patched` event, click Create — the worktree lands on `main`
anyway. No toast, no console warning, just a wrong base branch.

Same anti-pattern in two surfaces — guard both with a useRef so init
runs exactly once per modal-open / mount session:

  - NewWorktreeModal.tsx (open-prop modal): the ref resets on close so
    re-opening always re-initializes from the fresh repo metadata.
  - WorktreeTab.tsx (tab inside CreateDialog): mounts/unmounts with
    the dialog, so the per-mount ref is sufficient.

Other potential fields with the same pattern were left alone — the
guard is specifically for sourceBranch which a user types directly;
fields like repoId only change via explicit dropdown handlers
(handleRepoChange) which are intentionally still allowed to reset
sourceBranch.

This is the same shape of fix as #1001 (session list filters being
reset by WebSocket events), applied to a different code path.

Tests (regression coverage):
  - NewWorktreeModal: preserves typed sourceBranch across repoById
    Map reference churn / re-initializes on close-and-reopen.
  - WorktreeTab: preserves typed sourceBranch across repoById churn.

* fix(repos,ui): close gaps in default_branch end-to-end coverage

Three followups from a code review of #1127. The PR's primary fixes are
correct, but each one had an adjacent surface where the same root cause
still bit users.

1. cloneRepo's existing-repo early-return ignored options.branch.

   When `~/.agor/repos/<slug>` already exists (re-clone after a half-
   broken first attempt, manual provisioning, restart loop), cloneRepo
   returned early with `defaultBranch = await getDefaultBranch(targetPath)`,
   leaving the working tree on whatever was previously checked out. The
   executor then wrote the user-supplied pin into the DB record. Net:
   DB claimed `feat/x`, disk on `main`, `.agor.yml` parsed at
   `cloneResult.path` came from `main` — exactly the symptom the
   --branch fix was supposed to close.

   Now: when the existing checkout is on a different branch than the
   pin, fetch origin/<pin> and check out. Failure (dirty working tree,
   branch missing on remote) throws with a clear message instead of
   silently returning a stale defaultBranch.

   New tests in cloneRepo:
     - switches the working tree on a reused clone with a pinned branch
     - rejects reuse when the pin can't be checked out

2. Settings → Worktrees → Create Worktree had the same useEffect anti-
   pattern as NewWorktreeModal / WorktreeTab.

   `useEffect([..., repos, boards, ...])` where `repos` and `boards`
   are derived via `mapToArray(repoById)` / `mapToArray(boardById)`
   on every render. WebSocket-triggered Map ref churn re-fired the
   effect and `setFieldsValue({ sourceBranch })` overwrote typed
   values. Same fix shape as the rest of the PR — useRef gate so init
   runs exactly once per `createModalOpen=true` session.

   New test mirroring NewWorktreeModal / WorktreeTab tests.

3. Surface the pinned branch in the cloneError message.

   The clone exits non-zero with no useful detail when the operator
   typo'd the Default Branch field — `git clone --branch <typo>`
   returns 128, the executor's stderr is consumed by
   spawnExecutorFireAndForget, and the user gets `Clone failed (exit
   code 128). Check that the repository URL is correct and accessible.`
   with no hint that the branch is the cause.

   When a default_branch was supplied, append it to the error so the
   operator can self-diagnose without diving into daemon logs. (Data
   integrity is fine; cloneRepo throwing means the executor never
   reaches the DB-write call site, so no half-formed repo records
   sneak through. The cleanup is purely about the UX of the error
   message reaching the UI.)

---------

Co-authored-by: Diego Pucci <geido@192.168.0.21>

Author: geido

apps/agor-daemon/src/register-routes.ts

@@ -2092,7 +2092,7 @@ export async function registerRoutes(ctx: RegisterRoutesContext): Promise<void>
     '/repos/clone',
     {
       async create(
-        data: { url: string; name?: string; destination?: string },
+        data: { url: string; name?: string; destination?: string; default_branch?: string },
         params: RouteParams
       ) {
         return reposService.cloneRepository(data, params);

apps/agor-daemon/src/services/repos.ts

@@ -144,7 +144,7 @@ export class ReposService extends DrizzleService<Repo, Partial<Repo>, RepoParams
    * Client receives 'repos.created' WebSocket event when complete.
    */
   async cloneRepository(
-    data: { url: string; slug?: string; name?: string },
+    data: { url: string; slug?: string; name?: string; default_branch?: string },
     params?: RepoParams
   ): Promise<{ status: 'pending' | 'exists'; slug: string }> {
     // Note: `||` (not `??`) is intentional — we want an empty `data.slug`
@@ -200,6 +200,10 @@ export class ReposService extends DrizzleService<Repo, Partial<Repo>, RepoParams
         params: {
           url: data.url,
           slug,
+          // Forward the user-supplied default_branch so the executor
+          // persists what the operator typed in "Add Repository" instead
+          // of silently overwriting it with origin/HEAD.
+          ...(data.default_branch ? { default_branch: data.default_branch } : {}),
           createDbRecord: true,
           userId: userId as string | undefined,
           initUnixGroup: rbacEnabled,
@@ -217,10 +221,20 @@ export class ReposService extends DrizzleService<Repo, Partial<Repo>, RepoParams
             const io = (app as unknown as { io?: { emit: (event: string, data: unknown) => void } })
               .io;
             if (io) {
+              // Include the pinned branch in the message so an operator who
+              // typo'd the Default Branch can self-diagnose. `git clone
+              // --branch <X>` failure is one of the most common reasons a
+              // clone exits non-zero, but the executor's stderr is consumed
+              // by spawnExecutorFireAndForget — without this hint the user
+              // sees only "Clone failed (exit code 128)" and has no idea
+              // the branch field is the cause.
+              const branchHint = data.default_branch
+                ? ` Default Branch was set to '${data.default_branch}' — verify it exists on the remote.`
+                : '';
               io.emit('repo:cloneError', {
                 slug,
                 url: data.url,
-                error: `Clone failed (exit code ${code}). Check that the repository URL is correct and accessible.`,
+                error: `Clone failed (exit code ${code}). Check that the repository URL is correct and accessible.${branchHint}`,
               });
             }
           }

apps/agor-ui/src/components/CreateDialog/tabs/WorktreeTab.test.tsx

@@ -0,0 +1,64 @@
+/**
+ * Regression tests for WorktreeTab source-branch preservation.
+ *
+ * Same root cause as NewWorktreeModal.test.tsx — every `repos.patched`
+ * WebSocket event gave the parent component a new `repoById` Map
+ * reference, re-firing the form-init `useEffect`, and `setFieldsValue`
+ * silently overwrote the user's typed `sourceBranch` with the repo's
+ * `default_branch`. Different surface (the WorktreeTab inside the unified
+ * CreateDialog) — same fix (useRef gate so init runs once per mount).
+ */
+
+import type { Repo } from '@agor-live/client';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { WorktreeTab, type WorktreeTabConfig } from './WorktreeTab';
+
+function makeRepo(overrides: Partial<Repo> = {}): Repo {
+  return {
+    repo_id: 'repo-1',
+    slug: 'org/repo-1',
+    name: 'repo-1',
+    default_branch: 'main',
+    repo_type: 'remote',
+    remote_url: 'https://github.com/org/repo-1.git',
+    local_path: '/tmp/repo-1',
+    ...overrides,
+  } as unknown as Repo;
+}
+
+describe('WorktreeTab — source-branch preservation', { timeout: 10_000 }, () => {
+  it('preserves user-typed sourceBranch across `repoById` Map reference churn (WebSocket patches)', () => {
+    const formRef: React.MutableRefObject<(() => Promise<WorktreeTabConfig | null>) | null> = {
+      current: null,
+    };
+    const repo = makeRepo({ default_branch: 'main' });
+
+    const { rerender } = render(
+      <WorktreeTab
+        repoById={new Map([[repo.repo_id, repo]])}
+        onValidityChange={vi.fn()}
+        formRef={formRef}
+      />
+    );
+
+    const branchInput = screen.getByLabelText(/Source Branch/i) as HTMLInputElement;
+    expect(branchInput.value).toBe('main');
+
+    fireEvent.change(branchInput, { target: { value: 'release/2024-q1' } });
+    expect(branchInput.value).toBe('release/2024-q1');
+
+    // New Map reference, same data — pre-fix this would reset the field.
+    rerender(
+      <WorktreeTab
+        repoById={new Map([[repo.repo_id, repo]])}
+        onValidityChange={vi.fn()}
+        formRef={formRef}
+      />
+    );
+
+    expect((screen.getByLabelText(/Source Branch/i) as HTMLInputElement).value).toBe(
+      'release/2024-q1'
+    );
+  });
+});

apps/agor-ui/src/components/CreateDialog/tabs/WorktreeTab.tsx

@@ -1,6 +1,6 @@
 import type { Repo } from '@agor-live/client';
 import { Form } from 'antd';
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { mapToArray } from '@/utils/mapHelpers';
 import { WorktreeFormFields } from '../../WorktreeFormFields';
 
@@ -46,19 +46,27 @@ export const WorktreeTab: React.FC<WorktreeTabProps> = ({
     }, 0);
   }, [form, onValidityChange]);
 
-  // Remember last used repo
+  // Initialize form once per mount. Without this guard the effect re-fires
+  // on every `repos.patched` WebSocket event (which gives `repoById` a new
+  // Map reference), and `setFieldsValue({ sourceBranch })` silently
+  // overwrites whatever the user typed back to the repo's default branch.
+  // The user notices only after submitting that the worktree got created
+  // off `main` instead of their chosen branch.
+  const initialized = useRef(false);
   useEffect(() => {
-    if (repoById.size === 0) return;
+    if (initialized.current || repoById.size === 0) return;
 
     const lastRepoId = localStorage.getItem('agor-last-repo-id');
     if (lastRepoId && repoById.has(lastRepoId)) {
+      initialized.current = true;
       form.setFieldsValue({
         repoId: lastRepoId,
         sourceBranch: repoById.get(lastRepoId)?.default_branch,
       });
       setSelectedRepoId(lastRepoId);
       handleValuesChange();
     } else if (repoById.size > 0) {
+      initialized.current = true;
       const firstRepo = mapToArray(repoById)[0];
       form.setFieldsValue({
         repoId: firstRepo.repo_id,

apps/agor-ui/src/components/NewWorktreeModal/NewWorktreeModal.test.tsx

@@ -0,0 +1,113 @@
+/**
+ * Regression tests for NewWorktreeModal source-branch preservation.
+ *
+ * Bug: every `repos.patched` WebSocket event gave the parent component a
+ * new `repoById` Map reference, which re-fired the form-init `useEffect`
+ * and `setFieldsValue({ sourceBranch })` silently overwrote whatever the
+ * user typed back to the repo's `default_branch`. The user only noticed
+ * after submitting that the worktree was created off `main` instead of
+ * their chosen branch.
+ *
+ * The fix gates initialization with a `useRef` so it runs exactly once per
+ * modal-open session. These tests pin that guardrail.
+ */
+
+import type { Repo } from '@agor-live/client';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { NewWorktreeModal } from './NewWorktreeModal';
+
+function makeRepo(overrides: Partial<Repo> = {}): Repo {
+  return {
+    repo_id: 'repo-1',
+    slug: 'org/repo-1',
+    name: 'repo-1',
+    default_branch: 'main',
+    repo_type: 'remote',
+    remote_url: 'https://github.com/org/repo-1.git',
+    local_path: '/tmp/repo-1',
+    ...overrides,
+  } as unknown as Repo;
+}
+
+describe('NewWorktreeModal — source-branch preservation', { timeout: 10_000 }, () => {
+  it('preserves user-typed sourceBranch across `repoById` Map reference churn (WebSocket patches)', async () => {
+    const repo = makeRepo({ default_branch: 'main' });
+    const { rerender } = render(
+      <NewWorktreeModal
+        open
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        repoById={new Map([[repo.repo_id, repo]])}
+      />
+    );
+
+    // The init effect should populate sourceBranch from repo.default_branch
+    // on first render. Use the visible label to locate the field.
+    const branchInput = screen.getByLabelText(/Source Branch/i) as HTMLInputElement;
+    expect(branchInput.value).toBe('main');
+
+    // User clears the field and types their preferred branch.
+    fireEvent.change(branchInput, { target: { value: 'release/2024-q1' } });
+    expect(branchInput.value).toBe('release/2024-q1');
+
+    // Simulate a WebSocket `repos.patched` event by handing the modal a NEW
+    // Map reference. The repo data hasn't changed; only the reference has.
+    // Pre-fix, this re-fired the effect and reset sourceBranch back to
+    // 'main'. With the useRef guard, the typed value must persist.
+    rerender(
+      <NewWorktreeModal
+        open
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        repoById={new Map([[repo.repo_id, repo]])}
+      />
+    );
+
+    expect((screen.getByLabelText(/Source Branch/i) as HTMLInputElement).value).toBe(
+      'release/2024-q1'
+    );
+  });
+
+  it('re-initializes sourceBranch when the modal is closed and re-opened', async () => {
+    // Closing the modal must clear the "initialized" flag so the next open
+    // populates fresh defaults. Otherwise a user who typed a stale value,
+    // closed, came back later — and the form would still have the stale
+    // typed value with no way to know it didn't come from the new repo.
+    const repo = makeRepo({ default_branch: 'main' });
+    const { rerender } = render(
+      <NewWorktreeModal
+        open
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        repoById={new Map([[repo.repo_id, repo]])}
+      />
+    );
+
+    fireEvent.change(screen.getByLabelText(/Source Branch/i), {
+      target: { value: 'some-typed-value' },
+    });
+
+    rerender(
+      <NewWorktreeModal
+        open={false}
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        repoById={new Map([[repo.repo_id, repo]])}
+      />
+    );
+
+    // Re-open with an updated default_branch — the form should pick it up.
+    const repoUpdated = makeRepo({ default_branch: 'develop' });
+    rerender(
+      <NewWorktreeModal
+        open
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        repoById={new Map([[repoUpdated.repo_id, repoUpdated]])}
+      />
+    );
+
+    expect((screen.getByLabelText(/Source Branch/i) as HTMLInputElement).value).toBe('develop');
+  });
+});

apps/agor-ui/src/components/NewWorktreeModal/NewWorktreeModal.tsx

@@ -1,6 +1,6 @@
 import type { Repo } from '@agor-live/client';
 import { Button, Form, Modal } from 'antd';
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { mapToArray } from '@/utils/mapHelpers';
 import type { WorktreeTabConfig } from '../CreateDialog/tabs/WorktreeTab';
 import { WorktreeFormFields } from '../WorktreeFormFields';
@@ -43,14 +43,25 @@ export const NewWorktreeModal: React.FC<NewWorktreeModalProps> = ({
     }, 0);
   }, [form]);
 
-  // Remember last used repo from localStorage
+  // Initialize form once per modal-open session. Without this guard the
+  // effect re-fires on every `repos.patched` WebSocket event (which gives
+  // `repoById` a new Map reference), and `setFieldsValue({ sourceBranch })`
+  // silently overwrites whatever the user typed back to the repo's default
+  // branch. The user notices only after submitting that the worktree got
+  // created off `main` instead of their chosen branch.
+  const initialized = useRef(false);
   useEffect(() => {
-    if (!open || repoById.size === 0) return;
+    if (!open) {
+      initialized.current = false;
+      return;
+    }
+    if (initialized.current || repoById.size === 0) return;
 
     const lastRepoId = localStorage.getItem('agor-last-repo-id');
 
     // If we have a last used repo and it still exists, use it
     if (lastRepoId && repoById.has(lastRepoId)) {
+      initialized.current = true;
       form.setFieldsValue({
         repoId: lastRepoId,
         sourceBranch: repoById.get(lastRepoId)?.default_branch,
@@ -60,6 +71,7 @@ export const NewWorktreeModal: React.FC<NewWorktreeModalProps> = ({
       handleValuesChange();
     } else if (repoById.size > 0) {
       // No last-repo-id or it doesn't exist anymore - auto-select first repo
+      initialized.current = true;
       const firstRepo = mapToArray(repoById)[0];
       form.setFieldsValue({
         repoId: firstRepo.repo_id,

apps/agor-ui/src/components/SettingsModal/WorktreesTable.test.tsx

@@ -0,0 +1,78 @@
+/**
+ * Regression test for WorktreesTable source-branch preservation in the
+ * Settings → Worktrees → Create Worktree modal.
+ *
+ * Same root cause as NewWorktreeModal / WorktreeTab — every `repos.patched`
+ * (or `boards.patched`) WebSocket event hands the table new array
+ * references for `repos` / `boards`, which re-fired the form-init
+ * `useEffect`, and `setFieldsValue({ sourceBranch })` silently overwrote
+ * whatever the user typed back to the repo's `default_branch`.
+ *
+ * The fix is the same useRef guard so init runs exactly once per
+ * `createModalOpen=true` session.
+ */
+
+import type { Board, Repo, Worktree } from '@agor-live/client';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { WorktreesTable } from './WorktreesTable';
+
+function makeRepo(overrides: Partial<Repo> = {}): Repo {
+  return {
+    repo_id: 'repo-1',
+    slug: 'org/repo-1',
+    name: 'repo-1',
+    default_branch: 'main',
+    repo_type: 'remote',
+    remote_url: 'https://github.com/org/repo-1.git',
+    local_path: '/tmp/repo-1',
+    ...overrides,
+  } as unknown as Repo;
+}
+
+describe('WorktreesTable — source-branch preservation', { timeout: 10_000 }, () => {
+  it('preserves user-typed sourceBranch across `repoById` / `boardById` Map reference churn', () => {
+    const repo = makeRepo({ default_branch: 'main' });
+    const repoById = new Map([[repo.repo_id, repo]]);
+    const boardById = new Map<string, Board>();
+    const worktreeById = new Map<string, Worktree>();
+    const sessionsByWorktree = new Map<string, never[]>();
+
+    const { rerender } = render(
+      <WorktreesTable
+        client={null}
+        worktreeById={worktreeById}
+        repoById={repoById}
+        boardById={boardById}
+        sessionsByWorktree={sessionsByWorktree as Map<string, never[]>}
+      />
+    );
+
+    // Open the create modal
+    fireEvent.click(screen.getByRole('button', { name: /Create Worktree/i }));
+
+    // The init effect populates sourceBranch from the repo's default_branch
+    const branchInput = screen.getByLabelText(/Source Branch/i) as HTMLInputElement;
+    expect(branchInput.value).toBe('main');
+
+    // User types their pinned branch
+    fireEvent.change(branchInput, { target: { value: 'release/2024-q1' } });
+    expect(branchInput.value).toBe('release/2024-q1');
+
+    // Simulate a `repos.patched` WebSocket event by handing the table NEW
+    // Map references for repoById and boardById. Same data, different refs.
+    rerender(
+      <WorktreesTable
+        client={null}
+        worktreeById={worktreeById}
+        repoById={new Map([[repo.repo_id, repo]])}
+        boardById={new Map<string, Board>()}
+        sessionsByWorktree={sessionsByWorktree as Map<string, never[]>}
+      />
+    );
+
+    expect((screen.getByLabelText(/Source Branch/i) as HTMLInputElement).value).toBe(
+      'release/2024-q1'
+    );
+  });
+});