@nextclaw/x-harness 0.2.63 → 0.2.65

package/README.md

@@ -34,6 +34,8 @@ const result = await x.readCreator({
 ```
 
 Read APIs: `readCreator`, `readBookmarks`, `searchSources`, `readPost`, `readPerson`, `readFeedback`, `inspectAccount`, `inspectRound`.
+Bulk list audit: `readFollowbackAudit` saves deduplicated relationship lists and resumable coverage evidence. Followback direction reads unfiltered followers; unmatched profile counts remain incomplete. See [the API reference](skill/references/followback-audit.md). `followBatch` optionally persists bounded random intent gaps, while retaining all original budget, refusal and unknown guards.
+
 Write APIs: `publishPost`, `replyToPost`, `followOne`, `followBatch`, `runGrowthRound`.
 Recovery: `verifySubmission`, `verifyPublishedPost`, `verifyFollow`.
 

package/SOURCE.md

@@ -1,8 +1,8 @@
 # Corresponding source
 
-Version 0.2.63, commit 6e70dc4b7351bc7ec59936ed517465133001099b.
+Version 0.2.65, commit ece6b7ad7f4355d105ed6ec939bbcd8c136b4ce1.
 
-Complete source, build scripts and dependencies: https://github.com/Peiiii/x-harness/tree/6e70dc4b7351bc7ec59936ed517465133001099b
+Complete source, build scripts and dependencies: https://github.com/Peiiii/x-harness/tree/ece6b7ad7f4355d105ed6ec939bbcd8c136b4ce1
 
 Clone this revision, run npm ci, npm run bootstrap and npm run release:build.
 

package/dist/api.d.ts

@@ -89,6 +89,7 @@ export declare class BusinessHarness implements XGrowthHarness {
         target: import("./types.js").PostTarget;
         mode?: ReadMode;
     }): Promise<ReadResult>;
+    readFollowbackAudit(args: import("./types.js").FollowbackAuditOptions): Promise<import("./types.js").FollowbackAuditResult>;
     readPeople(args: import("./types.js").PeopleOptions): Promise<ReadResult>;
     readPerson({ target, mode, }: {
         target: import("./types.js").PersonTarget;

package/dist/api.js

@@ -1,15 +1,18 @@
 import { sameHandle, samePublishedText } from "./platform-rules.js";
+import { FollowbackAudit } from "./followback-audit.js";
 import { IncomingReactions } from "./incoming-reactions.js";
 import { createGrowthHarness } from "./growth.js";
 import { readResult, decisions, diagnostic, stableReason } from "./results.js";
 export class BusinessHarness {
     #reactions;
+    #followbackAudit;
     #platform;
     #store;
     #core;
     #readCache;
     #clock;
     constructor(dependencies) {
+        this.readFollowbackAudit = this.readFollowbackAudit.bind(this);
         this.replyBatch = this.replyBatch.bind(this);
         this.likeIncomingBatch = this.likeIncomingBatch.bind(this);
         this.#reactions = new IncomingReactions(dependencies);
@@ -37,6 +40,7 @@ export class BusinessHarness {
         this.#platform = platform;
         this.#store = store;
         this.#core = createGrowthHarness(dependencies);
+        this.#followbackAudit = new FollowbackAudit((args) => this.#core.readPeople(args), (value) => store.recordProof(value), this.#clock, (ref) => store.evidenceExists(ref));
         this.#readCache = new Map();
     }
     async invoke(operation, args) {
@@ -598,6 +602,9 @@ export class BusinessHarness {
     readPost({ target, mode, includeContext, includeThread, resolveQuote, }) {
         return this.read("readPost", { ...target, includeContext, includeThread, resolveQuote }, mode);
     }
+    readFollowbackAudit(args) {
+        return this.#followbackAudit.run(args);
+    }
     readPeople(args) {
         return this.read("readPeople", args, args.mode);
     }

package/dist/browser-dom-capabilities.js

@@ -10,6 +10,11 @@ export class DOMCapabilities {
     }
     capabilities(operation) {
         const base = missingMethods(this.#tab?.playwright, ["evaluate"]);
+        if (operation === "resetPeople")
+            return [
+                ...base,
+                ...missingMethods(this.#tab, ["getAXState", "pressKey"]),
+            ];
         if (operation === "readPeople") {
             base.push(...missingMethods(this.#tab, ["goto", "url"]), ...missingMethods(this.#tab?.playwright, ["locator", "waitForURL"]));
             if (typeof this.#tab?.playwright?.locator === "function")

package/dist/browser-dom-editing.js

@@ -169,17 +169,50 @@ export class DOMEditing {
     }
     async handleNextPeople(_command) {
         const current = this.#session.current;
+        const reset = _command.reset === true;
         const handle = current?.result?.people?.at(-1)?.handle;
         if (current?.query?.view !== "people" ||
-            current.result.needsStateCheck ||
+            (!reset && current.result.needsStateCheck) ||
             current.result.alerts?.length ||
-            !/^[A-Za-z0-9_]{1,15}$/.test(handle ?? ""))
+            (!reset && !/^[A-Za-z0-9_]{1,15}$/.test(handle ?? "")))
             throw new Error("people-page-unconfirmed");
+        this.#session.current = null;
+        if (reset) {
+            await this.#tab.getAXState({ emit: false });
+            await this.#tab.pressKey(null, "Control+Home");
+            await this.#tab.getAXState({ emit: false });
+            return { completed: true };
+        }
+        if (typeof this.#tab.getAXState === "function" &&
+            typeof this.#tab.scroll === "function") {
+            const ax = await this.#tab.getAXState({
+                emit: false,
+                disableDiffing: true,
+            });
+            const anchorHandle = current.result.scrollAnchor?.handle;
+            const control = typeof ax === "string" &&
+                /^[A-Za-z0-9_]{1,15}$/.test(anchorHandle ?? "")
+                ? ax.match(new RegExp(`^.*?([0-9]+) button (?:正在关注|取消关注|回关|关注) @${anchorHandle}\\s*$`, "m"))
+                : null;
+            if (control) {
+                const pages = current.result.scrollAnchor?.pages;
+                await this.#tab.scroll(Number(control[1]), "down", Number.isInteger(pages) && pages >= 1 && pages <= 20 ? pages : 1);
+                await this.#tab.getAXState({ emit: false });
+                return { completed: true };
+            }
+            const timeline = typeof ax === "string"
+                ? ax.match(/^.*?([0-9]+) (?:container|scroll area) (?:时间线：|Timeline: ?)(?:正在关注|关注者|认证关注者|Following|Followers|Verified followers)\s*$/m)
+                : null;
+            if (timeline) {
+                await this.#tab.scroll(Number(timeline[1]), "down", 1);
+                await this.#tab.getAXState({ emit: false });
+                return { completed: true };
+            }
+        }
         const anchor = this.#tab.playwright
             .locator(`main [data-testid="primaryColumn"] a[href=${JSON.stringify("/" + handle)}]`)
             .filter({ visible: true, hasText: new RegExp(`^@${handle}$`, "i") });
         const unique = await this.#unique(anchor);
-        this.#session.current = null;
         if (typeof this.#tab.pressKey === "function")
             await this.#tab.pressKey(null, "PageDown");
         else

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

@@ -14,6 +14,8 @@ export declare class DOMNavigation {
     private handleWaitForFolder;
     private handleWaitForPosts;
     private handleOpenObserved;
+    private waitFallbackRoute;
+    private handleWaitProfileContent;
     private handleWaitTargetContent;
     private handleRefreshPerson;
     private handleRefreshPosts;

package/dist/browser-dom-navigation.js

@@ -145,8 +145,11 @@ export class DOMNavigation {
         // Explicit recovery uses forceNavigation; durable verification uses refreshPerson.
         if (!command.forceNavigation &&
             typeof this.#tab.url === "function" &&
-            (await this.#tab.url()) === xURL(command.url).href)
+            (await this.#tab.url()) === xURL(command.url).href) {
+            if (command.view === "person")
+                await this.handleWaitProfileContent(this.#tab.playwright.locator('[data-testid="UserName"]'), command.url);
             return;
+        }
         const originalPage = typeof this.#tab.url === "function"
             ? await this.#tab.url()
             : this.#session.current?.result?.page;
@@ -203,15 +206,12 @@ export class DOMNavigation {
                     check.alerts?.length)
                     throw error;
                 await this.#tab.goto(command.url);
-                await this.#tab.playwright.waitForURL(command.url, {
-                    timeoutMs: command.view === "posts" ? 15000 : 5000,
-                    ...(command.view === "posts" ? { waitUntil: "commit" } : {}),
-                });
+                await this.waitFallbackRoute(command);
             }
         }
         if (command.view === "person") {
             // Profile readiness belongs to profile content; self profiles have no Follow button.
-            await this.handleWaitTargetContent(this.#tab.playwright.locator('[data-testid="UserName"]'), command.url);
+            await this.handleWaitProfileContent(this.#tab.playwright.locator('[data-testid="UserName"]'), command.url);
         }
         else if (command.view === "people") {
             await this.#tab.playwright
@@ -237,6 +237,41 @@ export class DOMNavigation {
         }
         return;
     }
+    async waitFallbackRoute(command) {
+        try {
+            await this.#tab.playwright.waitForURL(command.url, {
+                timeoutMs: command.view === "posts" ? 15000 : 5000,
+                ...(command.view === "posts" ? { waitUntil: "commit" } : {}),
+            });
+        }
+        catch (error) {
+            if (command.view !== "posts" ||
+                !/Timed out waiting for URL/.test(error.message))
+                throw error;
+            const check = await this.#observe({ view: "account", limit: 1 });
+            if (check.page !== command.url || check.alerts?.length)
+                throw error;
+            // Only a committed exact route is recovered; exact content readiness still follows.
+        }
+    }
+    async handleWaitProfileContent(target, url) {
+        try {
+            await this.handleWaitTargetContent(target, url);
+            return;
+        }
+        catch (error) {
+            if (!/timed out|timeout|deadline exceeded/i.test(error.message))
+                throw error;
+            const check = await this.#observe({ view: "account", limit: 1 });
+            if (check.page !== url || check.alerts?.length)
+                throw Error("target-readiness-route-or-alert", { cause: error });
+            // A loaded X error view does not become a profile by waiting longer.
+            // Reopen this exact observed route once; never repeat a Follow click.
+            this.#session.current = null;
+            await this.#tab.goto(url);
+            await this.handleWaitTargetContent(target, url);
+        }
+    }
     async handleWaitTargetContent(detail, url) {
         const deadline = Date.now() + 15000;
         for (let attempt = 0; attempt < 4; attempt++) {
@@ -257,7 +292,7 @@ export class DOMNavigation {
                     throw error;
                 const check = await this.#observe({ view: "account", limit: 1 });
                 if (check.page !== url || check.alerts?.length)
-                    throw error;
+                    throw Error("target-readiness-route-or-alert", { cause: error });
             }
         }
     }
@@ -284,7 +319,7 @@ export class DOMNavigation {
             idleTimedOut = true;
         }
         await this.#tab.reload();
-        await this.handleWaitTargetContent(this.#tab.playwright.getByRole("button", {
+        await this.handleWaitProfileContent(this.#tab.playwright.getByRole("button", {
             name: new RegExp(`^(?:正在关注|取消关注|关注|回关) @${command.handle}$`, "i"),
         }), command.url);
         if (idleTimedOut)

package/dist/browser-native.js

@@ -133,6 +133,7 @@ export class NativeXBrowser {
                             ? "not-following"
                             : "unknown",
                 blue: null,
+                blueEvidenceSupported: false,
             };
         }
         if (query.view === "composer") {

package/dist/executor-actionability.d.ts

@@ -0,0 +1,2 @@
+/** An explicit executor-local restriction never relaxes account-wide refusals. */
+export declare function actionableForExecutor(state: any, kind: string, executor: any, evidenceExists: (path: any) => boolean): boolean;

package/dist/executor-actionability.js

@@ -0,0 +1,17 @@
+/** An explicit executor-local restriction never relaxes account-wide refusals. */
+export function actionableForExecutor(state, kind, executor, evidenceExists) {
+    const item = state.items.find((i) => i.kind === kind);
+    if (item?.actionable === true)
+        return true;
+    const restriction = item?.executionRestriction;
+    return Boolean(restriction?.scope === "executor" &&
+        restriction.executorId &&
+        restriction.reason === item.reason &&
+        item.blockEvidence?.includes(restriction.evidenceRef) &&
+        executor?.id &&
+        restriction.executorId !== executor.id &&
+        executor.scopeKinds?.includes(kind) &&
+        evidenceExists(executor.evidenceRef) &&
+        evidenceExists(restriction.evidenceRef) &&
+        state.executions?.[restriction.executorId]?.scopeKinds?.includes(kind));
+}

package/dist/follow-batch-pacing.d.ts

@@ -0,0 +1,11 @@
+import type { RoundStore } from "./store.js";
+import type { FollowPacing } from "./types.js";
+/** Waits from the latest actual account attempt; chosen gaps survive batch resume. */
+export declare class FollowBatchPacing {
+    private store;
+    private clock;
+    private wait;
+    constructor(store: RoundStore, clock: () => number, wait?: (ms: number) => Promise<void>);
+    static validate(pacing?: FollowPacing): void;
+    before(batchId: string, handle: string, pacing?: FollowPacing): Promise<void>;
+}

package/dist/follow-batch-pacing.js

@@ -0,0 +1,49 @@
+import { randomInt } from "node:crypto";
+/** Waits from the latest actual account attempt; chosen gaps survive batch resume. */
+export class FollowBatchPacing {
+    store;
+    clock;
+    wait;
+    constructor(store, clock, wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+        this.store = store;
+        this.clock = clock;
+        this.wait = wait;
+    }
+    static validate(pacing) {
+        if (pacing &&
+            (!Number.isSafeInteger(pacing.minGapMs) ||
+                !Number.isSafeInteger(pacing.maxGapMs) ||
+                pacing.minGapMs < 5000 ||
+                pacing.maxGapMs > 30000 ||
+                pacing.maxGapMs < pacing.minGapMs))
+            throw new Error("follow-pacing-range-invalid");
+    }
+    async before(batchId, handle, pacing) {
+        if (!pacing)
+            return;
+        const snapshot = await this.store.transaction(({ state }) => {
+            const next = structuredClone(state), batch = next.followBatches.find((b) => b.id === batchId);
+            if (!batch)
+                throw new Error("follow-pacing-batch-missing");
+            if (batch.pacing &&
+                JSON.stringify(batch.pacing) !== JSON.stringify(pacing))
+                throw new Error("follow-pacing-resume-mismatch");
+            batch.pacing ??= pacing;
+            batch.gaps ??= {};
+            batch.gaps[handle.toLowerCase()] ??= {
+                gapMs: randomInt(pacing.minGapMs, pacing.maxGapMs + 1),
+            };
+            return next;
+        });
+        const attempts = (snapshot.state.attempts ?? []).filter((a) => a.kind === "follow" && Number.isFinite(Date.parse(a.at)));
+        const lastAt = Math.max(...attempts.map((a) => Date.parse(a.at)));
+        if (!Number.isFinite(lastAt))
+            return;
+        const batch = snapshot.state.followBatches.find((b) => b.id === batchId);
+        const notBefore = lastAt + batch.gaps[handle.toLowerCase()].gapMs;
+        const remaining = notBefore - this.clock();
+        if (remaining > 0)
+            await this.wait(remaining);
+        // The round owns fresh guards/claims/authorization after this wait, before intent.
+    }
+}

package/dist/followback-audit.d.ts

@@ -0,0 +1,13 @@
+import type { BoundaryRecord } from "./boundary.js";
+import type { FollowbackAuditOptions, FollowbackAuditResult } from "./types.js";
+/** Owns a read-only two-list observation, not an unfollow plan or account ledger. */
+export declare class FollowbackAudit {
+    #private;
+    constructor(read: (args: BoundaryRecord) => Promise<BoundaryRecord>, proof: (value: unknown) => Promise<string>, clock: () => number, evidenceExists: (ref: string) => boolean);
+    private allowed;
+    private validate;
+    private job;
+    private window;
+    private result;
+    run(args: FollowbackAuditOptions): Promise<FollowbackAuditResult>;
+}

package/dist/followback-audit.js

@@ -0,0 +1,281 @@
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+/** Owns a read-only two-list observation, not an unfollow plan or account ledger. */
+export class FollowbackAudit {
+    #read;
+    #proof;
+    #clock;
+    #evidenceExists;
+    #jobs = new Map();
+    #running = false;
+    constructor(read, proof, clock, evidenceExists) {
+        this.#read = read;
+        this.#proof = proof;
+        this.#clock = clock;
+        this.#evidenceExists = evidenceExists;
+    }
+    allowed(args) {
+        const hour = new Date(this.#clock() + 8 * 3600000).getUTCHours();
+        return (hour >= 7 ||
+            (args.nightReadAuthorization?.userAuthorized === true &&
+                this.#evidenceExists(args.nightReadAuthorization.evidenceRef) &&
+                Number.isFinite(Date.parse(args.nightReadAuthorization.expiresAt)) &&
+                this.#clock() < Date.parse(args.nightReadAuthorization.expiresAt)));
+    }
+    validate(args) {
+        if (args.direction && !["both", "followback"].includes(args.direction))
+            throw new Error("followback-direction-invalid");
+        const a = new URL(args.following.url), b = new URL(args.followers.url);
+        const match = a.pathname.match(/^\/([A-Za-z0-9_]{1,15})\/following\/?$/);
+        if (!match ||
+            !["x.com", "www.x.com"].includes(a.hostname) ||
+            a.protocol !== "https:" ||
+            b.origin !== a.origin ||
+            b.pathname.toLowerCase().replace(/\/$/, "") !==
+                `/${match[1].toLowerCase()}/followers` ||
+            a.search ||
+            b.search ||
+            a.hash ||
+            b.hash ||
+            !args.following.evidenceRef ||
+            !args.followers.evidenceRef)
+            throw new Error("followback-own-unfiltered-list-targets-required");
+        for (const target of [args.following, args.followers])
+            if (target.expectedCount !== undefined &&
+                (!Number.isSafeInteger(target.expectedCount) ||
+                    target.expectedCount < 0))
+                throw new Error("followback-exact-count-required");
+        if (!Number.isInteger(args.maxWindows ?? 100) ||
+            (args.maxWindows ?? 100) < 1 ||
+            (args.maxWindows ?? 100) > 1000)
+            throw new Error("followback-window-budget-invalid");
+    }
+    job(args) {
+        this.validate(args);
+        const targets = { following: args.following, followers: args.followers };
+        if (args.scanId) {
+            let prior = this.#jobs.get(args.scanId);
+            if (!prior &&
+                args.resumeEvidenceRef &&
+                this.#evidenceExists(args.resumeEvidenceRef)) {
+                const checkpoint = JSON.parse(readFileSync(args.resumeEvidenceRef, "utf8"));
+                if (checkpoint.schema !== "followback-audit/v1" ||
+                    checkpoint.scanId !== args.scanId)
+                    throw new Error("followback-checkpoint-invalid");
+                for (const kind of ["following", "followers"]) {
+                    if (!checkpoint[kind]?.entries ||
+                        Object.values(checkpoint[kind].entries).some((p) => !/^[A-Za-z0-9_]{1,15}$/.test(p.handle ?? "") ||
+                            p.url?.toLowerCase() !==
+                                `https://x.com/${p.handle.toLowerCase()}`))
+                        throw new Error("followback-checkpoint-invalid");
+                }
+                prior = checkpoint;
+            }
+            if (!prior)
+                throw new Error("followback-resume-mismatch");
+            if (JSON.stringify(prior.targets) !== JSON.stringify(targets)) {
+                for (const kind of ["following", "followers"]) {
+                    const old = prior.targets[kind], target = targets[kind];
+                    if (old.url !== target.url ||
+                        !this.#evidenceExists(target.evidenceRef))
+                        throw new Error("followback-resume-mismatch");
+                    if (old.expectedCount !== target.expectedCount &&
+                        old.evidenceRef === target.evidenceRef)
+                        throw new Error("followback-counter-revision-proof-required");
+                }
+                prior.counterRevisions ??= [];
+                prior.counterRevisions.push({
+                    at: new Date(this.#clock()).toISOString(),
+                    before: prior.targets,
+                    after: targets,
+                });
+                prior.targets = targets;
+                for (const kind of ["following", "followers"])
+                    prior[kind].complete =
+                        targets[kind].expectedCount !== undefined &&
+                            Object.keys(prior[kind].entries).length ===
+                                targets[kind].expectedCount &&
+                            !prior[kind].gaps.length;
+            }
+            this.#jobs.set(args.scanId, prior);
+            return prior;
+        }
+        const job = {
+            scanId: randomUUID(),
+            targets,
+            startedAt: new Date(this.#clock()).toISOString(),
+            following: {
+                entries: {},
+                complete: false,
+                advance: false,
+                stalled: 0,
+                gaps: [],
+            },
+            followers: {
+                entries: {},
+                complete: false,
+                advance: false,
+                stalled: 0,
+                gaps: [],
+            },
+            windows: [],
+        };
+        this.#jobs.set(job.scanId, job);
+        return job;
+    }
+    async window(job, kind) {
+        const state = job[kind], target = job.targets[kind];
+        const value = await this.#read({
+            target,
+            limit: 1000,
+            offset: state.started ? (state.offset ?? 0) : 0,
+            reset: !state.started,
+            bulk: true,
+            advance: state.started ? state.advance : false,
+            mode: "decision",
+        });
+        job.windows.push({
+            kind,
+            at: new Date(this.#clock()).toISOString(),
+            evidenceRef: value.evidenceRef,
+            status: value.status,
+        });
+        if (value.status !== "observed" || !value.complete || value.alerts?.length)
+            return value.reason ?? value.status;
+        const owner = new URL(target.url).pathname.split("/")[1];
+        if (value.accountHandle?.toLowerCase() !== owner.toLowerCase())
+            return "account-identity-unconfirmed";
+        state.started = true;
+        const before = Object.keys(state.entries).length;
+        for (const person of value.people ?? []) {
+            if (!person.handle ||
+                (person.relationship === "unknown" &&
+                    (kind === "following" || !value.listBound))) {
+                state.gaps.push({
+                    reason: "following-control-or-identity-unconfirmed",
+                    evidenceRef: value.evidenceRef,
+                });
+                continue;
+            }
+            if (kind === "following" && person.relationship !== "following")
+                continue;
+            if (kind === "followers" &&
+                !value.listBound &&
+                person.relationship !== "follows-you" &&
+                !person.followsYou)
+                continue;
+            Object.defineProperty(state.entries, person.handle.toLowerCase(), {
+                enumerable: true,
+                configurable: true,
+                writable: true,
+                value: {
+                    handle: person.handle,
+                    url: person.url,
+                    evidenceRef: value.evidenceRef,
+                    relationship: person.relationship,
+                    followsYou: person.followsYou,
+                    listMembership: value.listBound ? kind : undefined,
+                },
+            });
+        }
+        const count = Object.keys(state.entries).length;
+        state.complete =
+            target.expectedCount !== undefined &&
+                count === target.expectedCount &&
+                !state.gaps.length;
+        state.stalled =
+            count > before ? 0 : value.moreInDOM ? state.stalled : state.stalled + 1;
+        state.offset = value.moreInDOM
+            ? (value.offset ?? state.offset ?? 0) + (value.people?.length ?? 0)
+            : 0;
+        state.advance = !value.moreInDOM;
+        if (state.complete)
+            return null;
+        if (target.expectedCount !== undefined && count > target.expectedCount)
+            return "observed-count-changed";
+        return state.stalled >= 2 && value.atDocumentEnd !== false
+            ? "list-progress-stalled"
+            : null;
+    }
+    async result(job, reason) {
+        const following = Object.values(job.following.entries);
+        const mutual = following.filter((p) => Object.hasOwn(job.followers.entries, p.handle.toLowerCase()));
+        const absent = following.filter((p) => !Object.hasOwn(job.followers.entries, p.handle.toLowerCase()));
+        const complete = job.direction === "followback"
+            ? job.followers.complete
+            : job.following.complete && job.followers.complete;
+        const nonFollowers = job.followers.complete ? absent : [];
+        const provisional = job.followers.complete ? [] : absent;
+        const notFollowedBack = Object.values(job.followers.entries).filter((p) => p.relationship === "follows-you" ||
+            (p.listMembership === "followers" &&
+                p.relationship === "not-following") ||
+            (job.following.complete &&
+                !Object.hasOwn(job.following.entries, p.handle.toLowerCase())));
+        const observedAt = job.windows.at(-1)?.at ?? job.startedAt;
+        const evidenceRef = await this.#proof({
+            schema: "followback-audit/v1",
+            ...job,
+            observedAt,
+            complete,
+            reason,
+            mutual,
+            nonFollowers,
+            provisional,
+            notFollowedBack,
+        });
+        return {
+            direction: job.direction,
+            status: reason === "night-window"
+                ? "waiting"
+                : complete
+                    ? "observed"
+                    : "needsDecision",
+            scanId: job.scanId,
+            complete,
+            followingComplete: job.following.complete,
+            followersComplete: job.followers.complete,
+            followingCount: following.length,
+            followersCount: Object.keys(job.followers.entries).length,
+            mutualCount: mutual.length,
+            notFollowedBackCount: notFollowedBack.length,
+            nonFollowerCount: nonFollowers.length,
+            provisionalCount: provisional.length,
+            evidenceRef,
+            startedAt: job.startedAt,
+            observedAt,
+            ...(reason ? { reason } : {}),
+        };
+    }
+    async run(args) {
+        if (this.#running)
+            throw new Error("followback-audit-running");
+        const job = this.job(args);
+        job.direction = args.direction ?? job.direction ?? "both";
+        this.#running = true;
+        let reason = null;
+        try {
+            for (const kind of job.direction === "followback"
+                ? ["followers"]
+                : ["following", "followers"]) {
+                job[kind].stalled = 0;
+                for (let n = 0; n < (args.maxWindows ?? 100) && !job[kind].complete; n++) {
+                    if (!this.allowed(args)) {
+                        reason = "night-window";
+                        break;
+                    }
+                    reason = await this.window(job, kind);
+                    if (reason)
+                        break;
+                }
+                if (reason || !job[kind].complete) {
+                    reason ??= "window-budget-exhausted";
+                    break;
+                }
+            }
+            return await this.result(job, reason);
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+}

package/dist/growth-batch.d.ts

@@ -3,6 +3,6 @@ import type { GrowthDependencies } from "./growth-dependencies.js";
 export declare class FollowBatch {
     #private;
     constructor(dependencies: Pick<GrowthDependencies, "prepareActionsForCall" | "store" | "scope" | "stamp" | "clock" | "evidenceExists" | "executor" | "parallelRound" | "round">);
-    followBatch({ taskId, handles, preparedActions }?: any): Promise<BoundaryRecord>;
+    followBatch({ taskId, handles, preparedActions, pacing, }?: any): Promise<BoundaryRecord>;
 }
 export declare function createFollowBatch(...args: ConstructorParameters<typeof FollowBatch>): FollowBatch;

package/dist/growth-batch.js

@@ -1,6 +1,8 @@
+import { FollowBatchPacing } from "./follow-batch-pacing.js";
 import { followWindows, same } from "./growth-constants.js";
 import { followObservationAuthorized } from "./follow-observation-policy.js";
 export class FollowBatch {
+    #pacing;
     #prepareActionsForCall;
     #store;
     #scope;
@@ -11,6 +13,7 @@ export class FollowBatch {
     #parallelRound;
     #round;
     constructor(dependencies) {
+        this.#pacing = new FollowBatchPacing(dependencies.store, dependencies.clock);
         this.followBatch = this.followBatch.bind(this);
         const { prepareActionsForCall, store, scope, stamp, clock, evidenceExists, executor, parallelRound, round, } = dependencies;
         this.#prepareActionsForCall = prepareActionsForCall;
@@ -23,8 +26,9 @@ export class FollowBatch {
         this.#parallelRound = parallelRound;
         this.#round = round;
     }
-    async followBatch({ taskId, handles, preparedActions } = {}) {
+    async followBatch({ taskId, handles, preparedActions, pacing, } = {}) {
         const executor = this.#executor;
+        FollowBatchPacing.validate(pacing);
         if (!Array.isArray(handles) ||
             handles.length < 5 ||
             handles.length > 10 ||
@@ -47,6 +51,11 @@ export class FollowBatch {
             const previous = next.followBatches.findLast((b) => b.status !== "SETTLED" &&
                 b.handles.length === handles.length &&
                 b.handles.every((h, i) => same(h, handles[i])));
+            pacing ??=
+                previous?.pacing ??
+                    next.executions?.[executor?.id]?.followCadence?.intentPacing ??
+                    next.followCadence?.intentPacing;
+            FollowBatchPacing.validate(pacing);
             resumedBatch = Boolean(previous);
             batchId = previous?.id ?? `${taskId}-FOLLOW-${this.#stamp()}`;
             if (previous)
@@ -133,6 +142,7 @@ export class FollowBatch {
                 same(a.handle, handle) &&
                 a.status === "prepared"))
                 continue;
+            await this.#pacing.before(batchId, handle, pacing);
             result = await (executor ? this.#parallelRound : this.#round)({
                 taskId,
                 requestedKind: "follow",

package/dist/growth-execution.d.ts

@@ -8,8 +8,9 @@ import type { GrowthDependencies } from "./growth-dependencies.js";
 export declare class GrowthExecution {
     #private;
     execute: (snapshot: any, action: any) => Promise<ExecutionStep>;
-    constructor(dependencies: Pick<GrowthDependencies, "capability" | "platform" | "settleProof" | "clock" | "save" | "guardInput" | "waitBudget" | "authorizedWindow" | "stamp" | "store" | "executor" | "session">);
+    constructor(dependencies: Pick<GrowthDependencies, "capability" | "platform" | "settleProof" | "clock" | "save" | "guardInput" | "waitBudget" | "authorizedWindow" | "stamp" | "store" | "evidenceExists" | "executor" | "session">);
     private checkExecutionIdentity;
+    private actionIsActionable;
     private admitAction;
     private handleExecute;
 }

package/dist/growth-execution.js

@@ -1,3 +1,4 @@
+import { actionableForExecutor } from "./executor-actionability.js";
 import { operations, same } from "./growth-constants.js";
 export class GrowthExecution {
     #capability;
@@ -10,11 +11,12 @@ export class GrowthExecution {
     #authorizedWindow;
     #stamp;
     #store;
+    #evidenceExists;
     #executor;
     #session;
     execute;
     constructor(dependencies) {
-        const { capability, platform, settleProof, clock, save, guardInput, waitBudget, authorizedWindow, stamp, store, executor, session, } = dependencies;
+        const { capability, platform, settleProof, clock, save, guardInput, waitBudget, authorizedWindow, stamp, store, executor, evidenceExists, session, } = dependencies;
         this.#capability = capability;
         this.#platform = platform;
         this.#settleProof = settleProof;
@@ -26,6 +28,7 @@ export class GrowthExecution {
         this.#stamp = stamp;
         this.#store = store;
         this.#executor = executor;
+        this.#evidenceExists = evidenceExists;
         this.#session = session;
         this.execute = this.handleExecute.bind(this);
     }
@@ -59,10 +62,13 @@ export class GrowthExecution {
             };
         return null;
     }
+    actionIsActionable(state, kind) {
+        return actionableForExecutor(state, kind, this.#executor, this.#evidenceExists);
+    }
     async admitAction(snapshot, action) {
         const state = snapshot.state;
         const item = state.items.find((i) => i.kind === action.kind);
-        if (!item.actionable)
+        if (!this.actionIsActionable(state, action.kind))
             return {
                 snapshot,
                 need: {

package/dist/growth-state.js

@@ -1,3 +1,4 @@
+import { actionableForExecutor } from "./executor-actionability.js";
 import { checkRound } from "./round-state.js";
 import { kinds } from "./growth-constants.js";
 export class GrowthState {
@@ -80,7 +81,8 @@ export class GrowthState {
             const item = next.items.find((i) => i.kind === entry.kind);
             const reservation = before.status === "prepared" && after.status === "intent";
             if (reservation) {
-                if (!item.actionable || item.verified + item.unknown >= item.planned)
+                if (!actionableForExecutor(next, entry.kind, executor, this.#evidenceExists) ||
+                    item.verified + item.unknown >= item.planned)
                     throw new Error("shared-target-capacity-exhausted");
                 if (entry.kind === "follow" && this.#waitBudget(next))
                     throw new Error("shared-follow-budget-exhausted");

package/dist/growth.d.ts

@@ -4,7 +4,7 @@ export declare class GrowthHarness {
     verifyPublishedPost: ({ taskId, draftPath, publicURL, evidenceRef, sourceLink, sourceLinks, }: any) => Promise<any>;
     verifySubmission: ({ taskId, actionId }: any) => Promise<any>;
     verifyFollow: (target: any) => Promise<any>;
-    followBatch: ({ taskId, handles, preparedActions, }?: any) => Promise<import("./boundary.js").BoundaryRecord>;
+    followBatch: ({ taskId, handles, preparedActions, pacing, }?: any) => Promise<import("./boundary.js").BoundaryRecord>;
     preflight: ({ operation, input }: any) => any;
     readCreator: (args: any) => Promise<any>;
     readPeople: (args: any) => Promise<any>;

package/dist/growth.js

@@ -108,6 +108,7 @@ export class GrowthHarness {
         this.#settleProof = settleProof;
         this.#releaseSession = releaseSession;
         const { execute } = createGrowthExecution({
+            evidenceExists: this.#evidenceExists,
             capability: this.#capability,
             platform: this.#platform,
             settleProof: this.#settleProof,

package/dist/platform-capabilities.js

@@ -13,6 +13,8 @@ export class PlatformCapabilities {
         if (operation === "readCreator" &&
             typeof this.#browser.collectCreator !== "function")
             absent.push("browser.collectCreator");
+        if (operation === "readPeople" && input.reset)
+            absent.push(...(this.#browser.capabilities?.("resetPeople") ?? ["resetPeople"]));
         if (input.quoteTarget)
             absent.push(...(this.#browser.capabilities?.("openQuoteComposer") ?? [
                 "openQuoteComposer",

package/dist/platform-observation.js

@@ -39,7 +39,13 @@ export class PlatformObservation {
         catch {
             /* Blank/non-X pages require observed navigation. */
         }
-        if (!atTarget) {
+        const incompletePerson = atTarget &&
+            query.view === "person" &&
+            !value.alerts?.length &&
+            (value.needsStateCheck ||
+                (value.blue === null && value.blueEvidenceSupported !== false) ||
+                value.relationship === "unknown");
+        if (!atTarget || incompletePerson) {
             await this.#browser.act({
                 operation: "openObserved",
                 url: url.href,

package/dist/platform-targets.js

@@ -90,7 +90,7 @@ export class PlatformTargets {
             pageComplete: false,
         };
     }
-    async handleReadPeople({ target, offset = 0, limit = 5, advance = false, }) {
+    async handleReadPeople({ target, offset = 0, limit = 5, advance = false, bulk = false, reset = false, }) {
         const url = xURL(target?.url);
         if (!/^\/[A-Za-z0-9_]{1,15}\/(?:following|followers|verified_followers)\/?$/.test(url.pathname) ||
             url.search ||
@@ -100,17 +100,35 @@ export class PlatformTargets {
             offset < 0 ||
             !Number.isInteger(limit) ||
             limit < 1 ||
-            limit > 5 ||
+            limit > (bulk === true ? 1000 : 5) ||
             typeof advance !== "boolean")
             throw new Error("people-window-invalid");
-        let value = await this.#open(target, { view: "people", offset, limit });
-        if (advance) {
+        let value = await this.#open(target, {
+            view: "people",
+            offset,
+            limit,
+            bulk,
+        });
+        if (reset) {
+            if (value.page !== url.href || value.alerts?.length)
+                return { ...value, complete: false };
+            await this.#browser.act({ operation: "nextPeople", reset: true });
+            value = await this.#ready({ view: "people", offset: 0, limit, bulk });
+            if (value.atDocumentStart !== true)
+                return {
+                    ...value,
+                    complete: false,
+                    needsStateCheck: true,
+                    missing: [...(value.missing ?? []), "people-list-start-unconfirmed"],
+                };
+        }
+        if (advance && !reset) {
             if (value.needsStateCheck ||
                 value.alerts?.length ||
                 !value.people?.length)
                 return { ...value, complete: false };
             await this.#browser.act({ operation: "nextPeople" });
-            value = await this.#ready({ view: "people", offset: 0, limit });
+            value = await this.#ready({ view: "people", offset: 0, limit, bulk });
         }
         if (!value.page || xURL(value.page).href !== url.href)
             return {

package/dist/readers-profile.d.ts

@@ -1,3 +1,3 @@
 export declare function readProfile({ handle }?: any): any;
-export declare function readPeople({ offset, limit }?: any): any;
+export declare function readPeople({ offset, limit, bulk, }?: any): any;
 export declare function screenCandidates(profiles: any, { minRatio }?: any): any;

package/dist/readers-profile.js

@@ -78,15 +78,29 @@ export function readProfile({ handle } = {}) {
     };
 }
 // Bounded visible person cells for a currently loaded follower/following list.
-export function readPeople({ offset = 0, limit = 5 } = {}) {
+export function readPeople({ offset = 0, limit = 5, bulk = false, } = {}) {
     if (!Number.isInteger(offset) ||
         offset < 0 ||
         !Number.isInteger(limit) ||
         limit < 1 ||
-        limit > 5)
+        limit > (bulk === true ? 1000 : 5))
         throw new Error("人物窗口须为非负offset及1–5 limit");
     const visible = (el) => el.getClientRects().length > 0;
-    const cells = Array.from(document.querySelectorAll('main [data-testid="primaryColumn"] [data-testid="UserCell"]')).filter(visible);
+    const suffix = new URL(location.href).pathname
+        .split("/")
+        .filter(Boolean)
+        .at(-1);
+    const labelsByList = {
+        following: ["时间线：正在关注", "Timeline: Following"],
+        followers: ["时间线：关注者", "Timeline: Followers"],
+        verified_followers: ["时间线：认证关注者", "Timeline: Verified followers"],
+    };
+    const scopes = Array.from(document.querySelectorAll('main [data-testid="primaryColumn"] [aria-label]')).filter((e) => visible(e) &&
+        (labelsByList[suffix ?? ""] ?? []).includes(e.getAttribute("aria-label")));
+    const scope = scopes.length === 1 ? scopes[0] : null;
+    const cells = Array.from(scope
+        ? scope.querySelectorAll('[data-testid="UserCell"]')
+        : document.querySelectorAll('main [data-testid="primaryColumn"] [data-testid="UserCell"]')).filter(visible);
     const people = cells.slice(offset, offset + limit).map((cell) => {
         const links = Array.from(cell.querySelectorAll("a[href]"))
             .filter(visible)
@@ -102,7 +116,17 @@ export function readPeople({ offset = 0, limit = 5 } = {}) {
                 .map((a) => a.href?.match(/^\/([A-Za-z0-9_]{1,15})$/)?.[1])
                 .filter(Boolean)),
         ];
-        const handle = handles.length === 1 ? String(handles[0]) : null;
+        const controlHandles = [
+            ...new Set(buttons
+                .map((b) => b.label.match(/^(?:正在关注|取消关注|回关|关注) @([A-Za-z0-9_]{1,15})$/)?.[1])
+                .filter(Boolean)),
+        ];
+        const bound = controlHandles.length === 1 && handles.includes(controlHandles[0]);
+        const handle = bound
+            ? String(controlHandles[0])
+            : handles.length === 1 && !controlHandles.length
+                ? String(handles[0])
+                : null;
         const badges = Array.from(cell.querySelectorAll('svg[data-testid="icon-verified"]')).filter(visible);
         const blue = badges.length === 1
             ? [
@@ -147,14 +171,53 @@ export function readPeople({ offset = 0, limit = 5 } = {}) {
             url: handle ? "https://x.com/" + handle : null,
             blue,
             relationship,
+            followsYou: Array.from(cell.querySelectorAll('[data-testid="userFollowIndicator"]'))
+                .filter(visible)
+                .some((e) => /^(?:关注了你|Follows you)$/i.test(e.innerText?.trim() ?? e.textContent?.trim() ?? "")),
             biography,
         };
     });
+    const inViewport = cells.filter((cell) => {
+        if (typeof cell.getBoundingClientRect !== "function")
+            return false;
+        const rect = cell.getBoundingClientRect();
+        return rect.top > 100 && rect.bottom < window.innerHeight - 60;
+    });
+    const anchorCell = inViewport.at(-1);
+    const anchorLabels = anchorCell
+        ? Array.from(anchorCell.querySelectorAll("button"))
+            .filter(visible)
+            .map((b) => b.getAttribute("aria-label") || b.innerText)
+        : [];
+    const anchorButton = anchorCell
+        ? Array.from(anchorCell.querySelectorAll("button")).find((b) => /^(?:正在关注|取消关注|回关|关注) @/.test(b.getAttribute("aria-label") || b.innerText))
+        : null;
+    const anchorHeight = anchorButton?.getBoundingClientRect?.().height;
+    const anchorPages = anchorHeight > 0
+        ? Math.max(1, Math.min(20, Math.floor((window.innerHeight - 200) / anchorHeight)))
+        : 1;
+    const anchorHandles = [
+        ...new Set(anchorLabels
+            .map((label) => label.match(/^(?:正在关注|取消关注|回关|关注) @([A-Za-z0-9_]{1,15})$/)?.[1])
+            .filter(Boolean)),
+    ];
     return {
         page: location.href,
         people,
+        listBound: Boolean(scope),
+        scrollAnchor: anchorHandles.length === 1
+            ? { handle: anchorHandles[0], pages: anchorPages }
+            : null,
         offset,
         renderedPeople: cells.length,
+        atDocumentStart: typeof document.scrollingElement?.scrollTop === "number"
+            ? document.scrollingElement.scrollTop <= 3
+            : null,
+        atDocumentEnd: typeof document.scrollingElement?.scrollTop === "number"
+            ? document.scrollingElement.scrollTop +
+                document.scrollingElement.clientHeight >=
+                document.scrollingElement.scrollHeight - 3
+            : null,
         moreInDOM: offset + limit < cells.length,
         pageComplete: false,
         needsStateCheck: !people.length,

package/dist/types.d.ts

@@ -132,6 +132,46 @@ export interface ReadResult {
     unchangedIds?: string[];
     creator?: CreatorEvidence;
 }
+export interface FollowbackAuditOptions {
+    direction?: "both" | "followback";
+    /** Explicit user permission for this read task during 00–07; never authorizes writes. */
+    nightReadAuthorization?: {
+        userAuthorized: boolean;
+        evidenceRef: EvidenceRef;
+        expiresAt: string;
+    };
+    following: {
+        url: string;
+        evidenceRef: EvidenceRef;
+        expectedCount?: number;
+    };
+    followers: {
+        url: string;
+        evidenceRef: EvidenceRef;
+        expectedCount?: number;
+    };
+    maxWindows?: number;
+    scanId?: string;
+    resumeEvidenceRef?: EvidenceRef;
+}
+export interface FollowbackAuditResult {
+    direction: "both" | "followback";
+    status: "observed" | "needsDecision" | "waiting";
+    scanId: string;
+    complete: boolean;
+    followingComplete: boolean;
+    followersComplete: boolean;
+    followingCount: number;
+    followersCount: number;
+    mutualCount: number;
+    notFollowedBackCount: number;
+    nonFollowerCount: number;
+    provisionalCount: number;
+    evidenceRef: EvidenceRef;
+    startedAt: string;
+    observedAt: string;
+    reason?: string;
+}
 export interface PeopleOptions {
     target: {
         url: string;
@@ -407,7 +447,12 @@ export interface ReplyOptions {
         kind: "reply";
     }>;
 }
+export interface FollowPacing {
+    minGapMs: number;
+    maxGapMs: number;
+}
 export interface FollowOptions {
+    pacing?: FollowPacing;
     taskId: string;
     handles: string[];
     preparedActions?: Extract<PreparedAction, {
@@ -515,6 +560,7 @@ export interface XGrowthHarness {
     likeIncomingBatch(args: IncomingLikeOptions): Promise<IncomingLikeResult>;
     readCreator(args: CreatorOptions): Promise<ReadResult>;
     readPeople(args: PeopleOptions): Promise<ReadResult>;
+    readFollowbackAudit(args: FollowbackAuditOptions): Promise<FollowbackAuditResult>;
     readBookmarks(args: BookmarkOptions): Promise<ReadResult>;
     searchSources(args: SearchOptions): Promise<ReadResult>;
     readIncomingReplies(args?: IncomingReplyOptions): Promise<ReadResult>;

package/generated/observation.mjs

@@ -205,15 +205,29 @@ export const readXObservation = (query) => {
         observedAt: new Date().toISOString(),
     };
 };
-  const readPeople = function readPeople({ offset = 0, limit = 5 } = {}) {
+  const readPeople = function readPeople({ offset = 0, limit = 5, bulk = false, } = {}) {
     if (!Number.isInteger(offset) ||
         offset < 0 ||
         !Number.isInteger(limit) ||
         limit < 1 ||
-        limit > 5)
+        limit > (bulk === true ? 1000 : 5))
         throw new Error("人物窗口须为非负offset及1–5 limit");
     const visible = (el) => el.getClientRects().length > 0;
-    const cells = Array.from(document.querySelectorAll('main [data-testid="primaryColumn"] [data-testid="UserCell"]')).filter(visible);
+    const suffix = new URL(location.href).pathname
+        .split("/")
+        .filter(Boolean)
+        .at(-1);
+    const labelsByList = {
+        following: ["时间线：正在关注", "Timeline: Following"],
+        followers: ["时间线：关注者", "Timeline: Followers"],
+        verified_followers: ["时间线：认证关注者", "Timeline: Verified followers"],
+    };
+    const scopes = Array.from(document.querySelectorAll('main [data-testid="primaryColumn"] [aria-label]')).filter((e) => visible(e) &&
+        (labelsByList[suffix ?? ""] ?? []).includes(e.getAttribute("aria-label")));
+    const scope = scopes.length === 1 ? scopes[0] : null;
+    const cells = Array.from(scope
+        ? scope.querySelectorAll('[data-testid="UserCell"]')
+        : document.querySelectorAll('main [data-testid="primaryColumn"] [data-testid="UserCell"]')).filter(visible);
     const people = cells.slice(offset, offset + limit).map((cell) => {
         const links = Array.from(cell.querySelectorAll("a[href]"))
             .filter(visible)
@@ -229,7 +243,17 @@ export const readXObservation = (query) => {
                 .map((a) => a.href?.match(/^\/([A-Za-z0-9_]{1,15})$/)?.[1])
                 .filter(Boolean)),
         ];
-        const handle = handles.length === 1 ? String(handles[0]) : null;
+        const controlHandles = [
+            ...new Set(buttons
+                .map((b) => b.label.match(/^(?:正在关注|取消关注|回关|关注) @([A-Za-z0-9_]{1,15})$/)?.[1])
+                .filter(Boolean)),
+        ];
+        const bound = controlHandles.length === 1 && handles.includes(controlHandles[0]);
+        const handle = bound
+            ? String(controlHandles[0])
+            : handles.length === 1 && !controlHandles.length
+                ? String(handles[0])
+                : null;
         const badges = Array.from(cell.querySelectorAll('svg[data-testid="icon-verified"]')).filter(visible);
         const blue = badges.length === 1
             ? [
@@ -274,14 +298,53 @@ export const readXObservation = (query) => {
             url: handle ? "https://x.com/" + handle : null,
             blue,
             relationship,
+            followsYou: Array.from(cell.querySelectorAll('[data-testid="userFollowIndicator"]'))
+                .filter(visible)
+                .some((e) => /^(?:关注了你|Follows you)$/i.test(e.innerText?.trim() ?? e.textContent?.trim() ?? "")),
             biography,
         };
     });
+    const inViewport = cells.filter((cell) => {
+        if (typeof cell.getBoundingClientRect !== "function")
+            return false;
+        const rect = cell.getBoundingClientRect();
+        return rect.top > 100 && rect.bottom < window.innerHeight - 60;
+    });
+    const anchorCell = inViewport.at(-1);
+    const anchorLabels = anchorCell
+        ? Array.from(anchorCell.querySelectorAll("button"))
+            .filter(visible)
+            .map((b) => b.getAttribute("aria-label") || b.innerText)
+        : [];
+    const anchorButton = anchorCell
+        ? Array.from(anchorCell.querySelectorAll("button")).find((b) => /^(?:正在关注|取消关注|回关|关注) @/.test(b.getAttribute("aria-label") || b.innerText))
+        : null;
+    const anchorHeight = anchorButton?.getBoundingClientRect?.().height;
+    const anchorPages = anchorHeight > 0
+        ? Math.max(1, Math.min(20, Math.floor((window.innerHeight - 200) / anchorHeight)))
+        : 1;
+    const anchorHandles = [
+        ...new Set(anchorLabels
+            .map((label) => label.match(/^(?:正在关注|取消关注|回关|关注) @([A-Za-z0-9_]{1,15})$/)?.[1])
+            .filter(Boolean)),
+    ];
     return {
         page: location.href,
         people,
+        listBound: Boolean(scope),
+        scrollAnchor: anchorHandles.length === 1
+            ? { handle: anchorHandles[0], pages: anchorPages }
+            : null,
         offset,
         renderedPeople: cells.length,
+        atDocumentStart: typeof document.scrollingElement?.scrollTop === "number"
+            ? document.scrollingElement.scrollTop <= 3
+            : null,
+        atDocumentEnd: typeof document.scrollingElement?.scrollTop === "number"
+            ? document.scrollingElement.scrollTop +
+                document.scrollingElement.clientHeight >=
+                document.scrollingElement.scrollHeight - 3
+            : null,
         moreInDOM: offset + limit < cells.length,
         pageComplete: false,
         needsStateCheck: !people.length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/x-harness",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "type": "module",
   "description": "Typed X task harness with compact business results and explicit diagnostics.",
   "main": "./dist/index.js",
@@ -42,5 +42,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6e70dc4b7351bc7ec59936ed517465133001099b"
+  "gitHead": "ece6b7ad7f4355d105ed6ec939bbcd8c136b4ce1"
 }

package/skill/SKILL.md

@@ -6,7 +6,7 @@ description: Use X through task APIs with compact receipts, complete target evid
 
 # X Harness
 
-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.
+Use root API/current task reference. Normal use needs no implementation source or type-file reading.
 
 ## Bind once
 
@@ -25,6 +25,7 @@ var x = createXGrowthHarness({ tab, ledgerPath, proofDirectory });
 | Current need | Read only |
 | --- | --- |
 | Creator/bookmarks/search/post/person/feedback/account | [reads](references/reads.md) |
+| Followback list audit | [audit](references/followback-audit.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) |
 

package/skill/references/followback-audit.md

@@ -0,0 +1,17 @@
+# Followback list audit
+
+`x.readFollowbackAudit({following,followers,maxWindows?,scanId?,nightReadAuthorization?})` reads lists only. `direction:"followback"` scans followers alone and uses exact follows-you controls; complete then means the observed follower count matched, not both lists. Default "both" retains two-list coverage. Each target is `{url,evidenceRef,expectedCount?}` from the same observed account profile: following and **unfiltered** followers URLs, exact counters only. `verified_followers` is a subset and is rejected. A missing/rounded counter cannot establish full coverage. No profile-per-person opening, follow or unfollow is performed.
+
+One call scans bulk visible rows (up to 1,000 per observation; remaining DOM offsets are consumed before scrolling) and serially advances the original list; no model-driven five-person loop. maxWindows defaults to 100 per list, range 1–1000. Resume via scanId with identical targets; a new instance also requires resumeEvidenceRef pointing to the original immutable checkpoint. Keep the list tab at its original position; a changed/new tab must restart conservatively. Full immutable observations and checkpoint go to the existing proof directory; the receipt gives counts, completeness and evidenceRef. Read that local proof for lists or export it without dumping all rows into model context.
+
+Proof arrays: `mutual`, `nonFollowers` (we follow, they do not), `notFollowedBack` (they follow, we do not), `provisional` (following entries absent from incomplete followers). `notFollowedBack` uses exact follows-you controls, or count-matched following coverage; nonFollowers requires count-matched unfiltered followers. Never treat provisional as confirmed negative. Default direction requires both count-matched lists; followback direction requires the unfiltered follower count to match. Scoped follower-list membership with an exact not-following control also establishes a positive candidate. Counts can change while scanning; the result is an observation interval, not an atomic or permanent relationship guarantee. Check exact relationship again before any write.
+
+Alerts, wrong routes, unreadable rows, stall and window exhaustion retain incomplete proof; resume without assuming a virtualized tail means all. Missing own following controls remain a coverage gap. Shanghai 00–07 stops each new window. Only explicit human permission for this task/time can set `nightReadAuthorization:{userAuthorized:true,evidenceRef,expiresAt}` with an existing local user-authorization proof; this permits this audit's reads only, never writes or other tasks. It is not an SDK-wide technical lock.
+
+To actually follow back, load the matching writes reference, review candidates under the original project authorization, register original stable IDs, and use followBatch. This audit grants no relationship-write permission or quota exemption.
+
+Optional followBatch `pacing:{minGapMs,maxGapMs}` uses bounded 5–30 second ranges. Gaps are sampled once per original batch handle, persisted and reused on resume; it waits from the latest actual follow attempt. The normal round guards recheck after the wait. Pacing does not waive refusal/backoff/budgets or guarantee platform acceptance.
+
+Each newly started list resets through native Chrome Control+Home and verifies the DOM start before collecting rows. A saved checkpoint resumes the original position. Counter changes require a different existing reviewed evidenceRef for the same URLs; counter revisions are retained in the proof. A stall with an unmatched counter remains incomplete, even at the visible tail.
+
+On followBatch resume, persisted batch pacing wins; otherwise an omitted pacing option can use the original executor/account followCadence.intentPacing. Existing refusal, unknown and rolling-budget guards still apply.

package/skill/references/writes.md

@@ -93,3 +93,7 @@ Review an existing action with decision:{actionId,approved,evidenceRef,approvedT
 `likeIncomingBatch({batchId,targets:[{postId,url,evidenceRef,author,incomingEvidenceRef}],sampleRate:0.3})` samples once per stable batch (1–5 observed received comments), retains selection in the original ledger, serially likes and verifies exact public state. Existing likes never toggle. Each fresh click has a 30-second minimum gap; waiting returns resumeAt rather than polling. Unknown intent freezes that object. No reply-goal credit or guarantee against platform restrictions; alerts stop the batch.
 
 Optional executor.replyEmojiPolicy={sampleRate,maxInRecent} gates new reply drafts: stable original-ID sampling, no consecutive emoji, at most maxInRecent in the latest ten intents/unknown/verified replies. Plain text remains allowed; existing unknown recovery is unchanged.
+
+## Executor-local read restrictions
+
+A non-actionable item remains account-wide unless its original ledger explicitly records `executionRestriction:{scope:'executor',executorId,reason,evidenceRef}`. The exact current reason and evidence in `blockEvidence` must match, and the restricting executor must exist with the same kind. Another authorized executor can proceed through the root API with its own identity/source proof; the affected executor stays blocked. Missing/stale scope proof, shared capacity, alerts, windows, pacing, quality and unknown guards still reject. Do not infer locality from a message or silently clear another executor's marker.