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

package/dist/simulation/living/types.d.ts

@@ -119,8 +119,8 @@ export declare const beliefSchema: z.ZodObject<{
     claim: z.ZodString;
     source: z.ZodObject<{
         kind: z.ZodEnum<{
-            initial: "initial";
             inferred: "inferred";
+            initial: "initial";
             witnessed: "witnessed";
             told: "told";
             discovered: "discovered";
@@ -229,8 +229,8 @@ export declare const personSchema: z.ZodObject<{
         claim: z.ZodString;
         source: z.ZodObject<{
             kind: z.ZodEnum<{
-                initial: "initial";
                 inferred: "inferred";
+                initial: "initial";
                 witnessed: "witnessed";
                 told: "told";
                 discovered: "discovered";
@@ -431,8 +431,8 @@ export declare const tensionSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type LivingTension = z.infer<typeof tensionSchema>;
 export declare const scheduledKindSchema: z.ZodEnum<{
-    count: "count";
     plan: "plan";
+    count: "count";
     finish: "finish";
     reply: "reply";
     back: "back";
@@ -491,8 +491,8 @@ export declare const scheduledSchema: z.ZodObject<{
     at: z.ZodNumber;
     personId: z.ZodNullable<z.ZodString>;
     kind: z.ZodEnum<{
-        count: "count";
         plan: "plan";
+        count: "count";
         finish: "finish";
         reply: "reply";
         back: "back";
@@ -762,8 +762,8 @@ export declare const effectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     placeId: z.ZodNullable<z.ZodString>;
     targetId: z.ZodNullable<z.ZodString>;
     scheduleKind: z.ZodEnum<{
-        count: "count";
         plan: "plan";
+        count: "count";
         finish: "finish";
         reply: "reply";
         back: "back";
@@ -884,9 +884,9 @@ export declare const effectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             id: z.ZodString;
             type: z.ZodEnum<{
                 number: "number";
+                text: "text";
                 id: "id";
                 flag: "flag";
-                text: "text";
                 level: "level";
                 time: "time";
             }>;
@@ -996,8 +996,8 @@ export declare const effectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"decision.close">;
     entityId: z.ZodString;
     result: z.ZodEnum<{
-        failed: "failed";
         passed: "passed";
+        failed: "failed";
         lapsed: "lapsed";
     }>;
 }, z.core.$strip>, z.ZodObject<{
@@ -1295,8 +1295,8 @@ export declare const eventSchema: z.ZodObject<{
         placeId: z.ZodNullable<z.ZodString>;
         targetId: z.ZodNullable<z.ZodString>;
         scheduleKind: z.ZodEnum<{
-            count: "count";
             plan: "plan";
+            count: "count";
             finish: "finish";
             reply: "reply";
             back: "back";
@@ -1417,9 +1417,9 @@ export declare const eventSchema: z.ZodObject<{
                 id: z.ZodString;
                 type: z.ZodEnum<{
                     number: "number";
+                    text: "text";
                     id: "id";
                     flag: "flag";
-                    text: "text";
                     level: "level";
                     time: "time";
                 }>;
@@ -1529,8 +1529,8 @@ export declare const eventSchema: z.ZodObject<{
         kind: z.ZodLiteral<"decision.close">;
         entityId: z.ZodString;
         result: z.ZodEnum<{
-            failed: "failed";
             passed: "passed";
+            failed: "failed";
             lapsed: "lapsed";
         }>;
     }, z.core.$strip>, z.ZodObject<{
@@ -1675,8 +1675,8 @@ export declare const stateSchema: z.ZodObject<{
             claim: z.ZodString;
             source: z.ZodObject<{
                 kind: z.ZodEnum<{
-                    initial: "initial";
                     inferred: "inferred";
+                    initial: "initial";
                     witnessed: "witnessed";
                     told: "told";
                     discovered: "discovered";
@@ -1874,8 +1874,8 @@ export declare const stateSchema: z.ZodObject<{
         at: z.ZodNumber;
         personId: z.ZodNullable<z.ZodString>;
         kind: z.ZodEnum<{
-            count: "count";
             plan: "plan";
+            count: "count";
             finish: "finish";
             reply: "reply";
             back: "back";
@@ -1953,8 +1953,8 @@ export declare const stateSchema: z.ZodObject<{
         at: z.ZodNumber;
         personId: z.ZodNullable<z.ZodString>;
         kind: z.ZodEnum<{
-            count: "count";
             plan: "plan";
+            count: "count";
             finish: "finish";
             reply: "reply";
             back: "back";
@@ -2266,8 +2266,8 @@ export declare const stateSchema: z.ZodObject<{
             placeId: z.ZodNullable<z.ZodString>;
             targetId: z.ZodNullable<z.ZodString>;
             scheduleKind: z.ZodEnum<{
-                count: "count";
                 plan: "plan";
+                count: "count";
                 finish: "finish";
                 reply: "reply";
                 back: "back";
@@ -2388,9 +2388,9 @@ export declare const stateSchema: z.ZodObject<{
                     id: z.ZodString;
                     type: z.ZodEnum<{
                         number: "number";
+                        text: "text";
                         id: "id";
                         flag: "flag";
-                        text: "text";
                         level: "level";
                         time: "time";
                     }>;
@@ -2500,8 +2500,8 @@ export declare const stateSchema: z.ZodObject<{
             kind: z.ZodLiteral<"decision.close">;
             entityId: z.ZodString;
             result: z.ZodEnum<{
-                failed: "failed";
                 passed: "passed";
+                failed: "failed";
                 lapsed: "lapsed";
             }>;
         }, z.core.$strip>, z.ZodObject<{
@@ -2600,9 +2600,9 @@ export declare const stateSchema: z.ZodObject<{
             id: z.ZodString;
             type: z.ZodEnum<{
                 number: "number";
+                text: "text";
                 id: "id";
                 flag: "flag";
-                text: "text";
                 level: "level";
                 time: "time";
             }>;
@@ -2695,8 +2695,8 @@ export declare const stateSchema: z.ZodObject<{
             abstain: "abstain";
         }>>>;
         result: z.ZodOptional<z.ZodEnum<{
-            failed: "failed";
             passed: "passed";
+            failed: "failed";
             lapsed: "lapsed";
         }>>;
         settles: z.ZodOptional<z.ZodString>;

package/dist/simulation/orchestration/world_response.d.ts

@@ -22,8 +22,8 @@ declare const worldResponseSchema: z.ZodObject<{
     }, z.core.$strip>>>>;
     world_events: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
         description: z.ZodString;
-        primaryMetricsDelta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodNumber>>>;
-        metricsDelta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodNumber>>>;
+        primaryMetricsDelta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodNumber, unknown>>>;
+        metricsDelta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodNumber, unknown>>>;
     }, z.core.$strip>>>>;
     perceptions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
         agentId: z.ZodString;

package/dist/simulation/toolkit/dynamic_meetings.d.ts

@@ -173,8 +173,8 @@ export declare const meetingSchema: z.ZodObject<{
         priorTurnsDigest: z.ZodString;
         turnDigest: z.ZodNullable<z.ZodString>;
         provider: z.ZodEnum<{
-            zergrouter: "zergrouter";
             codex_legacy: "codex_legacy";
+            zergrouter: "zergrouter";
         }>;
         role: z.ZodLiteral<"character">;
         model: z.ZodEnum<{

package/dist/simulation/toolkit/dynamic_state.d.ts

@@ -63,9 +63,9 @@ export declare const agentSchema: z.ZodObject<{
         id: z.ZodString;
         eventId: z.ZodString;
         kind: z.ZodEnum<{
-            promise: "promise";
             outcome: "outcome";
             observation: "observation";
+            promise: "promise";
             conflict: "conflict";
             cooperation: "cooperation";
         }>;

package/dist/simulation/world/bootstrap_schema.d.ts

@@ -7,7 +7,7 @@ export declare const bootstrapRoleSchema: z.ZodObject<{
     department: z.ZodString;
     persona: z.ZodString;
     full_name: z.ZodOptional<z.ZodString>;
-    budget_authority: z.ZodPreprocess<z.ZodNumber>;
+    budget_authority: z.ZodPreprocess<z.ZodNumber, unknown>;
     signature_authority: z.ZodBoolean;
     deadline_pressure: z.ZodNumber;
     private_goal: z.ZodOptional<z.ZodString>;

package/dist/simulation/world/gm_schema.d.ts

@@ -42,13 +42,13 @@ export declare function coerceToNumber(value: unknown): number | undefined;
  */
 export declare function coerceNumericMap(raw: unknown, logger?: CoerceLogger): Record<string, number>;
 export declare function createGMWorldUpdateSchema(logger?: CoerceLogger): z.ZodObject<{
-    worldUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    worldUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodString>, unknown>>;
     worldEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     entityEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     agentObservations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
-    privateObservationsByAgentId: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodArray<z.ZodString>>>>;
-    primaryMetricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>>>;
-    metricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>>>;
+    privateObservationsByAgentId: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>>;
+    primaryMetricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>, unknown>>;
+    metricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>, unknown>>;
     disruptionSignals: z.ZodOptional<z.ZodObject<{
         hadDisruption: z.ZodOptional<z.ZodBoolean>;
         disruptionCount: z.ZodOptional<z.ZodNumber>;
@@ -80,13 +80,13 @@ export declare function createGMWorldUpdateSchema(logger?: CoerceLogger): z.ZodO
     }>>;
 }, z.core.$strip>;
 export declare const GMWorldUpdateSchema: z.ZodObject<{
-    worldUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    worldUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodString>, unknown>>;
     worldEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     entityEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     agentObservations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
-    privateObservationsByAgentId: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodArray<z.ZodString>>>>;
-    primaryMetricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>>>;
-    metricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>>>;
+    privateObservationsByAgentId: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>>;
+    primaryMetricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>, unknown>>;
+    metricUpdates: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodNumber>, unknown>>;
     disruptionSignals: z.ZodOptional<z.ZodObject<{
         hadDisruption: z.ZodOptional<z.ZodBoolean>;
         disruptionCount: z.ZodOptional<z.ZodNumber>;

package/dist/skills/loader.js

@@ -31,7 +31,9 @@ async function walk(dir, depth = 0) {
         const entries = await readdir(dir, { withFileTypes: true });
         const results = [];
         for (const entry of entries) {
-            if (entry.name.startsWith('.'))
+            // Dot folders and installed packages hold no skills; a skill's own
+            // node_modules tree can be hundreds of directories deep.
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
                 continue;
             const full = join(dir, entry.name);
             if (entry.isDirectory()) {

package/dist/types.d.ts

@@ -224,9 +224,10 @@ export interface ZTCConfig {
     tools?: string[];
 }
 export interface ToolParameterSchema {
-    type: string;
+    [keyword: string]: unknown;
+    type?: string | string[];
     description?: string;
-    enum?: string[];
+    enum?: unknown[];
     minimum?: number;
     maximum?: number;
     minLength?: number;
@@ -274,6 +275,7 @@ export type AgentEvent = {
 } | {
     type: 'history_checkpoint';
     messages: Message[];
+    replacesHistory?: boolean;
 } | {
     type: 'thinking_start';
 } | {
@@ -313,6 +315,8 @@ export type AgentEvent = {
     content: string;
 } | {
     type: 'stream_end';
+} | {
+    type: 'stream_reset';
 } | {
     type: 'request_metrics';
     metrics: RequestMetrics;

package/dist/ui/core/input.d.ts

@@ -32,6 +32,10 @@ export interface InputBus {
  *
  * Ink/Kitty usually provides `key.ctrl` with the printable letter, while
  * scrollback-mode terminals commonly provide the ASCII control byte alone.
+ * The chord must hold no other modifier: with a Hyper key (Cmd+Ctrl+Option+
+ * Shift) or any extra key down it is no shortcut. `shift` asks for Ctrl+Shift.
  */
-export declare function isControlKey(input: string, key: InputKey | undefined, letter: string): boolean;
+export declare function isControlKey(input: string, key: InputKey | undefined, letter: string, { shift }?: {
+    shift?: boolean;
+}): boolean;
 export declare function createInputBus(): InputBus;

package/dist/ui/core/input.js

@@ -3,8 +3,12 @@
  *
  * Ink/Kitty usually provides `key.ctrl` with the printable letter, while
  * scrollback-mode terminals commonly provide the ASCII control byte alone.
+ * The chord must hold no other modifier: with a Hyper key (Cmd+Ctrl+Option+
+ * Shift) or any extra key down it is no shortcut. `shift` asks for Ctrl+Shift.
  */
-export function isControlKey(input, key, letter) {
+export function isControlKey(input, key, letter, { shift = false } = {}) {
+    if (key?.meta || key?.alt || key?.super || Boolean(key?.shift) !== shift)
+        return false;
     const normalized = letter.toLowerCase();
     if (key?.ctrl && input.toLowerCase() === normalized)
         return true;

package/dist/ui/core/input_segments.d.ts

@@ -79,7 +79,11 @@ export declare function killInputDraft(state: InputState): {
     killed: InputDraftSnapshot;
 };
 export declare function yankInputKill(state: InputState, killed: InputKill): InputState;
-export declare function getInputShortcutHint(state: Pick<InputState, 'segments' | 'cursor'>, running?: boolean, canYank?: boolean): string | null;
+/**
+ * The hint row under the composer. A cleared draft's restore key is not here:
+ * the status line already says "Cleared · Ctrl+Y restores".
+ */
+export declare function getInputShortcutHint(state: Pick<InputState, 'segments' | 'cursor'>, running?: boolean): string | null;
 /** Save history and clear a submitted draft in one place for both renderers. */
 export declare function recordInputHistory(state: InputState, entry?: string, maxEntries?: number): InputState;
 export declare function historyUp(state: InputState): InputState;

package/dist/ui/core/input_segments.js

@@ -832,12 +832,14 @@ export function yankInputKill(state, killed) {
         next = insertSegment(next, { ...segment });
     return next;
 }
-export function getInputShortcutHint(state, running = false, canYank = false) {
+/**
+ * The hint row under the composer. A cleared draft's restore key is not here:
+ * the status line already says "Cleared · Ctrl+Y restores".
+ */
+export function getInputShortcutHint(state, running = false) {
     const hints = [];
     if (state.segments.length > 0)
         hints.push(running ? 'Ctrl+C stop' : 'Ctrl+C clear');
-    if (canYank)
-        hints.push('Ctrl+Y restore');
     const paste = getPasteExpansionHint(state);
     if (paste)
         hints.push(paste);

package/dist/ui/ratatui/headless_pane_manager.d.ts

@@ -12,7 +12,9 @@ export declare function encodeZtcPaneInput(input: string): string;
  * control plane. Callers that DO need specific infra vars in a child (e.g.
  * sim agent panes attaching to the message bus) must pass them explicitly via
  * `commandEnv` — those are merged last. Host RPC credentials are still removed
- * from user process panes after the merge.
+ * from user process panes after the merge. A headless run's reserved
+ * inference credentials are removed from every pane except `ztc` panes, which
+ * infer for themselves and reserve them again for their own tool children.
  */
 export declare function computePaneSpawnEnv(paneType: string, paneId: number, options?: {
     persona?: string;

package/dist/ui/ratatui/headless_pane_manager.js

@@ -19,7 +19,7 @@ import { accessSync, chmodSync, constants, existsSync, statSync } from 'fs';
 import { delimiter, dirname, isAbsolute, join, resolve } from 'path';
 import { createRequire } from 'module';
 import { isMuxPaneRestorable, resolveMuxPersistenceOptions, sanitizeMuxSessionState, validateWorkspaceState } from './mux_persistence.js';
-import { buildUserSubprocessEnv, removeUserSubprocessCredentials } from '../../utils/subprocess_env.js';
+import { buildUserSubprocessEnv, removeUserSubprocessCredentials, restoreModelRouteCredentials } from '../../utils/subprocess_env.js';
 import { handleWorkspaceLayout } from '../../workspace_layout.js';
 let _ptyMod;
 function loadPty() {
@@ -106,7 +106,9 @@ export function encodeZtcPaneInput(input) {
  * control plane. Callers that DO need specific infra vars in a child (e.g.
  * sim agent panes attaching to the message bus) must pass them explicitly via
  * `commandEnv` — those are merged last. Host RPC credentials are still removed
- * from user process panes after the merge.
+ * from user process panes after the merge. A headless run's reserved
+ * inference credentials are removed from every pane except `ztc` panes, which
+ * infer for themselves and reserve them again for their own tool children.
  */
 export function computePaneSpawnEnv(paneType, paneId, options = {}, source = process.env) {
     const env = {
@@ -116,7 +118,10 @@ export function computePaneSpawnEnv(paneType, paneId, options = {}, source = pro
         ...(options.persona ? { ZTC_SIM_PERSONA: options.persona } : {}),
         ...(options.commandEnv ?? {}),
     };
-    return paneType === 'colony_ztc' ? env : removeUserSubprocessCredentials(env);
+    if (paneType === 'colony_ztc')
+        return env;
+    const childEnv = removeUserSubprocessCredentials(env);
+    return paneType === 'ztc' ? restoreModelRouteCredentials(childEnv, { ...source, ...(options.commandEnv ?? {}) }) : childEnv;
 }
 /**
  * Inverse of encodeZtcPaneInput: recover the original input from a stdin line a
@@ -332,18 +337,24 @@ export class HeadlessPaneManager {
         return { cols: 120, rows: 40 };
     }
     async stop() {
+        const signalled = [];
         for (const pane of this.panes.values()) {
             if (pane.isAlive && (pane.process || pane.pty)) {
                 try {
                     this.killPaneProc(pane, 'SIGTERM');
+                    signalled.push(pane);
                 }
                 catch {
                     // Ignore
                 }
             }
         }
-        // Give child processes enough time to save session state via emergencySave
-        await new Promise((resolve) => setTimeout(resolve, 3000));
+        // Give child processes up to three seconds to save session state via emergencySave;
+        // stop waiting once every signalled pane has exited.
+        const deadline = Date.now() + 3000;
+        while (signalled.some(pane => pane.isAlive) && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
         for (const pane of this.panes.values()) {
             if (pane.isAlive && (pane.process || pane.pty)) {
                 try {

package/dist/ui/ratatui/input.js

@@ -5,11 +5,12 @@ export function clipboardPastePreference(input, key, paste = false) {
         return null;
     const command = key.super === true || (key.meta === true && key.alt !== true);
     const isV = input.toLowerCase() === 'v';
-    if (isV && (command || (key.ctrl && key.shift)))
+    if ((isV && command && !key.ctrl) || isControlKey(input, key, 'v', { shift: true }))
         return 'text';
-    if (isV && key.ctrl)
+    if (isControlKey(input, key, 'v'))
         return 'image';
-    if (isControlKey(input, key, 'i'))
+    // Tab is the byte Ctrl+I shares; a key the renderer names Tab is Tab.
+    if (!key.tab && isControlKey(input, key, 'i'))
         return 'image-only';
     return null;
 }

package/dist/ui/ratatui/process.js

@@ -9,22 +9,30 @@
  * a fullscreen multiplexer with split panes (alternate screen mode).
  */
 import { spawn } from 'child_process';
-import { existsSync, unlinkSync, appendFileSync } from 'fs';
+import { existsSync, unlinkSync } from 'fs';
 import { createInterface } from 'readline';
 import { join, dirname, resolve } from 'path';
-import { homedir, platform, arch, tmpdir } from 'os';
+import { homedir, platform, arch } from 'os';
 import { fileURLToPath } from 'url';
 import { createConnection } from 'net';
 import { serializeCommand, parseEvent, CAPABILITY_CLIPBOARD_IMAGE, CAPABILITY_CLIPBOARD_TEXT } from './protocol.js';
 import { generateIpcPath, removeOwnedIpcPath } from './ipc_path.js';
 import { loadDesktopRuntime, validateDesktopRendererReady } from '../../desktop/runtime.js';
-// Debug log file - use a file to avoid interfering with TUI
-const DEBUG_LOG_FILE = join(tmpdir(), `ztc-debug-${process.pid}.log`);
-function debugLog(message) {
-    if (process.env.ZTC_DEBUG === '1') {
-        const timestamp = new Date().toISOString();
-        appendFileSync(DEBUG_LOG_FILE, `[${timestamp}] ${message}\n`);
-    }
+import { debugFileLog as debugLog, describeInputForLog } from '../../utils/debug_log.js';
+import { rendererOpensInBackground } from '../../utils/session_interactivity.js';
+/** Renderer events that carry no user text, logged whole. */
+const PLAIN_RENDERER_EVENTS = new Set(['ready', 'resize', 'resize_ack', 'quit_requested']);
+/**
+ * A renderer event line as the debug log records it. Input, clipboard text,
+ * pane output and the rest can hold what the user typed or pasted, so they
+ * are logged by kind and size only.
+ */
+function describeRendererLine(line, event) {
+    if (!event)
+        return `unparsed ${line.length} bytes`;
+    if (event.type === 'input')
+        return `input ${describeInputForLog(event.input, event.paste)}`;
+    return PLAIN_RENDERER_EVENTS.has(event.type) ? line : `${event.type} ${line.length} bytes`;
 }
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -543,6 +551,9 @@ export class TuiProcess {
             if (this._desktopMode && options?.desktopUpdateRelaunch) {
                 childEnv.ZTERM_UPDATE_RELAUNCH = options.desktopUpdateRelaunch;
             }
+            // A test or CI run opens ZTerm without taking the person's focus.
+            if (this._desktopMode && rendererOpensInBackground(childEnv))
+                childEnv.ZTERM_BACKGROUND = '1';
             this.process = spawn(binaryPath, spawnArgs, {
                 stdio: this._desktopMode
                     ? ['ignore', 'ignore', 'pipe'] // Desktop: zterm owns its native window
@@ -761,12 +772,10 @@ export class TuiProcess {
             this.cleanup();
         });
         this.readline.on('line', (line) => {
-            debugLog(`[ztc-tui socket] ${line}`);
             const event = parseEvent(line);
-            if (!event) {
-                debugLog(`[ztc-tui] Failed to parse: ${line}`);
+            debugLog(`[ztc-tui socket] ${describeRendererLine(line, event)}`);
+            if (!event)
                 return;
-            }
             // `clipboard_image` is the answer to readClipboardImage(); consume it
             // here so it never reaches app event handlers.
             if (event.type === 'clipboard_image') {

package/dist/ui/ratatui/protocol.d.ts

@@ -38,6 +38,8 @@ export declare const CAPABILITY_TERMINAL_FRAME_METRICS = "terminal_frame_metrics
 export declare const CAPABILITY_TERMINAL_INTERACTION = "terminal_interaction_v1";
 export declare const CAPABILITY_CLIPBOARD_IMAGE = "clipboard_image";
 export declare const CAPABILITY_CLIPBOARD_TEXT = "clipboard_text";
+/** The renderer writes `transmit_image` uploads to its terminal. */
+export declare const CAPABILITY_KITTY_GRAPHICS = "kitty_graphics";
 export type SplitDirection = 'horizontal' | 'vertical';
 export type LayoutPreset = 'grid' | 'columns' | 'rows' | 'main_and_stack';
 export type PaneScrollMode = 'line_up' | 'line_down' | 'page_up' | 'page_down' | 'top' | 'bottom' | 'ratio';
@@ -287,6 +289,14 @@ export type RustCommand = {
 } | {
     type: 'read_clipboard_text';
     request_id: string;
+} | {
+    type: 'transmit_image';
+    id: number;
+    cols: number;
+    rows: number;
+    width: number;
+    height: number;
+    data: string;
 } | {
     type: 'config';
     scrollback?: boolean;
@@ -474,6 +484,10 @@ export type RustEvent = DesktopTaskAction | DesktopRuntimeAction | DesktopSessio
     cols: number;
     rows: number;
     capabilities?: string[];
+    cell_pixels?: {
+        width: number;
+        height: number;
+    };
 } | {
     type: 'input';
     input: string;

package/dist/ui/ratatui/protocol.js

@@ -15,6 +15,8 @@ export const CAPABILITY_TERMINAL_FRAME_METRICS = 'terminal_frame_metrics_v1';
 export const CAPABILITY_TERMINAL_INTERACTION = 'terminal_interaction_v1';
 export const CAPABILITY_CLIPBOARD_IMAGE = 'clipboard_image';
 export const CAPABILITY_CLIPBOARD_TEXT = 'clipboard_text';
+/** The renderer writes `transmit_image` uploads to its terminal. */
+export const CAPABILITY_KITTY_GRAPHICS = 'kitty_graphics';
 // ============================================================================
 // Serialization helpers
 // ============================================================================

package/dist/ui/scrollback.d.ts

@@ -6,6 +6,7 @@
  */
 import type { Message } from '../types.js';
 import { type ToolBodyHighlightPlan } from './syntax_highlight.js';
+import type { TextStyle } from './core/types.js';
 import { displayWidth, normalizeTranscriptText, padEndDisplay } from './core/text_width.js';
 /** Body gutter for a markdown/plain body; reasoning bodies pass a deeper one. */
 export interface ScrollbackBodyOptions {
@@ -65,7 +66,23 @@ export declare function toolBodyHighlightPlanForMessage(message: Message): ToolB
 export declare function messageToScrollbackLines(message: Message, formatTime: (date: Date) => string, cols: number, options?: {
     showThinking?: boolean;
     showTurnMetadata?: boolean;
+    /** The launch welcome draws the ZTC wordmark; a terminal too short for it leaves it out. */
+    wordmark?: boolean;
 }): ScrollbackLine[];
+/** A run of the launch welcome and its style; unstyled runs are spaces. */
+export type WelcomeRun = {
+    text: string;
+    style?: TextStyle;
+};
+/**
+ * The launch welcome with the ZTC wordmark, row by row as styled runs: beside
+ * the readout, centred on it, when both fit on a row; above it otherwise, as
+ * the film stacks them on a phone; and the readout alone where the wordmark
+ * does not fit, or when the caller leaves it out (too short to show it whole).
+ * The one owner of its layout and palette: the scrollback prints these rows
+ * with escape codes and the frame (the desktop app) paints them as styles.
+ */
+export declare function wordmarkWelcomeRows(content: string, cols: number, showMark: boolean): WelcomeRun[][];
 /**
  * Render message body to scrollback lines, matching the live
  * `ContentRenderer` in `components/SingleMessage.tsx`.