spexcode 0.6.2 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/plugin-harness.js

@@ -0,0 +1,146 @@
+import { mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copyFileIfChanged, writeFileIfChanged } from './file-write.js';
+// @@@ plugin-harness - the PLUGIN BUNDLE emitter: materialize the whole SpexCode system into ONE self-contained
+// Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.adopter-a` /
+// `.claude` → <folder>/plugins/spexcode/). It is the plugin-target counterpart of the native per-harness
+// write [[harness-adapter]] does — chosen INSTEAD of the natives (plugin exclusivity), so [[harness-delivery]]'s
+// materialize prunes every native first, then emits this. The bundle follows the de-facto Claude-plugin schema
+// (a `.claude-plugin/plugin.json` pointing at hooks/skills/commands/agents); the host's discovery order is
+// `.adopter-a-plugin > .claude-plugin > .codex-plugin` and adopter-a/Claude both read a `.claude-plugin` directly, so
+// the ONE `.claude-plugin` bundle reaches AdopterA, Claude, and (future) Codex from a single emit.
+//
+// The contract is NOT delivered by an always-on CLAUDE.md block here (the bundle never touches the repo's own
+// files) — it maps to a SessionStart hook that emits hookSpecificOutput.additionalContext (the harness-neutral
+// injection Claude/adopter-a normalize, the superpowers pattern), so a plugin host gets the contract with no
+// --append-system-prompt. The hooks reuse the SAME dispatch.sh wiring as the natives, located via the host's
+// ${CLAUDE_PLUGIN_ROOT} variable; dispatch.sh's first arg is the harness id `plugin`, so its shell mirror
+// (harness.sh) parses payloads as the claude family (adopter-a/Claude share Claude's tool names + file_path).
+const PKG = fileURLToPath(new URL('..', import.meta.url)); // installed spec-cli root
+const HOOKS_SRC = join(PKG, 'hooks'); // the canonical dispatch.sh + harness.sh source
+const PLUGIN_NAME = 'spexcode';
+// the host substitutes ${CLAUDE_PLUGIN_ROOT} with the bundle's own absolute path before running a hook command
+// (the same variable adopter-a's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
+// where the host scanned the bundle from.
+const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}';
+// the lifecycle events the bundle binds — the Claude/adopter-a superset; a host that fires fewer (Codex) simply
+// never invokes the extras, so binding all is harmless and one emit serves every host.
+const PLUGIN_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'];
+// the bundle dir for a plugin folder: <proj>/<folder>/plugins/spexcode — `<folder>` is the host's plugins-scan
+// root ([[harness-select]] requires it explicit), `plugins/<name>` the conventional bundle location under it.
+export function pluginBundleDir(proj, folder) {
+    return join(proj, folder, 'plugins', PLUGIN_NAME);
+}
+// the de-facto Claude-plugin manifest: name (the bundle identity clean() gates on), version, description, and
+// the component pointers Claude/adopter-a discover (hooks.json + the skills/commands/agents dirs).
+function pluginManifest(version) {
+    return JSON.stringify({
+        name: PLUGIN_NAME,
+        version,
+        description: 'SpexCode — spec-driven dev-flow contract, hooks, skills, commands & agents as one self-contained plugin.',
+        hooks: './hooks/hooks.json',
+        commands: './commands',
+        agents: './agents',
+        skills: './skills',
+    }, null, 2);
+}
+// hooks.json in the Claude/adopter-a-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
+// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited by handlers); SessionStart
+// ALSO runs inject-contract.sh first, so the contract additionalContext lands alongside the normal dispatch.
+function pluginHooksJson(spex) {
+    const dispatch = (e) => `SPEX='${spex}' bash "${PLUGIN_ROOT}/hooks/dispatch.sh" plugin ${e}`;
+    const inject = `bash "${PLUGIN_ROOT}/hooks/inject-contract.sh"`;
+    const hooks = {};
+    for (const e of PLUGIN_EVENTS) {
+        const cmds = e === 'SessionStart'
+            ? [{ type: 'command', command: inject }, { type: 'command', command: dispatch(e) }]
+            : [{ type: 'command', command: dispatch(e) }];
+        hooks[e] = [{ hooks: cmds }];
+    }
+    return JSON.stringify({ hooks }, null, 2);
+}
+// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at materialize time,
+// so the runtime hook is a trivial `cat` — never a fragile shell escaping of arbitrary contract prose.
+function contractContextJson(contract) {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: contract } }, null, 2);
+}
+// the SessionStart contract injector: print the pre-encoded additionalContext payload (the harness-neutral
+// stand-in for --append-system-prompt). A bare cat — all the encoding happened at materialize time.
+const INJECT_SH = `#!/usr/bin/env bash
+# Emit the SpexCode contract as SessionStart additionalContext — the harness-neutral contract injection (the
+# superpowers pattern; Claude/adopter-a normalize hookSpecificOutput.additionalContext) that replaces a plugin
+# host's missing --append-system-prompt. The JSON was written at materialize time, so this is a trivial cat.
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+[ -f "$here/contract-context.json" ] && cat "$here/contract-context.json"
+exit 0
+`;
+// emit (or idempotently re-emit) the whole bundle into <folder>/plugins/spexcode.
+export function emitPlugin(proj, folder, r) {
+    const bundle = pluginBundleDir(proj, folder);
+    const meta = join(bundle, '.claude-plugin');
+    const hooksDir = join(bundle, 'hooks');
+    mkdirSync(meta, { recursive: true });
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileIfChanged(join(meta, 'plugin.json'), pluginManifest(r.version));
+    // hooks: the SHARED dispatcher + its shell mirror (copied verbatim — the exact native wiring), the contract
+    // injector + its pre-encoded payload, and the event→dispatch binding.
+    copyFileIfChanged(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'));
+    copyFileIfChanged(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'));
+    writeFileIfChanged(join(hooksDir, 'inject-contract.sh'), INJECT_SH);
+    writeFileIfChanged(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract));
+    writeFileIfChanged(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex));
+    // skills / agents / commands — the Claude-plugin layout, the SAME materialized contents as the native dirs.
+    reconcileBundleDirectory(join(bundle, 'skills'), new Set(r.skills.map((s) => s.name)));
+    reconcileBundleDirectory(join(bundle, 'agents'), new Set(r.agents.map((a) => `${a.name}.md`)));
+    reconcileBundleDirectory(join(bundle, 'commands'), new Set(r.commands.map((c) => `${c.name}.md`)));
+    for (const s of r.skills)
+        writeBundleFile(join(bundle, 'skills', s.name, 'SKILL.md'), s.content);
+    for (const a of r.agents)
+        writeBundleFile(join(bundle, 'agents', `${a.name}.md`), a.content);
+    for (const c of r.commands)
+        writeBundleFile(join(bundle, 'commands', `${c.name}.md`), c.content);
+}
+function reconcileBundleDirectory(dir, expectedNames) {
+    if (!existsSync(dir))
+        return;
+    for (const entry of readdirSync(dir)) {
+        if (!expectedNames.has(entry))
+            rmSync(join(dir, entry), { recursive: true, force: true });
+    }
+}
+function writeBundleFile(f, content) {
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileIfChanged(f, content);
+}
+// the INVERSE of emitPlugin — prune the bundle when its folder is DESELECTED ([[harness-delivery]] tracks the
+// previously-emitted folders and cleans any the current set dropped, e.g. switching plugin→native or folder A→B).
+// Identity-gated on the bundle's own plugin.json `name`, so it removes ONLY a spexcode bundle, never a folder
+// the user populated with another plugin.
+export function cleanPlugin(proj, folder) {
+    const bundle = pluginBundleDir(proj, folder);
+    const manifest = join(bundle, '.claude-plugin', 'plugin.json');
+    if (!existsSync(manifest))
+        return;
+    try {
+        if (String(JSON.parse(readFileSync(manifest, 'utf8'))?.name) !== PLUGIN_NAME)
+            return;
+    }
+    catch {
+        return;
+    }
+    rmSync(bundle, { recursive: true, force: true });
+}
+// the bundle version stamped into plugin.json — the monorepo root `spexcode` package version (the published
+// artifact's version), falling back to the spec-cli package, then 0.0.0.
+export function pluginVersion() {
+    for (const p of [join(PKG, '..', 'package.json'), join(PKG, 'package.json')]) {
+        try {
+            const v = JSON.parse(readFileSync(p, 'utf8'))?.version;
+            if (v)
+                return String(v);
+        }
+        catch { /* keep trying */ }
+    }
+    return '0.0.0';
+}

package/node_modules/@spexcode/spec-cli/dist/pty-bridge.d.ts

@@ -0,0 +1,10 @@
+export type Viewer = {
+    send: (data: Buffer) => void;
+    commitSize?: (cols: number, rows: number) => void;
+};
+export declare function attachViewer(id: string, viewer: Viewer): void;
+export declare function hideViewer(id: string, viewer: Viewer): void;
+export declare function detachViewer(id: string, viewer: Viewer): void;
+export declare function resizeBridge(id: string, viewer: Viewer, colsValue: number, rowsValue: number): void;
+export declare function forwardInput(id: string, viewer: Viewer, data: string): boolean;
+export declare function superviseBridges(intervalMs?: number): void;

package/node_modules/@spexcode/spec-cli/dist/pty-bridge.js

@@ -0,0 +1,404 @@
+import { execFile, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { alive, withSessionInputLock } from './sessions.js';
+const pexec = promisify(execFile);
+const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode';
+const HELPER = fileURLToPath(new URL('./pty-helper.mjs', import.meta.url));
+const subscribers = new Map();
+const BSU = Buffer.from('\x1b[?2026h');
+const ESU = Buffer.from('\x1b[?2026l');
+const GEOMETRY_STABILIZATION_MS = 400;
+// A hidden but still-alive browser keeps its own client briefly so a quick return is continuous. A dead
+// socket bypasses this window and detaches immediately.
+const LINGER_MS = Number(process.env.SPEXCODE_TERM_LINGER_MS) > 0 ? Number(process.env.SPEXCODE_TERM_LINGER_MS) : 30_000;
+function subscriptionMap(id) {
+    let map = subscribers.get(id);
+    if (!map)
+        subscribers.set(id, map = new Map());
+    return map;
+}
+function currentSubscription(id, viewer) {
+    return subscribers.get(id)?.get(viewer);
+}
+function isCurrent(bridge) {
+    return currentSubscription(bridge.id, bridge.viewer)?.bridge === bridge;
+}
+function deliver(bridge, data) {
+    const subscription = currentSubscription(bridge.id, bridge.viewer);
+    if (!subscription || (!subscription.visible && !subscription.lingering))
+        return;
+    try {
+        bridge.viewer.send(data);
+    }
+    catch { /* socket close or heartbeat expiry owns removal */ }
+}
+function commitSize(bridge) {
+    const subscription = currentSubscription(bridge.id, bridge.viewer);
+    if (!subscription?.visible)
+        return;
+    try {
+        bridge.viewer.commitSize?.(bridge.cols, bridge.rows);
+    }
+    catch { /* socket close owns removal */ }
+}
+async function tmux(args) {
+    try {
+        const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, ...args]);
+        return stdout.trim();
+    }
+    catch {
+        return '';
+    }
+}
+function onHelperOutput(bridge, chunk) {
+    if (!isCurrent(bridge))
+        return;
+    if (bridge.delivery === 'stream') {
+        deliver(bridge, chunk);
+        return;
+    }
+    bridge.refreshBuf = bridge.refreshBuf.length ? Buffer.concat([bridge.refreshBuf, chunk]) : chunk;
+    releaseInitialRefresh(bridge);
+}
+function sendControl(bridge, message) {
+    try {
+        bridge.proc.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    catch { /* exit recovery owns retry */ }
+}
+function onHelperStderr(bridge, chunk) {
+    bridge.stderr += chunk.toString('utf8');
+    let newline;
+    while ((newline = bridge.stderr.indexOf('\n')) >= 0) {
+        const line = bridge.stderr.slice(0, newline);
+        bridge.stderr = bridge.stderr.slice(newline + 1);
+        const ready = line.match(/^READY (\d+)$/);
+        if (ready) {
+            bridge.ptyPid = Number(ready[1]);
+            const subscription = currentSubscription(bridge.id, bridge.viewer);
+            if (subscription)
+                subscription.startupError = undefined;
+            if (bridge.delivery === 'initial') {
+                armDeliveryBoundary(bridge);
+                queueRefresh(bridge);
+            }
+            continue;
+        }
+        const resized = line.match(/^RESIZED (\d+) (\d+)$/);
+        if (resized) {
+            if (bridge.delivery === 'initial'
+                && Number(resized[1]) === bridge.cols
+                && Number(resized[2]) === bridge.rows) {
+                queueRefresh(bridge);
+            }
+        }
+        else if (line) {
+            const failed = line.match(/^ERROR (.+)$/);
+            if (failed)
+                reportStartupError(bridge, failed[1]);
+            console.error(`[terminal helper ${bridge.id}/${bridge.ptyPid ?? 'starting'}] ${line}`);
+        }
+    }
+}
+function reportStartupError(bridge, detail) {
+    const subscription = currentSubscription(bridge.id, bridge.viewer);
+    if (!subscription || subscription.bridge !== bridge)
+        return;
+    const message = boundedStartupError(detail);
+    bridge.startupError = message;
+    if (!message || subscription.startupError === message)
+        return;
+    subscription.startupError = message;
+    deliver(bridge, Buffer.from(`\r\n[SpexCode terminal unavailable] ${message}\r\n`, 'utf8'));
+}
+function boundedStartupError(detail) {
+    return (detail instanceof Error ? detail.message : String(detail))
+        .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500) || 'native PTY failed to start';
+}
+function ensureBridge(id, viewer, subscription, cols, rows) {
+    if (subscription.bridge)
+        return { bridge: subscription.bridge, created: false };
+    let proc;
+    try {
+        proc = spawn(process.execPath, [HELPER, id, String(cols), String(rows)], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: process.env,
+        });
+    }
+    catch (error) {
+        try {
+            proc?.kill();
+        }
+        catch { /* spawn did not complete */ }
+        const detail = boundedStartupError(error);
+        if (subscription.startupError !== detail) {
+            subscription.startupError = detail;
+            try {
+                viewer.send(Buffer.from(`\r\n[SpexCode terminal unavailable] ${detail}\r\n`, 'utf8'));
+            }
+            catch { /* socket closed */ }
+        }
+        return { bridge: null, created: false };
+    }
+    const bridge = {
+        id, viewer, proc, cols, rows, stderr: '', delivery: 'initial',
+        refreshBuf: Buffer.alloc(0), refreshPending: false, refreshRunning: false,
+    };
+    subscription.bridge = bridge;
+    proc.stdout.on('data', (data) => onHelperOutput(bridge, data));
+    proc.stderr.on('data', (data) => onHelperStderr(bridge, data));
+    let reaped = false;
+    const gone = (detail) => {
+        if (reaped)
+            return;
+        reaped = true;
+        const current = currentSubscription(id, viewer);
+        if (current?.bridge !== bridge)
+            return;
+        if (!bridge.ptyPid && !bridge.startupError)
+            reportStartupError(bridge, detail || 'helper exited before native PTY startup');
+        current.bridge = undefined;
+        clearDelivery(bridge);
+        try {
+            bridge.proc.kill();
+        }
+        catch { /* already gone */ }
+        scheduleRestore(id, viewer, current);
+    };
+    proc.on('exit', (code, signal) => gone(`helper exited before native PTY startup (${signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`})`));
+    proc.on('error', (error) => gone(`helper process failed: ${error.message}`));
+    return { bridge, created: true };
+}
+function cancelLinger(subscription) {
+    if (subscription.lingerTimer)
+        clearTimeout(subscription.lingerTimer);
+    subscription.lingerTimer = undefined;
+    subscription.lingering = false;
+}
+function cancelRestore(subscription) {
+    if (subscription.restoreTimer)
+        clearTimeout(subscription.restoreTimer);
+    subscription.restoreTimer = undefined;
+}
+function killBridge(subscription) {
+    cancelLinger(subscription);
+    cancelRestore(subscription);
+    const bridge = subscription.bridge;
+    if (!bridge)
+        return;
+    subscription.bridge = undefined;
+    clearDelivery(bridge);
+    try {
+        bridge.proc.stdin.end();
+    }
+    catch { /* already gone */ }
+    const kill = setTimeout(() => { try {
+        bridge.proc.kill();
+    }
+    catch { /* already gone */ } }, 250);
+    kill.unref();
+}
+function beginDelivery(bridge) {
+    if (bridge.delivery === 'stream')
+        bridge.refreshBuf = Buffer.alloc(0);
+    bridge.delivery = 'initial';
+    bridge.refreshOffset = undefined;
+    armDeliveryBoundary(bridge);
+}
+function armDeliveryBoundary(bridge) {
+    if (bridge.deliveryTimer)
+        clearTimeout(bridge.deliveryTimer);
+    bridge.deliveryTimer = setTimeout(() => finishDelivery(bridge), GEOMETRY_STABILIZATION_MS);
+    bridge.deliveryTimer.unref();
+}
+function clearDelivery(bridge) {
+    bridge.delivery = 'stream';
+    if (bridge.deliveryTimer)
+        clearTimeout(bridge.deliveryTimer);
+    bridge.deliveryTimer = undefined;
+    bridge.refreshBuf = Buffer.alloc(0);
+    bridge.refreshPending = false;
+    bridge.refreshOffset = undefined;
+}
+function completeTransactionEnd(buffer, offset) {
+    const begin = buffer.indexOf(BSU, offset);
+    const end = begin >= 0 ? buffer.indexOf(ESU, begin + BSU.length) : -1;
+    return end >= 0 ? end + ESU.length : undefined;
+}
+function releaseInitialRefresh(bridge) {
+    if (bridge.delivery !== 'initial' || bridge.refreshOffset === undefined)
+        return;
+    const end = completeTransactionEnd(bridge.refreshBuf, bridge.refreshOffset);
+    if (end === undefined)
+        return;
+    const batch = bridge.refreshBuf.subarray(0, end);
+    bridge.refreshBuf = bridge.refreshBuf.subarray(end);
+    bridge.delivery = 'quarantine';
+    commitSize(bridge);
+    if (batch.length)
+        deliver(bridge, batch);
+}
+function finishDelivery(bridge) {
+    if (bridge.delivery === 'stream' || !isCurrent(bridge))
+        return;
+    const failOpen = bridge.delivery === 'initial';
+    const batch = bridge.refreshBuf;
+    clearDelivery(bridge);
+    if (!failOpen && !batch.length)
+        return;
+    // The control commit and following binary frame are one browser render transaction, including fail-open.
+    commitSize(bridge);
+    deliver(bridge, batch);
+}
+async function refreshBridge(bridge) {
+    if (!isCurrent(bridge) || !bridge.ptyPid)
+        return false;
+    const tty = await clientTty(bridge);
+    if (!tty)
+        return false;
+    await tmux(['refresh-client', '-t', tty]);
+    return true;
+}
+function queueRefresh(bridge) {
+    if (bridge.delivery !== 'initial')
+        return;
+    bridge.refreshPending = true;
+    if (bridge.refreshRunning)
+        return;
+    bridge.refreshPending = false;
+    bridge.refreshRunning = true;
+    void refreshBridge(bridge).then((refreshed) => {
+        bridge.refreshRunning = false;
+        if (!isCurrent(bridge) || bridge.delivery !== 'initial')
+            return;
+        if (bridge.refreshPending) {
+            queueRefresh(bridge);
+            return;
+        }
+        if (!refreshed)
+            return;
+        bridge.refreshOffset = bridge.refreshBuf.length;
+        releaseInitialRefresh(bridge);
+    });
+}
+async function clientTty(bridge) {
+    if (bridge.clientTty)
+        return bridge.clientTty;
+    if (!bridge.ptyPid)
+        return undefined;
+    const clients = await tmux(['list-clients', '-t', bridge.id, '-F', '#{client_pid} #{client_tty}']);
+    for (const line of clients.split('\n')) {
+        const space = line.indexOf(' ');
+        if (space > 0 && Number(line.slice(0, space)) === bridge.ptyPid) {
+            return (bridge.clientTty = line.slice(space + 1).trim());
+        }
+    }
+    return undefined;
+}
+function resize(bridge, cols, rows) {
+    if (bridge.cols === cols && bridge.rows === rows)
+        return;
+    beginDelivery(bridge);
+    bridge.cols = cols;
+    bridge.rows = rows;
+    sendControl(bridge, { t: 'resize', cols, rows });
+}
+export function attachViewer(id, viewer) {
+    const map = subscriptionMap(id);
+    const previous = map.get(viewer);
+    if (previous)
+        killBridge(previous);
+    map.set(viewer, { visible: false, lingering: false, cols: 0, rows: 0 });
+}
+export function hideViewer(id, viewer) {
+    const subscription = currentSubscription(id, viewer);
+    if (!subscription)
+        return;
+    subscription.visible = false;
+    if (!subscription.bridge)
+        return;
+    subscription.lingering = true;
+    if (subscription.lingerTimer)
+        return;
+    subscription.lingerTimer = setTimeout(() => {
+        subscription.lingerTimer = undefined;
+        if (!subscription.visible && currentSubscription(id, viewer) === subscription)
+            killBridge(subscription);
+    }, LINGER_MS);
+    subscription.lingerTimer.unref();
+}
+export function detachViewer(id, viewer) {
+    const map = subscribers.get(id);
+    const subscription = map?.get(viewer);
+    if (!map || !subscription)
+        return;
+    // A closed/dead socket is not a hidden live tab: remove its native client now, never after linger.
+    killBridge(subscription);
+    map.delete(viewer);
+    if (map.size === 0)
+        subscribers.delete(id);
+}
+export function resizeBridge(id, viewer, colsValue, rowsValue) {
+    const cols = Math.floor(colsValue), rows = Math.floor(rowsValue);
+    if (!(cols > 0 && rows > 0))
+        return;
+    const subscription = currentSubscription(id, viewer);
+    if (!subscription)
+        return;
+    const seamless = subscription.lingering && !!subscription.bridge
+        && subscription.bridge.cols === cols && subscription.bridge.rows === rows;
+    cancelLinger(subscription);
+    subscription.visible = true;
+    subscription.cols = cols;
+    subscription.rows = rows;
+    const { bridge, created } = ensureBridge(id, viewer, subscription, cols, rows);
+    if (!bridge || created || seamless)
+        return;
+    if (bridge.cols === cols && bridge.rows === rows) {
+        beginDelivery(bridge);
+        queueRefresh(bridge);
+    }
+    else {
+        resize(bridge, cols, rows);
+    }
+}
+const MAX_INPUT_BYTES = 64 * 1024;
+export function forwardInput(id, viewer, data) {
+    const subscription = currentSubscription(id, viewer);
+    if (!subscription?.visible || !subscription.bridge || !data || Buffer.byteLength(data, 'utf8') > MAX_INPUT_BYTES)
+        return false;
+    return withSessionInputLock(id, () => {
+        sendControl(subscription.bridge, { t: 'input', data });
+        return true;
+    }) ?? false;
+}
+async function restoreBridge(id, viewer, subscription) {
+    subscription.restoreTimer = undefined;
+    if (currentSubscription(id, viewer) !== subscription || subscription.bridge || !subscription.visible || !(await alive(id)))
+        return;
+    if (!(subscription.cols > 0 && subscription.rows > 0))
+        return;
+    ensureBridge(id, viewer, subscription, subscription.cols, subscription.rows);
+}
+function scheduleRestore(id, viewer, subscription) {
+    if (currentSubscription(id, viewer) !== subscription || !subscription.visible || subscription.bridge || subscription.restoreTimer)
+        return;
+    subscription.restoreTimer = setTimeout(() => void restoreBridge(id, viewer, subscription), 750);
+    subscription.restoreTimer.unref();
+}
+let supervising = false;
+export function superviseBridges(intervalMs = 4000) {
+    if (supervising)
+        return;
+    supervising = true;
+    const tick = () => {
+        for (const [id, viewers] of subscribers) {
+            for (const [viewer, subscription] of viewers)
+                scheduleRestore(id, viewer, subscription);
+        }
+        const timer = setTimeout(tick, intervalMs);
+        timer.unref();
+    };
+    tick();
+}

package/node_modules/@spexcode/spec-cli/dist/pty-helper.d.mts

@@ -0,0 +1 @@
+export {};

package/node_modules/@spexcode/spec-cli/dist/pty-helper.mjs

@@ -0,0 +1,101 @@
+import * as pty from 'node-pty';
+import { execFileSync } from 'node:child_process';
+import { ensureExecutableIfPresent, nodePtySpawnHelperPath } from './pty-native-helper.mjs';
+const [id, colsArg, rowsArg] = process.argv.slice(2);
+const cols = Number(colsArg);
+const rows = Number(rowsArg);
+const socket = process.env.SPEXCODE_TMUX || 'spexcode';
+if (!id || !(cols > 0 && rows > 0)) {
+    process.stderr.write('ERROR invalid helper arguments\n');
+    process.exit(2);
+}
+// Establish the outer-terminal contract before this process owns a PTY. tmux must preserve hyperlinks and
+// wrap client updates in DEC 2026 for xterm 6; doing the setup before forkpty preserves helper isolation.
+try {
+    // The dashboard renders the pane, not tmux's client chrome. Keeping this as a tmux session option makes
+    // the requested PTY grid the pane grid too; filtering a coloured final row in xterm would corrupt real
+    // pane content. SpexCode owns these sessions, so a later foreground attach sees the same status-free pane.
+    execFileSync('tmux', ['-L', socket, 'set-option', '-t', id, 'status', 'off']);
+    // Control follows the person actually driving: `latest` sizes the window to the most recently
+    // active client, so a small screen takes the grid the moment its user interacts and sees the WHOLE
+    // pane, while an idle larger viewer letterboxes. `largest` optimized the big display's real estate
+    // but left a small concurrent viewer a cropped corner it could never take back.
+    execFileSync('tmux', ['-L', socket, 'set-window-option', '-t', id, 'window-size', 'latest']);
+    execFileSync('tmux', ['-L', socket, 'set-option', '-g', 'mouse', 'on']);
+    execFileSync('tmux', ['-L', socket, 'set-option', '-g', 'history-limit', '50000']);
+    // Wheel routing stays tmux-default: copy-mode history for a plain pane, pass-through to a
+    // mouse-owning TUI. Claude's TUI virtual-scrolls its own transcript on those reports (it lives on
+    // the alternate screen and repaints in place, so tmux history cannot substitute — an in-place
+    // renderer never scrolls lines off the top). Restore the default bindings idempotently in case an
+    // earlier release rebound them server-wide; the unbind may already be clean, so it fails quietly.
+    execFileSync('tmux', ['-L', socket, 'bind-key', '-n', 'WheelUpPane', 'if', '-F', '-t=', '#{||:#{pane_in_mode},#{mouse_any_flag}}', 'send-keys -M', 'copy-mode -et=']);
+    try {
+        execFileSync('tmux', ['-L', socket, 'unbind-key', '-n', 'WheelDownPane']);
+    }
+    catch { /* already unbound */ }
+    const features = execFileSync('tmux', ['-L', socket, 'show-options', '-gsv', 'terminal-features'], { encoding: 'utf8' });
+    const xtermFeatures = new Set(features.split('\n').filter((line) => line.startsWith('xterm*:')).flatMap((line) => line.split(':').slice(1)));
+    const missing = ['sync', 'hyperlinks'].filter((feature) => !xtermFeatures.has(feature));
+    if (missing.length) {
+        execFileSync('tmux', ['-L', socket, 'set-option', '-as', 'terminal-features', `,xterm*:${missing.join(':')}`]);
+    }
+}
+catch { /* attach below fails loudly if the tmux server/session is unavailable */ }
+let terminal;
+try {
+    ensureExecutableIfPresent(nodePtySpawnHelperPath(pty.native));
+    terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
+    });
+}
+catch (error) {
+    const detail = (error instanceof Error ? error.message : String(error))
+        .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500);
+    process.stderr.write(`ERROR ${detail || 'native PTY failed to start'}\n`);
+    process.exit(1);
+}
+terminal.onData((data) => process.stdout.write(Buffer.from(data, 'utf8')));
+terminal.onExit(({ exitCode }) => process.exit(exitCode === 0 ? 0 : 1));
+process.stderr.write(`READY ${terminal.pid}\n`);
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+    input += chunk;
+    let newline;
+    while ((newline = input.indexOf('\n')) >= 0) {
+        const line = input.slice(0, newline);
+        input = input.slice(newline + 1);
+        if (!line)
+            continue;
+        try {
+            const message = JSON.parse(line);
+            if (message?.t === 'resize' && message.cols > 0 && message.rows > 0) {
+                const nextCols = Math.floor(message.cols);
+                const nextRows = Math.floor(message.rows);
+                terminal.resize(nextCols, nextRows);
+                process.stderr.write(`RESIZED ${nextCols} ${nextRows}\n`);
+            }
+            else if (message?.t === 'input' && typeof message.data === 'string' && Buffer.byteLength(message.data, 'utf8') <= 64 * 1024) {
+                terminal.write(message.data);
+            }
+        }
+        catch { /* malformed controls cannot become terminal input */ }
+    }
+});
+let closing = false;
+function close() {
+    if (closing)
+        return;
+    closing = true;
+    try {
+        terminal.kill();
+    }
+    catch { /* already gone */ }
+    setTimeout(() => process.exit(0), 100).unref();
+}
+process.stdin.on('end', close);
+process.on('SIGTERM', close);
+process.on('SIGINT', close);

package/node_modules/@spexcode/spec-cli/dist/pty-native-helper.d.mts

@@ -0,0 +1,2 @@
+export function nodePtySpawnHelperPath(nativeModule: any): string;
+export function ensureExecutableIfPresent(path: any): void;