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

package/dist/agent/commands/settings.js

@@ -1,10 +1,16 @@
+import { parseReasoningSelection } from '../../utils/reasoning.js';
+import { resolveRouterModel } from '../../utils/router_catalog.js';
+import { getSupportedCodexReasoningEfforts } from '../../utils/models.js';
 import { resolveExecutionSettings } from '../../config/execution.js';
 import { accountsCommand } from './accounts.js';
 import { authCommand } from './auth.js';
+import { setupCommand } from './setup.js';
+import { activatePermissionConfig } from './permissions.js';
+import { PERMISSION_CAPABILITIES } from '../../config/permissions.js';
 import { activeProfile, builtinProfileEmulation, listConfigProfiles } from '../../config/profiles.js';
 import { switchConfigProfile } from './config_profile_switch.js';
 import { keybindingsCommand } from './keybindings.js';
-import { DEFAULT_CONTEXT_PROGRESS_BAR } from '../../config.js';
+import { DEFAULT_CONTEXT_PROGRESS_BAR, resolveTerminalInteractionSettings } from '../../config.js';
 import { loadRouterCredentials } from '../../router_auth.js';
 import { CODEX_REASONING_EFFORTS } from '../../config/types.js';
 import { customPaneOptions, storedCustomPaneOptions, withCustomPaneOptions, } from '../../config/panes.js';
@@ -16,13 +22,13 @@ import { applyRuntimeModelSelection, getEffectiveModel } from './runtime_model.j
 import { parseGoalTurnCap } from './goal.js';
 import { shutdownAndClearWorkflowRegistry } from '../../workflows/registry_handle.js';
 import { invalidateSkillsCache, preloadSkillsManifest } from '../../skills/registry.js';
-import { MIN_TOOL_OUTPUT_LINES, parseToolOutputLines, resolveMessageDisplaySettings, } from '../../config/message_display.js';
+import { MIN_TOOL_OUTPUT_LINES, parseToolOutputLines, parseProseReadingRate, resolveMessageDisplaySettings, } from '../../config/message_display.js';
 import { DEFAULT_JEV_SETTINGS, MAX_AUTO_COMPACT_THRESHOLD, MAX_COMPACTION_TARGET_PERCENT, MIN_AUTO_COMPACT_THRESHOLD, MIN_COMPACTION_TARGET_PERCENT, MIN_CONTEXT_TOKEN_BUDGET, defaultTokenTrigger, maxCompactionTargetFor, minAutoCompactThresholdFor, parseCompactionTriggerMode, resolveAutoCompactThreshold, resolveCompactionTargetPercent, resolveCompactionTriggerMode, resolveCompactionSettings, resolveContextTokenBudget, tokenTriggerActive, MAX_JEV_KEEP_THRESHOLD, MAX_JEV_STATE_TOKENS, MIN_JEV_KEEP_THRESHOLD, MIN_JEV_PRESERVE_RECENT, MIN_JEV_STATE_TOKENS, parseAutoCompactThreshold, parseCompactionTargetPercent, parseContextTokenBudget, parseJevKeepThreshold, parseJevPreserveRecent, parseJevStateTokens, } from '../../config/compaction.js';
 import { MIN_MAX_ITERATIONS, parseMaxIterations } from '../../config/agent_limits.js';
 import { MAX_SFX_VOLUME, MIN_SFX_VOLUME, parseSfxPack, parseSfxVolume, resolveSfxPack, resolveSfxVolume, } from '../../config/sound.js';
 import { listPacks } from '../../audio/sfx.js';
 import { DEFAULT_SPINNER_VERBS, parseSpinnerVerbs } from '../../utils/spinner_verbs.js';
-import { MIN_API_RETRY_ATTEMPTS, MIN_API_RETRY_BASE_DELAY_MS, MIN_API_RETRY_TIMEOUT_MS, parseApiRetryAttempts, parseApiRetryBaseDelayMs, parseApiRetryTimeoutMs, resolveApiRetrySettings, } from '../../config/api_retry.js';
+import { MIN_API_RETRY_ATTEMPTS, MIN_API_RETRY_BASE_DELAY_MS, MIN_API_RETRY_TIMEOUT_MS, parseApiRetryAttempts, parseApiRetryBaseDelayMs, parseApiRetryMaxDelayMs, parseApiRecoveryWindowMs, parseApiRetryTimeoutMs, resolveApiRetrySettings, } from '../../config/api_retry.js';
 import { STATUS_LINE_ITEMS, compactStatusLineVariants, normalizeStatusLineSeparator, parseStatusLineItems, replaceStatusLineSide, resolveStatusLineSettings, statusLineItemOptions, statusLineSettingsForStorage, } from '../../ui/status_line_config.js';
 import { BAR_COLOR_FIELDS, contextProgressBarConfig, normalizeBarColor, publishContextProgressBar, withBarColor, } from './context_progress_bar.js';
 /**
@@ -132,6 +138,8 @@ export async function buildSettingsCategories(ctx) {
     const routerSignedIn = routerCredentials !== null && Date.parse(routerCredentials.expiresAt) > Date.now();
     const provider = ctx.config.getProvider();
     const model = ctx.config.getModel?.() || config.model;
+    const reasoningEfforts = getSupportedCodexReasoningEfforts(model, provider, ctx.config.getReasoningWireSurface?.(provider, model)
+        ?? (config.authMode === 'zrouter' || provider === 'openai_compatible' ? 'chat_tools' : 'native_api'));
     const claudeCliInstalled = isClaudeCliAvailable();
     const claudeCodeTokenPresent = Boolean(process.env.CLAUDE_CODE_OAUTH_TOKEN?.trim());
     const claudeCodeReady = hasUsableClaudeCodeCliAuth();
@@ -168,10 +176,30 @@ export async function buildSettingsCategories(ctx) {
         modelOptions = models.slice(0, 20).map(m => ({ value: m, label: m }));
     }
     catch { /* fallback: no pre-fetched options, user can type manually */ }
+    const routerCatalog = ctx.config.getRoutedModelCatalog?.();
+    const routerDescriptor = routerCatalog?.version === 1
+        ? resolveRouterModel(routerCatalog, provider, model) : undefined;
+    if (routerCatalog?.version === 1)
+        modelOptions = routerCatalog.models.filter(row => row.owned_by === provider && row.capabilities?.chat)
+            .map(row => ({ value: row.id, label: `${row.display_name || row.id}${row.capabilities?.tools === false ? ' (chat only)' : ''}${row.available === false ? ' (access unavailable)' : ''}` }));
+    const reasoningChoices = routerCatalog?.version === 1 ? routerDescriptor?.capabilities?.reasoning?.choices ?? []
+        : reasoningEfforts ?? CODEX_REASONING_EFFORTS;
+    const effortSupported = config.codexEffort === undefined || reasoningChoices.includes(config.codexEffort);
     const sections = [
         {
             name: 'Config Scope',
             settings: [
+                {
+                    name: 'setUpZtc',
+                    label: 'Set up ZTC',
+                    value: '/setup',
+                    type: 'text',
+                    description: 'Verify the runtime, account and sample workspace with the shared setup action.',
+                    onActivate: async () => {
+                        ctx.settingsPanel?.closeSettingsPanel?.();
+                        await setupCommand.handler([], ctx);
+                    },
+                },
                 {
                     name: 'configProfile',
                     label: 'Active config profile',
@@ -242,7 +270,8 @@ export async function buildSettingsCategories(ctx) {
                     // option matches a canonical PROVIDERS value instead of nothing.
                     value: normalizeProviderId(provider),
                     type: 'select',
-                    options: PROVIDERS,
+                    options: routerCatalog?.version === 1 ? [...new Map(routerCatalog.models.filter(row => row.capabilities?.chat)
+                            .map(row => [row.owned_by, { value: row.owned_by, label: row.provider_display_name || row.owned_by }])).values()] : PROVIDERS,
                 },
                 {
                     name: 'model',
@@ -258,13 +287,15 @@ export async function buildSettingsCategories(ctx) {
                     value: config.maxTokens === undefined ? 'provider default' : String(config.maxTokens),
                     type: 'text',
                     placeholder: 'provider default',
-                    description: 'Maximum output tokens, including reasoning tokens. Enter a positive whole number, or "provider default" to clear the limit.',
+                    description: `Maximum output tokens, including reasoning tokens. ${routerDescriptor?.capabilities?.max_output_tokens ? `Router limit: ${routerDescriptor.capabilities.max_output_tokens.toLocaleString()}. ` : ''}Enter a positive whole number, or "provider default" to clear the limit.`,
                 },
                 {
                     name: 'codexEffort', label: 'Default reasoning effort',
-                    value: config.codexEffort ?? 'provider default', type: 'select',
-                    options: [{ value: 'provider default', label: 'provider default' }, ...CODEX_REASONING_EFFORTS.map(level => ({ value: level, label: level }))],
-                    description: 'Global default. Model and provider overrides take precedence.',
+                    value: effortSupported ? config.codexEffort ?? 'provider default' : 'provider default', type: 'select',
+                    options: [{ value: 'provider default', label: 'provider default' }, ...reasoningChoices.map(level => ({ value: level, label: level }))],
+                    description: reasoningChoices.length === 0
+                        ? `This model takes no reasoning-effort setting (${provider} · ${model}).`
+                        : `Levels supported by ${provider} · ${model}. Model and provider overrides take precedence.`,
                 },
                 {
                     name: 'codexFastMode', label: 'Fast mode', value: String(config.codexFastMode === true), type: 'select',
@@ -536,7 +567,7 @@ export async function buildSettingsCategories(ctx) {
                     // provider's health, not a choice between five presets.
                     type: 'text',
                     placeholder: '3',
-                    description: 'How many times to try one request before failing the turn. Any whole number of at least 1.',
+                    description: 'Attempts before sustained recovery. 1 disables Agent-level retries and recovery; backend reconnect policies are separate. Any whole number of at least 1.',
                 },
                 {
                     name: 'apiRetryBaseDelay',
@@ -544,7 +575,18 @@ export async function buildSettingsCategories(ctx) {
                     value: String(apiRetry.baseDelayMs),
                     type: 'text',
                     placeholder: '2000',
-                    description: 'First wait between retries, in milliseconds. Each later wait doubles. Any whole number from 0.',
+                    description: 'Exponential wait base in milliseconds. Waits use jitter and the maximum delay below. Any whole number from 0.',
+                },
+                {
+                    name: 'apiRetryMaxDelay', label: 'Maximum retry wait', value: String(apiRetry.maxDelayMs),
+                    type: 'text', placeholder: '30000',
+                    description: 'Caps each retry wait in milliseconds. Any whole number of at least 1.',
+                },
+                {
+                    name: 'apiRetryRecoveryWindow', label: 'Endpoint recovery window',
+                    value: apiRetry.recoveryWindowMs === null ? 'continuous' : String(apiRetry.recoveryWindowMs),
+                    type: 'text', placeholder: 'continuous',
+                    description: 'After the initial attempts, retain the task until cancellation (continuous), for this many milliseconds, or stop at the initial limit (0).',
                 },
                 {
                     name: 'apiRetryTimeout',
@@ -559,6 +601,16 @@ export async function buildSettingsCategories(ctx) {
         {
             name: 'Verbosity',
             settings: [
+                {
+                    name: 'showTurnMetadata',
+                    label: 'Turn time and tokens',
+                    value: String(messageDisplay.showTurnMetadata),
+                    type: 'select',
+                    options: [
+                        { value: 'true', label: 'shown', description: 'Show elapsed time and model usage beside assistant timestamps' },
+                        { value: 'false', label: 'hidden', description: 'Keep message headers to role and timestamp' },
+                    ],
+                },
                 {
                     name: 'showThinking',
                     label: 'Show thinking prompts',
@@ -603,10 +655,19 @@ export async function buildSettingsCategories(ctx) {
                     value: String(messageDisplay.smoothStreaming),
                     type: 'select',
                     options: [
-                        { value: 'true', label: 'smooth', description: 'Reveal bursty output at a steady pace, keeping pace with the stream' },
-                        { value: 'false', label: 'instant', description: 'Show every arrival the moment it lands' },
+                        { value: 'true', label: 'smooth', description: 'Use bounded-lag smoothing when the prose reading cap is off' },
+                        { value: 'false', label: 'instant', description: 'Show every arrival immediately when the prose reading cap is off' },
                     ],
                 },
+                {
+                    name: 'proseReadingRateWordsPerSecond',
+                    label: 'Prose reading rate',
+                    value: messageDisplay.proseReadingRateWordsPerSecond === null
+                        ? 'off' : String(messageDisplay.proseReadingRateWordsPerSecond),
+                    type: 'text',
+                    placeholder: '9',
+                    description: 'Assistant prose words per second. Any positive finite rate, or "off" for bounded-lag streaming. Reasoning, tools, and messages containing fenced code are uncapped.',
+                },
             ],
         },
         {
@@ -719,6 +780,8 @@ export async function buildSettingsCategories(ctx) {
             settings: [
                 { name: 'uiTheme', label: 'Theme', value: config.uiTheme ?? 'ztc-dark', type: 'text', description: 'Terminal theme name. Use /theme list for built-in choices.' },
                 { name: 'rawScrollback', label: 'Raw scrollback', value: String(config.rawScrollback === true), type: 'select', options: [{ value: 'true', label: 'on' }, { value: 'false', label: 'off' }] },
+                { name: 'mouseCapture', label: 'Mouse capture', value: String(resolveTerminalInteractionSettings(config.terminalInteraction).mouseCapture), type: 'select', options: [{ value: 'true', label: 'on' }, { value: 'false', label: 'off' }], description: 'Requires a compatible renderer; otherwise saved for next launch.' },
+                { name: 'wheelScrollLines', label: 'Wheel scroll lines', value: String(resolveTerminalInteractionSettings(config.terminalInteraction).wheelScrollLines), type: 'text', description: 'Compatible renderer required. Lines per wheel: 1–20 (default 3).' },
                 { name: 'keybindings', label: 'Keybindings', value: `${Object.keys(config.keybindings?.zmux ?? {}).length} overrides`, type: 'text', description: 'Enter to edit shortcuts.', onActivate: () => { void keybindingsCommand.handler([], ctx); } },
                 {
                     name: 'panesCustomOptions',
@@ -889,7 +952,7 @@ export async function buildSettingsCategories(ctx) {
         group('Accounts', 'Config Scope', 'Accounts'),
         group('Provider & Model', 'Provider & Model', 'Claude Code'),
         group('Auth & Routing', 'Auth & Routing', 'API Keys', 'Custom Endpoint'),
-        group('Behavior', 'Behavior', 'Retries & Timeouts', 'Automation'),
+        group('Behavior', 'Behavior', 'Retries & Timeouts', 'Automation', 'Execution'),
         group('Context Compaction', 'Context Compaction', 'Context Storage'),
         group('Tools & Security', 'Tool Access'),
         group('Verbosity', 'Verbosity', 'Panes'),
@@ -1048,16 +1111,20 @@ function applySettingChange(ctx, setting, value) {
         ctx.config.set('execution', next);
         return;
     }
-    if (setting.startsWith('toolPermission_')) {
-        const capability = setting.slice('toolPermission_'.length);
-        if (!['file_read', 'file_write', 'shell_exec', 'network', 'screen_capture', 'computer_control', 'ml_inference'].includes(capability)) {
-            throw new Error(`Unknown tool permission: ${capability}`);
-        }
-        ctx.config.set('toolPermissions', { ...ctx.config.get().toolPermissions, [capability]: value === 'true' });
-        return;
-    }
     switch (setting) {
         case 'provider':
+            {
+                const catalog = ctx.config.getRoutedModelCatalog?.();
+                if (catalog?.version === 1) {
+                    const rows = catalog.models.filter(row => row.owned_by === value && row.capabilities?.chat);
+                    const selected = rows.find(row => row.is_default) ?? rows[0];
+                    if (!selected)
+                        throw new Error('Provider is not in the Router chat catalog.');
+                    ctx.config.setProvider(value);
+                    ctx.config.set('model', selected.id);
+                    break;
+                }
+            }
             ctx.config.setProvider(value);
             {
                 const resetModel = resolveModelForProviderChange(value, getEffectiveModel(ctx));
@@ -1082,10 +1149,19 @@ function applySettingChange(ctx, setting, value) {
             break;
         }
         case 'codexEffort':
-            if (value !== 'provider default' && !CODEX_REASONING_EFFORTS.includes(value)) {
+            const catalog = ctx.config.getRoutedModelCatalog?.();
+            const choices = catalog?.version === 1 ? resolveRouterModel(catalog, ctx.config.getProvider(), getEffectiveModel(ctx))?.capabilities?.reasoning?.choices ?? [] : CODEX_REASONING_EFFORTS;
+            if (value !== 'provider default' && !choices.includes(value)) {
                 throw new Error(`Unknown reasoning effort: ${value}`);
             }
-            ctx.config.set('codexEffort', value === 'provider default' ? undefined : value);
+            const activeConfig = ctx.config.get();
+            const activeProvider = ctx.config.getProvider();
+            const activeModel = ctx.config.getModel?.() || activeConfig.model;
+            const selectedEffort = parseReasoningSelection(activeProvider, activeModel, undefined, { effort: value === 'provider default' ? 'default' : value }, catalog?.version === 1
+                ? resolveRouterModel(catalog, activeProvider, activeModel)?.capabilities?.reasoning?.choices ?? []
+                : ctx.config.getReasoningWireSurface?.(activeProvider, activeModel)
+                    ?? (activeConfig.authMode === 'zrouter' || activeProvider === 'openai_compatible' ? 'chat_tools' : 'native_api'));
+            ctx.config.set('codexEffort', selectedEffort ?? undefined);
             break;
         case 'codexFastMode':
             ctx.config.set('codexFastMode', value === 'true');
@@ -1296,6 +1372,20 @@ function applySettingChange(ctx, setting, value) {
             ctx.config.set('apiRetry', { ...(ctx.config.get().apiRetry ?? {}), requestTimeoutMs });
             break;
         }
+        case 'apiRetryMaxDelay': {
+            const maxDelayMs = parseApiRetryMaxDelayMs(value);
+            if (maxDelayMs === null)
+                throw new Error('Maximum retry wait must be a whole number of milliseconds of at least 1.');
+            ctx.config.set('apiRetry', { ...(ctx.config.get().apiRetry ?? {}), maxDelayMs });
+            break;
+        }
+        case 'apiRetryRecoveryWindow': {
+            const recoveryWindowMs = parseApiRecoveryWindowMs(value);
+            if (recoveryWindowMs === undefined)
+                throw new Error('Recovery window must be continuous or a whole number of milliseconds of at least 0.');
+            ctx.config.set('apiRetry', { ...(ctx.config.get().apiRetry ?? {}), recoveryWindowMs });
+            break;
+        }
         case 'compactionMethod':
             ctx.config.set('compaction', {
                 ...resolveCompactionSettings(ctx.config.get()),
@@ -1366,6 +1456,12 @@ function applySettingChange(ctx, setting, value) {
                 groupToolCalls: value === 'true',
             });
             break;
+        case 'showTurnMetadata':
+            ctx.config.set('messageDisplay', {
+                ...resolveMessageDisplaySettings(ctx.config.get()),
+                showTurnMetadata: value === 'true',
+            });
+            break;
         case 'showThinking':
             ctx.config.set('messageDisplay', {
                 ...resolveMessageDisplaySettings(ctx.config.get()),
@@ -1378,6 +1474,16 @@ function applySettingChange(ctx, setting, value) {
                 smoothStreaming: value === 'true',
             });
             break;
+        case 'proseReadingRateWordsPerSecond': {
+            const rate = parseProseReadingRate(value);
+            if (rate === undefined)
+                throw new Error('Prose reading rate must be positive finite words per second, or "off".');
+            ctx.config.set('messageDisplay', {
+                ...resolveMessageDisplaySettings(ctx.config.get()),
+                proseReadingRateWordsPerSecond: rate,
+            });
+            break;
+        }
         case 'statusLineEnabled':
             ctx.config.set('statusLine', statusLineSettingsForStorage({
                 ...resolveStatusLineSettings(ctx.config.get().statusLine),
@@ -1430,22 +1536,6 @@ function applySettingChange(ctx, setting, value) {
         case 'mcpStatus':
             // Read-only informational setting.
             break;
-        case 'permissionProfile':
-            if (!ctx.config.get().permissionProfiles?.[value])
-                throw new Error(`Unknown permission profile: ${value}`);
-            ctx.config.set('permissionProfile', value);
-            break;
-        case 'sandboxEnabled':
-            ctx.config.set('sandbox', { ...ctx.config.get().sandbox, enabled: value === 'true' });
-            break;
-        case 'sandboxBackend':
-            if (!['auto', 'none', 'seatbelt', 'bubblewrap', 'windows-job'].includes(value))
-                throw new Error(`Unknown sandbox backend: ${value}`);
-            ctx.config.set('sandbox', { ...ctx.config.get().sandbox, backend: value });
-            break;
-        case 'sandboxRequireOsEnforcement':
-            ctx.config.set('sandbox', { ...ctx.config.get().sandbox, requireOsEnforcement: value === 'true' });
-            break;
         case 'sandboxAuditDir':
             ctx.config.set('sandbox', { ...ctx.config.get().sandbox, auditDir: value.trim() || undefined });
             break;
@@ -1570,6 +1660,19 @@ function applySettingChange(ctx, setting, value) {
         case 'rawScrollback':
             ctx.config.set('rawScrollback', value === 'true');
             break;
+        case 'mouseCapture':
+            if (value !== 'true' && value !== 'false')
+                throw new Error('Mouse capture must be true or false.');
+            ctx.config.set('terminalInteraction', { ...resolveTerminalInteractionSettings(ctx.config.get().terminalInteraction), mouseCapture: value === 'true' });
+            break;
+        case 'wheelScrollLines': {
+            const lines = Number(value.trim());
+            if (!value.trim() || !Number.isInteger(lines) || lines < 1 || lines > 20) {
+                throw new Error('Wheel scroll lines must be a whole number from 1 to 20.');
+            }
+            ctx.config.set('terminalInteraction', { ...resolveTerminalInteractionSettings(ctx.config.get().terminalInteraction), wheelScrollLines: lines });
+            break;
+        }
         case 'manifestsDir':
             ctx.config.set('manifestsDir', value.trim() || undefined);
             break;
@@ -1679,10 +1782,12 @@ function applySettingChange(ctx, setting, value) {
  */
 const LIVE_READ_SETTINGS = new Set([
     'toolOutputLines',
+    'showTurnMetadata',
     'collapseToolCalls',
     'groupToolCalls',
     'showThinking',
     'smoothStreaming',
+    'proseReadingRateWordsPerSecond',
     'statusLineEnabled',
     'statusLineLeft',
     'statusLineRight',
@@ -1702,6 +1807,8 @@ const LIVE_READ_SETTINGS = new Set([
     'sfxVolume',
     'sfxPack',
     'configScope',
+    'mouseCapture',
+    'wheelScrollLines',
 ]);
 /**
  * Re-read the rows whose displayed value is not simply what was picked.
@@ -1771,6 +1878,36 @@ export const settingsCommand = {
                 ? 'verbosity'
                 : sub;
         const onSettingChange = async (setting, value) => {
+            if (setting === 'permissionProfile' || setting.startsWith('toolPermission_')
+                || ['sandboxEnabled', 'sandboxBackend', 'sandboxRequireOsEnforcement'].includes(setting)) {
+                const config = ctx.config.get();
+                let next;
+                if (setting === 'permissionProfile')
+                    next = { ...config, permissionProfile: value };
+                else if (setting.startsWith('toolPermission_')) {
+                    const cap = setting.slice('toolPermission_'.length);
+                    if (!PERMISSION_CAPABILITIES.includes(cap) || !['true', 'false'].includes(value))
+                        throw new Error('Invalid tool permission');
+                    next = { ...config, toolPermissions: { ...config.toolPermissions, [cap]: value === 'true' } };
+                }
+                else {
+                    if (setting === 'sandboxBackend') {
+                        if (!['auto', 'none', 'seatbelt', 'bubblewrap', 'windows-job'].includes(value))
+                            throw new Error(`Unknown sandbox backend: ${value}`);
+                        next = { ...config, sandbox: { ...config.sandbox, backend: value } };
+                    }
+                    else {
+                        if (!['true', 'false'].includes(value))
+                            throw new Error('Invalid sandbox toggle');
+                        const key = setting === 'sandboxEnabled' ? 'enabled' : 'requireOsEnforcement';
+                        next = { ...config, sandbox: { ...config.sandbox, [key]: value === 'true' } };
+                    }
+                }
+                const notice = await activatePermissionConfig(next, ctx);
+                await refreshAllRowDisplays(categories, ctx);
+                ctx.addMessage({ role: 'system', content: notice });
+                return;
+            }
             if (setting === 'workflowsEnabled' && value === 'false') {
                 await shutdownAndClearWorkflowRegistry(5000);
             }
@@ -1801,6 +1938,15 @@ export const settingsCommand = {
             else if (setting !== 'clearSessionConfig' && !LIVE_READ_SETTINGS.has(setting)) {
                 ctx.reloadAgent();
             }
+            if (setting === 'mouseCapture' || setting === 'wheelScrollLines') {
+                const applied = ctx.zmux?.setTerminalInteraction?.(resolveTerminalInteractionSettings(ctx.config.get().terminalInteraction)) === true;
+                if (!applied)
+                    ctx.addMessage({
+                        role: 'system',
+                        content: 'Terminal interaction saved for the next compatible native renderer launch; not applied to this renderer.',
+                        metadata: { ephemeral: true },
+                    });
+            }
         };
         /**
          * One entry point for the settings surface, so the color picker can hand the

package/dist/agent/commands/setup.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from './types.js';
+export declare const setupCommand: Command;

package/dist/agent/commands/setup.js

@@ -0,0 +1,78 @@
+import { completeSetup, formatSetupReport } from '../../onboarding/setup.js';
+let activeSetup = null;
+async function startSetup(ctx, checkAgent) {
+    if (activeSetup) {
+        ctx.addMessage({ role: 'system', content: 'Setup is already running. Use /setup cancel to stop it.' });
+        return;
+    }
+    if (ctx.getMode?.() === 'plan') {
+        ctx.addMessage({ role: 'system', content: 'Setup can install tools and create a sample workspace. Use /exit-mode to leave Plan mode, then run /setup.' });
+        return;
+    }
+    const abort = new AbortController();
+    activeSetup = abort;
+    try {
+        const options = {
+            checkAgent, config: ctx.config, cwd: ctx.shell.getCwd(), signal: abort.signal,
+            onProgress: (content) => ctx.addMessage({ role: 'system', content }),
+        };
+        ctx.addMessage({ role: 'system', content: 'Setting up ZTC. Use /setup cancel to stop; completed steps can be resumed.' });
+        const report = await completeSetup(options);
+        ctx.addMessage({ role: 'system', content: formatSetupReport(report) });
+    }
+    catch {
+        ctx.addMessage({ role: 'system', content: abort.signal.aborted
+                ? 'ZTC setup cancelled. Completed steps were preserved; run /setup to resume.'
+                : 'ZTC setup could not complete. Check /doctor and the previous setup checks, then run /setup again.' });
+    }
+    finally {
+        if (activeSetup === abort)
+            activeSetup = null;
+    }
+}
+export const setupCommand = {
+    name: 'setup',
+    description: 'Set up and verify the environment, account and sample workspace',
+    usage: '[--check-agent|cancel]',
+    agentRunnable: false,
+    handler: (args, ctx) => {
+        if (ctx.commandOrigin === 'agent') {
+            ctx.addMessage({ role: 'system', content: 'Setup requires the user to type /setup and confirm its primary action.' });
+            return;
+        }
+        if (args.length === 1 && args[0] === 'cancel') {
+            activeSetup?.abort();
+            ctx.addMessage({ role: 'system', content: activeSetup ? 'Stopping setup…' : 'No setup is running. Use Esc to close an unconfirmed setup prompt.' });
+            return;
+        }
+        const checkAgent = args.length === 1 && args[0] === '--check-agent';
+        if (args.length && !checkAgent) {
+            ctx.addMessage({ role: 'system', content: 'Usage: /setup [--check-agent|cancel]' });
+            return;
+        }
+        if (activeSetup) {
+            ctx.addMessage({ role: 'system', content: 'Setup is already running. Use /setup cancel to stop it.' });
+            return;
+        }
+        ctx.addMessage({ role: 'system', content: 'Setup verifies Node, shell, GitHub auth and common tools; installs missing Git/ripgrep through a supported package manager; preserves current account/model defaults; creates a reusable sample; and checks shell health without spending model quota.' + (checkAgent ? ' You also requested one isolated model health request (at most 64 output tokens); it may use paid quota.' : '') });
+        let submitted = false;
+        const confirm = async (input) => {
+            if (submitted)
+                return;
+            submitted = true;
+            if (input === null)
+                return;
+            if (input.trim()) {
+                ctx.addMessage({ role: 'system', content: 'Setup was not started. Run /setup and press Enter to use its primary action, or Esc to cancel.' });
+                return;
+            }
+            await startSetup(ctx, checkAgent);
+        };
+        if (ctx.prompt.showPrompt) {
+            ctx.prompt.showPrompt({ title: 'Set up ZTC', question: checkAgent ? 'Enter to set up and use model quota · Esc to cancel' : 'Enter to set up without model quota · Esc to cancel' }, confirm);
+        }
+        else {
+            ctx.prompt.prompt(checkAgent ? 'Set up ZTC — Enter to set up and use model quota · Esc to cancel' : 'Set up ZTC — Enter to set up without model quota · Esc to cancel', confirm, { allowEmptySubmit: true });
+        }
+    },
+};

package/dist/agent/commands/share.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from './types.js';
+export declare const shareCommand: Command;

package/dist/agent/commands/share.js

@@ -0,0 +1,64 @@
+const USAGE = '/share [create [label] [--ttl seconds]|list|revoke <ID|all>|owner]';
+export const shareCommand = {
+    name: 'share',
+    description: 'Create, inspect or revoke read-only browser access to this session',
+    usage: USAGE,
+    handler: async (args, ctx) => {
+        const say = (content) => ctx.addMessage({ role: 'system', content });
+        if (ctx.commandOrigin === 'agent') {
+            say('Only you can manage terminal sharing.');
+            return;
+        }
+        const action = args[0] ?? 'list';
+        try {
+            const mirror = ctx.mirror;
+            if (!mirror?.sharing)
+                throw new Error('Session sharing requires the native ZTC mirror.');
+            if (!mirror.isRunning())
+                throw new Error('Start the mirror with /mirror start first.');
+            if (action === 'create') {
+                const labelParts = [];
+                let ttl = 3600;
+                let ttlSeen = false;
+                for (let i = 1; i < args.length; i++) {
+                    if (args[i] === '--ttl') {
+                        if (ttlSeen || !/^\d+$/.test(args[i + 1] ?? ''))
+                            throw new Error('TTL must be an integer from 1 to 43200 seconds.');
+                        ttlSeen = true;
+                        ttl = Number(args[++i]);
+                    }
+                    else {
+                        if (args[i].startsWith('--'))
+                            throw new Error(`Unknown sharing option: ${args[i]}`);
+                        labelParts.push(args[i]);
+                    }
+                }
+                if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > 43200)
+                    throw new Error('TTL must be an integer from 1 to 43200 seconds.');
+                const share = mirror.sharing.create(labelParts.join(' ') || 'Observer', ttl);
+                say(`Read-only share created: ${share.label}\nID: ${share.id}\nExpires: ${new Date(share.expiresAtMs).toISOString()}\n${share.url}\nThis link shows terminal activity and output. It cannot control the session.\nRemote viewers need an authenticated SSH tunnel to this loopback mirror. Revoke: /share revoke ${share.id}\nExisting browser controllers may need /share owner after sharing enables authentication.`);
+                return;
+            }
+            if (action === 'list' && args.length <= 1) {
+                const shares = mirror.sharing.list();
+                say(shares.length === 0 ? 'No observation shares.' : ['Observation shares:', ...shares.map(share => `${share.id} · ${share.label} · ${share.revoked ? 'revoked' : share.expiresAtMs <= Date.now() ? 'expired' : 'active'} · ${new Date(share.expiresAtMs).toISOString()}`)].join('\n'));
+                return;
+            }
+            if (action === 'revoke' && args.length === 2) {
+                const ids = args[1] === 'all' ? mirror.sharing.list().filter(share => !share.revoked).map(share => share.id) : [args[1]];
+                const count = ids.filter(id => mirror.sharing.revoke(id)).length;
+                say(count ? `Revoked ${count} observation share${count === 1 ? '' : 's'}. The terminal session keeps running.` : 'No active observation share matches that ID.');
+                return;
+            }
+            if (action === 'owner' && args.length === 1) {
+                await mirror.open();
+                say('Opened your controller view. Keep its credential private.');
+                return;
+            }
+            throw new Error(USAGE);
+        }
+        catch (error) {
+            say(`Sharing: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};

package/dist/agent/commands/status.js

@@ -8,9 +8,10 @@ import { isLocalSubscription } from './provider_choices.js';
 export const statusCommand = {
     name: 'status',
     description: 'Show current status',
+    usage: '/status [--verbose]',
     agentRunnable: true,
     category: 'core',
-    handler: (_, ctx) => {
+    handler: (args, ctx) => {
         const isAuthenticated = ctx.config.isAuthenticated?.() ?? false;
         const config = ctx.config.get();
         const provider = ctx.config.getProvider();
@@ -46,11 +47,22 @@ export const statusCommand = {
             routeError = error instanceof Error ? error.message : String(error);
         }
         const execution = ctx.getExecutionContext?.();
+        const environment = ctx.getEnvironment?.();
+        const executionLines = !execution ? [] : args.includes('--verbose')
+            ? [describeExecutionContext(execution)]
+            : [
+                `  Mode: ${execution.mode}`,
+                `  Working directory: ${execution.cwd}`,
+                `  Output cap: ${execution.maxTokens ?? 'provider default'}`,
+                `  Tools: ${execution.tools.length} registered; mux ${execution.mux ? 'connected' : 'off'}`,
+                '  Full execution details: /status --verbose',
+            ];
         ctx.addMessage({
             role: 'system',
             content: [
                 'Status:',
-                ...(execution ? [describeExecutionContext(execution)] : []),
+                ...(environment ? [`  Environment: ${environment.name} (${environment.status}); /environment status`] : []),
+                ...executionLines,
                 `  API Key: ${hasKey ? '✓ configured' : '✗ not set (use /config key <key>)'}`,
                 `  Platform Auth: ${isAuthenticated ? '✓ configured' : '✗ not set'}`,
                 `  Provider: ${provider}`,