acrylblends 1.0.6 → 1.0.8

package/lib/{snapshot-text-CtQm3n8n.js → snapshot-text-m13Pk-AI.js}

@@ -4,7 +4,7 @@ import { t as methodNotAllowed } from "./method-not-allowed-TO2_hnfl.js";
 import { r as streamSSE } from "./streaming-BlDaph8U.js";
 import { i as loopbackOnly, r as loopbackAuthority } from "./loopback-only-BbasoF7R.js";
 import "./helpers-BEjcdbgw.js";
-import { d as parseChannelToHost, l as UiControlError, u as WINDOW_ID } from "./protocol-Dt0AZBOz.js";
+import { d as parseChannelToHost, l as UiControlError, u as WINDOW_ID } from "./protocol-CQ_if7Dg.js";
 import "./src-BTBm4OPD.js";
 import "./middleware-BfG_fp8P.js";
 import { dirname, join } from "node:path";
@@ -18,9 +18,27 @@ import { timingSafeEqual } from "node:crypto";
 * The Host cannot reach into a page, so each page opens one event stream to the Host and answers calls by POST. With several pages open,
 * the one the user focused last is the one the agent drives. A page that reconnects with the same window id replaces its old stream.
 */
+/** A call that went to a page that never acknowledged it, and was taken back to be sent to the next page. */
+var Silent = class extends UiControlError {
+	constructor() {
+		super("timeout", "the page did not acknowledge the call");
+	}
+};
 /** How long a call may take before it is given up (a wait may take up to 10 seconds itself). */
 const DEFAULT_CALL_TIMEOUT_MS = 3e4;
+/** How long a page has to say it heard a read-only call before the call goes to the next page. */
+const DEFAULT_ACK_MS = 3e3;
+/**
+* The pages and who drives which. One page answers a call, chosen the same way every time: the page the Host just sent somewhere (it comes back as a new page, `prefer`), else the
+* one in front (it reports `focused`), else the most recently active; a page that did not acknowledge a call in time goes to the end of the line. An explicit desktop `window` picks its page.
+*/
 var UiChannel = class {
+	ackMs;
+	/** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
+	preferred;
+	constructor(options = {}) {
+		this.ackMs = options.ackMs ?? DEFAULT_ACK_MS;
+	}
 	connections = /* @__PURE__ */ new Map();
 	pending = /* @__PURE__ */ new Map();
 	nextId = 1;
@@ -40,10 +58,11 @@ var UiChannel = class {
 			windowId,
 			shellWindow,
 			focused,
-			lastActive: ++this.clock
+			lastActive: ++this.clock,
+			suspect: previous?.suspect === true
 		};
 		this.connections.set(windowId, connection);
-		for (const waiter of [...this.attachWaiters]) waiter();
+		for (const waiter of [...this.attachWaiters]) waiter(windowId);
 		return () => {
 			if (this.connections.get(windowId) === connection) this.drop(connection, false);
 		};
@@ -52,13 +71,22 @@ var UiChannel = class {
 	receive(windowId, message) {
 		const connection = this.connections.get(windowId);
 		if (connection === void 0) return;
+		connection.suspect = false;
 		if (message.t === "focus") {
 			connection.focused = message.focused;
-			if (message.focused) connection.lastActive = ++this.clock;
+			if (message.focused) {
+				connection.lastActive = ++this.clock;
+				if (this.preferred !== windowId) this.preferred = void 0;
+			}
 			return;
 		}
 		const entry = this.pending.get(message.id);
 		if (entry === void 0 || entry.connection !== connection) return;
+		if (message.t === "ack") {
+			entry.acked = true;
+			if (entry.ackTimer !== void 0) clearTimeout(entry.ackTimer);
+			return;
+		}
 		if (message.t === "result") this.settle(message.id, message.value);
 		else this.settle(message.id, void 0, new UiControlError(message.code, message.message));
 	}
@@ -68,27 +96,44 @@ var UiChannel = class {
 	}
 	/** The windows currently connected, most recently active first (for diagnostics and tests). */
 	windows() {
-		return this.byRecency().map(({ windowId, focused, shellWindow }) => ({
+		return this.ordered().map(({ windowId, focused, shellWindow }) => ({
 			windowId,
 			focused,
 			...shellWindow === void 0 ? {} : { shellWindow }
 		}));
 	}
+	/** Drive this page from now on (it is the one the Host just sent to a new place), until the person focuses another. */
+	prefer(windowId) {
+		const connection = this.connections.get(windowId);
+		if (connection === void 0) return;
+		this.preferred = windowId;
+		connection.lastActive = ++this.clock;
+	}
 	/**
-	* Ask the current page to do something.
+	* Ask the current page to do something. A read-only call (`look`, `wait`) that the page does not acknowledge in time goes to the next page, and the silent one is last in line
+	* until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
 	* @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
 	*/
-	call(request, options = {}) {
-		if (this.closed) return Promise.reject(new UiControlError("unloaded", "the door was unloaded"));
-		const ordered = this.byRecency();
-		const target = options.window === void 0 ? ordered[0] : ordered.find((connection) => connection.shellWindow === options.window);
-		if (target === void 0 && options.window !== void 0) {
+	async call(request, options = {}) {
+		if (this.closed) throw new UiControlError("unloaded", "the door was unloaded");
+		const ordered = this.ordered();
+		const candidates = options.window === void 0 ? ordered : ordered.filter((connection) => connection.shellWindow === options.window);
+		if (candidates.length === 0 && options.window !== void 0) {
 			const known = ordered.flatMap((connection) => connection.shellWindow === void 0 ? [] : [String(connection.shellWindow)]);
-			return Promise.reject(new UiControlError("no-window", `no page of window ${String(options.window)} is connected to the door${known.length === 0 ? " (no desktop window has a page connected)" : `; windows with a page: ${known.join(", ")}`}; window list prints the windows`));
+			throw new UiControlError("no-window", `no page of window ${String(options.window)} is connected to the door${known.length === 0 ? " (no desktop window has a page connected)" : `; windows with a page: ${known.join(", ")}`}; window list prints the windows`);
 		}
-		if (target === void 0) return Promise.reject(new UiControlError("no-window", "no page of the app is open to control"));
+		if (candidates.length === 0) throw new UiControlError("no-window", "no page of the app is open to control");
+		if (options.signal?.aborted === true) throw new UiControlError("aborted", "the call was cancelled");
+		const readOnly = request.op === "snapshot" || request.op === "wait";
+		for (const target of candidates) try {
+			return await this.callOne(target, request, options, readOnly);
+		} catch (cause) {
+			if (!(cause instanceof Silent)) throw cause;
+		}
+		throw new UiControlError("timeout", `no page of the app answered within ${String(Math.round(this.ackMs / 1e3))} s: the app's pages are open but none responded (a tab in the background, or a page that is still loading). Bring the app's tab to the front, or navigate it, then look again`);
+	}
+	callOne(target, request, options, failOver) {
 		const signal = options.signal;
-		if (signal?.aborted === true) return Promise.reject(new UiControlError("aborted", "the call was cancelled"));
 		const id = this.nextId;
 		this.nextId += 1;
 		return new Promise((resolve, reject) => {
@@ -99,7 +144,15 @@ var UiChannel = class {
 				this.settle(id, void 0, new UiControlError("aborted", "the call was cancelled"));
 			};
 			signal?.addEventListener("abort", onAbort, { once: true });
+			const ackTimer = failOver ? setTimeout(() => {
+				const entry = this.pending.get(id);
+				if (entry === void 0 || entry.acked) return;
+				target.suspect = true;
+				this.settle(id, void 0, new Silent());
+			}, this.ackMs) : void 0;
 			this.pending.set(id, {
+				acked: false,
+				ackTimer,
 				connection: target,
 				resolve,
 				reject,
@@ -143,12 +196,33 @@ var UiChannel = class {
 		});
 	}
 	/**
+	* A promise for the window id of the next page that connects and was not connected when this was asked (the page that came back after a reload or a move).
+	* @returns that id, or `undefined` when no new page connected within `timeoutMs`.
+	*/
+	expectNewPage(timeoutMs) {
+		const known = new Set(this.connections.keys());
+		return new Promise((resolve) => {
+			const done = (value) => {
+				clearTimeout(timer);
+				this.attachWaiters.delete(waiter);
+				resolve(value);
+			};
+			const waiter = (windowId) => {
+				if (!known.has(windowId)) done(windowId);
+			};
+			const timer = setTimeout(() => {
+				done(void 0);
+			}, timeoutMs);
+			this.attachWaiters.add(waiter);
+		});
+	}
+	/**
 	* Ask every connected page to reload (the app just changed under them) and wait, up to `timeoutMs`, for them to come back. Best effort: a page that does not come back
 	* (it was closed, or it moved to a page without the door) is not an error here.
 	* @returns how many pages were asked.
 	*/
 	async reloadAll(timeoutMs = 8e3) {
-		const targets = this.byRecency();
+		const targets = this.ordered();
 		if (this.closed || targets.length === 0) return 0;
 		const back = this.expectAttach(timeoutMs, targets.length);
 		for (const target of targets) {
@@ -172,12 +246,15 @@ var UiChannel = class {
 		for (const connection of [...this.connections.values()]) connection.stream.close();
 		this.connections.clear();
 	}
-	byRecency() {
-		return [...this.connections.values()].sort((a, b) => b.lastActive - a.lastActive);
+	/** The order pages are driven in: the one the Host sent somewhere, suspect ones last, the one in front, then the most recently active. */
+	ordered() {
+		const rank = (connection) => (connection.suspect ? 0 : 4) + (connection.windowId === this.preferred ? 2 : 0) + (connection.focused ? 1 : 0);
+		return [...this.connections.values()].sort((a, b) => rank(b) - rank(a) || b.lastActive - a.lastActive);
 	}
 	/** Forget a connection; its calls in flight settle as `disconnected` at once rather than waiting for their timeout. */
 	drop(connection, closeStream) {
 		this.connections.delete(connection.windowId);
+		if (this.preferred === connection.windowId) this.preferred = void 0;
 		for (const [id, entry] of [...this.pending]) if (entry.connection === connection) this.settle(id, void 0, new UiControlError("disconnected", "the page went away before it answered"));
 		if (closeStream) connection.stream.close();
 	}
@@ -186,6 +263,7 @@ var UiChannel = class {
 		if (entry === void 0) return;
 		this.pending.delete(id);
 		clearTimeout(entry.timer);
+		if (entry.ackTimer !== void 0) clearTimeout(entry.ackTimer);
 		entry.cleanup();
 		if (failure !== void 0) entry.reject(failure);
 		else if (value !== void 0) entry.resolve(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/plugins/acryl-door/plugin.json

@@ -8,6 +8,9 @@
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/schemastery": "3.18.4"
   },
+  "devDependencies": {
+    "ws": "8.21.3"
+  },
   "mount": "mount it after acryl-node-server and extensions in development builds: root.plugin(door); add <script type=\"module\" src=\"/api/acryl-door/page.js\"></script> to the pages; the command is .acryl/bin/acryl",
   "gitignore": [".acryl/"],
   "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],

package/plugins/acryl-door/src/cli/acryl.ts

@@ -26,6 +26,8 @@ export interface Invocation {
   readonly args: Record<string, unknown>
   readonly json: boolean
   readonly dir: string | undefined
+  /** Things the client changed or noticed in the command line; printed to stderr before the call. */
+  readonly warnings: readonly string[]
 }
 
 const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
@@ -47,6 +49,31 @@ const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
   tool list | tool call --tool <name> [--args '<json>']
   verbs`
 
+/**
+ * Git for Windows' bash (MSYS) turns an argument that looks like a Unix path into a Windows path before a native program sees it: `--path /nope` arrives as
+ * `C:/Program Files/Git/nope`. The shim stops that (MSYS_NO_PATHCONV), but a command that does not go through the shim, or an MSYS that ignores the variable, would still
+ * send the app a path it can never serve. A path that begins with the Git install folder is turned back into the path the person typed, with a warning. Only `--path` is read this way.
+ */
+export function undoMsysPath(value: string, env: NodeJS.ProcessEnv, platform: NodeJS.Platform, warnings: string[]): string {
+  if (platform !== 'win32' || !/^[A-Za-z]:[\\/]/u.test(value)) return value
+  const roots = new Set<string>()
+  if (env.EXEPATH) roots.add(env.EXEPATH)
+  for (const folder of (env.PATH ?? env.Path ?? '').split(';')) {
+    const found = /^(.*[\\/]Git)[\\/](?:usr[\\/]bin|cmd|bin|mingw64[\\/]bin)[\\/]?$/iu.exec(folder.trim())
+    if (found?.[1]) roots.add(found[1])
+  }
+  const flat = value.replaceAll('\\', '/')
+  for (const root of roots) {
+    const prefix = `${root.replaceAll('\\', '/').replace(/\/+$/u, '')}/`
+    if (flat.toLowerCase().startsWith(prefix.toLowerCase())) {
+      const path = `/${flat.slice(prefix.length)}`
+      warnings.push(`warning: Git Bash changed the path you typed into "${value}"; using "${path}". Run the command through .acryl/bin/acryl, or set MSYS_NO_PATHCONV=1, so it stays as typed.`)
+      return path
+    }
+  }
+  return value
+}
+
 function integer(values: Map<string, string>, flag: string): number | undefined {
   const raw = values.get(flag)
   if (raw === undefined) return undefined
@@ -56,7 +83,7 @@ function integer(values: Map<string, string>, flag: string): number | undefined
 }
 
 /** @throws UsageError. */
-export function parseInvocation(argv: readonly string[]): Invocation {
+export function parseInvocation(argv: readonly string[], env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): Invocation {
   const words: string[] = []
   const values = new Map<string, string>()
   const set = new Set<string>()
@@ -79,7 +106,8 @@ export function parseInvocation(argv: readonly string[]): Invocation {
   const [first, second, third] = words
   const json = set.has('--json')
   const dir = values.get('--dir')
-  const make = (verb: string, args: Record<string, unknown> = {}): Invocation => ({ verb, args, json, dir })
+  const warnings: string[] = []
+  const make = (verb: string, args: Record<string, unknown> = {}): Invocation => ({ verb, args, json, dir, warnings })
   switch (first) {
     case 'brief': return make('brief')
     case 'verbs': return make('verbs')
@@ -98,7 +126,7 @@ export function parseInvocation(argv: readonly string[]): Invocation {
       return make('act', {
         op: second,
         ...pick('--ref', 'ref'), ...pick('--text', 'text'), ...pick('--option', 'option'), ...pick('--key', 'key'),
-        ...pick('--direction', 'direction'), ...pick('--role', 'role'), ...pick('--name', 'name'), ...pick('--path', 'path'),
+        ...pick('--direction', 'direction'), ...pick('--role', 'role'), ...pick('--name', 'name'), ...(values.has('--path') ? { path: undoMsysPath(values.get('--path') as string, env, platform, warnings) } : {}),
         ...(amount === undefined ? {} : { amount }),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
         ...(window === undefined ? {} : { window }),
@@ -116,7 +144,7 @@ export function parseInvocation(argv: readonly string[]): Invocation {
     case 'window': {
       const id = integer(values, '--id')
       if (second === 'list') return make('window-list')
-      if (second === 'open') return make('window-open', values.has('--path') ? { path: values.get('--path') } : {})
+      if (second === 'open') return make('window-open', values.has('--path') ? { path: undoMsysPath(values.get('--path') as string, env, platform, warnings) } : {})
       if (second === 'focus' || second === 'close' || second === 'resize') {
         if (id === undefined) throw new UsageError(`window ${second} needs --id <n> (window list prints the ids)`)
         if (second === 'focus') return make('window-focus', { id })
@@ -182,6 +210,7 @@ export async function main(argv: readonly string[], io: Io): Promise<number> {
     if (cause instanceof UsageError) { io.err(`${cause.message}\n`); return 2 }
     throw cause
   }
+  for (const warning of invocation.warnings) io.err(`${warning}\n`)
   const app = findApp(io.cwd, invocation.dir)
   const file = app === undefined ? undefined : readDoorFile(app)
   if (app === undefined || file === undefined) {

package/plugins/acryl-door/src/host/channel.ts

@@ -20,7 +20,16 @@ export interface PageStream {
   close(): void
 }
 
+/** A call that went to a page that never acknowledged it, and was taken back to be sent to the next page. */
+class Silent extends UiControlError {
+  constructor() {
+    super('timeout', 'the page did not acknowledge the call')
+  }
+}
+
 interface Pending {
+  acked: boolean
+  ackTimer: NodeJS.Timeout | undefined
   readonly connection: Connection
   readonly resolve: (value: UiResult) => void
   readonly reject: (cause: UiControlError) => void
@@ -36,19 +45,40 @@ interface Connection {
   focused: boolean
   /** Order of last focus (or connection), so the most recent wins. */
   lastActive: number
+  /** A page that did not acknowledge a read-only call in time (a frozen or abandoned tab): last in line until it speaks again. */
+  suspect: boolean
 }
 
 /** How long a call may take before it is given up (a wait may take up to 10 seconds itself). */
 const DEFAULT_CALL_TIMEOUT_MS = 30_000
+/** How long a page has to say it heard a read-only call before the call goes to the next page. */
+const DEFAULT_ACK_MS = 3000
+
+export interface ChannelOptions {
+  /** How long a page has to acknowledge a read-only call (`look`, `wait`) before the next page is tried. */
+  readonly ackMs?: number
+}
 
+/**
+ * The pages and who drives which. One page answers a call, chosen the same way every time: the page the Host just sent somewhere (it comes back as a new page, `prefer`), else the
+ * one in front (it reports `focused`), else the most recently active; a page that did not acknowledge a call in time goes to the end of the line. An explicit desktop `window` picks its page.
+ */
 export class UiChannel {
+  private readonly ackMs: number
+  /** The page the Host sent to a new place and that came back: it keeps being driven until the person focuses another page. */
+  private preferred: string | undefined
+
+  constructor(options: ChannelOptions = {}) {
+    this.ackMs = options.ackMs ?? DEFAULT_ACK_MS
+  }
+
   private readonly connections = new Map<string, Connection>()
   private readonly pending = new Map<number, Pending>()
   private nextId = 1
   private clock = 0
   private closed = false
   /** Callers waiting for a page to (re)connect: each is told once, by the next stream that attaches. */
-  private readonly attachWaiters = new Set<() => void>()
+  private readonly attachWaiters = new Set<(windowId: string) => void>()
 
   /**
    * Register a page's stream. A stream already open for the same window is closed first, and its calls settle as `disconnected`.
@@ -57,9 +87,10 @@ export class UiChannel {
   attach(windowId: string, focused: boolean, stream: PageStream, shellWindow?: number): () => void {
     const previous = this.connections.get(windowId)
     if (previous !== undefined) this.drop(previous, true)
-    const connection: Connection = { stream, windowId, shellWindow, focused, lastActive: ++this.clock }
+    // A page that did not answer stays last in line when its stream reconnects: a tab that cannot answer reconnects just as readily, and would otherwise be first again.
+    const connection: Connection = { stream, windowId, shellWindow, focused, lastActive: ++this.clock, suspect: previous?.suspect === true }
     this.connections.set(windowId, connection)
-    for (const waiter of [...this.attachWaiters]) waiter()
+    for (const waiter of [...this.attachWaiters]) waiter(windowId)
     return () => { if (this.connections.get(windowId) === connection) this.drop(connection, false) }
   }
 
@@ -67,13 +98,24 @@ export class UiChannel {
   receive(windowId: string, message: ChannelToHost): void {
     const connection = this.connections.get(windowId)
     if (connection === undefined) return
+    // Whatever a page says, it is alive.
+    connection.suspect = false
     if (message.t === 'focus') {
       connection.focused = message.focused
-      if (message.focused) connection.lastActive = ++this.clock
+      if (message.focused) {
+        connection.lastActive = ++this.clock
+        // The person moved to this page: the Host stops insisting on the one it sent somewhere.
+        if (this.preferred !== windowId) this.preferred = undefined
+      }
       return
     }
     const entry = this.pending.get(message.id)
     if (entry === undefined || entry.connection !== connection) return
+    if (message.t === 'ack') {
+      entry.acked = true
+      if (entry.ackTimer !== undefined) clearTimeout(entry.ackTimer)
+      return
+    }
     if (message.t === 'result') this.settle(message.id, message.value)
     else this.settle(message.id, undefined, new UiControlError(message.code, message.message))
   }
@@ -85,32 +127,61 @@ export class UiChannel {
 
   /** The windows currently connected, most recently active first (for diagnostics and tests). */
   windows(): readonly { windowId: string; focused: boolean; shellWindow?: number }[] {
-    return this.byRecency().map(({ windowId, focused, shellWindow }) => ({ windowId, focused, ...(shellWindow === undefined ? {} : { shellWindow }) }))
+    return this.ordered().map(({ windowId, focused, shellWindow }) => ({ windowId, focused, ...(shellWindow === undefined ? {} : { shellWindow }) }))
+  }
+
+  /** Drive this page from now on (it is the one the Host just sent to a new place), until the person focuses another. */
+  prefer(windowId: string): void {
+    const connection = this.connections.get(windowId)
+    if (connection === undefined) return
+    this.preferred = windowId
+    connection.lastActive = ++this.clock
   }
 
   /**
-   * Ask the current page to do something.
+   * Ask the current page to do something. A read-only call (`look`, `wait`) that the page does not acknowledge in time goes to the next page, and the silent one is last in line
+   * until it speaks; a call that changes the page is never sent to a second page, because the first might still run it.
    * @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
    */
-  call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}): Promise<UiResult> {
-    if (this.closed) return Promise.reject(new UiControlError('unloaded', 'the door was unloaded'))
-    const ordered = this.byRecency()
+  async call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number; window?: number } = {}): Promise<UiResult> {
+    if (this.closed) throw new UiControlError('unloaded', 'the door was unloaded')
+    const ordered = this.ordered()
     // `window` is the number `window list` prints: that desktop window's page, not the one used last.
-    const target = options.window === undefined ? ordered[0] : ordered.find(connection => connection.shellWindow === options.window)
-    if (target === undefined && options.window !== undefined) {
+    const candidates = options.window === undefined ? ordered : ordered.filter(connection => connection.shellWindow === options.window)
+    if (candidates.length === 0 && options.window !== undefined) {
       const known = ordered.flatMap(connection => (connection.shellWindow === undefined ? [] : [String(connection.shellWindow)]))
-      return Promise.reject(new UiControlError('no-window', `no page of window ${String(options.window)} is connected to the door${known.length === 0 ? ' (no desktop window has a page connected)' : `; windows with a page: ${known.join(', ')}`}; window list prints the windows`))
+      throw new UiControlError('no-window', `no page of window ${String(options.window)} is connected to the door${known.length === 0 ? ' (no desktop window has a page connected)' : `; windows with a page: ${known.join(', ')}`}; window list prints the windows`)
     }
-    if (target === undefined) return Promise.reject(new UiControlError('no-window', 'no page of the app is open to control'))
+    if (candidates.length === 0) throw new UiControlError('no-window', 'no page of the app is open to control')
+    if (options.signal?.aborted === true) throw new UiControlError('aborted', 'the call was cancelled')
+    const readOnly = request.op === 'snapshot' || request.op === 'wait'
+    for (const target of candidates) {
+      try {
+        return await this.callOne(target, request, options, readOnly)
+      } catch (cause) {
+        if (!(cause instanceof Silent)) throw cause
+      }
+    }
+    throw new UiControlError('timeout', `no page of the app answered within ${String(Math.round(this.ackMs / 1000))} s: the app's pages are open but none responded (a tab in the background, or a page that is still loading). Bring the app's tab to the front, or navigate it, then look again`)
+  }
+
+  private callOne(target: Connection, request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number }, failOver: boolean): Promise<UiResult> {
     const signal = options.signal
-    if (signal?.aborted === true) return Promise.reject(new UiControlError('aborted', 'the call was cancelled'))
     const id = this.nextId
     this.nextId += 1
     return new Promise<UiResult>((resolve, reject) => {
       const timer = setTimeout(() => { this.settle(id, undefined, new UiControlError('timeout', 'the page did not answer in time')) }, options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS)
       const onAbort = (): void => { this.settle(id, undefined, new UiControlError('aborted', 'the call was cancelled')) }
       signal?.addEventListener('abort', onAbort, { once: true })
-      this.pending.set(id, { connection: target, resolve, reject, timer, cleanup: () => { signal?.removeEventListener('abort', onAbort) } })
+      const ackTimer = failOver
+        ? setTimeout(() => {
+            const entry = this.pending.get(id)
+            if (entry === undefined || entry.acked) return
+            target.suspect = true
+            this.settle(id, undefined, new Silent())
+          }, this.ackMs)
+        : undefined
+      this.pending.set(id, { acked: false, ackTimer, connection: target, resolve, reject, timer, cleanup: () => { signal?.removeEventListener('abort', onAbort) } } as Pending)
       const frame: ChannelToPage = { t: 'call', id, request }
       try {
         target.stream.send(JSON.stringify(frame))
@@ -134,13 +205,27 @@ export class UiChannel {
     })
   }
 
+  /**
+   * A promise for the window id of the next page that connects and was not connected when this was asked (the page that came back after a reload or a move).
+   * @returns that id, or `undefined` when no new page connected within `timeoutMs`.
+   */
+  expectNewPage(timeoutMs: number): Promise<string | undefined> {
+    const known = new Set(this.connections.keys())
+    return new Promise((resolve) => {
+      const done = (value: string | undefined): void => { clearTimeout(timer); this.attachWaiters.delete(waiter); resolve(value) }
+      const waiter = (windowId: string): void => { if (!known.has(windowId)) done(windowId) }
+      const timer = setTimeout(() => { done(undefined) }, timeoutMs)
+      this.attachWaiters.add(waiter)
+    })
+  }
+
   /**
    * Ask every connected page to reload (the app just changed under them) and wait, up to `timeoutMs`, for them to come back. Best effort: a page that does not come back
    * (it was closed, or it moved to a page without the door) is not an error here.
    * @returns how many pages were asked.
    */
   async reloadAll(timeoutMs = 8000): Promise<number> {
-    const targets = this.byRecency()
+    const targets = this.ordered()
     if (this.closed || targets.length === 0) return 0
     const back = this.expectAttach(timeoutMs, targets.length)
     for (const target of targets) {
@@ -161,13 +246,16 @@ export class UiChannel {
     this.connections.clear()
   }
 
-  private byRecency(): Connection[] {
-    return [...this.connections.values()].sort((a, b) => b.lastActive - a.lastActive)
+  /** The order pages are driven in: the one the Host sent somewhere, suspect ones last, the one in front, then the most recently active. */
+  private ordered(): Connection[] {
+    const rank = (connection: Connection): number => (connection.suspect ? 0 : 4) + (connection.windowId === this.preferred ? 2 : 0) + (connection.focused ? 1 : 0)
+    return [...this.connections.values()].sort((a, b) => rank(b) - rank(a) || b.lastActive - a.lastActive)
   }
 
   /** Forget a connection; its calls in flight settle as `disconnected` at once rather than waiting for their timeout. */
   private drop(connection: Connection, closeStream: boolean): void {
     this.connections.delete(connection.windowId)
+    if (this.preferred === connection.windowId) this.preferred = undefined
     for (const [id, entry] of [...this.pending]) {
       if (entry.connection === connection) this.settle(id, undefined, new UiControlError('disconnected', 'the page went away before it answered'))
     }
@@ -179,6 +267,7 @@ export class UiChannel {
     if (entry === undefined) return
     this.pending.delete(id)
     clearTimeout(entry.timer)
+    if (entry.ackTimer !== undefined) clearTimeout(entry.ackTimer)
     entry.cleanup()
     if (failure !== undefined) entry.reject(failure)
     else if (value !== undefined) entry.resolve(value)

package/plugins/acryl-door/src/host/door.ts

@@ -158,7 +158,7 @@ export class Door {
     const request = this.parse(rest)
     if (request.op !== 'reload' && request.op !== 'navigate') return await this.callPage(`act ${String(input.op)}`, request, signal, window) as UiActionResult
     // The page is replaced: wait for the new one to connect, so the next look sees it. The page may drop before it has answered; that is the reload working.
-    const back = this.deps.channel.expectAttach(this.deps.pageBackMs ?? PAGE_BACK_MS)
+    const back = this.deps.channel.expectNewPage(this.deps.pageBackMs ?? PAGE_BACK_MS)
     let answer: UiActionResult
     try {
       answer = await this.callPage(`act ${request.op}`, request, signal, window) as UiActionResult
@@ -166,7 +166,10 @@ export class Door {
       if (!(cause instanceof UiControlError && cause.code === 'disconnected')) { void back; throw cause }
       answer = { ok: true, detail: request.op === 'reload' ? 'reloading' : `going to ${request.path}` }
     }
-    if (!await back) throw new UiControlError('timeout', request.op === 'reload' ? 'the page did not come back after the reload' : `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`)
+    const came = await back
+    // The page that came back is the one this agent was driving: it stays the target until the person focuses another page.
+    if (came !== undefined) this.deps.channel.prefer(came)
+    if (came === undefined) throw new UiControlError('timeout', request.op === 'reload' ? 'the page did not come back after the reload' : `the page did not come back after going to ${request.path}: is there a page at that path, and does it load the door's script?`)
     const landed = request.op === 'navigate' ? await this.statusAt(request.path) : undefined
     return { ...answer, detail: `${answer.detail ?? 'done'}${landed === undefined ? '' : `; ${landed}`}; the page is back: look again` }
   }

package/plugins/acryl-door/src/host/page-socket.ts

@@ -0,0 +1,78 @@
+/**
+ * The page channel over a WebSocket. An event stream (`page-routes.ts`) holds one of the browser's six connections per host for as long as the page lives; two windows of an app that
+ * also stream their own state, with the panel following a run, use them all, and then no request of either window is sent (the door's answers, Stop). A WebSocket is not one of
+ * those six: it opens at once however many streams are open, and the page's answers travel on it too, so nothing is queued behind a stream.
+ *
+ * `GET <prefix>/channel/ws?window=<id>&focused=0|1[&shell=<n>]` upgrades. The messages are the same JSON as the stream's: down, `{ "e": "call", "d": "<the call>" }` and
+ * `{ "e": "ready" }` / `{ "e": "ping" }`; up, one {@link ChannelToHost} message per frame. A WebSocket has no CORS, so the `Origin` header is the boundary: it must be present and be
+ * exactly this app's own origin, or the upgrade is refused (403) before any handshake. A page on another port, a web site, and a program that sends no `Origin` are all refused.
+ */
+
+import { Acryl, type MiddlewareHandler } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import { loopbackAuthority } from 'acryl-router/middleware'
+import { parseChannelToHost, WINDOW_ID } from '../page/protocol.ts'
+import type { UiChannel } from './channel.ts'
+import { error } from './http.ts'
+
+/** How often the Host writes a `ping`; the page gives up on a socket that is silent for three of these. */
+export const SOCKET_HEARTBEAT_MS = 15_000
+
+export interface PageSocketOptions {
+  readonly prefix: string
+  readonly upgrade: UpgradeWebSocket
+  readonly heartbeatMs?: number
+}
+
+/** The upgrade request comes from this app's own page: a loopback peer on this port, and an `Origin` that is exactly this app's origin. Nothing else is read as proof. */
+export const ownOrigin: MiddlewareHandler = async (c, next) => {
+  const authority = loopbackAuthority(c)
+  const origin = c.req.header('origin')
+  const site = c.req.header('sec-fetch-site')
+  if (authority === undefined || origin === undefined || origin !== authority.origin || (site !== undefined && site !== 'same-origin')) {
+    return c.json(error('only this app\'s own page may open the channel'), 403)
+  }
+  const windowId = c.req.query('window')
+  if (windowId === undefined || !WINDOW_ID.test(windowId)) return c.json(error('a window id is required'), 400)
+  await next()
+}
+
+export function pageSocketRoutes(channel: UiChannel, options: PageSocketOptions): Acryl {
+  const heartbeatMs = options.heartbeatMs ?? SOCKET_HEARTBEAT_MS
+  return new Acryl().get(
+    `${options.prefix}/channel/ws`,
+    ownOrigin,
+    options.upgrade((c) => {
+      const windowId = c.req.query('window') as string
+      const focused = c.req.query('focused') === '1'
+      const shellQuery = Number(c.req.query('shell'))
+      const shellWindow = Number.isSafeInteger(shellQuery) && shellQuery > 0 ? shellQuery : undefined
+      let detach: (() => void) | undefined
+      let beat: NodeJS.Timeout | undefined
+      return {
+        onOpen(_event, ws) {
+          const write = (frame: { e: string; d?: string }): void => {
+            ws.send(JSON.stringify(frame))
+          }
+          // A call that cannot be written fails at once (`disconnected`), and a socket that is gone is dropped by its close: the door never holds a call for it.
+          detach = channel.attach(windowId, focused, { send: data => { write({ e: 'call', d: data }) }, close: () => { ws.close(1000, 'replaced') } }, shellWindow)
+          write({ e: 'ready' })
+          beat = setInterval(() => {
+            try { write({ e: 'ping' }) } catch { /* the close event follows */ }
+          }, heartbeatMs)
+        },
+        onMessage(event) {
+          if (typeof event.data !== 'string') return
+          let message: unknown
+          try { message = JSON.parse(event.data) } catch { return }
+          const parsed = parseChannelToHost(message)
+          if (parsed !== null) channel.receive(windowId, parsed)
+        },
+        onClose() {
+          if (beat !== undefined) clearInterval(beat)
+          detach?.()
+        },
+      }
+    }, { textOnly: true }),
+  )
+}

package/plugins/acryl-door/src/host/shim.ts

@@ -60,7 +60,8 @@ function cmdWord(value: string): string {
 
 export function posixShim(root: string, target: ShimTarget): string {
   const words = [target.node, ...target.nodeOptions, target.client, '--dir', root].map(shWord).join(' ')
-  const env = target.electron ? 'export ELECTRON_RUN_AS_NODE=1\n' : ''
+  // Git Bash on Windows rewrites an argument such as /nope into C:/Program Files/Git/nope when it starts a native program; the door's paths must reach it as typed. Harmless elsewhere.
+  const env = `${target.electron ? 'export ELECTRON_RUN_AS_NODE=1\n' : ''}export MSYS_NO_PATHCONV=1\nexport MSYS2_ARG_CONV_EXCL='*'\n`
   return `#!/bin/sh\n# This app's door (acryl-door): reaches only the app running from this folder. Rewritten each time the app starts.\n${env}exec ${words} "$@"\n`
 }