feat: delegate manual attachment to external terminals (#1871)

#1868 and #1870 provide managed sess preparation, connection references, and explicit terminal binding, but manual attachment still has a gap. When an external terminal has no live session binding, the status-bar attach action can send the native command to vscode-R's global endpoint. In vscode-R-console, that bypasses SessProxy and replaces the proxy-backed transport. PID discovery can also wait indefinitely on an extension-owned pseudoterminal before its frontend gets a chance to recover.

This adds `session.registerTerminalIntegration(terminal, { attach(token) })` so the frontend can restore its own transport and bind the accepted connection using the existing APIs:

- While a registered handler is pending, repeated attach requests remain busy even if a live binding already exists. Otherwise a live terminal owner is focused first, or the registered handler runs before PID discovery. Registered terminals are excluded from native PID association and use explicit binding.
- Registration survives disconnects and connection replacement. Disposal, terminal close, and watcher shutdown revoke it and request cancellation; moving focus away also cancels a pending attempt.
- Registering an integration releases native PID waits that already started for that terminal: scans continue to other terminals, and the old manual attach stops without fallback. Discovery updates use the same eligibility rules, and invalidated operations remain invalid after registration disposal. Terminal and watcher lifetimes, and the lifetime of the requesting handshake or manual operation, also bound native PID waits.
- Concurrent attach requests do not submit duplicate work. Success requires a current live terminal binding, and delayed completion preserves a newer choice of another session. A decline, exception, or cancellation never falls back to the native command.

Consumers can prepare through their proxy, observe the matching connection, and call `activate(sessionId, { terminal, connectionId, select: false })` before returning `true`. vscode-R then verifies the binding and selects/focuses the terminal. Consumers retain responsibility for prompt readiness, submission queues, failure explanations, and R code already submitted when cancellation occurs.

This completes the third part of the external session API for the intended 3.2.0 release alongside #1868 and #1870, so consumers can adopt managed sess with a supported manual recovery path. This change is on the TypeScript side and does not change the bundled sess revision or introduce another reinstall/restart transition. External frontends must adopt the hook; pasting a copied native attach command remains outside this API and can still bypass a proxy.

Author: eitsupi

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Added the extension API's `session.prepareAttachment()` for extensions that own an R process and need vscode-R's managed `sess` setup. R errors and interrupts during manual attachment are now reported as messages while leaving the R prompt usable.
 - Added connection change events and live connection references for sess attachments, with activation controls for consumer-owned terminals.
+- Added `session.registerTerminalIntegration()` so external terminals can recover sess connections without falling back to a native attach command.
 - The httpgd plot backend now requires the `httpgd` R package version 2.0.1 or later. Older versions are treated as unavailable when choosing the plot backend. (#1855)
 
 ## 3.0.1 - 2026-09-28

src/api.d.ts

@@ -40,6 +40,16 @@ export interface RSessionActivationOptions {
     select?: boolean;
 }
 
+/** Consumer-owned terminal hook for restoring a sess connection without bypassing its proxy. */
+export interface RExternalTerminalIntegration {
+    /**
+     * Reconnect through the consumer's transport and bind this terminal before resolving true.
+     * A resolved false is a consumer-reported decline/busy result; a rejection is shown by
+     * vscode-R. Cancellation can stop pending work, but cannot retract R code already submitted.
+     */
+    attach(token: vscode.CancellationToken): Promise<boolean>;
+}
+
 export interface RSessionPreparationOptions {
     /**
      * A local sess IPC endpoint on the current R host, such as a proxy socket.
@@ -123,6 +133,28 @@ export interface RSessionApi {
      * is still current after activation completes; a later disconnect can still occur.
      */
     activate(sessionId: string, options?: RSessionActivationOptions): Promise<boolean>;
+    /**
+     * Register one attach hook for an open terminal. Duplicate or closed-terminal registrations
+     * throw. The hook remains registered across session disconnects and replacements until its
+     * Disposable is disposed, the terminal closes, or the extension host shuts down. It is
+     * invoked before native PID discovery; false, rejection, busy, or cancellation never falls
+     * back to a native attach command. On true, vscode-R requires a current live session binding
+     * for this terminal, then focuses that session. Consumers should bind with
+     * `activate(..., { terminal, connectionId, select: false })` before resolving true. When no
+     * hook is in flight, a current live owner is focused and the hook is skipped. While a hook is
+     * in flight, repeated activations report busy without selecting or focusing its bound owner,
+     * and do not invoke another handler. The terminal remains busy until the handler promise
+     * settles, even after cancellation is requested.
+     * Registered terminals are excluded from native PID association, so consumers must bind
+     * their session explicitly. Registration during host shutdown throws.
+     * If the user selects another session while the hook is pending, vscode-R leaves that selection
+     * in place and retains the terminal binding. Cancellation is requested when focus leaves the
+     * terminal, it closes, registration is disposed, or the host shuts down. Consumers should
+     * stop cancellable waits and settle the handler on cancellation. Submitted R code cannot be
+     * recalled; the consumer must retain its preparation while the runtime keeps its submission
+     * queue occupied until execution finishes.
+     */
+    registerTerminalIntegration(terminal: vscode.Terminal, integration: RExternalTerminalIntegration): vscode.Disposable;
 }
 
 export type HelpSubMenu = 'doc' | 'pkgList' | 'refresh' | '?' | '??';

src/extension.ts

@@ -66,6 +66,7 @@ export async function activate(context: vscode.ExtensionContext): Promise<apiImp
         activate: session.activateSessionById,
         onDidChangeSessionConnection: session.onDidChangeSessionConnection,
         getSessionReference: session.getSessionReference,
+        registerTerminalIntegration: session.registerTerminalIntegration,
     };
 
     // assign extension context to global variable

src/nativeTerminalPidWait.ts

@@ -0,0 +1,123 @@
+export type NativeTerminalPidWaitResult<Value> =
+    | { readonly kind: 'resolved'; readonly value: Value; readonly isCurrent: () => boolean }
+    | { readonly kind: 'invalidated'; readonly reason: 'terminal' | 'lifecycle' | 'operation' };
+
+export interface NativeTerminalPidWaitOptions {
+    readonly signal?: AbortSignal;
+    readonly isEligible?: () => boolean;
+}
+
+interface NativeTerminalPidWaiter<T extends object> {
+    readonly terminal: T;
+    invalidate(reason: 'terminal' | 'lifecycle'): void;
+}
+
+/** Interruptible reads of VS Code's otherwise uncancellable terminal processId promise. */
+export class NativeTerminalPidWaitRegistry<T extends object> {
+    private lifecycleRevision = 0;
+    private readonly terminalRevisions = new WeakMap<T, number>();
+    private readonly waiters = new Set<NativeTerminalPidWaiter<T>>();
+
+    public invalidate(terminal: T): void {
+        this.terminalRevisions.set(terminal, this.revisionOf(terminal) + 1);
+        for (const waiter of this.waiters) {
+            if (waiter.terminal === terminal) { waiter.invalidate('terminal'); }
+        }
+    }
+
+    public invalidateAll(): void {
+        this.lifecycleRevision++;
+        for (const waiter of this.waiters) { waiter.invalidate('lifecycle'); }
+    }
+
+    public waitFor<Value>(
+        terminal: T,
+        read: () => PromiseLike<Value> | Value,
+        options: NativeTerminalPidWaitOptions = {},
+    ): Promise<NativeTerminalPidWaitResult<Value>> {
+        const terminalRevision = this.revisionOf(terminal);
+        const lifecycleRevision = this.lifecycleRevision;
+
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const isCurrent = (): boolean => !options.signal?.aborted
+                && lifecycleRevision === this.lifecycleRevision
+                && terminalRevision === this.revisionOf(terminal)
+                && (options.isEligible?.() ?? true);
+            const checkCurrent = (): boolean => {
+                try { return isCurrent(); }
+                catch (error) { finishError(error); return false; }
+            };
+            const finish = (result: NativeTerminalPidWaitResult<Value>): void => {
+                if (settled) { return; }
+                settled = true;
+                cleanup();
+                resolve(result);
+            };
+            const finishError = (error: unknown): void => {
+                if (settled) { return; }
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            const waiter: NativeTerminalPidWaiter<T> = {
+                terminal,
+                invalidate: reason => finish({ kind: 'invalidated', reason }),
+            };
+            const onAbort = () => finish({ kind: 'invalidated', reason: 'operation' });
+            const cleanup = (): void => {
+                this.waiters.delete(waiter);
+                options.signal?.removeEventListener('abort', onAbort);
+            };
+
+            // Install invalidation listeners before reading processId: its getter may
+            // synchronously trigger registration, close, or shutdown callbacks.
+            this.waiters.add(waiter);
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            if (options.signal?.aborted) {
+                onAbort();
+                return;
+            }
+            if (lifecycleRevision !== this.lifecycleRevision) {
+                finish({ kind: 'invalidated', reason: 'lifecycle' });
+                return;
+            }
+            let eligible: boolean;
+            try { eligible = options.isEligible?.() ?? true; }
+            catch (error) { finishError(error); return; }
+            if (terminalRevision !== this.revisionOf(terminal) || !eligible) {
+                finish({ kind: 'invalidated', reason: 'terminal' });
+                return;
+            }
+
+            let pending: Promise<Value>;
+            try { pending = Promise.resolve(read()); }
+            catch (error) { finishError(error); return; }
+            // Keep a rejection observer after invalidation so the underlying VS Code
+            // promise cannot become an unhandled rejection if it settles late.
+            void pending.then(value => {
+                if (settled) { return; }
+                if (!checkCurrent()) {
+                    if (settled) { return; }
+                    const reason = options.signal?.aborted ? 'operation'
+                        : lifecycleRevision !== this.lifecycleRevision ? 'lifecycle' : 'terminal';
+                    finish({ kind: 'invalidated', reason });
+                    return;
+                }
+                finish({ kind: 'resolved', value, isCurrent });
+            }, error => {
+                if (settled) { return; }
+                if (!checkCurrent()) {
+                    if (settled) { return; }
+                    const reason = options.signal?.aborted ? 'operation'
+                        : lifecycleRevision !== this.lifecycleRevision ? 'lifecycle' : 'terminal';
+                    finish({ kind: 'invalidated', reason });
+                    return;
+                }
+                finishError(error);
+            });
+        });
+    }
+
+    private revisionOf(terminal: T): number { return this.terminalRevisions.get(terminal) ?? 0; }
+}