@nextclaw/x-harness 0.2.65 → 0.2.67

package/SOURCE.md

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

package/dist/api.d.ts

@@ -82,6 +82,7 @@ export declare class BusinessHarness implements XGrowthHarness {
         diagnostic?: undefined;
     }>;
     searchSources(args: import("./types.js").SearchOptions): Promise<ReadResult>;
+    readExploreRecommendations(args?: import("./types.js").ExploreRecommendationOptions): Promise<ReadResult>;
     readPost({ target, mode, includeContext, includeThread, resolveQuote, }: {
         includeContext?: boolean;
         includeThread?: boolean;

package/dist/api.js

@@ -33,6 +33,8 @@ export class BusinessHarness {
         this.readIncomingConversations = this.readIncomingConversations.bind(this);
         this.readIncomingReplies = this.readIncomingReplies.bind(this);
         this.searchSources = this.searchSources.bind(this);
+        this.readExploreRecommendations =
+            this.readExploreRecommendations.bind(this);
         this.readBookmarks = this.readBookmarks.bind(this);
         this.readCreator = this.readCreator.bind(this);
         const { store, platform } = dependencies;
@@ -599,6 +601,9 @@ export class BusinessHarness {
     searchSources(args) {
         return this.read("searchSources", args, args.mode);
     }
+    readExploreRecommendations(args = {}) {
+        return this.read("readExploreRecommendations", args, args.mode);
+    }
     readPost({ target, mode, includeContext, includeThread, resolveQuote, }) {
         return this.read("readPost", { ...target, includeContext, includeThread, resolveQuote }, mode);
     }

package/dist/browser-dom-capabilities.js

@@ -45,7 +45,12 @@ export class DOMCapabilities {
         if (operation === "readCreator") {
             return this.creatorCapabilities(base, operation);
         }
-        if (["readBookmarks", "searchSources", "readFeedback"].includes(operation)) {
+        if ([
+            "readBookmarks",
+            "searchSources",
+            "readExploreRecommendations",
+            "readFeedback",
+        ].includes(operation)) {
             return this.collectionCapabilities(base, operation);
         }
         if (operation !== "read")

package/dist/browser-dom-editing.js

@@ -486,7 +486,8 @@ export class DOMEditing {
         if (names.length !== 1)
             throw new Error("回复按钮未唯一观察");
         const primary = result.posts[0].primary;
-        if (!primary || primary.match(/\/status\/(\d+)$/)?.[1] !== command.postId)
+        if (!primary ||
+            primary.match(/\/status\/(\d+)(?:\/history)?$/)?.[1] !== command.postId)
             throw new Error("回复主帖永久链接未绑定");
         const article = this.#locator("article").filter({
             has: this.#tab.playwright.locator(`a[href=${JSON.stringify(primary)}]`),

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

@@ -3,6 +3,7 @@ export declare class DOMNavigation {
     #private;
     openQuote: (command: any) => Promise<any>;
     searchSources: (command: any) => Promise<void>;
+    openExploreRecommendations: (command: any) => Promise<void>;
     waitForFolder: (command: any) => Promise<void>;
     waitForPosts: (command: any) => Promise<void>;
     openObserved: (command: any) => Promise<void>;
@@ -11,6 +12,7 @@ export declare class DOMNavigation {
     constructor(dependencies: Pick<DOMDependencies, "session" | "tab" | "observe">);
     private handleOpenQuote;
     private handleSearchSources;
+    private handleOpenExploreRecommendations;
     private handleWaitForFolder;
     private handleWaitForPosts;
     private handleOpenObserved;

package/dist/browser-dom-navigation.js

@@ -5,6 +5,7 @@ export class DOMNavigation {
     #observe;
     openQuote;
     searchSources;
+    openExploreRecommendations;
     waitForFolder;
     waitForPosts;
     openObserved;
@@ -17,6 +18,8 @@ export class DOMNavigation {
         this.#observe = observe;
         this.openQuote = this.handleOpenQuote.bind(this);
         this.searchSources = this.handleSearchSources.bind(this);
+        this.openExploreRecommendations =
+            this.handleOpenExploreRecommendations.bind(this);
         this.waitForFolder = this.handleWaitForFolder.bind(this);
         this.waitForPosts = this.handleWaitForPosts.bind(this);
         this.openObserved = this.handleOpenObserved.bind(this);
@@ -70,6 +73,10 @@ export class DOMNavigation {
             await this.#tab.goto(destination);
         return;
     }
+    async handleOpenExploreRecommendations() {
+        this.#session.current = null;
+        await this.#tab.goto("https://x.com/explore");
+    }
     async handleWaitForFolder(command) {
         if (command.selected) {
             await this.#tab.playwright
@@ -230,7 +237,7 @@ export class DOMNavigation {
             const articles = this.#tab.playwright.getByRole("article");
             const detail = /^\/\w{1,15}\/status\/\d+$/.test(path)
                 ? articles.filter({
-                    has: this.#tab.playwright.locator(`a[href=${JSON.stringify(path)}]`),
+                    has: this.#tab.playwright.locator(`a[href=${JSON.stringify(path)}],a[href=${JSON.stringify(path + "/history")}]`),
                 })
                 : articles;
             await this.handleWaitTargetContent(detail.first(), command.url);

package/dist/browser-native.js

@@ -170,7 +170,13 @@ export class NativeXBrowser {
     capabilities(operation) {
         if (operation === "readPeople")
             return ["native-people-blue-evidence"];
-        if (["readBookmarks", "searchSources", "readFeedback", "likePost"].includes(operation))
+        if ([
+            "readBookmarks",
+            "searchSources",
+            "readExploreRecommendations",
+            "readFeedback",
+            "likePost",
+        ].includes(operation))
             return [`native.${operation}`];
         const names = operation === "read"
             ? ["getAXState"]

package/dist/growth-execution.d.ts

@@ -12,6 +12,7 @@ export declare class GrowthExecution {
     private checkExecutionIdentity;
     private actionIsActionable;
     private admitAction;
+    private readSubmissionWithURLContinuation;
     private handleExecute;
 }
 export declare function createGrowthExecution(...args: ConstructorParameters<typeof GrowthExecution>): GrowthExecution;

package/dist/growth-execution.js

@@ -176,7 +176,7 @@ export class GrowthExecution {
         if (action.kind !== "follow") {
             let baseline;
             try {
-                baseline = await this.#platform.findSubmission({ ...action, intentAt: this.#stamp() }, { phase: "baseline" });
+                baseline = await this.readSubmissionWithURLContinuation({ ...action, intentAt: this.#stamp() }, { phase: "baseline" });
             }
             catch (error) {
                 return {
@@ -202,6 +202,23 @@ export class GrowthExecution {
         }
         return { beforeIds };
     }
+    async readSubmissionWithURLContinuation(action, context) {
+        try {
+            return await this.#platform.findSubmission(action, context);
+        }
+        catch (error) {
+            const preparedBaseline = context?.phase === "baseline";
+            const observedReceipt = !context &&
+                action.observedPublicURL &&
+                this.#evidenceExists(action.observedPublicEvidenceRef);
+            if (action.kind !== "reply" ||
+                !(preparedBaseline || observedReceipt) ||
+                !/Timed out waiting for URL/.test(String(error?.message ?? "")))
+                throw error;
+            // Continue only this read; the existing admission and receipt gates stay intact.
+            return this.#platform.findSubmission(action, context);
+        }
+    }
     async handleExecute(snapshot, action) {
         const executor = this.#executor;
         const recovering = ["intent", "unknown"].includes(action.status);
@@ -215,7 +232,7 @@ export class GrowthExecution {
         if (recovering) {
             let observation;
             try {
-                observation = await this.#platform.findSubmission(action);
+                observation = await this.readSubmissionWithURLContinuation(action);
             }
             catch (error) {
                 observation = {

package/dist/growth-tasks.d.ts

@@ -10,6 +10,7 @@ export declare class GrowthTasks {
     readPerson(args: any): Promise<any>;
     readBookmarks(args: any): Promise<any>;
     searchSources(args: any): Promise<any>;
+    readExploreRecommendations(args?: any): Promise<any>;
     readFeedback(args: any): Promise<any>;
     runGrowthRound(args: any): Promise<any>;
     resumeGrowthRound(args: any): Promise<any>;

package/dist/growth-tasks.js

@@ -19,6 +19,8 @@ export class GrowthTasks {
         this.runGrowthRound = this.runGrowthRound.bind(this);
         this.readFeedback = this.readFeedback.bind(this);
         this.searchSources = this.searchSources.bind(this);
+        this.readExploreRecommendations =
+            this.readExploreRecommendations.bind(this);
         this.readBookmarks = this.readBookmarks.bind(this);
         this.readPerson = this.readPerson.bind(this);
         this.readPeople = this.readPeople.bind(this);
@@ -40,7 +42,13 @@ export class GrowthTasks {
     }
     preflight({ operation, input = {} }) {
         const executor = this.#executor;
-        if (["readPeople", "readBookmarks", "searchSources", "readFeedback"].includes(operation))
+        if ([
+            "readPeople",
+            "readBookmarks",
+            "searchSources",
+            "readExploreRecommendations",
+            "readFeedback",
+        ].includes(operation))
             return this.#platform.preflight({ operation, input });
         if (["inspectRound", "verifySubmission"].includes(operation))
             return this.#capability("read", input);
@@ -110,6 +118,9 @@ export class GrowthTasks {
     searchSources(args) {
         return this.#readTask("searchSources", args);
     }
+    readExploreRecommendations(args = {}) {
+        return this.#readTask("readExploreRecommendations", args);
+    }
     readFeedback(args) {
         return this.#readTask("readFeedback", args);
     }

package/dist/growth.d.ts

@@ -13,6 +13,7 @@ export declare class GrowthHarness {
     readPerson: (args: any) => Promise<any>;
     readBookmarks: (args: any) => Promise<any>;
     searchSources: (args: any) => Promise<any>;
+    readExploreRecommendations: (args?: any) => Promise<any>;
     readFeedback: (args: any) => Promise<any>;
     runGrowthRound: (args: any) => Promise<any>;
     resumeGrowthRound: (args: any) => Promise<any>;

package/dist/growth.js

@@ -51,6 +51,7 @@ export class GrowthHarness {
     readPerson;
     readBookmarks;
     searchSources;
+    readExploreRecommendations;
     readFeedback;
     runGrowthRound;
     resumeGrowthRound;

package/dist/platform-collections.d.ts

@@ -4,6 +4,7 @@ export declare class PlatformCollections {
     collectSources: ({ processedIds, maxPages, limit }?: any) => Promise<any>;
     readCreator: (args: import("./types.js").CreatorOptions) => Promise<any>;
     readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
+    readExploreRecommendations: (args?: import("./types.js").ExploreRecommendationOptions) => Promise<any>;
     searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
     constructor(dependencies: Pick<PlatformDependencies, "ready" | "observed" | "browser" | "choose">);
     private handleCollectSources;
@@ -15,5 +16,6 @@ export declare class PlatformCollections {
     private bookmarkDiscovery;
     private waitForBookmarkLabel;
     private handleSearchSources;
+    private handleReadExploreRecommendations;
 }
 export declare function createPlatformCollections(...args: ConstructorParameters<typeof PlatformCollections>): PlatformCollections;

package/dist/platform-collections.js

@@ -1,4 +1,15 @@
 import { xURL, source } from "./platform-rules.js";
+const exploreNavigationEvidence = (nav) => ({
+    page: nav.page,
+    headings: (nav.headings ?? []).slice(0, 5),
+    tabs: (nav.controls ?? [])
+        .filter((control) => control.role === "tab")
+        .slice(0, 8)
+        .map((control) => ({
+        label: control.label,
+        selected: control.selected === true,
+    })),
+});
 export class PlatformCollections {
     #ready;
     #observed;
@@ -7,6 +18,7 @@ export class PlatformCollections {
     collectSources;
     readCreator;
     readBookmarks;
+    readExploreRecommendations;
     searchSources;
     constructor(dependencies) {
         const { ready, observed, browser, choose } = dependencies;
@@ -18,6 +30,8 @@ export class PlatformCollections {
         this.readCreator = this.handleReadCreator.bind(this);
         this.readBookmarks = this.handleReadBookmarks.bind(this);
         this.searchSources = this.handleSearchSources.bind(this);
+        this.readExploreRecommendations =
+            this.handleReadExploreRecommendations.bind(this);
     }
     async handleCollectSources({ processedIds = [], maxPages = 3, limit = 1, } = {}) {
         if (!Array.isArray(processedIds) ||
@@ -439,6 +453,134 @@ export class PlatformCollections {
             };
         return { ...value, query };
     }
+    async handleReadExploreRecommendations({ limit = 3, maxPages = 1, processedIds = [], } = {}) {
+        await this.#browser.act({ operation: "openExploreRecommendations" });
+        let nav = await this.#ready({ view: "navigation" });
+        const page = (value) => {
+            try {
+                const url = xURL(value);
+                return url.pathname.replace(/\/+$/, "") === "/explore" ? url : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        const entryPage = page(nav.page);
+        if (!entryPage)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: nav.page,
+                missing: ["explore-page-unconfirmed"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        if (!nav.alerts?.length && nav.needsStateCheck) {
+            try {
+                await this.#browser.act({ operation: "waitForPosts" });
+            }
+            catch (error) {
+                if (!/timed out|timeout/i.test(error.message))
+                    throw error;
+            }
+            nav = await this.#ready({ view: "navigation" });
+        }
+        if (nav.alerts?.length)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: nav.page,
+                missing: ["platform-alert"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        if (nav.needsStateCheck) {
+            const diagnosticRead = await this.handleCollectSources({
+                limit,
+                maxPages,
+                processedIds,
+            });
+            const sameExplorePage = page(diagnosticRead.page);
+            return {
+                ...diagnosticRead,
+                status: "needsDecision",
+                complete: false,
+                missing: [
+                    ...new Set([
+                        "explore-navigation-unconfirmed",
+                        ...(!sameExplorePage ? ["explore-page-changed-during-read"] : []),
+                        ...(diagnosticRead.missing ?? []),
+                    ]),
+                ],
+                sources: sameExplorePage ? (diagnosticRead.sources ?? []) : [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        }
+        const recommended = (nav.controls ?? []).filter((control) => control.role === "tab" &&
+            ["为你推荐", "For you"].includes(control.label.split("\n")[0]));
+        if (recommended.length !== 1)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: entryPage.href,
+                missing: ["explore-recommended-tab-unconfirmed"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        const expectedLabel = recommended[0].label.split("\n")[0];
+        if (!recommended[0].selected &&
+            !(await this.#choose(nav, (control) => control.role === "tab" &&
+                control.label.split("\n")[0] === expectedLabel)))
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: entryPage.href,
+                missing: ["explore-recommended-tab-selection-unavailable"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        nav = await this.#ready({ view: "navigation" });
+        const selected = (nav.controls ?? []).filter((control) => control.role === "tab" &&
+            control.label.split("\n")[0] === expectedLabel &&
+            control.selected);
+        if (!page(nav.page) ||
+            nav.needsStateCheck ||
+            nav.alerts?.length ||
+            selected.length !== 1)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: nav.page,
+                missing: ["explore-recommended-tab-selection-unconfirmed"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        const value = await this.handleCollectSources({
+            limit,
+            maxPages,
+            processedIds,
+        });
+        if (!page(value.page))
+            return {
+                ...value,
+                status: "needsDecision",
+                complete: false,
+                missing: ["explore-page-changed-during-read"],
+            };
+        return {
+            ...value,
+            sourceOrigin: {
+                kind: "explore-recommendations",
+                page: entryPage.href,
+                selectedTab: expectedLabel,
+            },
+        };
+    }
 }
 export function createPlatformCollections(...args) {
     return new PlatformCollections(...args);

package/dist/platform-dependencies.d.ts

@@ -19,6 +19,7 @@ export interface PlatformDependencies {
         media: any;
         links: any;
         needsExpansion: any;
+        metrics: string[];
         missing: any[];
     };
     collectSources: ({ processedIds, maxPages, limit }?: any) => Promise<any>;
@@ -28,6 +29,7 @@ export interface PlatformDependencies {
     readAccount: () => Promise<any>;
     readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
     searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
+    readExploreRecommendations: (args?: import("./types.js").ExploreRecommendationOptions) => Promise<any>;
     readFeedback: ({ targets, replyLimit }?: any) => Promise<any>;
     readPerson: (target: any) => Promise<any>;
     readPost: (target: any) => Promise<any>;

package/dist/platform-rules.js

@@ -34,7 +34,13 @@ export const source = (post, page) => ({
     images: post.images ?? [],
     media: post.media ?? [],
     links: post.links ?? [],
-    metrics: [...(post.buttons ?? []), ...(post.metrics ?? [])],
+    metrics: [
+        ...new Set([...(post.buttons ?? []), ...(post.metrics ?? [])]
+            .map((metric) => typeof metric === "string" ? metric : metric?.label)
+            .filter((label) => typeof label === "string" &&
+            /(?:回复|转帖|喜欢|书签|观看|查看|引用|replies|reply|reposts?|retweets?|likes?|bookmarks?|views?|quotes?)/i.test(label) &&
+            /\d/.test(label))),
+    ],
     needsExpansion: post.needsExpansion,
     missing: [
         ...(post.missing ?? []),

package/dist/platform.d.ts

@@ -1,3 +1,4 @@
+import { createPlatformCollections } from "./platform-collections.js";
 export { xURL } from "./platform-rules.js";
 export declare class XPlatform {
     #private;
@@ -8,6 +9,7 @@ export declare class XPlatform {
     readAccount: () => Promise<any>;
     readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
     searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
+    readExploreRecommendations: ReturnType<typeof createPlatformCollections>["readExploreRecommendations"];
     readFeedback: ({ targets, replyLimit }?: any) => Promise<any>;
     readPerson: (target: any) => Promise<any>;
     readPost: (target: any) => Promise<any>;

package/dist/platform.js

@@ -23,6 +23,7 @@ export class XPlatform {
     #readCreator;
     #readBookmarks;
     #searchSources;
+    #readExploreRecommendations;
     #createPlatformDiagnosticsResult;
     #followStage;
     #captureProof;
@@ -41,6 +42,7 @@ export class XPlatform {
     readAccount;
     readBookmarks;
     searchSources;
+    readExploreRecommendations;
     readFeedback;
     readPerson;
     readPost;
@@ -79,11 +81,12 @@ export class XPlatform {
             browser: browser,
             choose: this.#choose,
         });
-        const { collectSources, readCreator, readBookmarks, searchSources } = this.#createPlatformCollectionsResult;
+        const { collectSources, readCreator, readBookmarks, searchSources, readExploreRecommendations, } = this.#createPlatformCollectionsResult;
         this.#collectSources = collectSources;
         this.#readCreator = readCreator;
         this.#readBookmarks = readBookmarks;
         this.#searchSources = searchSources;
+        this.#readExploreRecommendations = readExploreRecommendations;
         this.#createPlatformDiagnosticsResult = createPlatformDiagnostics({
             clock: this.#clock,
         });
@@ -116,6 +119,7 @@ export class XPlatform {
         this.readAccount = this.#readAccount;
         this.readBookmarks = this.#readBookmarks;
         this.searchSources = this.#searchSources;
+        this.readExploreRecommendations = this.#readExploreRecommendations;
         this.readFeedback = this.#readFeedback;
         this.readPerson = this.#readPerson;
         this.readPeople = this.#createPlatformTargetsResult.readPeople;

package/dist/results.js

@@ -90,6 +90,17 @@ export function source(value, page) {
                 : []);
     if (out.links)
         out.links = out.links.filter((link) => isContentLink(link, out));
+    if (raw.metrics !== undefined) {
+        const metrics = list(raw.metrics).flatMap((value) => {
+            if (typeof value === "string")
+                return [value];
+            const label = object(value).label;
+            return typeof label === "string" ? [label] : [];
+        });
+        out.metrics = [
+            ...new Set(metrics.filter((label) => /(?:回复|转帖|喜欢|书签|观看|查看|引用|replies|reply|reposts?|retweets?|likes?|bookmarks?|views?|quotes?)/i.test(label) && /\d/.test(label))),
+        ];
+    }
     if (strings(raw.missing).length)
         out.missing = strings(raw.missing);
     return out;
@@ -200,6 +211,28 @@ export function readResult(operation, value, mode) {
         out.complete = false;
     if (raw.ids !== undefined)
         out.ids = strings(raw.ids);
+    if (operation === "readExploreRecommendations") {
+        const origin = object(raw.sourceOrigin);
+        try {
+            const page = new URL(String(origin.page));
+            if (origin.kind === "explore-recommendations" &&
+                page.protocol === "https:" &&
+                page.hostname === "x.com" &&
+                !page.username &&
+                !page.password &&
+                !page.port &&
+                page.pathname.replace(/\/+$/, "") === "/explore" &&
+                ["为你推荐", "For you"].includes(String(origin.selectedTab)))
+                out.sourceOrigin = {
+                    kind: "explore-recommendations",
+                    page: page.href,
+                    selectedTab: String(origin.selectedTab),
+                };
+        }
+        catch {
+            /* Unverified provenance is omitted at the public business boundary. */
+        }
+    }
     const missing = strings(raw.missing);
     if (list(raw.alerts).length && !missing.includes("platform-alert"))
         missing.push("platform-alert");

package/dist/types.d.ts

@@ -93,6 +93,11 @@ export interface Diagnostic {
     next?: "inspect-local-proof" | "restore-proof-store";
     evidenceRef?: EvidenceRef;
 }
+export interface SourceOriginEvidence {
+    kind: "explore-recommendations";
+    page: string;
+    selectedTab: "为你推荐" | "For you";
+}
 export interface ReadResult {
     status: "observed" | "needsDecision" | "needsCapability";
     fresh?: boolean;
@@ -124,6 +129,7 @@ export interface ReadResult {
         scopeComplete?: boolean;
     };
     sources?: PostEvidence[];
+    sourceOrigin?: SourceOriginEvidence;
     post?: PostEvidence;
     context?: PostEvidence[];
     threadPosts?: PostEvidence[];
@@ -253,6 +259,8 @@ export interface BookmarkOptions extends WindowOptions {
 export interface SearchOptions extends WindowOptions {
     query: string;
 }
+export interface ExploreRecommendationOptions extends WindowOptions {
+}
 export interface CreatorOptions {
     handle: string;
     target?: number;
@@ -563,6 +571,7 @@ export interface XGrowthHarness {
     readFollowbackAudit(args: FollowbackAuditOptions): Promise<FollowbackAuditResult>;
     readBookmarks(args: BookmarkOptions): Promise<ReadResult>;
     searchSources(args: SearchOptions): Promise<ReadResult>;
+    readExploreRecommendations(args?: ExploreRecommendationOptions): Promise<ReadResult>;
     readIncomingReplies(args?: IncomingReplyOptions): Promise<ReadResult>;
     readIncomingConversations(args?: IncomingConversationOptions): Promise<IncomingConversationResult>;
     readPost(args: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/x-harness",
-  "version": "0.2.65",
+  "version": "0.2.67",
   "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": "ece6b7ad7f4355d105ed6ec939bbcd8c136b4ce1"
+  "gitHead": "03a90495bd2c781577399aca850742082abe3556"
 }

package/skill/references/reads.md

@@ -6,6 +6,7 @@
 | readCreator | handle | target (10;1–50), maxScrolls, navigate, expand, mode |
 | readBookmarks | folder (observed name), or discoverOnly:true | processedIds, limit (1–5), maxPages (1–10), resume, mode |
 | searchSources | query | processedIds, limit (1–5), maxPages (1–10), mode |
+| readExploreRecommendations | none | processedIds, limit (1–5), maxPages (1–10), mode |
 | readPost | target: {postId,url,evidenceRef} | includeContext, resolveQuote, mode |
 | readPerson | target: {handle,url,evidenceRef} | mode |
 | readPeople | target: {url,evidenceRef} | offset, limit (1–5), advance, mode |
@@ -13,20 +14,20 @@
 | inspectAccount | none | mode |
 | inspectRound | taskId (original batch ID) | none |
 
-Targets require proof. Native creator: selected profile, navigate:false; relative time unknown; stop on page change.
+Targets need proof. Native `readCreator` requires a selected profile (`navigate:false`); relative time is unknown. Stop on route changes.
 
-Bookmarks resume:true continues the bound folder; rendered tail ≠ full proof.
+Bookmarks `resume:true` continues the bound folder; rendered tail ≠ full proof.
 
-observed ≠ field completeness; pageComplete:false = scope. View media before describing; preserve target text; keep other reads local.
+Observed ≠ complete; `pageComplete:false` means finite scope. Preserve full text; view media before describing; keep raw reads local.
 
-`readIncomingReplies`: ledger account; skip settled/intent/unknown and processedIds across dates. readPost(includeContext:true) for ancestors; missing context blocks review. Dedup publicly.
+Incoming replies: ledger only; carry processedIds; skip settled/intent/unknown. Read parents with `readPost(includeContext:true)`; deduplicate.
 
-Incoming: `readIncomingConversations({targets?,...window})` combines discovery/context (≤5); no preceding `readIncomingReplies`. Preflight/source failures remain visible. Returns ancestorPath, nodes, confirmed edges, unknown parents and attempts; rootCandidateId is only the earliest loaded ancestor. Missing context blocks review; never guess roots/edges or inbox clearance.
+Incoming conversations: `readIncomingConversations({targets?,...window})` discovers/reads ≤5 chains in one call. Targets need proof; returns nodes, ancestors, confirmed edges, unknown parents and attempts. `rootCandidateId` may not be root. Missing context blocks review; don't infer edges or clearance.
 
 `resolveQuote:true` follows one observed card and returns `post.quoteSource` only after exact destination/body/author/time binding.
 
-`readPeople`: observed follower/following; offset reuses cells; advance scrolls a fresh unique handle. Full bio/blue/relationship; dedup; unknowns need profiles. No Native.
+`readPeople`: selected followers/following; `offset` reuses cells, `advance` scrolls. Returns bio, blue, relationship; dedup. Unknowns need profiles; Native unsupported.
 
 Discovery: names only.
 
-Source decisions retain visible metric labels for batch screening; absent counts stay unknown.
+Count `sourceOrigin` only with confirmed `/explore` “For you” tab; exclude trends/search. Preserve visible counts; absent stays unknown.

package/skill/references/receipt-recovery.md

@@ -0,0 +1,7 @@
+# Observed reply receipt recovery
+
+If the root reports an original unknown but a fresh proof or public search exposes its actual own-account permalink, keep that original action. Never derive a receipt ID from a timestamp or guess URLs. Read the observed candidate with root readPost and its original evidenceRef; confirm the actual author, reviewed text, new ID and time at/after intent. A visible parent in context alone is not the final exact-parent verification.
+
+The original ledger already supports observedPublicURL and observedPublicEvidenceRef. Use the existing diagnostics createFileRoundStore transaction to attach only these two fields to that same unknown/intent reply, preserving other actions, executors and counts. Both fields must come from actual observed proof, not a claimed success. Then call root verifySubmission({taskId,actionId}); its normal fresh author/text/time/assets/exact-parent gates settle the original action. A rejected/ambiguous hint remains unknown. Do not manually mark verified, create a replacement action, resend or bypass alerts.
+
+Prepared reply baseline URL timeouts get one internal read-only continuation. A second timeout, unrelated failure, alerts or unconfirmed content stops before intent. Reusing this root behavior is preferable to model-level per-parent rewarming. This does not grant new platform access or override project budgets/windows.

package/skill/references/recovery.md

@@ -4,7 +4,7 @@ Load on failure/unknown only. Keep operation/status/missing/code/proof/error; do
 
 | Signal | Next action and exit condition |
 | --- | --- |
-| unknown submission | `await x.verifySubmission({taskId,actionId})`, same IDs; no replacement action or new submission before resolution. |
+| unknown submission | `await x.verifySubmission({taskId,actionId})`, same IDs; no resend. [Observed link](receipt-recovery.md). |
 | Existing public post needs recovery | `await x.verifyPublishedPost({taskId,draftPath,publicURL,evidenceRef})`; observed URL/proof. sourceLink/sourceLinks: [link proof](source-link-recovery.md). |
 | 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. |