@dotobokuri/fleet-console 1.9.0 → 1.10.1

package/AGENTS.md

@@ -4,13 +4,13 @@
 
 ## Owns
 
-- The console HTTP backend (loopback-only): its own server skeleton, security headers, static `/console/` serving of its own `dist/client/`, the browser observer REST/SSE surface, and the terminal PTY WebSocket. The console no longer imports or launches the retired gateway package.
+- The console HTTP backend (loopback-only): its own server skeleton, security headers, static `/console/` serving of its own `dist/client/`, the browser observer REST/SSE surface (including the `validateHost`-gated `GET /observer/api-catalog` route-catalog introspection that backs the Settings backend-API list), and the terminal PTY WebSocket. The console no longer imports or launches the retired gateway package.
 - The server lifecycle: lock file, runtime paths, health probe, and build-stale detection are console-owned. `fleet-console` is the daemon, not a launcher over someone else's daemon.
 - The `fleet-console` CLI entry point (`./cli` export, `dist/cli.mjs`): `start` (the default when no subcommand is given) ensures the local console server and opens the console URL in a browser; if a healthy daemon already exists, it opens that daemon's URL without starting a new server or erroring. `stop` stops the console server; `restart` stops the console server then starts a fresh one and opens it; `status` prints server health, endpoint, console URL, and registered-workspace count. The server binds to an OS-assigned random loopback port and records the actual port in the lock file, so consumers discover the port from the lock endpoint. `--help`/`-h` prints the banner-style help. `fleet console <args>` in `fleet-cli` relays the full argument list to this CLI as a child process, so every subcommand works through both `fleet console …` and the standalone `fleet-console …` binary. The root `pnpm fleet-console` script runs it from source via `tsx`; unpublished local runs isolate runtime files under the project workspace `.fleet/console` unless `FLEET_CONSOLE_DIR` is set, while published stable builds continue using the OS temp directory.
 - Console-owned terminal sessions are spawned server-side and observed in-process; carrier events flow directly into the observer store and browser SSE without a separate fleet-cli registration channel.
 - Console durable state is persisted in the console data directory's `state.json` (`createDurableJsonStore`, `sensitivity: "sensitive"`). The data directory follows the release channel: published stable builds use `~/.fleet/console/state.json`, while unpublished local runs (`pnpm fleet-console`/`tsx`) use the project workspace `.fleet/console/state.json` co-located with the lock, so a dev console never shares Theaters/Operations with a globally installed one. Setting `FLEET_CONSOLE_DIR` relocates the durable state (and captures) into that directory too — co-located with the lock, matching the runtime-file escape hatch — so a read-only checkout can point its writable runtime slot away from the project tree. The console server is the sole writer; the file stores `{ version: 1, theaters, operations }`. On startup the server restores Theaters and Operations into a dormant state (no PTY), and Operation state survives console restarts. Each Operation also records whether its label came from the operator or from automatic naming (`labelSource`), so the prompt-derived auto-name never overwrites a manual rename.
 - A capture inbound channel writes `{fleetSessionId}.json` under the same console data directory's `captures/` (`~/.fleet/console/captures/` for stable, the project `.fleet/console/captures/` for local runs). Provider CLI SessionStart hooks record provider session ids via `fleet-console hook capture-session <provider>`; the server reads the capture file, merges the provider session id into durable state, and cleans up the capture file. This is separate from the console lock file in `os.tmpdir()` (stable) / the project `.fleet/console` lock (local).
-- The React SPA served from the console backend at `/console/`: layout, components, styles, and visual identity. The global navigation bar owns **Theater** selection — a project root directory that groups console-owned terminal sessions and Codex wiki context. The Operations sidebar (under the Operation nav tab) lists terminal sessions filtered to the active Theater and provides a launch control that asks the operator to choose an Agent CLI before starting a new terminal session; each session lists its carrier job history (active and finished) in registration order, and selecting a job opens a centered streaming overlay over that session's terminal, scoped to the active session's jobs. A console-wide Operation quick-search (Cmd/Ctrl+K) searches terminal sessions across all Theaters, switches to the selected Operation's Theater, selects that Operation, and navigates to `/operations`; on `/codex` paths the same shortcut yields to Codex's own search.
+- The React SPA served from the console backend at `/console/`: layout, components, styles, and visual identity. The global navigation bar owns **Theater** selection — a project root directory that groups console-owned terminal sessions and Codex wiki context. The Operations surface renders a single spatial Map canvas of terminal sessions filtered to the active Theater; operators create sessions directly on the canvas (Shift-drag or right-click), choosing an Agent CLI before a new terminal session starts. Each session panel lists its active carrier jobs in a floating job dock, and selecting a job opens a centered streaming overlay scoped to that session's jobs. The canvas also hosts free shell panels (right-click) that resolve their cwd from the active Theater. A console-wide Operation quick-search (Cmd/Ctrl+K) searches terminal sessions across all Theaters, switches to the selected Operation's Theater, selects that Operation, and navigates to `/operations`; on `/codex` paths the same shortcut yields to Codex's own search.
 - The Codex/Fleet Wiki web surface under `/console/codex`: the console-owned Codex server gateway, workspace registry, wiki API routes, migrated vanilla TypeScript Maritime Codex client, `fleet wiki` compatibility helpers, and standalone `fleet-wiki` binary shim. The console-level **TheaterRegistry** is the source of truth for project roots and does not require a Fleet Wiki knowledge root; the Codex `WorkspaceRegistry` is the subset of Theaters whose directories contain a Fleet Wiki knowledge root. Codex must remain mounted under the Fleet Console GNB without an iframe or proxy daemon.
 - The observer-side client contract: REST snapshot fetches and the SSE consumption loop with reconnect/resync.
 - The streaming view model: the event reducer that folds `CarrierJobStreamEvent` timelines into per-job, per-track views with incremental text accumulation.
@@ -21,7 +21,7 @@
 - Canonical Codex workspace routes live under `/console/codex/w/:ws/...`; MRU-compatible API routes live under `/console/codex/api/...`. Do not reintroduce global `/api/...` wiki routes because console owns its own local API namespace.
 - The console-level **Theater** is the parent concept for project roots. Codex workspaces share the same id space (`workspaceHash(realpath(dir))`) but are a strict subset of the Theater registry (`hasWiki=true`). The Codex left workspace switcher is removed; Theater selection in the global navigation bar is the only workspace switch, and Theaters without a Fleet Wiki knowledge root render a "Codex 없음" state instead of mounting a wiki surface.
 - The migrated Codex client stays Vanilla TypeScript under `client/src/codex/**`; do not rewrite it into React state or components beyond the React mount host.
-- Codex has two presentation modes — **Full** (the dedicated `/console/codex` route) and **Side** (a right-docked overlay panel over the current route). A single shared mount host (`codex-host.ts`) is relocated between containers with `appendChild` and is never mounted twice — the Vanilla client is a module-level singleton, so exactly one Codex instance is ever live and switching modes must not `destroy()`+remount. In every mode the URL stays `/console/codex/...`; Side keeps the previously active route mounted as a background via the react-router `<Routes location=…>` pattern, and a direct deep-link or refresh onto `/codex` always renders Full. The view mode persists at `fleet-console.codex.view-mode` (`route`|`side`) and is switchable both from the global navigation bar (on the Codex route) and, while Side is closed, from a right-edge handle shown on any non-Codex route that opens Side directly (navigates to `/codex` and switches to `side`); the Side panel width persists at `fleet-console.codex.side-width` with no fixed min/max (viewport-bounded only), and the Codex layout is container-responsive — it sheds the rail, then the nav, as the panel narrows, leaving only the reading content. While Side is open, the ⌘K command palette is scoped to the Side panel region instead of rendering full-screen (driven by a `data-codex-side` body marker plus the `--codex-side-width` body variable), and the panel header carries manual collapse toggles for the left (Nav) and right (ToC/Manifest) panes — persisted at `fleet-console.codex.nav-collapsed`/`fleet-console.codex.rail-collapsed` and applied via `app-shell--nav-collapsed`/`app-shell--rail-collapsed` grid classes, independent of the container-query auto-collapse. The pane-collapse state is owned by the Vanilla Codex module and exposed to the React surface only through the `codex-host.ts` boundary.
+- Codex has two presentation modes — **Full** (the dedicated `/console/codex` route) and **Side** (a right-docked overlay panel over the current route). A single shared mount host (`codex-host.ts`) is relocated between containers with `appendChild` and is never mounted twice — the Vanilla client is a module-level singleton, so exactly one Codex instance is ever live and switching modes must not `destroy()`+remount. In every mode the URL stays `/console/codex/...`; Side keeps the previously active route mounted as a background via the react-router `<Routes location=…>` pattern, and a direct deep-link or refresh onto `/codex` always renders Full. The view mode persists at `fleet-console.codex.view-mode` (`route`|`side`) and is switchable from a right-edge handle shown on any non-Codex route that opens Side directly (navigates to `/codex` and switches to `side`); the Side panel width persists at `fleet-console.codex.side-width` with no fixed min/max (viewport-bounded only), and the Codex layout is container-responsive — it sheds the rail, then the nav, as the panel narrows, leaving only the reading content. While Side is open, the ⌘K command palette is scoped to the Side panel region instead of rendering full-screen (driven by a `data-codex-side` body marker plus the `--codex-side-width` body variable), and the panel header carries manual collapse toggles for the left (Nav) and right (ToC/Manifest) panes — persisted at `fleet-console.codex.nav-collapsed`/`fleet-console.codex.rail-collapsed` and applied via `app-shell--nav-collapsed`/`app-shell--rail-collapsed` grid classes, independent of the container-query auto-collapse. The pane-collapse state is owned by the Vanilla Codex module and exposed to the React surface only through the `codex-host.ts` boundary.
 - The Codex reading surface uses a single `app-shell` grid for every route. The reading measure (78ch at 17px / 1.78) is owned by `.markdown-body` and its reading-wrapper siblings (`.document-header`, `.related-list`) — never the shell grid; the shell max-width is 1680px and the rail track is `clamp(272px, 20vw, 320px)`. Shell modifiers are limited to `app-shell--wide` (browse routes home/index-md/log/conflicts/queue — rail removed), `app-shell--raw` (raw source — rail removed, full-width body, sidebar kept; the old `renderRawShell()` is gone), and the Side-only `app-shell--nav-collapsed`/`app-shell--rail-collapsed`. Modifiers only set grid columns/areas (single-class or `:where()` specificity) so the 900px/560px container queries still win by cascade, and queue-detail keeps its own internal `1fr + 300px` layout. The reading rail renders the ToC before the Manifest (the Manifest is an open-by-default `<details>`), the ToC has an `IntersectionObserver` scroll-spy that cleans up on every route change, and below 760px the rail is replaced by a document-level ToC drawer (a focus-trapped `role="dialog"`). Reading entries carry a breadcrumb and drop a duplicate title only when the first markdown H1 exactly normalizes to the entry title. Codex typography is tokenized through `--font-size-*`; brass = active/location and aurora = live/link semantics, glass surfaces, self-hosted Fraunces/Manrope/JetBrains Mono, and `prefers-reduced-motion` short-circuits are unchanged.
 - Preserve Maritime Codex UX: reading flow, raw viewer, Drydock queue, conflicts, index/log views, command palette, Manifest/ToC rails, copy-context actions, diagram lightbox, brass/aurora roles, and self-hosted fonts.
 - Preserve wiki security invariants: Host allowlist, Origin guard, write-surface loopback gate, DOMPurify markdown sanitization, Mermaid `securityLevel: "strict"` with `htmlLabels: false` and no `bindFunctions`, path containment, and lockfile bearer auth for admin workspace registration.
@@ -62,7 +62,7 @@
 
 ## Tech Stack (deliberate)
 
-- **React 19 + Vite + TypeScript.** Chosen because the console's core requirement is smooth incremental streaming UI and the package is slated to grow into the unified Fleet GUI. Do not replace with hand-rolled DOM rendering. A second surface has now landed (the Welcome dashboard), so `react-router-dom` (`BrowserRouter` with `basename="/console"`) is the sanctioned client router. Routes: `/` renders **Welcome** (the live dashboard); `/operations` renders the carrier observation surface (Sidebar + JobView); unknown paths redirect to `/`. The console backend already serves extensionless `/console/*` paths as `index.html` (SPA fallback in `static-console.ts`), so client-side routes require **no** backend change. Routing state belongs to react-router; observation data stays in the external `store.ts`. Do not add a state-management library until that store proves insufficient.
+- **React 19 + Vite + TypeScript.** Chosen because the console's core requirement is smooth incremental streaming UI and the package is slated to grow into the unified Fleet GUI. Do not replace with hand-rolled DOM rendering. `react-router-dom` (`BrowserRouter` with `basename="/console"`) is the sanctioned client router. Routes: `/` redirects to `/operations`; `/operations` renders the carrier observation surface (the Map canvas of session panels + JobView); unknown paths redirect to `/operations`. The console backend already serves extensionless `/console/*` paths as `index.html` (SPA fallback in `static-console.ts`), so client-side routes require **no** backend change. Routing state belongs to react-router; observation data stays in the external `store.ts`. Do not add a state-management library until that store proves insufficient.
 - State lives in a framework-agnostic external store (`client/src/store.ts`) bridged via `useSyncExternalStore`. Pure reduction logic stays in `client/src/reduce.ts` and must remain React-free and unit-tested.
 - Web fonts are self-hosted via `@fontsource-variable/*`. External font CDNs are forbidden.
 - Browser launch must use OS-level commands via `child_process.spawn`; do not add an `open` dependency.