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

package/dist/app/activity.js

@@ -1,33 +1,84 @@
 import { AGENT_STATUS_LABELS } from '../types.js';
 import { getToolVerb } from '../utils/tool_verbs.js';
+import { parseEvidenceSnapshot } from '../agent/runtime/evidence.js';
+import { parseTaskHandoffProjection } from '../session_handoff_contract.js';
+import { parseToolProgress } from '../tool_progress.js';
 export function applyAgentEventToState(previous, event) {
     // Preserve startedAt across mid-run re-entries (e.g. after a tool round-trip)
     // so the activity-line elapsed timer has a stable origin.
     const startedAt = previous.startedAt ?? new Date();
     switch (event.type) {
+        case 'task_handoff': {
+            if (!event.sessionId)
+                return previous;
+            const projection = event.projection === null ? null : parseTaskHandoffProjection(event.projection);
+            if (event.projection !== null && !projection)
+                return previous;
+            const retained = previous.taskHandoff;
+            if (projection && retained?.sessionId === event.sessionId
+                && retained.projection?.snapshot.source.sessionId === projection.snapshot.source.sessionId
+                && retained.projection.snapshot.revision >= projection.snapshot.revision)
+                return previous;
+            return { ...previous, taskHandoff: { sessionId: event.sessionId, projection } };
+        }
+        case 'evidence': {
+            const snapshot = parseEvidenceSnapshot(event.snapshot);
+            if (!snapshot || !event.sessionId || (previous.evidence?.sessionId === event.sessionId
+                && previous.evidence.snapshot.revision >= snapshot.revision))
+                return previous;
+            return { ...previous, evidence: { sessionId: event.sessionId, snapshot } };
+        }
+        case 'command_wait':
+            return { ...previous, status: 'tool_use', startedAt, waiting: event.waiting, requestRetry: undefined, error: undefined };
+        case 'command_wait_end':
+            return previous.waiting?.toolCallId === event.toolCallId ? { ...previous, waiting: undefined } : previous;
         case 'thinking_start':
-            return { ...previous, status: 'thinking', currentTool: undefined, startedAt, error: undefined };
-        case 'tool_start':
-            return { ...previous, status: 'tool_use', currentTool: event.tool, startedAt, error: undefined };
+            return { ...previous, status: 'thinking', currentTool: undefined, startedAt, error: undefined, requestRetry: undefined, waiting: undefined, toolProgress: undefined };
+        case 'api_retry':
+            return { ...previous, status: 'thinking', currentTool: undefined, startedAt, error: undefined,
+                waiting: undefined, toolProgress: undefined, requestRetry: { phase: event.phase ?? 'retry', attempt: event.attempt, delay: event.delay, ...(event.rateLimited ? { rateLimited: true } : {}) } };
+        case 'tool_start': {
+            const toolProgress = parseToolProgress({ toolCallId: event.toolCallId, tool: event.tool,
+                progress: { startedAt: Date.now(), outputBytes: 0, outputLines: 0, latestLine: '' } });
+            return { ...previous, status: 'tool_use', currentTool: event.tool, startedAt, error: undefined, requestRetry: undefined, waiting: undefined,
+                toolProgress: toolProgress ?? undefined };
+        }
+        case 'tool_progress': {
+            const observed = parseToolProgress({ toolCallId: event.toolCallId, tool: event.tool, progress: event.progress });
+            const owned = previous.toolProgress;
+            if (!observed || previous.status !== 'tool_use' || !owned
+                || owned.toolCallId !== observed.toolCallId || owned.tool !== observed.tool
+                || observed.progress.outputBytes < owned.progress.outputBytes
+                || observed.progress.outputLines < owned.progress.outputLines
+                || (owned.progress.lastOutputAt !== undefined
+                    && (observed.progress.lastOutputAt === undefined || observed.progress.lastOutputAt < owned.progress.lastOutputAt)))
+                return previous;
+            return { ...previous, toolProgress: observed };
+        }
+        case 'tool_end':
+            return previous.toolProgress?.toolCallId === event.toolCallId
+                ? { ...previous, toolProgress: undefined } : previous;
         case 'stream_start':
         case 'stream_end':
-            return { ...previous, status: 'streaming', startedAt, error: undefined };
+            return { ...previous, status: 'streaming', startedAt, error: undefined, requestRetry: undefined, waiting: undefined, toolProgress: undefined };
         case 'reasoning_delta':
-            if (previous.status === 'thinking' && previous.startedAt && previous.error === undefined) {
+            if (previous.status === 'thinking' && previous.startedAt && previous.error === undefined && !previous.requestRetry && !previous.waiting && !previous.toolProgress) {
                 return previous;
             }
-            return { ...previous, status: 'thinking', startedAt, error: undefined };
+            return { ...previous, status: 'thinking', startedAt, error: undefined, requestRetry: undefined, waiting: undefined, toolProgress: undefined };
         case 'stream_delta':
             // Hot path: one event per token. Skip the allocation when the status is
             // already streaming so subscribers don't fire per-token no-op updates.
-            if (previous.status === 'streaming' && previous.startedAt && previous.error === undefined) {
+            if (previous.status === 'streaming' && previous.startedAt && previous.error === undefined && !previous.waiting && !previous.toolProgress) {
                 return previous;
             }
-            return { ...previous, status: 'streaming', startedAt, error: undefined };
+            return { ...previous, status: 'streaming', startedAt, error: undefined, requestRetry: undefined, waiting: undefined, toolProgress: undefined };
         case 'tool_error':
-            return { ...previous, status: 'error', currentTool: event.tool, error: event.error };
+            if (previous.toolProgress && previous.toolProgress.toolCallId !== event.toolCallId)
+                return previous;
+            return { ...previous, status: 'error', currentTool: event.tool, error: event.error, requestRetry: undefined, waiting: undefined, toolProgress: undefined };
         case 'error':
-            return { ...previous, status: 'error', error: event.error };
+            return { ...previous, status: 'error', error: event.error, requestRetry: undefined, waiting: undefined, toolProgress: undefined };
         default:
             return previous;
     }
@@ -37,14 +88,19 @@ export function buildActivityDisplayState(state, thinkingLabel) {
         case 'thinking':
             return {
                 wireStatus: 'thinking',
-                label: thinkingLabel,
+                label: state.requestRetry ? retryActivityLabel(state.requestRetry) : thinkingLabel,
+                ...(state.requestRetry?.rateLimited ? { verb: retryActivityLabel(state.requestRetry) } : {}),
             };
         case 'tool_use': {
+            if (state.waiting)
+                return { wireStatus: 'tool_executing', verb: 'Waiting for command', label: 'Waiting for command', waiting: state.waiting,
+                    ...(state.toolProgress ? { toolProgress: state.toolProgress } : {}) };
             const verb = state.currentTool ? getToolVerb(state.currentTool) : 'Running tool';
             return {
                 wireStatus: 'tool_executing',
                 verb,
                 label: verb,
+                ...(state.toolProgress ? { toolProgress: state.toolProgress } : {}),
             };
         }
         case 'streaming':
@@ -74,8 +130,10 @@ export function buildActivityDisplayState(state, thinkingLabel) {
 export function getAgentActionLabel(state) {
     switch (state.status) {
         case 'thinking':
-            return AGENT_STATUS_LABELS.thinking;
+            return state.requestRetry ? retryActivityLabel(state.requestRetry) : AGENT_STATUS_LABELS.thinking;
         case 'tool_use':
+            if (state.waiting)
+                return 'Waiting for command';
             return getToolVerb(state.currentTool || 'tool');
         case 'streaming':
             return `${AGENT_STATUS_LABELS.streaming} response`;
@@ -83,6 +141,17 @@ export function getAgentActionLabel(state) {
             return null;
     }
 }
+function retryActivityLabel(retry) {
+    if (retry.rateLimited)
+        return `Rate-limited, waiting ${Math.ceil(retry.delay / 1000)}s`;
+    return retry.phase === 'recovery' ? 'Waiting for LLM endpoint' : 'Retrying LLM request';
+}
+export function formatApiRetryNotice(event) {
+    const attempts = event.phase === 'recovery'
+        ? `recovery attempt ${event.attempt - event.maxAttempts + 1}; current task retained`
+        : `attempt ${event.attempt}/${event.maxAttempts}`;
+    return `⚠️ ${event.reason}. Retrying in ${event.delay / 1000}s... (${attempts})`;
+}
 /**
  * Placeholder text for the composer while the agent is active.
  * Shared by every renderer so Ink and Ratatui show the same prompt.

package/dist/app/agent_runner.d.ts

@@ -8,9 +8,14 @@
  */
 import { Agent } from '../agent/index.js';
 import type { AgentEvent } from '../types.js';
+import type { ModelUsageObserver } from '../types.js';
 import { type AgentFactoryOptions } from '../agent/factory.js';
 import type { Message } from '../types.js';
+import type { ToolCheckpointHandler } from '../agent/runtime/tool_checkpoints.js';
+import type { SteeringAdmissionCheckpointHandler } from '../agent/agent.js';
 interface AgentRunnerOptions extends Partial<AgentFactoryOptions> {
+    /** Profile selection may wait for sign-in while retaining its session. */
+    allowUnavailableRouterAuth?: boolean;
     cwdProvider?: () => string;
 }
 /**
@@ -52,7 +57,7 @@ export declare class AgentRunLifecycle {
      *                  The callback should contain the renderer-specific event switch.
      * @returns The agent response and whether it was cancelled
      */
-    run(agent: Agent, messages: Message[], onEvent: (event: AgentEvent) => void, takeSteering?: () => Message[]): Promise<AgentRunResult>;
+    run(agent: Agent, messages: Message[], onEvent: (event: AgentEvent) => void, takeSteering?: () => Message[], toolCheckpoint?: ToolCheckpointHandler, steeringAdmission?: SteeringAdmissionCheckpointHandler, onUsage?: ModelUsageObserver): Promise<AgentRunResult>;
     /**
      * Cancel the currently active run (if any).
      * Aborts the in-flight API call and stops event delivery.

package/dist/app/agent_runner.js

@@ -9,12 +9,14 @@
 import { AgentError } from '../agent/index.js';
 import { createAgentFromConfig, resolveAgentBackendFromConfig } from '../agent/factory.js';
 import { configStore } from '../config.js';
+import { RouterConfigurationError } from '../router_auth.js';
 import { setBackgroundRegistry, getBackgroundRegistry, clearBackgroundRegistry } from '../agent/tools/index.js';
 import { BackgroundTaskRegistry } from '../agent/background_registry.js';
 import { InProcessWorkerExecutor, setWorkerExecutor, clearWorkerExecutor } from '../worker/index.js';
 import { configureWorkflowRegistry, shutdownAndClearWorkflowRegistry } from '../workflows/registry_handle.js';
 import { workflowsEnabled } from '../workflows/config.js';
-import { isCodexAppServerProvider } from '../agent/backends/provider_ids.js';
+import { isCodexAppServerProvider, normalizeProviderId } from '../agent/backends/provider_ids.js';
+import { admitPermissionProvider, projectPermissionPolicy, resolvePermissionProfile } from '../config/permissions.js';
 /**
  * Ensure the BackgroundTaskRegistry tracks the current shared executor.
  * Reuses the existing registry if one is already set — background tasks
@@ -40,11 +42,6 @@ function configureWorkflowRegistryContext(executor, cwdProvider, execution) {
     };
     configureWorkflowRegistry(registryOptions);
 }
-function resolveWorkerPermissionProfile() {
-    const config = configStore.get();
-    const id = config.permissionProfile;
-    return id ? config.permissionProfiles?.[id] : undefined;
-}
 function providerSupportsWorkflowWorkers(provider) {
     return !isCodexAppServerProvider(provider);
 }
@@ -58,23 +55,38 @@ function providerSupportsWorkflowWorkers(provider) {
  * @returns Agent instance or null if no usable credentials are configured
  */
 export function createAgentWithConfig(overrides = {}) {
-    const { cwdProvider = () => process.cwd(), ...agentOverrides } = overrides;
+    const { cwdProvider = () => process.cwd(), allowUnavailableRouterAuth = false, ...agentOverrides } = overrides;
     const config = configStore.get();
+    const permissionProfile = resolvePermissionProfile(config);
+    admitPermissionProvider(permissionProfile, projectPermissionPolicy(config), normalizeProviderId(agentOverrides.provider ?? config.provider ?? configStore.getProvider()));
     // provider/model are intentionally NOT passed here: the config snapshot
     // already carries the resolved values (get() folds in CLI/session
     // overrides), and passing them as renderer intent would make the
     // repo-scoped override (<cwd>/.ztc/config.json) unreachable. Renderer
     // overrides still flow via agentOverrides and win.
-    const resolvedBackend = resolveAgentBackendFromConfig({
-        config,
-        apiKey: overrides.apiKey,
-        openaiCompatibleBaseUrl: configStore.getOpenAICompatibleBaseUrl(),
-        emulationId: configStore.getEmulationId(),
-        cwd: cwdProvider(),
-        ...agentOverrides,
-    });
+    let resolvedBackend;
+    let deferredRouterAuth = false;
+    try {
+        resolvedBackend = resolveAgentBackendFromConfig({
+            config,
+            apiKey: overrides.apiKey,
+            // Backend resolution validates the endpoint only when that provider is
+            // selected; unrelated saved settings must not block another provider.
+            openaiCompatibleBaseUrl: configStore.getOpenAICompatibleSettings().baseUrl,
+            emulationId: configStore.getEmulationId(),
+            cwd: cwdProvider(),
+            ...agentOverrides,
+        });
+    }
+    catch (error) {
+        if (!allowUnavailableRouterAuth || !(error instanceof RouterConfigurationError) || !error.needsSignIn)
+            throw error;
+        resolvedBackend = null;
+        deferredRouterAuth = true;
+    }
     // Set up shared WorkerExecutor so delegate/background/batch can access the API
     if (resolvedBackend) {
+        admitPermissionProvider(permissionProfile, projectPermissionPolicy(config), resolvedBackend.provider);
         const executor = new InProcessWorkerExecutor({
             provider: resolvedBackend.provider,
             apiKey: resolvedBackend.apiKey,
@@ -86,7 +98,8 @@ export function createAgentWithConfig(overrides = {}) {
             approvalRequester: overrides.hookApprovalRequester,
             backend: resolvedBackend.backend,
             toolPermissions: config.toolPermissions,
-            permissionProfile: resolveWorkerPermissionProfile(),
+            permissionProfile,
+            commandPolicy: { profileId: config.permissionProfile ?? 'trusted', profile: permissionProfile, sandbox: config.sandbox },
         });
         setWorkerExecutor(executor);
         ensureBackgroundRegistry(executor);
@@ -108,10 +121,12 @@ export function createAgentWithConfig(overrides = {}) {
         clearBackgroundRegistry();
         void shutdownAndClearWorkflowRegistry(5000);
     }
+    if (deferredRouterAuth)
+        return null;
     return createAgentFromConfig({
         config,
         apiKey: overrides.apiKey,
-        openaiCompatibleBaseUrl: configStore.getOpenAICompatibleBaseUrl(),
+        openaiCompatibleBaseUrl: configStore.getOpenAICompatibleSettings().baseUrl,
         emulationId: configStore.getEmulationId(),
         cwd: cwdProvider(),
         ...agentOverrides,
@@ -140,7 +155,7 @@ export class AgentRunLifecycle {
      *                  The callback should contain the renderer-specific event switch.
      * @returns The agent response and whether it was cancelled
      */
-    async run(agent, messages, onEvent, takeSteering) {
+    async run(agent, messages, onEvent, takeSteering, toolCheckpoint, steeringAdmission, onUsage) {
         // Abort previous run if still in flight to avoid concurrent API calls
         if (this.abortController) {
             this.abortController.abort();
@@ -160,7 +175,7 @@ export class AgentRunLifecycle {
             // iterates. Renderers own their controller state and persist the visible
             // final turn themselves, so keep those API-only mutations off the live
             // transcript array.
-            const response = await agent.run(messages.slice(), controller.signal, takeSteering);
+            const response = await agent.run(messages.slice(), controller.signal, takeSteering, toolCheckpoint, steeringAdmission, onUsage);
             const cancelled = !isActive();
             return { response: cancelled ? null : response, cancelled };
         }

package/dist/app/command_context.js

@@ -1,10 +1,5 @@
-/**
- * CommandContext Factory
- *
- * Shared helpers for building CommandContext objects used by command handlers.
- * Eliminates duplication between TUI (cli_ratatui.ts) and headless (headless.ts) renderers.
- */
-import { listModels } from '../utils/models.js';
+import { discoverRouterCatalog, readRouterCatalog, routerModelIds, routerCatalogScope } from '../utils/router_catalog.js';
+import { loadModelCatalog } from './model_catalog_cache.js';
 import { getSkills } from '../skills/registry.js';
 import { runShellCommand } from '../utils/shell.js';
 import { configStore } from '../config.js';
@@ -33,6 +28,58 @@ export function routeUserInput(text) {
         const parts = text.slice(1).trimEnd().split(/\s+/);
         const cmd = parts[0];
         if (!cmd.includes('/')) {
+            if (cmd === 'job' && parts[1] === 'pin') {
+                // Only parse pin options. The command after -- belongs to the shell and
+                // must retain its exact quotes, argument spaces and metacharacters.
+                const tokens = [];
+                let token = '';
+                let quote = '';
+                let braces = 0;
+                let escaped = false;
+                const source = text.slice(1).trimEnd();
+                for (let i = 0; i < source.length; i++) {
+                    const char = source[i];
+                    if (!quote && !braces && /\s/.test(char)) {
+                        if (token) {
+                            tokens.push(token);
+                            if (token === '--') {
+                                tokens.push(source.slice(i + 1));
+                                return { type: 'command', cmd, args: tokens.slice(1) };
+                            }
+                            token = '';
+                        }
+                        continue;
+                    }
+                    token += char;
+                    if (escaped) {
+                        escaped = false;
+                        continue;
+                    }
+                    if (quote && char === '\\') {
+                        escaped = true;
+                        continue;
+                    }
+                    if (quote) {
+                        if (char === quote)
+                            quote = '';
+                    }
+                    else if (char === '"' || char === "'")
+                        quote = char;
+                    else if (char === '{')
+                        braces++;
+                    else if (char === '}')
+                        braces = Math.max(0, braces - 1);
+                }
+                if (token)
+                    tokens.push(token);
+                return { type: 'command', cmd, args: tokens.slice(1) };
+            }
+            if (cmd.toLowerCase() === 'fork' || cmd.toLowerCase() === 'side') {
+                // A fork's body is authored task data, not tokenized command options.
+                // Remove exactly the command separator and retain the remaining bytes.
+                const task = text.slice(cmd.length + 2);
+                return { type: 'command', cmd, args: task.length ? [task] : [] };
+            }
             return { type: 'command', cmd, args: parts.slice(1) };
         }
     }
@@ -43,19 +90,66 @@ export function routeUserInput(text) {
  * The models.list implementation is identical across all renderers.
  */
 export function buildModelsController(config) {
+    const listRouter = async (provider, options) => {
+        options?.signal?.throwIfAborted();
+        const connection = config.getRouterCatalogConnection?.();
+        const preview = connection && readRouterCatalog(connection);
+        const age = preview ? Date.now() - preview.fetchedAt : Infinity;
+        if (!options?.refresh && preview && !preview.authRequired && age >= 0 && age < 24 * 60 * 60 * 1000) {
+            // Scoped disk rows preview choices; a shared background refresh owns
+            // qualification and adoption. Editing never waits on a stale catalog.
+            if (age >= 30_000)
+                void buildModelsController(config).catalog(options?.signal, { refresh: true }).catch(() => { });
+            return routerModelIds(preview, provider);
+        }
+        return routerModelIds(await buildModelsController(config).catalog(options?.signal, options), provider);
+    };
     return {
+        catalog: async (signal, options) => {
+            try {
+                const connection = config.getRouterCatalogConnection?.();
+                if (!connection)
+                    throw new Error('Router discovery requires a Router login. Run ztc auth login.');
+                const scope = routerCatalogScope(connection);
+                signal?.throwIfAborted();
+                const previous = readRouterCatalog(connection);
+                const age = previous === undefined ? Infinity : Date.now() - previous.fetchedAt;
+                // Startup may reuse this process's live discovery, but always refreshes
+                // disk previews. An explicit refresh still forces a new HTTP request.
+                const reuse = !options?.refresh || options.refresh === 'startup' && !!readRouterCatalog(connection, { liveOnly: true });
+                const catalog = reuse && previous && !previous.authRequired && age >= 0 && age < 30_000
+                    ? previous : await discoverRouterCatalog(connection, signal);
+                signal?.throwIfAborted();
+                const active = config.getRouterCatalogConnection?.();
+                if (!active || routerCatalogScope(active) !== scope)
+                    throw new Error('Router discovery context changed. Retry model discovery.');
+                await config.adoptRouterCatalog?.(catalog);
+                return catalog;
+            }
+            catch (error) {
+                const cached = config.getRouterCatalog?.();
+                if (!signal?.aborted && cached)
+                    return { ...cached, ...(error instanceof Error && /authentication|expired|login|origin/i.test(error.message) ? { authRequired: true } : {}) };
+                throw error;
+            }
+        },
         list: async (provider, options) => {
+            if ((options?.authMode ?? config.getAuthMode?.()) === 'zrouter') {
+                return listRouter(provider ?? config.getProvider(), options);
+            }
             const llm = config.resolveLLMBackendConfig({ provider,
                 config: options?.authMode ? { ...config.get(), authMode: options.authMode } : undefined });
-            // Preserve discovery failures so callers can distinguish an unavailable
-            // catalog from a successful provider response with zero supported models.
-            return listModels({
+            if (llm.useProxy) {
+                return listRouter(llm.provider, options);
+            }
+            return loadModelCatalog({
                 signal: options?.signal,
                 provider: llm.provider,
                 apiKey: llm.apiKey,
                 baseUrl: llm.provider === 'openai_compatible' ? llm.compatBaseUrl : undefined,
                 proxyUrl: llm.useProxy ? llm.proxyUrl : undefined,
                 authToken: llm.useProxy ? llm.authToken : undefined,
+                workspaceId: llm.useProxy ? config.getRouterCatalogConnection?.()?.workspaceId : undefined,
                 codexAppServerCommand: llm.codexAppServerCommand,
                 codexAppServerArgs: llm.codexAppServerArgs,
                 codexHome: llm.codexHome,
@@ -178,6 +272,7 @@ export function buildAutoSelectWidgets() {
 /** Session controls do not execute the plan or change project files. */
 const PLAN_MODE_SESSION_COMMANDS = new Set([
     'accounts',
+    'attention',
     'auth',
     'config',
     'context',
@@ -192,6 +287,7 @@ const PLAN_MODE_SESSION_COMMANDS = new Set([
     'models',
     'permissions',
     'profile',
+    'rewind',
     'settings',
     'shortcuts',
     'skills',

package/dist/app/controller.d.ts

@@ -7,11 +7,12 @@
  * The state is a single immutable object that gets updated via dispatch().
  * Subscribers are notified whenever the state changes.
  */
-import type { Message, AgentState, InputMode, MessageInput, QueueEntry, DeliveryIntent, TodoStatus } from '../types.js';
+import { type Message, type AgentState, type InputMode, type CanonicalInputMode, type MessageInput, type QueueEntry, type DeliveryIntent, type TodoStatus } from '../types.js';
 import type { InputState } from '../ui/core/input_state.js';
 import type { ContextStatus } from '../utils/context.js';
 import type { Skill } from '../skills/types.js';
 import type { AgentMode } from './modes.js';
+import type { WorkspaceCollisionSnapshot } from '../workspace_collision.js';
 export type { TodoStatus } from '../types.js';
 export interface TodoItem {
     /** Unique identifier for the todo */
@@ -33,6 +34,7 @@ export declare const MAX_QUEUE = 10;
  */
 export declare const DEFAULT_TOAST_MS = 5000;
 export interface AppState {
+    workspaceCollision: WorkspaceCollisionSnapshot | null;
     /** Chat messages */
     messages: Message[];
     /** Current agent state (thinking, streaming, etc.) */
@@ -41,8 +43,8 @@ export interface AppState {
     sessionId: string;
     /** Current input state (segments, cursor, history) */
     inputState: InputState;
-    /** Input mode (queue or normal) */
-    inputMode: InputMode;
+    /** Busy Enter mode; legacy values are normalized at dispatch. */
+    inputMode: CanonicalInputMode;
     /** Toast notification message */
     toast: string | null;
     /** Spinner label when agent is working */
@@ -89,10 +91,13 @@ export interface AppState {
     mode: AgentMode;
     /** Path to current plan file (when in plan mode) */
     planFile: string | null;
-    /** Outbound message queue. Single-writer: ENQUEUE / DEQUEUE / REMOVE / CLEAR actions only. */
+    /** Outbound message queue, updated only through canonical queue actions. */
     queue: QueueEntry[];
 }
 export type AppAction = {
+    type: 'SET_WORKSPACE_COLLISION';
+    snapshot: WorkspaceCollisionSnapshot | null;
+} | {
     type: 'ADD_MESSAGE';
     message: Omit<Message, 'id' | 'timestamp'>;
 } | {
@@ -194,6 +199,9 @@ export type AppAction = {
     type: 'UPDATE_QUEUE_ENTRY';
     id: string;
     text: string;
+} | {
+    type: 'REORDER_QUEUE';
+    ids: string[];
 } | {
     type: 'CLEAR_QUEUE';
 };
@@ -228,6 +236,7 @@ export declare class AppController {
     setMessages(messages: Message[]): void;
     clearMessages(): void;
     setAgentState(agentState: AgentState): void;
+    setWorkspaceCollision(snapshot: WorkspaceCollisionSnapshot | null): void;
     setInputState(inputState: InputState): void;
     setInputStateSilent(inputState: InputState): void;
     /**
@@ -287,6 +296,8 @@ export declare class AppController {
     removeQueueEntry(id: string): void;
     /** Rewrite a queued entry's text in place. Returns false when the id is no longer queued. */
     updateQueueEntry(id: string, text: string): boolean;
+    /** Apply only an exact permutation of the currently accepted queue IDs. */
+    reorderQueue(ids: readonly string[]): boolean;
     clearQueue(): void;
     getQueue(): QueueEntry[];
 }

package/dist/app/controller.js

@@ -7,6 +7,7 @@
  * The state is a single immutable object that gets updated via dispatch().
  * Subscribers are notified whenever the state changes.
  */
+import { normalizeInputMode } from '../types.js';
 import { buildTodoIdentity } from './todo_state.js';
 function getActiveTodoKey(todos) {
     const activeIndex = todos.findIndex(todo => todo.status === 'in_progress');
@@ -41,6 +42,7 @@ export const DEFAULT_TOAST_MS = 5000;
 const generateId = () => Math.random().toString(36).slice(2, 11);
 function createInitialState() {
     return {
+        workspaceCollision: null,
         messages: [],
         agentState: { status: 'idle' },
         sessionId: generateId(),
@@ -50,7 +52,7 @@ function createInitialState() {
             history: [],
             historyIdx: -1,
         },
-        inputMode: 'queue',
+        inputMode: 'steer',
         toast: null,
         spinnerLabel: null,
         spinnerFrame: null,
@@ -88,6 +90,8 @@ function isDuplicateAssistantAppend(previous, next) {
 }
 function reducer(state, action) {
     switch (action.type) {
+        case 'SET_WORKSPACE_COLLISION':
+            return { ...state, workspaceCollision: action.snapshot };
         case 'ADD_MESSAGE': {
             const lastMessage = state.messages[state.messages.length - 1];
             if (isDuplicateAssistantAppend(lastMessage, action.message)) {
@@ -142,11 +146,13 @@ function reducer(state, action) {
                 messages: state.messages.filter((msg) => msg.id !== action.id),
             };
         case 'SET_AGENT_STATE':
-            return { ...state, agentState: action.state };
+            return { ...state, agentState: { ...action.state,
+                    taskHandoff: action.state.taskHandoff ?? state.agentState.taskHandoff,
+                    evidence: action.state.evidence ?? state.agentState.evidence } };
         case 'SET_INPUT_STATE':
             return { ...state, inputState: action.state };
         case 'SET_INPUT_MODE':
-            return { ...state, inputMode: action.mode };
+            return { ...state, inputMode: normalizeInputMode(action.mode) };
         case 'SET_TOAST':
             return { ...state, toast: action.message };
         case 'SET_SPINNER':
@@ -234,6 +240,17 @@ function reducer(state, action) {
             queue[index] = { ...current, text: action.text };
             return { ...state, queue };
         }
+        case 'REORDER_QUEUE': {
+            if (action.ids.length !== state.queue.length || new Set(action.ids).size !== action.ids.length)
+                return state;
+            const byId = new Map(state.queue.map(entry => [entry.id, entry]));
+            if (action.ids.some(id => !byId.has(id)))
+                return state;
+            const queue = action.ids.map(id => byId.get(id));
+            if (queue.every((entry, index) => entry === state.queue[index]))
+                return state;
+            return { ...state, queue };
+        }
         case 'CLEAR_QUEUE':
             return { ...state, queue: [] };
         default:
@@ -309,6 +326,9 @@ export class AppController {
     setAgentState(agentState) {
         this.dispatch({ type: 'SET_AGENT_STATE', state: agentState });
     }
+    setWorkspaceCollision(snapshot) {
+        this.dispatch({ type: 'SET_WORKSPACE_COLLISION', snapshot });
+    }
     setInputState(inputState) {
         this.dispatch({ type: 'SET_INPUT_STATE', state: inputState });
     }
@@ -474,6 +494,12 @@ export class AppController {
         this.dispatch({ type: 'UPDATE_QUEUE_ENTRY', id, text });
         return true;
     }
+    /** Apply only an exact permutation of the currently accepted queue IDs. */
+    reorderQueue(ids) {
+        this.dispatch({ type: 'REORDER_QUEUE', ids: [...ids] });
+        return ids.length === this.state.queue.length
+            && this.state.queue.every((entry, index) => entry.id === ids[index]);
+    }
     clearQueue() {
         this.dispatch({ type: 'CLEAR_QUEUE' });
     }

package/dist/app/escape_stop.d.ts

@@ -0,0 +1,11 @@
+/** Global Escape confirms only the same running owner within this window. */
+export declare const ESCAPE_STOP_WINDOW_MS = 2000;
+export interface EscapeStopArm<Owner> {
+    owner: Owner;
+    armedAtMs: number;
+}
+export declare function isEscapeStopArmed<Owner>(arm: EscapeStopArm<Owner> | null, owner: Owner | null, nowMs: number): boolean;
+export declare function advanceEscapeStop<Owner>(arm: EscapeStopArm<Owner> | null, owner: Owner | null, nowMs: number): {
+    confirmed: boolean;
+    arm: EscapeStopArm<Owner> | null;
+};

package/dist/app/escape_stop.js

@@ -0,0 +1,15 @@
+/** Global Escape confirms only the same running owner within this window. */
+export const ESCAPE_STOP_WINDOW_MS = 2000;
+export function isEscapeStopArmed(arm, owner, nowMs) {
+    if (arm === null || owner === null || arm.owner !== owner)
+        return false;
+    const elapsed = nowMs - arm.armedAtMs;
+    return elapsed >= 0 && elapsed <= ESCAPE_STOP_WINDOW_MS;
+}
+export function advanceEscapeStop(arm, owner, nowMs) {
+    if (owner === null)
+        return { confirmed: false, arm: null };
+    if (isEscapeStopArmed(arm, owner, nowMs))
+        return { confirmed: true, arm: null };
+    return { confirmed: false, arm: { owner, armedAtMs: nowMs } };
+}