@tomflow/proflow-execution-browser-extension 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-execution-browser-extension
 
+## 0.1.14
+
+### Patch Changes
+
+- Retire the obsolete Carrier package and Browser standalone management CLI, make Platform setup/status preserve owner and dependency semantics, and enforce read-only status observation across the final Real-3 deployment closeout.
+
+## 0.1.13
+
+### Patch Changes
+
+- Ship the Phase 3 browser, tunnel, model automation, platform readiness, and documentation closure as one verifiable platform snapshot.
+
 ## 0.1.12
 
 ### Patch Changes

package/DOCS.md

@@ -6,13 +6,19 @@ Execution 领域拥有的 Chrome MV3 Extension，负责 Task UI、审批提醒
 
 ## 主要能力
 
-- 提供 New Task 与 Side Panel UI、Task Observer 和 System Observer。
-- 创建、恢复和唤醒 Custom GPT Conversation，稳定观察 workerRef/c-id。
+- 运行期提供 New Task 与 Side Panel UI、Task Observer、System Observer 和 Browser Effect。
+- 运行期创建、恢复和唤醒 Custom GPT Conversation，稳定观察 workerRef/c-id。
+- 部署期通过独立 `/gpts/editor` / `/gpts/editor/*` Provisioning Surface 物化 Custom GPT；该分支不进入 Task/Worker 状态机。
+- 正常创建路径在单一 GPT Editor 会话中完成字段、Action Schema、API Key/Bearer、Knowledge ZIP、模型与 Capabilities 配置，再创建 Private GPT；不在 Create 后重新打开同一 GPT 做 Auth。
+- Knowledge Bundle 在 Mac 侧先做 ZIP traversal/大小/内部类型校验，最终向 GPT Knowledge 上传 `custom-gpt-knowledge.zip` 本体；不把解包后的 `.md` 逐文件作为正常上传物。
+- `FINALIZE_CUSTOM_GPT_AUTH` 只保留为显式 recovery/repair primitive，不属于正常 `createCustomGptRole` Golden Path。
 - 执行 DOM-first 浏览器操作，必要时使用截图与 Vision 辅助观察。
 
 ## 提供的 API 与 Public Contract
 
-- 提供 `execution-browser-executor` Contract，版本 `1.0.0`。
+- 提供 `execution-browser-executor` Contract，版本 `1.0.0`，仅用于运行期 Browser Execution。
+- 提供 `custom-gpt-web-provisioning` Contract，版本 `1.0.0`，仅用于部署期 Custom GPT Web Provisioning。
+- 两条能力只共享 Extension/loopback transport 等底层设施，不共享业务状态机。
 - 通过本地 Bridge 接收 typed Browser operation 并返回 Evidence。
 
 ## 依赖的 Module、Contract 和外部资源
@@ -26,7 +32,9 @@ Execution 领域拥有的 Chrome MV3 Extension，负责 Task UI、审批提醒
 
 ## 使用方式
 
-运行 `pnpm exec -- proflow-execution-browser-extension setup`，加载准备好的目录、登记 Extension ID、Reload 并验证 Bridge。
+运行 `platform setup --workspace <workspace> --module execution-browser-extension`。ProFlow 会先准备 unpacked 目录、运行配置和本地 Bridge，并用真实 hello + heartbeat 尝试重验证已有扩展；已有扩展仍在线时不会再次打扰用户。只有未检测到在线扩展时，ProFlow 才把正确目录复制到剪贴板并打开 `chrome://extensions/`，提示用户完成安装操作：如果开发者模式尚未开启则先开启，然后点击“加载未打包的扩展程序”，在目录选择窗口中粘贴并确认目录。完成后无需回终端输入任何标识或状态；扩展身份、session、hello/heartbeat、Browser Executor 配置和 setup evidence 都由机器自动发现、生成并验证。历史 pairing evidence 不能单独代替本次 live revalidation。
+
+若 pairing 等待超时，ProFlow 保留已经准备好的扩展文件和机器配置，不写伪 READY evidence，并输出稳定错误代码 `PAIRING_TIMEOUT`。用户确认 Chrome 已完成加载后重新执行 `platform setup` 即可。Agent setup 随后通过 `custom-gpt-web-provisioning` 使用同一 Extension package 的部署期分支。
 
 ## 职责边界与限制
 

package/SETUP.md

@@ -1,25 +1,21 @@
 # execution-browser-extension Setup
 
-## STEP-EXECUTION-BROWSER-EXTENSION-01 — 准备扩展并打开 Chrome
+## STEP-EXECUTION-BROWSER-EXTENSION-01 — 加载扩展并自动配对
 Responsible: USER
-Interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 01`
-Non-interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 01`
+Interactive executable: `platform setup --module execution-browser-extension`
+Non-interactive executable: `platform setup --module execution-browser-extension`
 Required inputs: none
-Verify: `pnpm exec -- proflow-execution-browser-extension setup 01`
-Success condition: 扩展目录已生成并可选择。
+Verify: `platform status`
+Success condition: 本地 pairing listener 已收到真实 Extension hello + heartbeat，并持久化部署证据。
 
-## STEP-EXECUTION-BROWSER-EXTENSION-02 — 登记 Extension ID 并生成配置
-Responsible: USER
-Interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 02`
-Non-interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 02 --extension-id <id>`
-Required inputs: Chrome Extension ID
-Verify: `pnpm exec -- proflow-execution-browser-extension verify`
-Success condition: Extension ID 和运行配置已保存。
+运行命令后，ProFlow 会先准备 unpacked 目录和所有机器配置，并尝试用真实 hello + heartbeat 重验证已有扩展。若已有扩展仍在线，则无需任何人工操作，setup 直接继续；只有未检测到在线扩展时，ProFlow 才把正确目录复制到剪贴板、打开 `chrome://extensions/` 并提示用户完成安装操作：如果开发者模式尚未开启则先开启，然后点击“加载未打包的扩展程序”，在目录选择窗口中粘贴并确认刚刚复制的目录。完成后无需回终端输入任何内容；扩展身份确认、Bridge 配置、hello/heartbeat 验证和 READY 状态均由 ProFlow 自动完成。历史 `setup.json` / verification evidence 不能单独跳过本次 live revalidation。
+
+若等待超时，已经准备好的扩展文件和机器配置会保留，且不会写入伪 READY evidence。用户只需确认 Chrome 中已经完成扩展加载，然后重新执行 `platform setup`；稳定错误代码为 `PAIRING_TIMEOUT`。
 
-## STEP-EXECUTION-BROWSER-EXTENSION-03 — 验证 Service Worker 与 Bridge
+## STEP-EXECUTION-BROWSER-EXTENSION-02 — 验证部署状态
 Responsible: AI
-Interactive executable: `pnpm exec -- proflow-execution-browser-extension setup 03`
-Non-interactive executable: `pnpm exec -- proflow-execution-browser-extension verify`
+Interactive executable: `platform status`
+Non-interactive executable: `platform status`
 Required inputs: none
-Verify: `pnpm exec -- proflow-execution-browser-extension verify`
+Verify: `platform status`
 Success condition: `execution-browser-extension.setupStatus=READY`.

package/dist/deployment/adapter.d.ts

@@ -7,6 +7,16 @@ export declare function materializeProductionConfig(input: {
 }): Promise<{
     loadDir: string;
 }>;
+export declare function pairBrowserExtensionSetup(context: ModuleCommandContext, options?: {
+    timeoutMs?: number;
+    onWaiting?: (input: {
+        loadDir: string;
+        endpoint: string;
+    }) => void | Promise<void>;
+}): Promise<{
+    extensionId: string;
+    extensionInstanceId: string;
+}>;
 export declare const behaviorAdapter: {
     readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
@@ -14,7 +24,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.14";
             data: {
                 loadDir: string;
             };
@@ -27,7 +37,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.14";
         };
         observedEffects: never[];
     }>;
@@ -37,10 +47,10 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.14";
             data: {
                 setupStatus: "ACTION_REQUIRED" | "READY";
-                runtimeStatus: "RUNNING" | "STOPPED";
+                runtimeStatus: "NOT_APPLICABLE";
                 issues?: {
                     scope: "SETUP";
                     code: string;
@@ -53,10 +63,19 @@ export declare const behaviorAdapter: {
         observedEffects: string[];
     }>;
     readonly setup: (context: ModuleCommandContext) => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.14";
+        };
+        observedEffects: string[];
+    } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.14";
             ok: false;
             status: "FAILED";
             error: {
@@ -66,92 +85,22 @@ export declare const behaviorAdapter: {
             };
             data: {
                 readonly steps: readonly [{
-                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-04";
-                    readonly title: "修复扩展配置";
+                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-RECOVER";
+                    readonly title: "重新加载并自动配对扩展";
                     readonly state: "BLOCKED";
                     readonly responsible: "EXTERNAL";
                     readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup";
-                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup --extension-id <id>";
+                        readonly interactive: "platform setup --module execution-browser-extension";
+                        readonly nonInteractive: "platform setup --module execution-browser-extension";
                     };
                     readonly requiredInputs: readonly [];
-                    readonly verify: "pnpm exec -- proflow-execution-browser-extension verify";
+                    readonly verify: "platform status";
                     readonly successCondition: "配置状态变为“已就绪”";
-                    readonly blockedReason: "Extension ID 或生成配置无效";
-                }];
-            };
-        };
-        observedEffects: never[];
-    } | {
-        result: {
-            contract: "deployment.result.v1";
-            moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
-            ok: false;
-            status: "ACTION_REQUIRED";
-            data: {
-                readonly steps: readonly [{
-                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-01";
-                    readonly title: "准备扩展并打开 Chrome";
-                    readonly description: "生成 unpacked 目录，复制路径并打开扩展管理页。";
-                    readonly state: "TODO";
-                    readonly responsible: "USER";
-                    readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup 01";
-                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 01";
-                    };
-                    readonly requiredInputs: readonly [];
-                    readonly verify: "pnpm exec -- proflow-execution-browser-extension setup 01";
-                    readonly successCondition: "扩展目录已生成并可选择";
-                    readonly humanAction: "启用开发者模式并选择脚本复制的目录。";
-                }, {
-                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-02";
-                    readonly title: "登记 Extension ID 并生成配置";
-                    readonly description: "保存扩展 ID，生成 Bridge 配置并提示 Reload。";
-                    readonly state: "TODO";
-                    readonly responsible: "USER";
-                    readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup 02";
-                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 02 --extension-id <id>";
-                    };
-                    readonly requiredInputs: readonly [{
-                        readonly name: "extensionId";
-                        readonly description: "Chrome Extension ID";
-                        readonly sensitive: false;
-                    }];
-                    readonly verify: "pnpm exec -- proflow-execution-browser-extension verify";
-                    readonly successCondition: "Extension ID 和运行配置已保存";
-                    readonly humanAction: "复制扩展 ID，并在配置生成后点击 Reload。";
-                }, {
-                    readonly id: "STEP-EXECUTION-BROWSER-EXTENSION-03";
-                    readonly title: "验证 Service Worker 与 Bridge";
-                    readonly description: "重新观察扩展后台和本地 Bridge。";
-                    readonly state: "TODO";
-                    readonly responsible: "AI";
-                    readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-execution-browser-extension setup 03";
-                        readonly nonInteractive: "pnpm exec -- proflow-execution-browser-extension verify";
-                    };
-                    readonly requiredInputs: readonly [];
-                    readonly verify: "pnpm exec -- proflow-execution-browser-extension verify";
-                    readonly successCondition: "execution-browser-extension.setupStatus=READY";
+                    readonly blockedReason: "真实 Extension heartbeat 未到达或本地 pairing 失败";
                 }];
             };
-            actionRequired: {
-                action: string;
-                description: string;
-            };
         };
         observedEffects: never[];
-    } | {
-        result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
-        };
-        observedEffects: string[];
     }>;
     readonly docs: (_context: ModuleCommandContext) => Promise<{
         result: {
@@ -159,7 +108,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.14";
             data: {
                 docs: string;
             };
@@ -172,11 +121,11 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.14";
         } | {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.14";
             ok: false;
             status: "FAILED";
             error: {
@@ -193,7 +142,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "execution-browser-extension";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.14";
         };
         observedEffects: never[];
     }>;

package/dist/deployment/adapter.js

@@ -3,6 +3,8 @@ import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { deterministicLoopbackPort, ensureModuleSecretFile, moduleWorkspaceStateDirectory, readModuleSharedFacts, writeModuleSharedFacts, } from "@tomflow/proflow-module-contract";
+import { runInteractiveBrowserExtensionSetup } from "../src/install-workflow.js";
+import { createBrowserExtensionPairingServer } from "../src/pairing.js";
 import { descriptor } from "./descriptor.js";
 const base = {
     contract: "deployment.result.v1",
@@ -11,75 +13,21 @@ const base = {
     moduleRef: descriptor.moduleRef,
     moduleVersion: descriptor.moduleVersion,
 };
-const setupPlan = {
-    steps: [
-        {
-            id: "STEP-EXECUTION-BROWSER-EXTENSION-01",
-            title: "准备扩展并打开 Chrome",
-            description: "生成 unpacked 目录，复制路径并打开扩展管理页。",
-            state: "TODO",
-            responsible: "USER",
-            execution: {
-                interactive: "pnpm exec -- proflow-execution-browser-extension setup 01",
-                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 01",
-            },
-            requiredInputs: [],
-            verify: "pnpm exec -- proflow-execution-browser-extension setup 01",
-            successCondition: "扩展目录已生成并可选择",
-            humanAction: "启用开发者模式并选择脚本复制的目录。",
-        },
-        {
-            id: "STEP-EXECUTION-BROWSER-EXTENSION-02",
-            title: "登记 Extension ID 并生成配置",
-            description: "保存扩展 ID，生成 Bridge 配置并提示 Reload。",
-            state: "TODO",
-            responsible: "USER",
-            execution: {
-                interactive: "pnpm exec -- proflow-execution-browser-extension setup 02",
-                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup 02 --extension-id <id>",
-            },
-            requiredInputs: [
-                {
-                    name: "extensionId",
-                    description: "Chrome Extension ID",
-                    sensitive: false,
-                },
-            ],
-            verify: "pnpm exec -- proflow-execution-browser-extension verify",
-            successCondition: "Extension ID 和运行配置已保存",
-            humanAction: "复制扩展 ID，并在配置生成后点击 Reload。",
-        },
-        {
-            id: "STEP-EXECUTION-BROWSER-EXTENSION-03",
-            title: "验证 Service Worker 与 Bridge",
-            description: "重新观察扩展后台和本地 Bridge。",
-            state: "TODO",
-            responsible: "AI",
-            execution: {
-                interactive: "pnpm exec -- proflow-execution-browser-extension setup 03",
-                nonInteractive: "pnpm exec -- proflow-execution-browser-extension verify",
-            },
-            requiredInputs: [],
-            verify: "pnpm exec -- proflow-execution-browser-extension verify",
-            successCondition: "execution-browser-extension.setupStatus=READY",
-        },
-    ],
-};
 const blockedSetupPlan = {
     steps: [
         {
-            id: "STEP-EXECUTION-BROWSER-EXTENSION-04",
-            title: "修复扩展配置",
+            id: "STEP-EXECUTION-BROWSER-EXTENSION-RECOVER",
+            title: "重新加载并自动配对扩展",
             state: "BLOCKED",
             responsible: "EXTERNAL",
             execution: {
-                interactive: "pnpm exec -- proflow-execution-browser-extension setup",
-                nonInteractive: "pnpm exec -- proflow-execution-browser-extension setup --extension-id <id>",
+                interactive: "platform setup --module execution-browser-extension",
+                nonInteractive: "platform setup --module execution-browser-extension",
             },
             requiredInputs: [],
-            verify: "pnpm exec -- proflow-execution-browser-extension verify",
+            verify: "platform status",
             successCondition: "配置状态变为“已就绪”",
-            blockedReason: "Extension ID 或生成配置无效",
+            blockedReason: "真实 Extension heartbeat 未到达或本地 pairing 失败",
         },
     ],
 };
@@ -176,7 +124,10 @@ async function readEvidence(context, loadDir) {
             raw.loadDir === loadDir &&
             typeof raw.extensionId === "string" &&
             /^[a-z]{32}$/.test(raw.extensionId) &&
+            typeof raw.extensionInstanceId === "string" &&
+            raw.extensionInstanceId.length > 0 &&
             raw.serviceWorker === "RUNNING" &&
+            raw.evidenceSource === "PAIRING_HEARTBEAT" &&
             typeof raw.observedAt === "string" &&
             !Number.isNaN(Date.parse(raw.observedAt))
             ? raw
@@ -186,28 +137,19 @@ async function readEvidence(context, loadDir) {
         return undefined;
     }
 }
-function input(context) {
-    const value = context.input;
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return {};
-    const extensionId = Reflect.get(value, "extensionId"), serviceWorker = Reflect.get(value, "serviceWorker"), observedAt = Reflect.get(value, "observedAt");
-    return {
-        ...(typeof extensionId === "string" ? { extensionId } : {}),
-        ...(serviceWorker === "RUNNING"
-            ? { serviceWorker: "RUNNING" }
-            : {}),
-        ...(typeof observedAt === "string" ? { observedAt } : {}),
-    };
-}
 async function ownFacts(context) {
     await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
     const loadDir = browserExtensionLoadDir(context.workspaceRoot);
     const bridgeTokenFile = await ensureModuleSecretFile(context, descriptor.moduleRef, "bridge");
     const bridgePort = deterministicLoopbackPort(context, descriptor.moduleRef, "bridge");
+    const provisioningBridgeTokenFile = await ensureModuleSecretFile(context, descriptor.moduleRef, "provisioning");
+    const provisioningBridgePort = deterministicLoopbackPort(context, descriptor.moduleRef, "provisioning");
     const facts = {
         loadDir,
         bridgeTokenFile,
         bridgeEndpoint: `http://127.0.0.1:${bridgePort}`,
+        provisioningBridgeTokenFile,
+        provisioningBridgeEndpoint: `http://127.0.0.1:${provisioningBridgePort}`,
         verificationEvidenceFile: verificationFile(context),
     };
     const setup = await readSetup(context);
@@ -221,7 +163,7 @@ async function ownFacts(context) {
     await writeModuleSharedFacts(context, descriptor.moduleRef, facts);
     return facts;
 }
-async function materialize(context, setup) {
+async function materializeRuntimeConfig(context) {
     const host = await readModuleSharedFacts(context, "platform-host");
     const endpoint = factString(host, "endpoint"), taskTokenFile = factString(host, "taskApplicationTokenFile"), approvalTokenFile = factString(host, "approvalApplicationTokenFile");
     if (!endpoint || !taskTokenFile || !approvalTokenFile)
@@ -230,11 +172,17 @@ async function materialize(context, setup) {
     const loadDir = String(facts.loadDir);
     const bridgeTokenFile = String(facts.bridgeTokenFile);
     const bridgeEndpoint = String(facts.bridgeEndpoint);
-    const runtimeConfig = {
+    const provisioningBridgeTokenFile = String(facts.provisioningBridgeTokenFile);
+    const provisioningBridgeEndpoint = String(facts.provisioningBridgeEndpoint);
+    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify({
         proflowRuntimeBridge: {
             endpoint: bridgeEndpoint,
             token: await credential(bridgeTokenFile),
         },
+        proflowProvisioningBridge: {
+            endpoint: provisioningBridgeEndpoint,
+            token: await credential(provisioningBridgeTokenFile),
+        },
         proflowTaskApplication: {
             endpoint,
             token: await credential(taskTokenFile),
@@ -243,15 +191,87 @@ async function materialize(context, setup) {
             endpoint,
             token: await credential(approvalTokenFile),
         },
+    }, null, 2)}\n`, { mode: 0o600 });
+    return {
+        facts,
+        loadDir,
+        bridgeTokenFile,
+        bridgeEndpoint,
+        provisioningBridgeTokenFile,
+        provisioningBridgeEndpoint,
+        endpoint,
+        taskTokenFile,
     };
-    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify(runtimeConfig, null, 2)}\n`, { mode: 0o600 });
-    await writeFile(executorConfigFile(context), `${JSON.stringify({ platformHost: { endpoint, tokenFile: taskTokenFile }, bridge: { extensionId: setup.extensionId, tokenFile: bridgeTokenFile, host: "127.0.0.1", port: Number(new URL(bridgeEndpoint).port) } }, null, 2)}\n`, { mode: 0o600 });
+}
+async function materializeExecutorConfig(context, setup, prepared) {
+    const resolved = prepared ?? (await materializeRuntimeConfig(context));
+    await writeFile(executorConfigFile(context), `${JSON.stringify({ platformHost: { endpoint: resolved.endpoint, tokenFile: resolved.taskTokenFile }, bridge: { extensionId: setup.extensionId, tokenFile: resolved.bridgeTokenFile, host: "127.0.0.1", port: Number(new URL(resolved.bridgeEndpoint).port) } }, null, 2)}\n`, { mode: 0o600 });
     await writeModuleSharedFacts(context, descriptor.moduleRef, {
-        ...facts,
+        ...resolved.facts,
         extensionId: setup.extensionId,
         browserExecutorConfigPath: executorConfigFile(context),
     });
 }
+async function persistPairedBrowserExtension(context, prepared, identity) {
+    const setup = { extensionId: identity.extensionId };
+    await writeFile(setupFile(context), `${JSON.stringify(setup, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await materializeExecutorConfig(context, setup, prepared);
+    const evidence = {
+        contract: "proflow.browser-extension-verification.v1",
+        moduleVersion: descriptor.moduleVersion,
+        loadDir: prepared.loadDir,
+        extensionId: identity.extensionId,
+        extensionInstanceId: identity.extensionInstanceId,
+        serviceWorker: "RUNNING",
+        evidenceSource: "PAIRING_HEARTBEAT",
+        observedAt: new Date().toISOString(),
+    };
+    await writeFile(verificationFile(context), `${JSON.stringify(evidence, null, 2)}\n`, { mode: 0o600 });
+    return identity;
+}
+export async function pairBrowserExtensionSetup(context, options = {}) {
+    await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
+    await installPackage(context);
+    const existingSetup = await readSetup(context);
+    const existingEvidence = await readEvidence(context, browserExtensionLoadDir(context.workspaceRoot));
+    const canRevalidateExisting = Boolean(existingSetup &&
+        existingEvidence &&
+        existingSetup.extensionId === existingEvidence.extensionId);
+    const prepared = await materializeRuntimeConfig(context);
+    const pairing = await createBrowserExtensionPairingServer({
+        token: await credential(prepared.bridgeTokenFile),
+        host: "127.0.0.1",
+        port: Number(new URL(prepared.bridgeEndpoint).port),
+        pairingTimeoutMs: options.timeoutMs ?? 120_000,
+    });
+    try {
+        const pairingPromise = pairing.waitForPairing();
+        if (canRevalidateExisting) {
+            const timeoutMs = options.timeoutMs ?? 120_000;
+            const revalidationGraceMs = Math.min(2_000, Math.max(25, Math.floor(timeoutMs / 4)));
+            const revalidated = await Promise.race([
+                pairingPromise.then((identity) => ({
+                    kind: "PAIRED",
+                    identity,
+                })),
+                new Promise((resolve) => setTimeout(() => resolve({ kind: "WAITING" }), revalidationGraceMs)),
+            ]);
+            if (revalidated.kind === "PAIRED") {
+                return persistPairedBrowserExtension(context, prepared, revalidated.identity);
+            }
+        }
+        await options.onWaiting?.({
+            loadDir: prepared.loadDir,
+            endpoint: pairing.endpoint,
+        });
+        return persistPairedBrowserExtension(context, prepared, await pairingPromise);
+    }
+    finally {
+        await pairing.close();
+    }
+}
 const failed = (code, message, retryable = true) => ({
     ...base,
     ok: false,
@@ -274,7 +294,7 @@ export const behaviorAdapter = {
         const loadDir = browserExtensionLoadDir(context.workspaceRoot);
         const setup = await readSetup(context);
         const evidence = await readEvidence(context, loadDir);
-        const setupReady = Boolean(setup && evidence);
+        const setupReady = Boolean(setup && evidence && setup.extensionId === evidence.extensionId);
         return {
             result: {
                 ...base,
@@ -282,7 +302,7 @@ export const behaviorAdapter = {
                     setupStatus: setupReady
                         ? "READY"
                         : "ACTION_REQUIRED",
-                    runtimeStatus: evidence ? "RUNNING" : "STOPPED",
+                    runtimeStatus: "NOT_APPLICABLE",
                     ...(setupReady
                         ? {}
                         : {
@@ -304,77 +324,38 @@ export const behaviorAdapter = {
         };
     },
     setup: async (context) => {
-        await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
-        const supplied = input(context);
-        let setup = await readSetup(context);
-        if (supplied.extensionId) {
-            if (!/^[a-z]{32}$/.test(supplied.extensionId))
-                return {
-                    result: {
-                        ...failed("SETUP_FAILED", "extensionId must be a canonical 32-character Chromium extension id", false),
-                        data: blockedSetupPlan,
-                    },
-                    observedEffects: [],
-                };
-            setup = { extensionId: supplied.extensionId };
-            await writeFile(setupFile(context), `${JSON.stringify(setup, null, 2)}\n`, { mode: 0o600 });
-        }
-        if (!setup)
+        try {
+            const input = typeof context.input === "object" && context.input !== null
+                ? context.input
+                : undefined;
+            await runInteractiveBrowserExtensionSetup({
+                workspaceRoot: context.workspaceRoot,
+                ...(input?.timeoutMs === undefined
+                    ? {}
+                    : { timeoutMs: input.timeoutMs }),
+                ...(input?.desktop === undefined ? {} : { desktop: input.desktop }),
+                ...(input?.pair === undefined ? {} : { pair: input.pair }),
+            });
             return {
-                result: {
-                    ...base,
-                    ok: false,
-                    status: "ACTION_REQUIRED",
-                    data: setupPlan,
-                    actionRequired: {
-                        action: "load-unpacked-extension",
-                        description: `Load ${browserExtensionLoadDir(context.workspaceRoot)} in Chrome, copy its extensionId, then run proflow-execution-browser-extension setup --extension-id <id>.`,
-                    },
-                },
-                observedEffects: [],
+                result: base,
+                observedEffects: [
+                    "Materializes browser runtime configuration",
+                    "Opens Chrome extension management",
+                    "Persists heartbeat-proven Chrome MV3 pairing evidence",
+                ],
             };
-        try {
-            await materialize(context, setup);
         }
         catch (error) {
             return {
                 result: {
                     ...failed("SETUP_FAILED", error instanceof Error
                         ? error.message
-                        : "browser extension config materialization failed"),
+                        : "browser extension setup failed"),
                     data: blockedSetupPlan,
                 },
                 observedEffects: [],
             };
         }
-        if (supplied.serviceWorker === "RUNNING") {
-            const evidence = {
-                contract: "proflow.browser-extension-verification.v1",
-                moduleVersion: descriptor.moduleVersion,
-                loadDir: browserExtensionLoadDir(context.workspaceRoot),
-                extensionId: setup.extensionId,
-                serviceWorker: "RUNNING",
-                observedAt: supplied.observedAt ?? new Date().toISOString(),
-            };
-            await writeFile(verificationFile(context), `${JSON.stringify(evidence, null, 2)}\n`, { mode: 0o600 });
-            return {
-                result: base,
-                observedEffects: ["Records real Chrome MV3 load evidence"],
-            };
-        }
-        return {
-            result: {
-                ...base,
-                ok: false,
-                status: "ACTION_REQUIRED",
-                data: setupPlan,
-                actionRequired: {
-                    action: "reload-and-verify-extension",
-                    description: "Reload the unpacked extension, confirm its MV3 service worker is RUNNING, then rerun proflow-execution-browser-extension setup --extension-id <id>.",
-                },
-            },
-            observedEffects: [],
-        };
     },
     docs: async (_context) => ({
         result: {