mixdog 1.4.1 → 1.4.3

package/scripts/provider-pingpong-live.mjs

@@ -10,7 +10,7 @@
 // stores. Only the API-key secrets (`secrets/agent.<provider>.apiKey.dpapi`) and the
 // `agent` section of mixdog-config.json are copied in. OAuth providers (`*-oauth`, whose
 // refresh tokens could be rotated) are skipped unless `--real-data` is passed, which
-// restores the old behaviour of running against the real data dir. The isolated dir is
+// runs against the real data dir instead. The isolated dir is
 // deleted at the end, after stopping only processes whose executable lives inside it.
 // Usage: node scripts/provider-pingpong-live.mjs [--suite extended] [--real-data] [case-name ...]
 import fs from 'node:fs';

package/scripts/prune-embedding-runtime.mjs

@@ -118,7 +118,9 @@ export async function pruneEmbeddingRuntime(packageRoot, options = {}) {
       }
     }
   }
-  await removeChildrenExcept(ortRoot, new Set(['package.json', 'dist', 'bin', 'node_modules']));
+  // npm runs onnxruntime-node's own postinstall (node ./script/install)
+  // concurrently with ours, so its script/ helpers must survive the prune.
+  await removeChildrenExcept(ortRoot, new Set(['package.json', 'dist', 'bin', 'node_modules', 'script']));
 
   // The Node bundle marks onnxruntime-web as an ignored webpack external. Keep
   // only its manifest so npm's dependency inventory remains coherent.

package/scripts/release-paths.mjs

@@ -51,7 +51,13 @@ const PATCH_GATE_FILES = [
 // workflow, output-style and bundled-skill trees (scripts/build-shipped-history.mjs)
 // and committed under src/defaults/. Release re-checks it, so the gate checks
 // it first instead of letting a stale file fail the deploy late.
-const HISTORY_GATE_PREFIXES = ['src/agents/', 'src/workflows/', 'src/output-styles/', 'src/defaults/'];
+const HISTORY_GATE_PREFIXES = [
+  'src/agents/',
+  'src/workflows/',
+  'src/output-styles/',
+  'src/orchestration/',
+  'src/defaults/',
+];
 const HISTORY_GATE_FILES = [
   'scripts/build-shipped-history.mjs',
   'src/runtime/shared/shipped-definitions.mjs',

package/scripts/suite-health.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 // Weekly opt-out sweep: run every test:*/smoke:* npm script in the repository
-// so no locally-registered suite can rot silently (docs/testing.md, "A
-// contract suite runs in CI or it drifts"). New scripts join automatically;
+// so no locally-registered suite can rot silently (docs/testing.md, "CI coverage"). New scripts join automatically;
 // exclusions are explicit, reasoned, and fail closed when they go stale.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -36,13 +35,9 @@ export const WORKSPACES = [
       'test:daemon:e2e': 'needs the built daemon; the release gate desktop job owns it',
       'test:spec-advisory': 'advisory by design (MIXDOG_TEST_ADVISORY)',
       'test:browser-host:integration': 'live desktop integration harness',
-      'test:browser-login-persistence:integration':
-        'live desktop integration harness; launches real Electron, which needs a display the Linux sweep runner lacks',
-      'test:browser-login-popup:integration':
-        'live desktop integration harness; launches real Electron, which needs a display the Linux sweep runner lacks',
       'test:browser-profile-import:integration': 'live desktop integration harness',
       'test:remote-webrtc-sender:integration':
-        'live desktop integration harness; launches real Electron, which needs a display the Linux sweep runner lacks',
+        'live desktop integration harness; launches real Electron and has never run in the sweep, so it stays out until verified under Xvfb',
       'test:computer-host:integration': 'live desktop integration harness',
       'test:computer-host:scenarios': 'live desktop scenario harness',
       'test:computer-host:repeats': 'live desktop scenario harness',
@@ -50,6 +45,32 @@ export const WORKSPACES = [
   },
 ];
 
+// Swept scripts that launch a real Electron window. The headless Linux runner
+// has no X server, so they run inside a virtual one (xvfb-run, as
+// linux-desktop-verify.yml does). The runner also has no usable keyring (a
+// keyring daemon there prompts for an unlock on a display it cannot open and
+// stalls the entry), and these entries check Mixdog's own persistence and
+// sign-out logic, not the OS keychain. So on Linux the sweep sets
+// TEST_PLAINTEXT_SAFE_STORAGE_ENV and the test harness alone (never the app)
+// switches Electron's safeStorage to its in-memory-password fallback.
+export const DISPLAY_SUITES = ['test:browser-login-persistence:integration', 'test:browser-login-popup:integration'];
+export const TEST_PLAINTEXT_SAFE_STORAGE_ENV = 'MIXDOG_TEST_PLAINTEXT_SAFE_STORAGE';
+
+const runsUnderDisplay = (ws, name, platform) =>
+  platform === 'linux' && ws.dir !== '.' && DISPLAY_SUITES.includes(name);
+
+export function sweepCommand(ws, name, platform = process.platform) {
+  const args = ['run', name, ...(ws.dir === '.' ? [] : ['--prefix', ws.dir])];
+  if (runsUnderDisplay(ws, name, platform)) {
+    return ['xvfb-run', ['-a', '--server-args=-screen 0 1440x900x24', 'npm', ...args]];
+  }
+  return [platform === 'win32' ? 'npm.cmd' : 'npm', args];
+}
+
+export function sweepEnv(ws, name, platform = process.platform, base = process.env) {
+  return runsUnderDisplay(ws, name, platform) ? { ...base, [TEST_PLAINTEXT_SAFE_STORAGE_ENV]: '1' } : base;
+}
+
 export function selectSuiteScripts(scripts, exclusions) {
   const names = Object.keys(scripts).filter((name) => /^(test|smoke)(:|$)/.test(name));
   const stale = Object.keys(exclusions).filter((name) => !names.includes(name));
@@ -59,12 +80,80 @@ export function selectSuiteScripts(scripts, exclusions) {
   return names.filter((name) => !(name in exclusions));
 }
 
-const lastLines = (text) =>
-  String(text || '')
+const TAIL_LINES = 25;
+const lastLines = (text, name) => {
+  const lines = String(text || '')
     .trim()
+    .split('\n');
+  if (lines.length <= TAIL_LINES) return lines.join('\n');
+  return [`[${name} truncated: last ${TAIL_LINES} of ${lines.length} lines]`, ...lines.slice(-TAIL_LINES)].join('\n');
+};
+
+// What a failed entry shows in the report: how it ended, every failure-summary
+// and failed-test line from either stream (a long stderr must not hide them),
+// then each stream's tail.
+export function failureParts({ stdout, stderr, status, signal, error }) {
+  const failedLines = `${stdout || ''}\n${stderr || ''}`
     .split('\n')
-    .slice(-25)
-    .join('\n');
+    .filter((line) => /^\[failure-summary\]|^\s*✖ /.test(line));
+  const ended = error
+    ? `spawn error: ${error.message}`
+    : `exit ${status ?? 'none'}${signal ? `, signal ${signal}` : ''}`;
+  const tails = [lastLines(stdout, 'stdout'), lastLines(stderr, 'stderr')].filter(Boolean).join('\n');
+  return { ended, failedLines, tails };
+}
+
+const failureText = ({ ended, failedLines, tails }) =>
+  [ended, failedLines.join('\n'), tails].filter(Boolean).join('\n').trim();
+
+export const failureTail = (child) => failureText(failureParts(child));
+
+// GitHub rejects an issue body over 65,536 characters (HTTP 422). Past the
+// limit the tails go first, then failure lines from the end; the omission is
+// always stated, and the full diagnostics stay in the workflow log.
+const ISSUE_BODY_LIMIT = 60_000;
+
+export function buildReport({ checked, runUrl, reportLines, failures, limit = ISSUE_BODY_LIMIT }) {
+  const render = (withTails, keep) => {
+    let left = keep;
+    let omitted = 0;
+    const blocks = failures.map(({ title, parts }) => {
+      const shown = parts.failedLines.slice(0, left);
+      left -= shown.length;
+      omitted += parts.failedLines.length - shown.length;
+      const text = failureText({ ...parts, failedLines: shown, tails: withTails ? parts.tails : '' });
+      return `${title}\n\n\`\`\`\n${text}\n\`\`\``;
+    });
+    const notes = [];
+    if (!withTails) notes.push('Stdout/stderr tails omitted to fit the issue size limit; see the workflow log.');
+    if (omitted) notes.push(`${omitted} more failure lines omitted — see the workflow log: ${runUrl}`);
+    return [
+      '# Weekly suite health sweep failed',
+      '',
+      `Checked: ${checked}`,
+      `Workflow run: ${runUrl}`,
+      '',
+      ...reportLines,
+      '',
+      ...blocks,
+      '',
+      ...notes,
+    ]
+      .join('\n')
+      .trimEnd()
+      .concat('\n');
+  };
+  const total = failures.reduce((sum, { parts }) => sum + parts.failedLines.length, 0);
+  if (render(true, total).length <= limit) return render(true, total);
+  let low = 0;
+  let high = total;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (render(false, mid).length <= limit) low = mid;
+    else high = mid - 1;
+  }
+  return render(false, low);
+}
 
 function runSweep() {
   const failures = [];
@@ -75,8 +164,9 @@ function runSweep() {
     for (const name of names) {
       const label = ws.dir === '.' ? name : `${ws.dir} ${name}`;
       const started = Date.now();
-      const args = ['run', name, ...(ws.dir === '.' ? [] : ['--prefix', ws.dir])];
-      const child = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, {
+      const [command, args] = sweepCommand(ws, name);
+      const child = spawnSync(command, args, {
+        env: sweepEnv(ws, name),
         encoding: 'utf8',
         shell: process.platform === 'win32',
         maxBuffer: 64 * 1024 * 1024,
@@ -88,10 +178,10 @@ function runSweep() {
       } else {
         // Tail each stream on its own: a long stderr (cargo build chatter) must
         // not push the test failure summary on stdout out of the report.
-        const tail = `${lastLines(child.stdout)}\n${lastLines(child.stderr)}`.trim();
-        failures.push(`- ${label}: FAILED (${seconds}s)\n\n\`\`\`\n${tail}\n\`\`\``);
+        const parts = failureParts(child);
+        failures.push({ title: `- ${label}: FAILED (${seconds}s)`, parts });
         reportLines.push(`- ${label}: FAILED (${seconds}s)`);
-        console.error(`${label}: FAILED (${seconds}s)\n${tail}`);
+        console.error(`${label}: FAILED (${seconds}s)\n${failureText(parts)}`);
       }
     }
   }
@@ -100,18 +190,10 @@ function runSweep() {
     const runUrl = process.env.GITHUB_RUN_ID
       ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
       : '(local run)';
-    const report = [
-      '# Weekly suite health sweep failed',
-      '',
-      `Checked: ${new Date().toISOString()}`,
-      `Workflow run: ${runUrl}`,
-      '',
-      ...reportLines,
-      '',
-      ...failures,
-      '',
-    ].join('\n');
-    writeFileSync('suite-health-report.md', report);
+    writeFileSync(
+      'suite-health-report.md',
+      buildReport({ checked: new Date().toISOString(), runUrl, reportLines, failures })
+    );
     process.exitCode = 1;
   }
 }

package/scripts/test.mjs

@@ -40,12 +40,11 @@ export const USAGE = `Usage: node scripts/test.mjs [--lane ${LANES.join('|')}] [
   --exclude-lane  drop one lane from the selection, repeatable. Electron and
                   window-capture tests cannot run twice at once, so a second
                   concurrent --lane all run uses --exclude-lane electron.
-  --rerun-failed <n>  re-run the failed files up to n times. Default: 1 for a
-                  local run, 0 (off) when CI is set; MIXDOG_TEST_RERUN_FAILED
-                  overrides the default. A test that passes on a re-run is
-                  reported as flaky and does NOT fail the run; a test that
-                  fails every re-run still exits 1. With 0 every failure fails
-                  the run.
+  --rerun-failed <n>  re-run the failed files up to n times to classify flaky
+                  tests. Default 0: every failure fails the run;
+                  MIXDOG_TEST_RERUN_FAILED overrides the default. A test that
+                  passes on a re-run is reported as flaky and does NOT fail the
+                  run; a test that fails every re-run still exits 1.
   Per-file timeout: --test-timeout (default 120000 ms for the fast lane, 600000
                   ms otherwise); MIXDOG_TEST_TIMEOUT_MS overrides, 0 disables.
   --import        forwarded to node (desktop passes its test-env and tsx loaders).
@@ -88,15 +87,11 @@ function rerunCount(value) {
   return Number(value);
 }
 
-// Files run in parallel on every core, which exposes timing-sensitive tests
-// that pass alone. A local run therefore re-runs failed files once and reports
-// a pass on the re-run as flaky (named in the failure summary). CI keeps the
-// strict policy unless it opts in with --rerun-failed or MIXDOG_TEST_RERUN_FAILED;
-// MIXDOG_TEST_RERUN_FAILED=0 turns the local default off.
+// Every failure fails the run, locally and in CI: a test that passes only on a
+// re-run is a defect to fix, not a pass. Re-runs happen only on an explicit
+// --rerun-failed or MIXDOG_TEST_RERUN_FAILED, to classify a failure as flaky.
 export function defaultRerunFailed(env = process.env) {
-  if (/^\d+$/.test(String(env.MIXDOG_TEST_RERUN_FAILED ?? ''))) return Number(env.MIXDOG_TEST_RERUN_FAILED);
-  const ci = String(env.CI ?? '').toLowerCase();
-  return ci && ci !== '0' && ci !== 'false' ? 0 : 1;
+  return /^\d+$/.test(String(env.MIXDOG_TEST_RERUN_FAILED ?? '')) ? Number(env.MIXDOG_TEST_RERUN_FAILED) : 0;
 }
 
 export function parseArgs(argv) {

package/src/agents/advisor/AGENT.md

@@ -1,13 +1,13 @@
 ---
 name: Advisor
-description: "Use when the approach is genuinely unclear, when errors recur or results stop converging, before changing approach, or when the user asks for a second opinion. Never for final verification."
+description: "Use as a second mind on hard work: consulting before a risky or complex change is built, hunting a bug whose cause is unclear, errors that recur or results that stop converging, or when the user asks. Never for final verification."
 ---
 
 Independent technical advisor.
 
-You are consulted at decision points: when the approach is genuinely
-unclear, when errors recur or results stop converging, before a
-change of approach, and when the user asks for a second opinion or
+You are a second mind on hard work: consulted before a risky or complex
+change is built, to hunt a bug whose cause is unclear, when errors recur or
+results stop converging, and when the user asks for a second opinion or
 cross-validation. You do not see the Lead's conversation; work from the brief
 and verify its evidence against the source yourself.
 

package/src/agents/advisor/agent.json

@@ -1,6 +1,6 @@
 {
   "id": "advisor",
   "name": "Advisor",
-  "description": "Use when the approach is genuinely unclear, when errors recur or results stop converging, before changing approach, or when the user asks for a second opinion. Never for final verification.",
+  "description": "Use as a second mind on hard work: consulting before a risky or complex change is built, hunting a bug whose cause is unclear, errors that recur or results that stop converging, or when the user asks. Never for final verification.",
   "entry": "AGENT.md"
 }

package/src/agents/explore/AGENT.md

@@ -0,0 +1,22 @@
+---
+name: Explore
+description: Use when Mixdog runs the explore tool. The tool stays off until a model is picked.
+permission: read
+---
+
+Read-only explorer for one query of the explore tool. Search and read the
+working directory; never edit, run commands or delegate.
+
+Answer the query in the message, then stop:
+
+- First a short direct answer.
+- Then the evidence: one `path:line` per finding, copied from tool output,
+  with a few words on what is there.
+- Only what you found. If nothing answers the query, say so in one line and
+  name what you searched.
+- Nothing else: no locations the query did not ask about, no notes on what
+  you did not read.
+
+Batch independent patterns and paths in one call. A location a tool returned
+is final: do not re-read or reconfirm it. Stop as soon as the answer is
+supported.

package/src/agents/explore/agent.json

@@ -0,0 +1,6 @@
+{
+  "id": "explore",
+  "name": "Explore",
+  "description": "Use when Mixdog runs the explore tool. The tool stays off until a model is picked.",
+  "entry": "AGENT.md"
+}

package/src/cli.mjs

@@ -24,6 +24,13 @@ try {
 // 2026-07-20). Default to production; an explicit NODE_ENV still wins.
 process.env.NODE_ENV ||= 'production';
 
+// HTTPS_PROXY/HTTP_PROXY work without NODE_USE_ENV_PROXY: honoured in this
+// process and in every child (the daemon included). On Windows without any
+// proxy variable, the static system proxy routes this process's own fetch and
+// is handed to the daemon this CLI starts, never exported as environment.
+(await import('./runtime/shared/llm/system-proxy.mjs')).adoptSystemProxy();
+(await import('./runtime/shared/llm/http-agent.mjs')).adoptEnvProxy();
+
 let swapped = false;
 const invocation = classifyCliInvocation(argv);
 const skipHostPrelude = invocation.kind === 'exec' || invocation.skipHostPrelude === true;

package/src/defaults/agents.json

@@ -1,5 +1,12 @@
 {
   "agents": [
+    {
+      "agent": "explore-agent",
+      "slot": "explore",
+      "description": "One-off read-only explorer, one per query of the explore tool",
+      "invokedBy": "explore",
+      "maintKey": "explore"
+    },
     {
       "agent": "cycle1-agent",
       "slot": "cycle1",

package/src/defaults/shipped-history.json

@@ -3,12 +3,14 @@
     "advisor": [
       "6bd0318995f70547c162efda92795e79",
       "895c5f4311dcbebc0c8756c9ec61a02a",
-      "d3b4a7926c9484833fe8ddba70260f9d"
+      "d3b4a7926c9484833fe8ddba70260f9d",
+      "fa56b363b9eeb07cb194dcd66dc4159b"
     ],
     "debugger": [
       "88c946270760ecbae86df65b9ce262f1"
     ],
     "explore": [
+      "baf26f0b3bd3abb0fb5a276febc8c4bc",
       "d4fa3ff93ace1dfac0b92792f42b9cbf"
     ],
     "front-worker": [
@@ -177,6 +179,20 @@
       "d5f205f3b57c0b9541b8acc237069287"
     ]
   },
+  "orchestration": {
+    "balanced.md": [
+      "ad1683ff1626ebabd4e027abe03fe29a"
+    ],
+    "focused.md": [
+      "e73b0d71f544900611b2d06f963472d4"
+    ],
+    "none.md": [
+      "9be4bf61f9ba91c4caf53296adff2e8a"
+    ],
+    "swarm.md": [
+      "7fa3e68e0c53d16203384f5ca645765d"
+    ]
+  },
   "skills": {
     "browser-use": [
       "00085086a7649ec6631f5cf0a3bbbf60",
@@ -186,6 +202,7 @@
       "43eeb0b9c5792f08f2223c76846926cb",
       "4ab5316454013712cedb25d9b75f4e43",
       "4f042de090d853ed38aaa82b88d301ac",
+      "5d909abd96e4aa8636f27cf652301c5e",
       "646365a3f7041a3da3d7d7d896a0c3b6",
       "662f730d603b1e583dc777a1984b9134",
       "814b0820a05119a049cf4262dc35301b",
@@ -216,6 +233,7 @@
       "8a5a68ec13a7414b35e7f3b0089e2208",
       "9728f28dc5b23eb1bb1924213d3ffddd",
       "9a8789b3b4f5f6b3ba02f407cdfb92f7",
+      "ab5cce4a2fccad63e006cf22aa6cc6b0",
       "b50e9c0ba5e8228583eab4f0e0573838",
       "c03f4d0e008467497c0152639953b166",
       "cd1a47197762135462037ea6555ea721",
@@ -246,6 +264,7 @@
       "e10367dd4291a0b3d8ee8e8dd60eae36",
       "e1f2526aaf123fb77072aa8975f890de",
       "e67f30ec5bbdd36d7feaabd35b7504b3",
+      "edc3519cf07e37702a5793bb23e0643c",
       "f0798c546c172a742e3384d82322ede4"
     ],
     "docx": [
@@ -268,6 +287,7 @@
       "07604666cb32a7df8b1d4f0d1e137890",
       "189bca949decd5bccbbdeb49a18426b2",
       "1db9f3e81c714e7e4aa8db8c8004cca0",
+      "290d7620499a4134fdf511aa4902043d",
       "6d922fc351d6519c3d92cc5807fe0615",
       "95c83d23f3625c35cc346477a470c769",
       "a47d07ea3402854dc03e655afd5a3a6d",
@@ -362,6 +382,7 @@
     ],
     "setup": [
       "0357c6d475ced8ba2446e6bda21899b4",
+      "0bb692f16b03c66f23af06cea06de51f",
       "0be31b379e919420e5b8f74926bdf6e5",
       "0d5c8c6e2349addf71d2ed2b4c1ccb1f",
       "0d6926aaca2890da9347f15a826546e3",
@@ -372,7 +393,9 @@
       "242f11864abdef90fa0cc9cb4599a579",
       "29a347c4d3a2f773fa92c627260301ba",
       "336ced846a9e4f774cbb109417856c3b",
+      "34c5f8fcb6292b8cc5239667d2119e83",
       "3716b2d2c2d973ae022694ed5cb756ad",
+      "398958b6f815bf8ad3f96dd288844333",
       "3dc990c29cdce1aca4b112d735ad5917",
       "3f72247651ad9d777b6754bfd46732aa",
       "50bdf35d06913236855080fdea6b50dc",
@@ -388,7 +411,10 @@
       "81e979463e0066e7a45cf511a31c5d68",
       "8476c811b2f02da3a434bcb23a1c3d12",
       "8af2b614e2a07b58dad6c0f1318d22e2",
+      "8b829db6b0675b62a71a1432dbd25490",
       "99d76213e70c6900d6af48ffa4045886",
+      "9a2188ce201e4394bc18182131b7a3e1",
+      "9b10b59b27497a126b212df083ace020",
       "9f90d3872b1ecd312977ce661b770b31",
       "ade615dd0f6ae6ed1601023e5b9cb692",
       "b21681ecfeb523c0d7dd89a299ec05a9",
@@ -409,21 +435,29 @@
       "ff18ac1a9f5961925aec27ffb870bae0"
     ],
     "setup-guide": [
+      "0968139f1aa26f48f03cfea2e94f45e8",
       "633e15b84dbe22f2b578b67cc35853d4",
       "72e474711ecd18cfcae6c8365e08286e",
       "920d5b29ccfe6c88f623cf0892b29285",
-      "ec88a82ab5e511c0afb1738162150648"
+      "dbe3d22991ad4dff6e3906f9101c9b5f",
+      "ec88a82ab5e511c0afb1738162150648",
+      "fa355d4ea5f1823e4b75219ab842c34a"
     ],
     "skill-creator": [
       "020817866da73a69544ba35086bdcd5f",
       "2f3f44805618783fbcca9a56652a5e91",
       "50e365910692a803732f68f82fc1ed1f",
       "77a4ca1c08f684780eeeebec50a3f1e6",
+      "92b2ed0b18a9c14470e434ec946a843f",
       "bd9bf738a5b3f443450c86230f3299fd",
       "bec7e5abbcae88a6781d23bcdd35e259",
       "d65265972caa7cbefc39baacc9e78157",
       "f450e6d58a7f1f06c71aa2dd557ce09c"
     ],
+    "test-suite": [
+      "df60ba4a182ee289f3550e79f1731cd4",
+      "f5c8ee5331a9b8279f997f609b10c380"
+    ],
     "video": [
       "6aad64b16521d324e355d125692a0cec",
       "82f61245cc67ce5380ab9ccf4c697c29",
@@ -436,6 +470,8 @@
       "8320fedd9dd745a332621c325a8bf355",
       "9c9fba19647b67d75a600137e38c02b8",
       "aa3531bfc4fd6ec3820493d0c190cc75",
+      "d9ba9f5f998bf42990eed838a3d1b774",
+      "df699ca05260ce37813a7fe6666927da",
       "f24ff77670e5aa43ce901dec1e0055ac",
       "f65924f0691284ad31000469a9855b62"
     ],

package/src/defaults/skills/browser-use/SKILL.md

@@ -320,7 +320,10 @@ file-reading tool instead of clicking around the page.
 **Multi-page task** — keep one snapshot per page; `list_tabs` when targets or
 ownership are unknown, then act on the intended tab. Use `back` instead of
 re-navigating when history suffices; forward is a `navigate` to the URL the
-earlier snapshot showed.
+earlier snapshot showed. A popup the page opens (`window.open`, an OAuth or
+sign-in window) becomes a background page the reply names ("Opened
+"popup-N" as a new page"), and the visible page does not switch: act on it
+by that name, and check `list_tabs` before concluding no popup opened.
 
 **Downloads / uploads** — `downloads` lists and can `wait` for and `attach`
 the newest file (≤ 8 MiB). A wait pins the newest download, or the next one to