@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/web/child_publication.d.ts

@@ -0,0 +1,17 @@
+export type ChildPublicationAdmission = {
+    accepted: true;
+    duplicate: boolean;
+} | {
+    accepted: false;
+    status: 400 | 409;
+    error: string;
+};
+/** Bounded parent-issued stream receipts. Retain tombstones so pane reuse cannot revive an old stream. */
+export declare class ChildPublicationLedger {
+    private readonly capacity;
+    private readonly streams;
+    constructor(capacity?: number);
+    open(paneId: number, scope?: string): string | null;
+    admit(paneId: number, id: unknown, sequence: unknown, scope?: string): ChildPublicationAdmission;
+    invalidate(paneId: number): void;
+}

package/dist/web/child_publication.js

@@ -0,0 +1,45 @@
+import { randomUUID } from 'node:crypto';
+/** Bounded parent-issued stream receipts. Retain tombstones so pane reuse cannot revive an old stream. */
+export class ChildPublicationLedger {
+    capacity;
+    streams = new Map();
+    constructor(capacity = 1024) {
+        this.capacity = capacity;
+        if (!Number.isSafeInteger(capacity) || capacity < 1)
+            throw new RangeError('Publication capacity must be a positive safe integer');
+    }
+    open(paneId, scope = '') {
+        const key = JSON.stringify([scope, paneId]);
+        if (!this.streams.has(key) && this.streams.size >= this.capacity)
+            return null;
+        const id = randomUUID();
+        this.streams.set(key, { paneId, id, sequence: 0 });
+        return id;
+    }
+    admit(paneId, id, sequence, scope = '') {
+        const stream = this.streams.get(JSON.stringify([scope, paneId]));
+        // Legacy children remain compatible only until this pane opts into ordered publication.
+        if (id === undefined && sequence === undefined) {
+            return stream ? { accepted: false, status: 409, error: 'publication_identity_required' }
+                : { accepted: true, duplicate: false };
+        }
+        if (typeof id !== 'string' || !Number.isSafeInteger(sequence) || sequence < 1) {
+            return { accepted: false, status: 400, error: 'invalid_publication_sequence' };
+        }
+        if (!stream || stream.id !== id)
+            return { accepted: false, status: 409, error: 'publication_superseded' };
+        const next = sequence;
+        if (next <= stream.sequence)
+            return { accepted: true, duplicate: true };
+        if (next !== stream.sequence + 1)
+            return { accepted: false, status: 409, error: 'publication_sequence_gap' };
+        stream.sequence = next;
+        return { accepted: true, duplicate: false };
+    }
+    invalidate(paneId) {
+        for (const stream of this.streams.values()) {
+            if (stream.paneId === paneId)
+                stream.id = null;
+        }
+    }
+}

package/dist/web/mirror_authenticator.d.ts

@@ -21,11 +21,29 @@
 export interface MirrorSession {
     expiresAtMs: number;
     canInspectPrompts: boolean;
+    /** Absent only in callers predating capability-scoped sessions. */
+    canControl?: boolean;
+    shareId?: string;
 }
 export interface MirrorTokenValidationResult {
     ok: boolean;
     expiresAtMs: number;
     canInspectPrompts: boolean;
+    canControl?: boolean;
+    shareId?: string;
+}
+export interface MirrorShare {
+    id: string;
+    label: string;
+    expiresAtMs: number;
+    createdAtMs: number;
+    revoked: boolean;
+}
+export interface MirrorTokenOptions {
+    ttlMs?: number;
+    canInspectPrompts?: boolean;
+    readOnly?: boolean;
+    label?: string;
 }
 export interface MirrorAuthDecision {
     ok: boolean;
@@ -56,10 +74,10 @@ export interface MirrorAuthenticator {
     readonly zergId: string;
     readonly cookieName: string;
     readonly queryTokenName: string;
-    issueToken(opts?: {
-        ttlMs?: number;
-        canInspectPrompts?: boolean;
-    }): string;
+    issueToken(opts?: MirrorTokenOptions): string;
+    listShares(): MirrorShare[];
+    revokeShare(id: string): boolean;
+    onShareRevoked(callback: (id: string) => void): () => void;
     isValidToken(token: string): MirrorTokenValidationResult;
     authenticate(ctx: MirrorAuthContext): MirrorAuthDecision;
     authenticateUpgrade(ctx: MirrorAuthContext): boolean;
@@ -69,19 +87,22 @@ export interface MirrorAuthenticator {
 }
 /** Production HMAC + session authenticator. Denies requests without valid credentials. */
 export declare class HmacMirrorAuthenticator implements MirrorAuthenticator {
-    readonly enabled: boolean;
+    protected requiresCredentials: boolean;
+    get enabled(): boolean;
     readonly zergId: string;
     readonly cookieName: string;
     readonly queryTokenName: string;
     protected readonly sharedSecret: string;
     protected readonly internalToken: string;
     protected readonly sessions: Map<string, MirrorSession>;
+    private readonly shares;
+    private readonly revocationListeners;
     constructor(config: MirrorAuthenticatorConfig);
-    issueToken(opts?: {
-        ttlMs?: number;
-        canInspectPrompts?: boolean;
-    }): string;
+    issueToken(opts?: MirrorTokenOptions): string;
     isValidToken(token: string): MirrorTokenValidationResult;
+    listShares(): MirrorShare[];
+    revokeShare(id: string): boolean;
+    onShareRevoked(callback: (id: string) => void): () => void;
     authenticate(ctx: MirrorAuthContext): MirrorAuthDecision;
     authenticateUpgrade(ctx: MirrorAuthContext): boolean;
     persistSession(session: MirrorSession): string;
@@ -98,9 +119,8 @@ export declare class HmacMirrorAuthenticator implements MirrorAuthenticator {
  * legacy `!mirrorAuthEnabled` fallback that ran AFTER the token path.
  */
 export declare class OpenMirrorAuthenticator extends HmacMirrorAuthenticator {
-    readonly enabled: boolean;
+    constructor(config: MirrorAuthenticatorConfig);
     authenticate(ctx: MirrorAuthContext): MirrorAuthDecision;
-    authenticateUpgrade(_ctx: MirrorAuthContext): boolean;
 }
 /**
  * Build the authenticator from environment policy, mirroring the legacy

package/dist/web/mirror_authenticator.js

@@ -24,13 +24,16 @@ const DEFAULT_QUERY_TOKEN_NAME = 'ztc_mirror_token';
 const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000;
 /** Production HMAC + session authenticator. Denies requests without valid credentials. */
 export class HmacMirrorAuthenticator {
-    enabled = true;
+    requiresCredentials = true;
+    get enabled() { return this.requiresCredentials; }
     zergId;
     cookieName;
     queryTokenName;
     sharedSecret;
     internalToken;
     sessions = new Map();
+    shares = new Map();
+    revocationListeners = new Set();
     constructor(config) {
         this.sharedSecret = config.sharedSecret;
         this.zergId = config.zergId;
@@ -40,6 +43,26 @@ export class HmacMirrorAuthenticator {
     }
     issueToken(opts = {}) {
         const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        if (opts.readOnly) {
+            if (!Number.isSafeInteger(ttlMs) || ttlMs < 1000 || ttlMs > DEFAULT_TTL_MS)
+                throw new Error('Observation TTL must be between 1 second and 12 hours, in whole milliseconds.');
+            const label = (opts.label ?? 'Observer').trim();
+            if (!label || label.length > 64 || /[\x00-\x1f\x7f]/.test(label))
+                throw new Error('Share label must contain 1–64 printable characters.');
+            for (const [id, share] of this.shares) {
+                if (share.revoked || share.expiresAtMs <= Date.now())
+                    this.shares.delete(id);
+            }
+            if (this.shares.size >= 100)
+                throw new Error('Share limit reached. Revoke an active observation share first.');
+            const id = randomUUID();
+            const expiresAtMs = Date.now() + ttlMs;
+            const signature = createHmac('sha256', this.sharedSecret).update(`${this.zergId}:${expiresAtMs}:observe:${id}`).digest('hex');
+            this.shares.set(id, { id, label, expiresAtMs, createdAtMs: Date.now(), revoked: false });
+            // Latch this on: revoking the last share must never restore open control.
+            this.requiresCredentials = true;
+            return `${expiresAtMs}.observe.${id}.${signature}`;
+        }
         const canInspectPrompts = opts.canInspectPrompts ?? false;
         const expiresAtSeconds = Math.floor((Date.now() + ttlMs) / 1000);
         const promptScope = canInspectPrompts ? '1' : '0';
@@ -49,6 +72,20 @@ export class HmacMirrorAuthenticator {
     }
     isValidToken(token) {
         const parts = token.split('.');
+        if (parts[1] === 'observe') {
+            const denied = { ok: false, expiresAtMs: 0, canInspectPrompts: false, canControl: false };
+            if (parts.length !== 4 || !/^\d+$/.test(parts[0]) || !/^[a-f0-9]{64}$/.test(parts[3]))
+                return denied;
+            const share = this.shares.get(parts[2]);
+            const expiresAtMs = Number(parts[0]);
+            if (!share || share.revoked || share.expiresAtMs !== expiresAtMs || Date.now() >= expiresAtMs || !this.sharedSecret)
+                return denied;
+            const expected = createHmac('sha256', this.sharedSecret).update(`${this.zergId}:${parts[0]}:observe:${share.id}`).digest();
+            const provided = Buffer.from(parts[3], 'hex');
+            if (!timingSafeEqual(expected, provided))
+                return denied;
+            return { ok: true, expiresAtMs, canInspectPrompts: false, canControl: false, shareId: share.id };
+        }
         if ((parts.length !== 2 && parts.length !== 3) || !this.sharedSecret) {
             return { ok: false, expiresAtMs: 0, canInspectPrompts: false };
         }
@@ -77,7 +114,21 @@ export class HmacMirrorAuthenticator {
         if (!timingSafeEqual(expected, provided)) {
             return { ok: false, expiresAtMs: 0, canInspectPrompts: false };
         }
-        return { ok: true, expiresAtMs, canInspectPrompts: promptScope === '1' };
+        return { ok: true, expiresAtMs, canInspectPrompts: promptScope === '1', canControl: true };
+    }
+    listShares() { return [...this.shares.values()].map(share => ({ ...share })); }
+    revokeShare(id) {
+        const share = this.shares.get(id);
+        if (!share || share.revoked)
+            return false;
+        share.revoked = true;
+        for (const listener of this.revocationListeners)
+            listener(id);
+        return true;
+    }
+    onShareRevoked(callback) {
+        this.revocationListeners.add(callback);
+        return () => { this.revocationListeners.delete(callback); };
     }
     authenticate(ctx) {
         // 1. Internal-token header (process-internal callers).
@@ -95,9 +146,13 @@ export class HmacMirrorAuthenticator {
                 const session = {
                     expiresAtMs: result.expiresAtMs,
                     canInspectPrompts: result.canInspectPrompts,
+                    canControl: result.canControl !== false,
+                    ...(result.shareId ? { shareId: result.shareId } : {}),
                 };
                 return { ok: true, session, issueCookie: session, source: 'browser' };
             }
+            if (tokenCandidate.split('.')[1] === 'observe')
+                return { ok: false, session: null, issueCookie: null, source: null };
         }
         // 3. Existing session cookie — no re-issuance.
         const session = this.sessionFromCookies(ctx.cookies);
@@ -108,26 +163,21 @@ export class HmacMirrorAuthenticator {
         return { ok: false, session: null, issueCookie: null, source: null };
     }
     authenticateUpgrade(ctx) {
-        if (this.matchesInternalToken(ctx.headers))
-            return true;
-        const bearer = this.extractBearerToken(ctx.headers);
-        if (bearer && this.isValidToken(bearer).ok)
-            return true;
-        const queryToken = ctx.url.searchParams.get(this.queryTokenName) || '';
-        if (queryToken && this.isValidToken(queryToken).ok)
-            return true;
-        return this.sessionFromCookies(ctx.cookies) !== null;
+        const decision = this.authenticate(ctx);
+        return decision.ok && decision.session?.canControl !== false;
     }
     persistSession(session) {
         const sessionId = randomUUID();
-        this.sessions.set(sessionId, session);
+        const observer = session.canControl === false || session.shareId !== undefined;
+        this.sessions.set(sessionId, { ...session, canControl: !observer, canInspectPrompts: observer ? false : session.canInspectPrompts });
         return sessionId;
     }
     getSession(sessionId) {
         const session = this.sessions.get(sessionId);
         if (!session)
             return null;
-        if (Date.now() > session.expiresAtMs) {
+        const share = session.shareId ? this.shares.get(session.shareId) : undefined;
+        if (Date.now() >= session.expiresAtMs || (session.shareId && (!share || share.revoked || Date.now() >= share.expiresAtMs))) {
             this.sessions.delete(sessionId);
             return null;
         }
@@ -165,16 +215,16 @@ export class HmacMirrorAuthenticator {
  * legacy `!mirrorAuthEnabled` fallback that ran AFTER the token path.
  */
 export class OpenMirrorAuthenticator extends HmacMirrorAuthenticator {
-    enabled = false;
+    constructor(config) { super(config); this.requiresCredentials = false; }
     authenticate(ctx) {
         const decision = super.authenticate(ctx);
         if (decision.ok)
             return decision;
+        const candidate = this.extractBearerToken(ctx.headers) || ctx.url.searchParams.get(this.queryTokenName) || '';
+        if (this.enabled || candidate.split('.')[1] === 'observe')
+            return decision;
         return { ok: true, session: null, issueCookie: null, source: 'open' };
     }
-    authenticateUpgrade(_ctx) {
-        return true;
-    }
 }
 /**
  * Build the authenticator from environment policy, mirroring the legacy

package/dist/web/mirror_client.d.ts

@@ -8,18 +8,34 @@
  *
  * Also provides bus connectivity for inter-ZTC messaging via SSE.
  */
+import { type EvidenceSnapshot } from '../agent/runtime/evidence.js';
+import type { TaskHandoffProjection } from '../session_handoff_contract.js';
 import type { SlashCommandUsage } from '../agent/commands/index.js';
 import type { MirrorPublisher, BusMessage, BusMember, ZlickyWebCursor, ZlickyWebHighlight, ZlickyWebStatus, HookApprovalPublishPayload } from './mirror_stream.js';
+export interface MirrorClientOptions {
+    /** Absolute deadline for each local HTTP exchange, including its response body. */
+    publicationTimeoutMs?: number;
+}
 export declare class MirrorClient implements MirrorPublisher {
     private port;
     private paneId;
+    private readonly sessionId;
     private busConnection;
     private busReconnectTimer;
     private paneName;
     private lastTokenUsage;
     private internalToken;
     private groupId;
-    constructor(port: number, paneId: number);
+    private readonly publicationTimeoutMs;
+    private publicationId;
+    private publicationSequence;
+    private publicationQueue;
+    private publicationBytes;
+    private publicationRequest;
+    private publicationDraining;
+    private publicationFailure;
+    private publicationDrain;
+    constructor(port: number, paneId: number, options?: MirrorClientOptions | string);
     getPaneId(): number;
     getPaneName(): string;
     getBusMember(): BusMember;
@@ -27,7 +43,12 @@ export declare class MirrorClient implements MirrorPublisher {
         type: string;
         data: Record<string, unknown>;
     }): void;
+    /** Resolve after acknowledged publications, or reject with the bounded transport failure. */
+    flushPublications(): Promise<void>;
+    private failPublication;
     private postEvent;
+    private drainPublications;
+    private postPublication;
     storeEvent(event: {
         type: string;
         data: Record<string, unknown>;
@@ -54,6 +75,8 @@ export declare class MirrorClient implements MirrorPublisher {
     publishSettingsPage(data?: Record<string, unknown>): void;
     publishStreamEnd(finalMessage?: string, metadata?: Record<string, unknown>): void;
     publishToolCall(tool: string, args: Record<string, unknown>, toolCallId: string): void;
+    publishEvidenceSnapshot(snapshot: EvidenceSnapshot, sessionId: string): void;
+    publishTaskHandoff(projection: TaskHandoffProjection | null, sessionId: string): void;
     publishToolResult(tool: string, result: string, success: boolean, toolCallId: string): void;
     publishTodoList(todos: Array<{
         content: string;
@@ -67,13 +90,17 @@ export declare class MirrorClient implements MirrorPublisher {
             description: string;
             recommended?: boolean;
         }>;
-    }>, paneId?: number, allowOther?: boolean): void;
+    }>, paneId?: number, allowOther?: boolean): string;
     publishHookApprovalRequest(request: HookApprovalPublishPayload): void;
+    publishHookApprovalResolved(id: string): void;
+    publishQuestionDismiss(questionId: string): void;
     publishWidgetPrompt(widgetId: string, options: {
         title?: string;
         question: string;
         placeholder?: string;
         defaultValue?: string;
+        isPassword?: boolean;
+        allowEmptySubmit?: boolean;
     }): void;
     publishWidgetSelect(widgetId: string, options: {
         title?: string;
@@ -104,7 +131,7 @@ export declare class MirrorClient implements MirrorPublisher {
     }): void;
     publishWidgetDismiss(widgetId: string): void;
     publishWidgetSettings(widgetId: string, data: Record<string, unknown>): void;
-    publishStatus(status: string, verb?: string): void;
+    publishStatus(status: string, verb?: string, waiting?: import('../types.js').CommandWaitingState, toolProgress?: import('../types.js').AgentState['toolProgress']): void;
     publishQueueState(total: number, entries: string[]): void;
     publishTokenUsage(input: number, output: number, total: number, percentage: number, options?: {
         reset?: boolean;
@@ -168,4 +195,4 @@ export declare class MirrorClient implements MirrorPublisher {
  * Create a MirrorClient if the environment indicates we're a child pane
  * with a parent mirror server. Returns null otherwise.
  */
-export declare function initMirrorClient(): MirrorClient | null;
+export declare function initMirrorClient(sessionId?: string): MirrorClient | null;

package/dist/web/mirror_client.js

@@ -9,18 +9,43 @@
  * Also provides bus connectivity for inter-ZTC messaging via SSE.
  */
 import { request } from 'http';
+import { parseEvidenceSnapshot } from '../agent/runtime/evidence.js';
+import { parseToolProgress } from '../tool_progress.js';
+import { parseTaskHandoffView } from './view_plugin.js';
+import { randomUUID } from 'node:crypto';
+import { MAX_TOOL_IMAGE_BODY_BYTES, mirrorToolImage } from './tool_image.js';
+const MAX_PENDING_PUBLICATIONS = 256;
+const MAX_PENDING_PUBLICATION_BYTES = 2 * 1024 * 1024;
+const MAX_CHILD_EVENT_BYTES = 512 * 1024 - 512;
+const MAX_PUBLICATION_RESPONSE_BYTES = 16 * 1024;
 export class MirrorClient {
     port;
     paneId;
+    sessionId;
     busConnection = null;
     busReconnectTimer = null;
     paneName;
     lastTokenUsage = null;
     internalToken;
     groupId;
-    constructor(port, paneId) {
+    publicationTimeoutMs;
+    publicationId = null;
+    publicationSequence = 0;
+    publicationQueue = [];
+    publicationBytes = 0;
+    publicationRequest = null;
+    publicationDraining = false;
+    publicationFailure = null;
+    publicationDrain = Promise.resolve();
+    constructor(port, paneId, options = {}) {
         this.port = port;
         this.paneId = paneId;
+        this.sessionId = typeof options === 'string' ? options : null;
+        const timeout = (typeof options === 'string' ? {} : options).publicationTimeoutMs ?? 5000;
+        if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 60_000) {
+            throw new RangeError('publicationTimeoutMs must be an integer between 1 and 60000');
+        }
+        this.publicationTimeoutMs = timeout;
         this.paneName = paneId > 0 ? `ZTC ${paneId}` : 'ZTC';
         this.internalToken = process.env.ZTC_MIRROR_INTERNAL_TOKEN || '';
         this.groupId = process.env.ZTC_MIRROR_GROUP || '';
@@ -37,22 +62,141 @@ export class MirrorClient {
     publish(event) {
         this.postEvent(event);
     }
-    postEvent(event, storeOnly = false) {
-        const payload = JSON.stringify({ pane_id: this.paneId, event, ...(storeOnly ? { store_only: true } : {}) });
-        const req = request({
-            hostname: 'localhost',
-            port: this.port,
-            path: this.groupId ? `/pane-events/${this.groupId}` : '/pane-events',
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': Buffer.byteLength(payload),
-                ...(this.internalToken ? { 'x-ztc-internal-token': this.internalToken } : {}),
-            },
+    /** Resolve after acknowledged publications, or reject with the bounded transport failure. */
+    async flushPublications() {
+        await this.publicationDrain;
+        if (this.publicationFailure)
+            throw this.publicationFailure;
+    }
+    failPublication(error) {
+        if (this.publicationFailure)
+            return;
+        this.publicationFailure = error;
+        const dropped = this.publicationQueue.length;
+        this.publicationQueue = [];
+        this.publicationBytes = 0;
+        this.publicationId = null;
+        this.publicationSequence = 0;
+        this.publicationRequest?.destroy();
+        process.stderr.write(`[Mirror pane=${this.paneId}] Child publication failed: ${error.message}. ${dropped} queued update(s) discarded; later updates open a fresh stream without replay.\n`);
+    }
+    postEvent(event, storeOnly = false, toolImage = false) {
+        if (this.sessionId !== null)
+            event = { ...event, data: { ...event.data, origin_session_id: this.sessionId } };
+        // A failure already tearing down its request cannot accept another update yet.
+        if (this.publicationDraining && this.publicationFailure)
+            return;
+        if (!this.publicationDraining)
+            this.publicationFailure = null;
+        let eventJson;
+        try {
+            eventJson = JSON.stringify(event);
+        }
+        catch {
+            this.failPublication(new Error('Child event is not JSON serializable'));
+            return;
+        }
+        const bytes = Buffer.byteLength(eventJson) + 512;
+        if (bytes > (toolImage ? MAX_TOOL_IMAGE_BODY_BYTES : MAX_CHILD_EVENT_BYTES)) {
+            this.failPublication(new Error('Child event exceeds the 512 KiB publication limit'));
+            return;
+        }
+        if (this.publicationQueue.length >= MAX_PENDING_PUBLICATIONS || this.publicationBytes + bytes > (toolImage ? MAX_TOOL_IMAGE_BODY_BYTES + MAX_PENDING_PUBLICATION_BYTES : MAX_PENDING_PUBLICATION_BYTES)) {
+            this.failPublication(new Error('Child publication queue exceeds 256 updates or 2 MiB'));
+            return;
+        }
+        this.publicationQueue.push({ eventJson, bytes, storeOnly, toolImage });
+        this.publicationBytes += bytes;
+        if (!this.publicationDraining)
+            this.publicationDrain = this.drainPublications();
+    }
+    async drainPublications() {
+        this.publicationDraining = true;
+        try {
+            if (!this.publicationId) {
+                const opened = await this.postPublication('/pane-publication', JSON.stringify({ pane_id: this.paneId }));
+                if (this.publicationFailure)
+                    throw this.publicationFailure;
+                if (typeof opened.publication_id !== 'string' || !opened.publication_id || opened.publication_id.length > 256) {
+                    throw new Error('Parent mirror did not issue a publication identity; update parent and child to matching versions');
+                }
+                this.publicationId = opened.publication_id;
+            }
+            while (this.publicationQueue.length) {
+                const item = this.publicationQueue[0];
+                const sequence = this.publicationSequence + 1;
+                const payload = `{"pane_id":${this.paneId},"publication_id":${JSON.stringify(this.publicationId)},"sequence":${sequence},"event":${item.eventJson}${item.storeOnly ? ',"store_only":true' : ''}}`;
+                await this.postPublication('/pane-events', payload, item.toolImage);
+                if (this.publicationFailure)
+                    throw this.publicationFailure;
+                this.publicationSequence = sequence;
+                this.publicationQueue.shift();
+                this.publicationBytes -= item.bytes;
+            }
+        }
+        catch (error) {
+            this.failPublication(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            this.publicationDraining = false;
+        }
+    }
+    postPublication(path, payload, toolImage = false) {
+        return new Promise((resolve, reject) => {
+            const req = request({
+                hostname: 'localhost', port: this.port,
+                path: this.groupId ? `${path}/${this.groupId}` : path,
+                method: 'POST', headers: {
+                    'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload),
+                    ...(this.internalToken ? { 'x-ztc-internal-token': this.internalToken } : {}),
+                    ...(toolImage ? { 'x-ztc-tool-image': '1' } : {}),
+                },
+            }, res => {
+                let output = '';
+                let bytes = 0;
+                res.on('data', (chunk) => {
+                    bytes += chunk.length;
+                    if (bytes > MAX_PUBLICATION_RESPONSE_BYTES) {
+                        reject(new Error('Parent publication response exceeds 16 KiB'));
+                        req.destroy();
+                        res.destroy();
+                    }
+                    else
+                        output += chunk.toString();
+                });
+                res.on('aborted', () => reject(new Error('Parent publication response was interrupted')));
+                res.on('error', reject);
+                res.on('end', () => {
+                    if (res.statusCode !== 200) {
+                        reject(new Error(`Parent publication HTTP ${res.statusCode ?? 0}`));
+                        return;
+                    }
+                    try {
+                        const body = JSON.parse(output);
+                        if (!body || typeof body !== 'object' || Array.isArray(body) || body.ok !== true) {
+                            reject(new Error('Parent publication receipt is malformed'));
+                            return;
+                        }
+                        resolve(body);
+                    }
+                    catch {
+                        reject(new Error('Parent publication receipt is not valid JSON'));
+                    }
+                });
+            });
+            this.publicationRequest = req;
+            const timer = setTimeout(() => {
+                reject(new Error(`Child publication timed out after ${this.publicationTimeoutMs} ms`));
+                req.destroy();
+            }, this.publicationTimeoutMs);
+            req.on('error', reject);
+            req.on('close', () => {
+                clearTimeout(timer);
+                if (this.publicationRequest === req)
+                    this.publicationRequest = null;
+            });
+            req.end(payload);
         });
-        req.on('error', () => { }); // fire-and-forget
-        req.write(payload);
-        req.end();
     }
     storeEvent(event) {
         this.postEvent(event, true);
@@ -194,23 +338,37 @@ export class MirrorClient {
     publishToolCall(tool, args, toolCallId) {
         this.postEvent({ type: 'tool_call', data: { tool, args, toolCallId } });
     }
+    publishEvidenceSnapshot(snapshot, sessionId) {
+        const validated = parseEvidenceSnapshot(snapshot);
+        if (!validated || !sessionId || Buffer.byteLength(sessionId) > 1024)
+            return;
+        this.postEvent({ type: 'evidence', data: { snapshot: validated, session_id: sessionId } });
+    }
+    publishTaskHandoff(projection, sessionId) {
+        const validated = parseTaskHandoffView({ sessionId, projection });
+        if (validated)
+            this.postEvent({ type: 'task_handoff', data: { ...validated } });
+    }
     publishToolResult(tool, result, success, toolCallId) {
+        const image = mirrorToolImage(result);
         this.postEvent({
             type: 'tool_result',
-            data: { tool, result: result.slice(0, 2000), success, toolCallId },
-        });
+            data: { tool, result: image ? result : result.slice(0, 2000), success, toolCallId },
+        }, false, Boolean(image));
     }
     publishTodoList(todos) {
         this.postEvent({ type: 'todo_list', data: { todos } });
     }
     publishAskUser(questions, paneId, allowOther) {
-        const baseData = { pane_id: paneId, allow_other: allowOther ?? true };
+        const questionId = randomUUID();
+        const baseData = { pane_id: paneId, question_id: questionId, allow_other: allowOther ?? true };
         if (questions.length === 1) {
             this.postEvent({ type: 'ask_user', data: { ...baseData, question: questions[0].question, options: questions[0].options } });
         }
         else {
             this.postEvent({ type: 'ask_user', data: { ...baseData, questions } });
         }
+        return questionId;
     }
     publishHookApprovalRequest(request) {
         this.postEvent({
@@ -226,6 +384,12 @@ export class MirrorClient {
             },
         });
     }
+    publishHookApprovalResolved(id) {
+        this.postEvent({ type: 'hook_approval_resolved', data: { id } });
+    }
+    publishQuestionDismiss(questionId) {
+        this.postEvent({ type: 'question_dismiss', data: { question_id: questionId } });
+    }
     publishWidgetPrompt(widgetId, options) {
         this.postEvent({ type: 'widget_prompt', data: { widget_id: widgetId, ...options } });
     }
@@ -241,8 +405,10 @@ export class MirrorClient {
     publishWidgetSettings(widgetId, data) {
         this.postEvent({ type: 'widget_settings', data: { widget_id: widgetId, ...data } });
     }
-    publishStatus(status, verb) {
-        this.postEvent({ type: 'status', data: { status, verb } });
+    publishStatus(status, verb, waiting, toolProgress) {
+        const observed = status === 'tool_executing' ? parseToolProgress(toolProgress) : null;
+        this.postEvent({ type: 'status', data: { status, verb, ...(waiting ? { waiting } : {}),
+                ...(observed ? { toolProgress: observed } : {}) } });
     }
     publishQueueState(total, entries) {
         this.postEvent({ type: 'queue_state', data: { total, entries } });
@@ -327,10 +493,10 @@ export class MirrorClient {
  * Create a MirrorClient if the environment indicates we're a child pane
  * with a parent mirror server. Returns null otherwise.
  */
-export function initMirrorClient() {
+export function initMirrorClient(sessionId) {
     const port = process.env.ZTC_MIRROR_PORT;
     const paneId = process.env.ZTC_PANE_ID;
     if (!port)
         return null;
-    return new MirrorClient(parseInt(port, 10), paneId ? parseInt(paneId, 10) : -1);
+    return new MirrorClient(parseInt(port, 10), paneId ? parseInt(paneId, 10) : -1, sessionId);
 }