fix: send SSH keepalive on idle SFTP sessions to prevent NAT drop (#669) (#671)

The main openSftp() connection path was building ssh2 connect options
without setting keepaliveInterval at all, so no SSH-level keepalive
packets were sent on the SFTP channel. When the SFTP panel sits idle
(the common case while a user browses files), NAT/firewall state
tables reap the idle TCP connection after ~30-60s, causing the panel
to disconnect while the SSH terminal next to it — which has its own
keepalive config via sshBridge — stays connected. That matches the
exact symptom reported in #669.

Default to a 10s keepalive interval, matching the existing SFTP jump
host path (sftpBridge.cjs:466-467). Honor an explicitly configured
positive options.keepaliveInterval (in seconds) if one is passed in,
so the frontend can thread the user setting through later without
another bridge change.

Closes #669

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/workflows/build.yml

@@ -43,6 +43,21 @@ jobs:
       - name: Install deps
         run: npm ci
 
+      - name: Install cross-platform native binaries
+        shell: bash
+        run: |
+          # npm ci only installs optional deps for the host platform, but
+          # electron-builder produces both arm64 and x64 binaries, so we
+          # need the native codex-acp binary for the other architecture too.
+          # Platform-specific codex-acp packages declare cpu/os constraints,
+          # so --force is needed to install the non-host-arch binary.
+          CODEX_VER=$(node -e "console.log(require('./node_modules/@zed-industries/codex-acp/package.json').version)")
+          if [[ "${{ matrix.name }}" == "macos" ]]; then
+            npm install "@zed-industries/codex-acp-darwin-x64@${CODEX_VER}" "@zed-industries/codex-acp-darwin-arm64@${CODEX_VER}" --no-save --force
+          elif [[ "${{ matrix.name }}" == "windows" ]]; then
+            npm install "@zed-industries/codex-acp-win32-x64@${CODEX_VER}" "@zed-industries/codex-acp-win32-arm64@${CODEX_VER}" --no-save --force
+          fi
+
       - name: Set version
         shell: bash
         run: |

App.tsx

@@ -32,6 +32,7 @@ import { Input } from './components/ui/input';
 import { Label } from './components/ui/label';
 import { ToastProvider, toast } from './components/ui/toast';
 import { VaultView, VaultSection } from './components/VaultView';
+import { QuickAddSnippetDialog } from './components/QuickAddSnippetDialog';
 import { KeyboardInteractiveModal, KeyboardInteractiveRequest } from './components/KeyboardInteractiveModal';
 import { PassphraseModal, PassphraseRequest } from './components/PassphraseModal';
 import { cn } from './lib/utils';
@@ -1538,6 +1539,17 @@ function App({ settings }: { settings: SettingsState }) {
         })}
       </div>
 
+      {/* Global "quick add snippet" dialog, triggered by the
+          netcatty:snippets:add window event (from ScriptsSidePanel "+"). */}
+      <QuickAddSnippetDialog
+        snippets={snippets}
+        packages={snippetPackages}
+        onCreateSnippet={(snippet) => updateSnippets([...snippets, snippet])}
+        onCreatePackage={(pkg) =>
+          updateSnippetPackages(Array.from(new Set([...snippetPackages, pkg])))
+        }
+      />
+
       {isQuickSwitcherOpen && (
         <Suspense fallback={null}>
           <LazyQuickSwitcher

application/i18n/locales/en.ts

@@ -237,9 +237,9 @@ const en: Messages = {
   'settings.appearance.themeColor.dark': 'Dark palette',
   'settings.appearance.customCss': 'Custom CSS',
   'settings.appearance.customCss.desc':
-    'Add custom CSS to personalize the app appearance. Changes apply immediately.',
+    'Add custom CSS to personalize the app appearance. Changes apply immediately. Major UI regions expose a [data-section="..."] attribute you can target — e.g. snippets-panel, host-details-panel, group-details-panel, serial-host-details-panel, ai-chat-panel, vault-sidebar, vault-main, vault-hosts-header, vault-host-list, vault-view, terminal-workspace, terminal-workspace-sidebar, top-tabs.',
   'settings.appearance.customCss.placeholder':
-    '/* Example: */\n.terminal { background: #1a1a2e !important; }\n:root { --radius: 0.25rem; }',
+    '/* Examples — use !important to beat Tailwind utility specificity */\n\n/* Make snippet sidebar text larger */\n[data-section="snippets-panel"] {\n  font-size: 14px !important;\n}\n\n/* Custom terminal background */\n.terminal { background: #1a1a2e !important; }\n\n/* Tweak global border radius */\n:root { --radius: 0.25rem; }',
   'settings.appearance.language': 'Language',
   'settings.appearance.language.desc': 'Choose the UI language',
   'settings.appearance.uiFont': 'Interface Font',

application/i18n/locales/zh-CN.ts

@@ -220,9 +220,10 @@ const zhCN: Messages = {
   'settings.appearance.themeColor.light': '浅色主题',
   'settings.appearance.themeColor.dark': '深色主题',
   'settings.appearance.customCss': '自定义 CSS',
-  'settings.appearance.customCss.desc': '使用自定义 CSS 个性化界面，修改会立即生效。',
+  'settings.appearance.customCss.desc':
+    '使用自定义 CSS 个性化界面，修改会立即生效。主要 UI 区块都暴露了 [data-section="..."] 属性供你定位，比如：snippets-panel、host-details-panel、group-details-panel、serial-host-details-panel、ai-chat-panel、vault-sidebar、vault-main、vault-hosts-header、vault-host-list、vault-view、terminal-workspace、terminal-workspace-sidebar、top-tabs。',
   'settings.appearance.customCss.placeholder':
-    '/* 示例：*/\n.terminal { background: #1a1a2e !important; }\n:root { --radius: 0.25rem; }',
+    '/* 示例 — 由于 Tailwind 优先级较高，需要使用 !important */\n\n/* 放大代码片段侧边栏字号 */\n[data-section="snippets-panel"] {\n  font-size: 14px !important;\n}\n\n/* 自定义终端背景色 */\n.terminal { background: #1a1a2e !important; }\n\n/* 调整全局圆角 */\n:root { --radius: 0.25rem; }',
   'settings.appearance.language': '语言',
   'settings.appearance.language.desc': '选择界面语言',
   'settings.appearance.uiFont': '界面字体',

components/AIChatSidePanel.tsx

@@ -775,7 +775,7 @@ const AIChatSidePanelInner: React.FC<AIChatSidePanelProps> = ({
   if (!isVisible) return null;
 
   return (
-    <div className="flex flex-col h-full bg-background">
+    <div className="flex flex-col h-full bg-background" data-section="ai-chat-panel">
       {/* ── Header ── */}
       <div className="px-2.5 py-1.5 flex items-center justify-between border-b border-border/50 shrink-0">
         <AgentSelector

components/GroupDetailsPanel.tsx

@@ -39,6 +39,7 @@ import {
 import {
   AsidePanel,
   AsidePanelContent,
+  type AsidePanelLayout,
 } from "./ui/aside-panel";
 import { Badge } from "./ui/badge";
 import { Button } from "./ui/button";
@@ -63,6 +64,7 @@ interface GroupDetailsPanelProps {
   terminalFontSize: number;
   onSave: (config: GroupConfig, newName?: string, newParent?: string | null) => void;
   onCancel: () => void;
+  layout?: AsidePanelLayout;
 }
 
 const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
@@ -76,6 +78,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
   terminalFontSize,
   onSave,
   onCancel,
+  layout = "overlay",
 }) => {
   const { t } = useI18n();
   const availableFonts = useAvailableFonts();
@@ -351,6 +354,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         onClearProxy={clearProxyConfig}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -368,6 +372,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         onClearChain={clearHostChain}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -395,6 +400,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         }}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -411,6 +417,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         onClose={onCancel}
         onBack={() => setActiveSubPanel("none")}
         showBackButton={true}
+        layout={layout}
       />
     );
   }
@@ -426,7 +433,9 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
       open={true}
       onClose={onCancel}
       width="w-[380px]"
+      dataSection="group-details-panel"
       title={t("vault.groups.details")}
+      layout={layout}
       actions={
         <Button
           variant="ghost"

components/HostDetailsPanel.tsx

@@ -51,6 +51,7 @@ import {
   AsidePanel,
   AsidePanelContent,
   AsidePanelFooter,
+  type AsidePanelLayout,
 } from "./ui/aside-panel";
 import { Badge } from "./ui/badge";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./ui/tooltip";
@@ -100,6 +101,7 @@ interface HostDetailsPanelProps {
   onCreateGroup?: (groupPath: string) => void; // Callback to create a new group
   onCreateTag?: (tag: string) => void; // Callback to create a new tag
   groupDefaults?: Partial<import('../domain/models').GroupConfig>;
+  layout?: AsidePanelLayout;
 }
 
 const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
@@ -118,6 +120,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
   onCreateGroup,
   onCreateTag,
   groupDefaults,
+  layout = "overlay",
 }) => {
   const { t } = useI18n();
   const { checkSshAgent } = useApplicationBackend();
@@ -502,6 +505,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onSave={handleCreateGroup}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -514,6 +518,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onClearProxy={clearProxyConfig}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -531,6 +536,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onClearChain={clearHostChain}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -559,6 +565,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         }}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -576,6 +583,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onClose={onCancel}
         onBack={() => setActiveSubPanel("none")}
         showBackButton={true}
+        layout={layout}
       />
     );
   }
@@ -614,6 +622,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onClose={onCancel}
         onBack={() => setActiveSubPanel("none")}
         showBackButton={true}
+        layout={layout}
       />
     );
   }
@@ -624,6 +633,8 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
       open={true}
       onClose={onCancel}
       width="w-[420px]"
+      layout={layout}
+      dataSection="host-details-panel"
       title={
         initialData ? t("hostDetails.title.details") : t("hostDetails.title.new")
       }

components/KeychainManager.tsx

@@ -515,12 +515,12 @@ echo $3 >> "$FILE"`);
       {/* Main Content */}
       <div
         className={cn(
-          "flex-1 overflow-y-auto transition-all duration-200",
+          "flex-1 flex flex-col min-h-0 transition-all duration-200",
           panel.type !== "closed" && "mr-[380px]",
         )}
       >
         {/* Toolbar */}
-        <div className="flex flex-wrap items-center gap-3 bg-secondary/60 border-b border-border/70 px-3 py-1.5">
+        <div className="flex flex-wrap items-center gap-3 bg-secondary/60 border-b border-border/70 px-3 py-1.5 shrink-0">
           {/* Filter Tabs */}
           <div className="flex items-center gap-1">
             {/* KEY button with split interaction: left=switch view, right=dropdown */}
@@ -684,8 +684,10 @@ echo $3 >> "$FILE"`);
           </div>
         </div>
 
-        {/* Keys Section */}
-        <div className="space-y-3 p-3">
+        {/* Scrollable Content */}
+        <div className="flex-1 overflow-y-auto">
+          {/* Keys Section */}
+          <div className="space-y-3 p-3">
           <div className="flex items-center justify-between">
             <h2 className="text-base font-semibold text-muted-foreground">
               {t("keychain.section.keys")}
@@ -817,6 +819,7 @@ echo $3 >> "$FILE"`);
             </div>
           </div>
         )}
+        </div>
       </div>
 
       {/* Slide-out Panel */}

components/QuickAddSnippetDialog.tsx

@@ -0,0 +1,185 @@
+/**
+ * QuickAddSnippetDialog — lightweight "new snippet" modal mounted at the
+ * App root and triggered by the `netcatty:snippets:add` window event.
+ *
+ * Intentionally minimal: label + command + package only. Advanced fields
+ * (target hosts, shortkey, tags) can be set later via the full Snippets
+ * manager. This keeps the user in their terminal context instead of
+ * navigating to the Vault view just to add a command.
+ */
+
+import { Package } from 'lucide-react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useI18n } from '../application/i18n/I18nProvider';
+import type { Snippet } from '../domain/models';
+import { Button } from './ui/button';
+import { Combobox } from './ui/combobox';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from './ui/dialog';
+import { Input } from './ui/input';
+import { Label } from './ui/label';
+import { Textarea } from './ui/textarea';
+
+export interface QuickAddSnippetDialogProps {
+  snippets: Snippet[];
+  packages: string[];
+  onCreateSnippet: (snippet: Snippet) => void;
+  onCreatePackage?: (packagePath: string) => void;
+}
+
+export const QuickAddSnippetDialog: React.FC<QuickAddSnippetDialogProps> = ({
+  snippets,
+  packages,
+  onCreateSnippet,
+  onCreatePackage,
+}) => {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(false);
+  const [label, setLabel] = useState('');
+  const [command, setCommand] = useState('');
+  const [packagePath, setPackagePath] = useState('');
+  const labelInputRef = useRef<HTMLInputElement>(null);
+
+  // Listen for the global "add snippet" request dispatched by the
+  // terminal-side ScriptsSidePanel + button. We reset form state on
+  // every open so stale input from a previous cancel does not leak.
+  useEffect(() => {
+    const handler = () => {
+      setLabel('');
+      setCommand('');
+      setPackagePath('');
+      setOpen(true);
+    };
+    window.addEventListener('netcatty:snippets:add', handler);
+    return () => window.removeEventListener('netcatty:snippets:add', handler);
+  }, []);
+
+  // Auto-focus the label input once the dialog renders, so the user can
+  // start typing immediately after clicking the + button.
+  useEffect(() => {
+    if (!open) return;
+    const id = window.setTimeout(() => labelInputRef.current?.focus(), 50);
+    return () => window.clearTimeout(id);
+  }, [open]);
+
+  // Derive combobox options from the union of existing packages (from
+  // props) and any package path referenced by an existing snippet, so
+  // the user can reuse anything they see in the main snippets view.
+  const packageOptions = useMemo(() => {
+    const set = new Set<string>();
+    for (const p of packages) {
+      if (p) set.add(p);
+    }
+    for (const s of snippets) {
+      if (s.package) set.add(s.package);
+    }
+    return Array.from(set).sort().map((value) => ({ value, label: value }));
+  }, [packages, snippets]);
+
+  const canSave = label.trim().length > 0 && command.trim().length > 0;
+
+  const handleSave = useCallback(() => {
+    if (!canSave) return;
+    const trimmedPackage = packagePath.trim();
+    // If the user typed a brand new package name, surface it to the parent
+    // so it can be added to the user's package list alongside the snippet.
+    if (trimmedPackage && !packages.includes(trimmedPackage)) {
+      onCreatePackage?.(trimmedPackage);
+    }
+    onCreateSnippet({
+      id: crypto.randomUUID(),
+      label: label.trim(),
+      command, // preserve whitespace in multi-line commands
+      tags: [],
+      package: trimmedPackage || '',
+      targets: [],
+    });
+    setOpen(false);
+  }, [canSave, packagePath, packages, onCreatePackage, onCreateSnippet, label, command]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      // Cmd/Ctrl+Enter from anywhere in the dialog saves the snippet.
+      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter' && canSave) {
+        e.preventDefault();
+        handleSave();
+      }
+    },
+    [canSave, handleSave],
+  );
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogContent className="max-w-md" onKeyDown={handleKeyDown}>
+        <DialogHeader>
+          <DialogTitle>{t('snippets.panel.newTitle')}</DialogTitle>
+          <DialogDescription>
+            {t('snippets.empty.desc')}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3">
+          <div className="space-y-1.5">
+            <Label htmlFor="quick-add-snippet-label" className="text-xs">
+              {t('snippets.field.description')}
+            </Label>
+            <Input
+              id="quick-add-snippet-label"
+              ref={labelInputRef}
+              value={label}
+              onChange={(e) => setLabel(e.target.value)}
+              placeholder={t('snippets.field.descriptionPlaceholder')}
+              className="h-9"
+            />
+          </div>
+
+          <div className="space-y-1.5">
+            <Label htmlFor="quick-add-snippet-command" className="text-xs">
+              {t('snippets.field.scriptRequired')}
+            </Label>
+            <Textarea
+              id="quick-add-snippet-command"
+              value={command}
+              onChange={(e) => setCommand(e.target.value)}
+              placeholder="echo hello"
+              className="min-h-[120px] font-mono text-xs"
+              spellCheck={false}
+            />
+          </div>
+
+          <div className="space-y-1.5">
+            <Label className="text-xs flex items-center gap-1.5">
+              <Package size={12} /> {t('snippets.field.package')}
+            </Label>
+            <Combobox
+              value={packagePath}
+              onValueChange={setPackagePath}
+              options={packageOptions}
+              placeholder={t('snippets.field.packagePlaceholder')}
+              allowCreate
+              onCreateNew={setPackagePath}
+              createText={t('snippets.field.createPackage')}
+            />
+          </div>
+        </div>
+
+        <DialogFooter>
+          <Button variant="outline" onClick={() => setOpen(false)}>
+            {t('common.cancel')}
+          </Button>
+          <Button onClick={handleSave} disabled={!canSave}>
+            {t('common.save')}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+};
+
+export default QuickAddSnippetDialog;

components/ScriptsSidePanel.tsx

@@ -5,7 +5,7 @@
  * Clicking a snippet executes it in the focused terminal session.
  */
 
-import { ChevronRight, Package, Search, Zap } from 'lucide-react';
+import { ChevronRight, Package, Plus, Search, Zap } from 'lucide-react';
 import React, { memo, useCallback, useMemo, useState } from 'react';
 import { useI18n } from '../application/i18n/I18nProvider';
 import { cn } from '../lib/utils';
@@ -119,15 +119,25 @@ const ScriptsSidePanelInner: React.FC<ScriptsSidePanelProps> = ({
     onSnippetClick(command, noAutoRun);
   }, [onSnippetClick]);
 
+  const handleAddSnippet = useCallback(() => {
+    // Let the App shell listen and navigate to the Snippets section with
+    // the "add" panel pre-opened, so the user does not have to leave the
+    // terminal to jump back and click "New Snippet".
+    window.dispatchEvent(new CustomEvent('netcatty:snippets:add'));
+  }, []);
+
   if (!isVisible) return null;
 
   const hasAnyContent = snippets.length > 0 || packages.length > 0;
 
   return (
-    <div className="h-full flex flex-col bg-background overflow-hidden">
-      {/* Search */}
-      <div className="shrink-0 px-2 py-1.5 border-b border-border/50">
-        <div className="relative">
+    <div
+      className="h-full flex flex-col bg-background overflow-hidden"
+      data-section="snippets-panel"
+    >
+      {/* Search + Add */}
+      <div className="shrink-0 px-2 py-1.5 border-b border-border/50 flex items-center gap-1.5">
+        <div className="relative flex-1 min-w-0">
           <Search size={12} className="absolute left-2 top-1/2 -translate-y-1/2 text-muted-foreground" />
           <Input
             value={search}
@@ -136,6 +146,15 @@ const ScriptsSidePanelInner: React.FC<ScriptsSidePanelProps> = ({
             className="h-7 pl-7 text-xs bg-muted/30 border-none"
           />
         </div>
+        <button
+          type="button"
+          onClick={handleAddSnippet}
+          title={t('snippets.action.newSnippet')}
+          aria-label={t('snippets.action.newSnippet')}
+          className="shrink-0 h-7 w-7 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/60 transition-colors"
+        >
+          <Plus size={14} />
+        </button>
       </div>
 
       {/* Breadcrumb */}

components/SelectHostPanel.tsx

@@ -1,11 +1,9 @@
 import {
-  ArrowLeft,
   Check,
   ChevronRight,
   LayoutGrid,
   Plus,
   Search,
-  X,
 } from "lucide-react";
 import React, { useMemo, useState } from "react";
 import { cn } from "../lib/utils";
@@ -14,6 +12,7 @@ import { Host, SSHKey } from "../types";
 import { ManagedSource } from "../domain/models";
 import { DistroAvatar } from "./DistroAvatar";
 import HostDetailsPanel from "./HostDetailsPanel";
+import { AsidePanel, type AsidePanelLayout } from "./ui/aside-panel";
 import { Button } from "./ui/button";
 import { Input } from "./ui/input";
 import { ScrollArea } from "./ui/scroll-area";
@@ -44,6 +43,7 @@ interface SelectHostPanelProps {
   title?: string;
   subtitle?: string;
   className?: string;
+  layout?: AsidePanelLayout;
 }
 
 const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
@@ -63,6 +63,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
   title,
   subtitle,
   className,
+  layout = "overlay",
 }) => {
   const { t } = useI18n();
   const panelTitle = title ?? t("selectHost.title");
@@ -205,35 +206,20 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
 
   return (
     <TooltipProvider delayDuration={300}>
-    <div
+    <AsidePanel
+      open={true}
+      onClose={onBack}
+      title={panelTitle}
+      subtitle={subtitle}
+      showBackButton={true}
+      onBack={onBack}
       className={cn(
-        "absolute right-0 top-0 bottom-0 w-[380px] border-l border-border/60 bg-background z-40 flex flex-col app-no-drag",
+        layout === "overlay" && "z-40",
+        showNewHostPanel && "overflow-visible",
         className,
       )}
+      layout={layout}
     >
-      {/* Header */}
-      <div className="px-4 py-3 border-b border-border/60 flex items-center justify-between gap-3 shrink-0">
-        <div className="flex items-center gap-3 min-w-0">
-          <button
-            onClick={onBack}
-            className="p-1 hover:bg-muted rounded-md transition-colors cursor-pointer shrink-0"
-          >
-            <ArrowLeft size={18} />
-          </button>
-          <div className="min-w-0">
-            <h3 className="text-sm font-semibold">{panelTitle}</h3>
-            {subtitle && (
-              <p className="text-xs text-muted-foreground">{subtitle}</p>
-            )}
-          </div>
-        </div>
-        <button
-          onClick={onBack}
-          className="p-1.5 hover:bg-muted rounded-md transition-colors cursor-pointer shrink-0"
-        >
-          <X size={18} />
-        </button>
-      </div>
 
       {/* Toolbar */}
       <div className="px-4 py-3 flex items-center gap-2 border-b border-border/60 shrink-0">
@@ -277,7 +263,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
       </div>
 
       {/* Content */}
-      <ScrollArea className="flex-1">
+      <ScrollArea className="flex-1 min-w-0">
         <div className="p-3 space-y-3">
           {/* Breadcrumbs */}
           {currentPath && (
@@ -398,7 +384,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
       </ScrollArea>
 
       {/* Footer */}
-      <div className="px-4 py-3 border-t border-border/60">
+      <div className="px-4 py-3 border-t border-border/60 shrink-0">
         <Button
           className="w-full"
           disabled={selectedHostIds.length === 0}
@@ -436,7 +422,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
           onCreateGroup={onCreateGroup}
         />
       )}
-    </div>
+    </AsidePanel>
     </TooltipProvider>
   );
 };

components/SerialHostDetailsPanel.tsx

@@ -17,6 +17,7 @@ import {
   AsidePanel,
   AsidePanelContent,
   AsidePanelFooter,
+  type AsidePanelLayout,
 } from './ui/aside-panel';
 
 interface SerialPort {
@@ -35,6 +36,7 @@ interface SerialHostDetailsPanelProps {
   groups?: string[];
   onSave: (host: Host) => void;
   onCancel: () => void;
+  layout?: AsidePanelLayout;
 }
 
 const BAUD_RATES = [300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600];
@@ -49,6 +51,7 @@ export const SerialHostDetailsPanel: React.FC<SerialHostDetailsPanelProps> = ({
   groups = [],
   onSave,
   onCancel,
+  layout = 'overlay',
 }) => {
   const { t } = useI18n();
   const terminalBackend = useTerminalBackend();
@@ -164,6 +167,8 @@ export const SerialHostDetailsPanel: React.FC<SerialHostDetailsPanelProps> = ({
       title={t('serial.edit.title')}
       subtitle={initialData.label}
       className="z-40"
+      layout={layout}
+      dataSection="serial-host-details-panel"
     >
       <AsidePanelContent>
         {/* Label */}

components/SnippetsManager.tsx

@@ -8,7 +8,7 @@ import { Host, ShellHistoryEntry, Snippet, SSHKey } from '../types';
 import { HotkeyScheme, KeyBinding, keyEventToString, ManagedSource, matchesKeyBinding, parseKeyCombo } from '../domain/models';
 import { DistroAvatar } from './DistroAvatar';
 import SelectHostPanel from './SelectHostPanel';
-import { AsidePanel, AsidePanelContent } from './ui/aside-panel';
+import { AsidePanel, AsidePanelContent, AsidePanelFooter } from './ui/aside-panel';
 import { Button } from './ui/button';
 import { Card } from './ui/card';
 import { Combobox, ComboboxOption } from './ui/combobox';
@@ -721,6 +721,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           onSaveHost={onSaveHost}
           onCreateGroup={onCreateGroup}
           title={t('snippets.targets.add')}
+          layout="inline"
         />
       );
     }
@@ -731,6 +732,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           open={true}
           onClose={handleClosePanel}
           title={editingSnippet.id ? t('snippets.panel.editTitle') : t('snippets.panel.newTitle')}
+          layout="inline"
           actions={
             <Button
               variant="ghost"
@@ -884,7 +886,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           </AsidePanelContent>
 
           {/* Footer */}
-          <div className="px-4 py-3 border-t border-border/60 shrink-0">
+          <AsidePanelFooter>
             <Button
               className="w-full"
               onClick={handleSubmit}
@@ -892,7 +894,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
             >
               {editingSnippet.targets?.length ? t('action.run') : t('common.save')}
             </Button>
-          </div>
+          </AsidePanelFooter>
         </AsidePanel>
       );
     }
@@ -906,6 +908,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           subtitle={t('snippets.history.subtitle', { count: shellHistory.length })}
           showBackButton={true}
           onBack={handleClosePanel}
+          layout="inline"
         >
           {/* History List */}
           <div
@@ -953,7 +956,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
 
   return (
     <TooltipProvider delayDuration={300}>
-    <div className="h-full flex gap-3 relative">
+    <div className="h-full min-h-0 flex relative">
       <div className="flex-1 flex flex-col min-h-0 min-w-0 overflow-hidden">
         <header className="border-b border-border/50 bg-secondary/80 backdrop-blur">
           <div className="h-14 px-4 py-2 flex items-center gap-2">

components/TerminalLayer.tsx

@@ -1819,7 +1819,10 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     if (!activeWorkspace || !isFocusMode) return null;
 
     return (
-      <div className="w-56 flex-shrink-0 bg-secondary/50 border-r border-border/50 flex flex-col">
+      <div
+        className="w-56 flex-shrink-0 bg-secondary/50 border-r border-border/50 flex flex-col"
+        data-section="terminal-workspace-sidebar"
+      >
         {/* Header with view toggle */}
         <div className="h-10 flex items-center justify-between px-3 border-b border-border/50">
           <span className="text-xs font-medium text-muted-foreground">
@@ -1890,6 +1893,7 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
       <div
         ref={workspaceOuterRef}
         className="absolute inset-0 bg-background flex flex-col"
+        data-section="terminal-workspace"
         style={{
           visibility: isTerminalLayerVisible ? 'visible' : 'hidden',
           pointerEvents: isTerminalLayerVisible ? 'auto' : 'none',

components/ThemeSelectPanel.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import {
     AsidePanel,
     AsidePanelContent,
+    type AsidePanelLayout,
 } from './ui/aside-panel';
 import { ScrollArea } from './ui/scroll-area';
 import { ThemeList } from './ThemeList';
@@ -13,6 +14,7 @@ interface ThemeSelectPanelProps {
     onClose: () => void;
     onBack?: () => void;
     showBackButton?: boolean;
+    layout?: AsidePanelLayout;
 }
 
 const ThemeSelectPanel: React.FC<ThemeSelectPanelProps> = ({
@@ -22,6 +24,7 @@ const ThemeSelectPanel: React.FC<ThemeSelectPanelProps> = ({
     onClose,
     onBack,
     showBackButton = true,
+    layout = 'overlay',
 }) => {
     return (
         <AsidePanel
@@ -30,6 +33,7 @@ const ThemeSelectPanel: React.FC<ThemeSelectPanelProps> = ({
             title="Select Color Theme"
             showBackButton={showBackButton}
             onBack={onBack}
+            layout={layout}
         >
             <AsidePanelContent className="p-0">
                 <ScrollArea className="h-full">

components/TopTabs.tsx

@@ -765,6 +765,7 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
   return (
     <div
       data-top-tabs-root
+      data-section="top-tabs"
       className="relative w-full bg-secondary app-drag"
       style={{
         ...dragRegionNoSelect,

components/VaultView.tsx

@@ -957,19 +957,12 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
     }
     return filtered
       .sort((a, b) => (b.lastConnectedAt || 0) - (a.lastConnectedAt || 0))
-      .slice(0, 20);
+      .slice(0, 6);
   }, [hosts, selectedGroupPath, search, selectedTags]);
 
-  // IDs of hosts already shown in Pinned/Recent sections at root level,
-  // so the main host list can exclude them to avoid duplicates.
-  const pinnedRecentIds = useMemo(() => {
-    const ids = new Set<string>();
-    for (const h of pinnedHosts) ids.add(h.id);
-    if (showRecentHosts) {
-      for (const h of recentHosts) ids.add(h.id);
-    }
-    return ids;
-  }, [pinnedHosts, recentHosts, showRecentHosts]);
+  // No longer deduplicate pinned/recent hosts from the main list,
+  // so hosts always appear in their groups regardless of pinned/recent status.
+  const pinnedRecentIds = useMemo(() => new Set<string>(), []);
 
   // For tree view: apply search, tag filter, and sorting, but not group filtering
   const treeViewHosts = useMemo(() => {
@@ -1450,6 +1443,15 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
   }, [managedSources]);
 
   const isHostsSectionActive = currentSection === "hosts";
+  const hasHostsSidePanel =
+    isHostsSectionActive &&
+    ((isGroupPanelOpen && !!editingGroupPath) || isHostPanelOpen);
+  const splitViewGridStyle = hasHostsSidePanel
+    ? {
+      gridTemplateColumns: "repeat(auto-fill, minmax(min(100%, 220px), 280px))",
+      justifyContent: "start" as const,
+    }
+    : undefined;
 
   const isSameDropTarget = useCallback((a: DropTarget | null, b: DropTarget | null) => {
     if (!a || !b) return a === b;
@@ -1552,13 +1554,16 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
 
   // Component no longer handles visibility - that's done by VaultViewWrapper
   return (
-    <div ref={rootRef} className="absolute inset-0 min-h-0 flex">
+    <div ref={rootRef} className="absolute inset-0 min-h-0 flex" data-section="vault-view">
       {/* Sidebar */}
       <TooltipProvider delayDuration={100}>
-        <div className={cn(
-          "bg-secondary/80 border-r border-border/60 flex flex-col transition-all duration-200",
-          sidebarCollapsed ? "w-14" : "w-52"
-        )}>
+        <div
+          className={cn(
+            "bg-secondary/80 border-r border-border/60 flex flex-col transition-all duration-200",
+            sidebarCollapsed ? "w-14" : "w-52"
+          )}
+          data-section="vault-sidebar"
+        >
           <div className={cn(
             "py-4 flex items-center",
             sidebarCollapsed ? "px-2 justify-center" : "px-4"
@@ -1721,12 +1726,16 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
       </TooltipProvider>
 
       {/* Main Area */}
-      <div className="flex-1 flex flex-col min-h-0 relative">
+      <div
+        className="flex-1 min-w-0 flex flex-col min-h-0 relative"
+        data-section="vault-main"
+      >
         <header
           className={cn(
             "border-b border-border/50 bg-secondary/80 backdrop-blur app-drag",
             !isHostsSectionActive && "hidden",
           )}
+          data-section="vault-hosts-header"
         >
           <div className="h-14 px-4 py-2 flex items-center gap-3">
             <div className="relative flex-1 app-no-drag">
@@ -1830,14 +1839,25 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                 <CheckSquare size={16} />
               </Button>
             </div>
-            {/* New Host split button */}
-            <div className="flex items-center app-no-drag">
+            {/* New Host split button — collapses with an animation when the
+                host details / new-host aside panel is open, since the button
+                would be a no-op in that state. */}
+            <div
+              className={cn(
+                "flex items-center app-no-drag overflow-hidden transition-[max-width,opacity,margin] duration-200 ease-in-out",
+                isHostPanelOpen
+                  ? "max-w-0 opacity-0 -ml-2 pointer-events-none"
+                  : "max-w-[260px] opacity-100",
+              )}
+              aria-hidden={isHostPanelOpen}
+            >
               <Dropdown>
                 <div className="flex items-center rounded-md bg-primary text-primary-foreground">
                   <Button
                     size="sm"
                     className="h-10 px-3 rounded-r-none bg-transparent hover:bg-white/10 shadow-none app-no-drag"
                     onClick={handleNewHost}
+                    tabIndex={isHostPanelOpen ? -1 : 0}
                   >
                     <Plus size={14} className="mr-2" /> {t("vault.hosts.newHost")}
                   </Button>
@@ -1845,6 +1865,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                     <Button
                       size="sm"
                       className="h-10 px-2 rounded-l-none bg-transparent hover:bg-white/10 border-l border-primary-foreground/20 shadow-none app-no-drag"
+                      tabIndex={isHostPanelOpen ? -1 : 0}
                     >
                       <ChevronDown size={14} />
                     </Button>
@@ -1881,22 +1902,37 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                 </DropdownContent>
               </Dropdown>
             </div>
-            <Button
-              size="sm"
-              variant="secondary"
-              className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
-              onClick={onCreateLocalTerminal}
+            {/* Terminal + Serial — collapse together with an animation when
+                the host details / new-host aside panel is open, freeing
+                horizontal space for the panel. */}
+            <div
+              className={cn(
+                "flex items-center gap-3 overflow-hidden transition-[max-width,opacity,margin] duration-200 ease-in-out",
+                isHostPanelOpen
+                  ? "max-w-0 opacity-0 -ml-3 pointer-events-none"
+                  : "max-w-[320px] opacity-100",
+              )}
+              aria-hidden={isHostPanelOpen}
             >
-              <TerminalSquare size={14} className="mr-2" /> {t("common.terminal")}
-            </Button>
-            <Button
-              size="sm"
-              variant="secondary"
-              className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
-              onClick={() => setIsSerialModalOpen(true)}
-            >
-              <Usb size={14} className="mr-2" /> {t("serial.button")}
-            </Button>
+              <Button
+                size="sm"
+                variant="secondary"
+                className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
+                onClick={onCreateLocalTerminal}
+                tabIndex={isHostPanelOpen ? -1 : 0}
+              >
+                <TerminalSquare size={14} className="mr-2" /> {t("common.terminal")}
+              </Button>
+              <Button
+                size="sm"
+                variant="secondary"
+                className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
+                onClick={() => setIsSerialModalOpen(true)}
+                tabIndex={isHostPanelOpen ? -1 : 0}
+              >
+                <Usb size={14} className="mr-2" /> {t("serial.button")}
+              </Button>
+            </div>
           </div>
         </header>
 
@@ -1906,6 +1942,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
             "flex-1 overflow-auto px-4 py-4 space-y-6",
             !isHostsSectionActive && "hidden",
           )}
+          data-section="vault-host-list"
           onDragEndCapture={() => setDragOverDropTarget(null)}
         >
                 <section className="space-y-2">
@@ -1980,9 +2017,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                       </h3>
                       <div className={cn(
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
-                      )}>
+                      )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}>
                         {pinnedHosts.map((host) => {
                           const safeHost = sanitizeHost(host);
                           const effectiveDistro = getEffectiveHostDistro(safeHost);
@@ -2080,9 +2121,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                       </h3>
                       <div className={cn(
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
-                      )}>
+                      )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}>
                         {recentHosts.map((host) => {
                           const safeHost = sanitizeHost(host);
                           const effectiveDistro = getEffectiveHostDistro(safeHost);
@@ -2181,9 +2226,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                       className={cn(
                         displayedGroups.length === 0 ? "hidden" : "",
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
                       )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}
                       onDragOver={(e) => {
                         e.preventDefault();
                       }}
@@ -2421,9 +2470,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                             <div
                               className={cn(
                                 viewMode === "grid"
-                                  ? "grid gap-3 grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                                  ? cn(
+                                    "grid gap-3",
+                                    !hasHostsSidePanel && "grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                                  )
                                   : "flex flex-col gap-0",
                               )}
+                              style={viewMode === "grid" ? splitViewGridStyle : undefined}
                             >
                               {group.hosts.filter((h) => selectedGroupPath || !pinnedRecentIds.has(h.id)).map((host) => {
                                 const safeHost = sanitizeHost(host);
@@ -2562,9 +2615,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                     <div
                       className={cn(
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
                       )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}
                     >
                       {displayedHosts.filter((h) => selectedGroupPath || !pinnedRecentIds.has(h.id)).map((host) => {
                           const safeHost = sanitizeHost(host);
@@ -2830,6 +2887,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
             setIsGroupPanelOpen(false);
             setEditingGroupPath(null);
           }}
+          layout="inline"
         />
       )}
 
@@ -2869,6 +2927,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
               Array.from(new Set([...customGroups, groupPath])),
             );
           }}
+          layout="inline"
         />
       )}
 
@@ -2889,6 +2948,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
             setIsHostPanelOpen(false);
             setEditingHost(null);
           }}
+          layout="inline"
         />
       )}
 

components/host-details/ChainPanel.tsx

@@ -7,7 +7,7 @@ import React, { useMemo, useState } from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { Host } from '../../types';
 import { DistroAvatar } from '../DistroAvatar';
-import { AsidePanel } from '../ui/aside-panel';
+import { AsidePanel, type AsidePanelLayout } from '../ui/aside-panel';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
 import { Input } from '../ui/input';
@@ -24,6 +24,7 @@ export interface ChainPanelProps {
     onClearChain: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const ChainPanel: React.FC<ChainPanelProps> = ({
@@ -37,6 +38,7 @@ export const ChainPanel: React.FC<ChainPanelProps> = ({
     onClearChain,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     const [searchQuery, setSearchQuery] = useState('');
@@ -54,6 +56,7 @@ export const ChainPanel: React.FC<ChainPanelProps> = ({
             title={t('hostDetails.chain.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onBack}>
                     {t('common.save')}

components/host-details/CreateGroupPanel.tsx

@@ -5,7 +5,7 @@
 import { FolderPlus,HelpCircle,Plus } from 'lucide-react';
 import React from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
-import { AsidePanel,AsidePanelContent } from '../ui/aside-panel';
+import { AsidePanel,AsidePanelContent,type AsidePanelLayout } from '../ui/aside-panel';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
 import { Input } from '../ui/input';
@@ -42,6 +42,7 @@ export interface CreateGroupPanelProps {
     onSave: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const CreateGroupPanel: React.FC<CreateGroupPanelProps> = ({
@@ -53,6 +54,7 @@ export const CreateGroupPanel: React.FC<CreateGroupPanelProps> = ({
     onSave,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     return (
@@ -62,6 +64,7 @@ export const CreateGroupPanel: React.FC<CreateGroupPanelProps> = ({
             title={t('hostDetails.group.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onSave} disabled={!newGroupName.trim()}>
                     {t('common.save')}

components/host-details/EnvVarsPanel.tsx

@@ -6,7 +6,7 @@ import { Plus,X } from 'lucide-react';
 import React from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { EnvVar } from '../../types';
-import { AsidePanel,AsidePanelContent } from '../ui/aside-panel';
+import { AsidePanel,AsidePanelContent,type AsidePanelLayout } from '../ui/aside-panel';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
 import { Input } from '../ui/input';
@@ -25,6 +25,7 @@ export interface EnvVarsPanelProps {
     onSave: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const EnvVarsPanel: React.FC<EnvVarsPanelProps> = ({
@@ -41,6 +42,7 @@ export const EnvVarsPanel: React.FC<EnvVarsPanelProps> = ({
     onSave,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     return (
@@ -50,6 +52,7 @@ export const EnvVarsPanel: React.FC<EnvVarsPanelProps> = ({
             title={t('hostDetails.envVars.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onSave}>
                     {t('common.save')}

components/host-details/ProxyPanel.tsx

@@ -7,7 +7,7 @@ import React from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { cn } from '../../lib/utils';
 import { ProxyConfig } from '../../types';
-import { AsidePanel,AsidePanelContent } from '../ui/aside-panel';
+import { AsidePanel,AsidePanelContent,type AsidePanelLayout } from '../ui/aside-panel';
 import { Badge } from '../ui/badge';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
@@ -19,6 +19,7 @@ export interface ProxyPanelProps {
     onClearProxy: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const ProxyPanel: React.FC<ProxyPanelProps> = ({
@@ -27,6 +28,7 @@ export const ProxyPanel: React.FC<ProxyPanelProps> = ({
     onClearProxy,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     return (
@@ -36,6 +38,7 @@ export const ProxyPanel: React.FC<ProxyPanelProps> = ({
             title={t('hostDetails.proxyPanel.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onBack} disabled={!proxyConfig?.host}>
                     {t('common.save')}

components/terminal/clearTerminalViewport.ts

@@ -0,0 +1,85 @@
+import type { Terminal as XTerm } from "@xterm/xterm";
+
+type CsiParam = number | number[];
+type InternalTerminal = XTerm & {
+  _core?: {
+    scroll?: (eraseAttr: unknown, isWrapped?: boolean) => void;
+    _inputHandler?: {
+      _eraseAttrData?: () => unknown;
+    };
+  };
+};
+
+const getVisibleContentRowCount = (term: XTerm): number => {
+  const buffer = term.buffer.active;
+  if (buffer.type !== "normal") {
+    return 0;
+  }
+
+  const baseY = buffer.baseY;
+  for (let row = term.rows - 1; row >= 0; row--) {
+    const line = buffer.getLine(baseY + row);
+    if (!line) {
+      continue;
+    }
+    if (line.translateToString(true).length > 0) {
+      return row + 1;
+    }
+  }
+
+  return 0;
+};
+
+export const preserveTerminalViewportInScrollback = (term: XTerm): void => {
+  const rowsToPreserve = getVisibleContentRowCount(term);
+  if (rowsToPreserve <= 0) {
+    return;
+  }
+
+  const internal = term as InternalTerminal;
+  const scroll = internal._core?.scroll;
+  const eraseAttr = internal._core?._inputHandler?._eraseAttrData?.();
+
+  if (typeof scroll !== "function" || eraseAttr === undefined) {
+    return;
+  }
+
+  for (let row = 0; row < rowsToPreserve; row++) {
+    scroll.call(internal._core, eraseAttr, false);
+  }
+};
+
+export const clearTerminalViewport = (term: XTerm): void => {
+  const buffer = term.buffer.active;
+  if (buffer.type !== "normal") return;
+
+  const cursorY = buffer.cursorY;
+  const cursorX = buffer.cursorX;
+
+  if (cursorY === 0 && buffer.baseY === 0) return;
+
+  const internal = term as InternalTerminal;
+  const scroll = internal._core?.scroll;
+  const eraseAttr = internal._core?._inputHandler?._eraseAttrData?.();
+
+  if (typeof scroll !== "function" || eraseAttr === undefined) return;
+
+  // Push lines above cursor into scrollback so they are preserved.
+  // After cursorY scrolls the prompt line shifts to active-screen row 0.
+  for (let i = 0; i < cursorY; i++) {
+    scroll.call(internal._core, eraseAttr, false);
+  }
+
+  // Clear everything below the prompt and reposition the cursor on it.
+  // CSI coordinates are 1-indexed.
+  const col = cursorX + 1;
+  term.write(`\x1b[2;1H\x1b[J\x1b[1;${col}H`, () => {
+    term.scrollToBottom();
+  });
+};
+
+export const isEraseScrollbackSequence = (params: CsiParam[]): boolean =>
+  params.length > 0 && params[0] === 3;
+
+export const isEraseViewportSequence = (params: CsiParam[]): boolean =>
+  params.length > 0 && params[0] === 2;

components/terminal/hooks/useTerminalContextActions.ts

@@ -3,6 +3,7 @@ import { useCallback } from "react";
 import type { RefObject } from "react";
 import { logger } from "../../../lib/logger";
 import { normalizeLineEndings, wrapBracketedPaste } from "../../../lib/utils";
+import { clearTerminalViewport } from "../clearTerminalViewport";
 
 type TerminalBackendWriteApi = {
   writeToSession: (sessionId: string, data: string) => void;
@@ -65,7 +66,7 @@ export const useTerminalContextActions = ({
   const onClear = useCallback(() => {
     const term = termRef.current;
     if (!term) return;
-    term.clear();
+    clearTerminalViewport(term);
   }, [termRef]);
 
   const onSelectWord = useCallback(() => {

components/terminal/runtime/createXTermRuntime.ts

@@ -31,6 +31,12 @@ import {
 import { logger } from "../../../lib/logger";
 import { isMacPlatform, normalizeLineEndings, wrapBracketedPaste } from "../../../lib/utils";
 import { netcattyBridge } from "../../../infrastructure/services/netcattyBridge";
+import {
+  clearTerminalViewport,
+  isEraseViewportSequence,
+  isEraseScrollbackSequence,
+  preserveTerminalViewportInScrollback,
+} from "../clearTerminalViewport";
 import type {
   Host,
   KeyBinding,
@@ -498,7 +504,7 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
           break;
         }
         case "clearBuffer": {
-          term.clear();
+          clearTerminalViewport(term);
           break;
         }
         case "searchTerminal": {
@@ -641,6 +647,17 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
   // OSC 7 format: \x1b]7;file://hostname/path\x07 or \x1b]7;file://hostname/path\x1b\\
   let currentCwd: string | undefined = undefined;
 
+  const eraseScrollbackDisposable = term.parser.registerCsiHandler({ final: "J" }, (params) => {
+    if (isEraseViewportSequence(params)) {
+      preserveTerminalViewportInScrollback(term);
+      return false;
+    }
+    if (!isEraseScrollbackSequence(params)) {
+      return false;
+    }
+    return true;
+  });
+
   // Register OSC 7 handler using xterm.js parser
   // OSC 7 is the standard way for shells to report the current working directory
   const osc7Disposable = term.parser.registerOscHandler(7, (data) => {
@@ -763,6 +780,7 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
     dispose: () => {
       cleanupMiddleClick?.();
       keywordHighlighter.dispose();
+      eraseScrollbackDisposable.dispose();
       osc7Disposable.dispose();
       osc52Disposable.dispose();
       try {

components/ui/aside-panel.tsx

@@ -1,5 +1,5 @@
 import { ArrowLeft, MoreVertical, X } from 'lucide-react';
-import React, { createContext, ReactNode, useCallback, useContext, useState } from 'react';
+import React, { createContext, ReactNode, useCallback, useContext, useMemo, useState } from 'react';
 import { cn } from '../../lib/utils';
 import { Popover, PopoverContent, PopoverTrigger } from './popover';
 import { ScrollArea } from './scroll-area';
@@ -44,6 +44,12 @@ interface AsidePanelProps {
     children: ReactNode;
     className?: string;
     width?: string;
+    layout?: AsidePanelLayout;
+    /**
+     * Optional stable identifier emitted as `data-section` on the panel
+     * root. Used as a targeting hook for Custom CSS (Settings → Appearance).
+     */
+    dataSection?: string;
 }
 
 interface AsidePanelHeaderProps {
@@ -171,14 +177,40 @@ interface AsidePanelStackProps {
     initialItem: AsideContentItem;
     className?: string;
     width?: string;
+    layout?: AsidePanelLayout;
+    /**
+     * Optional stable identifier emitted as `data-section` on the panel
+     * root. Used as a targeting hook for Custom CSS.
+     */
+    dataSection?: string;
 }
 
+export type AsidePanelLayout = 'overlay' | 'inline';
+
+const resolveInlineWidth = (width: string) => {
+    const arbitraryWidthMatch = width.match(/w-\[(.+)\]/);
+    if (arbitraryWidthMatch) {
+        return arbitraryWidthMatch[1];
+    }
+
+    switch (width) {
+        case 'w-full':
+            return '100%';
+        case 'w-screen':
+            return '100vw';
+        default:
+            return '380px';
+    }
+};
+
 export const AsidePanelStack: React.FC<AsidePanelStackProps> = ({
     open,
     onClose,
     initialItem,
     className,
     width = 'w-[380px]',
+    layout = 'overlay',
+    dataSection,
 }) => {
     const [stack, setStack] = useState<AsideContentItem[]>([initialItem]);
 
@@ -205,6 +237,13 @@ export const AsidePanelStack: React.FC<AsidePanelStackProps> = ({
 
     const currentItem = stack[stack.length - 1];
     const canGoBack = stack.length > 1;
+    const inlineWidth = useMemo(() => resolveInlineWidth(width), [width]);
+    const inlineStyle = layout === 'inline'
+        ? ({
+            width: inlineWidth,
+            ['--aside-inline-width' as string]: inlineWidth,
+        } as React.CSSProperties)
+        : undefined;
 
     // Reset stack when panel closes/opens
     React.useEffect(() => {
@@ -218,10 +257,14 @@ export const AsidePanelStack: React.FC<AsidePanelStackProps> = ({
     return (
         <AsidePanelContext.Provider value={{ push, pop, replace, clear, canGoBack, currentItem }}>
             <div className={cn(
-                "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
-                width,
+                layout === 'inline'
+                    ? "relative split-panel-enter shrink-0 h-full min-h-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden shadow-[-16px_0_32px_hsl(var(--foreground)/0.08)]"
+                    : "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
+                layout === 'overlay' && width,
                 className
-            )}>
+            )}
+            style={inlineStyle}
+            data-section={dataSection}>
                 <AsidePanelHeader
                     title={currentItem.title}
                     subtitle={currentItem.subtitle}
@@ -248,15 +291,29 @@ export const AsidePanel: React.FC<AsidePanelProps> = ({
     children,
     className,
     width = 'w-[380px]',
+    layout = 'overlay',
+    dataSection,
 }) => {
     if (!open) return null;
 
+    const inlineWidth = resolveInlineWidth(width);
+    const inlineStyle = layout === 'inline'
+        ? ({
+            width: inlineWidth,
+            ['--aside-inline-width' as string]: inlineWidth,
+        } as React.CSSProperties)
+        : undefined;
+
     return (
         <div className={cn(
-            "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
-            width,
+            layout === 'inline'
+                ? "relative split-panel-enter shrink-0 h-full min-h-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden shadow-[-16px_0_32px_hsl(var(--foreground)/0.08)]"
+                : "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
+            layout === 'overlay' && width,
             className
-        )}>
+        )}
+        style={inlineStyle}
+        data-section={dataSection}>
             {title && (
                 <AsidePanelHeader
                     title={title}

electron/bridges/ai/codexHelpers.cjs

@@ -82,13 +82,13 @@ function resolveCodexAcpBinaryPath(shellEnv, electronModule) {
   // Packaged build (or dev fallback): use npm-bundled binary
   try {
     const pkgName = getCodexPackageName();
-    if (!pkgName) return binaryName;
+    if (!pkgName) return null;
 
     const pkgRoot = path.dirname(require.resolve("@zed-industries/codex-acp/package.json"));
     const resolved = require.resolve(`${pkgName}/bin/${binaryName}`, { paths: [pkgRoot] });
     return toUnpackedAsarPath(resolved);
   } catch {
-    return binaryName;
+    return null;
   }
 }
 

electron/bridges/ai/ptyExec.cjs

@@ -145,6 +145,668 @@ function findEndMarker(outputText, marker) {
   return null;
 }
 
+function normalizePtyOutput(stdout, {
+  stripMarkers = false,
+  expectedPrompt = "",
+  trimOutput = true,
+  stripPrompt = true,
+  markerToStrip = null,
+} = {}) {
+  let cleaned = stripAnsi(stdout || "").replace(/\r/g, "");
+  if (stripMarkers) {
+    // Prefer the job-specific marker so user output that contains "__NCMCP_"
+    // (e.g. printf '__NCMCP_demo\n') is preserved.
+    const pattern = markerToStrip
+      ? new RegExp(`^[^\r\n]*${markerToStrip}[^\r\n]*[\r\n]*`, "gm")
+      : /^[^\r\n]*__NCMCP_[^\r\n]*[\r\n]*/gm;
+    cleaned = cleaned.replace(pattern, "");
+  }
+  const normalizedPrompt = stripAnsi(String(expectedPrompt || "")).replace(/\r/g, "");
+  if (stripPrompt && normalizedPrompt && cleaned.endsWith(normalizedPrompt)) {
+    cleaned = cleaned.slice(0, cleaned.length - normalizedPrompt.length);
+  }
+  return trimOutput ? cleaned.trim() : cleaned;
+}
+
+function appendBoundedOutput(current, chunk, maxBufferedChars) {
+  const combined = `${current || ""}${chunk || ""}`;
+  const limit = Number.isFinite(maxBufferedChars) ? Math.max(0, Math.floor(maxBufferedChars)) : 0;
+  if (limit <= 0 || combined.length <= limit) {
+    return { text: combined, dropped: 0 };
+  }
+  const dropped = combined.length - limit;
+  return {
+    text: combined.slice(dropped),
+    dropped,
+  };
+}
+
+function consumeVisibleText(carry, chunk) {
+  const input = `${carry || ""}${chunk || ""}`;
+  if (!input) {
+    return { visibleText: "", carry: "" };
+  }
+
+  let visibleText = "";
+  let index = 0;
+
+  while (index < input.length) {
+    const ch = input[index];
+
+    if (ch === "\r") {
+      // Preserve \r so consumers / serializers can collapse progress-bar
+      // redraws to the latest frame. \r\n becomes a single \n.
+      if (input[index + 1] === "\n") {
+        visibleText += "\n";
+        index += 2;
+        continue;
+      }
+      visibleText += "\r";
+      index += 1;
+      continue;
+    }
+
+    if (ch !== "\u001b") {
+      visibleText += ch;
+      index += 1;
+      continue;
+    }
+
+    if (index + 1 >= input.length) {
+      break;
+    }
+
+    const next = input[index + 1];
+
+    if (next === "[") {
+      let cursor = index + 2;
+      let complete = false;
+      while (cursor < input.length) {
+        const code = input.charCodeAt(cursor);
+        if (code >= 0x40 && code <= 0x7e) {
+          index = cursor + 1;
+          complete = true;
+          break;
+        }
+        cursor += 1;
+      }
+      if (!complete) break;
+      continue;
+    }
+
+    if (next === "]") {
+      let cursor = index + 2;
+      let complete = false;
+      while (cursor < input.length) {
+        const oscChar = input[cursor];
+        if (oscChar === "\u0007") {
+          index = cursor + 1;
+          complete = true;
+          break;
+        }
+        if (oscChar === "\u001b") {
+          if (cursor + 1 >= input.length) break;
+          if (input[cursor + 1] === "\\") {
+            index = cursor + 2;
+            complete = true;
+            break;
+          }
+        }
+        cursor += 1;
+      }
+      if (!complete) break;
+      continue;
+    }
+
+    visibleText += ch;
+    index += 1;
+  }
+
+  return {
+    visibleText,
+    carry: input.slice(index),
+  };
+}
+
+function startPtyJob(ptyStream, command, options) {
+  const {
+    stripMarkers = false,
+    trackForCancellation = null,
+    timeoutMs = 60000,
+    shellKind,
+    chatSessionId,
+    abortSignal,
+    expectedPrompt,
+    typedInput = false,
+    echoCommand,
+    maxBufferedChars = 0,
+    normalizeFinalOutput = true,
+    enforceWallTimeout = false,
+  } = options || {};
+
+  const marker = `__NCMCP_${Date.now().toString(36)}_${crypto.randomBytes(16).toString('hex')}__`;
+  const resolvedShellKind = shellKind || "posix";
+  const CANCEL_RETRY_MS = 5000;
+  const CANCEL_WALL_TIMEOUT_MS = 30000;
+
+  let output = "";
+  let foundStart = false;
+  let preStartOutput = "";
+  let visibleOutput = "";
+  let visibleOutputOffset = 0;
+  // Monotonic high-water mark for the visible byte stream. Increases on every
+  // append; never decreases when CR redraws collapse visibleOutput. Used as
+  // the polling nextOffset so callers' offsets stay monotonic.
+  let visibleHighWatermark = 0;
+  let visibleCarry = "";
+  let timeoutId = null;
+  let wallTimeoutId = null;
+  let startupTimeoutId = null;
+  let promptFallbackTimer = null;
+  let cancelRetryTimerId = null;
+  // Track one-shot timers scheduled inside requestCancel so finish() can
+  // clear them when the job exits early; otherwise they keep the Node
+  // event loop alive after the resultPromise has already resolved.
+  const cancelOneShotTimers = [];
+  let cancelRequested = false;
+  let finished = false;
+  let unsubscribe = null;
+  const cleanupFns = [];
+  let pendingStart = "";
+  let resolveResult;
+  const resultPromise = new Promise((resolve) => {
+    resolveResult = resolve;
+  });
+
+  function clearPromptFallback() {
+    if (promptFallbackTimer) {
+      clearTimeout(promptFallbackTimer);
+      promptFallbackTimer = null;
+    }
+  }
+
+  function clearCancelRetryTimer() {
+    if (cancelRetryTimerId) {
+      clearTimeout(cancelRetryTimerId);
+      cancelRetryTimerId = null;
+    }
+  }
+
+  function armOutputTimeout() {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      sendInterrupt();
+      if (cancelRequested) {
+        armOutputTimeout();
+        return;
+      }
+      const timeoutSec = Math.round(timeoutMs / 1000);
+      finish(foundStart ? output : preStartOutput, -1, `Command timed out after ${timeoutSec}s without output`);
+    }, timeoutMs);
+  }
+
+  // Hard wall-clock deadline: opt-in via enforceWallTimeout. Used by callers
+  // that have a strict tool-call budget (e.g. MCP terminal_execute, where the
+  // model can fall back to terminal_start). Default is off so existing
+  // foreground execution paths (Catty Agent) keep their inactivity-based
+  // timeout for long-running streaming commands.
+  function armWallTimeout() {
+    if (!enforceWallTimeout || maxBufferedChars > 0) return;
+    wallTimeoutId = setTimeout(() => {
+      if (finished) return;
+      sendInterrupt();
+      const timeoutSec = Math.round(timeoutMs / 1000);
+      finish(foundStart ? output : preStartOutput, -1, `Command timed out (${timeoutSec}s)`);
+    }, timeoutMs);
+  }
+
+  // Bounded startup deadline: we always need a hard limit on how long we
+  // wait for the wrapped command's start marker. Otherwise an already-chatty
+  // PTY (e.g. a tab running tail -f) would let onData re-arm the inactivity
+  // timer forever before _S arrives, hanging the call and the session lock.
+  // Foreground execs use the configured timeoutMs as the deadline (matching
+  // the pre-PR behavior); background jobs use a fixed 30s since their main
+  // timeout is much longer (1 hour) and meant for the actual command.
+  const BG_STARTUP_TIMEOUT_MS = 30000;
+  function armStartupTimeout() {
+    const startupMs = maxBufferedChars > 0 ? BG_STARTUP_TIMEOUT_MS : timeoutMs;
+    startupTimeoutId = setTimeout(() => {
+      if (finished || foundStart) return;
+      sendInterrupt();
+      const label = maxBufferedChars > 0 ? "Background job startup" : "Command startup";
+      finish(preStartOutput, -1, `${label} timed out — start marker never arrived`);
+    }, startupMs);
+  }
+  function clearStartupTimeout() {
+    if (startupTimeoutId) {
+      clearTimeout(startupTimeoutId);
+      startupTimeoutId = null;
+    }
+  }
+
+  function sendInterrupt() {
+    try {
+      if (typeof ptyStream.signal === "function") {
+        ptyStream.signal("INT");
+      }
+    } catch {
+      // Ignore signal failures and fall back to ETX.
+    }
+    try {
+      if (typeof ptyStream.write === "function") {
+        ptyStream.write("\x03");
+      }
+    } catch {
+      // Ignore PTY write failures during cancellation.
+    }
+  }
+
+  function requestCancel() {
+    if (finished || cancelRequested) return;
+    cancelRequested = true;
+    clearPromptFallback();
+    clearCancelRetryTimer();
+    // Cancel the startup timer too — otherwise a pre-start cancel resolves
+    // as "Background job startup timed out" instead of "Cancelled".
+    clearStartupTimeout();
+    // For pre-start cancellation on sessions without a known idle prompt,
+    // schedule a short fallback to finish the job after Ctrl+C has had time
+    // to take effect. Without this, the cancel waits the full forced-cancel
+    // window even though the shell may have returned to idle quickly.
+    if (!foundStart && !expectedPrompt) {
+      const t = setTimeout(() => {
+        if (finished || foundStart) return;
+        finish(preStartOutput, 130, "Cancelled");
+      }, 2000);
+      cancelOneShotTimers.push(t);
+    }
+    sendInterrupt();
+    cancelRetryTimerId = setTimeout(function retryCancel() {
+      if (finished || !cancelRequested) return;
+      sendInterrupt();
+      cancelRetryTimerId = setTimeout(retryCancel, CANCEL_RETRY_MS);
+    }, CANCEL_RETRY_MS);
+    armOutputTimeout();
+    const t150 = setTimeout(() => {
+      if (!finished) sendInterrupt();
+    }, 150);
+    cancelOneShotTimers.push(t150);
+    // Hard wall-clock deadline for cancellation: if the process ignores
+    // Ctrl+C and never redraws the prompt, force-finish after a bounded
+    // period so the session is not stuck in "stopping" forever.
+    // Mark as "forced" so callers can tell the shell may still be busy.
+    const tWall = setTimeout(() => {
+      if (!finished) {
+        finish(foundStart ? output : preStartOutput, 130, "Cancelled (forced — process may still be running)");
+      }
+    }, CANCEL_WALL_TIMEOUT_MS);
+    cancelOneShotTimers.push(tWall);
+  }
+
+  function schedulePromptFallback() {
+    clearPromptFallback();
+    if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
+    // Background jobs use a much longer delay (30s) so commands that open
+    // child shells / REPLs with the same prompt have time to print past
+    // their initial prompt and avoid being misdetected as completed.
+    // Foreground execs use 250ms to match the pre-PR behavior.
+    const delayMs = maxBufferedChars > 0 ? 30000 : 250;
+    promptFallbackTimer = setTimeout(() => {
+      if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
+      finish(output, null, null);
+    }, delayMs);
+  }
+
+  function checkEnd() {
+    const found = findEndMarker(output, marker);
+    if (!found) return;
+    const stdout = output.slice(0, found.endIdx);
+    finish(stdout, found.exitCode);
+  }
+
+  // Carry buffer for incomplete marker lines split across chunks.
+  let visibleMarkerCarry = "";
+
+  // Note: we intentionally do NOT collapse CR redraws in visibleOutput.
+  // Doing so makes polling offsets non-monotonic and can drop finalized
+  // lines after a CR rewrite. Instead, the buffer stores raw bytes
+  // (including \r) and the bounded-buffer cap (256KB) keeps progress-bar
+  // accumulation under control. Consumers that want a "collapsed" view
+  // can apply CR processing themselves.
+
+  function appendToVisible(text) {
+    if (!text) return;
+    const normalized = consumeVisibleText(visibleCarry, text);
+    visibleCarry = normalized.carry;
+    if (!normalized.visibleText) return;
+
+    let cleanVisible = normalized.visibleText;
+    if (maxBufferedChars > 0) {
+      // Rejoin with any incomplete line from the previous chunk so marker
+      // lines split across PTY data boundaries are matched as a whole.
+      cleanVisible = visibleMarkerCarry + cleanVisible;
+      visibleMarkerCarry = "";
+      // We must withhold any trailing line that *might* be the start of an
+      // internal marker line, even if the random marker token isn't fully
+      // present yet (the chunk boundary may split the marker mid-token).
+      // Detect this by looking for the constant prefix "__NCMCP_" — only
+      // user output that *contains an unrelated __NCMCP_ string and ends
+      // with a newline* will be preserved through the next strip step.
+      const NCMCP_PREFIX = "__NCMCP_";
+      const lastNl = cleanVisible.lastIndexOf("\n");
+      if (lastNl === -1) {
+        if (cleanVisible.includes(NCMCP_PREFIX)) {
+          visibleMarkerCarry = cleanVisible;
+          return;
+        }
+      } else if (lastNl < cleanVisible.length - 1) {
+        const trailing = cleanVisible.slice(lastNl + 1);
+        if (trailing.includes(NCMCP_PREFIX)) {
+          visibleMarkerCarry = trailing;
+          cleanVisible = cleanVisible.slice(0, lastNl + 1);
+        }
+      }
+      // Strip only this job's specific marker lines so user output that
+      // happens to contain "__NCMCP_" (e.g. printf '__NCMCP_demo\n') is
+      // preserved.
+      cleanVisible = cleanVisible.replace(new RegExp(`^[^\r\n]*${marker}[^\r\n]*[\r\n]*`, "gm"), "");
+      if (!cleanVisible) return;
+    }
+    visibleHighWatermark += cleanVisible.length;
+    const next = appendBoundedOutput(visibleOutput, cleanVisible, maxBufferedChars);
+    visibleOutput = next.text;
+    visibleOutputOffset += next.dropped;
+  }
+
+  function appendToOutput(text) {
+    if (!text) return;
+    const next = appendBoundedOutput(output, text, maxBufferedChars);
+    output = next.text;
+    appendToVisible(text);
+  }
+
+  function finish(stdout, exitCode, error) {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timeoutId);
+    clearTimeout(wallTimeoutId);
+    clearStartupTimeout();
+    clearPromptFallback();
+    clearCancelRetryTimer();
+    // Clear any pending one-shot cancel timers so they do not keep the
+    // Node event loop alive after the job has resolved.
+    while (cancelOneShotTimers.length) {
+      clearTimeout(cancelOneShotTimers.pop());
+    }
+    unsubscribe?.();
+    for (const fn of cleanupFns) {
+      try {
+        fn();
+      } catch {
+        // Ignore cleanup failures
+      }
+    }
+    if (trackForCancellation) {
+      trackForCancellation.delete(marker);
+    }
+
+    // Flush any incomplete marker carry — if it wasn't this job's marker, append it.
+    if (visibleMarkerCarry) {
+      const leftover = visibleMarkerCarry.replace(new RegExp(`^[^\r\n]*${marker}[^\r\n]*[\r\n]*`, "gm"), "");
+      visibleMarkerCarry = "";
+      if (leftover) {
+        const next = appendBoundedOutput(visibleOutput, leftover, maxBufferedChars);
+        visibleOutput = next.text;
+        visibleOutputOffset += next.dropped;
+      }
+    }
+
+    // For background jobs (maxBufferedChars > 0), use the already-stripped
+    // visibleOutput so completion offsets are consistent with polling offsets.
+    // Re-normalizing from the raw buffer would produce a shorter result because
+    // ANSI codes inflate the raw buffer, causing it to truncate earlier.
+    let cleaned;
+    let outputBaseOffset;
+    let totalOutputChars;
+    if (maxBufferedChars > 0 && foundStart) {
+      // Always strip this job's markers from the visible buffer — it accumulates
+      // raw PTY data including the end-marker line that must not leak to callers.
+      const strippedVisible = normalizePtyOutput(visibleOutput, {
+        stripMarkers: true,
+        markerToStrip: marker,
+        expectedPrompt,
+        trimOutput: normalizeFinalOutput,
+        stripPrompt: true,
+      });
+      cleaned = strippedVisible;
+      outputBaseOffset = visibleOutputOffset;
+      totalOutputChars = outputBaseOffset + visibleOutput.length;
+    } else {
+      const visibleStdout = normalizePtyOutput(stdout, {
+        stripMarkers,
+        markerToStrip: marker,
+        expectedPrompt,
+        trimOutput: false,
+        stripPrompt: true,
+      });
+      cleaned = normalizeFinalOutput
+        ? normalizePtyOutput(stdout, {
+          stripMarkers,
+          markerToStrip: marker,
+          expectedPrompt,
+          trimOutput: true,
+          stripPrompt: true,
+        })
+        : visibleStdout;
+      outputBaseOffset = foundStart ? visibleOutputOffset : 0;
+      totalOutputChars = outputBaseOffset + visibleStdout.length;
+    }
+    const finalError = (!error && cancelRequested) ? "Cancelled" : error;
+    const finalExitCode = finalError === "Cancelled" ? (exitCode ?? 130) : exitCode;
+    if (finalError) {
+      resolveResult({
+        ok: false,
+        stdout: cleaned,
+        stderr: "",
+        exitCode: finalExitCode ?? -1,
+        error: finalError,
+        outputBaseOffset,
+        totalOutputChars,
+        outputTruncated: outputBaseOffset > 0,
+      });
+    } else {
+      resolveResult({
+        ok: exitCode === 0 || exitCode === null,
+        stdout: cleaned,
+        stderr: "",
+        exitCode: finalExitCode ?? 0,
+        outputBaseOffset,
+        totalOutputChars,
+        outputTruncated: outputBaseOffset > 0,
+      });
+    }
+  }
+
+  function onData(data) {
+    const text = data.toString();
+    armOutputTimeout();
+
+    if (!foundStart) {
+      preStartOutput += text;
+      // Cap preStartOutput for background jobs so a noisy idle PTY can't
+      // accumulate megabytes before the start marker arrives. We only need
+      // enough tail to find the marker boundary.
+      if (maxBufferedChars > 0 && preStartOutput.length > maxBufferedChars) {
+        preStartOutput = preStartOutput.slice(preStartOutput.length - maxBufferedChars);
+      }
+      const combined = pendingStart + text;
+      pendingStart = "";
+      const startMarker = marker + "_S";
+      let matched = false;
+
+      const lines = combined.split(/\r?\n/);
+      const trailingPartial = /[\r\n]$/.test(combined) ? "" : lines.pop() || "";
+      for (const line of lines) {
+        if (stripAnsi(line).trim() === startMarker) {
+          foundStart = true;
+          matched = true;
+          break;
+        }
+      }
+      pendingStart = trailingPartial;
+
+      if (foundStart) {
+        clearStartupTimeout();
+        // Use the *last* occurrence of the start marker to skip the echoed
+        // wrapper command and capture only output after the real printf line.
+        const markerPattern = new RegExp(`${marker}_S[^\n\r]*(?:\r?\n|$)`, "g");
+        let boundary = -1;
+        let m;
+        while ((m = markerPattern.exec(preStartOutput)) !== null) {
+          boundary = m.index;
+        }
+        if (boundary !== -1) {
+          const afterBoundary = preStartOutput.slice(boundary);
+          const firstNl = afterBoundary.search(/\r?\n/);
+          const initialOutput = firstNl === -1 ? "" : afterBoundary.slice(firstNl).replace(/^\r?\n/, "");
+          output = "";
+          visibleOutput = "";
+          visibleOutputOffset = 0;
+          visibleCarry = "";
+          appendToOutput(initialOutput);
+        }
+        preStartOutput = "";
+        schedulePromptFallback();
+        checkEnd();
+        return;
+      }
+
+      if (!matched) {
+        const fallbackEnd = findEndMarker(preStartOutput, marker);
+        if (fallbackEnd) {
+          let stdout = preStartOutput.slice(0, fallbackEnd.endIdx);
+          const lastStartIdx = stdout.lastIndexOf(startMarker);
+          if (lastStartIdx !== -1) {
+            const nlAfterStart = stdout.indexOf("\n", lastStartIdx);
+            if (nlAfterStart !== -1) {
+              stdout = stdout.slice(nlAfterStart + 1);
+            }
+          }
+          finish(stdout, fallbackEnd.exitCode);
+          return;
+        }
+      }
+      // If we're cancelling a still-queued command and the shell has returned
+      // to its idle prompt, finish immediately as Cancelled instead of waiting
+      // for the cancel wall-clock timer.
+      if (cancelRequested && hasExpectedPromptSuffix(preStartOutput, expectedPrompt)) {
+        finish(preStartOutput, 130, "Cancelled");
+        return;
+      }
+      return;
+    }
+
+    appendToOutput(text);
+    if (!cancelRequested) {
+      schedulePromptFallback();
+    } else if (hasExpectedPromptSuffix(output, expectedPrompt)) {
+      finish(output, 130, "Cancelled");
+      return;
+    }
+    checkEnd();
+  }
+
+  if (abortSignal?.aborted) {
+    finish("", -1, "Cancelled");
+    return {
+      marker,
+      cancel: () => {},
+      getSnapshot: () => ({ stdout: "", status: "cancelled", foundStart: false }),
+      resultPromise,
+    };
+  }
+
+  armOutputTimeout();
+  armWallTimeout();
+  armStartupTimeout();
+
+  unsubscribe = subscribeToPtyData(ptyStream, onData);
+
+  const cancel = () => {
+    requestCancel();
+  };
+
+  if (trackForCancellation) {
+    trackForCancellation.set(marker, {
+      ptyStream,
+      chatSessionId: chatSessionId || null,
+      cancel,
+      cleanup: () => {
+        clearTimeout(timeoutId);
+        unsubscribe?.();
+      },
+    });
+  }
+
+  if (typeof ptyStream.on === "function") {
+    const onClose = () => finish(foundStart ? output : preStartOutput, null, cancelRequested ? "Cancelled" : "Stream closed unexpectedly");
+    const onError = (err) => finish(foundStart ? output : preStartOutput, -1, cancelRequested ? "Cancelled" : `Stream error: ${err?.message || err}`);
+    ptyStream.on("close", onClose);
+    ptyStream.on("end", onClose);
+    ptyStream.on("error", onError);
+    cleanupFns.push(() => {
+      try { ptyStream.removeListener("close", onClose); } catch {}
+      try { ptyStream.removeListener("end", onClose); } catch {}
+      try { ptyStream.removeListener("error", onError); } catch {}
+    });
+  }
+  if (typeof ptyStream.onExit === "function") {
+    const disposable = ptyStream.onExit(() => finish(foundStart ? output : preStartOutput, null, cancelRequested ? "Cancelled" : "Process exited"));
+    cleanupFns.push(() => {
+      try {
+        disposable?.dispose?.();
+      } catch {
+        // Ignore cleanup failures
+      }
+    });
+  }
+
+  if (abortSignal) {
+    const onAbort = () => {
+      requestCancel();
+    };
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    cleanupFns.push(() => abortSignal.removeEventListener("abort", onAbort));
+  }
+
+  if (typedInput && typeof echoCommand === "function") {
+    try {
+      echoCommand(command);
+    } catch {
+      // Ignore synthetic echo failures.
+    }
+  }
+
+  ptyStream.write(buildWrappedCommand(command, resolvedShellKind, marker));
+
+  return {
+    marker,
+    cancel,
+    // Until the start marker arrives, return empty stdout/zero offsets so
+    // an early poll cannot advance nextOffset past pre-start PTY noise that
+    // gets discarded once the real command begins.
+    getSnapshot: () => ({
+      stdout: foundStart ? visibleOutput : "",
+      outputBaseOffset: foundStart ? visibleOutputOffset : 0,
+      totalOutputChars: foundStart ? visibleOutputOffset + visibleOutput.length : 0,
+      outputTruncated: foundStart ? visibleOutputOffset > 0 : false,
+      status: finished ? "finished" : (cancelRequested ? "stopping" : "running"),
+      foundStart,
+    }),
+    resultPromise,
+  };
+}
+
 /**
  * Execute command through a terminal PTY stream.
  * The user sees the command typed and output in their terminal.
@@ -163,228 +825,7 @@ function findEndMarker(outputText, marker) {
  * @param {(command: string) => void} [options.echoCommand] - Callback used to display synthetic command echo
  */
 function execViaPty(ptyStream, command, options) {
-  const {
-    stripMarkers = false,
-    trackForCancellation = null,
-    timeoutMs = 60000,
-    shellKind,
-    chatSessionId,
-    abortSignal,
-    expectedPrompt,
-    typedInput = false,
-    echoCommand,
-  } = options || {};
-
-  const marker = `__NCMCP_${Date.now().toString(36)}_${crypto.randomBytes(16).toString('hex')}__`;
-  const resolvedShellKind = shellKind || "posix";
-
-  // Fast-path: already aborted before we even start
-  if (abortSignal?.aborted) {
-    return Promise.resolve({ ok: false, stdout: "", stderr: "", exitCode: -1, error: "Cancelled" });
-  }
-
-  return new Promise((resolve) => {
-    let output = "";
-    let foundStart = false;
-    let preStartOutput = "";
-    let timeoutId = null;
-    let promptFallbackTimer = null;
-    let finished = false;
-    let unsubscribe = null;
-    const cleanupFns = [];
-
-    // Buffer for incomplete line data when searching for start marker.
-    // SSH channels can split data at arbitrary byte boundaries, so the
-    // start marker may arrive across two chunks.  We keep the content
-    // after the last \n (i.e. the current incomplete line) and prepend
-    // it to the next chunk so indexOf can match the full marker.
-    let pendingStart = "";
-
-    const onData = (data) => {
-      const text = data.toString();
-
-      if (!foundStart) {
-        preStartOutput += text;
-        const combined = pendingStart + text;
-        pendingStart = "";
-        const startMarker = marker + "_S";
-        let matched = false;
-        let pos = 0;
-        while (pos < combined.length) {
-          const idx = combined.indexOf(startMarker, pos);
-          if (idx === -1) break;
-          if (idx === 0 || combined[idx - 1] === '\n' || combined[idx - 1] === '\r') {
-            foundStart = true;
-            matched = true;
-            const afterMarker = combined.slice(idx);
-            const nlIdx = afterMarker.indexOf("\n");
-            if (nlIdx !== -1) {
-              output += afterMarker.slice(nlIdx + 1);
-            }
-            break;
-          }
-          pos = idx + 1;
-        }
-        if (!matched) {
-          // Keep the last incomplete line for cross-chunk matching
-          const lastNl = combined.lastIndexOf("\n");
-          pendingStart = lastNl === -1 ? combined : combined.slice(lastNl + 1);
-        }
-        if (foundStart) {
-          preStartOutput = "";
-          schedulePromptFallback();
-          checkEnd();
-          return;
-        }
-
-        // Fallback: if strict start-marker detection missed (e.g. due shell
-        // control sequence prefixes), still complete as soon as we observe a
-        // valid end marker with exit code.
-        const fallbackEnd = findEndMarker(preStartOutput, marker);
-        if (fallbackEnd) {
-          let stdout = preStartOutput.slice(0, fallbackEnd.endIdx);
-          const lastStartIdx = stdout.lastIndexOf(startMarker);
-          if (lastStartIdx !== -1) {
-            const nlAfterStart = stdout.indexOf("\n", lastStartIdx);
-            if (nlAfterStart !== -1) {
-              stdout = stdout.slice(nlAfterStart + 1);
-            }
-          }
-          finish(stdout, fallbackEnd.exitCode);
-        }
-        return;
-      }
-
-      output += text;
-      schedulePromptFallback();
-      checkEnd();
-    };
-
-    function clearPromptFallback() {
-      if (promptFallbackTimer) {
-        clearTimeout(promptFallbackTimer);
-        promptFallbackTimer = null;
-      }
-    }
-
-    function schedulePromptFallback() {
-      clearPromptFallback();
-      if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
-
-      // Fallback for shells that visibly return to the same idle prompt but
-      // never emit the wrapped end marker line.
-      promptFallbackTimer = setTimeout(() => {
-        if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
-        finish(output, null, null);
-      }, 250);
-    }
-
-    function checkEnd() {
-      // Look for the end marker at a line boundary (actual printf output),
-      // not inside the echo of the printf command argument.
-      const found = findEndMarker(output, marker);
-      if (!found) return;
-      const stdout = output.slice(0, found.endIdx);
-      finish(stdout, found.exitCode);
-    }
-
-    function finish(stdout, exitCode, error) {
-      if (finished) return;
-      finished = true;
-      clearTimeout(timeoutId);
-      clearPromptFallback();
-      unsubscribe?.();
-      for (const fn of cleanupFns) { try { fn(); } catch { /* ignore */ } }
-      if (trackForCancellation) {
-        trackForCancellation.delete(marker);
-      }
-
-      let cleaned = stripAnsi(stdout || "").replace(/\r/g, "");
-      if (stripMarkers) {
-        cleaned = cleaned.replace(/^[^\r\n]*__NCMCP_[^\r\n]*[\r\n]*/gm, "");
-      }
-      const normalizedPrompt = stripAnsi(String(expectedPrompt || "")).replace(/\r/g, "");
-      if (normalizedPrompt && cleaned.endsWith(normalizedPrompt)) {
-        cleaned = cleaned.slice(0, cleaned.length - normalizedPrompt.length);
-      }
-      cleaned = cleaned.trim();
-      if (error) {
-        resolve({ ok: false, stdout: cleaned, stderr: "", exitCode: exitCode ?? -1, error });
-      } else {
-        resolve({
-          ok: exitCode === 0 || exitCode === null,
-          stdout: cleaned,
-          stderr: "",
-          exitCode: exitCode ?? 0,
-        });
-      }
-    }
-
-    timeoutId = setTimeout(() => {
-      // Send Ctrl+C to kill the timed-out command
-      if (typeof ptyStream.write === "function") ptyStream.write("\x03");
-      const timeoutSec = Math.round(timeoutMs / 1000);
-      finish(output, -1, `Command timed out (${timeoutSec}s)`);
-    }, timeoutMs);
-
-    unsubscribe = subscribeToPtyData(ptyStream, onData);
-
-    // Register for cancellation if tracking map provided
-    if (trackForCancellation) {
-      trackForCancellation.set(marker, {
-        ptyStream,
-        chatSessionId: chatSessionId || null,
-        cancel: () => {
-          if (typeof ptyStream.write === "function") ptyStream.write("\x03");
-          finish(output, -1, "Cancelled");
-        },
-        cleanup: () => {
-          clearTimeout(timeoutId);
-          unsubscribe?.();
-        },
-      });
-    }
-
-    // Stream close/error detection — resolve immediately instead of waiting for timeout
-    if (typeof ptyStream.on === "function") {
-      const onClose = () => finish(output, null, "Stream closed unexpectedly");
-      const onError = (err) => finish(output, -1, `Stream error: ${err?.message || err}`);
-      ptyStream.on("close", onClose);
-      ptyStream.on("end", onClose);
-      ptyStream.on("error", onError);
-      cleanupFns.push(() => {
-        try { ptyStream.removeListener("close", onClose); } catch { /* */ }
-        try { ptyStream.removeListener("end", onClose); } catch { /* */ }
-        try { ptyStream.removeListener("error", onError); } catch { /* */ }
-      });
-    }
-    // node-pty uses onExit instead of close/end
-    if (typeof ptyStream.onExit === "function") {
-      const disposable = ptyStream.onExit(() => finish(output, null, "Process exited"));
-      cleanupFns.push(() => { try { disposable?.dispose?.(); } catch { /* */ } });
-    }
-
-    // AbortSignal handling — send Ctrl+C and resolve when aborted
-    if (abortSignal) {
-      const onAbort = () => {
-        if (typeof ptyStream.write === "function") ptyStream.write("\x03");
-        finish(output, -1, "Cancelled");
-      };
-      abortSignal.addEventListener("abort", onAbort, { once: true });
-      cleanupFns.push(() => abortSignal.removeEventListener("abort", onAbort));
-    }
-
-    if (typedInput && typeof echoCommand === "function") {
-      try {
-        echoCommand(command);
-      } catch {
-        // Ignore synthetic echo failures.
-      }
-    }
-
-    // Markers are filtered from terminal display by preload.cjs.
-    ptyStream.write(buildWrappedCommand(command, resolvedShellKind, marker));
-  });
+  return startPtyJob(ptyStream, command, options).resultPromise;
 }
 
 /**
@@ -659,6 +1100,7 @@ execViaRawPty._seq = 0;
 
 module.exports = {
   execViaPty,
+  startPtyJob,
   execViaChannel,
   execViaRawPty,
   detectShellKind,

electron/bridges/aiBridge.cjs

@@ -1029,6 +1029,19 @@ function registerHandlers(ipcMain) {
       return { ok: false, error: "Session not found" };
     }
 
+    // Honor the per-session execution lock so this IPC path does not race with
+    // long-running background jobs started via terminal_start.
+    const busyErr = mcpServerBridge.getSessionBusyError?.(sessionId);
+    if (busyErr) return busyErr;
+    const reservation = mcpServerBridge.reserveSessionExecution?.(sessionId, "exec");
+    if (reservation && !reservation.ok) return reservation;
+    const sessionToken = reservation?.token;
+    const releaseLock = () => {
+      if (sessionToken) {
+        try { mcpServerBridge.releaseSessionExecution?.(sessionId, sessionToken); } catch {}
+      }
+    };
+
     // Look up device type from metadata (set by renderer from Host.deviceType).
     // Mosh sessions use a shell-backed PTY, so network device mode only applies to SSH/serial.
     // Prefer session.protocol (runtime truth) over meta.protocol (renderer hint)
@@ -1043,12 +1056,26 @@ function registerHandlers(ipcMain) {
     if (!isNetworkDevice) {
       const safety = mcpServerBridge.checkCommandSafety(command);
       if (safety.blocked) {
+        releaseLock();
         return { ok: false, error: `Command blocked by safety policy. Pattern: ${safety.matchedPattern}` };
       }
     }
 
+    // Helper: ensure the session lock is released once the promise settles
+    // (or immediately on a synchronous error/early return).
+    const withLockRelease = (factory) => {
+      try {
+        const result = factory();
+        return Promise.resolve(result).finally(releaseLock);
+      } catch (err) {
+        releaseLock();
+        return { ok: false, error: err?.message || String(err) };
+      }
+    };
+
     try {
       if ((session.protocol === "local" || session.type === "local") && session.shellKind === "unknown") {
+        releaseLock();
         return {
           ok: false,
           error: "AI execution is not supported for this local shell executable. Configure the local terminal to use bash/zsh/sh, fish, PowerShell/pwsh, or cmd.exe.",
@@ -1062,18 +1089,18 @@ function registerHandlers(ipcMain) {
       if (isNetworkDevice && ptyStream && typeof ptyStream.write === "function") {
         const { execViaRawPty } = require("./ai/ptyExec.cjs");
         const timeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaRawPty(ptyStream, command, {
+        return withLockRelease(() => execViaRawPty(ptyStream, command, {
           timeoutMs,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           chatSessionId,
           encoding: "utf8", // SSH PTY streams use UTF-8, not latin1
-        });
+        }));
       }
 
       // Prefer PTY stream (visible in terminal)
       if (ptyStream && typeof ptyStream.write === "function") {
         const timeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaPty(ptyStream, command, {
+        return withLockRelease(() => execViaPty(ptyStream, command, {
           stripMarkers: true,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           timeoutMs,
@@ -1089,11 +1116,16 @@ function registerHandlers(ipcMain) {
               syntheticEcho: true,
             });
           },
-        });
+          // Catty Agent has no terminal_start fallback for long-running
+          // commands, so do NOT enforce a hard wall-clock timeout here.
+          // The inactivity timeout still applies, so genuinely hung
+          // processes are still terminated.
+        }));
       }
 
       // Network devices require an interactive PTY for raw command execution.
       if (isNetworkDevice) {
+        releaseLock();
         return { ok: false, error: "Network device session has no writable PTY stream for command execution" };
       }
 
@@ -1102,27 +1134,29 @@ function registerHandlers(ipcMain) {
       if (sshClient && typeof sshClient.exec === "function") {
         const { execViaChannel } = require("./ai/ptyExec.cjs");
         const channelTimeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaChannel(sshClient, command, {
+        return withLockRelease(() => execViaChannel(sshClient, command, {
           timeoutMs: channelTimeoutMs,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           chatSessionId,
-        });
+        }));
       }
 
       // Serial port: raw command execution (no shell wrapping)
       if (session.protocol === "serial" && session.serialPort && typeof session.serialPort.write === "function") {
         const { execViaRawPty } = require("./ai/ptyExec.cjs");
         const serialTimeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaRawPty(session.serialPort, command, {
+        return withLockRelease(() => execViaRawPty(session.serialPort, command, {
           timeoutMs: serialTimeoutMs,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           chatSessionId,
           encoding: session.serialEncoding || "utf8",
-        });
+        }));
       }
 
+      releaseLock();
       return { ok: false, error: "No terminal stream or SSH client available for this session" };
     } catch (err) {
+      releaseLock();
       return { ok: false, error: err?.message || String(err) };
     }
   });
@@ -1208,8 +1242,14 @@ function registerHandlers(ipcMain) {
 
     const { createACPProvider } = require("@mcpc-tech/acp-ai-provider");
     const shellEnv = await getShellEnv();
+    const resolvedCommand = resolveCodexAcpBinaryPath(shellEnv, electronModule);
+    if (!resolvedCommand) {
+      const result = { ok: false, checkedAt: now, error: "codex-acp binary not found", code: "ENOENT" };
+      setCodexValidationCache(result);
+      return result;
+    }
     const provider = createACPProvider({
-      command: resolveCodexAcpBinaryPath(shellEnv, electronModule),
+      command: resolvedCommand,
       env: shellEnv,
       session: {
         cwd: process.cwd(),
@@ -1927,6 +1967,9 @@ function registerHandlers(ipcMain) {
         : claudeAcp
           ? claudeAcp.command
           : acpCommand;
+      if (!resolvedCommand) {
+        return { ok: false, models: [], error: `${agentLabel} binary not found` };
+      }
       const resolvedArgs = claudeAcp
         ? [...claudeAcp.prependArgs, ...(acpArgs || [])]
         : acpArgs || [];
@@ -2117,6 +2160,9 @@ function registerHandlers(ipcMain) {
           : claudeAcp
             ? claudeAcp.command
             : acpCommand;
+        if (!resolvedCommand) {
+          throw new Error(`${agentLabel} binary not found`);
+        }
         const resolvedArgs = claudeAcp
           ? [...claudeAcp.prependArgs, ...(acpArgs || [])]
           : acpArgs || [];
@@ -2185,12 +2231,16 @@ function registerHandlers(ipcMain) {
         cleanupAcpProvider(chatSessionId);
 
         const fallbackClaudeAcp = isClaudeAgent ? resolveClaudeAcpBinaryPath(shellEnv, electronModule) : null;
+        const fallbackCommand = isCodexAgent
+          ? resolveCodexAcpBinaryPath(shellEnv, electronModule)
+          : fallbackClaudeAcp
+            ? fallbackClaudeAcp.command
+            : acpCommand;
+        if (!fallbackCommand) {
+          throw new Error(`${agentLabel} binary not found`);
+        }
         const fallbackProvider = createACPProvider({
-          command: isCodexAgent
-            ? resolveCodexAcpBinaryPath(shellEnv, electronModule)
-            : fallbackClaudeAcp
-              ? fallbackClaudeAcp.command
-              : acpCommand,
+          command: fallbackCommand,
           args: fallbackClaudeAcp
             ? [...fallbackClaudeAcp.prependArgs, ...(acpArgs || [])]
             : acpArgs || [],
@@ -2250,7 +2300,9 @@ function registerHandlers(ipcMain) {
         `Use the "netcatty-remote-hosts" MCP tools to operate only on the terminal sessions exposed by Netcatty. ` +
         `Those sessions may be remote hosts, a local terminal, or Mosh-backed shells. ` +
         `Call get_environment first to discover available sessions and their IDs. ` +
-        `For normal shell commands, use terminal_execute so you receive command output. ` +
+        `Use terminal_execute only for commands likely to finish within about 60 seconds. ` +
+        `For long-running commands such as builds, scans, follow/log streaming, watch commands, or anything likely to exceed 60 seconds on PTY-backed shell sessions, use terminal_start, then terminal_poll until completed is true. Reuse the returned nextOffset for the next poll. If terminal_poll reports outputTruncated=true, only the retained tail starting at outputBaseOffset is still available. Do not poll aggressively: wait at least about 30 seconds between polls, and increase the interval further when there is no new output, to avoid wasting tokens. As soon as completed is true, stop polling and analyze the result immediately. Note: terminal_start requires a PTY-backed session; for sessions that only support exec-channel execution (no writable PTY), use terminal_execute instead. ` +
+        `Use terminal_stop if you need to interrupt a started long-running command. ` +
         `For serial/raw sessions and network device sessions (deviceType: network), commands are sent as-is without shell wrapping and exit codes are unavailable. Use vendor CLI commands directly.]\n\n${prompt}`;
 
       // Build message content: text + optional attachments
@@ -2427,7 +2479,11 @@ function registerHandlers(ipcMain) {
     const effectiveChatSessionId = chatSessionId || acpRequestSessions.get(requestId);
     const activeRun = effectiveChatSessionId ? acpChatRuns.get(effectiveChatSessionId) : null;
     const effectiveRequestId = requestId || activeRun?.requestId || "";
-    // Cancel PTY executions scoped to this chat session (send Ctrl+C)
+    // Cancel synchronous PTY executions scoped to this chat session (send Ctrl+C).
+    // Do NOT cancel terminal_start background jobs here — they were intentionally
+    // launched as long-running and should keep running when the user only wants
+    // to stop the model's polling/output. Background jobs are still cleaned up
+    // when the chat session itself is deleted (see cleanupScopedMetadata).
     mcpServerBridge.cancelPtyExecsForSession(effectiveChatSessionId);
     mcpServerBridge.setChatSessionCancelled?.(effectiveChatSessionId, true);
     mcpServerBridge.clearPendingApprovals(effectiveChatSessionId);

electron/bridges/mcpServerBridge.cjs

@@ -12,7 +12,7 @@ const path = require("node:path");
 const { existsSync } = require("node:fs");
 
 const { toUnpackedAsarPath } = require("./ai/shellUtils.cjs");
-const { execViaPty, execViaChannel, execViaRawPty } = require("./ai/ptyExec.cjs");
+const { execViaPty, startPtyJob, execViaChannel, execViaRawPty } = require("./ai/ptyExec.cjs");
 const { safeSend } = require("./ipcUtils.cjs");
 
 let sessions = null;   // Map<sessionId, { sshClient, stream, pty, proc, conn, ... }>
@@ -48,6 +48,13 @@ let permissionMode = "confirm";
 // Track active PTY executions for cancellation
 const activePtyExecs = new Map(); // marker → { ptyStream, cleanup }
 const cancelledChatSessions = new Set();
+const backgroundJobs = new Map(); // jobId -> job metadata
+const activeSessionExecutions = new Map(); // sessionId -> { kind, startedAt, token }
+const pendingSessionWriteApprovals = new Map(); // sessionId -> method
+const DEFAULT_BACKGROUND_JOB_TIMEOUT_MS = 60 * 60 * 1000;
+const DEFAULT_BACKGROUND_JOB_POLL_INTERVAL_MS = 30 * 1000;
+const BACKGROUND_JOB_RETENTION_MS = 10 * 60 * 1000;
+const MAX_BACKGROUND_JOB_OUTPUT_CHARS = 256 * 1024;
 
 // ── Approval gate (for confirm mode with ACP/MCP agents) ──
 let getMainWindowFn = null; // () => BrowserWindow | null
@@ -63,7 +70,12 @@ function setMainWindowGetter(fn) {
  * Sends an IPC event and returns a Promise<boolean> that resolves
  * when the user approves/rejects in the UI, or auto-denies after timeout.
  */
-const APPROVAL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+// External ACP agents (for example Codex) may give up on MCP tool calls after
+// about 120 seconds; see openai/codex#6127 ("timed out awaiting tools/call
+// after 120s"). Keep the Netcatty-side approval window below that with a small
+// buffer so a stale approval cannot still be accepted after the agent has
+// already timed out and abandoned the call.
+const APPROVAL_TIMEOUT_MS = 110 * 1000; // 110 seconds
 
 function requestApprovalFromRenderer(toolName, args, chatSessionId) {
   return new Promise((resolve) => {
@@ -161,6 +173,207 @@ function cancelPtyExecsForSession(chatSessionId) {
   }
 }
 
+function createBackgroundJobId() {
+  return `job_${Date.now().toString(36)}_${crypto.randomBytes(6).toString("hex")}`;
+}
+
+function cancelBackgroundJobsForSession(chatSessionId) {
+  if (!chatSessionId) return;
+  for (const [, job] of backgroundJobs) {
+    if (job.chatSessionId !== chatSessionId) continue;
+    if (job.status !== "running") continue;
+    try {
+      job.handle?.cancel?.();
+      job.status = "stopping";
+      job.error = "Cancellation requested";
+      job.updatedAt = Date.now();
+    } catch {
+      // Ignore cancellation failures
+    }
+  }
+}
+
+function readBackgroundJobSnapshot(job) {
+  if (!job) {
+    return {
+      stdout: "",
+      outputBaseOffset: 0,
+      totalOutputChars: 0,
+      outputTruncated: false,
+    };
+  }
+  if (job.status === "running" || job.status === "stopping") {
+    const snapshot = job.handle?.getSnapshot?.();
+    if (snapshot) {
+      const stdout = String(snapshot.stdout || "");
+      const outputBaseOffset = Math.max(0, Number(snapshot.outputBaseOffset) || 0);
+      const totalOutputChars = Math.max(outputBaseOffset + stdout.length, Number(snapshot.totalOutputChars) || 0);
+      return {
+        stdout,
+        outputBaseOffset,
+        totalOutputChars,
+        outputTruncated: Boolean(snapshot.outputTruncated),
+      };
+    }
+  }
+  const stdout = String(job.stdout || "");
+  const outputBaseOffset = Math.max(0, Number(job.outputBaseOffset) || 0);
+  const totalOutputChars = Math.max(outputBaseOffset + stdout.length, Number(job.totalOutputChars) || 0);
+  return {
+    stdout,
+    outputBaseOffset,
+    totalOutputChars,
+    outputTruncated: Boolean(job.outputTruncated),
+  };
+}
+
+function createOutputWindow(stdout) {
+  const fullText = String(stdout || "");
+  const totalOutputChars = fullText.length;
+  const outputBaseOffset = Math.max(0, totalOutputChars - MAX_BACKGROUND_JOB_OUTPUT_CHARS);
+  return {
+    stdout: outputBaseOffset > 0 ? fullText.slice(outputBaseOffset) : fullText,
+    outputBaseOffset,
+    totalOutputChars,
+    outputTruncated: outputBaseOffset > 0,
+  };
+}
+
+function refreshRunningJobSnapshot(job) {
+  if (!job || (job.status !== "running" && job.status !== "stopping")) return;
+  const snapshot = readBackgroundJobSnapshot(job);
+  job.stdout = snapshot.stdout;
+  job.outputBaseOffset = snapshot.outputBaseOffset;
+  job.totalOutputChars = snapshot.totalOutputChars;
+  job.outputTruncated = snapshot.outputTruncated;
+}
+
+function storeCompletedJobOutput(job, stdout, metadata = null) {
+  if (metadata && typeof metadata === "object") {
+    const normalizedStdout = String(metadata.stdout ?? stdout ?? "");
+    const outputBaseOffset = Math.max(0, Number(metadata.outputBaseOffset) || 0);
+    const totalOutputChars = Math.max(outputBaseOffset + normalizedStdout.length, Number(metadata.totalOutputChars) || 0);
+    job.stdout = normalizedStdout;
+    job.outputBaseOffset = outputBaseOffset;
+    job.totalOutputChars = totalOutputChars;
+    job.outputTruncated = Boolean(metadata.outputTruncated);
+    job.handle = null;
+    return;
+  }
+  const window = createOutputWindow(stdout);
+  job.stdout = window.stdout;
+  job.outputBaseOffset = window.outputBaseOffset;
+  job.totalOutputChars = window.totalOutputChars;
+  job.outputTruncated = window.outputTruncated;
+  job.handle = null;
+}
+
+function pruneCompletedBackgroundJobs(now = Date.now()) {
+  for (const [jobId, job] of backgroundJobs) {
+    if (job.status === "running" || job.status === "stopping") continue;
+    const updatedAt = Number(job.updatedAt) || 0;
+    if (updatedAt > 0 && now - updatedAt > BACKGROUND_JOB_RETENTION_MS) {
+      backgroundJobs.delete(jobId);
+    }
+  }
+}
+
+// Collapse carriage-return progress redraws to the latest frame.
+// Each \r resets the cursor to the start of the current line; the next
+// non-\r character overwrites the existing line content. A trailing \r
+// (with no following content) leaves the existing line intact, so a
+// snapshot taken between redraws still shows the latest visible frame.
+// Used at serialize time so the stored buffer can keep raw monotonic
+// offsets while polled output shows the latest frame.
+function collapseCarriageReturns(text) {
+  if (!text || text.indexOf("\r") === -1) return text;
+  let result = "";
+  let crPending = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\r") {
+      crPending = true;
+      continue;
+    }
+    if (ch === "\n") {
+      crPending = false;
+      result += ch;
+      continue;
+    }
+    if (crPending) {
+      const lastNl = result.lastIndexOf("\n");
+      result = lastNl >= 0 ? result.slice(0, lastNl + 1) : "";
+      crPending = false;
+    }
+    result += ch;
+  }
+  return result;
+}
+
+function serializeBackgroundJob(job, offset = 0) {
+  if (job.status === "running" || job.status === "stopping") {
+    refreshRunningJobSnapshot(job);
+  }
+  const stdout = job.stdout || "";
+  const outputBaseOffset = job.outputBaseOffset || 0;
+  const totalOutputChars = Math.max(outputBaseOffset + stdout.length, job.totalOutputChars || 0);
+  const numericOffset = Math.max(0, Number(offset) || 0);
+  const relativeOffset = numericOffset <= outputBaseOffset
+    ? 0
+    : Math.min(numericOffset - outputBaseOffset, stdout.length);
+  return {
+    ok: true,
+    jobId: job.id,
+    sessionId: job.sessionId,
+    command: job.command,
+    status: job.status,
+    completed: job.status !== "running" && job.status !== "stopping",
+    exitCode: job.exitCode,
+    error: job.error,
+    startedAt: job.startedAt,
+    updatedAt: job.updatedAt,
+    output: collapseCarriageReturns(stdout.slice(relativeOffset)),
+    nextOffset: totalOutputChars,
+    totalOutputChars,
+    outputBaseOffset,
+    outputTruncated: Boolean(job.outputTruncated),
+    recommendedPollIntervalMs: DEFAULT_BACKGROUND_JOB_POLL_INTERVAL_MS,
+  };
+}
+
+function describeActiveSessionExecution(entry) {
+  if (!entry) return "another command";
+  return entry.kind === "job" ? "a long-running command" : "another command";
+}
+
+function getSessionBusyError(sessionId) {
+  const active = activeSessionExecutions.get(sessionId);
+  if (!active) return null;
+  return {
+    ok: false,
+    error: `Session already has ${describeActiveSessionExecution(active)} in progress. Wait for it to finish or stop it before starting another command.`,
+  };
+}
+
+function reserveSessionExecution(sessionId, kind) {
+  const existing = getSessionBusyError(sessionId);
+  if (existing) return existing;
+  const token = `${kind}_${Date.now().toString(36)}_${crypto.randomBytes(6).toString("hex")}`;
+  activeSessionExecutions.set(sessionId, {
+    kind,
+    startedAt: Date.now(),
+    token,
+  });
+  return { ok: true, token };
+}
+
+function releaseSessionExecution(sessionId, token) {
+  const active = activeSessionExecutions.get(sessionId);
+  if (!active) return;
+  if (token && active.token !== token) return;
+  activeSessionExecutions.delete(sessionId);
+}
+
 function init(deps) {
   sessions = deps.sessions;
   electronModule = deps.electronModule || null;
@@ -413,14 +626,35 @@ async function handleMessage(socket, line) {
 // Methods that modify remote state — blocked in observer mode
 const WRITE_METHODS = new Set([
   "netcatty/exec",
+  "netcatty/jobStart",
+  "netcatty/jobStop",
 ]);
 
 /**
  * Validate that a sessionId is allowed in the current scope.
- * Checks both process-level SCOPED_SESSION_IDS and per-chatSession scoped metadata.
+ * Checks explicit per-call scopedSessionIds first (static MCP scope mode),
+ * then per-chatSession scoped metadata (dynamic mode), then global scope.
+ *
+ * An explicit empty array (`[]`) means "no access" — not "fall through to
+ * global scope" — matching the documented behavior in handleGetContext.
  */
-function validateSessionScope(sessionId, chatSessionId) {
+function validateSessionScope(sessionId, chatSessionId, explicitScopedIds = null) {
   if (!sessionId) return null; // will fail at handler level
+  if (Array.isArray(explicitScopedIds)) {
+    if (!explicitScopedIds.includes(sessionId)) {
+      return `Session "${sessionId}" is not in the current scope.`;
+    }
+    return null;
+  }
+  // If a chat has explicit scoped metadata (even an empty array), enforce it.
+  // Only fall through to fallback/global when no chat-scoped context exists.
+  if (chatSessionId && scopedMetadata.has(chatSessionId)) {
+    const chatScoped = scopedMetadata.get(chatSessionId)?.sessionIds || [];
+    if (!chatScoped.includes(sessionId)) {
+      return `Session "${sessionId}" is not in the current scope.`;
+    }
+    return null;
+  }
   const scopedIds = getScopedSessionIds(chatSessionId);
   if (scopedIds && scopedIds.length > 0 && !scopedIds.includes(sessionId)) {
     return `Session "${sessionId}" is not in the current scope.`;
@@ -429,36 +663,78 @@ function validateSessionScope(sessionId, chatSessionId) {
 }
 
 async function dispatch(method, params) {
-  // Observer mode: block all write operations
-  if (permissionMode === "observer" && WRITE_METHODS.has(method)) {
+  const sessionWriteLockId = (method === "netcatty/exec" || method === "netcatty/jobStart") ? params?.sessionId : null;
+  pruneCompletedBackgroundJobs();
+
+  // Observer mode: block all write operations *except* netcatty/jobStop,
+  // which must remain available so users can interrupt long-running jobs
+  // they started before switching to observer mode (otherwise the job
+  // would hold the per-session lock until it exits on its own).
+  if (permissionMode === "observer" && WRITE_METHODS.has(method) && method !== "netcatty/jobStop") {
     return { ok: false, error: `Operation denied: permission mode is "observer" (read-only). Change to "confirm" or "autonomous" in Settings → AI → Safety to allow this action.` };
   }
 
-  if (WRITE_METHODS.has(method) && isChatSessionCancelled(params?.chatSessionId)) {
+  // netcatty/jobStop must remain callable after ACP cancel so users can stop
+  // a long-running terminal_start job (which intentionally survives ACP Stop)
+  // even from a chat session whose write methods are otherwise blocked.
+  if (WRITE_METHODS.has(method) && method !== "netcatty/jobStop" && isChatSessionCancelled(params?.chatSessionId)) {
     return { ok: false, error: "Operation cancelled: the ACP session was stopped." };
   }
 
-  // Confirm mode: request user approval for write operations
-  if (permissionMode === "confirm" && WRITE_METHODS.has(method)) {
-    const { chatSessionId, ...toolArgs } = params || {};
-    const approved = await requestApprovalFromRenderer(method, toolArgs, chatSessionId);
-    if (!approved) {
-      return { ok: false, error: "Operation denied by user." };
-    }
-  }
-
-  // Scope validation for session-targeted operations
+  // Validate session scope *first* so out-of-scope callers cannot infer the
+  // existence or activity of foreign sessions through busy-state error
+  // messages, and so requests fail fast without blocking the write lock.
   if (method !== "netcatty/getContext" && params?.sessionId) {
-    const scopeErr = validateSessionScope(params.sessionId, params?.chatSessionId);
+    const scopeErr = validateSessionScope(params.sessionId, params?.chatSessionId, params?.scopedSessionIds);
     if (scopeErr) return { ok: false, error: scopeErr };
   }
-  switch (method) {
-    case "netcatty/getContext":
-      return handleGetContext(params);
-    case "netcatty/exec":
-      return handleExec(params);
-    default:
-      throw new Error(`Unknown method: ${method}`);
+
+  if ((method === "netcatty/exec" || method === "netcatty/jobStart") && params?.sessionId) {
+    const busy = getSessionBusyError(params.sessionId);
+    if (busy) return busy;
+  }
+
+  if (sessionWriteLockId) {
+    const pendingMethod = pendingSessionWriteApprovals.get(sessionWriteLockId);
+    if (pendingMethod) {
+      return {
+        ok: false,
+        error: "Session already has another command request awaiting approval or startup. Wait for it to finish before starting a new command.",
+      };
+    }
+    pendingSessionWriteApprovals.set(sessionWriteLockId, method);
+  }
+
+  try {
+    // Confirm mode: request user approval for write operations.
+    // netcatty/jobStop bypasses approval — it's a stop/cancel action that
+    // must remain available even if the renderer is unavailable; otherwise
+    // a runaway terminal_start job could not be interrupted at all.
+    if (permissionMode === "confirm" && WRITE_METHODS.has(method) && method !== "netcatty/jobStop") {
+      const { chatSessionId, ...toolArgs } = params || {};
+      const approved = await requestApprovalFromRenderer(method, toolArgs, chatSessionId);
+      if (!approved) {
+        return { ok: false, error: "Operation denied by user." };
+      }
+    }
+    switch (method) {
+      case "netcatty/getContext":
+        return handleGetContext(params);
+      case "netcatty/exec":
+        return handleExec(params);
+      case "netcatty/jobStart":
+        return handleJobStart(params);
+      case "netcatty/jobPoll":
+        return handleJobPoll(params);
+      case "netcatty/jobStop":
+        return handleJobStop(params);
+      default:
+        throw new Error(`Unknown method: ${method}`);
+    }
+  } finally {
+    if (sessionWriteLockId) {
+      pendingSessionWriteApprovals.delete(sessionWriteLockId);
+    }
   }
 }
 
@@ -526,7 +802,7 @@ function handleGetContext(params) {
 
 // ── Handler: exec ──
 
-function handleExec(params) {
+function resolveExecContext(params) {
   const { sessionId, command } = params;
   if (!sessionId || !command) throw new Error("sessionId and command are required");
   if (typeof command !== 'string' || !command.trim()) {
@@ -574,60 +850,296 @@ function handleExec(params) {
 
   const sshClient = session.conn || session.sshClient;
   const ptyStream = session.stream || session.pty || session.proc;
+  return {
+    ok: true,
+    context: {
+      sessionId,
+      command,
+      session,
+      chatSessionId,
+      sessionProtocol,
+      isNetworkDevice,
+      sshClient,
+      ptyStream,
+    },
+  };
+}
+
+function handleExec(params) {
+  const resolved = resolveExecContext(params);
+  if (!resolved.ok) return resolved;
+  const {
+    sessionId,
+    command,
+    session,
+    chatSessionId,
+    sessionProtocol,
+    isNetworkDevice,
+    sshClient,
+    ptyStream,
+  } = resolved.context;
+  const reservation = reserveSessionExecution(sessionId, "exec");
+  if (!reservation.ok) return reservation;
+  const sessionToken = reservation.token;
+
+  const runExecution = (factory) => {
+    try {
+      return Promise.resolve(factory()).finally(() => {
+        releaseSessionExecution(sessionId, sessionToken);
+      });
+    } catch (err) {
+      releaseSessionExecution(sessionId, sessionToken);
+      return { ok: false, error: err?.message || String(err) };
+    }
+  };
 
   // Network devices (switches/routers) connected via SSH: use raw execution.
   // Their vendor CLIs (Huawei VRP, Cisco IOS, etc.) don't run a POSIX shell,
   // so shell-wrapped commands with markers would fail. Raw mode sends commands
   // as-is with idle-timeout completion detection — same as serial sessions.
   if (isNetworkDevice && ptyStream && typeof ptyStream.write === "function") {
-    return execViaRawPty(ptyStream, command, {
+    return runExecution(() => execViaRawPty(ptyStream, command, {
       timeoutMs: commandTimeoutMs,
       trackForCancellation: activePtyExecs,
       chatSessionId: params?.chatSessionId,
       encoding: "utf8", // SSH PTY streams use UTF-8, not latin1
-    });
+    }));
   }
 
   // Prefer the interactive PTY so the user sees command/output in-session.
   if (ptyStream && typeof ptyStream.write === "function") {
-    return execViaPty(ptyStream, command, {
+    return runExecution(() => execViaPty(ptyStream, command, {
       trackForCancellation: activePtyExecs,
       timeoutMs: commandTimeoutMs,
       shellKind: session.shellKind,
       expectedPrompt: session.lastIdlePrompt || "",
       typedInput: true,
       echoCommand: (rawCommand) => echoCommandToSession(session, sessionId, rawCommand),
-    });
+      // MCP callers have terminal_start as a fallback for long commands,
+      // so enforce a hard wall-clock timeout here to match the MCP budget.
+      enforceWallTimeout: true,
+    }));
   }
 
   // Network devices require an interactive PTY for raw command execution.
   // If we got here, ptyStream wasn't writable — there's no usable channel.
   if (isNetworkDevice) {
+    releaseSessionExecution(sessionId, sessionToken);
     return { ok: false, error: "Network device session has no writable PTY stream for command execution" };
   }
 
   // Fallback: SSH exec channel (invisible to terminal).
   // At this point ptyStream is not writable (already returned above if it was).
   if (sshClient && typeof sshClient.exec === "function") {
-    return execViaChannel(sshClient, command, {
+    return runExecution(() => execViaChannel(sshClient, command, {
       timeoutMs: commandTimeoutMs,
       trackForCancellation: activePtyExecs,
-    });
+      // Pass chatSessionId so cancelPtyExecsForSession can interrupt this
+      // exec channel when the originating ACP run is stopped.
+      chatSessionId: params?.chatSessionId,
+    }));
   }
 
   // Serial port: raw command execution (no shell wrapping)
   if (session.protocol === "serial" && session.serialPort && typeof session.serialPort.write === "function") {
-    return execViaRawPty(session.serialPort, command, {
+    return runExecution(() => execViaRawPty(session.serialPort, command, {
       timeoutMs: commandTimeoutMs,
       trackForCancellation: activePtyExecs,
       chatSessionId: params?.chatSessionId,
       encoding: session.serialEncoding || "utf8",
-    });
+    }));
   }
 
+  releaseSessionExecution(sessionId, sessionToken);
   return { ok: false, error: "Session does not support command execution" };
 }
 
+function handleJobStart(params) {
+  const resolved = resolveExecContext(params);
+  if (!resolved.ok) return resolved;
+  const {
+    sessionId,
+    command,
+    session,
+    chatSessionId,
+    isNetworkDevice,
+    sessionProtocol,
+    ptyStream,
+  } = resolved.context;
+
+  if (isNetworkDevice || sessionProtocol === "serial") {
+    return {
+      ok: false,
+      error: "Background execution currently supports shell-backed PTY sessions only.",
+    };
+  }
+
+  if (!ptyStream || typeof ptyStream.write !== "function") {
+    return {
+      ok: false,
+      error: "Background execution requires a writable PTY-backed terminal session.",
+    };
+  }
+
+  const reservation = reserveSessionExecution(sessionId, "job");
+  if (!reservation.ok) return reservation;
+  const sessionToken = reservation.token;
+
+  const jobId = createBackgroundJobId();
+  const timeoutMs = Math.max(commandTimeoutMs, DEFAULT_BACKGROUND_JOB_TIMEOUT_MS);
+  let handle;
+  try {
+    handle = startPtyJob(ptyStream, command, {
+      // Intentionally do NOT register in activePtyExecs: terminal_start jobs
+      // are designed to survive ACP "Stop" so the model can stop polling
+      // without aborting a long-running build/scan/log stream. The job is
+      // managed via terminal_stop and the per-session execution lock.
+      timeoutMs,
+      shellKind: session.shellKind,
+      chatSessionId,
+      expectedPrompt: session.lastIdlePrompt || "",
+      typedInput: true,
+      echoCommand: (rawCommand) => echoCommandToSession(session, sessionId, rawCommand),
+      maxBufferedChars: MAX_BACKGROUND_JOB_OUTPUT_CHARS,
+      normalizeFinalOutput: false,
+    });
+  } catch (err) {
+    releaseSessionExecution(sessionId, sessionToken);
+    return { ok: false, error: err?.message || String(err) };
+  }
+
+  const startedAt = Date.now();
+  const job = {
+    id: jobId,
+    sessionId,
+    chatSessionId: chatSessionId || null,
+    command,
+    status: "running",
+    startedAt,
+    updatedAt: startedAt,
+    exitCode: null,
+    error: null,
+    stdout: "",
+    outputBaseOffset: 0,
+    totalOutputChars: 0,
+    outputTruncated: false,
+    handle,
+  };
+  backgroundJobs.set(jobId, job);
+
+  handle.resultPromise.then((result) => {
+    job.updatedAt = Date.now();
+    job.exitCode = result.exitCode ?? null;
+    storeCompletedJobOutput(job, result.stdout || "", result);
+    const isForcedCancel = typeof result.error === "string" && result.error.includes("forced");
+    if (result.error === "Cancelled" || isForcedCancel) {
+      // Forced cancel means the process ignored SIGINT for the cancel
+      // wall-clock window. We mark the job as cancelled and release the
+      // lock so the session is reusable; the error message tells the
+      // caller the process may still be running so subsequent commands
+      // should be considered carefully. This is consistent: callers see
+      // completed=true exactly when the lock is no longer held.
+      job.status = "cancelled";
+      job.error = result.error;
+      releaseSessionExecution(sessionId, sessionToken);
+      return;
+    }
+    if (result.error) {
+      job.status = "failed";
+      job.error = result.error;
+      releaseSessionExecution(sessionId, sessionToken);
+      return;
+    }
+    // A non-zero exit code without an error message still represents a
+    // failed command (e.g. a build/test that returned 1). Mark it as failed
+    // so callers don't have to special-case exitCode against status.
+    if (typeof result.exitCode === "number" && result.exitCode !== 0) {
+      job.status = "failed";
+      job.error = `Command exited with code ${result.exitCode}`;
+      releaseSessionExecution(sessionId, sessionToken);
+      return;
+    }
+    job.status = "completed";
+    releaseSessionExecution(sessionId, sessionToken);
+  }).catch((err) => {
+    job.updatedAt = Date.now();
+    job.status = "failed";
+    job.error = err?.message || String(err);
+    storeCompletedJobOutput(job, job.stdout || "");
+    releaseSessionExecution(sessionId, sessionToken);
+  });
+
+  return {
+    ok: true,
+    jobId,
+    sessionId,
+    command,
+    status: "running",
+    startedAt,
+    outputMode: "foreground-mirrored",
+    recommendedPollIntervalMs: DEFAULT_BACKGROUND_JOB_POLL_INTERVAL_MS,
+  };
+}
+
+function getScopedJob(jobId, chatSessionId) {
+  const job = backgroundJobs.get(jobId);
+  if (!job) return null;
+  // Per-chat isolation: a job started under a chat session can only be
+  // accessed by callers presenting the same chatSessionId. Unscoped or
+  // statically-scoped callers cannot reach into another chat's jobs.
+  if (job.chatSessionId) {
+    if (!chatSessionId || job.chatSessionId !== chatSessionId) {
+      return null;
+    }
+  }
+  return job;
+}
+
+function handleJobPoll(params) {
+  const { jobId, offset = 0, chatSessionId, scopedSessionIds } = params || {};
+  if (!jobId) throw new Error("jobId is required");
+  const job = getScopedJob(jobId, chatSessionId || null);
+  if (!job) return { ok: false, error: "Background job not found" };
+  // Re-check session scope so a caller that lost access to the host
+  // cannot continue reading output from jobs on that session.
+  // Covers dynamic (chatSessionId), static (scopedSessionIds), and global modes.
+  if (job.sessionId) {
+    const scopeErr = validateSessionScope(job.sessionId, chatSessionId || null, scopedSessionIds);
+    if (scopeErr) return { ok: false, error: scopeErr };
+  }
+  return serializeBackgroundJob(job, offset);
+}
+
+function handleJobStop(params) {
+  const { jobId, chatSessionId, scopedSessionIds } = params || {};
+  if (!jobId) throw new Error("jobId is required");
+  const job = getScopedJob(jobId, chatSessionId || null);
+  if (!job) return { ok: false, error: "Background job not found" };
+  // For statically scoped MCP clients, validate that the job's session is
+  // within the caller's static scope so a foreign jobId cannot cancel jobs
+  // outside the caller's allowed sessions. Dynamic chat scope is already
+  // enforced by getScopedJob (caller's chatSessionId must match the job's),
+  // and we intentionally do NOT re-check dynamic scope here so jobs can
+  // still be stopped after workspace membership changes — otherwise the
+  // session lock would stay held forever.
+  if (Array.isArray(scopedSessionIds) && job.sessionId) {
+    if (!scopedSessionIds.includes(job.sessionId)) {
+      return { ok: false, error: `Session "${job.sessionId}" is not in the current scope.` };
+    }
+  }
+  if (job.status === "running") {
+    try {
+      job.handle?.cancel?.();
+    } catch (err) {
+      return { ok: false, error: err?.message || String(err) };
+    }
+    job.status = "stopping";
+    job.error = "Cancellation requested";
+    job.updatedAt = Date.now();
+  }
+  return serializeBackgroundJob(job, 0);
+}
+
 // ── MCP Server Config Builder ──
 
 function resolveMcpServerRuntimeCommand() {
@@ -695,6 +1207,12 @@ function cleanupScopedMetadata(chatSessionId) {
   if (chatSessionId) {
     scopedMetadata.delete(chatSessionId);
     cancelledChatSessions.delete(chatSessionId);
+    cancelBackgroundJobsForSession(chatSessionId);
+    // Resolve any in-flight approval requests so dispatch()'s finally block
+    // releases its pendingSessionWriteApprovals entry. Without this, a chat
+    // deleted while an approval was pending would leave the per-session
+    // write lock held until the approval timeout expires.
+    clearPendingApprovals(chatSessionId);
   }
 }
 
@@ -705,6 +1223,15 @@ function cleanup() {
     tcpPort = null;
   }
   scopedMetadata.clear();
+  for (const [, job] of backgroundJobs) {
+    try {
+      job.handle?.cancel?.();
+    } catch {
+      // Ignore cancellation failures during cleanup
+    }
+  }
+  backgroundJobs.clear();
+  activeSessionExecutions.clear();
 }
 
 module.exports = {
@@ -723,6 +1250,7 @@ module.exports = {
   getOrCreateHost,
   buildMcpServerConfig,
   activePtyExecs,
+  cancelBackgroundJobsForSession,
   cancelAllPtyExecs,
   cancelPtyExecsForSession,
   getSessionMeta,
@@ -731,4 +1259,7 @@ module.exports = {
   setMainWindowGetter,
   resolveApprovalFromRenderer,
   clearPendingApprovals,
+  reserveSessionExecution,
+  releaseSessionExecution,
+  getSessionBusyError,
 };

electron/bridges/sftpBridge.cjs

@@ -954,6 +954,14 @@ async function openSftp(event, options) {
     // Enable keyboard-interactive authentication (required for 2FA/MFA)
     tryKeyboard: true,
     readyTimeout: 120000, // 2 minutes for 2FA input
+    // Keep SFTP sessions alive while the panel is idle. Without SSH-level
+    // keepalive packets the connection sits with zero data flow while the
+    // user is just browsing files, and NAT/firewall state tables drop the
+    // idle TCP connection after ~30-60s (the exact symptom of #669).
+    // Honor an explicitly configured positive keepaliveInterval (seconds);
+    // otherwise default to 10s, matching the SFTP jump host path below.
+    keepaliveInterval: options.keepaliveInterval > 0 ? options.keepaliveInterval * 1000 : 10000,
+    keepaliveCountMax: 3,
     algorithms: buildSftpAlgorithms(options.legacyAlgorithms),
   };
 
@@ -1388,7 +1396,12 @@ async function readSftpBinary(event, payload) {
 }
 
 /**
- * Write file content
+ * Write file content.
+ *
+ * If the target file already exists, its mode is preserved — ssh2-sftp-client's
+ * `put()` otherwise overwrites existing files with the server's default mode
+ * (typically 0o666 after umask), which would silently change permissions on
+ * files edited through the built-in text editor.
  */
 async function writeSftp(event, payload) {
   const client = sftpClients.get(payload.sftpId);
@@ -1397,7 +1410,31 @@ async function writeSftp(event, payload) {
   await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(payload.path, encoding);
+
+  let existingMode = null;
+  try {
+    const stat = await client.stat(encodedPath);
+    if (typeof stat.mode === "number") {
+      // Mask with 0o7777 so special bits (setuid/setgid/sticky) are preserved too.
+      existingMode = stat.mode & 0o7777;
+    }
+  } catch (_err) {
+    // File does not exist — treat as a new file and let the server apply defaults.
+  }
+
   await client.put(Buffer.from(payload.content, "utf-8"), encodedPath);
+
+  if (existingMode !== null) {
+    try {
+      await client.chmod(encodedPath, existingMode);
+    } catch (err) {
+      console.warn(
+        `[sftp] Failed to restore permissions on ${payload.path}:`,
+        err && err.message ? err.message : err,
+      );
+    }
+  }
+
   return true;
 }
 

electron/bridges/windowManager.cjs

@@ -44,6 +44,10 @@ const OAUTH_LOOPBACK_PORT = 45678; // must match electron/bridges/oauthBridge.cj
 const WINDOW_STATE_FILE = "window-state.json";
 const DEFAULT_WINDOW_WIDTH = 1400;
 const DEFAULT_WINDOW_HEIGHT = 900;
+// Minimum window size: enough to render the expanded sidebar + a usable
+// host list + the 420px host details / new-host aside panel without overflow.
+const MIN_WINDOW_WIDTH = 1100;
+const MIN_WINDOW_HEIGHT = 640;
 
 function debugLog(...args) {
   if (!DEBUG_WINDOWS) return;
@@ -626,9 +630,10 @@ async function createWindow(electronModule, options) {
   };
 
   if (savedState) {
-    // Use saved dimensions
-    windowBounds.width = savedState.width;
-    windowBounds.height = savedState.height;
+    // Use saved dimensions, but clamp to the minimum so a previously
+    // shrunk window from an older build cannot start below the minimum.
+    windowBounds.width = Math.max(savedState.width, MIN_WINDOW_WIDTH);
+    windowBounds.height = Math.max(savedState.height, MIN_WINDOW_HEIGHT);
 
     // Only use saved position if the screen is available at that location
     if (typeof savedState.x === "number" && typeof savedState.y === "number") {
@@ -658,6 +663,8 @@ async function createWindow(electronModule, options) {
 
   const win = new BrowserWindow({
     ...windowBounds,
+    minWidth: MIN_WINDOW_WIDTH,
+    minHeight: MIN_WINDOW_HEIGHT,
     backgroundColor,
     icon: appIcon,
     show: false,

electron/mcp/netcatty-mcp-server.cjs

@@ -216,7 +216,7 @@ server.tool(
 // Tool: terminal_execute
 server.tool(
   "terminal_execute",
-  "Execute a command on a Netcatty terminal session. For shell sessions, the command runs in the session's shell. For serial/raw sessions and network device sessions (deviceType: network), commands are sent as-is without shell wrapping and exit codes are unavailable.",
+  "Execute a short command on a Netcatty terminal session and wait for the full result. Use this only for commands expected to finish within about 60 seconds. For long-running commands such as builds, scans, log-following, or anything likely to exceed that budget, use terminal_start and then terminal_poll instead.",
   {
     sessionId: z.string().describe("The terminal session ID (from get_environment) to execute on."),
     command: z.string().describe("The command to execute in the target session."),
@@ -242,6 +242,69 @@ server.tool(
   },
 );
 
+server.tool(
+  "terminal_start",
+  "Start a long-running command on a Netcatty terminal session without waiting for final completion. The command still runs in the visible terminal/PTTY so the user can watch live output. Prefer this whenever the command may exceed about 2 minutes, or when it streams output for an extended period, such as builds, scans, watch commands, and log-follow commands. After starting, wait at least about 30 seconds before the first terminal_poll unless you have a strong reason to check sooner.",
+  {
+    sessionId: z.string().describe("The terminal session ID (from get_environment) to execute on."),
+    command: z.string().describe("The command to start in the target session."),
+  },
+  async ({ sessionId, command }) => {
+    const guardErr = guardWriteOperation(command, { skipBlocklist: true });
+    if (guardErr) {
+      return { content: [{ type: "text", text: `Error: ${guardErr}` }], isError: true };
+    }
+    const result = await rpcCall("netcatty/jobStart", { ...scopeParams, sessionId, command });
+    if (!result.ok) {
+      return { content: [{ type: "text", text: `Error: ${result.error || "Failed to start background command"}` }], isError: true };
+    }
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          jobId: result.jobId,
+          sessionId: result.sessionId,
+          status: result.status,
+          startedAt: result.startedAt,
+          outputMode: result.outputMode,
+          recommendedPollIntervalMs: result.recommendedPollIntervalMs,
+        }, null, 2),
+      }],
+    };
+  },
+);
+
+server.tool(
+  "terminal_poll",
+  "Poll a long-running Netcatty command that was started with terminal_start. Returns incremental output since the given offset and the current status. Use the returned nextOffset for the next poll. If outputTruncated is true, only the retained tail starting at outputBaseOffset is still available. Do not poll aggressively: wait at least about 30 seconds between polls unless the tool output explicitly justifies checking sooner. As soon as completed is true, stop polling and analyze the final result immediately.",
+  {
+    jobId: z.string().describe("The background job ID returned by terminal_start."),
+    offset: z.number().int().min(0).optional().describe("Character offset previously returned as nextOffset. Omit or use 0 on the first poll."),
+  },
+  async ({ jobId, offset }) => {
+    const result = await rpcCall("netcatty/jobPoll", { ...scopeParams, jobId, offset: offset || 0 });
+    if (!result.ok) {
+      return { content: [{ type: "text", text: `Error: ${result.error || "Failed to poll background command"}` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+server.tool(
+  "terminal_stop",
+  "Stop a long-running Netcatty command that was started with terminal_start. This sends Ctrl+C to the running terminal job and returns its latest state.",
+  {
+    jobId: z.string().describe("The background job ID returned by terminal_start."),
+  },
+  async ({ jobId }) => {
+    const result = await rpcCall("netcatty/jobStop", { ...scopeParams, jobId });
+    if (!result.ok) {
+      return { content: [{ type: "text", text: `Error: ${result.error || "Failed to stop background command"}` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
 // ── Start ──
 
 async function main() {

index.css

@@ -102,6 +102,29 @@
   }
 }
 
+@keyframes split-panel-enter {
+  0% {
+    width: 0;
+    min-width: 0;
+    opacity: 0;
+    transform: translateX(22px);
+  }
+  55% {
+    opacity: 0.88;
+  }
+  100% {
+    width: var(--aside-inline-width);
+    min-width: var(--aside-inline-width);
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+.split-panel-enter {
+  animation: split-panel-enter 220ms cubic-bezier(0.24, 0.84, 0.32, 1) both;
+  will-change: width, opacity, transform;
+}
+
 :root {
   color-scheme: light;
 }