@termfleet/terminal

Compatibility entrypoints for the framework-neutral terminal transport and durable tmux primitives owned by @volter-ai-dev/supercode-terminal.

Each legacy module directly reexports its corresponding @volter-ai-dev/supercode-terminal/substrate/<module>.js module. Existing public exports and TypeScript types remain available at the seven legacy subpaths below. This package contains no terminal implementation or additional wrapper behavior; changes belong in the Supercode owner package.

The owner manages terminal attachment lifetimes. Closing an attachment releases its WebSocket, PTY client, listeners, timers, and file descriptors; it does not terminate the durable tmux session. Session termination remains a separate, explicit operation controlled by the embedding host.

Exports are split by environment without splitting the package:

• @termfleet/terminal/client.js — browser-safe terminal WebSocket client and wire contract, including live control-attachment resize.
• @termfleet/terminal/attach.js — Node CLI attachment loop with deterministic TTY restoration and Ctrl-b d detach.
• @termfleet/terminal/local-terminal.js — structured launch in macOS Terminal.
• @termfleet/terminal/tmux.js — Node tmux session, capture, input, and ownership primitives.
• @termfleet/terminal/tmux-stream.js — Node PTY-to-WebSocket attachment with idempotent handle cleanup.
• @termfleet/terminal/native-host.js — an embedded macOS host that discovers, captures, opens, and safely relinquishes user-owned Terminal/iTerm agent sessions without a Termfleet provider or server process.
• @termfleet/terminal/session-lifecycle.js — the shared semantic lifecycle observer used by both the embedded host and full Termfleet providers.

@homebridge/node-pty-prebuilt-multiarch and ws are optional peers because browser-only consumers need neither. A host importing tmux-stream.js must provide both.

The tmux helpers accept an optional socket everywhere, so applications can use an isolated tmux server instead of touching the user's default server. Created sessions can carry an app-namespaced ownership mark; discovery does not claim or terminate unmarked sessions. Terminal attachment is intentionally separate from session termination: disposing a viewer only detaches its ephemeral PTY client and releases all handles.

Interactive clients may send bounded resize frames after the initial size negotiation. The PTY follows those dimensions live, while read-only observers continue inheriting the durable pane's size and can never reflow it.

@termfleet/terminal/local-terminal.js opens a structured command in the user's macOS Terminal without constructing AppleScript from caller data. Every program, argument, working directory, and environment value is POSIX-quoted before the fixed AppleScript receives it as a single argv value. Unsupported platforms fail honestly instead of guessing a terminal emulator.

The native host deliberately returns only durable agent session IDs, backend names, and semantic lifecycle states. Native window IDs, TTYs, PIDs, AppleScript references, and tmux handles stay inside the host process. Moving a session requires a fresh idle proof from an independent agent-aware observer; the terminal screen alone cannot authorize a second writer.

Modern Codex versions may not keep their rollout file open. The host retains those process-keyed candidates privately, matches them to an expected working directory with hasSessionCandidate(), and resolves the exact durable ID plus idle proof through resolveSession() only when an embedder explicitly requests a handoff.

createSession accepts a structured { program, arguments } command plus an environment map. Arguments are passed directly without constructing a shell command, and the credential bootstrap deletes itself before the command starts.