elanous 0.2.0 → 0.2.5

package/src/preview/terminal.ts

@@ -127,6 +127,18 @@ const defaultSpawn: SpawnFn = (shell, args, o) => {
   return pty.spawn(shell, args, o as any) as IPty;
 };
 
+/** node-pty 네이티브 `resize(fd, cols, rows)` 를 임의의 master fd(우리 dup)에 부른다. 'ok' 또는 실패 사유. */
+export function resizeMasterFd(fd: number, cols: number, rows: number): string {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any
+    const native: any = require('node-pty/lib/utils').loadNativeModule('pty').module;
+    native.resize(fd, cols, rows);
+    return 'ok';
+  } catch (e) {
+    return String(e);
+  }
+}
+
 /** Known POSIX-y user login shells. We only inject `-l -i` defaults for
  *  these; arbitrary `shell` strings (matrix `tailscale`/`ssh` wrappers)
  *  fall through with `[]`. */
@@ -583,7 +595,18 @@ export class PreviewTerminal {
     if (cols === this.term.cols && rows === this.term.rows) return;
     try { this.term.resize(cols, rows); } catch { /* ignore */ }
     if (this.registryHandle) { try { this.registryHandle.resize(cols, rows); } catch { /* ignore */ } }
-    else { try { this.pty?.resize(cols, rows); } catch { /* ignore */ } }
+    else if (this.pty) {
+      // Bun + node-pty quirk(머리말) — node-pty 가 쥔 master fd 는 Bun 에서 EBADF 라 `pty.resize` 가
+      // ioctl 에서 던진다. 종전엔 그 오류를 삼켜서 ***웹 터미널 PTY 가 영영 80×24*** 였다(2026-09-28 실측:
+      // xterm 172칸 ↔ `stty size` 24 80 — 셸이 80칸에서 접어 프롬프트·긴 명령이 깨졌다).
+      // ⇒ 우리가 dup 해 둔 fd 로 같은 네이티브 resize(TIOCSWINSZ)를 부른다. 커널이 SIGWINCH 를 보낸다.
+      try {
+        this.pty.resize(cols, rows);
+      } catch (e) {
+        const viaDup = this.dupFd >= 0 ? resizeMasterFd(this.dupFd, cols, rows) : 'no-dup-fd';
+        debug.log('preview.terminal', 'resize.fallback', { cols, rows, reason: String(e), viaDup });
+      }
+    }
   }
 
   /** Kill the shell, close the master fd, dispose the emulator. Safe

package/src/preview-pane/mount.ts

@@ -1,5 +1,5 @@
 import type { DisplayCoordinator } from '../display/coordinator.js';
-import type { Action, DisplayMouseEvent, KeyEvent } from '../display/types.js';
+import type { DisplayMouseEvent } from '../display/types.js';
 import {
   showLivePaneMultiModal,
   showPaneMultiModal,
@@ -14,12 +14,8 @@ import {
   resolvePaneMultiLiveSnapshotChrome,
 } from '../dashboard/modals/pane-multi-chrome.js';
 import type { ThemeTokens } from '../theme/tokens.js';
-import { mintPaneId } from '../virtual-windows/addressing.js';
-import type { PaneBroadcast, PaneContent, PaneUnsubscribe } from '../virtual-windows/pane-content.js';
 import type { WidgetHost } from '../widgets/host.js';
 import type { PreviewPaneModel } from './model.js';
-import type { PreviewPaneRegistry } from './registry.js';
-import { pad, truncate, visibleWidth } from '../tui.js';
 
 export interface OpenPreviewPaneModalDeps {
   preview: PreviewPaneModel;
@@ -37,16 +33,6 @@ export interface OpenPreviewPaneModalDeps {
   onCancel?(): void;
 }
 
-export interface PreviewPaneContentSpec {
-  kind: 'vw-preview';
-  previewId: string;
-  title?: string;
-}
-
-export interface PreviewPaneMountDeps {
-  previewPaneRegistry: PreviewPaneRegistry;
-}
-
 export function createPreviewPaneModalWidgetId(
   previewWidgetInstanceId: string,
 ): string {
@@ -126,133 +112,6 @@ export function resolvePreviewPaneModalChromeAction(
   return true;
 }
 
-function createObserver(): {
-  emit: () => void;
-  on: (event: 'update' | 'output' | 'exit', cb: () => void) => PaneUnsubscribe;
-} {
-  const subs = new Map<'update' | 'output' | 'exit', Set<() => void>>();
-  return {
-    emit() {
-      for (const cb of subs.get('update') ?? []) {
-        try { cb(); } catch { /* ignore */ }
-      }
-    },
-    on(event, cb) {
-      const set = subs.get(event) ?? new Set<() => void>();
-      set.add(cb);
-      subs.set(event, set);
-      return () => { set.delete(cb); };
-    },
-  };
-}
-
-function clampPreviewOffset(preview: PreviewPaneModel, rows: number): void {
-  const maxOffset = Math.max(0, preview.previewLines.length - Math.max(1, rows));
-  preview.previewOffset = Math.max(0, Math.min(preview.previewOffset, maxOffset));
-}
-
-function formatPreviewLine(line: string, width: number): string {
-  return visibleWidth(line) > width ? truncate(line, width) : pad(line, width);
-}
-
-export function createPreviewPaneContent(
-  spec: PreviewPaneContentSpec,
-  deps: PreviewPaneMountDeps,
-): PaneContent {
-  const preview = deps.previewPaneRegistry.get(spec.previewId);
-  if (!preview) {
-    throw new Error(`createPreviewPaneContent: unknown preview id "${spec.previewId}"`);
-  }
-  const obs = createObserver();
-  let lastRows = 8;
-
-  return {
-    id: mintPaneId(),
-    kind: spec.kind,
-    title: spec.title ?? 'preview',
-    focusPolicy: 'interactive',
-    start() {},
-    stop() {},
-    render(ctx) {
-      lastRows = Math.max(1, ctx.rows);
-      clampPreviewOffset(preview, ctx.rows);
-      const lines: string[] = [];
-      for (let i = 0; i < Math.max(1, ctx.rows); i++) {
-        const line = preview.previewLines[preview.previewOffset + i] ?? '';
-        lines.push(formatPreviewLine(line, ctx.cols));
-      }
-      return lines.join('\n');
-    },
-    onKey(ev: KeyEvent): Action {
-      const step = Math.max(1, lastRows);
-      if (ev.name === 'up' || ev.name === 'k') {
-        preview.previewOffset = Math.max(0, preview.previewOffset - 1);
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      if (ev.name === 'down' || ev.name === 'j') {
-        preview.previewOffset += 1;
-        clampPreviewOffset(preview, step);
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      if (ev.name === 'pageup') {
-        preview.previewOffset = Math.max(0, preview.previewOffset - step);
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      if (ev.name === 'pagedown') {
-        preview.previewOffset += step;
-        clampPreviewOffset(preview, step);
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      if (ev.name === 'home' || ev.name === 'g') {
-        preview.previewOffset = 0;
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      if (ev.name === 'end' || (ev.name === 'G' && ev.shift)) {
-        preview.previewOffset = Math.max(0, preview.previewLines.length - step);
-        clampPreviewOffset(preview, step);
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      return { type: 'none' };
-    },
-    onMouse(ev: DisplayMouseEvent): Action {
-      if (ev.type === 'scroll-up') {
-        preview.previewOffset = Math.max(0, preview.previewOffset - 3);
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      if (ev.type === 'scroll-down') {
-        preview.previewOffset += 3;
-        clampPreviewOffset(preview, lastRows);
-        obs.emit();
-        return { type: 'refresh' };
-      }
-      return { type: 'none' };
-    },
-    write(bytes: string) {
-      preview.previewLines = bytes.split('\n');
-      preview.previewOffset = 0;
-      obs.emit();
-    },
-    acceptBroadcast(input: PaneBroadcast) {
-      preview.previewLines = input.text.split('\n');
-      preview.previewOffset = 0;
-      obs.emit();
-    },
-    capture() {
-      return preview.previewLines.join('\n');
-    },
-    get isAlive() { return true; },
-    on: obs.on,
-    dispose() {},
-  };
-}
-
 export function openPreviewPaneModal(
   deps: OpenPreviewPaneModalDeps,
 ): { dispose(): void; id: string; bounds: { row: number; col: number; width: number; height: number } } {

package/src/prompt/references.ts

@@ -1,39 +1,12 @@
-// Prompt reference expander — T2-P1.
-//
-// One entry point for every `@<kind>:<id>` reference in chat input.
-// Each registered expander handles a specific token family; the
-// overall pipeline composes them in order so new references can be
-// added without touching the call site in dashboard.ts.
-//
-// Supported kinds (T2-P1 landing):
-//
-//   @term:<id>            — TerminalSessionRegistry session snapshot
-//   @term:<id>#<N>        — last N bytes
-//   @term:<id>#all        — full render
-//
-// Planned (T2-P2):
-//
-//   @pane:<id>            — VirtualWindow pane capture
-//   @win:<N>/pane:<id>    — same but qualified
-//
-// Keeping the expander pipeline here (outside dashboard.ts) so the
-// wiring is testable in isolation and the chat submit path stays
-// three lines of plumbing.
+// Chat prompt reference expander. Only terminal session tokens are expanded;
+// other tokens pass through unchanged for the model to see.
 
 import { expandTerminalReferences } from './term-reference.js';
-import { expandVirtualWindowReferences } from './vw-reference.js';
 import type { TerminalSessionRegistry } from '../terminal/session-registry.js';
-import type { AddressBook } from '../virtual-windows/addressing.js';
-import type { WindowRegistry } from '../virtual-windows/window-registry.js';
 
 export interface PromptReferenceDeps {
   /** TerminalSessionRegistry — powers @term:<id>. Omitted = skip. */
   terminalRegistry?: TerminalSessionRegistry;
-  /** AddressBook — powers @pane:<id> + @win:<N>. Omitted = skip. */
-  addressBook?: AddressBook;
-  /** WindowRegistry — required for pane enumeration (@win:<N> /
-   *  @win:<N>#all) and for resolving the live PaneContent. */
-  windowRegistry?: WindowRegistry;
 }
 
 /** Expand every @<kind>:<id> token in `input` into its structured
@@ -44,28 +17,8 @@ export function expandPromptReferences(
   deps: PromptReferenceDeps,
 ): string {
   if (!input.includes('@')) return input;
-  let out = input;
   if (deps.terminalRegistry) {
-    out = expandTerminalReferences(out, deps.terminalRegistry);
+    return expandTerminalReferences(input, deps.terminalRegistry);
   }
-  if (deps.addressBook && deps.windowRegistry) {
-    const reg = deps.windowRegistry;
-    out = expandVirtualWindowReferences(out, {
-      addressBook: deps.addressBook,
-      paneLookup: (paneId) => {
-        const pane = deps.addressBook!.resolvePane(paneId);
-        if (!pane) return null;
-        const window = reg.get(pane.windowId);
-        const content = window?.getPane(paneId) ?? null;
-        if (!content) return null;
-        return { capture: () => content.capture(), kind: content.kind };
-      },
-      listPanes: (winId) => {
-        const window = reg.get(winId);
-        if (!window) return [];
-        return window.listPanes().map((p) => ({ id: p.id, kind: p.content.kind }));
-      },
-    });
-  }
-  return out;
+  return input;
 }

package/src/prompt-library/universal-preamble.ts

@@ -59,6 +59,10 @@ export const PROJECT_ANCHOR_NON_CANDIDATE_FILENAMES = ['CLAUDE.md'] as const;
 export const PROJECT_TREE_MAX_CHARS = 8 * 1024;
 export const PROJECT_TREE_DIR_ENTRY_LIMIT = 20;
 
+const NO_TOOLS_VERIFICATION_GUIDANCE = `## Chat without tools — verify rather than guess
+This conversation has tools disabled. Do not guess repository or real-time facts that require verification, such as file counts, file contents, commits, or the current time. Say you cannot check them here. The project tree above is for navigation, not evidence for counts.
+To check these facts, enable tools with \`elanous agent …\` or \`elanous chat --tools …\`.`;
+
 // P4 (2026-05-03) — Family-agnostic coding-agent lifecycle. Maps the
 // three user-facing pipelines to an explicit tool-batch sequence so every
 // model (not just codex) follows the same shape. Pattern source:
@@ -673,8 +677,7 @@ export function loadProjectAnchor(cwd: string): ProjectAnchorResult {
   return result;
 }
 
-/** Build the surface-agnostic preamble. Currently MVP — emits zero or
- *  one system message (project anchor). Surfaces spread the result
+/** Build the surface-agnostic preamble. Surfaces spread the result
  *  into their own preamble; e.g.
  *
  *  ```ts
@@ -729,6 +732,9 @@ export function buildUniversalPreamble(ctx: UniversalPreambleContext): LLMMessag
       content: `## Project Layout (top-level + 1 depth)\n\n\`\`\`\n${tree.content}\n\`\`\`\n\nUse this layout to pick directories directly instead of issuing broad project-root Grep/Glob calls. When AGENTS.md / CLAUDE.md describe a track or subsystem, this layout shows where its files actually live.`,
     });
   }
+  if (!ctx.enabledTools?.length) {
+    out.push({ role: 'system', content: NO_TOOLS_VERIFICATION_GUIDANCE });
+  }
   // P4 (2026-05-03) — Family-agnostic coding-agent lifecycle. Append
   // before family addendum so codex (which has its own discipline
   // overlay) sees both: lifecycle (what shape) + addendum (how to behave

package/src/pty-shell/pty-control-ipc.ts

@@ -9,8 +9,10 @@ import { resetExternalWriteProvenanceForTesting } from './pty-write-provenance.j
 import { parsePtyWriteActor, resolveRemoteControlActor, type PtyWriteActor } from './pty-write-arbiter.js';
 import { isPtyAccessMode } from './pty-ref.js';
 import { debug } from '../debug/log.js';
+import { encodeSgrMouse, mouseModeOffReason, type PtyMouseInput } from './pty-mouse.js';
+import { startPtyRecording, stopPtyRecording } from './pty-recording.js';
 
-const OWNER_PTY_CONTROL_ACTIONS = ['takeover', 'release', 'input-text', 'input-key', 'resize', 'snapshot', 'rename', 'terminate', 'capabilities'] as const;
+const OWNER_PTY_CONTROL_ACTIONS = ['takeover', 'release', 'input-text', 'input-key', 'input-mouse', 'resize', 'snapshot', 'rename', 'terminate', 'capabilities', 'record-start', 'record-stop'] as const;
 export type PtyControlAction = typeof OWNER_PTY_CONTROL_ACTIONS[number];
 type PtyControlStatus = 'success' | 'unknown-pty' | 'denied' | 'failed' | 'write-failed' | 'owner-unreachable';
 
@@ -33,9 +35,11 @@ function isStringList(value: unknown): value is readonly string[] {
 
 export type PtyControlPayload =
   | { readonly chars: string }
+  | PtyMouseInput
   | { readonly cols: number; readonly rows: number }
   | { readonly ansi: boolean }
-  | { readonly nickname: string };
+  | { readonly nickname: string }
+  | { readonly cols: number; readonly rows: number; readonly title?: string };
 
 export interface PtyControlRequestOptions {
   /** 요청자가 주장하는 쓰기 주체. `'agent'` 는 run-identity 일치를 요구한다(`resolveRemoteControlActor`). */
@@ -57,6 +61,10 @@ export interface PtyControlResult {
   readonly diagnostic?: 'owner-unavailable' | 'render-unavailable';
   readonly frameUnavailable?: boolean;
   readonly actions?: readonly string[];
+  readonly path?: string;
+  readonly recordingId?: string;
+  readonly bytes?: number;
+  readonly durationMs?: number;
 }
 
 interface ControlRow {
@@ -294,7 +302,41 @@ async function processPtyControlRequestsOnce(getHandle: (id: string) => PtyContr
       else if (!isOwnerPtyControlAction(row.action)) result = { status: 'denied', reason: 'unsupported-action' };
       else if (row.action === 'capabilities') result = { status: 'success', actions: OWNER_PTY_CONTROL_ACTIONS };
       else if (row.action === 'terminate') result = await terminatePty(handle);
-      else if (row.action === 'snapshot') {
+      else if (row.action === 'record-start' || row.action === 'record-stop') {
+        if (requested === null) result = { status: 'denied', reason: 'invalid-actor' };
+        else if (row.action === 'record-stop') {
+          const stopped = stopPtyRecording(row.pty_id);
+          result = stopped.ok
+            ? { status: 'success', path: stopped.path, bytes: stopped.bytes, durationMs: stopped.durationMs }
+            : { status: 'denied', reason: stopped.reason };
+        } else {
+          const payload = parsePayload(row);
+          if (payload !== null && (typeof payload !== 'object' || Array.isArray(payload)
+            || !('cols' in payload) || !('rows' in payload)
+            || !Number.isSafeInteger(payload.cols) || payload.cols < 1
+            || !Number.isSafeInteger(payload.rows) || payload.rows < 1
+            || ('title' in payload && payload.title !== undefined && typeof payload.title !== 'string'))) {
+            result = { status: 'denied', reason: 'invalid-record-payload' };
+          } else {
+            // The cast header must carry the PTY's real size, and only the owner knows it:
+            // a caller's cols/rows are never trusted, and an unknown size is refused, never guessed.
+            const cols = handle.cols;
+            const rows = handle.rows;
+            if (cols === undefined || rows === undefined) {
+              result = { status: 'denied', reason: 'dimensions-unknown' };
+            } else {
+              const started = startPtyRecording(row.pty_id, {
+                cols,
+                rows,
+                ...(payload && 'title' in payload && typeof payload.title === 'string' ? { title: payload.title } : {}),
+              });
+              result = started.ok
+                ? { status: 'success', recordingId: started.recordingId, path: started.path }
+                : { status: 'denied', reason: started.reason };
+            }
+          }
+        }
+      } else if (row.action === 'snapshot') {
         if (!handle.renderScreen) {
           result = { status: 'failed', reason: 'screen-unavailable' };
         }
@@ -355,6 +397,18 @@ async function processPtyControlRequestsOnce(getHandle: (id: string) => PtyContr
             : outcome === 'denied'
               ? { status: 'denied', reason: 'write-arbiter' }
               : { status: 'failed', reason: 'resize-error' };
+        } else if (row.action === 'input-mouse' && 'kind' in payload && 'x' in payload && 'y' in payload) {
+          let chars: string | undefined;
+          try { chars = encodeSgrMouse(payload); }
+          catch { result = { status: 'denied', reason: 'invalid-mouse-payload' }; }
+          if (chars !== undefined) {
+            const off = mouseModeOffReason(handle);
+            if (off) result = { status: 'denied', reason: off };
+            else {
+              const outcome = writePtyWithOutcome(handle, chars, authorized.actor);
+              result = outcome === 'success' ? { status: 'success' } : outcome === 'denied' ? { status: 'denied', reason: 'write-arbiter' } : { status: 'write-failed', reason: 'adapter-write' };
+            }
+          }
         } else if ((row.action === 'input-text' || row.action === 'input-key') && 'chars' in payload) {
           // ⛔⭐ 여기서 세지 «않는다» — 계기는 `registry.write`(진짜 초크포인트)에 있다.
           //   여기서도 세면 크로스-프로세스 쓰기가 **두 번** 세어진다(`[S]` 리뷰 후 이동).

package/src/pty-shell/pty-mouse.ts

@@ -0,0 +1,75 @@
+/** Bound named-key expansion before allocating its repeated PTY escape sequence. */
+export const MAX_PTY_KEY_REPEAT = 100;
+
+export interface PtyMouseInput {
+  readonly x: number;
+  readonly y: number;
+  readonly button?: 'left' | 'middle' | 'right';
+  readonly kind: 'click' | 'scroll-up' | 'scroll-down';
+}
+
+export function encodeSgrMouse(input: PtyMouseInput): string {
+  const { x, y, kind, button = 'left' } = input;
+  if (!Number.isSafeInteger(x) || x < 1 || !Number.isSafeInteger(y) || y < 1) {
+    throw new Error('mouse coordinates must be positive 1-based integers');
+  }
+  if (!['left', 'middle', 'right'].includes(button) || !['click', 'scroll-up', 'scroll-down'].includes(kind)) {
+    throw new Error('invalid mouse button or kind');
+  }
+  const code = kind === 'scroll-up' ? 64 : kind === 'scroll-down' ? 65 : ['left', 'middle', 'right'].indexOf(button);
+  const press = `\x1b[<${code};${x};${y}M`;
+  return kind === 'click' ? `${press}\x1b[<${code};${x};${y}m` : press;
+}
+
+/** DEC private modes are independent; SGR coordinates require ?1006 as well as an event mode. */
+export function detectMouseMode(outputChunk: string): { readonly enabled: boolean; feed: (chunk: string) => boolean } {
+  const modes = new Set<number>();
+  let pending = '';
+  const isEnabled = (): boolean => modes.has(1006) && (modes.has(1000) || modes.has(1002) || modes.has(1003));
+
+  const feed = (chunk: string): boolean => {
+    const combined = pending + chunk;
+    // eslint-disable-next-line no-control-regex
+    const sequence = /\x1b\[\?([0-9;]+)([hl])/g;
+    for (const match of combined.matchAll(sequence)) {
+      for (const token of match[1]!.split(';')) {
+        const mode = Number(token);
+        if (mode === 1000 || mode === 1002 || mode === 1003 || mode === 1006) {
+          if (match[2] === 'h') modes.add(mode);
+          else modes.delete(mode);
+        }
+      }
+    }
+    // Retain only an incomplete CSI suffix; never replay completed transitions.
+    // eslint-disable-next-line no-control-regex
+    const start = combined.lastIndexOf('\x1b');
+    const suffix = start >= 0 ? combined.slice(start) : '';
+    pending = /^\x1b(?:\[(?:\?(?:[0-9;]*)?)?)?$/.test(suffix) && suffix.length < 64 ? suffix : '';
+    return isEnabled();
+  };
+  feed(outputChunk);
+  return {
+    get enabled() { return isEnabled(); },
+    feed,
+  };
+}
+
+const trackers = new Map<string, ReturnType<typeof detectMouseMode>>();
+export const MOUSE_MODE_OFF_REASON = 'PTY mouse mode is off or SGR ?1006 is not enabled';
+
+/** Called by the existing registry output/exit path, before screen rendering strips DEC mode sequences. */
+export function trackPtyMouseOutput(id: string, chunk: string): void {
+  const tracker = trackers.get(id) ?? detectMouseMode('');
+  tracker.feed(chunk);
+  trackers.set(id, tracker);
+}
+
+export function forgetPtyMouseMode(id: string): void { trackers.delete(id); }
+
+export function mouseModeForPty(handle: { readonly id: string }): boolean {
+  return trackers.get(handle.id)?.enabled ?? false;
+}
+
+export function mouseModeOffReason(handle: { readonly id: string }): string | undefined {
+  return mouseModeForPty(handle) ? undefined : MOUSE_MODE_OFF_REASON;
+}

package/src/pty-shell/pty-recording.ts

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { createRecorder } from '../capture/recorder.js';
+import { getRecordingStore } from '../capture/recording-store.js';
+import type { RecorderHandle } from '../capture/types.js';
+import { debug } from '../debug/log.js';
+
+interface ActiveRecording {
+  readonly recordingId: string;
+  readonly path: string;
+  readonly handle: RecorderHandle;
+  readonly startedAt: number;
+}
+
+const active = new Map<string, ActiveRecording>();
+
+export type StartPtyRecordingResult =
+  | { readonly ok: true; readonly recordingId: string; readonly path: string }
+  | { readonly ok: false; readonly reason: 'already-recording' };
+export type StopPtyRecordingResult =
+  | { readonly ok: true; readonly path: string; readonly bytes: number; readonly durationMs: number }
+  | { readonly ok: false; readonly reason: 'not-recording' };
+
+/** A process-local output tap; the capture store is shared with other recording hosts. */
+export function startPtyRecording(ptyId: string, opts: { cols: number; rows: number; title?: string }): StartPtyRecordingResult {
+  if (active.has(ptyId)) return { ok: false, reason: 'already-recording' };
+  if (!Number.isSafeInteger(opts.cols) || opts.cols < 1 || !Number.isSafeInteger(opts.rows) || opts.rows < 1) {
+    throw new Error('invalid PTY recording dimensions');
+  }
+  const startedAt = Date.now();
+  const directory = join(elanousStateRoot(), 'recordings');
+  const safeId = ptyId.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 64);
+  let timestamp = startedAt;
+  let path = join(directory, `pty-${safeId}-${timestamp}.cast`);
+  while (existsSync(path) || [...active.values()].some((entry) => entry.path === path)) {
+    path = join(directory, `pty-${safeId}-${++timestamp}.cast`);
+  }
+  const handle = createRecorder({ dims: { cols: opts.cols, rows: opts.rows }, ...(opts.title === undefined ? {} : { title: opts.title }) });
+  handle.start();
+  const entry = getRecordingStore().start({ handle, encoder: 'asciicast', source: { surfaceLabel: `pty:${ptyId}` } });
+  active.set(ptyId, { recordingId: entry.id, path, handle, startedAt });
+  debug.log('pty.record', 'start', { ptyId, path, bytes: 0 });
+  return { ok: true, recordingId: entry.id, path };
+}
+
+export function tapPtyOutput(ptyId: string, chunk: string): void {
+  active.get(ptyId)?.handle.write(chunk, 'o');
+}
+
+function finish(ptyId: string, event: 'stop' | 'auto-stop' | 'auto-stop-recovered', path?: string): StopPtyRecordingResult {
+  const entry = active.get(ptyId);
+  if (!entry) return { ok: false, reason: 'not-recording' };
+  const target = path ?? entry.path;
+  const body = entry.handle.serialize();
+  mkdirSync(dirname(target), { recursive: true });
+  // Atomic save: write a temp file, then rename. A failed write leaves no partial cast at the
+  // target path and keeps the recording active, so the caller can retry the stop.
+  const temp = `${target}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temp, body, { encoding: 'utf8', flag: 'w' });
+    renameSync(temp, target);
+  } catch (error) {
+    try { rmSync(temp, { force: true }); } catch { /* best effort */ }
+    debug.log('pty.record', 'save-error', { ptyId, path: target, error: String(error) });
+    throw error;
+  }
+  // The cast is on disk from here: the recording is finished whatever the bookkeeping below does,
+  // otherwise a retry would find nothing to stop and the store would keep an active row forever.
+  active.delete(ptyId);
+  const bytes = Buffer.byteLength(body, 'utf8');
+  const durationMs = Date.now() - entry.startedAt;
+  closeBookkeeping(ptyId, entry, target);
+  debug.log('pty.record', event, { ptyId, path: target, bytes });
+  return { ok: true, path: target, bytes, durationMs };
+}
+
+function closeBookkeeping(ptyId: string, entry: ActiveRecording, artifactPath: string | undefined): void {
+  try { entry.handle.stop(); }
+  catch (error) { debug.log('pty.record', 'handle-stop-error', { ptyId, error: String(error) }); }
+  try { getRecordingStore().markStopped(entry.recordingId, artifactPath ? { artifactPath } : {}); }
+  catch (error) { debug.log('pty.record', 'mark-stopped-error', { ptyId, error: String(error) }); }
+}
+
+export function stopPtyRecording(ptyId: string): StopPtyRecordingResult {
+  return finish(ptyId, 'stop');
+}
+
+/** Called on PTY exit (and on unregister when exit was never delivered). Nothing can call
+ *  `--stop` on a PTY that is gone, so a failed save is retried once at a recovery path through the
+ *  same atomic save and close-out; if that fails too the recording is closed with the loss on record
+ *  — it never stays active with no way out. */
+export function autoStopPtyRecording(ptyId: string): StopPtyRecordingResult {
+  try {
+    return finish(ptyId, 'auto-stop');
+  } catch (error) {
+    const entry = active.get(ptyId);
+    if (!entry) throw error;
+    try {
+      return finish(ptyId, 'auto-stop-recovered', `${entry.path}.recovered`);
+    } catch (retryError) {
+      active.delete(ptyId);
+      closeBookkeeping(ptyId, entry, undefined);
+      debug.log('pty.record', 'auto-stop-save-failed', { ptyId, path: entry.path, error: String(error), retryError: String(retryError) });
+      throw retryError;
+    }
+  }
+}