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

package/dist/cli_args.js

@@ -1,11 +1,10 @@
-import { CODEX_REASONING_EFFORTS } from './config/types.js';
-import { getSupportedCodexReasoningEfforts, unsupportedEffortMessage } from './utils/models.js';
 import { validateProfileName } from './config/profiles.js';
 const BOOLEAN_FLAGS = new Set([
-    '--no-pin-task-header', '--help', '-h', '--version', '-v', '--list-sessions', '--plan', '--desktop', '--mux', '--no-mux', '--new-window', '--fullscreen', '--pane', '--human-sim-pane', '--zlicky', '--computer-use', '--ml', '--sfx-list', '--voyager-loop', '--mirror', '--open-mirror', '--mirror-open', '--no-browser-open', '--navigator-hidden', '--headless-mirror', '--headless-mirror-open', '--headless-interactive', '--headless', '--json', '--json-stream', '--quiet', '-q', '--timestamps', '--verbose', '--colony',
+    '--detach-environment', '--no-pin-task-header', '--help', '-h', '--version', '-v', '--list-sessions', '--plan', '--desktop', '--mux', '--no-mux', '--new-window', '--fullscreen', '--pane', '--human-sim-pane', '--zlicky', '--computer-use', '--ml', '--sfx-list', '--voyager-loop', '--mirror', '--open-mirror', '--mirror-open', '--no-browser-open', '--navigator-hidden', '--headless-mirror', '--headless-mirror-open', '--headless-interactive', '--headless', '--json', '--json-stream', '--quiet', '-q', '--timestamps', '--verbose', '--colony',
 ]);
 const REQUIRED_VALUE_FLAGS = new Set([
-    '--cwd', '--name', '--session-id', '--session-file', '--mode', '--agent-domain', '--domain-paths', '--embedded', '--embedded-rom', '--embedded-workflow', '--embedded-runtime-tick-ms', '--embedded-runtime-frame-budget', '--bench', '--bench-workflow', '--num-zergs', '--provider', '--model', '--profile', '--effort', '--thinking', '--emulation', '--prompt', '--max-iterations', '--timeout', '--output', '--voyager-task', '--voyager-max-rounds', '--mirror-port', '--navigator-group', '--connect-zerg',
+    '--layout', '--layout-refresh-ms', '--layout-workers',
+    '--cwd', '--name', '--session-id', '--session-file', '--mode', '--agent-domain', '--domain-paths', '--embedded', '--embedded-rom', '--embedded-workflow', '--embedded-runtime-tick-ms', '--embedded-runtime-frame-budget', '--bench', '--bench-workflow', '--num-zergs', '--provider', '--model', '--auth-mode', '--router-url', '--profile', '--effort', '--thinking', '--emulation', '--prompt', '--max-iterations', '--timeout', '--output', '--voyager-task', '--voyager-max-rounds', '--mirror-port', '--navigator-group', '--connect-zerg',
 ]);
 const OPTIONAL_VALUE_FLAGS = new Set(['--resume', '--continue', '-c', '--sfx']);
 /** Separate prompt text from options before the legacy flag consumers see it. */
@@ -48,6 +47,7 @@ export function parsePromptInvocation(input) {
     return { args, ...(prompt !== undefined ? { prompt } : {}) };
 }
 const POSITIVE_INTEGER_FLAGS = new Set([
+    '--layout-refresh-ms', '--layout-workers',
     '--timeout',
     '--max-iterations',
     '--embedded-runtime-tick-ms',
@@ -96,19 +96,7 @@ export function validateCliArgs(args) {
                     return { ok: false, message: error.message, error: 'invalid_profile', flag: token, value: next };
                 }
             }
-            if (token === '--effort') {
-                if (!CODEX_REASONING_EFFORTS.includes(next)) {
-                    return { ok: false, message: `--effort must be one of: ${CODEX_REASONING_EFFORTS.join(', ')}.`, error: 'invalid_effort', flag: token, value: next };
-                }
-                const modelIndex = args.indexOf('--model');
-                const providerIndex = args.indexOf('--provider');
-                const model = modelIndex >= 0 ? args[modelIndex + 1] : undefined;
-                const provider = providerIndex >= 0 ? args[providerIndex + 1] : undefined;
-                const supported = getSupportedCodexReasoningEfforts(model, provider);
-                if (supported && !supported.includes(next)) {
-                    return { ok: false, message: unsupportedEffortMessage(model, next, supported), error: 'unsupported_effort', flag: token, value: next };
-                }
-            }
+            // Model-specific effort validation runs after configuration and Router definitions load.
             i += 1;
             continue;
         }
@@ -136,6 +124,20 @@ export function validateCliArgs(args) {
             };
         }
     }
+    const layout = args.includes('--layout');
+    const setting = args.find(arg => arg === '--layout-refresh-ms' || arg === '--layout-workers');
+    if (setting && !layout)
+        return { ok: false, message: `Error: ${setting} requires --layout.`, error: 'missing_layout', flag: setting };
+    if (layout) {
+        const conflict = ['--headless', '--pane', '--no-mux', '--num-zergs'].find(flag => args.includes(flag));
+        if (conflict)
+            return { ok: false, message: 'Error: --layout requires an interactive workspace and cannot be combined with --headless, --pane, --no-mux or --num-zergs.', error: 'conflicting_layout_options', flag: conflict };
+        for (const [flag, max] of [['--layout-refresh-ms', 86400000], ['--layout-workers', 32]]) {
+            const index = args.indexOf(flag);
+            if (index >= 0 && Number(args[index + 1]) > max)
+                return { ok: false, message: `Error: ${flag} must not exceed ${max}.`, error: 'invalid_layout_bound', flag, value: args[index + 1] };
+        }
+    }
     return { ok: true };
 }
 export function requiresPlanSafeRenderer(options) {

package/dist/cli_main.js

@@ -31,8 +31,20 @@ import { parsePromptInvocation, requiresPlanSafeRenderer, validateCliArgs, } fro
 import { parseHeadlessInteractionMode } from './app/headless_interaction.js';
 import { buildCliCommonStarts } from './onboarding/first_run.js';
 import { validateProfileName } from './config/profiles.js';
-// Parse command line args
+import { loadDesktopRuntime } from './desktop/runtime.js';
+import { resolveOwnedCliLaunch } from './desktop/cli_launch.js';
+// Information-only flags remain available to diagnose an incompatible bundle.
 const args = process.argv.slice(2);
+let desktopRuntime = null;
+try {
+    if (!args.some(arg => ['--help', '-h', '--version', '-v'].includes(arg)))
+        desktopRuntime = loadDesktopRuntime();
+}
+catch (error) {
+    console.error(`[ztc] ${error.message}`);
+    process.exit(1);
+}
+// Parse command line args
 const profileExplicitAtLaunch = args.includes('--profile') || process.env.ZTC_PROFILE !== undefined;
 const profileFlags = args.flatMap((arg, index) => arg === '--profile' ? [index] : []);
 if (profileFlags.length > 1) {
@@ -59,6 +71,23 @@ catch (error) {
 const commandArgs = profileFlags.length === 0
     ? args
     : args.filter((_, index) => index !== profileFlags[0] && index !== profileFlags[0] + 1);
+// Attachment owns its terminal and transport; do not initialize a local agent.
+if (commandArgs[0] === 'attach') {
+    const { runTerminalAttachCli } = await import('./terminal_attach.js');
+    process.exit(await runTerminalAttachCli(commandArgs.slice(1)));
+}
+// Adapters must be able to deliver receipts without starting an agent or a TTY.
+if (commandArgs[0] === 'inbox') {
+    try {
+        const { runInboxCli } = await import('./intake/cli.js');
+        await runInboxCli(commandArgs.slice(1));
+    }
+    catch (error) {
+        console.error(`[ztc inbox] ${error.message}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
 // Device login must work without a TTY, provider credentials, or agent startup.
 if (commandArgs[0] === 'auth') {
     try {
@@ -192,7 +221,8 @@ catch (error) {
     console.error(`[ztc] ${error.message}`);
     process.exit(2);
 }
-// `ztc attach` — REMOVED in favour of zmux's native frame-mirror protocol.
+// Local frame attachment uses zmux's native protocol through Ctrl+B W.
+// `ztc attach --session` uses an explicit durable tmux backend, locally or over SSH.
 //
 // The Ctrl+B W navigator now dispatches an `attach_mirror` command directly to
 // the local zmux, which connects to the remote zmux's Unix socket and paints
@@ -235,6 +265,7 @@ ZTC - Zerg Terminal Client v${version}
 
 Usage: ztc [options] [prompt]
        ztc auth <login|status|logout>
+       ztc inbox list|show <req-ID>|receive --file <request.json> [--json]
        ztc config reset [--profile <name>]
        ztc resume [id]
        ztc --branch <workspace-name> [options]
@@ -285,6 +316,9 @@ Options:
   --new-window         Open a new terminal window for zmux (auto-detects terminal emulator)
   --fullscreen         Maximize the new terminal window to fill the screen
   --num-zergs <n|CxR>  Auto-create ZTC panes: N for columns, CxR for grid (e.g. 3x2)
+  --layout <name>      Open orchestrator, pair, grid or .ztc/layouts/<name>.yaml
+  --layout-refresh-ms <n>  Orchestrator status refresh (default: 600000); r refreshes now
+  --layout-workers <n> Grid worker count (1–32; default: 4)
   --embedded <system>  Start in an embedded workspace for the named checked-in system
   --embedded-rom <path>
                        Override the ROM/image used by an embedded runtime, when supported
@@ -298,6 +332,8 @@ Options:
   --bench-workflow <id>
                        Run a bench workflow after opening the workspace
   --provider <name>    LLM provider override (anthropic, claude_code, openai, codex_app_server, codex_legacy, gemini, inception, kimi, kimi_code, etc.; codex is a legacy alias)
+  --auth-mode <mode>  Override routing for this process (auto, direct, zrouter)
+  --router-url <url>  Router origin for this process; matching login is required
   --profile <name>     Use named settings in ~/.ztc/profiles/<name>/config.json
                        (default: ~/.ztc/config.json). Sessions stay shared.
   --model <name>       LLM model override (e.g., claude-sonnet-4-20250514, gpt-4o)
@@ -318,6 +354,7 @@ Headless Mode (for automation/CI):
   --prompt <text>      Run a single prompt and exit (with --headless)
   -p, --print          Run a prompt or stdin without the interactive terminal
   --max-iterations <n> Cap agent iterations per prompt (default: unlimited; the wall-clock timeout is the backstop)
+  --detach-environment Resume the conversation in the current project without reopening its saved environment
   --quiet, -q          Suppress build output, only show agent responses
   --timestamps         Show timestamps in plain text output
   --timeout <ms>       Timeout for agent operations in milliseconds (default: 43200000)
@@ -423,6 +460,7 @@ In-App Commands:
   /zlicky-ptt        Toggle Zlicky global push-to-talk dictation
   /voice             Manage TTS voice synthesis
   /update            Update ZTC (saves session, updates, restarts)
+  /desktop install-cli [directory]  Install the bundled app's optional terminal command
   /exit              Exit ZTC
 
 Keyboard Shortcuts:
@@ -776,6 +814,9 @@ if (numZergsIndex >= 0) {
         }
     }
 }
+const layoutPreset = args.includes('--layout') ? required_flag_value('--layout', 'Error: --layout requires a name') : undefined;
+const layoutRefreshMs = args.includes('--layout-refresh-ms') ? Number(required_flag_value('--layout-refresh-ms', 'Error: --layout-refresh-ms requires a value')) : undefined;
+const layoutWorkers = args.includes('--layout-workers') ? Number(required_flag_value('--layout-workers', 'Error: --layout-workers requires a value')) : undefined;
 // Parse Zlicky/computer-use flags for computer control tools.
 const zlickyMode = args.includes('--zlicky');
 const computerUseMode = args.includes('--computer-use') || zlickyMode;
@@ -889,13 +930,26 @@ end tell`;
 function openInNewWindow(maximize) {
     // Build re-launch command: same argv minus --new-window and --fullscreen
     const filteredArgs = process.argv.slice(1).filter(a => a !== '--new-window' && a !== '--fullscreen');
+    // --cwd already selected the project before this branch. Forward that
+    // directory instead of applying a relative path again after the shell's cd.
+    const cwdArgumentIndex = filteredArgs.lastIndexOf('--cwd');
+    if (cwdArgumentIndex >= 0)
+        filteredArgs[cwdArgumentIndex + 1] = process.cwd();
     // When running via tsx (dev mode), process.execPath is still "node" which can't run .ts files.
     // Detect this and use npx tsx instead.
     const scriptPath = filteredArgs[0] || '';
-    const runner = scriptPath.endsWith('.ts')
+    const ownedLaunch = resolveOwnedCliLaunch(filteredArgs.slice(1), desktopRuntime);
+    const runner = ownedLaunch ? shellEscape(ownedLaunch.command) : scriptPath.endsWith('.ts')
         ? 'npx tsx'
         : shellEscape(process.execPath);
-    const relaunchCmd = `cd ${shellEscape(process.cwd())} && ${runner} ${filteredArgs.map(shellEscape).join(' ')}`;
+    // Terminal/iTerm start a fresh shell; carry only the admitted bundle's state routing.
+    const ownerEnvironment = ownedLaunch
+        ? ['ZTC_DESKTOP_RUNTIME_MANIFEST', 'ZTC_PROFILE', 'ZTC_CONFIG_DIR', 'ZTC_SESSIONS_DIR'].flatMap(key => {
+            const value = process.env[key];
+            return value === undefined ? [] : [`${key}=${shellEscape(value)}`];
+        })
+        : [];
+    const relaunchCmd = `cd ${shellEscape(process.cwd())} && ${[...ownerEnvironment, runner, ...(ownedLaunch?.args ?? filteredArgs).map(shellEscape)].join(' ')}`;
     const COLS = 220;
     const ROWS = 55;
     const termProgram = process.env.TERM_PROGRAM || '';
@@ -1043,9 +1097,36 @@ async function main() {
         const { initMcpServers } = await import('./mcp/client.js');
         await initMcpServers(mcpServers);
     }
+    const authModeIndex = args.indexOf('--auth-mode');
+    const routerUrlIndex = args.indexOf('--router-url');
+    if (authModeIndex >= 0 || routerUrlIndex >= 0) {
+        const authMode = authModeIndex >= 0 ? args[authModeIndex + 1] : configStore.getAuthMode();
+        if (!['auto', 'direct', 'zrouter'].includes(authMode))
+            throw new Error('Invalid --auth-mode');
+        configStore.setCliOverride('authMode', authMode);
+        if (routerUrlIndex >= 0)
+            configStore.setCliOverride('zergProxyUrl', args[routerUrlIndex + 1]);
+    }
     // Apply --provider / --model CLI overrides (never persisted to config.json)
+    // Discover opaque model IDs and Router-defined reasoning choices before
+    // resolving explicit launch flags. Normal interactive startup waits until
+    // after its first paint to do this HTTP request.
+    const modelParts = cliModel?.split('/') ?? [];
+    const knownQualifiedModel = modelParts.length === 2 && getProviderForModel(modelParts[1]) === modelParts[0];
+    const needsModelDiscovery = !!cliModel && !cliProvider && !getProviderForModel(cliModel) && !knownQualifiedModel;
+    if (needsModelDiscovery || args.includes('--effort') || args.includes('--thinking')) {
+        try {
+            if (configStore.resolveLLMBackendConfig({ provider: cliProvider || undefined }).useProxy) {
+                const { buildModelsController } = await import('./app/command_context.js');
+                await buildModelsController(configStore).catalog(AbortSignal.timeout(1000));
+            }
+        }
+        catch { /* Existing cached/legacy controls remain usable while offline. */ }
+    }
+    const cliRoute = configStore.getResolvedAuthMode();
+    const inferredCliProvider = cliProvider || (cliRoute === 'zrouter' && knownQualifiedModel ? modelParts[0] : undefined);
     const resolvedCliOverride = cliModel
-        ? resolveModelAndProvider(cliModel, cliProvider || undefined)
+        ? resolveModelAndProvider(cliModel, inferredCliProvider, cliRoute)
         : undefined;
     const effectiveCliProvider = (resolvedCliOverride?.provider || cliProvider);
     const effectiveCliModel = resolvedCliOverride?.model || cliModel;
@@ -1069,11 +1150,17 @@ async function main() {
     const thinkingIndex = args.indexOf('--thinking');
     if (effortIndex >= 0 || thinkingIndex >= 0) {
         const { parseReasoningSelection } = await import('./utils/reasoning.js');
-        const level = parseReasoningSelection(configStore.getProvider(), configStore.getModel(), configStore.getCodexEffort(), {
-            effort: effortIndex >= 0 ? args[effortIndex + 1] : undefined,
-            thinking: thinkingIndex >= 0 ? args[thinkingIndex + 1] : undefined,
-        });
-        configStore.setCliOverride('codexEffort', level ?? undefined);
+        try {
+            const level = parseReasoningSelection(configStore.getProvider(), configStore.getModel(), configStore.getCodexEffort(), {
+                effort: effortIndex >= 0 ? args[effortIndex + 1] : undefined,
+                thinking: thinkingIndex >= 0 ? args[thinkingIndex + 1] : undefined,
+            }, configStore.getReasoningContract());
+            configStore.setCliOverride('codexEffort', level ?? undefined);
+        }
+        catch (error) {
+            console.error(`[ztc] ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(2);
+        }
     }
     // Background-refresh superuser status so pre-existing logins get the field backfilled.
     // Skip for colony children (they inherit the parent status) and explicitly offline
@@ -1177,6 +1264,7 @@ async function main() {
         debugLog('[main] Running in headless mode');
         const { runHeadless } = await import('./headless.js');
         await runHeadless({
+            detachEnvironment: args.includes('--detach-environment'),
             mode: zlickyMode ? 'zlicky' : (startInPlanMode ? undefined : (modePathArg || undefined)),
             planMode: startInPlanMode,
             sessionId: headlessSessionId || undefined,
@@ -1208,6 +1296,7 @@ async function main() {
         debugLog(`[main] Running as headless child pane (ZTC_PANE_ID=${process.env.ZTC_PANE_ID})`);
         const { runHeadless } = await import('./headless.js');
         await runHeadless({
+            detachEnvironment: args.includes('--detach-environment'),
             mode: zlickyMode ? 'zlicky' : (startInPlanMode ? undefined : (modePathArg || undefined)),
             planMode: startInPlanMode,
             sessionId: explicitSessionId || undefined,
@@ -1308,7 +1397,7 @@ async function main() {
         process.exit(1);
     }
     // Interactive ZTC defaults to zmux. If it is unavailable, fall back to single-pane Ratatui.
-    if (!headlessMirror && desktopMode && !isZtermAvailable()) {
+    if (!headlessMirror && desktopMode && !isZtermAvailable(desktopRuntime)) {
         console.error('Error: zterm desktop binary not found.');
         console.error('Build it with: cd packages/zterm && cargo build --release');
         process.exit(1);
@@ -1487,6 +1576,7 @@ async function main() {
     debugLog('[main] Creating RatatuiApp');
     const { RatatuiApp } = await import('./cli_ratatui.js');
     const app = new RatatuiApp({
+        detachEnvironment: args.includes('--detach-environment'),
         resumeSession: resumedSession || undefined,
         resumePicker: resumePickerRequested,
         sessionId: resumedSession?.metadata.id || explicitSessionId || undefined,
@@ -1502,7 +1592,11 @@ async function main() {
         navigatorHidden,
         mux: muxMode,
         desktop: desktopMode,
+        desktopRuntime,
         numZergsGrid: muxMode ? numZergsGrid : { cols: 1, rows: 1 },
+        layoutPreset,
+        layoutRefreshMs,
+        layoutWorkers,
         embeddedSystemName: embeddedSystemName || undefined,
         embeddedWorkflowId: embeddedWorkflowId || undefined,
         benchName: benchName || undefined,
@@ -1566,9 +1660,12 @@ async function main() {
     catch (err) {
         debugLog(`[main] Caught error: ${err.message}`);
         console.error('Failed to start Ratatui renderer:', err.message);
-        if (effectivePlanLaunch
+        if (desktopMode
+            || effectivePlanLaunch
             || err.name === 'PlanFileCreationError') {
-            console.error('Plan mode startup failed closed; Ink fallback is disabled.');
+            console.error(desktopMode
+                ? 'Desktop startup failed. Update or reinstall ZTerm.app and try again.'
+                : 'Plan mode startup failed closed; Ink fallback is disabled.');
             if (createdSessionStubId) {
                 try {
                     await deleteSession(process.cwd(), createdSessionStubId);