@gobing-ai/knowledge-kit 0.0.31 → 0.0.33

package/plugins/publishings/xhs-pub/src/modes.ts

@@ -0,0 +1,300 @@
+import { isAbsolute } from 'node:path';
+import type { Content } from '@gobing-ai/kk-core';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+
+/**
+ * The xhs channel's publishing TYPES, declared and validated (ADR-029).
+ *
+ * One plugin per channel: the four console modes a single authenticated session offers are
+ * `operations` of this plugin — selected from `options.operation ?? content.metadata.operation`,
+ * resolved against {@link XHS_OPERATIONS}, and refused by name **before** a browser is launched or
+ * a profile is resolved. Each operation owns its own entry step, artifact set, limits and flow
+ * (`./flow`); the channel owns the profile dir, session, preflight and `Content → Result` mapping
+ * (`./index`).
+ *
+ * Labels and constraints come from the live console walk (`docs/design/xhs-ui-discovery.md`).
+ * Everything here is pre-browser: it decides whether the run is allowed to open a session at all.
+ */
+
+export const TARGET = 'xhs';
+
+/**
+ * Channel-wide console facts, shared by the session gate (`./index`) and the flows (`./flow`):
+ * every mode is reached from this one creator-console entry, and a completed publish is marked in
+ * the console's own URL (measured live 2026-09-26).
+ */
+export const PUBLISH_URL = 'https://creator.xiaohongshu.com/publish/publish';
+export const PUBLISHED_MARKER = 'published=true';
+
+export const XHS_OPERATIONS = ['上传图文', '上传视频', '写长文', '发播客'] as const;
+
+export type XhsOperation = (typeof XHS_OPERATIONS)[number];
+
+/**
+ * No operation requested ⇒ the note/composer mode this channel shipped with. The daily pipeline's
+ * card-series stage (`kk-workflow-stages.ts` E8) still dispatches xhs-pub without one, and its
+ * packaged `Content` is exactly an image-text note.
+ */
+export const DEFAULT_XHS_OPERATION: XhsOperation = '上传图文';
+
+/** Exit-early resolution of the requested operation (ADR-029 dispatch). */
+export function resolveXhsOperation(
+    options?: Record<string, unknown>,
+    content?: Content,
+): { operation: XhsOperation; error?: undefined } | { operation?: undefined; error: string } {
+    const raw = options?.operation ?? content?.metadata?.operation;
+    if (raw === undefined) return { operation: DEFAULT_XHS_OPERATION };
+    if (typeof raw !== 'string' || !(XHS_OPERATIONS as readonly string[]).includes(raw)) {
+        return {
+            error: `unsupported operation '${String(raw)}' for ${TARGET}: expected one of ${XHS_OPERATIONS.join(', ')}`,
+        };
+    }
+    return { operation: raw as XhsOperation };
+}
+
+/** Image extensions the 图文 grid accepts (`accept=".jpg,.jpeg,.png,.webp"`). */
+const IMAGE_EXTENSIONS = /\.(png|jpe?g|webp)$/i;
+const IMAGE_LIST = 'png|jpg|jpeg|webp';
+/** Video extensions the dropzone accepts (`accept=".mp4,.mov,…,.ts"`). */
+const VIDEO_EXTENSIONS = /\.(mp4|mov|flv|f4v|mkv|rm|rmvb|m4v|mpg|mpeg|ts)$/i;
+const VIDEO_LIST = 'mp4|mov|flv|f4v|mkv|rm|rmvb|m4v|mpg|mpeg|ts';
+/** Audio extensions the 发播客 modal's picker accepts (`accept=".mp3,.wav,.aac,.flac,.m4a"`). */
+const AUDIO_EXTENSIONS = /\.(mp3|wav|aac|flac|m4a)$/i;
+const AUDIO_LIST = 'mp3|wav|aac|flac|m4a';
+
+/** Images the 图文 grid accepts before it refuses the batch (discovery §2: ≤18). */
+export const XHS_IMAGE_MAX = 18;
+/**
+ * Note-title characters. The daily card-series stage enforces the same cap on the plan it packages
+ * for this channel (`kk-workflow-stages.ts` XHS_TITLE_CAP), which is exactly the content this
+ * plugin receives.
+ */
+export const XHS_NOTE_TITLE_MAX = 20;
+/** Note-body characters, read off the 图文 editor's own `0/1000` counter (discovery §2). */
+export const XHS_NOTE_BODY_MAX = 1000;
+
+/** Per-mode field ceilings, as recorded by the console walk. */
+export interface ModeLimits {
+    /** Images the 图文 grid accepts before it refuses the batch. */
+    imageMax?: number;
+    /** Title characters; the same cap the daily card-series stage already enforces on the plan. */
+    titleMax?: number;
+    /** Note-body characters, read off the editor's own `0/1000` counter. */
+    bodyMax?: number;
+}
+
+export const MODE_LIMITS: Record<XhsOperation, ModeLimits> = {
+    // 图文: image grid ≤18, note title 20, note body 0/1000 (discovery §2).
+    上传图文: { imageMax: XHS_IMAGE_MAX, titleMax: XHS_NOTE_TITLE_MAX, bodyMax: XHS_NOTE_BODY_MAX },
+    // 视频: one video file; the same note composer carries the title. No body counter was recorded
+    // for the video note, so none is enforced.
+    上传视频: { titleMax: XHS_NOTE_TITLE_MAX },
+    // 写长文: no upload and no recorded ceiling — it is the long-form surface.
+    写长文: {},
+    // 发播客: the artifacts are the audio and its cover; no text ceiling was recorded.
+    发播客: {},
+};
+
+/**
+ * A validated mode input: the operation plus the artifacts and limits that mode requires.
+ * Discriminated on `operation` so every flow narrows to exactly the artifacts it may use.
+ */
+export type ModeInput =
+    | { operation: '上传图文'; images: string[] }
+    | { operation: '上传视频'; video: string }
+    | { operation: '写长文' }
+    | { operation: '发播客'; audio: string; cover: string };
+
+/** Validated artifacts in upload order — the evidence a Result reports. */
+export function artifactPaths(input: ModeInput): string[] {
+    switch (input.operation) {
+        case '上传图文':
+            return input.images;
+        case '上传视频':
+            return [input.video];
+        case '写长文':
+            return [];
+        case '发播客':
+            return [input.audio, input.cover];
+    }
+}
+
+interface MediaSpec {
+    /** `metadata` key the artifact is read from. */
+    key: 'video' | 'audio' | 'coverImage';
+    /** Error prefix, e.g. `video validation`. */
+    label: string;
+    extensions: RegExp;
+    /** Accepted extensions for the error text. */
+    list: string;
+}
+
+/**
+ * Reads one local media artifact out of `Content.metadata`. The repo spells a single artifact
+ * either bare (`metadata.coverImage`, `metadata.audioFile`) or as a `{ path }` descriptor
+ * (`metadata.images[]`), so both are accepted here; the error always names the `metadata` key.
+ */
+async function resolveMediaPath(content: Content, spec: MediaSpec): Promise<{ path?: string; error?: string }> {
+    const raw = content.metadata?.[spec.key];
+    const path =
+        typeof raw === 'string'
+            ? raw
+            : typeof (raw as { path?: unknown } | undefined)?.path === 'string'
+              ? ((raw as { path: string }).path as string)
+              : undefined;
+    if (path === undefined || path.length === 0) {
+        return {
+            error: `${spec.label}: Content.metadata.${spec.key} is required (absolute path to an existing ${spec.list} file)`,
+        };
+    }
+    if (!isAbsolute(path)) {
+        return { error: `${spec.label}: Content.metadata.${spec.key} must be absolute, got '${path}'` };
+    }
+    if (!spec.extensions.test(path)) {
+        return {
+            error: `${spec.label}: Content.metadata.${spec.key} has unsupported extension (expected ${spec.list}): '${path}'`,
+        };
+    }
+    if (!(await createNodeFileSystem().exists(path))) {
+        return { error: `${spec.label}: Content.metadata.${spec.key} does not exist: '${path}'` };
+    }
+    return { path };
+}
+
+/**
+ * Pure pre-browser validation of one image-text note: `publishStatus`, the ordered image batch and
+ * the mode's caps. Kept as the 图文 entry point (and exported for its own tests).
+ */
+export async function validatePublishInput(content: Content): Promise<{ paths?: string[]; error?: string }> {
+    const status = validatePublishStatus(content);
+    if (status.error) return { error: status.error };
+    const images = content.metadata?.images;
+    if (!Array.isArray(images) || images.length === 0) {
+        return { error: 'images validation: metadata.images must be a non-empty ordered array' };
+    }
+    const max = XHS_IMAGE_MAX;
+    if (images.length > max) {
+        return {
+            error: `images validation: metadata.images holds ${images.length} entries but the 上传图文 grid accepts ≤${max}`,
+        };
+    }
+    const paths: string[] = [];
+    for (const [i, image] of images.entries()) {
+        const path = (image as { path?: unknown })?.path;
+        if (typeof path !== 'string' || path.length === 0) {
+            return { error: `images validation: images[${i}].path is missing` };
+        }
+        if (!isAbsolute(path)) {
+            return { error: `images validation: images[${i}].path must be absolute, got '${path}'` };
+        }
+        if (!IMAGE_EXTENSIONS.test(path)) {
+            return {
+                error: `images validation: images[${i}].path has unsupported extension (expected ${IMAGE_LIST}): '${path}'`,
+            };
+        }
+        if (!(await createNodeFileSystem().exists(path))) {
+            return { error: `images validation: images[${i}].path does not exist: '${path}'` };
+        }
+        paths.push(path);
+    }
+    return { paths };
+}
+
+/**
+ * `publishStatus` is the operator's explicit live-publish request: absent means draft, `public`
+ * means the flow may click the console's 发布 control, and anything else is refused here — before
+ * a browser opens, so a typo can never reach a real publish control.
+ */
+function validatePublishStatus(content: Content): { error?: string } {
+    const status = content.metadata?.publishStatus;
+    if (status !== undefined && status !== 'draft' && status !== 'public') {
+        return {
+            error: `publishStatus validation: unknown publishStatus '${String(status)}' (expected 'draft' or 'public')`,
+        };
+    }
+    return {};
+}
+
+/** The note title cap is shared by the two note-composer modes. */
+function validateTitle(content: Content, operation: XhsOperation): { error?: string } {
+    const max = MODE_LIMITS[operation].titleMax;
+    if (max === undefined) return {};
+    const title = content.title ?? '';
+    if (title.length > max) {
+        return {
+            error: `title validation: Content.title is ${title.length} chars but ${operation} accepts ≤${max}`,
+        };
+    }
+    return {};
+}
+
+function validateBody(content: Content, operation: XhsOperation): { error?: string } {
+    const max = MODE_LIMITS[operation].bodyMax;
+    if (max === undefined) return {};
+    if (content.body.length > max) {
+        return {
+            error: `body validation: Content.body is ${content.body.length} chars but ${operation} accepts ≤${max}`,
+        };
+    }
+    return {};
+}
+
+export type ModeValidation = { input: ModeInput; error?: undefined } | { input?: undefined; error: string };
+
+/**
+ * Pre-browser validation for the requested operation: what it needs, and whether it fits.
+ * A failure here is returned as `ok:false` naming the missing artifact, field or limit — the run
+ * never opens a browser or resolves a profile for input the console cannot accept.
+ */
+export async function validateModeInput(operation: XhsOperation, content: Content): Promise<ModeValidation> {
+    const status = validatePublishStatus(content);
+    if (status.error) return { error: status.error };
+
+    switch (operation) {
+        case '上传图文': {
+            const title = validateTitle(content, operation);
+            if (title.error) return { error: title.error };
+            const body = validateBody(content, operation);
+            if (body.error) return { error: body.error };
+            const images = await validatePublishInput(content);
+            if (images.error) return { error: images.error };
+            return { input: { operation, images: images.paths ?? [] } };
+        }
+        case '上传视频': {
+            const title = validateTitle(content, operation);
+            if (title.error) return { error: title.error };
+            const video = await resolveMediaPath(content, {
+                key: 'video',
+                label: 'video validation',
+                extensions: VIDEO_EXTENSIONS,
+                list: VIDEO_LIST,
+            });
+            if (video.error) return { error: video.error };
+            return { input: { operation, video: video.path ?? '' } };
+        }
+        case '写长文': {
+            // No upload: the body IS the artifact, authored in place in the console editor.
+            if (content.body.trim().length === 0) {
+                return { error: 'body validation: Content.body must be non-empty for 写长文 (authored in place)' };
+            }
+            return { input: { operation } };
+        }
+        case '发播客': {
+            const audio = await resolveMediaPath(content, {
+                key: 'audio',
+                label: 'audio validation',
+                extensions: AUDIO_EXTENSIONS,
+                list: AUDIO_LIST,
+            });
+            if (audio.error) return { error: audio.error };
+            const cover = await resolveMediaPath(content, {
+                key: 'coverImage',
+                label: 'cover validation',
+                extensions: IMAGE_EXTENSIONS,
+                list: IMAGE_LIST,
+            });
+            if (cover.error) return { error: cover.error };
+            return { input: { operation, audio: audio.path ?? '', cover: cover.path ?? '' } };
+        }
+    }
+}

package/plugins/publishings/xhs-pub/src/page.ts

@@ -0,0 +1,254 @@
+import { trySelectors } from '@gobing-ai/publish-harness';
+import { waitUntil } from '@gobing-ai/publish-harness/browser';
+
+/**
+ * The console's page seam (ADR-029) and the helpers every xhs operation shares.
+ *
+ * `XhsPage` is deliberately a structural subset of the Playwright `Page`: the flows are driven
+ * through it so the offline tests can script the console (fake page) instead of launching a
+ * browser. Anything the shared `@gobing-ai/publish-harness/browser` helpers need on a real
+ * Playwright page is part of this seam, never reached around it.
+ */
+
+export const POLL_MS = 500;
+
+// The shared poll (0184 R2); re-exported so flow/index keep importing it from here.
+export { waitUntil };
+export const STEP_TIMEOUT_MS = 30_000;
+
+/** The console's mode tab bar; it mounts late and renders every tab several times over. */
+export const CREATOR_TAB_BAR = 'div.creator-tab';
+/** 上传视频 / 上传图文 / 写长文 / 发播客 — the bar is only usable once all four are laid out. */
+export const CREATOR_TAB_COUNT = 4;
+
+/** A control resolved inside a closed shadow root, in viewport coordinates. */
+export interface ShadowControl {
+    label: string;
+    x: number;
+    y: number;
+}
+
+/** Locates a labelled control inside a closed shadow root (CDP-backed in production). */
+export interface ShadowProbe {
+    findControl(labels: readonly string[]): Promise<ShadowControl | null>;
+}
+
+export interface XhsLocator {
+    count(): Promise<number>;
+    isVisible(options?: { timeout?: number }): Promise<boolean>;
+    fill(text: string, options?: { timeout?: number }): Promise<void>;
+    click(options?: { timeout?: number; force?: boolean }): Promise<void>;
+    /**
+     * Type into the element. The XHS note body is a TipTap/ProseMirror editor: `fill` sets
+     * the DOM text without the editor registering content, so a later save has nothing to
+     * save and produces no observable draft.
+     */
+    type?(text: string, options?: { timeout?: number; delay?: number }): Promise<void>;
+    textContent?(): Promise<string>;
+}
+
+/** Structural subset of the Playwright page the script driver uses. */
+export interface XhsPage {
+    goto(url: string, options?: { timeout?: number }): Promise<void>;
+    locator(selector: string): { first(): XhsLocator; count(): Promise<number> };
+    /** Playwright accepts one path or a list; the flows use both (one video, or an image batch). */
+    setInputFiles(selector: string, paths: readonly string[] | string): Promise<void>;
+    waitForSelector(selector: string, options?: { timeout?: number }): Promise<unknown>;
+    url(): string;
+    /** Page-side script evaluation; the shared paste helper runs its clipboard script through it. */
+    evaluate(expression: string): Promise<unknown>;
+    /** How many matches are laid out at an on-screen box (the tab-clone filter). */
+    countOnScreen(selector: string): Promise<number>;
+    /** Click the first on-screen match — the console renders the tabs 3×. */
+    clickInViewport?(selector: string): Promise<boolean>;
+    /** Resolve a labelled control inside a closed shadow root. */
+    findShadowControl?(labels: readonly string[]): Promise<ShadowControl | null>;
+    /** Click at viewport coordinates. */
+    clickAt?(x: number, y: number): Promise<void>;
+}
+
+export interface OpenedPage {
+    page: XhsPage;
+    close(): Promise<void>;
+}
+
+export type OpenPage = (profileDir: string) => Promise<OpenedPage>;
+
+/** The `div.creator-tab` carrying one mode's label. */
+export function creatorTabSelector(label: string): string {
+    return `${CREATOR_TAB_BAR}:has-text("${label}")`;
+}
+
+/**
+ * Enter one console mode by clicking the tab bar's **on-screen** instance.
+ *
+ * Hazard (measured 2026-10-05, `docs/design/xhs-ui-discovery.md` §1): every tab is rendered at
+ * least three times — an `aria-hidden="true"` clone, a clone laid out far off-viewport (measured
+ * `x=-9726, y=-9918`), and the live node — and the whole bar mounts late and varies. A
+ * `...:has-text(label).first()` binds to a clone and hangs for the full step timeout (measured:
+ * 30 s, reported as "no real node"), and `:not([aria-hidden="true"])` alone still matches an
+ * off-screen clone. So the bar is waited on first (≥4 laid-out, on-screen tabs) and the click
+ * then targets the first candidate whose box is inside the viewport.
+ */
+export async function clickCreatorTab(
+    page: XhsPage,
+    label: string,
+    opts: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<void> {
+    const timeoutMs = opts.timeoutMs ?? STEP_TIMEOUT_MS;
+    const pollMs = opts.pollMs ?? POLL_MS;
+    // A count read that throws (a detached node while the bar is still mounting) is "not yet",
+    // not a broken rail: the deadline below is what reports the observed state.
+    const onScreenCount = () => page.countOnScreen(CREATOR_TAB_BAR).catch(() => 0);
+    const mounted = await waitUntil(
+        () => onScreenCount().then((count) => count >= CREATOR_TAB_COUNT),
+        timeoutMs,
+        pollMs,
+    );
+    if (!mounted) {
+        const observed = await onScreenCount();
+        throw new Error(
+            `mode entry: the console tab bar did not mount within ${timeoutMs}ms (${observed} of ${CREATOR_TAB_COUNT} on-screen '${CREATOR_TAB_BAR}' nodes) — every tab renders aria-hidden and off-viewport clones`,
+        );
+    }
+    if (!page.clickInViewport) {
+        throw new Error(
+            `mode entry: this driver cannot read viewport geometry, so the on-screen '${label}' tab cannot be told apart from its off-screen clones`,
+        );
+    }
+    const clicked = await page.clickInViewport(creatorTabSelector(label));
+    if (!clicked) {
+        throw new Error(
+            `mode entry: no in-viewport '${label}' tab found (only aria-hidden or off-screen clones matched) — the mode was not entered`,
+        );
+    }
+}
+
+export function wrapPlaywrightPage(raw: unknown, shadow?: ShadowProbe): XhsPage {
+    const pw = raw as {
+        goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
+        locator(selector: string): {
+            count(): Promise<number>;
+            nth(index: number): {
+                boundingBox(): Promise<{ x: number; y: number; width: number; height: number } | null>;
+                click(options?: Record<string, unknown>): Promise<void>;
+            };
+            first(): Record<string, (...args: unknown[]) => unknown> & Promise<unknown>;
+        };
+        setInputFiles(selector: string, paths: readonly string[] | string): Promise<void>;
+        waitForSelector(selector: string, options?: Record<string, unknown>): Promise<unknown>;
+        url(): string;
+        viewportSize?(): { width: number; height: number } | null;
+        evaluate(expression: string): Promise<unknown>;
+        mouse: { click(x: number, y: number): Promise<void> };
+    };
+
+    /**
+     * The matches of `selector` that are laid out at a readable box inside the viewport. A
+     * `display:none` node reports no box at all (`boundingBox()` → null), which is the non-hidden
+     * half of the tab-bar rule; an off-screen clone keeps its box and is rejected on coordinates.
+     * Without a readable viewport nothing qualifies — the duplicates cannot be told apart, so the
+     * caller fails loud instead of clicking a maybe-off-screen copy.
+     */
+    const onScreen = async (
+        selector: string,
+    ): Promise<Array<{ index: number; box: { x: number; y: number; width: number; height: number } }>> => {
+        const viewport = pw.viewportSize?.() ?? null;
+        if (viewport === null) return [];
+        const total = await pw.locator(selector).count();
+        const found: Array<{ index: number; box: { x: number; y: number; width: number; height: number } }> = [];
+        for (let index = 0; index < total; index += 1) {
+            const candidate = pw.locator(selector).nth(index);
+            const box = await candidate.boundingBox().catch(() => null);
+            if (!box || box.width === 0 || box.height === 0) continue;
+            const outside = box.x < 0 || box.y < 0 || box.x >= viewport.width || box.y >= viewport.height;
+            if (outside) continue;
+            found.push({ index, box });
+        }
+        return found;
+    };
+
+    return {
+        goto: (url, options) => pw.goto(url, options) as Promise<void>,
+        locator: (selector) => ({
+            count: () => pw.locator(selector).count(),
+            first: () => {
+                const loc = pw.locator(selector).first() as unknown as {
+                    count(): Promise<number>;
+                    isVisible(o?: Record<string, unknown>): Promise<boolean>;
+                    fill(t: string, o?: Record<string, unknown>): Promise<void>;
+                    click(o?: Record<string, unknown>): Promise<void>;
+                };
+                return {
+                    count: () => loc.count(),
+                    isVisible: (options) => loc.isVisible(options),
+                    fill: (text, options) => loc.fill(text, options),
+                    click: (options) => loc.click(options),
+                    type: (text, options) =>
+                        (
+                            loc as unknown as {
+                                pressSequentially(text: string, options?: { delay?: number }): Promise<void>;
+                            }
+                        ).pressSequentially(text, options),
+                    textContent: () => (loc as unknown as { textContent(): Promise<string> }).textContent(),
+                };
+            },
+        }),
+        setInputFiles: (selector, paths) => pw.setInputFiles(selector, paths),
+        waitForSelector: (selector, options) => pw.waitForSelector(selector, options),
+        url: () => pw.url(),
+        evaluate: (expression) => pw.evaluate(expression),
+        countOnScreen: async (selector) => (await onScreen(selector)).length,
+        clickInViewport: async (selector) => {
+            const [candidate] = await onScreen(selector);
+            if (candidate === undefined) return false;
+            // The tab's inner span intercepts the hit test, so the click must be forced.
+            await pw.locator(selector).nth(candidate.index).click({ force: true });
+            return true;
+        },
+        findShadowControl: async (labels) => (shadow ? shadow.findControl(labels) : null),
+        clickAt: (x, y) => pw.mouse.click(x, y),
+    };
+}
+
+/** Polls the candidate list until one selector has an attached match; throws naming `what`. */
+export async function findSelector(
+    page: XhsPage,
+    selectors: readonly string[],
+    what: string,
+    timeoutMs = STEP_TIMEOUT_MS,
+): Promise<string> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const found = await trySelectors(page, selectors);
+        if (found.found && found.selector) return found.selector;
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+    throw new Error(`${what}: no matching element observed`);
+}
+
+/**
+ * Find the first selector that is ATTACHED, ignoring visibility. Upload widgets hide the
+ * real `<input type="file">` behind a styled drop zone, and `trySelectors` filters on
+ * visibility by default — so a hidden input needs this probe. Uploading into the wrong
+ * input is still caught: the thumbnail count must match the payload afterwards.
+ */
+export async function findAttachedSelector(
+    page: XhsPage,
+    selectors: readonly string[],
+    what: string,
+    timeoutMs = STEP_TIMEOUT_MS,
+): Promise<string> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        for (const selector of selectors) {
+            const attached = await page
+                .locator(selector)
+                .count()
+                .catch(() => 0);
+            if (attached > 0) return selector;
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+    throw new Error(`${what}: no matching element observed`);
+}

package/plugins/publishings/xhs-pub/src/profile-check.ts

@@ -6,7 +6,8 @@
  *  - `login` recovers an absent/expired session headed via the upstream
  *    `loginWithProfile`, polled with the same XHS-owned readiness gate the publish
  *    flow uses;
- *  - `check` reopens the existing profile headless and reports the session as
+ *  - `check` reopens the existing profile (headless by default; `--headed` skips the headless
+ *    pass and probes headed only, 0216) and reports the session as
  *    `verified` or `refused` — a site refusal, expired session, or missing profile
  *    is an explicit failed readiness, never a success. The upstream launcher never
  *    creates a profile headless, so a check cannot fabricate a session from a
@@ -21,7 +22,7 @@
  * the full recipe lives in docs/design/xhs-image-cards.md.
  */
 import { parseArgs } from 'node:util';
-import { resolveBrowserProfileDir } from '@gobing-ai/publish-harness';
+import { kkBrowserLauncher, resolveChannelProfileDir } from '@gobing-ai/publish-harness/browser';
 import { type BrowserLauncher, loginWithProfile } from '@gobing-ai/ts-browser-automation';
 import { echo, echoError } from '@gobing-ai/ts-utils';
 import { type AutomationGuard, createAutomationGuard } from './automation-guard';
@@ -60,11 +61,20 @@ export async function loginProfile(opts: ProfileLoginOptions): Promise<void> {
         url: PUBLISH_URL,
         isAuthenticated: (page) => isXhsConsoleReady(wrapPlaywrightPage(page)),
         timeoutMs: opts.timeoutMs ?? LOGIN_TIMEOUT_MS,
-        launcher: opts.launcher,
+        launcher: opts.launcher ?? kkBrowserLauncher,
     });
 }
 
-/** `login|check [--profile <dir>] [--timeout <ms>]`; profile precedence matches the publish flow. */
+/** Exit 2 with the human usage on stderr and the ADR-032 `error` verdict as the last stdout line. */
+function usageError(message: string): number {
+    echoError(
+        `profile-check: ${message} — usage: profile-check.ts [login|check] [--profile <dir>] [--timeout <ms>] [--headed]`,
+    );
+    echo(JSON.stringify({ status: 'error', detail: message }));
+    return 2;
+}
+
+/** `login|check [--profile <dir>] [--timeout <ms>] [--headed]`; profile precedence matches the publish flow. */
 export async function main(
     argv: string[] = process.argv.slice(2),
     launcher?: BrowserLauncher,
@@ -73,26 +83,28 @@ export async function main(
     let command: string;
     let profileDir: string;
     let timeoutMs: number | undefined;
+    let headed = false;
     try {
         const { positionals, values } = parseArgs({
             args: argv,
             allowPositionals: true,
-            options: { profile: { type: 'string' }, timeout: { type: 'string' } },
+            options: {
+                profile: { type: 'string' },
+                timeout: { type: 'string' },
+                headed: { type: 'boolean' },
+            },
         });
         command = positionals[0] ?? 'check';
+        headed = values.headed === true;
         if (values.timeout !== undefined) {
             timeoutMs = Number(values.timeout);
             if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
                 throw new Error(`--timeout must be a non-negative number of ms, got '${values.timeout}'`);
             }
         }
-        const override = values.profile ?? process.env.XHS_PROFILE_DIR ?? process.env.KK_BROWSER_PROFILE_DIR;
-        profileDir = resolveBrowserProfileDir(CHANNEL, override);
+        profileDir = resolveChannelProfileDir(CHANNEL, values.profile);
     } catch (error) {
-        echoError(
-            `profile-check: ${error instanceof Error ? error.message : String(error)} — usage: profile-check.ts [login|check] [--profile <dir>] [--timeout <ms>]`,
-        );
-        return 1;
+        return usageError(error instanceof Error ? error.message : String(error));
     }
     if (command === 'login') {
         try {
@@ -105,21 +117,21 @@ export async function main(
         }
     }
     if (command !== 'check') {
-        echoError(
-            `profile-check: unknown command '${command}' — usage: profile-check.ts [login|check] [--profile <dir>] [--timeout <ms>]`,
-        );
-        return 1;
+        return usageError(`unknown command '${command}'`);
     }
     // ADR-025: a manual session check is a real console visit, so it draws on the shared 2h
     // automation budget rather than a separate one. `login` is deliberately uncapped above: it is
     // operator-interactive, so capping it would only block recovery from an expired session.
     const cap = guard.allow('check');
     if (!cap.allowed) {
-        echoError(`profile-check: ${cap.reason}`);
+        // The budget refusal is still a readiness verdict (0216 contract): emit the JSON line so
+        // `kk plugin check` reports a refusal with the operator hint instead of a malformed probe.
+        echo(JSON.stringify({ status: 'refused', profileDir, detail: `xhs readiness refused: ${cap.reason}` }));
+        echoError(cap.reason);
         return 1;
     }
     guard.record('check');
-    const outcome = await checkXhsProfileSession({ profileDir, timeoutMs, launcher });
+    const outcome = await checkXhsProfileSession({ profileDir, timeoutMs, launcher, headedOnly: headed });
     echo(JSON.stringify(outcome));
     if (outcome.status !== 'verified') {
         echoError(outcome.detail);