@with-logic/elwood 0.1.3 → 0.2.0

package/dist/terminal/headless.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headless.d.ts","sourceRoot":"","sources":["../../src/terminal/headless.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,aAAa,GAAG,OAAO,iBAAiB,EAAE,QAAQ,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,QAAQ,IAAI,gBAAgB,CAAC;IAC7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,KAAK,IAAI,GAC5C,cAAc,CAEhB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,GAC3D,cAAc,CAchB"}
+{"version":3,"file":"headless.d.ts","sourceRoot":"","sources":["../../src/terminal/headless.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMlD,MAAM,MAAM,aAAa,GAAG,OAAO,iBAAiB,EAAE,QAAQ,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,QAAQ,IAAI,gBAAgB,CAAC;IAC7B;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,KAAK,IAAI,GAC5C,cAAc,CAEhB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,EAC5D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAClC,cAAc,CAqBhB"}

package/dist/terminal/headless.js

@@ -1,30 +1,39 @@
-/**
- * Headless xterm.js terminal model for PTY rendering and input control.
- * Implements PRD §4.1, §5.3, and §9.
- */
+/** Headless PTY rendering and input control (PRD §4.1, §5.3, §9). */
 import xtermHeadless from "@xterm/headless";
+import { RenderCursor } from "./cursor.js";
+import { PtyOutput } from "./pty-output.js";
+import { RenderQueue } from "./render-queue.js";
+import { terminalSnapshot } from "./snapshot.js";
 export function createHeadlessTerminal(size, onInput) {
     return new HeadlessTerminal(size, onInput);
 }
-export function attachPtyTerminal(size, pty, onRendered) {
+export function attachPtyTerminal(size, pty, onRendered, onReceived) {
     const terminal = new HeadlessTerminal(size, (input) => pty.write(input));
-    const unsubscribe = pty.onData((data) => {
-        // Own the whole continuation: a throwing public `terminal:data` listener reached
-        // via onRendered, or a render failure, must not surface as an unhandled rejection
-        // on normal PTY output. There is no caller to reject to on the render path, so the
-        // failure is swallowed here (the write itself already can't poison the queue).
-        void terminal
-            .writeOutput(data)
-            .then(() => onRendered(data, terminal))
-            .catch(() => undefined);
+    const output = new PtyOutput((data) => terminal.writeOutput(data, () => onRendered(data, terminal), true), pty.flowControl);
+    terminal.attachOutput(output);
+    // Resume at child exit so unread tail output is not stranded behind backpressure.
+    const off = [
+        pty.onData((data) => {
+            if (data.length > 0)
+                terminal.cursor.received();
+            // Startup health checks need raw bytes before asynchronous batching/rendering.
+            onReceived?.(data);
+            output.push(data);
+        }),
+        pty.onExit(() => output.releaseFlowControl()),
+    ];
+    terminal.onDispose(() => {
+        for (const unsubscribe of off)
+            unsubscribe();
     });
-    terminal.onDispose(unsubscribe);
     return terminal;
 }
 class HeadlessTerminal {
     xterm;
+    cursor;
     currentSize;
-    writeQueue = Promise.resolve();
+    renders;
+    ptyOutput;
     onInput;
     inputWaiters = [];
     disposers = [];
@@ -38,6 +47,9 @@ class HeadlessTerminal {
             cols: size.cols,
             rows: size.rows,
         });
+        this.cursor = new RenderCursor(this.xterm, () => this.ptyOutput?.hasStagedOutput === true);
+        this.disposers.push(() => this.cursor.dispose());
+        this.renders = new RenderQueue((data, done) => this.xterm.write(data, done), () => this.ptyOutput?.flush());
         this.xterm.onData((input) => this.forwardInput(input));
         this.xterm.onTitleChange((title) => {
             this.currentTitle = title;
@@ -49,16 +61,20 @@ class HeadlessTerminal {
     get title() {
         return this.currentTitle;
     }
-    writeOutput(data) {
+    get renderFailed() {
+        return this.renders.renderFailed;
+    }
+    // PTY batches were counted on arrival; direct writes introduce their own output.
+    writeOutput(data, onRendered, alreadyReceived = false) {
         if (this.disposed)
             return Promise.resolve();
-        const write = this.writeQueue.then(() => new Promise((resolve) => this.xterm.write(data, resolve)));
-        // Chain the NEXT write off a never-rejecting tail so a single failed write
-        // (e.g. a synchronous xterm.write throw) cannot poison every subsequent write
-        // by leaving `writeQueue` permanently rejected. The caller still sees the real
-        // result via the returned `write` promise.
-        this.writeQueue = write.catch(() => undefined);
-        return write;
+        this.ptyOutput?.flush(); // keep a direct write ordered after PTY output already received
+        const revision = alreadyReceived ? this.cursor.queued() : this.cursor.received();
+        const arrival = this.cursor.arrival;
+        return this.renders.enqueue(data, () => {
+            this.cursor.rendered(revision, arrival);
+            onRendered?.();
+        });
     }
     sendInput(input) {
         if (this.disposed)
@@ -75,19 +91,10 @@ class HeadlessTerminal {
         this.xterm.resize(size.cols, size.rows);
     }
     snapshot() {
-        const buffer = this.xterm.buffer.active;
-        const lines = Array.from({ length: this.currentSize.rows }, (_, index) => buffer.getLine(buffer.viewportY + index)?.translateToString(true) ?? "");
-        return {
-            cols: this.currentSize.cols,
-            rows: this.currentSize.rows,
-            cursorX: buffer.cursorX,
-            cursorY: buffer.cursorY,
-            lines,
-            text: lines.join("\n"),
-        };
+        return terminalSnapshot(this.xterm, this.currentSize);
     }
     settled() {
-        return this.writeQueue;
+        return this.renders.settled();
     }
     dispose() {
         if (this.disposed)
@@ -95,11 +102,16 @@ class HeadlessTerminal {
         this.disposed = true;
         for (const dispose of this.disposers.splice(0))
             dispose();
+        this.ptyOutput?.dispose();
+        this.renders.dispose();
         this.xterm.dispose();
     }
     onDispose(dispose) {
         this.disposers.push(dispose);
     }
+    attachOutput(output) {
+        this.ptyOutput = output;
+    }
     forwardInput(input) {
         const waiter = this.inputWaiters.shift();
         if (!waiter) {

package/dist/terminal/headless.js.map

@@ -1 +1 @@
-{"version":3,"file":"headless.js","sourceRoot":"","sources":["../../src/terminal/headless.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"headless.js","sourceRoot":"","sources":["../../src/terminal/headless.ts"],"names":[],"mappings":"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"}

package/dist/terminal/pty-output.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Coalesces adjacent PTY chunks and, when the adapter supplies `flowControl`,
+ * bounds the pending rendering backlog with backpressure. Adapters without flow
+ * control still batch, but their backlog is unbounded.
+ * Implements PRD §4.1 and C-PERF-06.
+ */
+import type { PtyProcess } from "../pty/types.ts";
+export declare const renderHighWaterBytes: number;
+export declare const renderLowWaterBytes: number;
+export declare const renderBatchBytes: number;
+export declare const renderBatchDelayMs = 4;
+export declare class PtyOutput {
+    private readonly write;
+    private readonly flow;
+    private paused;
+    private chunks;
+    private bufferedBytes;
+    private pendingBytes;
+    private scheduled;
+    private disposed;
+    /** Cleared at child exit: a pause after that could never be lifted by a producer. */
+    private throttled;
+    constructor(write: (data: string) => Promise<void>, flow: PtyProcess["flowControl"]);
+    /** Received bytes that have not yet been handed to the ordered render queue. */
+    get hasStagedOutput(): boolean;
+    push(data: string): void;
+    flush(): void;
+    /**
+     * Stop throttling reads and stay unpaused. Used at child exit, where the producer
+     * is gone: further accounting could only re-pause a PTY nobody will resume.
+     */
+    releaseFlowControl(): void;
+    dispose(): void;
+    private release;
+    private resume;
+}
+//# sourceMappingURL=pty-output.d.ts.map

package/dist/terminal/pty-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-output.d.ts","sourceRoot":"","sources":["../../src/terminal/pty-output.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,oBAAoB,QAAc,CAAC;AAChD,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAC5D,eAAO,MAAM,gBAAgB,QAAY,CAAC;AAC1C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAKpC,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,QAAQ,CAAS;IACzB,qFAAqF;IACrF,OAAO,CAAC,SAAS,CAAQ;gBAEb,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC;IAKnF,gFAAgF;IAChF,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IA6BxB,KAAK,IAAI,IAAI;IAgBb;;;OAGG;IACH,kBAAkB,IAAI,IAAI;IAK1B,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;CAMf"}

package/dist/terminal/pty-output.js

@@ -0,0 +1,109 @@
+/**
+ * Coalesces adjacent PTY chunks and, when the adapter supplies `flowControl`,
+ * bounds the pending rendering backlog with backpressure. Adapters without flow
+ * control still batch, but their backlog is unbounded.
+ * Implements PRD §4.1 and C-PERF-06.
+ */
+import { Buffer } from "node:buffer";
+export const renderHighWaterBytes = 1024 * 1024;
+export const renderLowWaterBytes = renderHighWaterBytes / 2;
+export const renderBatchBytes = 64 * 1024;
+export const renderBatchDelayMs = 4;
+// A UTF-16 code unit occupies at most three UTF-8 bytes. Slicing at 16K units
+// leaves room for whole surrogate pairs while keeping every piece below 64 KiB.
+const pieceCodeUnits = renderBatchBytes / 4;
+export class PtyOutput {
+    write;
+    flow;
+    paused;
+    chunks = [];
+    bufferedBytes = 0;
+    pendingBytes = 0;
+    scheduled;
+    disposed = false;
+    /** Cleared at child exit: a pause after that could never be lifted by a producer. */
+    throttled = true;
+    constructor(write, flow) {
+        this.write = write;
+        this.flow = flow;
+    }
+    /** Received bytes that have not yet been handed to the ordered render queue. */
+    get hasStagedOutput() {
+        return this.bufferedBytes > 0;
+    }
+    push(data) {
+        if (this.disposed)
+            return;
+        for (let start = 0; start < data.length;) {
+            let end = Math.min(start + pieceCodeUnits, data.length);
+            const last = data.charCodeAt(end - 1);
+            if (end < data.length && last >= 0xd800 && last <= 0xdbff)
+                end--;
+            const chunk = data.slice(start, end);
+            const bytes = Buffer.byteLength(chunk);
+            if (this.bufferedBytes + bytes > renderBatchBytes)
+                this.flush();
+            this.chunks.push(chunk);
+            this.bufferedBytes += bytes;
+            this.pendingBytes += bytes;
+            if (this.throttled &&
+                !this.paused &&
+                this.pendingBytes >= renderHighWaterBytes &&
+                this.flow) {
+                this.paused = this.flow;
+                this.paused.pause();
+            }
+            if (this.bufferedBytes === renderBatchBytes)
+                this.flush();
+            start = end;
+        }
+        if (this.bufferedBytes > 0 && !this.scheduled) {
+            this.scheduled = setTimeout(() => this.flush(), renderBatchDelayMs);
+        }
+    }
+    flush() {
+        clearTimeout(this.scheduled);
+        this.scheduled = undefined;
+        if (this.bufferedBytes === 0)
+            return;
+        const data = this.chunks.join("");
+        const bytes = this.bufferedBytes;
+        this.chunks = [];
+        this.bufferedBytes = 0;
+        // Rendering and public observer failures have no caller on the PTY path.
+        // Own both outcomes, and always release their byte reservation.
+        void this.write(data).then(() => this.release(bytes), () => this.release(bytes));
+    }
+    /**
+     * Stop throttling reads and stay unpaused. Used at child exit, where the producer
+     * is gone: further accounting could only re-pause a PTY nobody will resume.
+     */
+    releaseFlowControl() {
+        this.throttled = false;
+        this.resume();
+    }
+    dispose() {
+        this.disposed = true;
+        clearTimeout(this.scheduled);
+        this.scheduled = undefined;
+        this.chunks = [];
+        this.bufferedBytes = 0;
+        this.pendingBytes = 0;
+        this.resume();
+    }
+    release(bytes) {
+        if (this.disposed)
+            return;
+        this.pendingBytes -= bytes;
+        if (this.pendingBytes < renderLowWaterBytes)
+            this.resume();
+    }
+    resume() {
+        if (!this.paused)
+            return;
+        const flow = this.paused;
+        this.paused = undefined;
+        flow.resume();
+    }
+}
+//# sourceMappingURL=pty-output.js.map

package/dist/terminal/pty-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-output.js","sourceRoot":"","sources":["../../src/terminal/pty-output.ts"],"names":[],"mappings":"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"}

package/dist/terminal/render-queue.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ordered xterm writes with disposal-safe completion, generation-aware settlement and
+ * a permanent render-failure state, so callers can tell whether the screen reflects
+ * everything received. Implements PRD §4.1/§5.3, C-PERF-06 and C-API-56.
+ */
+type XtermWrite = (data: string | Uint8Array, done: () => void) => void;
+export declare class RenderQueue {
+    /** True once any write has failed; nothing later can prove the screen complete again. */
+    renderFailed: boolean;
+    private readonly pending;
+    private drained;
+    private resolveDrained;
+    private settling;
+    /** Set by a settle pass that finished, so `settled()` can tell it never awaited. */
+    private settlePassDone;
+    private readonly write;
+    private readonly submitStaged;
+    /** `submitStaged` hands over any output a batching layer still holds back. */
+    constructor(write: XtermWrite, submitStaged?: () => void);
+    enqueue(data: string | Uint8Array, onRendered?: () => void): Promise<void>;
+    /** One shared traversal: a caller that gave up and retries joins it, never stacks. */
+    settled(): Promise<void>;
+    dispose(): void;
+    private settle;
+    private complete;
+    private finish;
+    private release;
+}
+export {};
+//# sourceMappingURL=render-queue.d.ts.map

package/dist/terminal/render-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-queue.d.ts","sourceRoot":"","sources":["../../src/terminal/render-queue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,KAAK,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAExE,qBAAa,WAAW;IACtB,yFAAyF;IACzF,YAAY,UAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,cAAc,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAA4B;IAC5C,oFAAoF;IACpF,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAE1C,8EAA8E;gBAClE,KAAK,EAAE,UAAU,EAAE,YAAY,GAAE,MAAM,IAAsB;IAKzE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB1E,sFAAsF;IACtF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAaxB,OAAO,IAAI,IAAI;YAMD,MAAM;IAapB,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,OAAO;CAMhB"}

package/dist/terminal/render-queue.js

@@ -0,0 +1,105 @@
+/**
+ * Ordered xterm writes with disposal-safe completion, generation-aware settlement and
+ * a permanent render-failure state, so callers can tell whether the screen reflects
+ * everything received. Implements PRD §4.1/§5.3, C-PERF-06 and C-API-56.
+ */
+export class RenderQueue {
+    /** True once any write has failed; nothing later can prove the screen complete again. */
+    renderFailed = false;
+    pending = new Set();
+    drained = Promise.resolve();
+    resolveDrained;
+    settling;
+    /** Set by a settle pass that finished, so `settled()` can tell it never awaited. */
+    settlePassDone = false;
+    write;
+    submitStaged;
+    /** `submitStaged` hands over any output a batching layer still holds back. */
+    constructor(write, submitStaged = () => undefined) {
+        this.write = write;
+        this.submitStaged = submitStaged;
+    }
+    enqueue(data, onRendered) {
+        if (this.pending.size === 0) {
+            this.drained = new Promise((resolve) => {
+                this.resolveDrained = resolve;
+            });
+        }
+        return new Promise((resolve, reject) => {
+            const pending = { resolve, reject };
+            this.pending.add(pending);
+            try {
+                // xterm already preserves write order and yields while draining. Feeding
+                // its buffer directly avoids paying a fresh timer for every PTY chunk.
+                this.write(data, () => this.complete(pending, onRendered));
+            }
+            catch (error) {
+                // The bytes are gone and the parser may be mid-sequence; no later output can
+                // prove a complete resynchronization, so the failure is permanent.
+                this.renderFailed = true;
+                this.finish(pending);
+                reject(error);
+            }
+        });
+    }
+    /** One shared traversal: a caller that gave up and retries joins it, never stacks. */
+    settled() {
+        if (this.settling !== undefined)
+            return this.settling;
+        this.settlePassDone = false;
+        const settling = this.settle();
+        // A pass that finds nothing pending completes WITHOUT ever awaiting, so it has
+        // already finished by the time it returns here. Memoizing it would strand a
+        // resolved promise: every later caller would join it and return without
+        // observing new output, silently losing the barrier queued writes rely on
+        // (C-API-56). Only an unfinished pass is worth sharing.
+        if (!this.settlePassDone)
+            this.settling = settling;
+        return settling;
+    }
+    dispose() {
+        for (const pending of this.pending)
+            pending.resolve();
+        this.pending.clear();
+        this.release();
+    }
+    async settle() {
+        // Output received while waiting is staged or submitted behind this pass, so submit
+        // and drain again until a pass finds nothing. Observers run inside each write's
+        // render callback, so every one of them has run by the time this resumes.
+        this.submitStaged();
+        while (this.pending.size > 0) {
+            await this.drained;
+            this.submitStaged();
+        }
+        this.settlePassDone = true;
+        this.settling = undefined;
+    }
+    complete(pending, onRendered) {
+        if (!this.pending.has(pending))
+            return; // disposed while xterm still held the callback
+        try {
+            // Run observers inside the ordered render callback: a promise continuation
+            // could otherwise observe a newer frame from the same xterm drain batch.
+            onRendered?.();
+            pending.resolve();
+        }
+        catch (error) {
+            pending.reject(error);
+        }
+        finally {
+            this.finish(pending);
+        }
+    }
+    finish(pending) {
+        this.pending.delete(pending);
+        this.release();
+    }
+    release() {
+        if (this.pending.size === 0) {
+            this.resolveDrained?.();
+            this.resolveDrained = undefined;
+        }
+    }
+}
+//# sourceMappingURL=render-queue.js.map

package/dist/terminal/render-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-queue.js","sourceRoot":"","sources":["../../src/terminal/render-queue.ts"],"names":[],"mappings":"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"}

package/dist/terminal/snapshot.d.ts

@@ -0,0 +1,5 @@
+/** Captures viewport text and cursor coordinates synchronously (PRD §4.1/§5.3). */
+import type { TerminalSize } from "../core/types.ts";
+import type { TerminalSnapshot, XtermTerminal } from "./headless.ts";
+export declare function terminalSnapshot(xterm: XtermTerminal, size: TerminalSize): TerminalSnapshot;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/terminal/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/terminal/snapshot.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAErE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,GAAG,gBAAgB,CAc3F"}

package/dist/terminal/snapshot.js

@@ -0,0 +1,13 @@
+export function terminalSnapshot(xterm, size) {
+    const buffer = xterm.buffer.active;
+    const lines = Array.from({ length: size.rows }, (_, index) => buffer.getLine(buffer.viewportY + index)?.translateToString(true) ?? "");
+    return {
+        cols: size.cols,
+        rows: size.rows,
+        cursorX: buffer.cursorX,
+        cursorY: buffer.cursorY,
+        lines,
+        text: lines.join("\n"),
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/terminal/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/terminal/snapshot.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,gBAAgB,CAAC,KAAoB,EAAE,IAAkB;IACvE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CACtB,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,EACrB,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,EAAE,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,CACtF,CAAC;IACF,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,KAAK;QACL,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;KACvB,CAAC;AACJ,CAAC"}

package/docs/api.md

@@ -17,7 +17,6 @@ import { startClaude } from "@with-logic/elwood"; // deprecated; prefer `new Cla
 
 const claude = await startClaude({
   cwd: "/path/to/project",
-  disallowedTools: ["AskUserQuestion"],
   autotrust: true,
   persona: "You are a terse reviewer. Prefer diffs over prose.",
   hooks: {
@@ -95,6 +94,8 @@ interface ElwoodAgentSession {
   compact(options?: { readonly timeoutMs?: number }): Promise<void>;
   listModels(options?: { readonly timeoutMs?: number }): Promise<readonly AgentModelOption[]>;
   setModel(id: string, options?: { readonly timeoutMs?: number }): Promise<void>;
+  listQuestions(): Promise<readonly ElwoodQuestionRequest[]>;
+  answerQuestions(requestId: string, answers: readonly ElwoodQuestionAnswer[], options?: ElwoodQuestionAnswerOptions): Promise<void>;
   createLoop(request: ElwoodLoopRequest): Promise<ElwoodLoopSnapshot>;
   listLoops(): Promise<readonly ElwoodLoopSnapshot[]>;
   cancelLoop(loopId: string): Promise<void>;
@@ -106,6 +107,12 @@ interface ElwoodAgentSession {
 
 ## Sending input
 
+Native agent questions have a separate control path: subscribe to `question`
+events, recover pending requests with `listQuestions()`, and submit a complete
+request with `answerQuestions()`. These controls work while an ergonomic turn is
+waiting and do not create another user turn. See [questions.md](questions.md) for
+the event, capability, validation and input-ownership contract.
+
 `sendMessage` is the adapter-neutral chat-loop operation. If the session is
 ready it writes through the PTY immediately. If the session is alive but busy,
 Elwood queues it and submits it on the next `ready` transition.