@nextclaw/x-harness 0.1.0 → 0.1.1

package/dist/readers-profile.js

@@ -0,0 +1,157 @@
+// Profile selectors are the visible controls observed in the live X workflow.
+// Missing/ambiguous counters remain unknown; rounded counts carry their precision.
+export function readProfile({ handle } = {}) {
+    if (!/^[A-Za-z0-9_]{1,15}$/.test(handle ?? ""))
+        throw new Error("需要已观察的X handle");
+    const visible = (el) => el.getClientRects().length > 0;
+    const main = document.querySelector("main");
+    if (!main)
+        return {
+            handle,
+            blue: null,
+            relationship: "unknown",
+            alerts: ["missing-main"],
+            observedAt: new Date().toISOString(),
+        };
+    const buttons = Array.from(main.querySelectorAll("button")).filter(visible);
+    const labels = buttons.map((b) => b.getAttribute("aria-label") || b.innerText);
+    const relationship = labels.includes(`正在关注 @${handle}`) ||
+        labels.includes(`取消关注 @${handle}`)
+        ? "following"
+        : labels.includes(`回关 @${handle}`)
+            ? "follows-you"
+            : labels.includes(`关注 @${handle}`)
+                ? "not-following"
+                : "unknown";
+    const badges = buttons
+        .filter((b) => b.getAttribute("aria-label") === "提供已验证账号的详细信息。")
+        .map((b) => b.querySelector("svg"))
+        .filter(Boolean);
+    const blue = badges.length === 1
+        ? [
+            getComputedStyle(badges[0]).color,
+            getComputedStyle(badges[0]).fill,
+        ].includes("rgb(29, 155, 240)")
+        : null;
+    const links = Array.from(main.querySelectorAll("a[href]")).filter(visible);
+    const counter = (suffixes) => {
+        const matched = links.filter((a) => suffixes.some((s) => a.getAttribute("href")?.toLowerCase() ===
+            `/${handle}/${s}`.toLowerCase()));
+        const texts = [...new Set(matched.map((a) => a.innerText.trim()))];
+        if (texts.length !== 1)
+            return { value: null, text: texts, precision: "unknown" };
+        const match = texts[0].match(/^([\d,.]+)\s*(万|亿|[KMB])?/i);
+        const factors = {
+            万: 1e4,
+            亿: 1e8,
+            K: 1e3,
+            M: 1e6,
+            B: 1e9,
+        };
+        const value = match
+            ? Number(match[1].replaceAll(",", "")) *
+                (factors[match[2]?.toUpperCase()] ?? 1)
+            : null;
+        const hrefs = [...new Set(matched.map((a) => a.getAttribute("href")))];
+        return {
+            value: Number.isFinite(value) ? value : null,
+            text: texts[0],
+            precision: match?.[2] ? "rounded" : "exact",
+            url: hrefs.length === 1 ? "https://x.com" + hrefs[0] : null,
+        };
+    };
+    return {
+        handle,
+        blue,
+        relationship,
+        relationshipControls: labels
+            .filter((label) => label.includes("@" + handle) || /取消关注|订阅/.test(label))
+            .slice(0, 5),
+        biography: main.querySelector('[data-testid="UserDescription"]')
+            ?.innerText ?? null,
+        following: counter(["following"]),
+        followers: counter(["followers", "verified_followers"]),
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((a) => a.innerText),
+        observedAt: new Date().toISOString(),
+    };
+}
+// Bounded visible person cells for a currently loaded follower/following list.
+export function readPeople({ offset = 0, limit = 5 } = {}) {
+    if (!Number.isInteger(offset) ||
+        offset < 0 ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 5)
+        throw new Error("人物窗口须为非负offset及1–5 limit");
+    const visible = (el) => el.getClientRects().length > 0;
+    const cells = Array.from(document.querySelectorAll('main [data-testid="UserCell"]')).filter(visible);
+    const people = cells.slice(offset, offset + limit).map((cell) => {
+        const links = Array.from(cell.querySelectorAll("a[href]"))
+            .filter(visible)
+            .map((a) => ({ text: a.innerText, href: a.getAttribute("href") }));
+        const buttons = Array.from(cell.querySelectorAll("button"))
+            .filter(visible)
+            .map((b) => ({
+            label: b.getAttribute("aria-label") || b.innerText,
+            disabled: b.disabled,
+        }));
+        return { text: cell.innerText, links, buttons };
+    });
+    return {
+        page: location.href,
+        people,
+        offset,
+        renderedPeople: cells.length,
+        moreInDOM: offset + limit < cells.length,
+        pageComplete: false,
+        needsStateCheck: !people.length,
+        missing: people.length ? [] : ["people-cells-not-found"],
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((a) => a.innerText),
+        observedAt: new Date().toISOString(),
+    };
+}
+// This ranks observed clues, never a predicted follow-back probability.
+export function screenCandidates(profiles, { minRatio = 0.8 } = {}) {
+    if (!Array.isArray(profiles) || !Number.isFinite(minRatio) || minRatio <= 0)
+        throw new Error("profiles数组和正minRatio必填");
+    const seen = new Set();
+    return profiles
+        .map((p) => {
+        const key = String(p.handle ?? "").toLowerCase();
+        const duplicate = seen.has(key);
+        seen.add(key);
+        const following = p.following?.value, followers = p.followers?.value;
+        const ratio = Number.isFinite(following) &&
+            Number.isFinite(followers) &&
+            followers > 0
+            ? following / followers
+            : null;
+        const clues = [];
+        if (typeof p.mutualEvidence === "string" && p.mutualEvidence.trim())
+            clues.push({ kind: "explicit-mutual", evidence: p.mutualEvidence });
+        if (ratio !== null && ratio >= minRatio)
+            clues.push({
+                kind: "following-ratio",
+                ratio,
+                following: p.following,
+                followers: p.followers,
+                evidence: "关注/粉丝比例线索，非回关概率",
+            });
+        const rejected = [
+            duplicate && "duplicate",
+            p.blue !== true && "blue-unconfirmed",
+            p.relationship !== "not-following" && "relationship-ineligible",
+            p.alerts?.length && "page-alert",
+            !clues.length && "no-followback-clue",
+            !/^[A-Za-z0-9_]{1,15}$/.test(p.handle ?? "") && "invalid-handle",
+        ].filter(Boolean);
+        return { ...p, ratio, clues, eligible: rejected.length === 0, rejected };
+    })
+        .sort((a, b) => Number(b.eligible) - Number(a.eligible) ||
+        Number(b.clues.some((c) => c.kind === "explicit-mutual")) -
+            Number(a.clues.some((c) => c.kind === "explicit-mutual")));
+}

package/dist/readers.d.ts

@@ -1,20 +1,9 @@
-export declare function readPosts({ offset, limit, targetId, }?: any): any;
-export declare function changes(result: any, cache: any, page: any, fresh?: any): any;
-export declare function readAX(state: any, { mode, offset, limit, targetId, targetHandle, }?: any): any;
-export declare function createAXTabHarness(tab: any): any;
-export declare function createAXHarness(app: any): any;
-export declare function setupCode(): any;
-export declare function readProfile({ handle }?: any): any;
-export declare function readPeople({ offset, limit }?: any): any;
-export declare function readComposer(): any;
-export declare function readMenu(): any;
-export declare function readNavigation({ targetLabel }?: any): any;
-export declare function readMediaEditor(): any;
-export declare function attachImage(tab: any, { path }?: any): Promise<any>;
-export declare function openReply(tab: any, { postId }?: any): Promise<any>;
-export declare function screenCandidates(profiles: any, { minRatio }?: any): any;
-export declare function profileCode({ tab, handle }?: any): any;
-export declare function profilesCode(entries: any): any;
-export declare function browserCode({ handle, offset, limit, targetId, fresh, }?: any): any;
-export declare function axCode({ handle, mode, offset, limit, targetId, targetHandle, fresh, }?: any): any;
-export declare function runReaderCLI(): void;
+/** Compatibility exports only. Implementation owners are task-specific modules. */
+export { readPosts, changes } from "./readers-posts.js";
+export { readAX } from "./readers-ax-parser.js";
+export { createAXTabHarness, createAXHarness } from "./readers-ax-host.js";
+export { readProfile, readPeople, screenCandidates, } from "./readers-profile.js";
+export { readComposer, readMediaEditor } from "./readers-composer.js";
+export { readMenu, readNavigation } from "./readers-navigation.js";
+export { attachImage, openReply } from "./readers-actions.js";
+export { setupCode, profileCode, profilesCode, browserCode, axCode, runReaderCLI, } from "./readers-cli.js";

package/dist/results.js

@@ -21,7 +21,7 @@ export function diagnostic(value) {
     if (typeof raw.code !== "string")
         return undefined;
     return {
-        ...pick(raw, ["operation", "category"]),
+        ...pick(raw, ["operation", "category", "next", "evidenceRef"]),
         code: stableReason(raw.code),
     };
 }

package/dist/round-state.js

@@ -109,8 +109,8 @@ export function checkRound(state, { now = Date.now(), evidenceExists = existsSyn
                         reply.unknown, "未提交欠量仍在；未知提交不能冻结新对象");
             if (exit.reason === "outside-window") {
                 const shanghaiHour = (new Date(now).getUTCHours() + 8) % 24;
-                require(shanghaiHour < 7 ||
-                    shanghaiHour >= 22, "仍在上海07至22点执行窗口，不能以时段截止结束");
+                require(shanghaiHour <
+                    7, "仍在上海07至24点评论执行窗口，不能以时段截止结束");
             }
             if (exit.reason === "user-stop")
                 require(typeof exit.instructionEvidenceRef === "string" &&

package/dist/types.d.ts

@@ -75,6 +75,8 @@ export interface Diagnostic {
     operation?: string;
     category?: string;
     code: string;
+    next?: "inspect-local-proof" | "restore-proof-store";
+    evidenceRef?: EvidenceRef;
 }
 export interface ReadResult {
     status: "observed" | "needsDecision" | "needsCapability";
@@ -196,6 +198,7 @@ export interface ActionResult {
     diagnostic?: Diagnostic;
 }
 export interface RoundResult {
+    diagnostic?: Diagnostic;
     status: string;
     taskId: string;
     mayEnd: boolean;
@@ -220,6 +223,7 @@ export interface RoundResult {
     };
 }
 export interface BatchResult {
+    diagnostic?: Diagnostic;
     status: string;
     taskId: string;
     batchId?: string;
@@ -265,6 +269,12 @@ export interface IndependentExecution {
     tabId: string;
     evidenceRef: EvidenceRef;
     scopeEvidenceRef: EvidenceRef;
+    windowAuthorization?: {
+        actionId: string;
+        userAuthorized: true;
+        expiresAt: string;
+        evidenceRef: EvidenceRef;
+    };
 }
 export interface PublishOptions {
     taskId: string;

package/generated/observation.mjs

@@ -487,7 +487,8 @@ export const readXObservation = (query) => {
                             const read = (node) => {
                                 if (node.nodeType === 3)
                                     return node.textContent ?? "";
-                                if (node.nodeType === 1 && node.tagName === "A") {
+                                if (node.nodeType === 1 &&
+                                    node.tagName === "A") {
                                     const href = node.getAttribute("href") ?? "";
                                     if (/^\/\w{1,15}\/status\/\d+$/.test(href))
                                         return `https://x.com${href}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/x-harness",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "X tasks for browser-enabled AI agents: compact results, complete evidence and verified writes.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/skill/SKILL.md

@@ -1,52 +1,33 @@
 ---
 name: x-harness
-version: 0.1.0
-description: Use X through named task APIs with compact receipts, complete target evidence and verified writes. Requires a compatible CUA browser host and the user's own logged-in X account. Install and update with the npm-distributed X Harness runtime.
+version: 0.1.1
+description: Use X through task APIs with compact receipts, complete target evidence and verified writes; requires compatible CUA and the user's X login.
 ---
 
 # X Harness
 
-Use the installed runtime; normal tasks call its root business API. Do not recreate browser selectors, print full DOM/AX, or call lower layers for normal work. Keep observations local and only return the relevant complete evidence, receipt and actionable warnings.
+Use the root business API. Load only the current task reference; reuse unchanged instructions and a valid binding. Normal use needs no implementation source or type-file reading.
 
-## First use
+## Bind once
 
-Installed module: `{{MODULE_URL}}`
-CLI: `{{CLI_PATH}}`
+Read current host CUA documentation; bind a real logged-in `tab` or native `app`, exactly one. Preserve other tasks' tabs/editors.
 
-If these placeholders are unresolved, install first:
-`npx @nextclaw/x-harness@latest setup --target codex` (or `--target claude`).
-
-Requires Node 22+, a host that exposes compatible CUA `tab` or native `app` methods, and the user's own X login. Codex desktop CUA is validated. Installing this Skill into Claude only installs instructions; confirm that host's browser methods before claiming it can execute. If browser access/login is absent, report the actual missing condition; never fabricate execution or borrow the publisher's account.
-
-Read the host's CUA documentation before using its controls. Bind/create a task tab through the host's documented API, preserving the user's session. A compatible tab has `url()`, `playwright.evaluate()`, locator methods and optional navigation/AX/screenshot methods; native apps have `getAXState()`, click/key/paste methods. Use the provided connection; do not launch an unrelated automation driver.
-
-Initialize the user's own workspace once with `node <CLI> init --directory <user workspace> --account <user handle>`. It returns `ledgerPath`, `proofDirectory`, `taskId` and account. Existing project configurations and ledgers remain the owner; reuse those instead of creating duplicate state. Never import the publisher's operations directories, policies or credentials.
-
-In the host's Node-capable REPL:
+Installed module: `{{MODULE_URL}}`; CLI: `{{CLI_PATH}}`.
+In this repository use the absolute file URL of `<repository>/packages/x-harness/dist/index.js` with original ledger/proof paths. Unresolved placeholders do not require reinstalling an existing repository runtime. Only absent runtime/workspace or an update needs [setup](references/setup.md).
 
 ```js
-const { createXGrowthHarness } = await import("MODULE_URL_FROM_SETUP");
-const x = createXGrowthHarness({ tab, ledgerPath, proofDirectory });
-const result = await x.readCreator({
-  handle: "USER_HANDLE",
-  target: 5,
-  mode: "decision",
-});
-// Print only the needed result; keep the full browser observation in the REPL.
+var { createXGrowthHarness } = await import(moduleURL);
+var x = createXGrowthHarness({ tab, ledgerPath, proofDirectory });
 ```
 
-Substitute the stable installed URL and initialized paths. Never assume an old imported module hot-reloads after updating. Read `references/api.md` only for the next operation's arguments and the installed `.d.ts` for detailed types.
-
-## Execution
-
-Choose the single named task: readCreator/readBookmarks/searchSources/readPost/readPerson/readFeedback/inspectAccount; publishPost/replyToPost/followOne/followBatch; inspectRound/runGrowthRound; verifySubmission/verifyPublishedPost/verifyFollow. `receipt` is the default compact result; `decision` includes full relevant evidence; `delta` rereads and returns changed complete evidence plus unchanged IDs. Do not trim the target's body to save tokens.
-
-Writing needs explicit authorization from the current user, verified identity, their own ledger plan, reviewed prepared actions and existing evidence files. Initialization plans zero writes. Set the authorized planned count in the original ledger before execution; never expand an authorized scope yourself. Check the installed types for action, quality and executor fields; retain one owner for the ledger, do not invent approvals or evidence. The current runtime writes only 07:00–22:00 Asia/Shanghai and follow candidate gates require reviewed Chinese-language, blue-check candidates; disclose these conditions when relevant.
-
-Interpret returned status literally: `verified` requires public proof; `unknown` is not success. For an unknown submission, call verifySubmission on the same action before any new submission. `needsCapability`, `needsDecision`, `waiting` and partial windows must be reported, with the next required condition. Capture visual media before making claims about its contents.
+## Load by task
 
-## Updates
+| Current need | Read only |
+| --- | --- |
+| Creator/bookmarks/search/post/person/feedback/account | [reads](references/reads.md) |
+| Publish/reply/follow or a round | [writes](references/writes.md), preamble + common review + matching operation heading |
+| Unknown submission, missing capability or connection failure | [recovery](references/recovery.md) |
 
-Run `npx @nextclaw/x-harness@latest update --target codex` (or claude). It stages the exact fetched release, replaces only managed runtime/Skill directories, saves the previous version and retains user workspaces/configurations. It refuses unfamiliar directories. Start a fresh module binding afterward and verify the next real read operation. A release's distributed Skill and runtime use the same version.
+Default `receipt` is for status; use `decision` on the first call needing content, `delta` for changed evidence with valid prior context. Keep observations in REPL/proof; return complete relevant evidence and actionable warnings. Never truncate target text or print full DOM/AX. Root calls own capability checks, intent, submission, verification and settlement; verified results need no extra preflight/reload/verify.
 
-Free use under the bundled proprietary license; the distributed JS is readable, the TS source repository remains private. Website: https://x-harness.gemigo.app/
+Writes require user authorization, verified identity, reviewed evidence and the original ledger plan; project rules own policy. Unknown submission: verify the same action before any new submission. Follow recovery for other failures; read source only to repair a concrete defect/unsupported capability, verify, then return to root calls.

package/skill/references/api.md

@@ -1,37 +1,10 @@
-# Root API usage
+# API navigation
 
-Bind once: `createXGrowthHarness({ tab, ledgerPath, proofDirectory })`. Exactly one `tab` or native `app`. Read operations can use the initialized zero-write plan.
+Compatibility index; normal tasks route directly from the Skill. Load one current reference, not all files.
 
-```js
-await x.readCreator({
-  handle: "USER_HANDLE",
-  target: 10,
-  maxScrolls: 8,
-  mode: "decision",
-});
-await x.searchSources({ query: "AI agents", limit: 5, mode: "decision" });
-await x.readBookmarks({ folder: "FOLDER_NAME", limit: 5, mode: "decision" });
-await x.inspectAccount({ mode: "decision" });
-await x.readPost({ target: { postId, url, evidenceRef }, mode: "decision" });
-await x.readPerson({ target: { handle, url, evidenceRef }, mode: "decision" });
-await x.readFeedback({
-  targets: [{ postId, url, evidenceRef }],
-  mode: "decision",
-});
-await x.inspectRound({ taskId });
-```
+- Reading: [reads](reads.md).
+- Reviewed writes/rounds: [writes](writes.md), matching operation heading.
+- Failure/unknown submission: [recovery](recovery.md).
+- Missing installation/workspace or update: [setup](setup.md).
 
-Targets/evidence come from prior observed results. Exact option types are in the installed `dist/types.d.ts`. `readFeedback` may need your accountURL as documented there. Preserve full relevant content and expose missing fields rather than inventing them.
-
-```js
-await x.publishPost({ taskId, draftPath, preparedAction: originalAction });
-await x.replyToPost({ taskId, postId, text, preparedAction: replyAction });
-await x.followOne({ taskId, handle }); // action already prepared in the original ledger
-await x.followBatch({ taskId, handles, preparedActions });
-await x.verifySubmission({ taskId, actionId });
-await x.verifyPublishedPost({ taskId, draftPath, publicURL, evidenceRef });
-await x.verifyFollow({ handle, url, evidenceRef });
-await x.runGrowthRound({ taskId, maxActions: 3 });
-```
-
-Before preparing writes, read the appropriate installed PreparedAction and operation option types. Required reviewed evidence cannot be replaced with a made-up reference. Original posts include actual draftPath, complete text, observed compose URL/proof, author proof and approvedText/draftFingerprint quality. Reply/follow targets require observed evidence. Concurrent task tabs need an explicitly evidenced executor scope; see HarnessOptions/Executor. Business root calls own capability checks, intent journaling, single submission, public verification and ledger settlement.
+Public declarations are the compatibility contract for custom integrations, not a prerequisite for documented calls.

package/skill/references/reads.md

@@ -0,0 +1,23 @@
+# Read tasks
+
+Load for reading only. A valid root binding `x` with existing ledger/proof paths suffices; no write plan needed. `mode` defaults to `receipt`; use `decision` immediately when drafting/reviewing needs text. `delta` omits only unchanged evidence previously returned by this instance; after context loss use `decision`.
+
+| API | Required | Optional |
+| --- | --- | --- |
+| readCreator | handle | target (default 10, 1–50), maxScrolls, navigate, expand, mode |
+| readBookmarks | folder (observed name) | processedIds, limit, maxPages, mode |
+| searchSources | query | processedIds, limit, maxPages, mode |
+| readPost | target: {postId,url,evidenceRef} | mode |
+| readPerson | target: {handle,url,evidenceRef} | mode |
+| readFeedback | targets: [{postId,url,evidenceRef}] | replyLimit, mode |
+| inspectAccount | none | mode |
+| inspectRound | taskId (original batch ID) | none |
+
+```js
+var result = await x.readCreator({ handle: selectedHandle, target: 5, mode: 'decision' });
+var postResult = await x.readPost({ target: observedPost, mode: 'decision' });
+```
+
+Targets/proof come from actual observations, never guessed URLs or made-up references. API owns navigation/expansion and bounded collection. Native creator collection may return `needsCapability`; inspect that signal before changing adapter.
+
+Results include status/evidenceRef/missing/IDs/completeness. In `decision`, creator/bookmark/search use `sources`, post `post`, person `person`, feedback `feedback`; account includes accountHandle/accountURL. `observed` alone does not prove every requested field exists. `pageComplete:false` is a collection boundary, not proof of truncated target text. View media before describing it. Return complete chosen evidence; keep other observations local. Only on failure load recovery.

package/skill/references/recovery.md

@@ -0,0 +1,25 @@
+# Recovery by signal
+
+Load on failure/unknown only. Keep operation/status/missing/code/proof/error; never infer success or repeat identical failures.
+
+| Signal | Next action and exit condition |
+| --- | --- |
+| unknown submission | `await x.verifySubmission({taskId,actionId})`, same IDs; no replacement action or new submission before resolution. |
+| Existing public post needs recovery | `await x.verifyPublishedPost({taskId,draftPath,publicURL,evidenceRef})`; observed URL/proof. Optional sourceLink: {href,resolvedURL,evidenceRef,renderedText?}. |
+| Follow needs independent recovery | `await x.verifyFollow({handle,url,evidenceRef,mode:'decision'})`; honor returned verified. Normal followBatch already verifies. |
+| needsDecision | Resolve returned missing review/proof in original action, resume same ID. Current AI performs internal review under project contract. |
+| waiting | Honor resumeAt/reason, continue independent permitted work; never bypass time/identity/claim gates. |
+| needsCapability | Inspect exact missing method/operation. If a supported binding supplies it, rebind once and retry a necessary read; otherwise repair reported owner with failing sample and targeted validation. |
+| diagnostic.next: inspect-local-proof | Read only `{operation,error}` from diagnostic.evidenceRef; resolve via this reference, keep full proof local. Unknown/intent needs same-ID verification. Unsupported: report code/error and update/support; no private source. |
+| diagnostic.next: restore-proof-store | Restore the workspace's writable proof directory, then resume the same action. Do not replace its ledger or infer submission failure. |
+| Missing fields/partial window | Narrow to target, expand/advance documented bounded window; preserve text. No whole-page output or automatic reload. |
+
+## Host connection or native focus
+
+Failure to list/bind Chrome is a host-connection failure before reaching X, not proof of logged-out X. Per current host documentation rediscover the task tab once; validate navigation plus a necessary visible read. Native focus rejection instead needs latest AX URL/window confirmation and one supported focus correction. Do not repeat discovery or restart editors blindly.
+
+Lost tab: reuse a live owned tab or create a task tab in the same actual browser; preserve other editors. Native fallback changes binding to app, not business calls; unsupported native tasks remain gaps. Network/TUN observations do not authorize setting changes.
+
+## Repair boundary
+
+Normal use/known recovery need no source. Unresolved runtime defect/unsupported capability permits diagnostics: maintainers repair the owner, verify the failed boundary and return to root; consumers report gap/update/support, without private TS. Never scan adapters for arguments, add parsers, bypass refusal or resubmit unknown.

package/skill/references/setup.md

@@ -0,0 +1,23 @@
+# Setup and updates
+
+Load only when runtime/workspace is absent, binding needs refreshing after update, or adapter scope changes.
+
+## Repository runtime
+
+Use `<repository>/packages/x-harness/dist/index.js` as an absolute file URL; if absent run `pnpm --filter @ai-content-studio/x-harness build`. Reuse original ledger/proofs and runtime-context entry; do not initialize a second ledger or download another runtime. Global Skill links to this repository owner.
+
+## Independent installation
+
+Requires Node 22+, compatible CUA and own X login. Run `npx @nextclaw/x-harness@latest setup --target codex` (or `--target claude`); use returned moduleURL/cliPath. Setup substitutes placeholders. Skill text does not add browser access. Missing host/login is a prerequisite, not permission to invent execution.
+
+Initialize once: `node <cliPath> init --directory <user workspace> --account <user handle>`. Reuse returned ledgerPath/proofDirectory/taskId; initialization plans zero writes. Existing project state remains its owner.
+
+## Adapter and parallel scope
+
+Host owns tab/app acquisition: read its current documentation once and reuse the valid handle. Tab needs url(), playwright.evaluate() and locators; native app AX/click/key/paste. Do not launch a separate driver.
+
+Native binding: `{app,ledgerPath,proofDirectory}` instead of tab. Independent task tabs may add `executor:{id:taskId,scopeKinds:['original'],evidenceRef:scopeProof}` using actual authorized scope/proof; kinds are original/reply/follow. Never borrow another executor's editor or claim.
+
+## Update
+
+Independent installs run `npx @nextclaw/x-harness@latest update --target codex` (or claude); it backs up managed runtime/Skill and preserves workspaces. Repository users update the original repository owner. Rebind using the new versioned moduleURL returned by update or written into this Skill; it refreshes the whole dependency graph in a persistent REPL. Never reuse the previous URL or add a root-only query string. Preserve pending actions/editors; reacquire the task tab after a necessary host reset. Verify one necessary read with the new module, not all documents. Distributed Skill/runtime share a version. Free use follows bundled proprietary license; TS source remains private.

package/skill/references/writes.md

@@ -0,0 +1,51 @@
+# Writes and rounds
+
+Load common review plus only the operation heading needed. Existing project contract owns authorization, identity, budgets, policy and original ledger plan. Independent initialization has zero planned writes; set only authorized counts in that ledger before executing. Current runtime window is 07:00–24:00 Asia/Shanghai for replies and 07:00–22:00 for other writes; follow gates require reviewed Chinese-language blue-check candidates. Do not expand scope. Examples below use existing real observations/proof; they are not executable authorization.
+
+## Common review
+
+A prepared action has id (stable original ID), status:'prepared', accountHandle, accountURL, accountEvidenceRef and quality. All proof references are existing files; URLs/identity must be actually observed. Already prepared ledger actions need not be prepared again.
+
+Content quality: `{approved:true,approvedText:text,evidenceRef:reviewProof,draftFingerprint}`; original fingerprint is SHA-256 of exact draft file bytes. Use Node crypto/createHash and fs/readFileSync locally; this requires no runtime source. Reply quality needs approvedText/proof; original also needs draftFingerprint. Any changed text/file needs a fresh review. Follow quality: `{approved:true,handle,blue:true,chinese:true,evidenceRef:reviewProof}`; verify evidence, never infer blue from generic certification.
+
+Action APIs return status/actionId/publicURL/evidenceRef and reason/missing/resumeAt when relevant. Verified requires public proof. Unknown loads recovery, never resubmits. Business calls own intent, submit once, fresh verification and original settlement.
+
+## Publish
+
+Additional fields: kind:'original', draftPath (existing .post.md), text (complete approved text), composeURL, composeEvidenceRef; optional assets:[{path,alt}], activation:'click'|'keyboard'. Every media path must exist and be reviewed.
+
+```js
+var result = await x.publishPost({ taskId, draftPath, preparedAction: {
+  id: actionId, status: 'prepared', kind: 'original',
+  accountHandle, accountURL, accountEvidenceRef,
+  quality: { approved: true, approvedText: text, evidenceRef: reviewProof, draftFingerprint },
+  draftPath, text, composeURL, composeEvidenceRef,
+} });
+```
+
+Optional independentExecution:{tabId,evidenceRef,scopeEvidenceRef} requires real independent task-tab/scope proof; binding executor scope is covered in setup only if needed. Existing original action can omit preparedAction; draftPath still required.
+
+## Reply
+
+Additional fields: kind:'reply', postId, url, evidenceRef (observed parent), text; optional assets/activation as above. Common account/quality fields still required. The exact parent is verified by the API.
+
+```js
+var result = await x.replyToPost({ taskId, postId, text, preparedAction: {
+  id: actionId, status: 'prepared', kind: 'reply',
+  accountHandle, accountURL, accountEvidenceRef,
+  quality: { approved: true, approvedText: text, evidenceRef: reviewProof },
+  postId, url: parentURL, evidenceRef: parentProof, text,
+} });
+```
+
+## Follow
+
+Additional fields: kind:'follow', handle, url, evidenceRef (observed person), plus common account fields and follow quality. Batch uses `{taskId,handles,preparedActions?}`; original contract determines allowed batch sizes. Each preparedAction corresponds to its handle. If already prepared, omit preparedActions. `await x.followOne({taskId,handle})` requires its original prepared action and project-permitted single-action scope. A preexisting relationship is not a new verified follow; honor result counts.
+
+## Round
+
+`await x.inspectRound({taskId})` inspects original state; `await x.runGrowthRound({taskId,maxActions})` runs/resumes it. maxActions bounds this call, not original planned total. Preparation uses decision:{type:'prepareActions',accountHandle,ownershipEvidenceRef,actions}; actions are the reviewed structures above.
+
+Optional decision fields: attemptsCoverage:{complete,since,evidenceRef}, sharedAttempts:[{kind,at}], nextScheduledCheckAt. For follow budgets, coverage must actually cover the required window; unknown history cannot be recorded as zero. Missing data remains a decision gap.
+
+Review an existing action with decision:{actionId,approved,evidenceRef,approvedText?,draftFingerprint?,blue?,chinese?}; use content fields for content, blue/chinese for follow. approved:false skips that candidate without filling original planned count. Preserve intent/unknown/verified states and IDs. Read returned gaps/decision/mayEnd; partial success is not whole-round completion.