gitspace 0.2.0-rc.16 → 0.2.0-rc.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitspace",
-  "version": "0.2.0-rc.16",
+  "version": "0.2.0-rc.17",
   "description": "CLI for managing GitHub workspaces with git worktrees and secure remote terminal access",
   "bin": {
     "gssh": "./bin/gssh"
@@ -17,10 +17,10 @@
     "relay": "bun src/relay/index.ts"
   },
   "optionalDependencies": {
-    "@gitspace/darwin-arm64": "0.2.0-rc.16",
-    "@gitspace/darwin-x64": "0.2.0-rc.16",
-    "@gitspace/linux-x64": "0.2.0-rc.16",
-    "@gitspace/linux-arm64": "0.2.0-rc.16"
+    "@gitspace/darwin-arm64": "0.2.0-rc.17",
+    "@gitspace/darwin-x64": "0.2.0-rc.17",
+    "@gitspace/linux-x64": "0.2.0-rc.17",
+    "@gitspace/linux-arm64": "0.2.0-rc.17"
   },
   "keywords": [
     "cli",

package/src/app/session/useWorkspaceDeleteFlow.ts

@@ -30,6 +30,7 @@ export interface UseWorkspaceDeleteFlowOptions {
   onDeleteSuccess?: (context: WorkspaceDeleteContext) => void | Promise<void>;
   onDeleteCancelled?: (context: WorkspaceDeleteContext) => void | Promise<void>;
   onDeleteError?: (context: WorkspaceDeleteErrorContext) => void | Promise<void>;
+  showLoadingDuringDelete?: boolean;
 }
 
 export interface UseWorkspaceDeleteFlowResult {
@@ -86,6 +87,7 @@ export function useWorkspaceDeleteFlow(
     onDeleteSuccess,
     onDeleteCancelled,
     onDeleteError,
+    showLoadingDuringDelete = false,
   } = options;
 
   const executeDelete = useCallback(async (
@@ -100,13 +102,17 @@ export function useWorkspaceDeleteFlow(
     };
 
     await onBeforeDelete?.(context);
-    flow.showLoading({
-      title: 'Deleting Workspace',
-      message:
-        params.scriptPolicy === 'skip'
-          ? 'Removing workspace without cleanup scripts...'
-          : `Running cleanup scripts for "${target.workspaceName}"...`,
-    });
+    if (showLoadingDuringDelete) {
+      flow.showLoading({
+        title: 'Deleting Workspace',
+        message:
+          params.scriptPolicy === 'skip'
+            ? 'Removing workspace without cleanup scripts...'
+            : `Running cleanup scripts for "${target.workspaceName}"...`,
+      });
+    } else {
+      flow.close();
+    }
 
     try {
       await deleteWorkspace(target.projectName, target.workspaceId, params);
@@ -144,7 +150,15 @@ export function useWorkspaceDeleteFlow(
 
       return false;
     }
-  }, [deleteWorkspace, flow, onBeforeDelete, onDeleteCancelled, onDeleteError, onDeleteSuccess]);
+  }, [
+    deleteWorkspace,
+    flow,
+    onBeforeDelete,
+    onDeleteCancelled,
+    onDeleteError,
+    onDeleteSuccess,
+    showLoadingDuringDelete,
+  ]);
 
   const deleteWorkspaceWithPrompt = useCallback(async (target: WorkspaceDeleteTarget): Promise<boolean> => {
     return executeDelete(target, { scriptPolicy: 'auto' }, false);

package/src/app.tui.tsx

@@ -87,7 +87,10 @@ import { useUserActivity } from './hooks/index.js';
 import { useBundleRefreshAttachFlow } from './session/index.js';
 import { useAttachController } from './app/session/useAttachController.js';
 import { useWorkspaceDeleteFlow } from './app/session/useWorkspaceDeleteFlow.js';
-import { initializeSecretRuntime } from './core/secret-runtime.js';
+import {
+  consumeLegacyCleanupReminderForTui,
+  initializeSecretRuntime,
+} from './core/secret-runtime.js';
 import {
   resolveInboxCommand,
   resolveMachineListCommand,
@@ -1322,9 +1325,13 @@ function App({ relayConfig, onQuit }: AppProps) {
   // ========== Keyboard Handlers ==========
 
   useKeyboard(async (key) => {
+    const localScriptTerminalRunning =
+      state.view === 'scripts' &&
+      (localScriptState?.isRunning ?? true);
+
     // Handle flow modals FIRST - even in terminal view
     // This ensures y/n work in confirmation modals when terminal is underneath
-    if (flow.isOpen) {
+    if (flow.isOpen && !localScriptTerminalRunning) {
       // Handle confirm modal with y/n shortcuts
       if (flow.flow.type === 'confirm') {
         if (key.raw === 'y' || key.name === 'return') {
@@ -2059,7 +2066,7 @@ function App({ relayConfig, onQuit }: AppProps) {
           error={localScriptState?.error}
           exitCode={localScriptState?.exitCode}
         />
-        <FlowTUI flow={flow} />
+        {!isRunning && <FlowTUI flow={flow} />}
         <StatusBar hint={isRunning ? '[Running scripts...]' : '[Esc/n] Back to workspaces'} />
       </Fragment>
     );
@@ -2590,6 +2597,12 @@ export async function launchTUI(
   // Clean exit handler
   const handleQuit = () => {
     renderer.destroy();
+
+    const legacyReminder = consumeLegacyCleanupReminderForTui();
+    if (legacyReminder) {
+      logger.warning(legacyReminder);
+    }
+
     process.exit(0);
   };
 

package/src/app.web.tsx

@@ -747,18 +747,19 @@ export default function App() {
     terminal.mode === 'browsing' &&
     showScriptTerminal
   ) {
+    const isRunning = terminal.scriptState?.isRunning ?? true;
     return (
       <>
         <ScriptTerminal
           phase={terminal.scriptState?.phase ?? 'pre'}
           workspaceName={scriptWorkspaceName}
-          isRunning={terminal.scriptState?.isRunning ?? true}
+          isRunning={isRunning}
           error={terminal.scriptState?.error}
           exitCode={terminal.scriptState?.exitCode}
           setWriteCallback={terminal.setWriteCallback}
           onBack={() => setShowScriptTerminal(false)}
         />
-        <FlowWeb flow={flow} />
+        {!isRunning && <FlowWeb flow={flow} />}
         <Toaster theme="dark" position="top-right" richColors />
       </>
     );

package/src/commands/migrate.ts

@@ -0,0 +1,52 @@
+import { getSecretMigrationInputs } from '../core/secret-runtime.js';
+import { logger } from '../utils/logger.js';
+import { promptConfirm } from '../utils/prompts.js';
+import { cleanupLegacySecretEntries, preloadAllSecrets } from '../utils/secrets.js';
+
+export interface CleanupLegacyOptions {
+  yes?: boolean;
+}
+
+export async function migrateCleanupLegacy(
+  options: CleanupLegacyOptions = {}
+): Promise<void> {
+  const migrationInputs = getSecretMigrationInputs();
+
+  if (!options.yes) {
+    const confirmed = await promptConfirm(
+      'Delete legacy keychain entries (project:*, global, and old per-key entries)? Unified secrets are kept.',
+      false
+    );
+
+    if (!confirmed) {
+      logger.info('Cancelled');
+      return;
+    }
+  }
+
+  // Ensure legacy entries are copied into unified storage before cleanup.
+  await preloadAllSecrets(migrationInputs.projectNames, {
+    projectLegacyKeys: migrationInputs.projectSecretKeys,
+    globalLegacyKeys: migrationInputs.globalSecretKeys,
+  });
+
+  const result = await cleanupLegacySecretEntries(migrationInputs.projectNames, {
+    projectLegacyKeys: migrationInputs.projectSecretKeys,
+    globalLegacyKeys: migrationInputs.globalSecretKeys,
+  });
+
+  if (result.errors.length > 0) {
+    logger.warning(`Legacy cleanup completed with ${result.errors.length} error(s).`);
+    for (const error of result.errors) {
+      logger.error(`  ${error}`);
+    }
+    logger.info(
+      `Legacy cleanup finished with issues. Deleted ${result.deleted} entries (${result.missing} already absent).`
+    );
+    return;
+  }
+
+  logger.success(
+    `Legacy cleanup complete. Deleted ${result.deleted} entries (${result.missing} already absent).`
+  );
+}

package/src/components/RemoteMachineScreen.tui.tsx

@@ -89,6 +89,32 @@ export function RemoteMachineScreen({ machine, relayUrl, identity, onBack }: Rem
       }
       return remote.selectedProjectName;
     },
+    onBeforeAttach: ({ target, params }) => {
+      if (target === 'workspace' && params.workspaceId) {
+        setShowInbox(false);
+        setScriptWorkspaceName(params.workspaceId.split(':').slice(-1)[0] ?? params.workspaceId);
+        setShowScriptTerminal(true);
+      }
+    },
+    onAttachCancelled: ({ target }) => {
+      if (target === 'workspace') {
+        setShowScriptTerminal(false);
+      }
+    },
+    onAttachError: ({ target, message }) => {
+      const isWorkspaceScriptFailure = message.startsWith('Workspace scripts failed during');
+      const hasScriptRuntimeState = Boolean(remote.scriptState);
+
+      if (target === 'workspace' && (!isWorkspaceScriptFailure || !hasScriptRuntimeState)) {
+        setShowScriptTerminal(false);
+      }
+
+      flow.showMessage({
+        title: isWorkspaceScriptFailure ? 'Workspace Script Failed' : 'Session Failed',
+        message,
+        variant: 'error',
+      });
+    },
   });
 
   const { deleteWorkspaceWithPrompt } = useWorkspaceDeleteFlow({
@@ -221,7 +247,11 @@ export function RemoteMachineScreen({ machine, relayUrl, identity, onBack }: Rem
   }, [flow, renderer]);
 
   useKeyboard(async (key) => {
-    if (flow.isOpen) {
+    const scriptTerminalRunning =
+      showScriptTerminal &&
+      (remote.scriptState?.isRunning ?? true);
+
+    if (flow.isOpen && !scriptTerminalRunning) {
       if (flow.flow.type === 'confirm') {
         if (key.raw === 'y' || key.name === 'return') {
           await flow.handleConfirm();
@@ -429,7 +459,7 @@ export function RemoteMachineScreen({ machine, relayUrl, identity, onBack }: Rem
           error={remote.scriptState?.error}
           exitCode={remote.scriptState?.exitCode}
         />
-        <FlowTUI flow={flow} />
+        {!isRunning && <FlowTUI flow={flow} />}
         <StatusBar hint={isRunning ? '[Running scripts...]' : '[Esc/n] Back to workspaces'} />
       </Fragment>
     );

package/src/core/secret-runtime.ts

@@ -1,30 +1,71 @@
-import { getAllProjectNames, readProjectConfig } from './config.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getAllProjectNames, getSpacesDir, readProjectConfig } from './config.js';
 import { logger } from '../utils/logger.js';
-import { preloadProjectSecrets } from '../utils/secrets.js';
+import { preloadAllSecrets } from '../utils/secrets.js';
 import { SpacesError } from '../types/errors.js';
 
 interface SecretRuntimeState {
   ignoreKeychainAndSkipSecrets: boolean;
-  initialized: boolean;
   projectsWithSecrets: Set<string>;
+  legacyEntriesDetected: boolean;
+  legacyReminderConsumed: boolean;
 }
 
-const state: SecretRuntimeState = {
-  ignoreKeychainAndSkipSecrets: false,
-  initialized: false,
-  projectsWithSecrets: new Set<string>(),
-};
+export interface SecretMigrationInputs {
+  projectNames: string[];
+  projectSecretKeys: Record<string, string[]>;
+  globalSecretKeys: string[];
+}
+
+function readHostSubdomains(): string[] {
+  const hostPath = join(getSpacesDir(), 'host.json');
+  if (!existsSync(hostPath)) {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(hostPath, 'utf-8')) as {
+      subdomain?: unknown;
+      subdomains?: unknown;
+    };
+
+    const found = new Set<string>();
+    if (typeof parsed.subdomain === 'string' && parsed.subdomain.length > 0) {
+      found.add(parsed.subdomain);
+    }
+
+    if (Array.isArray(parsed.subdomains)) {
+      for (const candidate of parsed.subdomains) {
+        if (typeof candidate === 'string' && candidate.length > 0) {
+          found.add(candidate);
+        }
+      }
+    }
+
+    return [...found];
+  } catch {
+    return [];
+  }
+}
+
+export function getSecretMigrationInputs(): SecretMigrationInputs {
+  const projectNames = getAllProjectNames();
+  const projectSecretKeys: Record<string, string[]> = {};
+  const globalSecretKeys = new Set<string>([
+    'GITSPACE_TOKEN',
+    'linear-api-key',
+    'relay:signingPrivateKey',
+  ]);
 
-function collectProjectsWithSecrets(): Array<{ projectName: string; keys: string[] }> {
-  const projects = getAllProjectNames();
-  const result: Array<{ projectName: string; keys: string[] }> = [];
+  for (const projectName of projectNames) {
+    globalSecretKeys.add(`linear-api-key-${projectName}`);
 
-  for (const projectName of projects) {
     try {
       const config = readProjectConfig(projectName);
-      const keys = config.bundleSecretKeys ?? [];
+      const keys = [...new Set(config.bundleSecretKeys ?? [])];
       if (keys.length > 0) {
-        result.push({ projectName, keys });
+        projectSecretKeys[projectName] = keys;
       }
     } catch (error) {
       logger.debug(
@@ -33,9 +74,24 @@ function collectProjectsWithSecrets(): Array<{ projectName: string; keys: string
     }
   }
 
-  return result;
+  for (const subdomain of readHostSubdomains()) {
+    globalSecretKeys.add(`TUNNEL_TOKEN_${subdomain}`);
+  }
+
+  return {
+    projectNames,
+    projectSecretKeys,
+    globalSecretKeys: [...globalSecretKeys],
+  };
 }
 
+const state: SecretRuntimeState = {
+  ignoreKeychainAndSkipSecrets: false,
+  projectsWithSecrets: new Set<string>(),
+  legacyEntriesDetected: false,
+  legacyReminderConsumed: false,
+};
+
 export interface InitializeSecretRuntimeOptions {
   ignoreKeychainAndSkipSecrets?: boolean;
 }
@@ -45,13 +101,14 @@ export async function initializeSecretRuntime(
 ): Promise<void> {
   const ignore = options.ignoreKeychainAndSkipSecrets ?? false;
   state.ignoreKeychainAndSkipSecrets = ignore;
+  state.legacyEntriesDetected = false;
+  state.legacyReminderConsumed = false;
 
-  const projectsWithSecrets = collectProjectsWithSecrets();
-  state.projectsWithSecrets = new Set(projectsWithSecrets.map((entry) => entry.projectName));
+  const migrationInputs = getSecretMigrationInputs();
+  state.projectsWithSecrets = new Set(Object.keys(migrationInputs.projectSecretKeys));
 
   if (ignore) {
-    state.initialized = true;
-    if (projectsWithSecrets.length > 0) {
+    if (state.projectsWithSecrets.size > 0) {
       logger.warning(
         'Ignoring keychain and skipping secret-dependent scripts (use with caution).'
       );
@@ -59,16 +116,12 @@ export async function initializeSecretRuntime(
     return;
   }
 
-  if (projectsWithSecrets.length === 0) {
-    state.initialized = true;
-    return;
-  }
-
   try {
-    for (const entry of projectsWithSecrets) {
-      await preloadProjectSecrets(entry.projectName, entry.keys);
-    }
-    state.initialized = true;
+    const preloadResult = await preloadAllSecrets(migrationInputs.projectNames, {
+      projectLegacyKeys: migrationInputs.projectSecretKeys,
+      globalLegacyKeys: migrationInputs.globalSecretKeys,
+    });
+    state.legacyEntriesDetected = preloadResult.legacyEntriesDetected;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new SpacesError(
@@ -80,6 +133,15 @@ export async function initializeSecretRuntime(
   }
 }
 
+export function consumeLegacyCleanupReminderForTui(): string | null {
+  if (!state.legacyEntriesDetected || state.legacyReminderConsumed) {
+    return null;
+  }
+
+  state.legacyReminderConsumed = true;
+  return 'Legacy keychain entries are still present. Run `gssh migrate cleanup-legacy` once you are confident the unified keychain storage is stable.';
+}
+
 export function shouldSkipSecretDependentScripts(
   projectName: string,
   configuredSecretKeys?: string[]

package/src/core/workspace.ts

@@ -193,9 +193,29 @@ export async function deleteWorkspaceCore(
   try {
     await removeWorktree(baseDir, workspacePath, true);
   } catch (e) {
-    result.errorCode = 'WORKTREE_REMOVE_FAILED';
-    result.error = e instanceof Error ? e.message : 'Failed to remove worktree';
-    return result;
+    const message = e instanceof Error ? e.message : String(e);
+    const isNotWorkingTreeError = /not a working tree/i.test(message);
+
+    if (isNotWorkingTreeError) {
+      logger.debug(
+        `Worktree metadata missing for ${workspaceName}; removing directory directly.`
+      );
+
+      try {
+        rmSync(workspacePath, { recursive: true, force: true });
+      } catch (rmError) {
+        result.errorCode = 'WORKTREE_REMOVE_FAILED';
+        result.error =
+          rmError instanceof Error
+            ? rmError.message
+            : 'Failed to remove orphaned workspace directory';
+        return result;
+      }
+    } else {
+      result.errorCode = 'WORKTREE_REMOVE_FAILED';
+      result.error = message || 'Failed to remove worktree';
+      return result;
+    }
   }
 
   // Try to delete the local branch

package/src/index.ts

@@ -56,6 +56,7 @@ import { hostReserve, hostRelease, hostList, hostSetPrimary, hostStatus } from '
 import { startTmux, stopTmux, statusTmux, listTmux, newTmux, attachTmux, killTmux } from './commands/tmux.js'
 import { showStatus } from './commands/status.js'
 import { configNotifications, linearSetup, linearShow, linearClear } from './commands/config.js'
+import { migrateCleanupLegacy } from './commands/migrate.js'
 import { notificationsInstall, notificationsUninstall, notificationsHook, notificationsStatus } from './commands/notifications.js'
 import { bundleRefresh, bundleStatus } from './commands/bundle.js'
 
@@ -723,6 +724,27 @@ configLinearCommand
 		}
 	})
 
+// ============================================================================
+// Migration Commands
+// ============================================================================
+
+const migrateCommand = program
+	.command('migrate')
+	.description('Migration and cleanup utilities')
+
+migrateCommand
+	.command('cleanup-legacy')
+	.description('Delete legacy keychain entries kept for backwards compatibility')
+	.option('-y, --yes', 'Skip confirmation prompt')
+	.action(async (options) => {
+		await checkFirstTimeSetup()
+		try {
+			await migrateCleanupLegacy(options)
+		} catch (error) {
+			handleError(error)
+		}
+	})
+
 // ============================================================================
 // Notifications Commands
 // ============================================================================

package/src/session/useBundleRefreshAttachFlow.ts

@@ -394,10 +394,8 @@ export function useBundleRefreshAttachFlow(
             return false;
           }
 
-          currentOptions.flow.showLoading({
-            title: 'Bundle Refresh',
-            message: 'Retrying session attach...',
-          });
+          // Ensure lifecycle script output is visible in ScriptTerminal during retry.
+          currentOptions.flow.close();
           await Promise.resolve(currentOptions.attachSession(pending.params));
           currentOptions.flow.close();
           return true;
@@ -436,10 +434,8 @@ export function useBundleRefreshAttachFlow(
 
         await currentOptions.applyBundleRefresh(projectName, pending.workspaceId, submission);
 
-        currentOptions.flow.showLoading({
-          title: 'Bundle Refresh',
-          message: 'Retrying session attach...',
-        });
+        // Ensure lifecycle script output is visible in ScriptTerminal during retry.
+        currentOptions.flow.close();
 
         await Promise.resolve(currentOptions.attachSession(pending.params));
         currentOptions.flow.close();
@@ -476,10 +472,8 @@ export function useBundleRefreshAttachFlow(
       }
 
       try {
-        currentOptions.flow.showLoading({
-          title: 'Attaching Session',
-          message: 'Retrying without workspace scripts...',
-        });
+        // Do not block ScriptTerminal with loading overlays while attach retries.
+        currentOptions.flow.close();
         await Promise.resolve(currentOptions.attachSession({
           ...pending.params,
           scriptPolicy: 'skip',

package/src/utils/__tests__/workspace-setup.integration.test.ts

@@ -19,6 +19,7 @@ let mockProjectConfig: any;
 let secretStore: Record<string, string>;
 let onboardingQueue: Array<any>;
 let capturedOnboardingBatches: OnboardingStep[][];
+let mockRemoveWorktreeError: string | null;
 let oldTmuxSocket: string | undefined;
 let oldTmuxSessionDir: string | undefined;
 let oldTmuxPidFile: string | undefined;
@@ -48,6 +49,9 @@ function setupModuleMocks(): void {
       lastCommit: '',
     }),
     removeWorktree: async (_baseDir: string, workspacePath: string) => {
+      if (mockRemoveWorktreeError) {
+        throw new Error(mockRemoveWorktreeError);
+      }
       if (existsSync(workspacePath)) {
         rmSync(workspacePath, { recursive: true, force: true });
       }
@@ -205,6 +209,7 @@ describe('workspace setup integration', () => {
     secretStore = {};
     onboardingQueue = [];
     capturedOnboardingBatches = [];
+    mockRemoveWorktreeError = null;
 
     // Guard rails: isolate tmux-lite env in case a future code path accidentally
     // reaches tmux-lite helpers.
@@ -604,4 +609,25 @@ describe('workspace setup integration', () => {
     expect(secondAttempt.success).toBe(true);
     expect(existsSync(workspacePath)).toBe(false);
   });
+
+  it('falls back to removing workspace directory when git reports not a working tree', async () => {
+    const { deleteWorkspaceCore } = await loadWorkspaceCoreModule();
+
+    const workspaceName = 'ws-orphan';
+    const workspacePath = join(workspacesDir, workspaceName);
+    mkdirSync(workspacePath, { recursive: true });
+
+    mockRemoveWorktreeError = `fatal: '${workspacePath}' is not a working tree`;
+
+    const result = await deleteWorkspaceCore('test-project', workspaceName, {
+      nonInteractive: true,
+      keepBranch: true,
+      removeScriptPolicy: 'skip',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.error).toBeUndefined();
+    expect(result.errorCode).toBeUndefined();
+    expect(existsSync(workspacePath)).toBe(false);
+  });
 });

package/src/utils/secrets.ts

@@ -1,28 +1,162 @@
 /**
- * Secure secrets management using Bun.secrets API
- * Stores secrets in the OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager)
+ * Secure secrets management using Bun.secrets API.
  *
- * All project secrets are stored in a single keychain entry per project (as JSON).
- * All global secrets are stored in a single keychain entry (as JSON).
- * This ensures only ONE keychain prompt per operation, regardless of how many secrets are needed.
+ * Current format: a SINGLE unified keychain entry containing both global
+ * and project-scoped secret maps.
+ *
+ * Legacy formats still supported for reads/migration:
+ * - project blobs: project:<name>
+ * - global blob: global
+ * - very old per-secret keys: <project>:<key> and <key>
  */
 
 const SERVICE_NAME = 'com.gitspace';
 
 // Keychain entry names
+const UNIFIED_SECRETS_KEY = 'secrets';
 const PROJECT_SECRETS_PREFIX = 'project:';
 const GLOBAL_SECRETS_KEY = 'global';
 
-// In-memory cache for loaded secret blobs
-// Maps keychain entry name -> parsed secrets object
-const secretsBlobCache = new Map<string, Record<string, string>>();
+interface UnifiedSecretsBlob {
+  global: Record<string, string>;
+  projects: Record<string, Record<string, string>>;
+  metadata: {
+    schemaVersion: number;
+    legacyMigrationComplete: boolean;
+    legacyEntriesRetained: boolean;
+  };
+}
+
+const UNIFIED_SECRETS_SCHEMA_VERSION = 2;
+
+// In-memory cache for unified secrets blob
+let unifiedSecretsCache: UnifiedSecretsBlob | null = null;
+
+// Process-level marker used for reminders about legacy cleanup.
+let legacyEntriesDetected = false;
+const legacyProjectBlobChecked = new Set<string>();
+let legacyGlobalBlobChecked = false;
+
+function createEmptyBlob(): UnifiedSecretsBlob {
+  return {
+    global: {},
+    projects: {},
+    metadata: {
+      schemaVersion: UNIFIED_SECRETS_SCHEMA_VERSION,
+      legacyMigrationComplete: false,
+      legacyEntriesRetained: false,
+    },
+  };
+}
+
+function normalizeRecord(value: unknown): Record<string, string> {
+  if (!value || typeof value !== 'object') {
+    return {};
+  }
+
+  const output: Record<string, string> = {};
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof raw === 'string') {
+      output[key] = raw;
+    }
+  }
+  return output;
+}
+
+function parseUnifiedSecretsBlob(raw: string | null): UnifiedSecretsBlob {
+  if (!raw) {
+    return createEmptyBlob();
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as {
+      global?: unknown;
+      projects?: unknown;
+      metadata?: unknown;
+    };
+
+    const projects: Record<string, Record<string, string>> = {};
+    if (parsed.projects && typeof parsed.projects === 'object') {
+      for (const [projectName, projectSecrets] of Object.entries(parsed.projects as Record<string, unknown>)) {
+        projects[projectName] = normalizeRecord(projectSecrets);
+      }
+    }
+
+    const metadata =
+      parsed.metadata && typeof parsed.metadata === 'object'
+        ? (parsed.metadata as {
+            schemaVersion?: unknown;
+            legacyMigrationComplete?: unknown;
+            legacyEntriesRetained?: unknown;
+          })
+        : {};
+
+    return {
+      global: normalizeRecord(parsed.global),
+      projects,
+      metadata: {
+        schemaVersion:
+          typeof metadata.schemaVersion === 'number' && Number.isFinite(metadata.schemaVersion)
+            ? metadata.schemaVersion
+            : UNIFIED_SECRETS_SCHEMA_VERSION,
+        legacyMigrationComplete: metadata.legacyMigrationComplete === true,
+        legacyEntriesRetained: metadata.legacyEntriesRetained === true,
+      },
+    };
+  } catch {
+    return createEmptyBlob();
+  }
+}
+
+function isLegacyMigrationComplete(blob: UnifiedSecretsBlob): boolean {
+  return blob.metadata.legacyMigrationComplete === true;
+}
+
+async function loadUnifiedSecretsBlob(): Promise<UnifiedSecretsBlob> {
+  if (unifiedSecretsCache) {
+    return unifiedSecretsCache;
+  }
+
+  const raw = await Bun.secrets.get({
+    service: SERVICE_NAME,
+    name: UNIFIED_SECRETS_KEY,
+  });
+
+  unifiedSecretsCache = parseUnifiedSecretsBlob(raw);
+  if (unifiedSecretsCache.metadata.legacyMigrationComplete) {
+    legacyEntriesDetected = unifiedSecretsCache.metadata.legacyEntriesRetained;
+  }
+  return unifiedSecretsCache;
+}
+
+async function saveUnifiedSecretsBlob(blob: UnifiedSecretsBlob): Promise<void> {
+  const normalized: UnifiedSecretsBlob = {
+    global: { ...blob.global },
+    projects: { ...blob.projects },
+    metadata: {
+      schemaVersion: UNIFIED_SECRETS_SCHEMA_VERSION,
+      legacyMigrationComplete: blob.metadata.legacyMigrationComplete === true,
+      legacyEntriesRetained: blob.metadata.legacyEntriesRetained === true,
+    },
+  };
+  unifiedSecretsCache = normalized;
+
+  await Bun.secrets.set({
+    service: SERVICE_NAME,
+    name: UNIFIED_SECRETS_KEY,
+    value: JSON.stringify(normalized),
+  });
+}
 
 /**
  * Clear the in-memory secrets cache
  * Useful for long-running processes that need fresh values
  */
 export function clearSecretsCache(): void {
-  secretsBlobCache.clear();
+  unifiedSecretsCache = null;
+  legacyProjectBlobChecked.clear();
+  legacyGlobalBlobChecked = false;
+  legacyEntriesDetected = false;
 }
 
 // ============================================================================
@@ -36,38 +170,64 @@ function getProjectSecretsKey(projectName: string): string {
   return `${PROJECT_SECRETS_PREFIX}${projectName}`;
 }
 
-/**
- * Load the secrets blob for a project from keychain (or cache)
- * This is the only function that accesses the keychain for project secrets
- */
-async function loadProjectSecretsBlob(projectName: string): Promise<Record<string, string>> {
-  const keychainKey = getProjectSecretsKey(projectName);
+async function loadLegacyProjectBlob(projectName: string): Promise<{
+  hasLegacyEntry: boolean;
+  secrets: Record<string, string>;
+}> {
+  legacyProjectBlobChecked.add(projectName);
+  const raw = await Bun.secrets.get({
+    service: SERVICE_NAME,
+    name: getProjectSecretsKey(projectName),
+  });
+
+  if (!raw) {
+    return { hasLegacyEntry: false, secrets: {} };
+  }
 
-  // Check cache first
-  if (secretsBlobCache.has(keychainKey)) {
-    return secretsBlobCache.get(keychainKey)!;
+  legacyEntriesDetected = true;
+  try {
+    return { hasLegacyEntry: true, secrets: normalizeRecord(JSON.parse(raw)) };
+  } catch {
+    return { hasLegacyEntry: true, secrets: {} };
   }
+}
 
-  // Load from keychain (triggers one OS prompt)
+async function loadLegacyGlobalBlob(): Promise<{
+  hasLegacyEntry: boolean;
+  secrets: Record<string, string>;
+}> {
+  legacyGlobalBlobChecked = true;
   const raw = await Bun.secrets.get({
     service: SERVICE_NAME,
-    name: keychainKey,
+    name: GLOBAL_SECRETS_KEY,
   });
 
-  // Parse JSON or return empty object
-  let secrets: Record<string, string> = {};
-  if (raw) {
-    try {
-      secrets = JSON.parse(raw);
-    } catch {
-      // Invalid JSON, start fresh
-      secrets = {};
-    }
+  if (!raw) {
+    return { hasLegacyEntry: false, secrets: {} };
   }
 
-  // Cache the loaded blob
-  secretsBlobCache.set(keychainKey, secrets);
-  return secrets;
+  legacyEntriesDetected = true;
+  try {
+    return { hasLegacyEntry: true, secrets: normalizeRecord(JSON.parse(raw)) };
+  } catch {
+    return { hasLegacyEntry: true, secrets: {} };
+  }
+}
+
+function mergeSecrets(
+  existing: Record<string, string>,
+  legacy: Record<string, string>
+): Record<string, string> {
+  // New-format values win if both are present.
+  return { ...legacy, ...existing };
+}
+
+/**
+ * Load project secrets from the unified blob.
+ */
+async function loadProjectSecretsBlob(projectName: string): Promise<Record<string, string>> {
+  const blob = await loadUnifiedSecretsBlob();
+  return { ...(blob.projects[projectName] || {}) };
 }
 
 /**
@@ -77,25 +237,13 @@ async function saveProjectSecretsBlob(
   projectName: string,
   secrets: Record<string, string>
 ): Promise<void> {
-  const keychainKey = getProjectSecretsKey(projectName);
-
-  // Update cache
-  secretsBlobCache.set(keychainKey, secrets);
-
-  // Save to keychain
+  const blob = await loadUnifiedSecretsBlob();
   if (Object.keys(secrets).length === 0) {
-    // Delete the entry if no secrets remain
-    await Bun.secrets.delete({
-      service: SERVICE_NAME,
-      name: keychainKey,
-    });
+    delete blob.projects[projectName];
   } else {
-    await Bun.secrets.set({
-      service: SERVICE_NAME,
-      name: keychainKey,
-      value: JSON.stringify(secrets),
-    });
+    blob.projects[projectName] = { ...secrets };
   }
+  await saveUnifiedSecretsBlob(blob);
 }
 
 /**
@@ -121,11 +269,28 @@ export async function getProjectSecret(
   projectName: string,
   key: string
 ): Promise<string | null> {
-  const secrets = await loadProjectSecretsBlob(projectName);
+  const blob = await loadUnifiedSecretsBlob();
+  const current = blob.projects[projectName] || {};
 
   // Found in new format
-  if (secrets[key] !== undefined) {
-    return secrets[key];
+  if (current[key] !== undefined) {
+    return current[key];
+  }
+
+  if (isLegacyMigrationComplete(blob)) {
+    return null;
+  }
+
+  // Try legacy project blob format: project:<name>
+  if (!legacyProjectBlobChecked.has(projectName)) {
+    const legacyBlob = await loadLegacyProjectBlob(projectName);
+    if (legacyBlob.hasLegacyEntry) {
+      blob.projects[projectName] = mergeSecrets(current, legacyBlob.secrets);
+      await saveUnifiedSecretsBlob(blob);
+      if (blob.projects[projectName][key] !== undefined) {
+        return blob.projects[projectName][key];
+      }
+    }
   }
 
   // Try old format: ${projectName}:${key}
@@ -136,15 +301,12 @@ export async function getProjectSecret(
   });
 
   if (oldValue) {
-    // Migrate to new format automatically
-    secrets[key] = oldValue;
-    await saveProjectSecretsBlob(projectName, secrets);
-
-    // Delete old entry
-    await Bun.secrets.delete({
-      service: SERVICE_NAME,
-      name: oldKeychainName,
-    });
+    legacyEntriesDetected = true;
+    blob.projects[projectName] = {
+      ...(blob.projects[projectName] || {}),
+      [key]: oldValue,
+    };
+    await saveUnifiedSecretsBlob(blob);
 
     return oldValue;
   }
@@ -176,15 +338,53 @@ export async function getProjectSecrets(
   projectName: string,
   keys: string[]
 ): Promise<Record<string, string>> {
-  const secrets = await loadProjectSecretsBlob(projectName);
+  const blob = await loadUnifiedSecretsBlob();
+  let secrets = blob.projects[projectName] || {};
+  let changed = false;
+
+  if (!isLegacyMigrationComplete(blob) && !legacyProjectBlobChecked.has(projectName)) {
+    const legacyBlob = await loadLegacyProjectBlob(projectName);
+    if (legacyBlob.hasLegacyEntry) {
+      secrets = mergeSecrets(secrets, legacyBlob.secrets);
+      blob.projects[projectName] = secrets;
+      changed = true;
+    }
+  }
+
   const result: Record<string, string> = {};
 
   for (const key of keys) {
     if (key in secrets) {
       result[key] = secrets[key];
+      continue;
+    }
+
+    if (isLegacyMigrationComplete(blob)) {
+      continue;
+    }
+
+    // Legacy per-secret fallback (very old format)
+    const oldKeychainName = `${projectName}:${key}`;
+    const oldValue = await Bun.secrets.get({
+      service: SERVICE_NAME,
+      name: oldKeychainName,
+    });
+
+    if (oldValue) {
+      legacyEntriesDetected = true;
+      result[key] = oldValue;
+      blob.projects[projectName] = {
+        ...(blob.projects[projectName] || {}),
+        [key]: oldValue,
+      };
+      changed = true;
     }
   }
 
+  if (changed) {
+    await saveUnifiedSecretsBlob(blob);
+  }
+
   return result;
 }
 
@@ -219,12 +419,9 @@ export async function deleteProjectSecrets(
  * Used when removing a project entirely
  */
 export async function deleteAllProjectSecrets(projectName: string): Promise<void> {
-  const keychainKey = getProjectSecretsKey(projectName);
-  secretsBlobCache.delete(keychainKey);
-  await Bun.secrets.delete({
-    service: SERVICE_NAME,
-    name: keychainKey,
-  });
+  const blob = await loadUnifiedSecretsBlob();
+  delete blob.projects[projectName];
+  await saveUnifiedSecretsBlob(blob);
 }
 
 // ============================================================================
@@ -232,58 +429,20 @@ export async function deleteAllProjectSecrets(projectName: string): Promise<void
 // ============================================================================
 
 /**
- * Load the global secrets blob from keychain (or cache)
- * This is the only function that accesses the keychain for global secrets
+ * Load global secrets from the unified blob.
  */
 async function loadGlobalSecretsBlob(): Promise<Record<string, string>> {
-  // Check cache first
-  if (secretsBlobCache.has(GLOBAL_SECRETS_KEY)) {
-    return secretsBlobCache.get(GLOBAL_SECRETS_KEY)!;
-  }
-
-  // Load from keychain (triggers one OS prompt)
-  const raw = await Bun.secrets.get({
-    service: SERVICE_NAME,
-    name: GLOBAL_SECRETS_KEY,
-  });
-
-  // Parse JSON or return empty object
-  let secrets: Record<string, string> = {};
-  if (raw) {
-    try {
-      secrets = JSON.parse(raw);
-    } catch {
-      // Invalid JSON, start fresh
-      secrets = {};
-    }
-  }
-
-  // Cache the loaded blob
-  secretsBlobCache.set(GLOBAL_SECRETS_KEY, secrets);
-  return secrets;
+  const blob = await loadUnifiedSecretsBlob();
+  return { ...blob.global };
 }
 
 /**
  * Save the global secrets blob to keychain
  */
 async function saveGlobalSecretsBlob(secrets: Record<string, string>): Promise<void> {
-  // Update cache
-  secretsBlobCache.set(GLOBAL_SECRETS_KEY, secrets);
-
-  // Save to keychain
-  if (Object.keys(secrets).length === 0) {
-    // Delete the entry if no secrets remain
-    await Bun.secrets.delete({
-      service: SERVICE_NAME,
-      name: GLOBAL_SECRETS_KEY,
-    });
-  } else {
-    await Bun.secrets.set({
-      service: SERVICE_NAME,
-      name: GLOBAL_SECRETS_KEY,
-      value: JSON.stringify(secrets),
-    });
-  }
+  const blob = await loadUnifiedSecretsBlob();
+  blob.global = { ...secrets };
+  await saveUnifiedSecretsBlob(blob);
 }
 
 /**
@@ -303,13 +462,30 @@ export async function setSecret(key: string, value: string): Promise<void> {
  * format for seamless migration from older versions.
  */
 export async function getSecret(key: string): Promise<string | null> {
-  const secrets = await loadGlobalSecretsBlob();
+  const blob = await loadUnifiedSecretsBlob();
+  const secrets = blob.global;
 
   // Found in new format
   if (secrets[key] !== undefined) {
     return secrets[key];
   }
 
+  if (isLegacyMigrationComplete(blob)) {
+    return null;
+  }
+
+  // Try legacy global blob format: global
+  if (!legacyGlobalBlobChecked) {
+    const legacyBlob = await loadLegacyGlobalBlob();
+    if (legacyBlob.hasLegacyEntry) {
+      blob.global = mergeSecrets(blob.global, legacyBlob.secrets);
+      await saveUnifiedSecretsBlob(blob);
+      if (blob.global[key] !== undefined) {
+        return blob.global[key];
+      }
+    }
+  }
+
   // Try old format: direct key name
   const oldValue = await Bun.secrets.get({
     service: SERVICE_NAME,
@@ -317,15 +493,9 @@ export async function getSecret(key: string): Promise<string | null> {
   });
 
   if (oldValue) {
-    // Migrate to new format automatically
-    secrets[key] = oldValue;
-    await saveGlobalSecretsBlob(secrets);
-
-    // Delete old entry
-    await Bun.secrets.delete({
-      service: SERVICE_NAME,
-      name: key,
-    });
+    legacyEntriesDetected = true;
+    blob.global[key] = oldValue;
+    await saveUnifiedSecretsBlob(blob);
 
     return oldValue;
   }
@@ -346,6 +516,204 @@ export async function deleteSecret(key: string): Promise<boolean> {
   return true;
 }
 
+export interface PreloadAllSecretsResult {
+  legacyEntriesDetected: boolean;
+  importedLegacyProjectEntries: number;
+  importedLegacyGlobalEntry: boolean;
+}
+
+export interface PreloadAllSecretsOptions {
+  globalLegacyKeys?: string[];
+  projectLegacyKeys?: Record<string, string[]>;
+}
+
+/**
+ * Preload all secrets for the process into memory.
+ * This is intended to be called once at startup (serve + TUI).
+ */
+export async function preloadAllSecrets(
+  projectNames: string[],
+  options: PreloadAllSecretsOptions = {}
+): Promise<PreloadAllSecretsResult> {
+  const blob = await loadUnifiedSecretsBlob();
+
+  if (isLegacyMigrationComplete(blob)) {
+    legacyEntriesDetected = blob.metadata.legacyEntriesRetained;
+    return {
+      legacyEntriesDetected,
+      importedLegacyProjectEntries: 0,
+      importedLegacyGlobalEntry: false,
+    };
+  }
+
+  let importedLegacyProjectEntries = 0;
+  let importedLegacyGlobalEntry = false;
+  let changed = false;
+  let detectedLegacyEntries = false;
+
+  const projectLegacyKeys = options.projectLegacyKeys ?? {};
+  const globalLegacyKeys = [...new Set(options.globalLegacyKeys ?? [])];
+
+  const projectNamesToCheck = [...new Set([...projectNames, ...Object.keys(projectLegacyKeys)])];
+
+  for (const projectName of projectNamesToCheck) {
+    const legacyProject = await loadLegacyProjectBlob(projectName);
+    if (!legacyProject.hasLegacyEntry) {
+      // continue with per-key migration below
+    } else {
+      detectedLegacyEntries = true;
+      importedLegacyProjectEntries += 1;
+      const current = blob.projects[projectName] || {};
+      const merged = mergeSecrets(current, legacyProject.secrets);
+      if (JSON.stringify(current) !== JSON.stringify(merged)) {
+        blob.projects[projectName] = merged;
+        changed = true;
+      }
+    }
+
+    const oldKeys = [...new Set(projectLegacyKeys[projectName] ?? [])];
+    for (const key of oldKeys) {
+      const oldValue = await Bun.secrets.get({
+        service: SERVICE_NAME,
+        name: `${projectName}:${key}`,
+      });
+
+      if (!oldValue) {
+        continue;
+      }
+
+      detectedLegacyEntries = true;
+      const currentProjectSecrets = blob.projects[projectName] || {};
+      if (currentProjectSecrets[key] === undefined) {
+        blob.projects[projectName] = {
+          ...currentProjectSecrets,
+          [key]: oldValue,
+        };
+        changed = true;
+      }
+    }
+  }
+
+  const legacyGlobal = await loadLegacyGlobalBlob();
+  if (legacyGlobal.hasLegacyEntry) {
+    detectedLegacyEntries = true;
+    importedLegacyGlobalEntry = true;
+    const merged = mergeSecrets(blob.global, legacyGlobal.secrets);
+    if (JSON.stringify(blob.global) !== JSON.stringify(merged)) {
+      blob.global = merged;
+      changed = true;
+    }
+  }
+
+  for (const key of globalLegacyKeys) {
+    const oldValue = await Bun.secrets.get({
+      service: SERVICE_NAME,
+      name: key,
+    });
+
+    if (!oldValue) {
+      continue;
+    }
+
+    detectedLegacyEntries = true;
+    if (blob.global[key] === undefined) {
+      blob.global[key] = oldValue;
+      changed = true;
+    }
+  }
+
+  blob.metadata.legacyMigrationComplete = true;
+  blob.metadata.legacyEntriesRetained = detectedLegacyEntries;
+  changed = true;
+
+  legacyEntriesDetected = detectedLegacyEntries;
+
+  if (changed) {
+    await saveUnifiedSecretsBlob(blob);
+  }
+
+  return {
+    legacyEntriesDetected,
+    importedLegacyProjectEntries,
+    importedLegacyGlobalEntry,
+  };
+}
+
+export function hasLegacyEntriesInProcess(): boolean {
+  return legacyEntriesDetected;
+}
+
+export interface CleanupLegacySecretsResult {
+  deleted: number;
+  missing: number;
+  errors: string[];
+}
+
+export interface CleanupLegacySecretsOptions {
+  globalLegacyKeys?: string[];
+  projectLegacyKeys?: Record<string, string[]>;
+}
+
+/**
+ * Remove legacy keychain entries now that unified secrets are in use.
+ * This only removes legacy blob entries (`project:*`, `global`).
+ *
+ * TODO(v0.3+): remove legacy blob reads and this cleanup path once
+ * unified secrets storage has been stable for several releases.
+ */
+export async function cleanupLegacySecretEntries(
+  projectNames: string[],
+  options: CleanupLegacySecretsOptions = {}
+): Promise<CleanupLegacySecretsResult> {
+  const result: CleanupLegacySecretsResult = {
+    deleted: 0,
+    missing: 0,
+    errors: [],
+  };
+
+  const projectLegacyKeys = options.projectLegacyKeys ?? {};
+  const globalLegacyKeys = options.globalLegacyKeys ?? [];
+
+  const entries = new Set<string>([
+    GLOBAL_SECRETS_KEY,
+    ...[...new Set(projectNames)].map((name) => getProjectSecretsKey(name)),
+    ...globalLegacyKeys,
+  ]);
+
+  for (const [projectName, keys] of Object.entries(projectLegacyKeys)) {
+    for (const key of keys) {
+      entries.add(`${projectName}:${key}`);
+    }
+  }
+
+  for (const name of entries) {
+    try {
+      const deleted = await Bun.secrets.delete({
+        service: SERVICE_NAME,
+        name,
+      });
+      if (deleted) {
+        result.deleted += 1;
+      } else {
+        result.missing += 1;
+      }
+    } catch (error) {
+      result.errors.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  if (result.errors.length === 0) {
+    const blob = await loadUnifiedSecretsBlob();
+    if (blob.metadata.legacyEntriesRetained) {
+      blob.metadata.legacyEntriesRetained = false;
+      await saveUnifiedSecretsBlob(blob);
+    }
+    legacyEntriesDetected = false;
+  }
+
+  return result;
+}
+
 // ============================================================================
 // Migration from old format (one keychain entry per secret)
 // ============================================================================