tabminal 2.0.15 → 2.0.17

package/ACP_PLANING.md

@@ -1,184 +1,271 @@
-# ACP Planing
+# ACP Planning
 
-## Goal
+Last updated: 2026-03-27
 
-Integrate ACP-based coding agents into Tabminal without implementing agents
-ourselves. Agents run on the Tabminal host, managed by the Tabminal backend.
-The web UI adds an Agent panel integrated into the existing workspace/editor
-area and supports multiple concurrent agent tabs per host.
+This file is no longer a pure implementation plan.
+It is now the ACP status ledger for Tabminal:
 
-## Constraints
+- what shipped
+- what is stable
+- what remains open
 
-- Do not break existing terminal, file editor, multi-host, or AI-assist flows.
-- Reuse community-maintained protocol and agent ecosystem pieces where
-  practical.
-- Keep lifecycle bounded: lazy start, reusable while tabs are open, and
-  cleaned up after inactivity.
-- Host isolation remains strict: each agent runtime and tab belongs to one
-  host.
-- MVP should be usable before advanced ACP capabilities are added.
+Use `/Users/leask/Documents/Tabminal/AGENTS.md` as the broader engineering
+handoff document. Use this file as the ACP-specific roadmap/status snapshot.
 
-## Selected Architecture
+## 1) Goal
+
+Integrate ACP-based coding agents into Tabminal without building custom agents
+in-repo. Agents should run on the Tabminal host, be managed by the Tabminal
+backend, and feel native inside the existing workspace/editor UI.
+
+## 2) Current Architecture
 
 ### Backend
 
-Add an ACP supervisor inside the Tabminal backend.
+Implemented:
+
+- ACP supervisor in `/Users/leask/Documents/Tabminal/src/acp-manager.mjs`
+- Built-in host-local agent definitions:
+  - Gemini CLI
+  - Codex CLI
+  - Claude Agent
+  - GitHub Copilot
+  - ACP Test Agent when `TABMINAL_ENABLE_TEST_AGENT=1`
+- Lazy runtime startup
+- Runtime reuse while tabs are active
+- Idle cleanup
+- ACP websocket fan-out to browser clients
+- Session restore for ACP runtimes that support `loadSession`
+- Per-agent saved config/env persistence
 
-Responsibilities:
-- List supported agent definitions available on the host.
-- Start ACP runtimes on demand.
-- Reuse ACP runtime processes while tabs/sessions are active.
-- Create ACP sessions within a runtime.
-- Bridge ACP events to browser clients over a dedicated WebSocket.
-- Expose minimal approval surfaces later; MVP focuses on prompt/stream/cancel.
+### Frontend
 
-Transport strategy:
-- Primary: stdio-launched ACP agents.
-- Future: attach to TCP ACP servers for tools like GitHub Copilot CLI.
+Implemented:
 
-Lifecycle:
-- Lazy runtime start on first use.
-- Keep alive while any agent tab is attached.
-- Idle timeout after last tab closes.
-- Destroy all runtimes on backend shutdown.
+- Host-scoped agent dropdown from the sidebar
+- Agent tabs inside the shared workspace tab strip
+- Transcript rendering with message/tool/permission/plan history
+- Composer with send/stop, slash-command suggestions, attachments, and keyboard
+  shortcuts
+- Mode/model/thought-level/permission selectors
+- Managed terminal summaries and `Jump in`
+- Usage HUD
+- Plan panel that archives into transcript history once complete
+- Agent-specific workspace restore and focus behavior
 
-### Frontend
+## 3) Completed Scope
 
-Add a host-scoped Agent button beside the file editor toggle area.
-
-Behavior:
-- Clicking Agent opens a dropdown of available agents for the active host.
-- Choosing an agent opens a new Agent tab inside the existing editor pane tab
-  strip.
-- Agent tabs coexist with file tabs.
-- Each agent tab streams conversation updates and supports prompt send/cancel.
-
-MVP UI:
-- Agent tabs render in the editor workspace.
-- Transcript area with coalesced message stream.
-- Prompt textarea + single send/stop button.
-- Mode picker, new chat action, and slash-command chips when available.
-- Status row with host, cwd, mode, and runtime/session status.
-
-## Reuse Strategy
-
-Use:
-- `@agentclientprotocol/sdk` for protocol/client implementation.
-- ACP Registry later for agent metadata discovery.
-
-Do not directly embed:
-- Chrome ACP web client.
-- ACP UI desktop frontend.
-
-Reason:
-- They are standalone apps, not embeddable widgets.
-- Tabminal needs native integration with existing host/session/workspace state.
-
-## MVP Scope
-
-### Phase 1
-
-Status:
-- Implemented on `acp` branch and usable with real browser smoke.
-- Backend ACP supervisor, API, and WS fan-out are live.
-- Frontend agent tabs, transcript rendering, prompt send/cancel, and
-  permission resolution are live.
-- Agent tab metadata now persists on the backend and restores across backend
-  restart for ACP runtimes that support `loadSession`.
-- Agent panel interaction polish is live:
-  - duplicate agent tabs auto-number as `#1`, `#2`, ...
-  - `Enter` sends
-  - `Esc` stops active runs
-  - `Ctrl+J` and `Shift+Enter` insert newlines
-  - mode switching and new-chat flows are available in-panel
-  - tool calls and permission requests render as structured cards
-- Verified with:
-  - `npm run lint`
-  - `npm test`
-  - browser smoke against isolated local ACP test agent
-  - browser restart-restore validation against backend-persisted ACP tabs
-- Current polish fixes already applied:
-  - Codex token stream is coalesced into a single assistant message instead of
-    one message per chunk.
-  - User prompts are no longer duplicated when an ACP runtime echoes
-    `user_message_chunk` updates after local optimistic insertion.
-  - Gemini definition availability is disabled with reason
-    `API key missing` when no key is configured.
-  - Agent panel typography has been reduced to align with the existing
-    workspace/editor density.
-
-Backend:
-- ACP supervisor module.
-- Built-in agent definitions for Gemini CLI, Codex CLI adapter, Claude adapter,
-  and Copilot CLI ACP server descriptor.
-- REST endpoints:
+The following items are effectively shipped and usable.
+
+### 3.1 Core ACP plumbing
+
+- ACP dependency integrated
+- Backend ACP supervisor live
+- REST endpoints live:
   - `GET /api/agents`
+  - `GET /api/agents/config`
+  - `PUT /api/agents/config/:agentId`
+  - `DELETE /api/agents/config/:agentId`
   - `POST /api/agents/tabs`
   - `POST /api/agents/tabs/:tabId/prompt`
   - `POST /api/agents/tabs/:tabId/cancel`
   - `POST /api/agents/tabs/:tabId/mode`
+  - `POST /api/agents/tabs/:tabId/config`
   - `POST /api/agents/tabs/:tabId/permissions/:permissionId`
   - `DELETE /api/agents/tabs/:tabId`
-- WebSocket endpoint for live event fan-out.
-
-Frontend:
-- Agent dropdown button.
-- Agent tab state model.
-- Agent transcript rendering.
-- Prompt send/stop.
-- Mode picker.
-- New chat action.
-- Slash-command starter chips.
-- Structured tool call / permission cards.
-- Host-scoped tabs in editor pane.
-
-### Deferred
-
-- File attachments.
-- Rich diff/resource rendering in tool outputs.
-- Terminal execution transcript UI for ACP tool calls.
-- Registry-driven install UX.
-- TCP ACP runtime support in UI.
-- Dedicated conversation history browser independent of terminal sessions.
-
-## Safety and Isolation
-
-- Agent runtimes inherit the host filesystem context, not browser-local state.
-- Prompt and transcript data stay isolated per host.
-- Closing an agent tab detaches from its ACP session.
-- When the last ACP session on a runtime closes, runtime enters idle cleanup.
-
-## Test Plan
-
-Backend:
-- Unit tests for supervisor lifecycle.
-- Mock ACP runtime process to test stream/cancel behavior.
-- API tests for create/send/cancel/close.
-
-Frontend:
-- State/unit tests are minimal in current stack; use integration smoke.
-- Manual flow:
-  - open agent dropdown
-  - create Gemini/Codex tab
-  - send prompt
-  - receive stream
-  - cancel
-  - open second agent tab
-  - verify file editor tabs still work
-  - verify terminal tabs still work
-
-Regression checks:
+- ACP websocket endpoint live
+
+### 3.2 Agent tab UX
+
+- Agent tabs coexist with file tabs and pinned terminal tabs
+- Duplicate agent tabs auto-number
+- `Enter` sends
+- `Shift+Enter` and `Ctrl+J` insert newline
+- `Esc` stops active runs
+- `Ctrl+Shift+A` opens the agent menu
+- Slash-command menu opens upward as floating overlay
+- Keyboard navigation inside slash-command menu is implemented
+
+### 3.3 Transcript and tool rendering
+
+- Coalesced assistant message streaming
+- Optimistic user message insertion
+- De-duplication when runtime echoes user chunks
+- Structured tool-call cards
+- Structured permission cards
+- Diff rendering
+- Code/resource rendering
+- Terminal output rendering inside tool cards
+- Path link rendering
+- Running-terminal activity summary
+
+### 3.4 Managed terminal flow
+
+- ACP tool calls can create managed terminal sessions
+- `Jump in` switches to the real terminal session when still alive
+- Focus-stealing bug after `Jump in` has been fixed
+- Hidden pinned terminals no longer report bogus tiny sizes to the backend
+
+### 3.5 Persistence and restore
+
+- Agent tab metadata persists on backend
+- Agent config persists on backend
+- Transcript/tool/permission/plan state persists
+- Restore works across backend restart for runtimes that support `loadSession`
+- Restore no longer wrongly penalizes built-in agent availability on startup
+
+### 3.6 Usage / status UI
+
+- Usage HUD implemented
+- CSS-only expanded HUD layout stabilized
+- Plan panel implemented
+- Completed plan moves into transcript history instead of permanently occupying
+  composer-adjacent UI
+- Transcript auto-scroll logic now follows the correct “only pin if already at
+  bottom” rule
+
+### 3.7 Test tooling
+
+- ACP Test Agent supports real slash-command scenarios:
+  - `/demo`
+  - `/plan`
+  - `/diff`
+  - `/permission`
+  - `/cancel`
+  - `/stale`
+  - `/order`
+  - `/fail`
+- ACP browser smoke covers current UI shape
+- ACP manager tests cover restore, prompt attachments, config, availability, and
+  slash commands
+
+## 4) Stable Contracts
+
+These should now be treated as product contracts, not experiments.
+
+- ACP agents are host-scoped.
+- Agent tabs do not require the file tree to be open.
+- Workspace tabs should remain visible if there is any file tab, agent tab, or
+  pinned terminal tab.
+- `Jump in` is a management path, not a read-only preview, while the terminal is
+  still alive.
+- Internal shell bootstrap commands such as `TABMINAL_SHELL_READY=1` must never
+  surface as user notifications.
+- ACP availability should reflect the backend runtime environment, not only the
+  developer's interactive shell.
+- On small screens, agent config selectors collapse to icon-only affordances.
+
+## 5) Remaining Work
+
+This is the actual remaining ACP backlog.
+
+### 5.1 Still open
+
+#### A) Registry-driven install/setup UX
+
+Status: not done
+
+Missing:
+
+- guided install flow for agents that are unavailable
+- first-class setup UX for installing required CLIs
+- richer host diagnostics for why a definition is unavailable
+
+Current state:
+
+- availability reasons are shown
+- some config/setup flows exist
+- but this is not yet a complete install-onboarding UX
+
+#### B) Explicit TCP ACP runtime support in the UI
+
+Status: not done
+
+Missing:
+
+- user-visible workflow for attaching to TCP ACP servers
+- transport selection UX
+- connection lifecycle UX for non-stdio ACP runtimes
+
+Current state:
+
+- architecture originally allowed for this direction
+- product currently operates around stdio-launched/local CLI definitions
+
+#### C) Dedicated conversation history browser
+
+Status: not done
+
+Missing:
+
+- independent history browser for ACP conversations
+- browsing/searching old conversations outside the current terminal/workspace
+  session context
+
+Current state:
+
+- transcript restores with the tab
+- completed plans archive into the transcript
+- but there is no standalone conversation history surface
+
+### 5.2 Nice-to-have follow-up work
+
+These are not blockers, but they are logical next ACP improvements.
+
+- stronger browser smoke coverage for touch/mobile-only ACP interactions
+- clearer visual distinction between running, attention, and completed agent
+  states at scale
+- broader multi-host ACP smoke scenarios
+- richer availability/setup diagnostics in the UI
+
+## 6) What Was Originally Deferred But Is Now Done
+
+These items were previously listed as deferred and should no longer be treated
+as open backlog:
+
+- prompt/file attachments
+- diff rendering in tool outputs
+- code/resource rendering in tool outputs
+- terminal execution transcript UI for ACP tool calls
+
+## 7) Test and Verification Status
+
+Current ACP verification surface:
+
 - `npm run lint`
 - `npm test`
-- existing multi-host session behavior
-- editor pane switching between file tabs and agent tabs
-
-## Implementation Order
-
-1. Add ACP dependency and inspect exact SDK client API.
-2. Implement backend supervisor with a mockable adapter layer.
-3. Expose API/WS endpoints with no frontend integration yet.
-4. Add frontend Agent button and agent tab model.
-5. Wire prompt streaming and cancellation.
-6. Run tests and manual smoke.
-7. Iterate on lifecycle and UI fit.
+- `npm run build`
+- browser smoke via
+  `/Users/leask/Documents/Tabminal/scripts/acp-browser-smoke.mjs`
+
+Recommended ACP manual spot-checks when behavior changes:
+
+1. Start with `TABMINAL_ENABLE_TEST_AGENT=1`
+2. Run `/demo`
+3. Verify:
+   - agent menu
+   - slash-command menu
+   - plan panel
+   - usage HUD
+   - tool call cards
+   - managed terminal
+   - `Jump in`
+   - transcript scroll behavior
+4. Run `/permission`
+5. Run `/cancel`
+6. Reload and verify restore
+
+## 8) Recommendation
+
+ACP is no longer in “MVP not landed” status.
+It is in “shipped, actively polished, with a short remaining backlog” status.
+
+Practical summary:
+
+- Core ACP product: done
+- ACP UI polish: largely done
+- ACP infra/test surface: done
+- Remaining strategic work: 3 real items
+
+That remaining scope is small enough that this file should stay as a status
+ledger, not a large speculative design doc.

package/AGENTS.md

@@ -1,320 +1,471 @@
 # Tabminal Agent Notes
 
-Last updated: 2026-03-23
+Last updated: 2026-03-27
 
-This file is for future AI/code agents working in this repo.
-Goal: keep context accurate, avoid reintroducing old bugs, and preserve current UX
-contracts after the multi-host refactor.
+This file is for future coding agents working in this repo.
+Keep it current, specific, and operational. The main goal is to preserve the
+current product contracts so later work does not regress multi-host behavior,
+ACP agent UX, or mobile ergonomics.
 
 ## 1) Project Snapshot
 
-- Runtime: Node.js >= 22, ESM project.
-- Backend entry: `src/server.mjs`.
-- Frontend entry: `public/app.js` (plus modules in `public/modules/`).
-- PWA shell: `public/index.html` + `public/sw.js`.
-- Native app workspace: `apps/`
-  - Apple client: `apps/Apple`
-  - Ghostty vendor tooling: `apps/ghostty-vendor`
-- Multi-host registry persistence: `~/.tabminal/cluster.json` via backend API.
+- Runtime: Node.js `>= 22`, ESM project.
+- Backend entry: `src/server.mjs`
+- Frontend entry: `public/app.js`
+- PWA shell:
+  - `public/index.html`
+  - `public/sw.js`
+- Native app workspace:
+  - `apps/Apple`
+  - `apps/ghostty-vendor`
 
-Core idea now:
-- One web app can connect to multiple Tabminal backends.
-- Main host controls page-level auth modal/state.
-- Sub-hosts are independent connection/auth units and can reconnect separately.
+Current product shape:
 
-## 2) Non-Negotiable Behavior Contracts
+- Persistent terminal sessions remain the core product.
+- There are now two AI surfaces:
+  - terminal-native assistant in `src/terminal-session.mjs`
+  - ACP agent workspace in `src/acp-manager.mjs` + `public/app.js`
+- One web UI can connect to multiple Tabminal hosts.
+- The workspace bar now mixes file tabs, agent tabs, and pinned terminal tabs.
+
+Important persistence files under `~/.tabminal`:
+
+- `config.json`
+- `cluster.json`
+- `agent-tabs.json`
+- `agent-config.json`
+
+## 2) Non-Negotiable Contracts
 
 ### 2.1 Host model and state isolation
 
-- UI term is `Host` (not `Server`) for user-facing labels.
+- UI term is `Host`, not `Server`, for user-facing labels.
 - Every session belongs to exactly one host.
-- Session/editor/file-tree/expanded-path state is host-isolated.
+- Session state, editor state, file tree state, ACP agent tabs, and workspace
+  tabs are host-isolated.
 - Do not merge runtime state across hosts.
 
 Relevant code:
-- `public/app.js` (`state.servers`, `state.sessions`, `makeSessionKey` usage)
+- `public/app.js`
 - `public/modules/session-meta.js`
 
 ### 2.2 Auth model
 
-- Main host (`id = 'main'`) auth controls the app login modal.
-- Only main host 401/403 should trigger global login modal.
-- Sub-host 401/403 should mark that host as reconnect/login required, not global logout.
-- Sub-host may require Cloudflare Access login without password change.
+- Main host (`id = 'main'`) controls the global login modal.
+- Only main-host `401/403` should trigger app-wide login UI.
+- Sub-host auth failures must stay local to that host.
+- Sub-hosts may require Cloudflare Access login without password change.
 
 Relevant code:
-- `public/app.js` `ServerClient.handleUnauthorized`
-- `public/app.js` `ServerClient.handleAccessRedirect`
+- `public/app.js`
+  - `ServerClient.handleUnauthorized`
+  - `ServerClient.handleAccessRedirect`
 
-### 2.3 Token storage contract
+### 2.3 Token storage
 
 - Main host token:
-  - persisted in browser `localStorage` key `tabminal_auth_token:main`.
+  - browser `localStorage`
+  - key: `tabminal_auth_token:main`
 - Sub-host tokens:
-  - persisted in backend registry `~/.tabminal/cluster.json`.
-  - should not persist in browser localStorage.
-- Removing a host should remove any stale local token key for that host id.
+  - persisted in backend `cluster.json`
+  - do not persist in browser `localStorage`
+- Removing a host should also remove any stale local token keyed to that host.
 
 Relevant code:
-- `public/app.js` `ServerClient.constructor`, `ServerClient.setToken`
-- `src/persistence.mjs` `loadCluster` / `saveCluster`
+- `public/app.js`
+- `src/persistence.mjs`
 
-### 2.4 Host registry persistence contract
+### 2.4 Host registry persistence
 
-- Frontend does not own host list persistence anymore.
-- Source of truth: backend `GET/PUT /api/cluster`.
-- File format in `~/.tabminal/cluster.json`:
+- Frontend is not the source of truth for host list persistence.
+- Source of truth is backend `GET/PUT /api/cluster`.
+- File format:
   - `{ "servers": [{ id, baseUrl, host, token }, ...] }`
-- On page load, host list is restored from backend after main host auth succeeds.
+- On page load, host list restores only after main-host auth succeeds.
 
 Relevant code:
-- `public/app.js` `loadServerRegistryFromBackend`, `saveServerRegistryToBackend`
-- `src/server.mjs` `/api/cluster`
-- `src/persistence.mjs` cluster helpers
+- `public/app.js`
+- `src/server.mjs`
+- `src/persistence.mjs`
 
 ### 2.5 Deduplication and self-host skip
 
 - Host uniqueness key is normalized `hostname[:port]` in lowercase.
-- Path is not part of dedupe key.
-- Registry hydration skips entries that resolve to current main node
-  (same endpoint key or same hostname) to prevent self-loop duplicates.
-- This is intentional to support sharing one cluster config across nodes.
+- Path is intentionally not part of the dedupe key.
+- Hydration skips entries that resolve to the current main node to avoid
+  self-loop duplicates.
+- Path-based multi-host routing such as `/a/*` and `/b/*` is not supported by
+  the current client assumptions.
 
 Relevant code:
-- `public/modules/url-auth.js` `getServerEndpointKeyFromUrl`
-- `public/app.js` `findServerByEndpointKey`, `hydrateServerRegistry`
-
-Important implication:
-- Path-based multi-host on one domain (like `/a/*`, `/b/*`) is not supported by current
-  client routing assumptions.
+- `public/modules/url-auth.js`
+- `public/app.js`
 
 ### 2.6 Session creation ownership
 
-- Backend no longer auto-creates a default session/tab.
-- Frontend ensures usability:
-  - if no sessions after init, create one on main host.
-  - if user closes last session, create one on main host.
+- Backend does not auto-create a default session anymore.
+- Frontend is responsible for usability:
+  - create one main-host session if init returns none
+  - recreate one main-host session if user closes the last session
 
 Relevant code:
-- `public/app.js` `initApp`, `closeSession`
-- `src/server.mjs` (no auto-create fallback)
+- `public/app.js`
+- `src/server.mjs`
 
-### 2.7 Polling / heartbeat behavior
+### 2.7 Polling and heartbeat
 
-- Online heartbeat sync interval: `1000ms` (frontend).
-- Reconnect retry cadence when host is down: `5000ms` throttle per host.
-- Do not remove strong polling; it is a UX requirement.
+- Frontend heartbeat cadence: `1000ms`
+- Reconnect retry throttle per host: `5000ms`
+- Do not weaken these without measuring UX fallout.
 
 Relevant code:
 - `public/app.js`
-  - `HEARTBEAT_INTERVAL_MS = 1000`
-  - `RECONNECT_RETRY_MS = 5000`
-  - `syncServer`, `ServerClient.startHeartbeat`
 
 ### 2.8 Cloudflare Access handling
 
-Current behavior for sub-hosts:
-- requests use `credentials: 'include'` so Access cookies can be sent.
-- requests default to `redirect: 'manual'` on non-main hosts.
-- Access redirect is treated as reconnect reason, not generic password failure.
-- reconnect UI can trigger opening host root in a new tab for Access login.
+- Non-main host requests use `credentials: 'include'`.
+- Non-main host fetches default to `redirect: 'manual'`.
+- Access redirects should show reconnect/login state, not generic password
+  failure.
+- Reconnect UI may open the host root in a new tab for Access login.
 
 Relevant code:
 - `public/app.js`
-  - `ServerClient.fetch`
-  - `probeAccessLoginUrl`
-  - `openAccessLoginPage`
 - `public/modules/url-auth.js`
-  - `isAccessRedirectResponse`
-  - `buildAccessLoginUrl` (root origin)
 
-### 2.9 CORS policy in backend
+### 2.9 Runtime version and PWA coherence
 
-- Backend currently allows cross-origin by reflecting request origin when present.
-- For requests without origin, backend returns `Access-Control-Allow-Origin: *`.
-- OPTIONS is handled with 204 directly.
-- No per-origin `cors-origin` config is used now.
+- Backend heartbeat returns runtime boot id.
+- Frontend appends `?rt=<bootId>` and reloads on runtime change.
+- `index.html` versions `styles.css` and `app.js` with runtime key.
+- Service worker is versioned the same way.
 
 Relevant code:
-- `src/server.mjs` top-level CORS middleware
+- `src/server.mjs`
+- `public/app.js`
+- `public/index.html`
+- `public/sw.js`
 
-### 2.10 Runtime version and PWA cache coherence
+## 3) ACP Design Contracts
 
-- Backend heartbeat returns runtime boot id.
-- Frontend appends `?rt=<bootId>` to URL and reloads on server restart/version change.
-- `index.html` loads `styles.css` and `app.js` using runtime key.
-- SW is registered with `?rt=<bootId>`, cache key includes that runtime id.
-- App shell (`/`, `/index.html`, `/app.js`, `/styles.css`, `/modules/*`) uses
-  network-first.
+### 3.1 ACP architecture shape
 
-Relevant code:
-- `src/server.mjs` `/api/heartbeat` -> `runtime.bootId`
-- `public/app.js` `handlePrimaryRuntimeVersion`
-- `public/index.html` runtime loader script
-- `public/sw.js`
+- Tabminal embeds an ACP supervisor in the backend.
+- ACP agents are not implemented in-repo; Tabminal launches or attaches to
+  external ACP runtimes.
+- Built-in definitions currently include:
+  - Gemini CLI
+  - Codex CLI
+  - Claude Agent
+  - GitHub Copilot
+  - ACP Test Agent when `TABMINAL_ENABLE_TEST_AGENT=1`
 
-## 3) UX Contracts to Keep
+Relevant code:
+- `src/acp-manager.mjs`
+- `src/acp-test-agent.mjs`
 
-### 3.1 Sidebar host controls
+### 3.2 ACP workspace model
 
-- Per-host row: primary action button + (non-main only) remove button.
-- Remove button is overlay style (top-left), hidden by default, fades in on hover/focus.
-- Main host has no remove button.
-- Main button text:
-  - normal: `New Tab @ <Host>`
-  - reconnect: `Reconnect <Host>`
-  - access flow: `Cloudflare Login <Host>`
-- Second line includes latency text + heartbeat dot + mini heartbeat canvas.
+- Agent tabs share the same workspace strip as file tabs and pinned terminal
+  tabs.
+- Showing the agent workspace must not force-open the file tree.
+- Showing the file tree must not be required for agent tabs to exist.
+- Workspace bar should stay visible whenever there is any open file tab, agent
+  tab, or pinned terminal tab.
 
 Relevant code:
-- `public/app.js` `renderServerControls`
-- `public/styles.css` `.server-row`, `.server-main-button`, `.server-delete-button`
+- `public/app.js`
+- `public/styles.css`
 
-### 3.2 Host naming display
+### 3.3 Agent dropdown and toggle behavior
 
-Display priority for host name:
-1. configured `host` alias
-2. runtime hostname from host heartbeat
-3. URL hostname
-4. `'unknown'`
+- Left sidebar robot button is a toggle.
+- First click opens the host-scoped agent dropdown.
+- Clicking the same button again closes it.
+- If either file tree or agent toggle is active, the opposite control remains
+  visible; do not let one disappear while the other is lit.
 
-Session metadata line should stay:
-- `HOST: user@<host>`
-- host text uses `.host-emphasis` style.
+### 3.4 Jump in semantics
+
+- `Jump in` is not a read-only preview.
+- While the managed terminal is still alive, it should switch into a real
+  controllable terminal session.
+- If the terminal has already exited, the restored session is effectively
+  history-only.
+- Agent sync must never steal focus back from a session the user jumped into.
 
 Relevant code:
-- `public/modules/session-meta.js`
+- `public/app.js`
 
-### 3.3 Path display
+### 3.5 Hidden terminal resize contract
 
-- PWD display in tab meta uses fish-style compact path shortening.
-- Keep this style unless a full UX redesign is explicitly requested.
+- If a main terminal is hidden because it is pinned into a workspace tab and is
+  not the active visible tab, do not report resized dimensions from that hidden
+  state back to the backend.
+- Keep the previous valid size instead.
+- This prevents broken sidebar previews caused by tiny hidden-layout sizes.
 
 Relevant code:
-- `public/modules/session-meta.js` `shortenPathFishStyle`
+- `public/app.js`
 
-### 3.4 Small-screen rule (< 600px height)
+### 3.6 Shell ready noise filtering
 
-- `new-tab-item` region is capped to two-button area height and scrollable.
-- This is intentional for small-height mobile/embedded layouts.
+- `TABMINAL_SHELL_READY=1` and related shell bootstrap commands are internal.
+- They must not produce user notifications or visible execution-completed noise.
 
 Relevant code:
-- `public/styles.css` `@media (max-height: 600px)` on `.new-tab-item`
+- `shell/tabminal-bashrc`
+- `src/terminal-session.mjs`
+- `public/app.js`
 
-## 4) Known Pitfalls and Their Root Causes
+### 3.7 Agent plan behavior
 
-### 4.1 `SecurityError: insecure WebSocket from HTTPS page`
+- In-progress plan lives in the fixed area between activity strip and composer.
+- Once fully completed, it should archive into transcript history and stop
+  occupying the fixed panel slot.
+- Completed plans are historical transcript content, not permanent composer UI.
 
-Cause:
-- trying `ws://` from HTTPS page.
-Current mitigation:
-- WS URL builder chooses `wss://` if page is HTTPS or host URL is HTTPS.
+### 3.8 Transcript auto-scroll contract
 
-Check:
-- `public/app.js` `ServerClient.resolveWsUrl`
-- ensure host URL is HTTPS when used from secure origin.
+- If the user was already at the bottom, keep them pinned to bottom when:
+  - new transcript messages arrive
+  - tool-call terminal blocks grow
+  - plan/activity/queue panels change height
+  - transcript container height changes
+- If the user was not at the bottom, preserve position and do not yank them
+  back down.
 
-### 4.2 `TypeError: Failed to fetch` during heartbeat
+Relevant code:
+- `public/app.js`
 
-Usually means:
-- host down, DNS issue, TLS failure, CORS block, or network unreachable.
-Expected behavior:
-- warning-level reconnect messaging, not noisy crash behavior.
+### 3.9 Slash command menu contract
 
-Check:
-- browser network tab
-- host availability
-- Access auth state for that host
+- Slash-command menu opens upward, as a floating overlay above the composer.
+- It must not push the composer or nearby controls.
+- Keyboard navigation must keep the active item scrolled into view with some
+  padding from the edges.
+- Current shortcut to open agent menu is `Ctrl+Shift+A`.
 
-### 4.3 Cloudflare Access 302/login loops
+Relevant code:
+- `public/app.js`
+- `public/styles.css`
+- `public/index.html`
 
-Important:
-- CORS headers alone do not fix Access redirect login requirements.
-- Main issue is Access auth challenge during API request.
-- Current design handles this by detecting redirect and opening host root login page.
+### 3.10 Usage HUD contract
 
-### 4.4 Host list not restoring after refresh
+- Expanded usage HUD is now a CSS-driven fixed layout.
+- Do not reintroduce JS-measured width growth or time-based width drift.
+- Context line uses right-side usage text.
+- Limit rows use `% left` plus reset text.
+- The HUD should expand predictably and not resize every second as reset text
+  updates.
 
-Check in order:
-1. main host authenticated?
-2. `/api/cluster` returns expected `servers` array?
-3. entries include valid `id` and `baseUrl`?
-4. entry skipped as self-host by dedupe/hostname rule?
+Relevant code:
+- `public/styles.css`
+- `public/app.js`
 
-### 4.5 Same domain with different path does not behave as separate hosts
+## 4) ACP Status and Remaining Gaps
 
-Current architecture dedupes by `hostname[:port]` and uses absolute `/api/*`/`/ws/*`.
-Do not assume path-prefix multiplexing works without deeper routing redesign.
+`ACP_PLANING.md` is partly stale.
 
-## 5) File Map for Fast Onboarding
+Implemented from that plan:
 
-Backend:
-- `src/server.mjs`: API routes, WS upgrade, CORS, runtime boot id, startup/shutdown.
-- `src/config.mjs`: merged config parser (defaults/home/local/CLI/env), validation.
-- `src/auth.mjs`: hash auth, lockout logic, API and WS auth checks.
-- `src/persistence.mjs`: sessions, memory, cluster registry disk persistence.
-- `src/terminal-manager.mjs`: PTY session lifecycle + persistence glue.
-- `src/terminal-session.mjs`: terminal stream parsing, history, metadata, AI context.
+- ACP supervisor and backend APIs
+- ACP websocket fan-out
+- agent tab restore and `loadSession` restore where supported
+- slash commands
+- prompt attachments
+- structured tool cards
+- diff and code/resource rendering
+- managed terminal transcript UI
+- permission handling
+- usage HUD
+- browser smoke and ACP test agent support
 
-Frontend:
-- `public/app.js`: host/session state, sync loop, UI orchestration.
-- `public/modules/url-auth.js`: URL normalization, dedupe key, auth helpers.
-- `public/modules/session-meta.js`: host display and path shortening.
-- `public/styles.css`: sidebar/tab/host control styling and responsive rules.
-- `public/index.html`: shell DOM, runtime versioned loader, SW register.
-- `public/sw.js`: runtime-versioned caching strategy.
+Still not clearly done end-to-end:
 
-Native apps:
-- `apps/README.md`: native app architecture and rollout plan.
-- `apps/Apple`: Apple-platform app, Swift package, CLI launch scripts.
-- `apps/ghostty-vendor`: Ghostty xcframework build and verification helpers.
+- registry-driven install UX
+- explicit TCP ACP runtime support in the UI
+- dedicated conversation history browser independent of terminal sessions
 
-## 6) Logs and Debug Guidance
+Implication:
 
-Expected, low-noise warnings:
-- host unreachable / reconnect transitions.
-- invalid cluster entries skipped.
+- Do not delete `ACP_PLANING.md` just because most of the MVP shipped.
+- If it is removed later, first copy the still-open deferred items into a new
+  canonical roadmap document.
 
-Avoid:
-- spamming full stack traces for normal offline scenarios.
-- debug-only console noise left enabled by default.
+## 5) File Map for Fast Onboarding
 
-Note:
-- old `cluster-debug` helper has been intentionally removed; do not reintroduce
-  unless there is a concrete observability requirement.
+Backend:
+- `src/server.mjs`
+  - API routes, WS upgrade, auth, runtime boot id
+- `src/config.mjs`
+  - merged config parser and validation
+- `src/auth.mjs`
+  - password hashing and auth checks
+- `src/persistence.mjs`
+  - sessions, cluster registry, ACP tab/config persistence
+- `src/terminal-manager.mjs`
+  - PTY lifecycle and persistence
+- `src/terminal-session.mjs`
+  - terminal stream parsing, shell AI path, execution model
+- `src/acp-manager.mjs`
+  - ACP definitions, runtime supervision, ACP tab lifecycle
+- `src/acp-test-agent.mjs`
+  - local ACP smoke agent with slash-command fixtures
 
-## 7) Security and Risk Notes
+Frontend:
+- `public/app.js`
+  - nearly all UI orchestration lives here
+- `public/modules/url-auth.js`
+  - URL normalization and auth helpers
+- `public/modules/session-meta.js`
+  - host display and compact path formatting
+- `public/styles.css`
+  - all current UI contracts and responsive rules
+- `public/index.html`
+  - shell DOM, layout bootstrapping, shortcuts modal
 
-- Product is high-privilege by design (terminal + file write).
-- AI features may send terminal context to model providers.
-- Current policy is explicit risk acknowledgment (`--accept-terms` / config flag).
-- Choose trusted model providers and least-privilege credentials.
+Tests and smoke:
+- `test/acp-manager.mjs`
+  - richest ACP coverage
+- `scripts/acp-browser-smoke.mjs`
+  - browser ACP smoke against a real running app and real Chrome remote debug
 
-## 8) Deployment and Ops Notes
+## 6) Debug and Testing Guidance
 
-- Local helper script: `reploy.sh` (intentionally ignored by git and npm package).
-- It restarts one macOS launchctl node + several Linux pm2 nodes via SSH.
-- Script contains aggressive cleanup on Linux nodes (reset/clean fallback);
-  use carefully in shared environments.
+### 6.1 Basic quality gates
 
-## 9) Quality Gates Before Release
+Run these before release or after meaningful ACP/UI changes:
 
-Recommended checks:
 1. `npm run lint`
 2. `npm test`
 3. `npm run build`
-4. quick manual smoke:
-   - main host login
-   - add host (with and without password, inheritance path)
-   - reconnect flow (normal + Access login path)
-   - delete host
-   - restart backend and confirm runtime cache refresh (`rt` flow)
 
-## 10) Change Safety Rules for Future Refactors
+### 6.2 ACP test agent
+
+Enable it with:
+
+```bash
+TABMINAL_ENABLE_TEST_AGENT=1 npm start -- --accept-terms
+```
+
+Useful slash commands in ACP Test Agent:
+
+- `/demo`: richest happy-path demo
+- `/plan`: plan and usage only
+- `/diff`: terminal, diff, code/resource payloads
+- `/permission`: permission flow
+- `/cancel`: long-running cancel flow
+- `/stale`: stale tool settlement path
+- `/order`: message ordering around tools
+- `/fail`: prompt error path
+
+Use these instead of inventing ad-hoc prompts when validating ACP UI.
+
+### 6.3 Browser smoke
+
+Preferred browser smoke:
+
+- `scripts/acp-browser-smoke.mjs`
+
+It supports:
+
+- Chrome remote debugging target
+- ACP Test Agent slash-command flows
+- attachment coverage
+- tool/diff/code/terminal assertions
+- restore-tail validation
+
+Typical setup:
+
+1. Start a local Tabminal instance with `TABMINAL_ENABLE_TEST_AGENT=1`
+2. Run Chrome with remote debugging
+3. Point smoke at that Chrome target and Tabminal URL
+
+### 6.4 Availability/debug tips
+
+If an ACP agent appears inconsistently available:
+
+- Compare the backend runtime `PATH` with your interactive shell `PATH`.
+- Do not assume your login shell and the running `npm start` environment match.
+- Copilot and other CLIs may live in `~/.local/bin`; ACP discovery now augments
+  common user-local bin paths.
+- Restore failures should not temporarily mark built-in definitions unavailable.
+
+Relevant code:
+- `src/acp-manager.mjs`
+
+### 6.5 Focus and session-debug tips
+
+If `Jump in` appears to bounce back to the original agent workspace:
+
+- inspect agent-sync code first
+- the previous bug was backend updates restoring preferred workspace on the
+  wrong session and stealing focus
+
+If terminal preview proportions become huge:
+
+- check whether a hidden terminal is still reporting resized dimensions
+
+If you get noisy shell-ready notifications:
+
+- check for internal execution events being surfaced to the frontend
+
+## 7) Known Pitfalls
+
+### 7.1 `SecurityError: insecure WebSocket from HTTPS page`
+
+Cause:
+- trying `ws://` from an HTTPS page
+
+Mitigation:
+- websocket URL must switch to `wss://` when page or host URL is HTTPS
+
+### 7.2 `TypeError: Failed to fetch` during heartbeat
+
+Typical causes:
+- host down
+- DNS/TLS failure
+- CORS block
+- network unreachable
+- Cloudflare Access auth needed
+
+Expected behavior:
+- reconnect warning state, not noisy crash behavior
+
+### 7.3 Cloudflare Access loops
+
+- CORS headers alone do not solve auth redirects.
+- The problem is usually Access challenge during API fetch.
+- Current model is to detect redirect and open host root login page.
+
+### 7.4 Same domain with different path as multiple hosts
+
+- Not supported by current assumptions.
+- Do not patch around this casually; it needs a deeper routing redesign.
+
+## 8) Security and Risk Notes
+
+- Product is high-privilege by design.
+- AI features may send terminal or agent context to external providers.
+- `--accept-terms` is the explicit risk-ack mechanism.
+- Prefer least-privilege credentials and trusted providers.
+
+## 9) Deployment and Ops Notes
+
+- Local helper script:
+  - `reploy.sh`
+- It restarts one macOS launchctl node plus several Linux `pm2` nodes via SSH.
+- It includes aggressive cleanup behavior on Linux nodes; use carefully.
+
+## 10) Change Safety Rules
 
-- Do not move host list back to localStorage.
+- Do not move host registry persistence back into browser-owned local state.
 - Do not make sub-host auth failures trigger global logout.
 - Do not remove `credentials: 'include'` from host fetch wrapper.
-- Do not remove reconnect backoff (`5s`) or online heartbeat cadence (`1s`).
+- Do not remove the `1s` heartbeat or `5s` reconnect throttle without evidence.
 - Do not reintroduce backend auto-create-session fallback.
-- Do not add path-based host assumptions without redesigning URL/WS routing model.
+- Do not bring back JS-driven usage HUD width measurement.
+- Do not let agent sync steal focus from a user-selected terminal session.
+- Do not let hidden terminal tabs report bogus tiny sizes to the backend.

package/README.md

@@ -267,8 +267,8 @@ reliable.
 
 ## Architecture Snapshot
 
-- Backend: Node.js, Koa, `node-pty`, WebSocket, ACP SDK
-- Frontend: vanilla JS, `xterm.js`, Monaco Editor
+- Backend: [`Node.js`](https://nodejs.org/), [`utilitas`](https://github.com/leask/utilitas), [`Koa`](https://github.com/koajs/koa), [`node-pty`](https://github.com/Tyriar/node-pty), [`WebSocket`](https://github.com/websockets/ws), [`ACP SDK`](https://github.com/acp-kit/acp-sdk)
+- Frontend: [`Vanilla JS 😝`](http://vanilla-js.com/), [`xterm.js`](https://github.com/xtermjs/xterm.js), [`Monaco Editor`](https://github.com/microsoft/monaco-editor)
 - Persistence: host-local files under `~/.tabminal`
 - Native clients and packaging work live under:
   - `apps/Apple`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tabminal",
-  "version": "2.0.15",
+  "version": "2.0.17",
   "description": "A modern, persistent web terminal with multi-tab support and real-time system monitoring.",
   "type": "module",
   "bin": {