@vincentt-xr/cli 0.1.0

package/dist/preview/cloudflared.js

@@ -0,0 +1,46 @@
+// Resolve a runnable cloudflared binary so a preview never hard-fails on a
+// missing system install. The tunnel protocol is proprietary QUIC to Cloudflare's
+// edge — there is no pure-Node connector, so *some* cloudflared binary is
+// required. We prefer one already on PATH (respects a user's own install) and
+// otherwise fall back to the copy the `cloudflared` npm package provisions, so a
+// fresh machine that installed only the harness can still preview on a device.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+function isOnPath() {
+    // `which`/`where` exits 0 only when the binary resolves on PATH.
+    const probe = process.platform === "win32" ? "where" : "which";
+    return spawnSync(probe, ["cloudflared"], { stdio: "ignore" }).status === 0;
+}
+/**
+ * Return a spawnable cloudflared command/path, provisioning one if the host has
+ * none. Resolves to `"cloudflared"` when a system install is on PATH, else to the
+ * `cloudflared` package's managed binary (already fetched by its postinstall, or
+ * downloaded here on demand when install scripts were skipped). Throws only if the
+ * download itself fails (offline / blocked egress) — surface that to the user
+ * with the manual `brew install cloudflared` fallback.
+ */
+export async function ensureCloudflared(opts = {}) {
+    if (isOnPath())
+        return "cloudflared";
+    const cloudflared = await import("cloudflared");
+    if (existsSync(cloudflared.bin))
+        return cloudflared.bin;
+    // Reached only when the package's postinstall was skipped (e.g. --ignore-scripts).
+    const log = opts.onLog ?? (() => undefined);
+    log("cloudflared not found — downloading a one-time copy…");
+    await mkdir(path.dirname(cloudflared.bin), { recursive: true });
+    // The download may print progress. On an MCP stdio server, ANY stdout write
+    // corrupts the JSON-RPC stream — redirect stdout→stderr for its duration.
+    const realWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = process.stderr.write.bind(process.stderr);
+    try {
+        await cloudflared.install(cloudflared.bin);
+    }
+    finally {
+        process.stdout.write = realWrite;
+    }
+    log(`cloudflared ready at ${cloudflared.bin}`);
+    return cloudflared.bin;
+}

package/dist/preview/index.d.ts

@@ -0,0 +1,3 @@
+export { startSessionTunnel, type SessionTunnel } from "./tunnel.js";
+export { ensureCloudflared, type EnsureCloudflaredOptions } from "./cloudflared.js";
+export { startPreview, type StartPreviewOptions, type RunningPreview } from "./runner.js";

package/dist/preview/index.js

@@ -0,0 +1,6 @@
+// Public surface of the preview limb (`@vincentt-xr/harness/preview`): the tunnel
+// mint, the cloudflared resolver, and the full one-call preview runner. Barrel
+// only — implementations live in the sibling modules.
+export { startSessionTunnel } from "./tunnel.js";
+export { ensureCloudflared } from "./cloudflared.js";
+export { startPreview } from "./runner.js";

package/dist/preview/net.d.ts

@@ -0,0 +1,6 @@
+/** Ask the OS for an unused ephemeral port. */
+export declare function getFreePort(): Promise<number>;
+/** True if something already accepts TCP connections on the port (e.g. a dev server). */
+export declare function isPortListening(port: number, host?: string): Promise<boolean>;
+/** Poll the app for any non-5xx HTTP response until it's ready or the timeout hits. */
+export declare function waitForApp(port: number, timeoutMs: number): Promise<boolean>;

package/dist/preview/net.js

@@ -0,0 +1,56 @@
+// TCP/HTTP port helpers for the preview runner: pick a free port for the internal
+// servers, detect a dev server already listening (so we reuse it instead of
+// spawning a second one), and wait for the app to actually serve before we hand
+// back a public URL.
+import { createServer, connect } from "node:net";
+import { get as httpGet } from "node:http";
+/** Ask the OS for an unused ephemeral port. */
+export function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const { port } = srv.address();
+            srv.close(() => resolve(port));
+        });
+    });
+}
+/** True if something already accepts TCP connections on the port (e.g. a dev server). */
+export function isPortListening(port, host = "127.0.0.1") {
+    return new Promise((resolve) => {
+        const sock = connect(port, host);
+        const done = (v) => {
+            sock.destroy();
+            resolve(v);
+        };
+        sock.setTimeout(400);
+        sock.once("connect", () => done(true));
+        sock.once("timeout", () => done(false));
+        sock.once("error", () => resolve(false));
+    });
+}
+/** Poll the app for any non-5xx HTTP response until it's ready or the timeout hits. */
+export function waitForApp(port, timeoutMs) {
+    const probe = () => new Promise((resolve) => {
+        const req = httpGet({ host: "127.0.0.1", port, path: "/", timeout: 1000 }, (res) => {
+            res.resume();
+            resolve((res.statusCode ?? 500) < 500);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+    return new Promise((resolve) => {
+        const deadline = Date.now() + timeoutMs;
+        const tick = async () => {
+            if (await probe())
+                return resolve(true);
+            if (Date.now() >= deadline)
+                return resolve(false);
+            setTimeout(() => void tick(), 300);
+        };
+        void tick();
+    });
+}

package/dist/preview/proxy.d.ts

@@ -0,0 +1,4 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+export declare function proxyWeb(req: IncomingMessage, res: ServerResponse, targetPort: number): void;
+export declare function proxyWs(req: IncomingMessage, socket: Duplex, head: Buffer, targetPort: number): void;

package/dist/preview/proxy.js

@@ -0,0 +1,49 @@
+// A minimal same-host reverse proxy: forward HTTP requests and WebSocket upgrades
+// to a localhost target port. Enough for the preview front proxy (app + harness
+// relay behind one origin); not a general proxy. No deps.
+import { connect } from "node:net";
+import { request, } from "node:http";
+// Rewrite Host to the loopback target. cloudflared forwards the public Host, and
+// esbuild's `serve` 403s any Host it doesn't recognize — so the phone would get a
+// 403. The origin only needs a Host it accepts; the browser never sees this value.
+function localHeaders(headers, targetPort) {
+    return { ...headers, host: `localhost:${targetPort}` };
+}
+export function proxyWeb(req, res, targetPort) {
+    const proxyReq = request({
+        host: "127.0.0.1",
+        port: targetPort,
+        path: req.url,
+        method: req.method,
+        headers: localHeaders(req.headers, targetPort),
+    }, (proxyRes) => {
+        res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+        proxyRes.pipe(res);
+    });
+    proxyReq.on("error", () => {
+        if (!res.headersSent)
+            res.writeHead(502);
+        res.end();
+    });
+    req.pipe(proxyReq);
+}
+export function proxyWs(req, socket, head, targetPort) {
+    // Re-issue the upgrade handshake against the target and splice the sockets.
+    const headers = localHeaders(req.headers, targetPort);
+    const upstream = connect(targetPort, "127.0.0.1", () => {
+        const headerLines = [
+            `${req.method} ${req.url} HTTP/1.1`,
+            ...Object.entries(headers).map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(", ") : v}`),
+            "",
+            "",
+        ].join("\r\n");
+        upstream.write(headerLines);
+        if (head && head.length)
+            upstream.write(head);
+        upstream.pipe(socket);
+        socket.pipe(upstream);
+    });
+    const bail = () => socket.destroy();
+    upstream.on("error", bail);
+    socket.on("error", bail);
+}

package/dist/preview/runner.d.ts

@@ -0,0 +1,45 @@
+import { type ChildProcess } from "node:child_process";
+export interface StartPreviewOptions {
+    /** Project directory — its .vincentt binding + dev script drive the preview. */
+    projectCwd: string;
+    /** App dev-serve port (default 5173). If a server is already listening here, it
+     *  is reused instead of spawning a second one. */
+    appPort?: number;
+    /** Relay port. Default: an OS-assigned free port (returned as relayPort). */
+    relayPort?: number;
+    /** Front-proxy port the tunnel points at. Default: an OS-assigned free port. */
+    frontPort?: number;
+    /** Path routed to the relay instead of the app (default /__harness). */
+    harnessPath?: string;
+    /** Command that starts the app dev serve on $PORT (default `npm run dev`). */
+    devCommand?: string[];
+    /** stdio for the app dev serve. "ignore" (default) keeps an MCP server's stdout
+     *  clean; a CLI can pass "inherit" to surface build output. */
+    appStdio?: "ignore" | "inherit";
+    /** How long to wait for cloudflared to register before giving up (default 45s). */
+    registerTimeoutMs?: number;
+    /** How long to wait for the app to serve before returning anyway (default 8s).
+     *  Kept short so an MCP tool call stays within strict clients' ~30s timeout;
+     *  a not-yet-ready app still returns (appReady=false), it isn't an error. */
+    appReadyTimeoutMs?: number;
+    /** Progress sink (relay/cloudflared lines). Never write app stdout to MCP stdout. */
+    onLog?: (message: string) => void;
+}
+export interface RunningPreview {
+    /** Public https URL to open on the device. */
+    url: string;
+    /** Relay port the diag_* tools query (may be OS-assigned). */
+    relayPort: number;
+    /** The app dev-serve port the tunnel ultimately serves. */
+    appPort: number;
+    /** Whether the app was responding when we returned (false = URL may be blank). */
+    appReady: boolean;
+    /** Tear down tunnel (+ DNS route), app dev serve, front proxy, and relay. */
+    stop: () => Promise<void>;
+}
+export declare function startPreview(opts: StartPreviewOptions): Promise<RunningPreview>;
+/**
+ * Resolve once cloudflared reports a live edge connection, reject if it exits
+ * first or never registers. Exported for unit testing the log-scan/timeout logic.
+ */
+export declare function waitForRegister(tunnel: ChildProcess, timeoutMs: number): Promise<void>;

package/dist/preview/runner.js

@@ -0,0 +1,111 @@
+// The whole preview stack behind one call. Stands up, in order: the app dev serve
+// (on an internal port), the harness relay (WS event sink + localhost /query), a
+// front proxy unifying them on one origin (`/__harness` → relay, else → app), and
+// a cloudflared tunnel to that origin so a phone gets ONE https URL that serves
+// both the app (secure context → live camera) and the diagnostics socket.
+//
+// Returns the public URL plus a `stop()` that reaps everything. A failure at any
+// step tears down what was already started, so the caller never leaks a child
+// process or a live backend tunnel. Used by both the CLI (`npm run preview`) and
+// the MCP verbs (preview_start / preview_stop).
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { startRelay } from "../relay/server.js";
+import { ensureCloudflared } from "./cloudflared.js";
+import { startSessionTunnel } from "./tunnel.js";
+import { proxyWeb, proxyWs } from "./proxy.js";
+import { getFreePort, isPortListening, waitForApp } from "./net.js";
+export async function startPreview(opts) {
+    const { projectCwd, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", registerTimeoutMs = 45_000, appReadyTimeoutMs = 8_000, onLog = () => undefined, } = opts;
+    // Resolve ports. The app port defaults to 5173; the relay + front ports are
+    // harness-internal, so auto-pick free ones (the relay port is returned for the
+    // MCP diag_* tools to point at) instead of colliding on fixed defaults.
+    const appPort = opts.appPort ?? 5173;
+    const relayPort = opts.relayPort ?? (await getFreePort());
+    const frontPort = opts.frontPort ?? (await getFreePort());
+    // If a dev server is already up on appPort, reuse it — don't spawn a second one
+    // that would fail to bind and leave the tunnel serving a broken origin.
+    const reuseApp = await isPortListening(appPort);
+    // Track every resource so any failure below can unwind exactly what started.
+    let app;
+    let relay;
+    let front;
+    let session;
+    let tunnel;
+    const stop = async () => {
+        tunnel?.kill();
+        app?.kill();
+        front?.close();
+        if (relay)
+            await relay.close();
+        if (session)
+            await session.reap();
+    };
+    try {
+        // Resolve cloudflared up front so a fresh host provisions it before we mint a
+        // tunnel we couldn't otherwise run.
+        const cloudflaredBin = await ensureCloudflared({ onLog });
+        if (reuseApp) {
+            onLog(`reusing the dev server already on :${appPort}`);
+        }
+        else {
+            app = spawn(devCommand[0], devCommand.slice(1), {
+                cwd: projectCwd,
+                env: { ...process.env, PORT: String(appPort) },
+                stdio: appStdio,
+                // Windows: npm/pnpm are .cmd shims — spawn needs a shell to resolve them.
+                shell: process.platform === "win32",
+            });
+        }
+        relay = startRelay({
+            port: relayPort,
+            path: harnessPath,
+            projectDir: projectCwd,
+            onLog: (m) => onLog(`[relay] ${m}`),
+        });
+        front = createServer((req, res) => proxyWeb(req, res, req.url?.startsWith(harnessPath) ? relayPort : appPort));
+        front.on("upgrade", (req, socket, head) => proxyWs(req, socket, head, req.url?.startsWith(harnessPath) ? relayPort : appPort));
+        await new Promise((resolve) => front.listen(frontPort, resolve));
+        session = await startSessionTunnel(projectCwd, frontPort);
+        tunnel = spawn(cloudflaredBin, ["tunnel", "run", "--token", session.runToken], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        await waitForRegister(tunnel, registerTimeoutMs);
+        // Don't hand back a live URL that serves a blank page: wait for the app to
+        // actually respond. Non-fatal — a slow build still returns, flagged not-ready.
+        const appReady = reuseApp ? true : await waitForApp(appPort, appReadyTimeoutMs);
+        if (!appReady) {
+            onLog(`app on :${appPort} isn't responding yet — the URL may be blank until it builds`);
+        }
+        return { url: session.url, relayPort, appPort, appReady, stop };
+    }
+    catch (err) {
+        await stop();
+        throw err;
+    }
+}
+/**
+ * Resolve once cloudflared reports a live edge connection, reject if it exits
+ * first or never registers. Exported for unit testing the log-scan/timeout logic.
+ */
+export function waitForRegister(tunnel, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const scan = (buf) => {
+            if (/Registered tunnel connection|Connection [^ ]+ registered/.test(String(buf))) {
+                finish(resolve);
+            }
+        };
+        tunnel.stdout?.on("data", scan);
+        tunnel.stderr?.on("data", scan);
+        tunnel.on("exit", (code) => finish(() => reject(new Error(`cloudflared exited before registering (code ${code}).`))));
+        const timer = setTimeout(() => finish(() => reject(new Error(`cloudflared did not register within ${timeoutMs}ms.`))), timeoutMs);
+    });
+}

package/dist/preview/tunnel.d.ts

@@ -0,0 +1,14 @@
+import { type MintedTunnel } from "../lib/backend.js";
+export interface SessionTunnel extends MintedTunnel {
+    /** Public https URL to open on the device. */
+    url: string;
+    /** Tear the tunnel down (DNS route + tunnel). Idempotent; call on SIGINT. */
+    reap: () => Promise<void>;
+}
+/**
+ * Mint a per-session dev tunnel for the project bound to `projectCwd`, routing
+ * <slug>-<token>.<apex> to the local `localPort`. Returns the URL to open and a
+ * `reap()` for teardown. Throws with an actionable message when the directory is
+ * unbound (run project_create) or no backend/PAT is configured.
+ */
+export declare function startSessionTunnel(projectCwd: string, localPort: number): Promise<SessionTunnel>;

package/dist/preview/tunnel.js

@@ -0,0 +1,28 @@
+// Per-session dev tunnel: resolve the project binding + machine config and mint a
+// named tunnel via the backend (which holds the Cloudflare account creds). Stays
+// free of any child-process / cloudflared coupling — the caller runs cloudflared
+// with the returned run token (see runner.ts) and calls reap() on exit.
+import { loadProjectBinding, resolveConfig } from "../shared/config.js";
+import { mintTunnel, reapTunnel } from "../lib/backend.js";
+/**
+ * Mint a per-session dev tunnel for the project bound to `projectCwd`, routing
+ * <slug>-<token>.<apex> to the local `localPort`. Returns the URL to open and a
+ * `reap()` for teardown. Throws with an actionable message when the directory is
+ * unbound (run project_create) or no backend/PAT is configured.
+ */
+export async function startSessionTunnel(projectCwd, localPort) {
+    const binding = await loadProjectBinding(projectCwd);
+    if (!binding) {
+        throw new Error("No project bound to this directory — run project_create first.");
+    }
+    const cfg = await resolveConfig(projectCwd);
+    const minted = await mintTunnel(cfg, binding.projectId, localPort);
+    return {
+        ...minted,
+        url: `https://${minted.hostname}`,
+        reap: () => reapTunnel(cfg, binding.projectId, {
+            tunnelId: minted.tunnelId,
+            dnsRecordId: minted.dnsRecordId,
+        }),
+    };
+}

package/dist/relay/annotations.d.ts

@@ -0,0 +1,30 @@
+import type { Annotation, AnnotationInput } from "@vincentt-xr/harness/events";
+export declare const ANNOTATIONS_DIR = ".vincentt/annotations";
+export declare function annotationsDir(projectDir: string): string;
+export declare class AnnotationStore {
+    private readonly projectDir;
+    private readonly dir;
+    private items;
+    private seq;
+    private waiters;
+    private loaded;
+    constructor(projectDir: string, dir?: string);
+    /** Load persisted annotations so seq continues across preview restarts. */
+    init(): Promise<void>;
+    /** Persist and register a new annotation, then wake matching long-poll waiters. */
+    add(input: AnnotationInput, opts: {
+        now: number;
+        id: string;
+    }): Promise<Annotation>;
+    /** The first annotation with seq greater than `after`, if one is already held. */
+    peekAfter(after: number): Annotation | undefined;
+    /**
+     * Long-poll: resolve with the first annotation whose seq is greater than
+     * `after`, either immediately (already held) or as soon as one arrives. Resolves
+     * null if none arrives within `timeoutMs`.
+     */
+    nextAfter(after: number, timeoutMs: number): Promise<Annotation | null>;
+    private wake;
+    /** Release any parked waiters on teardown so nothing hangs. */
+    close(): void;
+}

package/dist/relay/annotations.js

@@ -0,0 +1,126 @@
+// The relay's annotation store: the agent-agnostic core of the reverse channel.
+// The device POSTs an annotation (screenshot + spec + message) over the preview
+// tunnel; this store stamps + persists it and unblocks any long-poll consumer
+// waiting on it (`vincentt feedback --wait`). One store per preview run, bound to
+// one project directory.
+//
+// Persistence lives under <project>/.vincentt/annotations/:
+//   • <id>.png        — the full-res annotated screenshot
+//   • store.ndjson    — one JSON line per annotation (also gives seq continuity
+//                       across preview restarts, so a consumer's saved cursor stays
+//                       valid)
+// The seq is a monotonic per-project cursor: a consumer asks "next after seq N".
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export const ANNOTATIONS_DIR = ".vincentt/annotations";
+const STORE_FILE = "store.ndjson";
+export function annotationsDir(projectDir) {
+    return path.join(projectDir, ANNOTATIONS_DIR);
+}
+function decodeDataUrl(dataUrl) {
+    const comma = dataUrl.indexOf(",");
+    const payload = comma === -1 ? dataUrl : dataUrl.slice(comma + 1);
+    return Buffer.from(payload, "base64");
+}
+export class AnnotationStore {
+    projectDir;
+    dir;
+    items = [];
+    seq = 0;
+    waiters = [];
+    loaded = false;
+    constructor(projectDir, dir = annotationsDir(projectDir)) {
+        this.projectDir = projectDir;
+        this.dir = dir;
+    }
+    /** Load persisted annotations so seq continues across preview restarts. */
+    async init() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const text = await fs.readFile(path.join(this.dir, STORE_FILE), "utf8");
+            for (const line of text.split("\n")) {
+                if (!line.trim())
+                    continue;
+                const a = JSON.parse(line);
+                this.items.push(a);
+                if (a.seq > this.seq)
+                    this.seq = a.seq;
+            }
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    /** Persist and register a new annotation, then wake matching long-poll waiters. */
+    async add(input, opts) {
+        await this.init();
+        await fs.mkdir(this.dir, { recursive: true });
+        const screenshotPath = path.join(this.dir, `${opts.id}.png`);
+        await fs.writeFile(screenshotPath, decodeDataUrl(input.screenshot));
+        const spec = input.spec ?? {};
+        const annotation = {
+            id: opts.id,
+            seq: ++this.seq,
+            createdAt: opts.now,
+            projectDir: this.projectDir,
+            message: input.message,
+            screenshotPath,
+            spec,
+            sessionId: input.sessionId,
+        };
+        this.items.push(annotation);
+        await fs.appendFile(path.join(this.dir, STORE_FILE), JSON.stringify(annotation) + "\n");
+        this.wake(annotation);
+        return annotation;
+    }
+    /** The first annotation with seq greater than `after`, if one is already held. */
+    peekAfter(after) {
+        return this.items.find((a) => a.seq > after);
+    }
+    /**
+     * Long-poll: resolve with the first annotation whose seq is greater than
+     * `after`, either immediately (already held) or as soon as one arrives. Resolves
+     * null if none arrives within `timeoutMs`.
+     */
+    nextAfter(after, timeoutMs) {
+        const held = this.peekAfter(after);
+        if (held)
+            return Promise.resolve(held);
+        return new Promise((resolve) => {
+            const waiter = {
+                after,
+                resolve,
+                timer: setTimeout(() => {
+                    this.waiters = this.waiters.filter((w) => w !== waiter);
+                    resolve(null);
+                }, timeoutMs),
+            };
+            waiter.timer.unref?.();
+            this.waiters.push(waiter);
+        });
+    }
+    wake(a) {
+        const remaining = [];
+        for (const w of this.waiters) {
+            if (a.seq > w.after) {
+                clearTimeout(w.timer);
+                w.resolve(a);
+            }
+            else {
+                remaining.push(w);
+            }
+        }
+        this.waiters = remaining;
+    }
+    /** Release any parked waiters on teardown so nothing hangs. */
+    close() {
+        for (const w of this.waiters) {
+            clearTimeout(w.timer);
+            w.resolve(null);
+        }
+        this.waiters = [];
+    }
+}

package/dist/relay/injectors.d.ts

@@ -0,0 +1,29 @@
+import type { Annotation } from "@vincentt-xr/harness/events";
+export interface Injector {
+    /** Stable id for config/logging: "claude-code" | "paste" | … */
+    readonly name: string;
+    /** Cheap best-effort readiness probe. The dispatcher skips unavailable injectors. */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Deliver so the agent acts with zero user action. Resolves when the host
+     * accepted the injection (not when the agent finishes). Throws if it couldn't —
+     * the dispatcher falls through to the next injector (paste never throws).
+     */
+    inject(a: Annotation): Promise<void>;
+}
+export interface Dispatcher {
+    dispatch(a: Annotation): Promise<string>;
+}
+/** Walk the injector chain; first available that accepts wins, else fall through. */
+export declare function createDispatcher(injectors: Injector[], onLog?: (msg: string) => void): Dispatcher;
+/**
+ * Claude Code passive injector: append the annotation to a queue a running `/loop`
+ * drains. Available only when the queue dir exists (the loop has been set up), so a
+ * project with no loop configured falls through to the fallback.
+ */
+export declare function claudeCodeInjector(queuePath: string): Injector;
+/**
+ * Universal never-fail fallback. When no zero-action injector accepted the
+ * annotation, stage a ready prompt so the worst case is a single paste.
+ */
+export declare function pasteInjector(onReady: (prompt: string) => void): Injector;

package/dist/relay/injectors.js

@@ -0,0 +1,72 @@
+// The one per-agent seam of the reverse channel (docs/harness-annotation-push.md).
+// Everything upstream — capture, relay, store — is agent-agnostic; turning a
+// stored annotation into an agent turn goes through an Injector. The dispatcher
+// walks an ordered chain: the first available injector that accepts wins, and on
+// failure it falls through to the next. The final injector never fails.
+//
+// This change ships only the Claude Code passive injector (append to the queue a
+// running `/loop` drains) plus the never-fail paste fallback. Active injectors and
+// other agents' injectors are follow-ups behind this same interface.
+import { appendFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+/** Walk the injector chain; first available that accepts wins, else fall through. */
+export function createDispatcher(injectors, onLog = () => undefined) {
+    return {
+        async dispatch(a) {
+            for (const inj of injectors) {
+                try {
+                    if (!(await inj.isAvailable()))
+                        continue;
+                    await inj.inject(a);
+                    onLog(`annotation ${a.id} → ${inj.name}`);
+                    return inj.name;
+                }
+                catch (err) {
+                    onLog(`injector ${inj.name} failed: ${err.message}; falling back`);
+                }
+            }
+            // Unreachable when a never-fail fallback (pasteInjector) terminates the chain.
+            throw new Error("no injector accepted the annotation");
+        },
+    };
+}
+/**
+ * Claude Code passive injector: append the annotation to a queue a running `/loop`
+ * drains. Available only when the queue dir exists (the loop has been set up), so a
+ * project with no loop configured falls through to the fallback.
+ */
+export function claudeCodeInjector(queuePath) {
+    return {
+        name: "claude-code",
+        async isAvailable() {
+            return existsSync(path.dirname(queuePath));
+        },
+        async inject(a) {
+            await mkdir(path.dirname(queuePath), { recursive: true });
+            const line = JSON.stringify({
+                id: a.id,
+                seq: a.seq,
+                message: a.message,
+                screenshot: a.screenshotPath,
+                spec: a.spec,
+            }) + "\n";
+            await appendFile(queuePath, line, "utf8");
+        },
+    };
+}
+/**
+ * Universal never-fail fallback. When no zero-action injector accepted the
+ * annotation, stage a ready prompt so the worst case is a single paste.
+ */
+export function pasteInjector(onReady) {
+    return {
+        name: "paste",
+        async isAvailable() {
+            return true;
+        },
+        async inject(a) {
+            onReady(`Review annotation ${a.id}: ${a.message}\nScreenshot: ${a.screenshotPath}`);
+        },
+    };
+}

package/dist/relay/server.d.ts

@@ -0,0 +1,24 @@
+import { EventStore } from "./store.js";
+import { AnnotationStore } from "./annotations.js";
+import { type Dispatcher } from "./injectors.js";
+export interface RelayOptions {
+    port?: number;
+    /** WS path the client connects to (default matches HarnessProvider). */
+    path?: string;
+    capacity?: number;
+    onLog?: (msg: string) => void;
+    /** Bind the reverse channel to this project dir (enables annotation routes). */
+    projectDir?: string;
+    /** Injected for tests; else built from projectDir. */
+    annotationStore?: AnnotationStore;
+    /** Injected for tests; else a Claude-Code-passive → paste chain. */
+    dispatcher?: Dispatcher;
+    /** Injected for tests. */
+    makeId?: () => string;
+}
+export interface RelayHandle {
+    store: EventStore;
+    annotations?: AnnotationStore;
+    close: () => Promise<void>;
+}
+export declare function startRelay(opts?: RelayOptions): RelayHandle;