@nextclaw/x-harness 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,10 @@
+X Harness — Proprietary Free-Use License
+Copyright (c) 2026 Wang Pei. All rights reserved.
+
+Permission is granted, without charge, to install and use the distributed runtime and accompanying Skill for personal and commercial work. You may make backup copies and modify the Skill text for your own use.
+
+This is not an open-source license. Redistribution, resale, sublicensing, publishing modified runtime versions, or use of the runtime to provide a competing hosted product requires prior written permission from the copyright holder. No rights to the private TypeScript source repository are granted. Do not remove copyright or license notices.
+
+The software is provided "as is", without warranty. To the extent permitted by applicable law, the copyright holder is not liable for damages arising from its use. You are responsible for your account, permissions, content and compliance with the services you use. This license does not grant access to any platform, account or private data.
+
+Contact: https://x.com/XiaotiaoWang

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# X Harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Named X task APIs for browser-enabled AI agents. A reading task returns the relevant complete text and evidence; a write task records intent, submits once, verifies the public result and settles the user's ledger. Default receipts are compact; `decision` keeps complete target evidence; `delta` only returns changed evidence.
+
+Website: https://x-harness.gemigo.app/
+
+## Install and update
+
+```sh
+npx @nextclaw/x-harness@latest setup --target codex
+npx @nextclaw/x-harness@latest update --target codex
+```
+
+Requires Node.js 22+ and a compatible browser-enabled AI host. Codex desktop with CUA is the validated host. `--target claude` installs Skill text into Claude's Skill directory; the Claude host must separately provide compatible CUA tab/app methods. Installing text alone does not add browser control.
+
+The runtime lives in `~/.x-harness/runtime`; the Skill is managed in the selected host's Skill directory. Updates preserve your independent workspaces, back up the previous runtime and Skill, and refuse to overwrite unrecognized directories. Bind the new moduleURL reported by update; its versioned path refreshes the complete module graph, including in a persistent REPL. The stable CLI entry remains usable.
+
+Initialize your own workspace (use the stable CLI path reported by setup):
+
+```sh
+node ~/.x-harness/runtime/node_modules/@nextclaw/x-harness/cli/main.js init --directory ./x-workspace --account your_handle
+```
+
+Setup prints the absolute module URL and CLI path. Ask your agent to use the installed `x-harness` Skill. Your agent binds a real logged-in CUA tab once, then uses `createXGrowthHarness({ tab, ledgerPath, proofDirectory })`. It does not use your publisher's account or ledger.
+
+```js
+const { createXGrowthHarness } = await import(moduleURL);
+const x = createXGrowthHarness({ tab, ledgerPath, proofDirectory });
+const result = await x.readCreator({
+  handle: "your_handle",
+  target: 5,
+  mode: "decision",
+});
+```
+
+Read APIs: `readCreator`, `readBookmarks`, `searchSources`, `readPost`, `readPerson`, `readFeedback`, `inspectAccount`, `inspectRound`.
+Write APIs: `publishPost`, `replyToPost`, `followOne`, `followBatch`, `runGrowthRound`.
+Recovery: `verifySubmission`, `verifyPublishedPost`, `verifyFollow`.
+
+Writing requires the user's explicit task authorization, reviewed prepared actions and their own ledger plan. Initialization enables no planned writes. Current runtime windows (Asia/Shanghai): originals/follows 07:00–22:00; replies 07:00–24:00. Follow any stricter original project contract; follow quality gates currently require reviewed Chinese-language, blue-check candidates. Read tasks do not require that candidate policy. Missing browser capability, login or decision evidence is returned explicitly. Unknown submissions are verified before any further submission.
+
+Free to use under the included proprietary license. The distributed JavaScript is readable; the private TypeScript repository is not published. This is not an official X product. See `LICENSE` for permitted use.

package/cli/main.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync, cpSync, mkdtempSync, openSync, closeSync, unlinkSync, readdirSync, } from "node:fs";
+import { join, resolve, dirname, relative } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const release = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+const args = process.argv.slice(2);
+const command = args.shift() ?? "help";
+const flags = new Map();
+for (let i = 0; i < args.length; i += 2) {
+    const key = args[i], value = args[i + 1];
+    if (!["--target", "--home", "--directory", "--account"].includes(key) ||
+        !value ||
+        value.startsWith("--") ||
+        flags.has(key))
+        throw Error(`Invalid argument: ${key}`);
+    flags.set(key, value);
+}
+const customHome = flags.get("--home");
+const home = resolve(customHome ?? join(homedir(), ".x-harness"));
+const readJSON = (path) => JSON.parse(readFileSync(path, "utf8"));
+const output = (value) => process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+const marker = (path, file) => existsSync(join(path, file)) &&
+    [release.name, "@peiiii/x-harness"].includes(readJSON(join(path, file)).managedBy);
+function guard(path, file) {
+    if (existsSync(path) &&
+        (lstatSync(path).isSymbolicLink() || !marker(path, file)))
+        throw Error(`Refusing to overwrite unmanaged directory: ${path}`);
+}
+function skillPath(target) {
+    if (!["codex", "claude"].includes(target))
+        throw Error("Target must be codex or claude");
+    return customHome
+        ? join(home, "skills", target, "x-harness")
+        : join(homedir(), `.${target}`, "skills", "x-harness");
+}
+function location() {
+    return {
+        version: release.version,
+        moduleURL: pathToFileURL(join(packageRoot, "dist", "index.js")).href,
+        cliPath: fileURLToPath(import.meta.url),
+        home,
+    };
+}
+function stageRuntime(stage, runtime) {
+    const stagedRuntime = join(stage, "runtime");
+    const suffix = join("versions", release.version, "node_modules", ...release.name.split("/"));
+    const installedRoot = join(stagedRuntime, suffix);
+    cpSync(packageRoot, installedRoot, { recursive: true });
+    if (readJSON(join(installedRoot, "package.json")).version !== release.version)
+        throw Error("Installed version mismatch");
+    const finalRoot = join(runtime, suffix);
+    const stableRoot = join(stagedRuntime, "node_modules", ...release.name.split("/"));
+    const stableCLI = join(runtime, "node_modules", ...release.name.split("/"), "cli", "main.js");
+    mkdirSync(join(stableRoot, "cli"), { recursive: true });
+    writeFileSync(join(stableRoot, "package.json"), JSON.stringify({ type: "module" }));
+    const entry = relative(dirname(stableCLI), join(finalRoot, "cli", "main.js"))
+        .split("\\")
+        .join("/");
+    writeFileSync(join(stableRoot, "cli", "main.js"), `#!/usr/bin/env node\nawait import(new URL(${JSON.stringify(entry)}, import.meta.url));\n`);
+    return { stagedRuntime, installedRoot, finalRoot, stableCLI };
+}
+function setup() {
+    const target = flags.get("--target") ?? "codex";
+    const stateFile = join(home, "installation.json");
+    if (!existsSync(stateFile) &&
+        readdirSync(home).some((name) => name !== ".installation.lock"))
+        throw Error(`Unmanaged installation home: ${home}`);
+    const previous = existsSync(stateFile)
+        ? readJSON(stateFile)
+        : { managedBy: release.name, targets: [] };
+    if (![release.name, "@peiiii/x-harness"].includes(previous.managedBy))
+        throw Error("Unmanaged installation state");
+    const targets = [...new Set([...previous.targets, target])];
+    const runtime = join(home, "runtime");
+    guard(runtime, ".x-harness-managed.json");
+    for (const t of targets)
+        guard(skillPath(t), ".x-harness-managed.json");
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const stage = mkdtempSync(join(home, ".setup-"));
+    const backup = join(home, "backups", `${Date.now()}-${randomUUID()}`);
+    const changes = [];
+    let completed = false;
+    try {
+        // Persist npx's already fetched runtime once; versioned URLs invalidate the whole module graph.
+        const { stagedRuntime, installedRoot, finalRoot, stableCLI } = stageRuntime(stage, runtime);
+        const metadata = { managedBy: release.name, version: release.version };
+        writeFileSync(join(stagedRuntime, ".x-harness-managed.json"), JSON.stringify(metadata));
+        const installs = [{ src: stagedRuntime, dest: runtime, key: "runtime" }];
+        for (const t of targets) {
+            const stagedSkill = join(stage, `skill-${t}`);
+            cpSync(join(installedRoot, "skill"), stagedSkill, { recursive: true });
+            const content = readFileSync(join(stagedSkill, "SKILL.md"), "utf8")
+                .replaceAll("{{MODULE_URL}}", pathToFileURL(join(finalRoot, "dist", "index.js")).href)
+                .replaceAll("{{CLI_PATH}}", stableCLI);
+            writeFileSync(join(stagedSkill, "SKILL.md"), content);
+            writeFileSync(join(stagedSkill, ".x-harness-managed.json"), JSON.stringify(metadata));
+            installs.push({
+                src: stagedSkill,
+                dest: skillPath(t),
+                key: `skill-${t}`,
+            });
+        }
+        // Install/download succeeds before replacing either managed artifact.
+        for (const item of installs) {
+            const saved = join(backup, item.key), hadOld = existsSync(item.dest);
+            mkdirSync(dirname(item.dest), { recursive: true });
+            if (hadOld) {
+                mkdirSync(backup, { recursive: true });
+                renameSync(item.dest, saved);
+            }
+            changes.push({ dest: item.dest, backup: saved, hadOld });
+            renameSync(item.src, item.dest);
+        }
+        const state = { ...metadata, targets, updatedAt: new Date().toISOString() };
+        const nextState = join(stage, "installation.json");
+        writeFileSync(nextState, JSON.stringify(state, null, 2));
+        renameSync(nextState, stateFile);
+        completed = true;
+        output({
+            status: "installed",
+            ...state,
+            moduleURL: pathToFileURL(join(finalRoot, "dist", "index.js")).href,
+            cliPath: stableCLI,
+            skillPaths: targets.map(skillPath),
+            backup: changes.some((c) => c.hadOld) ? backup : null,
+            next: "Start a fresh module binding using the installed x-harness Skill.",
+        });
+    }
+    finally {
+        if (!completed)
+            for (const change of changes.reverse()) {
+                rmSync(change.dest, { recursive: true, force: true });
+                if (change.hadOld)
+                    renameSync(change.backup, change.dest);
+            }
+        rmSync(stage, { recursive: true, force: true });
+    }
+}
+function init() {
+    const directory = resolve(flags.get("--directory") ?? "./x-workspace");
+    const account = (flags.get("--account") ?? "").replace(/^@/, "");
+    if (!/^[a-zA-Z0-9_]{1,15}$/.test(account))
+        throw Error("Provide your own X handle with --account");
+    const configPath = join(directory, "x-harness.json");
+    if (existsSync(configPath)) {
+        const config = readJSON(configPath);
+        if (config.accountHandle !== account)
+            throw Error("Existing workspace belongs to a different account");
+        output({ status: "existing", configPath, ...config });
+        return;
+    }
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const ledgerPath = join(directory, "round.md"), proofDirectory = join(directory, "proofs");
+    if (existsSync(ledgerPath))
+        throw Error("Existing ledger is unmanaged; use its configuration instead of overwriting");
+    const taskId = `x-${randomUUID()}`;
+    const state = {
+        batchId: taskId,
+        status: "RUNNING",
+        updatedAt: new Date().toISOString(),
+        accountHandle: account,
+        items: ["follow", "original", "reply"].map((kind) => ({
+            kind,
+            planned: 0,
+            verified: 0,
+            unknown: 0,
+            actionable: true,
+        })),
+        execution: { owner: "harness", exclusive: true },
+        attempts: [],
+        actions: [],
+    };
+    mkdirSync(proofDirectory);
+    writeFileSync(ledgerPath, `# @${account} · Your X workspace\n\n\`\`\`x-round-state\n${JSON.stringify(state, null, 2)}\n\`\`\`\n`, { flag: "wx", mode: 0o600 });
+    const config = { accountHandle: account, taskId, ledgerPath, proofDirectory };
+    writeFileSync(configPath, JSON.stringify(config, null, 2), {
+        flag: "wx",
+        mode: 0o600,
+    });
+    output({ status: "initialized", configPath, ...config });
+}
+try {
+    if (["setup", "update"].includes(command)) {
+        mkdirSync(home, { recursive: true, mode: 0o700 });
+        const lockPath = join(home, ".installation.lock");
+        const lock = openSync(lockPath, "wx", 0o600);
+        try {
+            setup();
+        }
+        finally {
+            closeSync(lock);
+            unlinkSync(lockPath);
+        }
+    }
+    else if (command === "init")
+        init();
+    else if (command === "location")
+        output(location());
+    else if (command === "help")
+        output({
+            setup: "npx @nextclaw/x-harness@latest setup --target codex",
+            update: "npx @nextclaw/x-harness@latest update --target codex",
+            init: "node <cliPath> init --directory ./x-workspace --account YOUR_HANDLE",
+            targets: ["codex", "claude"],
+            requires: "Node 22+; compatible CUA browser host and your own X login",
+        });
+    else
+        throw Error(`Unknown command: ${command}`);
+}
+catch (error) {
+    process.stderr.write(JSON.stringify({
+        status: "failed",
+        reason: error instanceof Error ? error.message : String(error),
+    }) + "\n");
+    process.exitCode = 1;
+}

package/dist/api.d.ts

@@ -0,0 +1,10 @@
+import type { XGrowthHarness } from "./types.js";
+import type { BoundaryRecord } from "./boundary.js";
+/** Internal dependencies; only the normal X factory is exported from the root. */
+export interface BusinessDependencies {
+    platform: BoundaryRecord;
+    store: import("./store.js").RoundStore;
+    clock?: () => number;
+    executor?: BoundaryRecord;
+}
+export declare function createBusinessHarness(dependencies: BusinessDependencies): XGrowthHarness;

package/dist/api.js

@@ -0,0 +1,308 @@
+import { createGrowthHarness } from "./growth.js";
+import { readResult, decisions, diagnostic, stableReason } from "./results.js";
+export function createBusinessHarness(dependencies) {
+    const { store } = dependencies;
+    const core = createGrowthHarness(dependencies);
+    const readCache = new Map();
+    // All public operations share the same error boundary. Full errors remain local proof.
+    async function invoke(operation, args) {
+        try {
+            const raw = await core[operation](args);
+            // Legacy core decisions can contain a human error without a diagnostic proof.
+            // Expose a bounded recovery route; consumers never need implementation source.
+            const errors = [
+                raw.reason,
+                ...(raw.decision ?? []).flatMap((d) => [
+                    d.reason,
+                    d.error,
+                ]),
+            ].filter((reason) => typeof reason === "string" && stableReason(reason) !== reason);
+            if (errors.length) {
+                const evidenceRef = await store.recordProof({
+                    operation,
+                    error: errors[0],
+                    ...(errors.length > 1 ? { errors } : {}),
+                });
+                return {
+                    ...raw,
+                    ...(raw.reason ? { reason: stableReason(raw.reason) } : {}),
+                    evidenceRef,
+                    ...(raw.decision
+                        ? {
+                            decision: raw.decision.map((d) => ({
+                                ...d,
+                                reason: stableReason(d.reason),
+                            })),
+                        }
+                        : {}),
+                    diagnostic: {
+                        operation,
+                        category: "boundary",
+                        code: "harness-boundary-error",
+                        next: "inspect-local-proof",
+                        evidenceRef,
+                    },
+                };
+            }
+            return raw;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            let evidenceRef;
+            try {
+                evidenceRef = await store.recordProof({ operation, error: message });
+            }
+            catch {
+                /* Evidence failure is explicit below. */
+            }
+            return {
+                status: "needsDecision",
+                boundaryFailed: true,
+                fresh: false,
+                complete: false,
+                reason: evidenceRef
+                    ? stableReason(message)
+                    : "evidence-store-unavailable",
+                ...(evidenceRef
+                    ? { evidenceRef }
+                    : { missing: ["local-proof-unavailable"] }),
+                diagnostic: {
+                    operation,
+                    category: "boundary",
+                    code: evidenceRef
+                        ? "harness-boundary-error"
+                        : "evidence-store-unavailable",
+                    next: evidenceRef ? "inspect-local-proof" : "restore-proof-store",
+                    ...(evidenceRef ? { evidenceRef } : {}),
+                },
+            };
+        }
+    }
+    async function read(operation, args = {}, mode = "receipt") {
+        if (!["receipt", "decision", "delta"].includes(mode))
+            return {
+                status: "needsDecision",
+                complete: false,
+                reason: "read-mode-invalid",
+            };
+        // Always collect fresh evidence once. Projection, not a second browser call, chooses output.
+        const raw = await invoke(operation, { ...args, mode: "decision" });
+        const output = readResult(operation, raw, mode);
+        if (mode === "receipt")
+            return output;
+        const collection = output.sources ??
+            output.feedback ??
+            (output.post ? [output.post] : output.person ? [output.person] : []);
+        const changed = [], unchangedIds = [];
+        for (const entry of collection) {
+            const id = "id" in entry ? entry.id : "handle" in entry ? entry.handle : null;
+            if (!id) {
+                changed.push(entry);
+                continue;
+            }
+            const key = JSON.stringify([operation, id]), value = JSON.stringify(entry);
+            if (readCache.get(key) === value)
+                unchangedIds.push(id);
+            else
+                changed.push(entry);
+            readCache.set(key, value);
+        }
+        // Creator metadata changes independently from the post collection.
+        if (operation === "readCreator") {
+            for (const name of ["person", "creator"]) {
+                if (!output[name])
+                    continue;
+                const key = JSON.stringify([operation, name, args.handle]);
+                const value = JSON.stringify(output[name], (k, v) => k === "observedAt" ? undefined : v);
+                if (mode === "delta" && readCache.get(key) === value)
+                    delete output[name];
+                readCache.set(key, value);
+            }
+        }
+        // A decision has delivered complete evidence and seeds the next delta.
+        if (mode === "decision")
+            return output;
+        if (output.sources)
+            output.sources = changed;
+        if (output.feedback)
+            output.feedback = changed;
+        if (output.post && !changed.length)
+            delete output.post;
+        if (operation !== "readCreator" && output.person && !changed.length)
+            delete output.person;
+        output.unchangedIds = unchangedIds;
+        return output;
+    }
+    async function compactRound(operation, args) {
+        const raw = await invoke(operation, args);
+        const out = {
+            status: raw.status,
+            taskId: args.taskId,
+            mayEnd: raw.mayEnd === true,
+        };
+        if (raw.scopeKinds)
+            out.scopeKinds = raw.scopeKinds;
+        if (raw.actual)
+            out.actual = Object.fromEntries(Object.entries(raw.actual).map(([kind, v]) => {
+                const counts = v;
+                return [kind, { verified: counts.verified, unknown: counts.unknown }];
+            }));
+        if (raw.gaps)
+            out.gaps = raw.gaps.map((v) => ({
+                kind: v.kind,
+                remaining: v.remaining,
+                unknown: v.unknown,
+            }));
+        const issues = decisions(raw.decision);
+        if (issues.length)
+            out.decision = issues;
+        if (raw.evidenceRef)
+            out.evidenceRef = raw.evidenceRef;
+        const d = diagnostic(raw.diagnostic);
+        if (d)
+            out.diagnostic = d;
+        if (Array.isArray(raw.settlementErrors))
+            out.settlementErrors = raw.settlementErrors
+                .map(stableReason)
+                .filter((v) => v !== undefined);
+        if (raw.reason)
+            out.decision = [
+                ...(out.decision ?? []),
+                { reason: stableReason(raw.reason), status: "needsDecision" },
+            ];
+        if (raw.missing)
+            out.decision = [...(out.decision ?? []), { missing: raw.missing }];
+        if (raw.checkpoint)
+            out.checkpoint = {
+                taskId: args.taskId,
+                executorId: raw.checkpoint.executorId,
+                completed: raw.checkpoint.completed,
+                resume: "runGrowthRound",
+            };
+        return out;
+    }
+    async function single(operation, args, selector) {
+        const raw = await invoke(operation, args);
+        let snapshot;
+        try {
+            snapshot = await store.load();
+        }
+        catch {
+            return {
+                status: "needsDecision",
+                taskId: args.taskId,
+                reason: "original-ledger-unavailable",
+                evidenceRef: raw.evidenceRef,
+            };
+        }
+        if (snapshot.state.batchId !== args.taskId)
+            return {
+                status: "needsDecision",
+                taskId: args.taskId,
+                reason: "original-task-id-required",
+                evidenceRef: raw.evidenceRef,
+            };
+        const action = snapshot.state.actions?.find(selector);
+        const issues = decisions(raw.decision);
+        const issue = issues.find((d) => d.actionId === action?.id) ??
+            issues.find((d) => !d.actionId);
+        const unresolved = action && ["intent", "unknown"].includes(action.status);
+        const status = unresolved
+            ? "unknown"
+            : raw.boundaryFailed
+                ? "needsDecision"
+                : issue?.status === "waiting" || raw.status === "waiting"
+                    ? "waiting"
+                    : raw.status === "needsCapability"
+                        ? "needsCapability"
+                        : action &&
+                            ["verified", "preexisting", "skipped"].includes(action.status)
+                            ? action.status
+                            : "needsDecision";
+        const out = { status, taskId: args.taskId };
+        if (action?.id)
+            out.actionId = action.id;
+        if (action?.publicId) {
+            out.publicId = action.publicId;
+            out.publicURL = `https://x.com/${action.accountHandle}/status/${action.publicId}`;
+        }
+        const evidenceRef = action?.resultEvidence ?? raw.evidenceRef;
+        if (evidenceRef)
+            out.evidenceRef = evidenceRef;
+        const reason = stableReason(issue?.reason ?? raw.reason);
+        if (reason)
+            out.reason = reason;
+        if (issue?.resumeAt)
+            out.resumeAt = issue.resumeAt;
+        const missing = issue?.missing ?? raw.missing;
+        if (Array.isArray(missing) && missing.length)
+            out.missing = missing;
+        if (unresolved && !evidenceRef)
+            out.missing = [
+                ...new Set([...(out.missing ?? []), "result-proof-unavailable"]),
+            ];
+        const d = diagnostic(raw.diagnostic);
+        if (d)
+            out.diagnostic = d;
+        return out;
+    }
+    return {
+        readCreator: (args) => read("readCreator", args, args.mode),
+        readBookmarks: (args) => read("readBookmarks", args, args.mode),
+        searchSources: (args) => read("searchSources", args, args.mode),
+        readPost: ({ target, mode }) => read("readPost", target, mode),
+        readPerson: ({ target, mode }) => read("readPerson", target, mode),
+        readFeedback: (args) => read("readFeedback", args, args.mode),
+        inspectAccount: (args = {}) => read("inspectAccount", args, args.mode),
+        inspectRound: (args) => compactRound("inspectRound", args),
+        runGrowthRound: (args) => compactRound("runGrowthRound", args),
+        publishPost: (args) => single("publishPost", args, (a) => a.kind === "original" && a.draftPath === args.draftPath),
+        replyToPost: (args) => single("replyToPost", args, (a) => a.kind === "reply" &&
+            a.postId === args.postId &&
+            a.text === args.text),
+        followOne: (args) => single("followOne", args, (a) => a.kind === "follow" &&
+            a.handle?.toLowerCase() === args.handle.toLowerCase()),
+        verifySubmission: (args) => single("verifySubmission", args, (a) => a.id === args.actionId),
+        verifyPublishedPost: (args) => single("verifyPublishedPost", args, (a) => a.kind === "original" && a.draftPath === args.draftPath),
+        followBatch: async (args) => {
+            const raw = await invoke("followBatch", args);
+            const output = {
+                status: raw.status ?? (raw.mayEnd ? "verified" : "needsDecision"),
+                taskId: args.taskId,
+                planned: raw.planned ?? args.handles.length,
+                attempted: raw.attempted ?? 0,
+                verified: raw.verifiedThisCall ?? 0,
+                unknown: raw.unknownInBatch ?? 0,
+                remaining: raw.remaining ?? args.handles.length,
+                mayEnd: raw.mayEnd === true,
+            };
+            if (raw.batchId)
+                output.batchId = raw.batchId;
+            if (raw.evidenceRef)
+                output.evidenceRef = raw.evidenceRef;
+            const d = diagnostic(raw.diagnostic);
+            if (d)
+                output.diagnostic = d;
+            const issues = decisions(raw.decision);
+            if (raw.reason)
+                issues.push({ reason: raw.reason, status: "needsDecision" });
+            if (raw.missing)
+                issues.push({ missing: raw.missing });
+            if (issues.length)
+                output.decision = issues;
+            return output;
+        },
+        verifyFollow: async (args) => {
+            const raw = await invoke("verifyFollow", {
+                ...args,
+                mode: args.mode ?? "receipt",
+            });
+            const out = readResult("verifyFollow", raw, "receipt");
+            out.handle = args.handle;
+            out.verified = raw.verified === true;
+            if (args.mode === "decision" && raw.observation)
+                out.person = readResult("readPerson", raw.observation, "decision").person;
+            return out;
+        },
+    };
+}

package/dist/boundary.d.ts

@@ -0,0 +1,2 @@
+/** Internal dynamic UI/ledger boundary. Public business contracts are separately typed. */
+export type BoundaryRecord = Record<string, any>;

package/dist/browser-common.d.ts

@@ -0,0 +1,4 @@
+export declare const plain: (label: any) => any;
+export declare const valueOf: (label: any) => any;
+export declare const missingMethods: (object: any, names: any) => any;
+export declare function serialized(port: any): any;

package/dist/browser-common.js

@@ -0,0 +1,29 @@
+export const plain = (label) => label.replace(/^(?:按钮|link|文本输入区域|文本输入区|文本区域|文本栏) /, "");
+export const valueOf = (label) => label.match(/, Value: ([\s\S]*)$/)?.[1] ?? null;
+export const missingMethods = (object, names) => names.filter((name) => typeof object?.[name] !== "function");
+export function serialized(port) {
+    let busy = false;
+    const run = async (fn) => {
+        if (busy)
+            throw new Error("浏览器harness操作进行中，禁止并发");
+        busy = true;
+        try {
+            return await fn();
+        }
+        finally {
+            busy = false;
+        }
+    };
+    return {
+        ...port,
+        observe: (query) => run(() => port.observe(query)),
+        act: (command) => run(() => port.act(command)),
+        screenshot: () => run(() => port.screenshot()),
+        ...(port.collectCreator
+            ? {
+                collectCreator: (args) => run(() => port.collectCreator(args)),
+            }
+            : {}),
+    };
+}
+// AX indices never cross this port. Only semantic commands reach the platform layer.

package/dist/browser-dom-capabilities.d.ts

@@ -0,0 +1,4 @@
+import type { DOMDependencies } from "./browser-dom-dependencies.js";
+export declare function createDOMCapabilities(dependencies: Pick<DOMDependencies, "tab" | "nativeSubmit">): {
+    capabilities(operation: any): any;
+};