@pellux/goodvibes-terminal-shell 1.7.0

package/README.md

@@ -0,0 +1,45 @@
+# @pellux/goodvibes-terminal-shell
+
+Shared terminal-shell plumbing for GoodVibes daemon front-ends. Two front-ends drive a full-screen terminal UI over the same daemon runtime, and they must keep a specific slice of that runtime wiring **identical**. When copies of it drift, real defects ship. This package is the single home for that slice, so each front-end consumes one implementation instead of maintaining a parallel copy.
+
+## Install
+
+```sh
+npm install @pellux/goodvibes-terminal-shell
+```
+
+## What belongs here
+
+Plumbing that must not drift between front-ends:
+
+- **Gateway verb-group composition** — `attachWsOnlyGatewayVerbHandlers(catalog, deps)` binds the ws-only verb DESCRIPTORS (`fleet.*`, `checkpoints.*`, `sessions.search`, `push.*`) to their HANDLERS together, so a verb can never be descriptor-present but handler-absent. A descriptor with no handler answers `501 "Gateway method is not invokable"` over both websocket and HTTP invoke; registering the two together is what prevents that. `createArchivableFleetRegistry(deps)` builds the one shared, archive-aware process registry the `fleet.*` verbs query.
+- **Terminal enter/restore sequencing** — `createTerminalLifecycle(deps)` owns the alt-screen enter, the idempotent synchronous restore (leave the alt screen, or clear the primary viewport **without** `ESC[3J` so scrollback survives; show the cursor on the screen the shell prompt lands on), and the restored-state gate `isTerminalRestored()`. The canonical escape sequences live in `TERMINAL_ESCAPES`.
+- **Render-tick coalescing** — `createRenderScheduler(renderNow, scheduleFlush?, isReleased?)` collapses a within-tick burst of render requests into exactly one composite. Wire its third `isReleased` argument to the lifecycle's `isTerminalRestored()` so a late frame after teardown cannot paint over the restored shell.
+- **The descriptor/handler conformance gate** — see below.
+
+Every capability is a thin, dependency-injected wrapper: the front-end passes its concrete managers (process registry, checkpoint manager, session broker, secrets manager, approval broker, shell paths, terminal I/O) in, and this package owns the wiring.
+
+## What does NOT belong here
+
+Surface that front-ends legitimately diverge on, and which must stay in each app:
+
+- Panels, views, and read-models
+- Rendering, layout, and theming
+- Keybindings and input handling
+- Command surfaces and slash commands
+- Application shutdown policy (draining services, persisting sessions, exit codes) — each app calls this package's `restoreTerminal()` for the terminal hand-back, but owns its own teardown.
+
+## The conformance gate
+
+The exact regression this package exists to prevent — a registered descriptor with no handler — is catchable in your own CI. Compose your daemon/gateway catalog exactly as production does, then assert every descriptor is invokable:
+
+```ts
+import { assertEveryDescriptorHasHandler } from '@pellux/goodvibes-terminal-shell/conformance';
+
+test('every registered gateway descriptor has a handler', () => {
+  const catalog = composeMyDaemonCatalog();
+  assertEveryDescriptorHasHandler(catalog); // throws with the offending ids
+});
+```
+
+`findMethodsMissingHandlers(catalog, options)` returns the offending ids instead of throwing. Both accept `onlyIds` / `ignoreIds` for catalogs whose builtin descriptors get handlers from a different layer. The catalog is read through a narrow structural view, so any `GatewayMethodCatalog`-shaped object works.

package/dist/conformance.d.ts

@@ -0,0 +1,11 @@
+/**
+ * conformance.ts — the descriptor/handler drift gate.
+ *
+ * The gate's implementation now lives once in the contracts package
+ * (@pellux/goodvibes-contracts/testing) so every consuming front-end runs the
+ * SAME kit rather than a divergent local copy. This module re-exports it so
+ * @pellux/goodvibes-terminal-shell's public surface is unchanged — the single
+ * source moved, the consumer contract did not.
+ */
+export { findMethodsMissingHandlers, assertEveryDescriptorHasHandler, type GatewayCatalogConformanceView, type ConformanceOptions, } from '@pellux/goodvibes-contracts/testing';
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,GACxB,MAAM,qCAAqC,CAAC"}

package/dist/conformance.js

@@ -0,0 +1,10 @@
+/**
+ * conformance.ts — the descriptor/handler drift gate.
+ *
+ * The gate's implementation now lives once in the contracts package
+ * (@pellux/goodvibes-contracts/testing) so every consuming front-end runs the
+ * SAME kit rather than a divergent local copy. This module re-exports it so
+ * @pellux/goodvibes-terminal-shell's public surface is unchanged — the single
+ * source moved, the consumer contract did not.
+ */
+export { findMethodsMissingHandlers, assertEveryDescriptorHasHandler, } from '@pellux/goodvibes-contracts/testing';

package/dist/gateway-verbs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * gateway-verbs.ts — attach handlers for every ws-only gateway verb group, and
+ * build the archive-aware fleet registry, in one shared place both daemon
+ * front-ends consume.
+ *
+ * The GatewayMethodCatalog's builtin DESCRIPTORS make fleet.* (including the
+ * archive verbs), checkpoints.*, sessions.search, and push.* appear in the
+ * contract, but a descriptor without an attached handler answers
+ * 501 "Gateway method is not invokable" over both websocket and HTTP invoke.
+ * A composition root that registers those descriptors but never calls the SDK's
+ * registration entry point ships exactly that 501 for the whole ws-only family
+ * — the regression this package exists to make impossible to reintroduce
+ * independently in each front-end. `attachWsOnlyGatewayVerbHandlers` binds the
+ * descriptors and their handlers together, and the conformance helper in
+ * ./conformance.ts gates that no descriptor is ever left handler-less.
+ *
+ * This module is a thin, dependency-injected wrapper over the SDK's own
+ * registration entry points. Front-ends pass their concrete managers in; the
+ * package owns the wiring so it cannot drift between them.
+ */
+import { type GatewayMethodCatalog, type GatewayVerbGroupDeps } from '@pellux/goodvibes-sdk/platform/control-plane';
+import { type ArchivableProcessRegistry, type ProcessRegistryDeps } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
+/**
+ * Attach handlers for the ws-only gateway verb groups (fleet.* / checkpoints.* /
+ * sessions.search / push.*) onto an existing catalog. Descriptors and handlers
+ * are registered together, so a verb can never be descriptor-present but
+ * handler-absent (the 501 regression class).
+ *
+ * Call once, at composition time, after the injected managers all exist. The
+ * dependency shape (`GatewayVerbGroupDeps`) is owned by the SDK; this wrapper
+ * exists so each front-end has a single named call site instead of reaching
+ * into the SDK's registration internals directly and diverging.
+ */
+export declare function attachWsOnlyGatewayVerbHandlers(gatewayMethods: GatewayMethodCatalog, deps: GatewayVerbGroupDeps): void;
+/**
+ * Build the one shared, archive-aware process registry that aggregates a
+ * front-end's runtime managers (agents, WRFC chains, workflows, watchers,
+ * background processes). Constructed once per composition — not per consumer —
+ * so the coalesced tick and the agent-activity side-table are shared, not
+ * duplicated. Archive-aware: finished agent/swarm subtrees can be moved out of
+ * the live fleet view into a session-scoped archive (see the SDK's
+ * fleet/archive.ts).
+ *
+ * This is the registry the fleet.* gateway verbs above query, so building it
+ * here keeps the registry and its verb handlers on the same shared seam.
+ */
+export declare function createArchivableFleetRegistry(deps: ProcessRegistryDeps): ArchivableProcessRegistry;
+export type { GatewayVerbGroupDeps, ProcessRegistryDeps, ArchivableProcessRegistry };
+//# sourceMappingURL=gateway-verbs.d.ts.map

package/dist/gateway-verbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-verbs.d.ts","sourceRoot":"","sources":["../src/gateway-verbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACzB,MAAM,8CAA8C,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAC7C,cAAc,EAAE,oBAAoB,EACpC,IAAI,EAAE,oBAAoB,GACzB,IAAI,CAEN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,mBAAmB,GAAG,yBAAyB,CAElG;AAED,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/gateway-verbs.js

@@ -0,0 +1,51 @@
+/**
+ * gateway-verbs.ts — attach handlers for every ws-only gateway verb group, and
+ * build the archive-aware fleet registry, in one shared place both daemon
+ * front-ends consume.
+ *
+ * The GatewayMethodCatalog's builtin DESCRIPTORS make fleet.* (including the
+ * archive verbs), checkpoints.*, sessions.search, and push.* appear in the
+ * contract, but a descriptor without an attached handler answers
+ * 501 "Gateway method is not invokable" over both websocket and HTTP invoke.
+ * A composition root that registers those descriptors but never calls the SDK's
+ * registration entry point ships exactly that 501 for the whole ws-only family
+ * — the regression this package exists to make impossible to reintroduce
+ * independently in each front-end. `attachWsOnlyGatewayVerbHandlers` binds the
+ * descriptors and their handlers together, and the conformance helper in
+ * ./conformance.ts gates that no descriptor is ever left handler-less.
+ *
+ * This module is a thin, dependency-injected wrapper over the SDK's own
+ * registration entry points. Front-ends pass their concrete managers in; the
+ * package owns the wiring so it cannot drift between them.
+ */
+import { registerGatewayVerbGroups, } from '@pellux/goodvibes-sdk/platform/control-plane';
+import { createProcessRegistry, withFleetArchive, } from '@pellux/goodvibes-sdk/platform/runtime/fleet';
+/**
+ * Attach handlers for the ws-only gateway verb groups (fleet.* / checkpoints.* /
+ * sessions.search / push.*) onto an existing catalog. Descriptors and handlers
+ * are registered together, so a verb can never be descriptor-present but
+ * handler-absent (the 501 regression class).
+ *
+ * Call once, at composition time, after the injected managers all exist. The
+ * dependency shape (`GatewayVerbGroupDeps`) is owned by the SDK; this wrapper
+ * exists so each front-end has a single named call site instead of reaching
+ * into the SDK's registration internals directly and diverging.
+ */
+export function attachWsOnlyGatewayVerbHandlers(gatewayMethods, deps) {
+    registerGatewayVerbGroups(gatewayMethods, deps);
+}
+/**
+ * Build the one shared, archive-aware process registry that aggregates a
+ * front-end's runtime managers (agents, WRFC chains, workflows, watchers,
+ * background processes). Constructed once per composition — not per consumer —
+ * so the coalesced tick and the agent-activity side-table are shared, not
+ * duplicated. Archive-aware: finished agent/swarm subtrees can be moved out of
+ * the live fleet view into a session-scoped archive (see the SDK's
+ * fleet/archive.ts).
+ *
+ * This is the registry the fleet.* gateway verbs above query, so building it
+ * here keeps the registry and its verb handlers on the same shared seam.
+ */
+export function createArchivableFleetRegistry(deps) {
+    return withFleetArchive(createProcessRegistry(deps));
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @pellux/goodvibes-terminal-shell
+ *
+ * Shared terminal-shell plumbing for GoodVibes daemon front-ends. This is the
+ * single home for the runtime wiring that two front-ends must keep identical:
+ * gateway verb-group composition, terminal enter/restore sequencing, and
+ * render-tick coalescing. Each capability is a thin, dependency-injected wrapper
+ * so a front-end's composition root becomes a few named calls into this package
+ * instead of a hand-maintained copy that drifts.
+ *
+ * See ./conformance for the descriptor/handler gate a consumer runs against its
+ * own composition in CI.
+ */
+export { attachWsOnlyGatewayVerbHandlers, createArchivableFleetRegistry, type GatewayVerbGroupDeps, type ProcessRegistryDeps, type ArchivableProcessRegistry, } from './gateway-verbs.js';
+export { TERMINAL_ESCAPES, createTerminalLifecycle, type TerminalEscapes, type TerminalSequenceSet, type TerminalLifecycleDeps, type TerminalLifecycle, } from './terminal-lifecycle.js';
+export { createRenderScheduler, type RenderScheduler, } from './render-scheduler.js';
+export { findMethodsMissingHandlers, assertEveryDescriptorHasHandler, type GatewayCatalogConformanceView, type ConformanceOptions, } from './conformance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @pellux/goodvibes-terminal-shell
+ *
+ * Shared terminal-shell plumbing for GoodVibes daemon front-ends. This is the
+ * single home for the runtime wiring that two front-ends must keep identical:
+ * gateway verb-group composition, terminal enter/restore sequencing, and
+ * render-tick coalescing. Each capability is a thin, dependency-injected wrapper
+ * so a front-end's composition root becomes a few named calls into this package
+ * instead of a hand-maintained copy that drifts.
+ *
+ * See ./conformance for the descriptor/handler gate a consumer runs against its
+ * own composition in CI.
+ */
+export { attachWsOnlyGatewayVerbHandlers, createArchivableFleetRegistry, } from './gateway-verbs.js';
+export { TERMINAL_ESCAPES, createTerminalLifecycle, } from './terminal-lifecycle.js';
+export { createRenderScheduler, } from './render-scheduler.js';
+export { findMethodsMissingHandlers, assertEveryDescriptorHasHandler, } from './conformance.js';

package/dist/render-scheduler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * render-scheduler.ts — same-tick render coalescing for the terminal shell.
+ *
+ * A front-end fans out its own direct render() calls across turn/stream/input
+ * wiring (many invocation contexts). Each one previously ran a full synchronous
+ * composite the instant it was called. When several fire within a single
+ * event-loop tick — a streaming burst is the canonical case — only the LAST
+ * frame is ever visible; the earlier composites are immediately overwritten.
+ * This scheduler collapses every schedule() call made within one tick into a
+ * single composite flushed on the microtask queue, so the tick produces exactly
+ * one frame. That frame is byte-identical to what the last synchronous render()
+ * would have produced, because the coalesced flush runs after all of the tick's
+ * synchronous state mutations, reading the same final state the last direct
+ * render() would have read.
+ *
+ * This is deliberately SEPARATE from any cross-tick, throttled (~60fps)
+ * coalescer a front-end may run for its panel/input/runtime fan-out — that kind
+ * caps repaint RATE across ticks. This one collapses the WITHIN-tick burst with
+ * no added latency: a microtask flushes at the tail of the current tick, before
+ * the event loop yields to I/O, so the frame still lands in the same turn it was
+ * requested in.
+ *
+ * flushNow() preserves a synchronous immediate path for callers that genuinely
+ * need the frame composited before they return. Terminal resize is the known
+ * case: the resize handler resets the compositor diff and must repaint against
+ * the new dimensions synchronously rather than waiting for the microtask.
+ * flushNow() also clears any pending coalesced flush, so a resize (or any
+ * immediate paint) followed by an already-queued microtask never double-composites.
+ */
+export interface RenderScheduler {
+    /**
+     * Coalesced request: schedule a composite for the current tick. N calls within
+     * one tick collapse into exactly one composite, flushed on the microtask queue.
+     */
+    readonly schedule: () => void;
+    /**
+     * Immediate request: run the composite synchronously right now, and cancel any
+     * pending coalesced flush so the tick still composites only once. Use only where
+     * a caller genuinely requires synchronous output (terminal resize).
+     */
+    readonly flushNow: () => void;
+}
+/**
+ * Build a render scheduler around `renderNow` (the synchronous composite closure).
+ *
+ * `scheduleFlush` is the deferral primitive; it defaults to `queueMicrotask` so
+ * bursts coalesce within the current tick. Tests and benchmarks inject a manual
+ * queue to flush deterministically.
+ */
+export declare function createRenderScheduler(renderNow: () => void, scheduleFlush?: (flush: () => void) => void, 
+/**
+ * When provided and returning true, every composite path becomes a no-op.
+ * Wire this to the terminal lifecycle's isTerminalRestored(): once the exit
+ * teardown has handed the terminal back to the shell, a late frame (async
+ * shutdown races, stray timers) would paint cursor-positioned content over
+ * the user's primary screen and strand the next prompt mid-screen.
+ */
+isReleased?: () => boolean): RenderScheduler;
+//# sourceMappingURL=render-scheduler.d.ts.map

package/dist/render-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-scheduler.d.ts","sourceRoot":"","sources":["../src/render-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,IAAI,EACrB,aAAa,GAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,IAAqB;AAC3D;;;;;;GAMG;AACH,UAAU,GAAE,MAAM,OAAqB,GACtC,eAAe,CA2BjB"}

package/dist/render-scheduler.js

@@ -0,0 +1,72 @@
+/**
+ * render-scheduler.ts — same-tick render coalescing for the terminal shell.
+ *
+ * A front-end fans out its own direct render() calls across turn/stream/input
+ * wiring (many invocation contexts). Each one previously ran a full synchronous
+ * composite the instant it was called. When several fire within a single
+ * event-loop tick — a streaming burst is the canonical case — only the LAST
+ * frame is ever visible; the earlier composites are immediately overwritten.
+ * This scheduler collapses every schedule() call made within one tick into a
+ * single composite flushed on the microtask queue, so the tick produces exactly
+ * one frame. That frame is byte-identical to what the last synchronous render()
+ * would have produced, because the coalesced flush runs after all of the tick's
+ * synchronous state mutations, reading the same final state the last direct
+ * render() would have read.
+ *
+ * This is deliberately SEPARATE from any cross-tick, throttled (~60fps)
+ * coalescer a front-end may run for its panel/input/runtime fan-out — that kind
+ * caps repaint RATE across ticks. This one collapses the WITHIN-tick burst with
+ * no added latency: a microtask flushes at the tail of the current tick, before
+ * the event loop yields to I/O, so the frame still lands in the same turn it was
+ * requested in.
+ *
+ * flushNow() preserves a synchronous immediate path for callers that genuinely
+ * need the frame composited before they return. Terminal resize is the known
+ * case: the resize handler resets the compositor diff and must repaint against
+ * the new dimensions synchronously rather than waiting for the microtask.
+ * flushNow() also clears any pending coalesced flush, so a resize (or any
+ * immediate paint) followed by an already-queued microtask never double-composites.
+ */
+/**
+ * Build a render scheduler around `renderNow` (the synchronous composite closure).
+ *
+ * `scheduleFlush` is the deferral primitive; it defaults to `queueMicrotask` so
+ * bursts coalesce within the current tick. Tests and benchmarks inject a manual
+ * queue to flush deterministically.
+ */
+export function createRenderScheduler(renderNow, scheduleFlush = queueMicrotask, 
+/**
+ * When provided and returning true, every composite path becomes a no-op.
+ * Wire this to the terminal lifecycle's isTerminalRestored(): once the exit
+ * teardown has handed the terminal back to the shell, a late frame (async
+ * shutdown races, stray timers) would paint cursor-positioned content over
+ * the user's primary screen and strand the next prompt mid-screen.
+ */
+isReleased = () => false) {
+    let scheduled = false;
+    const flush = () => {
+        // A synchronous flushNow() (or a superseding immediate paint) before this
+        // microtask ran clears `scheduled`, turning this into a no-op so a single
+        // tick never composites twice.
+        if (!scheduled)
+            return;
+        scheduled = false;
+        if (isReleased())
+            return;
+        renderNow();
+    };
+    const schedule = () => {
+        if (scheduled)
+            return;
+        scheduled = true;
+        scheduleFlush(flush);
+    };
+    const flushNow = () => {
+        // Satisfy any pending coalesced flush, then composite synchronously.
+        scheduled = false;
+        if (isReleased())
+            return;
+        renderNow();
+    };
+    return { schedule, flushNow };
+}

package/dist/terminal-lifecycle.d.ts

@@ -0,0 +1,123 @@
+/**
+ * terminal-lifecycle.ts — shared terminal enter/restore sequencing for GoodVibes
+ * daemon front-ends.
+ *
+ * Both front-ends drive a full-screen terminal UI and must enter and later
+ * restore the terminal identically. When these sequences diverge between them,
+ * exit teardown leaves the wrong screen active or wipes the user's scrollback —
+ * a defect class that recurs whenever the two copies drift. This module is the
+ * single home for the escape sequences and the enter/restore ordering, so both
+ * front-ends share one implementation.
+ *
+ * What lives here is only the terminal-state sequencing and the restored-state
+ * gate. The graceful application shutdown (draining services, persisting
+ * sessions, exit codes) is front-end-specific and stays in each app's own
+ * process-lifecycle wiring; that wiring calls `restoreTerminal()` from this
+ * module for the synchronous terminal hand-back.
+ */
+/**
+ * The canonical control sequences the shell writes to enter and leave terminal
+ * mode (alt screen, mouse, cursor, keyboard-extension, paste, and focus
+ * reporting). Shared verbatim so the two front-ends cannot drift on the bytes.
+ */
+export declare const TERMINAL_ESCAPES: {
+    readonly ALT_SCREEN_ENTER: "\u001B[?1049h";
+    readonly ALT_SCREEN_EXIT: "\u001B[?1049l";
+    readonly MOUSE_ENABLE: "\u001B[?1000h\u001B[?1002h\u001B[?1006h";
+    readonly MOUSE_DISABLE: "\u001B[?1006l\u001B[?1002l\u001B[?1000l";
+    readonly CURSOR_HIDE: "\u001B[?25l";
+    readonly CURSOR_SHOW: "\u001B[?25h";
+    readonly KEYBOARD_EXT_ENABLE: "\u001B[>4;2m\u001B[?1u";
+    readonly KEYBOARD_EXT_DISABLE: "\u001B[>4;0m\u001B[?1l";
+    readonly PASTE_ENABLE: "\u001B[?2004h";
+    readonly PASTE_DISABLE: "\u001B[?2004l";
+    readonly FOCUS_ENABLE: "\u001B[?1004h";
+    readonly FOCUS_DISABLE: "\u001B[?1004l";
+    /**
+     * Clear viewport + home the cursor, WITHOUT ESC[3J. The 3J form wipes the
+     * user's PRIMARY-screen scrollback on several emulators; the restore path
+     * must never use it. Used by the no-alt-screen restore path.
+     */
+    readonly CLEAR_VIEWPORT_HOME: "\u001B[2J\u001B[H";
+};
+export type TerminalEscapes = typeof TERMINAL_ESCAPES;
+/**
+ * The subset of escape sequences the enter/restore paths compose. Defaults to
+ * TERMINAL_ESCAPES; overridable only for tests that assert exact byte output.
+ */
+export interface TerminalSequenceSet {
+    readonly ALT_SCREEN_ENTER: string;
+    readonly ALT_SCREEN_EXIT: string;
+    readonly MOUSE_ENABLE: string;
+    readonly MOUSE_DISABLE: string;
+    readonly CURSOR_HIDE: string;
+    readonly CURSOR_SHOW: string;
+    readonly KEYBOARD_EXT_ENABLE: string;
+    readonly KEYBOARD_EXT_DISABLE: string;
+    readonly PASTE_ENABLE: string;
+    readonly PASTE_DISABLE: string;
+    readonly FOCUS_ENABLE: string;
+    readonly FOCUS_DISABLE: string;
+    readonly CLEAR_VIEWPORT_HOME: string;
+}
+export interface TerminalLifecycleDeps {
+    /** Raw write to the terminal output stream (typically stdout.write bound). */
+    readonly write: (data: string) => void;
+    /**
+     * Whether the alt screen is skipped. Mirrors the front-end's --no-alt-screen
+     * flag: when true, enter never switches to the alt screen and restore clears
+     * the primary viewport (without 3J) instead of leaving the alt screen.
+     */
+    readonly noAltScreen: boolean;
+    /**
+     * Wrap the restore write so it is not suppressed by an output guard. When a
+     * front-end installs a stdout guard, restore must still reach the real
+     * terminal. Defaults to calling the write directly.
+     */
+    readonly guardedWrite?: (write: () => void) => void;
+    /**
+     * Dispose the front-end's terminal output guard, if any. Called AFTER the
+     * restore write so a crash stack reaches the real stderr instead of being
+     * suppressed by the guard. No-op by default.
+     */
+    readonly disposeOutputGuard?: () => void;
+    /**
+     * Set raw mode on the input stream. Called last during restore; wrapped in a
+     * try/catch because stdin may not be a TTY. No-op by default.
+     */
+    readonly setRawMode?: (enabled: boolean) => void;
+    /** Escape sequences; defaults to the shared TERMINAL_ESCAPES. */
+    readonly escapes?: TerminalSequenceSet;
+}
+export interface TerminalLifecycle {
+    /**
+     * Compose and write the enter sequence: alt-screen (unless noAltScreen),
+     * clear + home, hide cursor, then enable mouse / keyboard-extension / paste /
+     * focus reporting. Idempotent-safe to call once at startup.
+     */
+    readonly enterTerminal: () => void;
+    /**
+     * Idempotent, synchronous-only terminal restore. Safe to call from
+     * process 'exit', signal handlers, uncaughtException, and the graceful exit
+     * path. Disposes the output guard AFTER the restore write so a crash stack
+     * still reaches the real stderr.
+     */
+    readonly restoreTerminal: () => void;
+    /**
+     * True once restoreTerminal has run. The compositor must never write another
+     * frame after this: the terminal is back on the user's primary screen, and a
+     * late cursor-positioned frame (async shutdown races, stray timers) would
+     * paint over shell content and strand the prompt mid-screen. Wire the render
+     * scheduler's `isReleased` to this.
+     */
+    readonly isTerminalRestored: () => boolean;
+}
+/**
+ * Build the shared terminal lifecycle around a front-end's injected terminal
+ * I/O. Behavior mirrors the reference front-end exactly: enter switches to the
+ * alt screen (unless disabled) and enables the input modes; restore leaves the
+ * alt screen (or clears the primary viewport without 3J), shows the cursor on
+ * the screen the shell prompt lands on, then hands input back.
+ */
+export declare function createTerminalLifecycle(deps: TerminalLifecycleDeps): TerminalLifecycle;
+//# sourceMappingURL=terminal-lifecycle.d.ts.map

package/dist/terminal-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-lifecycle.d.ts","sourceRoot":"","sources":["../src/terminal-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;IAa3B;;;;OAIG;;CAEK,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,IAAI,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,OAAO,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAmDtF"}

package/dist/terminal-lifecycle.js

@@ -0,0 +1,94 @@
+/**
+ * terminal-lifecycle.ts — shared terminal enter/restore sequencing for GoodVibes
+ * daemon front-ends.
+ *
+ * Both front-ends drive a full-screen terminal UI and must enter and later
+ * restore the terminal identically. When these sequences diverge between them,
+ * exit teardown leaves the wrong screen active or wipes the user's scrollback —
+ * a defect class that recurs whenever the two copies drift. This module is the
+ * single home for the escape sequences and the enter/restore ordering, so both
+ * front-ends share one implementation.
+ *
+ * What lives here is only the terminal-state sequencing and the restored-state
+ * gate. The graceful application shutdown (draining services, persisting
+ * sessions, exit codes) is front-end-specific and stays in each app's own
+ * process-lifecycle wiring; that wiring calls `restoreTerminal()` from this
+ * module for the synchronous terminal hand-back.
+ */
+/**
+ * The canonical control sequences the shell writes to enter and leave terminal
+ * mode (alt screen, mouse, cursor, keyboard-extension, paste, and focus
+ * reporting). Shared verbatim so the two front-ends cannot drift on the bytes.
+ */
+export const TERMINAL_ESCAPES = {
+    ALT_SCREEN_ENTER: '\x1b[?1049h',
+    ALT_SCREEN_EXIT: '\x1b[?1049l',
+    MOUSE_ENABLE: '\x1b[?1000h\x1b[?1002h\x1b[?1006h',
+    MOUSE_DISABLE: '\x1b[?1006l\x1b[?1002l\x1b[?1000l',
+    CURSOR_HIDE: '\x1b[?25l',
+    CURSOR_SHOW: '\x1b[?25h',
+    KEYBOARD_EXT_ENABLE: '\x1b[>4;2m\x1b[?1u',
+    KEYBOARD_EXT_DISABLE: '\x1b[>4;0m\x1b[?1l',
+    PASTE_ENABLE: '\x1b[?2004h',
+    PASTE_DISABLE: '\x1b[?2004l',
+    FOCUS_ENABLE: '\x1b[?1004h',
+    FOCUS_DISABLE: '\x1b[?1004l',
+    /**
+     * Clear viewport + home the cursor, WITHOUT ESC[3J. The 3J form wipes the
+     * user's PRIMARY-screen scrollback on several emulators; the restore path
+     * must never use it. Used by the no-alt-screen restore path.
+     */
+    CLEAR_VIEWPORT_HOME: '\x1b[2J\x1b[H',
+};
+/**
+ * Build the shared terminal lifecycle around a front-end's injected terminal
+ * I/O. Behavior mirrors the reference front-end exactly: enter switches to the
+ * alt screen (unless disabled) and enables the input modes; restore leaves the
+ * alt screen (or clears the primary viewport without 3J), shows the cursor on
+ * the screen the shell prompt lands on, then hands input back.
+ */
+export function createTerminalLifecycle(deps) {
+    const escapes = deps.escapes ?? TERMINAL_ESCAPES;
+    const guardedWrite = deps.guardedWrite ?? ((write) => write());
+    const disposeOutputGuard = deps.disposeOutputGuard ?? (() => { });
+    const setRawMode = deps.setRawMode ?? (() => { });
+    const enterTerminal = () => {
+        guardedWrite(() => deps.write((deps.noAltScreen ? '' : escapes.ALT_SCREEN_ENTER)
+            + escapes.CLEAR_VIEWPORT_HOME
+            + escapes.CURSOR_HIDE
+            + escapes.MOUSE_ENABLE
+            + escapes.KEYBOARD_EXT_ENABLE
+            + escapes.PASTE_ENABLE
+            + escapes.FOCUS_ENABLE));
+    };
+    let terminalRestored = false;
+    const restoreTerminal = () => {
+        if (terminalRestored)
+            return;
+        terminalRestored = true;
+        // Alt-screen path: just leave the alt screen — 1049l restores the primary
+        // screen and cursor exactly as they were at launch. Clearing first is
+        // pointless (the alt screen is discarded) and actively harmful: a clear
+        // with ESC[3J wipes the PRIMARY scrollback on several emulators even when
+        // issued from the alt screen.
+        // No-alt path: the compositor painted over the primary screen, so clear
+        // the viewport and home the cursor — but WITHOUT 3J, the user's scrollback
+        // is theirs. CURSOR_SHOW goes AFTER the screen switch so visibility
+        // applies to the screen the shell prompt lands on.
+        const exitScreen = deps.noAltScreen ? escapes.CLEAR_VIEWPORT_HOME : escapes.ALT_SCREEN_EXIT;
+        guardedWrite(() => deps.write(escapes.PASTE_DISABLE + escapes.KEYBOARD_EXT_DISABLE + escapes.MOUSE_DISABLE + escapes.FOCUS_DISABLE
+            + exitScreen + escapes.CURSOR_SHOW));
+        // Dispose the guard AFTER the restore write so a crash stack reaches the
+        // real stderr instead of being suppressed by the guard.
+        disposeOutputGuard();
+        try {
+            setRawMode(false);
+        }
+        catch { /* input stream may not be a TTY */ }
+    };
+    return {
+        enterTerminal,
+        restoreTerminal,
+        isTerminalRestored: () => terminalRestored,
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pellux/goodvibes-terminal-shell",
+  "version": "1.7.0",
+  "engines": {
+    "bun": "1.3.10",
+    "node": ">=22.0.0"
+  },
+  "description": "Shared terminal-shell plumbing for GoodVibes daemon front-ends: gateway verb-group composition, terminal enter/restore sequencing, render-tick coalescing, and a descriptor/handler conformance gate.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance.d.ts",
+      "import": "./dist/conformance.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mgd34msu/goodvibes-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mgd34msu/goodvibes-sdk/issues"
+  },
+  "homepage": "https://github.com/mgd34msu/goodvibes-sdk",
+  "keywords": [
+    "goodvibes",
+    "sdk",
+    "terminal",
+    "daemon",
+    "gateway"
+  ],
+  "dependencies": {
+    "@pellux/goodvibes-contracts": "1.7.0",
+    "@pellux/goodvibes-sdk": "1.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}