humanish 0.20.3 → 0.20.5

package/dist/comms-faux-inbox.d.ts

@@ -0,0 +1,37 @@
+import type { CommsAddress, CommsChannel, CommsChannelKind, CommsMessage, InboundRaw, OutboundMessage } from "./comms-types.js";
+/** Extract actionable http(s) links from a message body (href="…" and bare URLs), de-duped, in order.
+ *  The verification magic-link the persona would tap. Pure; body is runtime-only. */
+export declare function extractLinks(body: string): string[];
+/** Extract OTP-shaped tokens from a message body. Labeled codes ("your code is 481920",
+ *  "verification code 8A3F2K") are high-precision and preferred; if none are labeled, fall back to an
+ *  isolated 4–8 digit run (a bare OTP). Pure; tokens are runtime-only literal-scrub targets. */
+export declare function extractOtpCodes(body: string): string[];
+export interface FauxInboxOptions {
+    /** "email" (default) or "sms" — the address shape + surface differ; machinery is identical. */
+    channel?: CommsChannelKind;
+    /** Email domain for minted addresses. Default example.test (an RFC 6761 reserved, unroutable test
+     *  domain — public-safe; override to a branded reserved domain once it's added to the email allowlist). */
+    domain?: string;
+    /** Injected clock (ms) for deterministic tests. Default Date.now. */
+    now?: () => number;
+}
+/** The in-process faux adapter. Implements the same CommsChannel port a real provider adapter would. */
+export declare class FauxInbox implements CommsChannel {
+    readonly channel: CommsChannelKind;
+    readonly kind: "faux";
+    private readonly domain;
+    private readonly clock;
+    private readonly byActor;
+    private readonly byValue;
+    private readonly queues;
+    private counter;
+    constructor(options?: FauxInboxOptions);
+    provision(actorId: string): Promise<CommsAddress>;
+    private route;
+    send(message: OutboundMessage): Promise<CommsMessage>;
+    deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;
+    poll(address: CommsAddress, since?: number): Promise<CommsMessage[]>;
+    teardown(): Promise<void>;
+    /** Inspection helper (tests / a surface): every inbox currently provisioned. */
+    addresses(): CommsAddress[];
+}

package/dist/comms-faux-inbox.js

@@ -0,0 +1,147 @@
+// The FAUX in-process email/SMS bus (#297 Stage 2). Deterministic, $0, offline, public-safe: a
+// message an app-under-test "sends" (via an ingress like the Resend catch) is routed to the
+// addressed actor inbox and read back through the same CommsChannel port a real provider adapter
+// would implement. Nothing leaves the process. See comms-types.ts for the port + public-safety notes.
+import { digestText } from "./redaction.js";
+/** Extract actionable http(s) links from a message body (href="…" and bare URLs), de-duped, in order.
+ *  The verification magic-link the persona would tap. Pure; body is runtime-only. */
+export function extractLinks(body) {
+    if (typeof body !== "string" || body.length === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const push = (raw) => {
+        const url = raw.trim().replace(/[).,;'"]+$/, "");
+        if (/^https?:\/\//i.test(url) && !seen.has(url)) {
+            seen.add(url);
+            out.push(url);
+        }
+    };
+    let m;
+    const href = /href\s*=\s*["']([^"']+)["']/gi;
+    while ((m = href.exec(body)) !== null)
+        push(m[1] ?? "");
+    const bare = /https?:\/\/[^\s"'<>)\]]+/gi;
+    while ((m = bare.exec(body)) !== null)
+        push(m[0]);
+    return out.slice(0, 50);
+}
+function stripTags(html) {
+    return html
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Extract OTP-shaped tokens from a message body. Labeled codes ("your code is 481920",
+ *  "verification code 8A3F2K") are high-precision and preferred; if none are labeled, fall back to an
+ *  isolated 4–8 digit run (a bare OTP). Pure; tokens are runtime-only literal-scrub targets. */
+export function extractOtpCodes(body) {
+    if (typeof body !== "string" || body.length === 0)
+        return [];
+    const text = stripTags(body);
+    const labeled = [];
+    const seen = new Set();
+    const push = (list, code) => {
+        const c = code.toUpperCase();
+        if (c && !seen.has(c)) {
+            seen.add(c);
+            list.push(c);
+        }
+    };
+    const labeledRe = /(?:one[-\s]?time\s+(?:pass)?code|verification\s+code|security\s+code|access\s+code|login\s+code|confirmation\s+code|passcode|\bOTP\b|\bPIN\b|\bcode\b)\D{0,15}\b([0-9]{4,8}|[A-Z0-9]{6,8})\b/gi;
+    let m;
+    while ((m = labeledRe.exec(text)) !== null)
+        push(labeled, m[1] ?? "");
+    if (labeled.length > 0)
+        return labeled.slice(0, 10);
+    // Fallback: an isolated 4–8 digit run (a bare, unlabeled OTP), not embedded in a longer token.
+    const bare = [];
+    const bareRe = /(?<![0-9A-Za-z])([0-9]{4,8})(?![0-9A-Za-z])/g;
+    while ((m = bareRe.exec(text)) !== null)
+        push(bare, m[1] ?? "");
+    return bare.slice(0, 10);
+}
+function sanitizeLocalPart(actorId) {
+    return actorId.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "actor";
+}
+function smsAddressFor(actorId) {
+    const digits = digestText(actorId, 16).replace(/[a-f]/g, (c) => String(c.charCodeAt(0) % 10)).slice(0, 7);
+    return `+1555${digits}`;
+}
+/** The in-process faux adapter. Implements the same CommsChannel port a real provider adapter would. */
+export class FauxInbox {
+    channel;
+    kind = "faux";
+    domain;
+    clock;
+    byActor = new Map();
+    byValue = new Map();
+    queues = new Map();
+    counter = 0;
+    constructor(options = {}) {
+        this.channel = options.channel ?? "email";
+        this.domain = options.domain ?? "example.test";
+        this.clock = options.now ?? (() => Date.now());
+    }
+    async provision(actorId) {
+        const existing = this.byActor.get(actorId);
+        if (existing)
+            return existing;
+        const value = this.channel === "sms" ? smsAddressFor(actorId) : `${sanitizeLocalPart(actorId)}@${this.domain}`;
+        const address = { channel: this.channel, actorId, value, digest: digestText(value, 16) };
+        this.byActor.set(actorId, address);
+        this.byValue.set(value.toLowerCase(), address);
+        this.queues.set(value.toLowerCase(), []);
+        return address;
+    }
+    route(from, to, subject, body) {
+        const at = this.clock();
+        const message = {
+            id: `comms-${(this.counter += 1).toString().padStart(4, "0")}`,
+            channel: this.channel,
+            from,
+            to,
+            ...(subject === undefined ? {} : { subject }),
+            body,
+            links: extractLinks(body),
+            codes: extractOtpCodes(body),
+            sentAt: at,
+            deliveredAt: at
+        };
+        for (const addr of to) {
+            const queue = this.queues.get(addr.value.toLowerCase());
+            if (queue)
+                queue.push(message);
+        }
+        return message;
+    }
+    async send(message) {
+        return this.route(message.from.value, message.to, message.subject, message.body);
+    }
+    async deliverRaw(inbound) {
+        const to = (inbound.to ?? [])
+            .map((raw) => this.byValue.get(String(raw).trim().toLowerCase()))
+            .filter((address) => address !== undefined);
+        if (to.length === 0)
+            return []; // no provisioned inbox matched → nothing to deliver to
+        return [this.route(inbound.from, to, inbound.subject, inbound.body)];
+    }
+    async poll(address, since = 0) {
+        const queue = this.queues.get(address.value.toLowerCase()) ?? [];
+        return queue.filter((message) => message.deliveredAt > since);
+    }
+    async teardown() {
+        this.byActor.clear();
+        this.byValue.clear();
+        this.queues.clear();
+        this.counter = 0;
+    }
+    /** Inspection helper (tests / a surface): every inbox currently provisioned. */
+    addresses() {
+        return [...this.byActor.values()];
+    }
+}
+//# sourceMappingURL=comms-faux-inbox.js.map

package/dist/comms-faux-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-faux-inbox.js","sourceRoot":"","sources":["../src/comms-faux-inbox.ts"],"names":[],"mappings":"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"}

package/dist/comms-resend-catch.d.ts

@@ -0,0 +1,30 @@
+import type { CommsChannel } from "./comms-types.js";
+/** A Resend send payload we accepted, normalized (runtime-only; for inspection/tests). */
+export interface ResendEmailPayload {
+    from: string;
+    to: string[];
+    subject?: string;
+    html?: string;
+    text?: string;
+}
+export interface ResendCatchServer {
+    /** Point the app here: `RESEND_BASE_URL=<url>` (loopback only). */
+    readonly url: string;
+    readonly port: number;
+    /** Every payload accepted this run (runtime-only). */
+    readonly received: ResendEmailPayload[];
+    close(): Promise<void>;
+}
+export interface ResendCatchOptions {
+    /** Bind host. Default 127.0.0.1 (loopback ONLY — never bind a public interface). */
+    host?: string;
+    /** Port. Default 0 (ephemeral — read the chosen port off the returned server). */
+    port?: number;
+    /** Deterministic id for the Resend-shaped response (tests). Default a zero-padded counter. */
+    idFor?: (n: number) => string;
+}
+/**
+ * Start the Resend-shaped catch server, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as `RESEND_BASE_URL`. `close()` in a finally (mirror by-id teardown).
+ */
+export declare function startResendCatchServer(channel: CommsChannel, options?: ResendCatchOptions): Promise<ResendCatchServer>;

package/dist/comms-resend-catch.js

@@ -0,0 +1,120 @@
+// A LOOPBACK catch server that speaks the Resend `POST /emails` wire shape, so an app hardwired to
+// Resend is redirected into the faux bus with ONE env var and no code change: point the app at this
+// server via `RESEND_BASE_URL=<url>` (the official `resend` Node SDK reads that env var / a `baseUrl`
+// option). The app's real verification email POSTs here instead of api.resend.com; we route it into
+// the CommsChannel and the persona reads it. Nothing is delivered onward. (#297 — the API-first
+// analog of pointing SMTP at a local catcher, since Resend is HTTPS-first and its own SMTP delivers
+// for real.) 127.0.0.1 only; bodies are never logged.
+import { createServer } from "node:http";
+/** "Name <email@host>" → "email@host"; a bare address passes through. */
+function bareEmail(value) {
+    const angle = value.match(/<([^>]+)>/);
+    return (angle ? angle[1] ?? value : value).trim();
+}
+function asStringArray(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => String(entry));
+    if (typeof value === "string")
+        return [value];
+    return [];
+}
+function normalizeResendPayload(payload) {
+    return {
+        from: typeof payload.from === "string" ? payload.from : "",
+        to: asStringArray(payload.to).map(bareEmail),
+        ...(typeof payload.subject === "string" ? { subject: payload.subject } : {}),
+        ...(typeof payload.html === "string" ? { html: payload.html } : {}),
+        ...(typeof payload.text === "string" ? { text: payload.text } : {})
+    };
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                req.destroy();
+                reject(new Error("request body too large"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/**
+ * Start the Resend-shaped catch server, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as `RESEND_BASE_URL`. `close()` in a finally (mirror by-id teardown).
+ */
+export async function startResendCatchServer(channel, options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const received = [];
+    let idCounter = 0;
+    const idFor = options.idFor ?? ((n) => `humanish-catch-${n.toString().padStart(6, "0")}`);
+    const respondJson = (res, status, value) => {
+        res.statusCode = status;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify(value));
+    };
+    const handle = async (req, res) => {
+        const path = (req.url ?? "/").split("?")[0];
+        if (req.method === "GET" && (path === "/" || path === "/health")) {
+            respondJson(res, 200, { ok: true, service: "humanish-resend-catch", channel: channel.channel });
+            return;
+        }
+        // Resend's send endpoints: POST /emails (single) and /emails/batch. Batch is an array of sends.
+        if (req.method === "POST" && (path === "/emails" || path === "/emails/batch")) {
+            const raw = await readBody(req, MAX_BODY_BYTES);
+            let parsed;
+            try {
+                parsed = JSON.parse(raw.length > 0 ? raw : "{}");
+            }
+            catch {
+                respondJson(res, 422, { error: "invalid JSON body" });
+                return;
+            }
+            const items = Array.isArray(parsed) ? parsed : [parsed];
+            const ids = [];
+            for (const item of items) {
+                if (typeof item !== "object" || item === null)
+                    continue;
+                const payload = normalizeResendPayload(item);
+                received.push(payload);
+                const inbound = {
+                    from: payload.from,
+                    to: payload.to,
+                    ...(payload.subject === undefined ? {} : { subject: payload.subject }),
+                    body: payload.html ?? payload.text ?? ""
+                };
+                await channel.deliverRaw(inbound);
+                idCounter += 1;
+                ids.push(idFor(idCounter));
+            }
+            // Resend-shaped response: a single send returns { id }; a batch returns { data: [{ id }, …] }.
+            if (path === "/emails/batch")
+                respondJson(res, 200, { data: ids.map((id) => ({ id })) });
+            else
+                respondJson(res, 200, { id: ids[0] ?? idFor(idCounter) });
+            return;
+        }
+        respondJson(res, 404, { error: "not found" });
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch(() => {
+            if (!res.headersSent)
+                respondJson(res, 500, { error: "catch server error" });
+        });
+    });
+    await new Promise((resolve) => server.listen(options.port ?? 0, host, () => resolve()));
+    const port = server.address().port;
+    return {
+        url: `http://${host}:${port}`,
+        port,
+        received,
+        close: () => new Promise((resolve) => server.close(() => resolve()))
+    };
+}
+//# sourceMappingURL=comms-resend-catch.js.map

package/dist/comms-resend-catch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-resend-catch.js","sourceRoot":"","sources":["../src/comms-resend-catch.ts"],"names":[],"mappings":"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"}

package/dist/comms-types.d.ts

@@ -0,0 +1,63 @@
+export type CommsChannelKind = "email" | "sms";
+/** One actor's inbox identity. `value` is runtime-only; `digest` is the only form meant to persist. */
+export interface CommsAddress {
+    channel: CommsChannelKind;
+    /** Which lane owns this inbox. */
+    actorId: string;
+    /** Runtime-only raw address, e.g. patient-07@example.test | +15550137. */
+    value: string;
+    /** sha256-short(value) — the only form persisted (redaction.digestText). */
+    digest: string;
+}
+/** A message that arrived to (or was sent from) an inbox. Body/links/codes are runtime-only. */
+export interface CommsMessage {
+    id: string;
+    channel: CommsChannelKind;
+    /** Raw sender — an app-under-test address, or another actor's address. Runtime-only. */
+    from: string;
+    /** Resolved recipient inboxes this message was delivered to. */
+    to: CommsAddress[];
+    subject?: string;
+    /** Runtime-only for real; local-only for faux (never a share path without redaction — #108). */
+    body: string;
+    /** Actionable links extracted from the body (magic-link / invite / reset). Runtime-only. */
+    links: string[];
+    /** OTP-shaped tokens extracted from the body. Runtime-only; literal-scrub targets. */
+    codes: string[];
+    sentAt: number;
+    deliveredAt: number;
+}
+/** An actor sending OUT (a reply/compose); recipients are known CommsAddresses. */
+export interface OutboundMessage {
+    from: CommsAddress;
+    to: CommsAddress[];
+    subject?: string;
+    body: string;
+}
+/** A raw inbound from an INGRESS (the Resend catch, an SMTP sink, …): recipients are raw address
+ *  strings the bus resolves against its provisioned inboxes. */
+export interface InboundRaw {
+    from: string;
+    to: string[];
+    subject?: string;
+    body: string;
+}
+/**
+ * The port. Faux (in-process) + real-email + real-sms adapters implement it identically. Async so a
+ * real (network) adapter fits without changing callers; the faux adapter just resolves immediately.
+ */
+export interface CommsChannel {
+    readonly channel: CommsChannelKind;
+    readonly kind: "faux" | "real";
+    /** Mint/allocate an inbox for an actor (address auto-generated). Idempotent per actor. */
+    provision(actorId: string): Promise<CommsAddress>;
+    /** Route a composed message from one actor to addressed inboxes. Returns the delivered record. */
+    send(message: OutboundMessage): Promise<CommsMessage>;
+    /** Route a raw ingress delivery (app-under-test → recipient strings). Returns the messages that
+     *  matched a provisioned inbox (unmatched recipients are dropped — no inbox to deliver to). */
+    deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;
+    /** New messages delivered to `address` since `since` (exclusive), oldest-first. Drives the surface. */
+    poll(address: CommsAddress, since?: number): Promise<CommsMessage[]>;
+    /** Release inboxes BY id (mirror the by-id sandbox teardown rail). */
+    teardown(): Promise<void>;
+}

package/dist/comms-types.js

@@ -0,0 +1,10 @@
+// The addressed message bus (#297) — the seam that makes "off-app" comms (email/SMS the persona
+// actually lives in) a first-class, persona-driven testable surface. A single port, addressed by
+// actor; faux (in-process) and real (provider-backed) adapters implement it identically, so the
+// persona surface + evidence writer consume it without knowing which is behind it.
+//
+// PUBLIC-SAFETY: raw address values, message bodies, links, and codes are RUNTIME-ONLY. Only the
+// address DIGEST (sha256-short, via redaction.digestText) is ever meant to reach a persisted bundle;
+// a verification link / OTP has "no secret shape" (like the lobby code) → literal-scrub + digest.
+export {};
+//# sourceMappingURL=comms-types.js.map

package/dist/comms-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-types.js","sourceRoot":"","sources":["../src/comms-types.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,iGAAiG;AACjG,gGAAgG;AAChG,mFAAmF;AACnF,EAAE;AACF,iGAAiG;AACjG,qGAAqG;AACrG,kGAAkG"}

package/dist/index.d.ts

@@ -17,6 +17,11 @@ export type { FetchLike, OpenAiResponsesProviderOptions } from "./openai-respons
 export { adapterScoreFailureMessage, applyAdapterScoreFailureToReview, applyBrowserAdapterHooks } from "./adapter-extension.js";
 export type { BrowserAdapterBackend, BrowserLabAdapterHooks, BrowserLabScoringContext } from "./adapter-extension.js";
 export type { RedactionHooks } from "./redaction.js";
+export { FauxInbox, extractLinks, extractOtpCodes } from "./comms-faux-inbox.js";
+export type { FauxInboxOptions } from "./comms-faux-inbox.js";
+export { startResendCatchServer } from "./comms-resend-catch.js";
+export type { ResendCatchOptions, ResendCatchServer, ResendEmailPayload } from "./comms-resend-catch.js";
+export type { CommsAddress, CommsChannel, CommsChannelKind, CommsMessage, InboundRaw, OutboundMessage } from "./comms-types.js";
 export { DESKTOP_RATE, MODEL_RATES, PRICING_SCHEMA, estimateActorCost, estimateDesktopCost } from "./pricing.js";
 export type { ActorEstimatedCost, DesktopCostEstimate, DesktopRate, ModelRate } from "./pricing.js";
 export { normalizeCliArgv } from "./argv.js";

package/dist/index.js

@@ -7,6 +7,11 @@ export { createE2BDesktopExecutor } from "./e2b-desktop-executor.js";
 export { loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 export { DEFAULT_OPENAI_CU_MODEL, OPENAI_RESPONSES_CU_CAPABILITIES, createOpenAiResponsesProvider } from "./openai-responses-cu.js";
 export { adapterScoreFailureMessage, applyAdapterScoreFailureToReview, applyBrowserAdapterHooks } from "./adapter-extension.js";
+// Addressed comms bus (#297): faux email/SMS inboxes + the Resend-shaped ingress that redirects an
+// API-first app into the faux bus with one env var. Real (provider-backed) adapters implement the
+// same CommsChannel port.
+export { FauxInbox, extractLinks, extractOtpCodes } from "./comms-faux-inbox.js";
+export { startResendCatchServer } from "./comms-resend-catch.js";
 export { DESKTOP_RATE, MODEL_RATES, PRICING_SCHEMA, estimateActorCost, estimateDesktopCost } from "./pricing.js";
 export { normalizeCliArgv } from "./argv.js";
 export { CODEX_APP_SERVER_UI_SCHEMA, startCodexAppServerUi } from "./codex-app-server-ui.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/observer-assets.js

@@ -417,6 +417,20 @@ a { color: inherit; text-decoration: none; }
 /* ============================================================ STREAM SURFACES */
 .surface-fill { position: absolute; inset: 0; width: 100%; height: 100%; }
 .surface-screenshot { object-fit: contain; object-position: top center; }
+/* Replay scrubber (#292 first slice): a per-turn keyframe timeline built from persisted frames + trace. */
+.replay { position: absolute; inset: 0; display: flex; flex-direction: column; background: #0b0d10; }
+.replay-stage { position: relative; flex: 1 1 auto; min-height: 0; }
+.replay-badge { position: absolute; top: 6px; right: 8px; z-index: 2; font-size: 9px; text-transform: uppercase; letter-spacing: .04em; color: var(--text-2); background: rgba(0,0,0,.55); border: 1px solid var(--line-2); border-radius: 999px; padding: 2px 7px; }
+.replay-bar { flex: 0 0 auto; display: flex; align-items: center; gap: 6px; padding: 6px 8px; border-top: 1px solid var(--line-2); background: var(--surface-2); }
+.replay-btn { display: inline-flex; align-items: center; justify-content: center; width: 26px; height: 26px; border-radius: 7px; border: 1px solid var(--line-2); background: transparent; color: var(--text-1); cursor: pointer; }
+.replay-btn:hover { background: var(--surface-3); }
+.replay-range { flex: 1 1 auto; accent-color: var(--accent-color); cursor: pointer; height: 4px; min-width: 40px; }
+.replay-count { flex: 0 0 auto; font-size: 11px; color: var(--text-2); min-width: 44px; text-align: right; }
+.replay-info { flex: 0 0 auto; max-height: 32%; overflow-y: auto; padding: 8px 10px; border-top: 1px solid var(--line-2); background: var(--surface-1); font-size: 12px; line-height: 1.5; color: var(--text-1); }
+.replay-acts { display: flex; flex-wrap: wrap; gap: 4px; margin-bottom: 6px; }
+.replay-act { font-family: var(--mono); font-size: 10px; color: var(--text-2); background: var(--surface-3); border: 1px solid var(--line-2); border-radius: 5px; padding: 2px 6px; }
+.replay-narr { white-space: pre-wrap; color: var(--text-1); }
+.replay-dim { color: var(--text-2); font-style: italic; }
 .live-stream-mount { position: absolute; inset: 0; overflow: hidden; background: #000; }
 .live-stream-overlay { position: absolute; overflow: hidden; pointer-events: none; z-index: 2; }
 .live-stream-overlay[data-focus="true"] .bw-lab-dock { max-height: 86px; }
@@ -1143,6 +1157,12 @@ export function observerClientJs() {
     motion: readPref("motion", "full")
   };
   var artifactCache = {};
+  // Replay-scrubber state: per-stream current frame index + auto-advance timer. Kept OUTSIDE the S
+  // render-state so a data-poll re-render preserves the scrub position; indices survive because
+  // render() reads scrubIndexFor() (which defaults to the last frame — also fixing the "finished lane
+  // cuts to black" symptom). Timers are cleared on every render() so playback never orphans.
+  var scrubState = {};
+  var scrubTimers = {};
   var liveStreamFrames = {};
   var liveStreamHost = null;
   var liveStreamLayoutRaf = null;
@@ -1198,7 +1218,9 @@ export function observerClientJs() {
     lock: '<rect x="4.5" y="10" width="15" height="10" rx="2"' + P + '/><path d="M8 10V7a4 4 0 0 1 8 0v3"' + P + '/>',
     caret: '<path d="m6 9 6 6 6-6"' + P + '/>',
     filter: '<path d="M3 5h18l-7 8.2V20l-4-2.2v-4.6L3 5Z"' + P + '/>',
-    panelRight: '<rect x="3" y="4" width="18" height="16" rx="2"' + P + '/><path d="M15 4v16"' + P + '/>'
+    panelRight: '<rect x="3" y="4" width="18" height="16" rx="2"' + P + '/><path d="M15 4v16"' + P + '/>',
+    play: '<path d="M7 5l12 7-12 7z"' + P + '/>',
+    pause: '<path d="M9 5v14M15 5v14"' + P + '/>'
   };
   function icon(name, size) {
     var s = size || 18;
@@ -1605,14 +1627,147 @@ export function observerClientJs() {
     }
     return '<div class="wait"><div class="wait-inner">' + inner + '</div></div>';
   }
+  // ---------------------------------------------------------------- replay scrubber
+  // A durable per-turn keyframe replay built PURELY from the artifacts already in the bundle: the
+  // ordered actor.items (reasoning/message/ui_action) sequenced against each persisted screenshot.
+  // No new capture, no schema change, no new privacy surface — it reuses the frames' existing
+  // gitignored / publishable:false posture. (#292 first slice.)
+  function replayFrames(s) {
+    var actor = s && s.actor;
+    var items = actor && actor.items;
+    if (!items || !items.length) return [];
+    var frames = [];
+    var narration = [];
+    var actions = [];
+    for (var i = 0; i < items.length; i += 1) {
+      var it = items[i];
+      if (!it) continue;
+      if (it.kind === "reasoning" || it.kind === "message") { if (it.text) narration.push(String(it.text)); }
+      else if (it.kind === "ui_action") { if (it.title) actions.push(String(it.title)); }
+      else if (it.kind === "screenshot" && it.screenshotRef && it.screenshotRef.path) {
+        frames.push({
+          src: it.screenshotRef.path,
+          label: it.title || ("frame " + (frames.length + 1)),
+          redaction: (it.screenshotRef.redaction && it.screenshotRef.redaction !== "none") ? it.screenshotRef.redaction : "raw",
+          narration: narration,
+          actions: actions
+        });
+        narration = [];
+        actions = [];
+      }
+    }
+    return frames;
+  }
+  function streamById(id) {
+    var ss = currentData.streams || [];
+    for (var i = 0; i < ss.length; i += 1) { if (ss[i].id === id) return ss[i]; }
+    return null;
+  }
+  function scrubIndexOf(id, frames) {
+    var v = scrubState[id];
+    if (v == null) return frames.length ? frames.length - 1 : 0; // default: the last real frame
+    v = Number(v);
+    if (!(v >= 0)) v = 0;
+    if (v > frames.length - 1) v = frames.length - 1;
+    return v;
+  }
+  function frameInfoHtml(f) {
+    if (!f) return "";
+    var out = "";
+    var acts = (f.actions || []).filter(Boolean);
+    var narr = (f.narration || []).filter(Boolean);
+    if (acts.length) out += '<div class="replay-acts">' + acts.map(function (a) { return '<span class="replay-act">' + esc(a) + '</span>'; }).join("") + '</div>';
+    if (narr.length) out += '<div class="replay-narr">' + esc(narr.join(NL + NL)) + '</div>';
+    if (!out) out = '<div class="replay-narr replay-dim">No narration recorded before this frame.</div>';
+    return out;
+  }
+  function replayScrubber(s) {
+    var frames = replayFrames(s);
+    var id = s.id;
+    var idx = scrubIndexOf(id, frames);
+    var f = frames[idx];
+    var playing = !!scrubTimers[id];
+    return '<div class="replay" data-stream="' + esc(id) + '">'
+      + '<div class="replay-stage"><img class="surface-fill surface-screenshot" id="replay-img-' + esc(id) + '" src="' + esc(runArtifactHref(f && f.src)) + '" alt="replay frame ' + (idx + 1) + '"/>'
+      + '<span class="replay-badge" id="replay-badge-' + esc(id) + '" title="frame capture fidelity">' + esc(f ? f.redaction : "raw") + '</span></div>'
+      + '<div class="replay-bar">'
+      + '<button class="replay-btn" id="replay-play-' + esc(id) + '" data-action="scrub:' + esc(id) + ':play" aria-label="Play replay">' + icon(playing ? "pause" : "play", 13) + '</button>'
+      + '<button class="replay-btn" data-action="scrub:' + esc(id) + ':-1" aria-label="Previous frame">' + icon("chevL", 13) + '</button>'
+      + '<input class="replay-range" type="range" data-role="scrub" data-stream="' + esc(id) + '" min="0" max="' + (frames.length - 1) + '" step="1" value="' + idx + '" aria-label="Scrub frames"/>'
+      + '<button class="replay-btn" data-action="scrub:' + esc(id) + ':1" aria-label="Next frame">' + icon("chevR", 13) + '</button>'
+      + '<span class="replay-count mono" id="replay-count-' + esc(id) + '">' + (idx + 1) + '/' + frames.length + '</span>'
+      + '</div>'
+      + '<div class="replay-info" id="replay-info-' + esc(id) + '">' + frameInfoHtml(f) + '</div>'
+      + '</div>';
+  }
+  function updateScrubDom(id) {
+    var s = streamById(id);
+    if (!s) return;
+    var frames = replayFrames(s);
+    if (!frames.length) return;
+    var idx = scrubIndexOf(id, frames);
+    var f = frames[idx];
+    var img = document.getElementById("replay-img-" + id);
+    if (img) img.setAttribute("src", runArtifactHref(f && f.src));
+    var badge = document.getElementById("replay-badge-" + id);
+    if (badge) badge.textContent = f ? f.redaction : "raw";
+    var cnt = document.getElementById("replay-count-" + id);
+    if (cnt) cnt.textContent = (idx + 1) + "/" + frames.length;
+    var info = document.getElementById("replay-info-" + id);
+    if (info) info.innerHTML = frameInfoHtml(f);
+    var range = app.querySelector('.replay-range[data-stream="' + id + '"]');
+    if (range && String(range.value) !== String(idx)) range.value = idx;
+  }
+  function syncPlayBtn(id) {
+    var btn = document.getElementById("replay-play-" + id);
+    if (btn) btn.innerHTML = icon(scrubTimers[id] ? "pause" : "play", 13);
+  }
+  function stopScrubPlay(id) {
+    if (scrubTimers[id]) { clearInterval(scrubTimers[id]); delete scrubTimers[id]; syncPlayBtn(id); }
+  }
+  function stopAllScrubTimers() {
+    for (var k in scrubTimers) { if (scrubTimers.hasOwnProperty(k)) clearInterval(scrubTimers[k]); }
+    scrubTimers = {};
+  }
+  function toggleScrubPlay(id) {
+    if (scrubTimers[id]) { stopScrubPlay(id); return; }
+    var s = streamById(id);
+    var frames = s ? replayFrames(s) : [];
+    if (frames.length < 2) return;
+    if (scrubIndexOf(id, frames) >= frames.length - 1) { scrubState[id] = 0; updateScrubDom(id); } // restart from the top
+    scrubTimers[id] = setInterval(function () {
+      var st = streamById(id);
+      var fr = st ? replayFrames(st) : [];
+      if (fr.length < 2) { stopScrubPlay(id); return; }
+      var cur = scrubIndexOf(id, fr);
+      if (cur >= fr.length - 1) { stopScrubPlay(id); return; }
+      scrubState[id] = cur + 1;
+      updateScrubDom(id);
+    }, 850);
+    syncPlayBtn(id);
+  }
+  function handleScrub(id, op) {
+    var s = streamById(id);
+    var frames = s ? replayFrames(s) : [];
+    if (!frames.length) return;
+    if (op === "play") { toggleScrubPlay(id); return; }
+    stopScrubPlay(id);
+    var idx = scrubIndexOf(id, frames) + Number(op);
+    if (idx < 0) idx = 0;
+    if (idx > frames.length - 1) idx = frames.length - 1;
+    scrubState[id] = idx;
+    updateScrubDom(id);
+  }
   function browserSurface(s, focus) {
     var live = tone(s.status) === "running";
     var route = laneRoute(s) || "(local)";
     var liveUrl = browserLiveUrl(s);
     var shot = browserShot(s);
     var dock = focus ? browserLabDock(s, shot) : "";
+    var showReplay = focus && !(liveUrl && S.media === "live") && replayFrames(s).length >= 2;
     var body;
     if (liveUrl && S.media === "live") body = liveStreamMount(s, liveUrl);
+    else if (showReplay) body = replayScrubber(s);
     else if (shot) body = '<img class="surface-fill surface-screenshot" src="' + esc(shot) + '" alt="' + (s.desktopGeometry ? "desktop screenshot" : "browser screenshot") + '"/>';
     else body = '<div class="bw-app-wait"><div class="wait-spinner" style="width:24px;height:24px"></div>'
       + '<div class="mono" style="font-size:9px">' + esc(route) + '</div>'
@@ -2495,6 +2650,7 @@ export function observerClientJs() {
   }
 
   function render() {
+    stopAllScrubTimers(); // a full rebuild replaces the scrubber DOM; never leave a timer ticking on stale nodes
     var docEl = document.documentElement;
     docEl.setAttribute("data-theme", S.theme);
     docEl.setAttribute("data-motion", S.motion);
@@ -2561,6 +2717,7 @@ export function observerClientJs() {
     var arg = parts[1];
     var arg2 = parts[2];
     switch (cmd) {
+      case "scrub": handleScrub(arg, arg2); break;
       case "open": openFocus(arg); break;
       case "select": S.focusedId = arg; writeHash(arg); render(); break;
       case "exit-focus": exitFocus(); break;
@@ -2615,7 +2772,16 @@ export function observerClientJs() {
   });
   app.addEventListener("input", function (e) {
     var t = e.target;
-    if (t && t.getAttribute && t.getAttribute("data-role") === "search") { S.query = t.value; render(); }
+    if (!t || !t.getAttribute) return;
+    if (t.getAttribute("data-role") === "search") { S.query = t.value; render(); return; }
+    if (t.getAttribute("data-role") === "scrub") {
+      // Direct DOM update (NOT a full render) so dragging the slider stays smooth and the slider
+      // element is not rebuilt mid-drag. Position is stashed in scrubState so a later render restores it.
+      var sid = t.getAttribute("data-stream");
+      stopScrubPlay(sid);
+      scrubState[sid] = Number(t.value);
+      updateScrubDom(sid);
+    }
   });
   document.addEventListener("mousedown", function (e) {
     if (openDd) {

package/dist/observer-assets.js.map

@@ -1 +1 @@
-{"version":3,"file":"observer-assets.js","sourceRoot":"","sources":["../src/observer-assets.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAChF,+EAA+E;AAC/E,iEAAiE;AACjE,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,+CAA+C;AAE/C,MAAM,UAAU,WAAW;IACzB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwiCR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2nDR,CAAC;AACF,CAAC"}
+{"version":3,"file":"observer-assets.js","sourceRoot":"","sources":["../src/observer-assets.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAChF,+EAA+E;AAC/E,iEAAiE;AACjE,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,+CAA+C;AAE/C,MAAM,UAAU,WAAW;IACzB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsjCR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmxDR,CAAC;AACF,CAAC"}

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.20.3`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.20.5`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.

package/docs/goals/current.md

@@ -16,7 +16,7 @@ Humanish should be the open-source CLI that lets a maintainer ask:
 The answer should be observable, verifiable, public-safe, and easy to turn into
 actionable feedback.
 
-## Current Program Truth (source `0.20.3`)
+## Current Program Truth (source `0.20.5`)
 
 The package source and repository implementation in this tree agree on these
 points:

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.20.3` (2026-08-03). The containment boundary introduced in
+Package/source version in this tree: `0.20.5` (2026-08-03). The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.20.3",
+  "version": "0.20.5",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [