@dotdrelle/wiki-manager 0.9.3 → 0.11.0

package/src/shell/StartupScreen.tsx

@@ -0,0 +1,212 @@
+/** @jsxImportSource @opentui/solid */
+import { useKeyboard } from '@opentui/solid';
+import { createMemo, createSignal, For } from 'solid-js';
+import { fit } from './textFit';
+
+export type StartupAction =
+  | 'new-conversation'
+  | 'open-workspace'
+  | 'run-workflow'
+  | 'init-workspace';
+
+type StartupItem = {
+  action: StartupAction;
+  label: string;
+  detail: string;
+};
+
+function statusDot(ready: boolean) {
+  return ready ? '●' : '○';
+}
+
+function initWorkspaceItem(detail: string): StartupItem {
+  return { action: 'init-workspace', label: 'Initialize workspace', detail };
+}
+
+export function StartupScreen(props: {
+  version: string;
+  model: string;
+  connectedMcpServers: number;
+  wikiReady: boolean;
+  workspaceName?: string | null;
+  profileName?: string | null;
+  workspaces: string[];
+  hasWorkspace: boolean;
+  width: number;
+  height: number;
+  onSelect: (action: StartupAction, workspaceName?: string) => void;
+  onQuit: () => void;
+}) {
+  const [mode, setMode] = createSignal<'home' | 'workspace-select'>('home');
+  const [selected, setSelected] = createSignal(0);
+  const panelWidth = createMemo(() => Math.max(54, Math.min(86, props.width - 4)));
+  const panelHeight = createMemo(() => Math.max(24, Math.min(32, props.height - 2)));
+  const left = createMemo(() => Math.max(1, Math.floor((props.width - panelWidth()) / 2)));
+  const top = createMemo(() => Math.max(1, Math.floor((props.height - panelHeight()) / 2)));
+
+  const items = createMemo<StartupItem[]>(() => {
+    if (!props.hasWorkspace) {
+      return [initWorkspaceItem('Create and configure the default workspace')];
+    }
+    return [
+      {
+        action: 'new-conversation',
+        label: 'Start a new conversation',
+        detail: props.workspaceName ? `Load ${props.workspaceName} with default .wikirc` : 'Load default .wikirc',
+      },
+      {
+        action: 'open-workspace',
+        label: 'Open workspace',
+        detail: 'Select, load, then start agents and services',
+      },
+      initWorkspaceItem('Create and configure a new workspace'),
+      {
+        action: 'run-workflow',
+        label: 'Run a workflow',
+        detail: 'Switch to Agent mode after loading the workspace',
+      },
+    ];
+  });
+  const workspaceItems = createMemo(() => props.workspaces.map((name) => ({
+    label: name,
+    detail: name === props.workspaceName ? 'default workspace' : 'available workspace',
+  })));
+  const currentLength = createMemo(() => mode() === 'workspace-select' ? workspaceItems().length : items().length);
+
+  const move = (delta: number) => {
+    setSelected((value) => (value + delta + currentLength()) % currentLength());
+  };
+
+  const choose = (index = selected()) => {
+    if (mode() === 'workspace-select') {
+      const item = workspaceItems()[index];
+      if (item) props.onSelect('open-workspace', item.label);
+      return;
+    }
+    const item = items()[index];
+    if (!item) return;
+    if (item.action === 'open-workspace') {
+      setMode('workspace-select');
+      setSelected(0);
+      return;
+    }
+    props.onSelect(item.action);
+  };
+
+  useKeyboard((key: any) => {
+    const keyName = String(key.name ?? '').toLowerCase();
+    const sequence = String(key.sequence ?? '');
+    if ((key.ctrl || key.meta) && keyName === 'c') {
+      props.onQuit();
+      return;
+    }
+    if (keyName === 'escape' && mode() === 'workspace-select') {
+      setMode('home');
+      setSelected(0);
+      return;
+    }
+    if (keyName === 'escape') {
+      props.onQuit();
+      return;
+    }
+    if (keyName === 'up') {
+      move(-1);
+      return;
+    }
+    if (keyName === 'down') {
+      move(1);
+      return;
+    }
+    if (keyName === 'return' || keyName === 'enter') {
+      choose();
+      return;
+    }
+    const numeric = Number.parseInt(sequence, 10);
+    if (Number.isInteger(numeric) && numeric >= 1 && numeric <= currentLength()) {
+      choose(numeric - 1);
+    }
+  });
+
+  const status = createMemo(() => {
+    if (!props.hasWorkspace) return 'Setup needed';
+    return props.wikiReady ? 'Ready' : 'Default .wikirc missing';
+  });
+
+  const subtitle = createMemo(() => {
+    const workspace = props.workspaceName ?? 'no workspace';
+    const profile = props.profileName ?? 'default';
+    return `${workspace} / ${profile}`;
+  });
+
+  const innerWidth = createMemo(() => Math.max(40, panelWidth() - 6));
+  const shortcutHint = createMemo(() => {
+    const count = currentLength();
+    const quick = count === 1 ? '1 quick select' : `1-${count} quick select`;
+    return mode() === 'workspace-select'
+      ? `↑/↓ select  Enter open  ${quick}  Esc back`
+      : `↑/↓ select  Enter open  ${quick}  Esc quit`;
+  });
+  const menuTitle = createMemo(() => mode() === 'workspace-select' ? 'Select workspace' : '');
+
+  return (
+    <box width="100%" height="100%" backgroundColor="#0B0D12">
+      <box
+        position="absolute"
+        left={left()}
+        top={top()}
+        width={panelWidth()}
+        height={panelHeight()}
+        border
+        borderStyle="rounded"
+        borderColor="#8BD5CA"
+        backgroundColor="#111318"
+        padding={2}
+        flexDirection="column"
+        overflow="hidden"
+      >
+        <box height={1} flexDirection="row">
+          <text fg="#8BD5CA" content={fit(`DONNA v${props.version}`, Math.floor(innerWidth() * 0.5))} />
+          <text fg={props.wikiReady ? '#8BD5CA' : '#FBBF24'} content={fit(` ${statusDot(props.wikiReady)} ${status()}`, Math.floor(innerWidth() * 0.45))} />
+        </box>
+        <text height={1} fg="#7F8C8D" content={fit(subtitle(), innerWidth())} />
+        <text height={1}>{''}</text>
+        <text height={1} fg="#D6DEE8">██████╗  ██████╗ ███╗   ██╗███╗   ██╗ █████╗</text>
+        <text height={1} fg="#D6DEE8">██╔══██╗██╔═══██╗████╗  ██║████╗  ██║██╔══██╗</text>
+        <text height={1} fg="#D6DEE8">██║  ██║██║   ██║██╔██╗ ██║██╔██╗ ██║███████║</text>
+        <text height={1} fg="#D6DEE8">██║  ██║██║   ██║██║╚██╗██║██║╚██╗██║██╔══██║</text>
+        <text height={1} fg="#D6DEE8">██████╔╝╚██████╔╝██║ ╚████║██║ ╚████║██║  ██║</text>
+        <text height={1} fg="#D6DEE8">╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═══╝╚═╝  ╚═╝</text>
+        <text height={1}>{''}</text>
+        <text height={1} fg="#7F8C8D" content={menuTitle()} />
+        <box height={Math.max(1, currentLength())} flexDirection="column">
+          <For each={mode() === 'workspace-select' ? workspaceItems() : items()}>
+            {(item, index) => {
+              const active = () => index() === selected();
+              return (
+                <box
+                  height={1}
+                  flexDirection="row"
+                  onMouseUp={() => choose(index())}
+                >
+                  <text width={4} fg={active() ? '#111318' : '#7F8C8D'} bg={active() ? '#8BD5CA' : undefined}>
+                    {active() ? '›' : ' '} {index() + 1}
+                  </text>
+                  <text width={28} fg={active() ? '#8BD5CA' : '#D6DEE8'} content={fit(item.label, 27)} />
+                  <text fg="#7F8C8D" content={fit(item.detail, Math.max(8, innerWidth() - 34))} />
+                </box>
+              );
+            }}
+          </For>
+        </box>
+        <text height={1}>{''}</text>
+        <box height={3} flexDirection="column" border={['left']} borderStyle="heavy" borderColor="#5DADE2" paddingX={1}>
+          <text height={1} fg="#D6DEE8" content={fit(`LLM  ${statusDot(Boolean(props.model))} ${props.model || 'not configured'}`, innerWidth() - 2)} />
+          <text height={1} fg="#D6DEE8" content={fit(`MCP  ${statusDot(props.connectedMcpServers > 0)} ${props.connectedMcpServers} server(s) configured`, innerWidth() - 2)} />
+          <text height={1} fg="#D6DEE8" content={fit(`Wiki ${statusDot(props.wikiReady)} ${props.wikiReady ? 'default profile ready' : 'init required'}`, innerWidth() - 2)} />
+        </box>
+        <text height={1}>{''}</text>
+        <text height={1} fg="#7F8C8D" content={shortcutHint()} />
+      </box>
+    </box>
+  );
+}

package/src/shell/repl.js

@@ -15,7 +15,7 @@ import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { listSkills } from '../core/skills.js';
 import { listWikircProfiles } from '../core/wikirc.js';
 import { listWorkspaces } from '../core/workspaces.js';
-import { fetchRuntimeState, postRuntimeApprove, postRuntimeCancel, postRuntimeRun, streamRuntimeEvents } from '../runtime/client.js';
+import { fetchRuntimeState, postRuntimeApprove, postRuntimeCancel, postRuntimeControl, postRuntimeRun, streamRuntimeEvents } from '../runtime/client.js';
 
 marked.use(markedTerminal());
 // marked-terminal's text renderer extracts token.text (raw string) instead of
@@ -743,7 +743,18 @@ export function applyRuntimeStateToShellSession(session, state) {
     logs: Array.isArray(state.logs) ? [...state.logs] : [],
     summary: state.summary ?? null,
     status: state.status ?? 'idle',
+    planRevision: state.planRevision ?? 0,
+    planPatches: Array.isArray(state.planPatches) ? state.planPatches.map((patch) => ({ ...patch })) : [],
   };
+  session.workflow = state.workflow && typeof state.workflow === 'object'
+    ? {
+        ...state.workflow,
+        nodes: Array.isArray(state.workflow.nodes) ? state.workflow.nodes.map((node) => ({ ...node })) : [],
+        relations: Array.isArray(state.workflow.relations) ? state.workflow.relations.map((relation) => ({ ...relation })) : [],
+        waitingReasons: Array.isArray(state.workflow.waitingReasons) ? [...state.workflow.waitingReasons] : [],
+        warnings: Array.isArray(state.workflow.warnings) ? [...state.workflow.warnings] : [],
+      }
+    : null;
   session.headlessPlan = session.agentProjection.plan
     ? session.agentProjection.plan.map((step) => ({ ...step }))
     : null;
@@ -772,6 +783,27 @@ export function applyRuntimeStateToShellSession(session, state) {
   return true;
 }
 
+// Submits a prompt to the shared runtime. If the workspace is already busy
+// (HTTP 409 from POST /run), route the input through the runtime control lane
+// so status questions and plan-change proposals do not become future runs.
+export async function submitRuntimeRun(line, { runtime, session }) {
+  const workspace = session.workspace ?? null;
+  try {
+    await postRuntimeRun(line, { url: runtime.url, workspace });
+    return { kind: 'accepted' };
+  } catch (err) {
+    if (err?.status !== 409) {
+      return { kind: 'error', message: err instanceof Error ? err.message : String(err) };
+    }
+    try {
+      const result = await postRuntimeControl('message', { url: runtime.url, workspace, input: line });
+      return { kind: result?.kind ?? 'control', result };
+    } catch (queueErr) {
+      return { kind: 'error', message: queueErr instanceof Error ? queueErr.message : String(queueErr) };
+    }
+  }
+}
+
 function activityText(session) {
   const activity = sessionActivities(session).find((item) => !item.terminal)
     ?? (session.productionActivity?.label ? session.productionActivity : null);
@@ -1499,13 +1531,25 @@ async function runTuiShell({ agent, packageJson, session, runtime = null }) {
             syncRuntimeState();
           }
         } else if (runtime?.url && !session.chatMode && !line.trim().startsWith('/')) {
-          await postRuntimeRun(line, {
-            url: runtime.url,
-            workspace: session.workspace ?? null,
-          });
           conversationMessages(session).push({ role: 'user', content: line });
-          conversationMessages(session).push({ role: 'command', content: `Runtime run queued: ${runtime.url}` });
-          activityLines = [...activityLines, 'runtime: run accepted'].slice(-LOWER_DETAIL_ROWS);
+          const outcome = await submitRuntimeRun(line, { runtime, session });
+          if (outcome.kind === 'accepted') {
+            conversationMessages(session).push({ role: 'command', content: `Runtime run queued: ${runtime.url}` });
+            activityLines = [...activityLines, 'runtime: run accepted'].slice(-LOWER_DETAIL_ROWS);
+          } else if (outcome.kind === 'queued') {
+            conversationMessages(session).push({ role: 'command', content: 'Runtime is busy — request added to the control queue, it will start automatically.' });
+            activityLines = [...activityLines, 'runtime: control queued'].slice(-LOWER_DETAIL_ROWS);
+          } else if (outcome.kind === 'observe' || outcome.kind === 'converse' || outcome.kind === 'mutate') {
+            const explanation = outcome.result?.explanation ?? 'Runtime control message accepted.';
+            conversationMessages(session).push({ role: 'command', content: explanation });
+            activityLines = [...activityLines, `runtime: ${outcome.kind}`].slice(-LOWER_DETAIL_ROWS);
+          } else if (outcome.kind === 'ambiguous') {
+            conversationMessages(session).push({ role: 'command', content: 'Runtime could not classify that message. Use /queue for a future run, or ask/status more explicitly.' });
+            activityLines = [...activityLines, 'runtime: ambiguous control'].slice(-LOWER_DETAIL_ROWS);
+          } else {
+            conversationMessages(session).push({ role: 'command', content: `Runtime error: ${outcome.message}` });
+            activityLines = [...activityLines, `runtime error: ${outcome.message}`].slice(-LOWER_DETAIL_ROWS);
+          }
           syncRuntimeState();
         } else {
           const result = await runLine(line, { agent, packageJson, session, onUpdate: rerender, onStep });

package/src/shell/repl.test.js

@@ -1,6 +1,20 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { applyRuntimeStateToShellSession, createSession, conversationMessages } from './repl.js';
+import { applyRuntimeStateToShellSession, createSession, conversationMessages, submitRuntimeRun } from './repl.js';
+
+function stubFetch(handler) {
+  const original = globalThis.fetch;
+  globalThis.fetch = handler;
+  return () => { globalThis.fetch = original; };
+}
+
+function jsonResponse(status, body) {
+  return { ok: status >= 200 && status < 300, status, text: async () => JSON.stringify(body), json: async () => body };
+}
+
+function pathOf(url) {
+  return new URL(String(url)).pathname;
+}
 
 test('applyRuntimeStateToShellSession projects runtime state into shell session', () => {
   const session = createSession();
@@ -22,6 +36,12 @@ test('applyRuntimeStateToShellSession projects runtime state into shell session'
       terminal: false,
     }],
     queue: [{ id: 'q-1', status: 'waiting' }],
+    workflow: {
+      nodes: [{ id: 'task:build', type: 'task', label: 'Build', status: 'running' }],
+      relations: [{ type: 'contains', from: 'run:run-1', to: 'task:build' }],
+      waitingReasons: ['queue:q-1'],
+      warnings: ['legacy_sequential_plan'],
+    },
     logs: ['agentic-loop: turn 1/20'],
   });
 
@@ -31,8 +51,64 @@ test('applyRuntimeStateToShellSession projects runtime state into shell session'
   assert.equal(session.activities['production:job-1'].status, 'running');
   assert.equal(session.productionActivity.jobId, 'job-1');
   assert.equal(session.jobQueue[0].id, 'q-1');
+  assert.equal(session.workflow.nodes[0].id, 'task:build');
+  assert.equal(session.workflow.relations[0].type, 'contains');
+  assert.deepEqual(session.workflow.waitingReasons, ['queue:q-1']);
   assert.deepEqual(conversationMessages(session), [
     { role: 'user', content: 'Build docs' },
     { role: 'donna', content: 'Working.' },
   ]);
 });
+
+test('submitRuntimeRun reports acceptance without throwing', async () => {
+  const restore = stubFetch(async (url) => {
+    assert.equal(pathOf(url), '/run');
+    return jsonResponse(202, { accepted: true, runId: 'run-1' });
+  });
+  try {
+    const session = createSession();
+    const outcome = await submitRuntimeRun('build the doc', { runtime: { url: 'http://runtime.test' }, session });
+    assert.deepEqual(outcome, { kind: 'accepted' });
+  } finally {
+    restore();
+  }
+});
+
+test('submitRuntimeRun routes busy runtime input through the control lane', async () => {
+  let controlBody = null;
+  const restore = stubFetch(async (url, init) => {
+    const path = pathOf(url);
+    if (path === '/run') return jsonResponse(409, { error: 'A runtime run is already active.' });
+    if (path === '/control') {
+      controlBody = JSON.parse(String(init.body));
+      return jsonResponse(200, { accepted: true, kind: 'observe', explanation: 'Runtime run is active.' });
+    }
+    throw new Error(`unexpected fetch: ${url}`);
+  });
+  try {
+    const session = createSession();
+    const outcome = await submitRuntimeRun('Où en est le build ?', { runtime: { url: 'http://runtime.test' }, session });
+    assert.equal(outcome.kind, 'observe');
+    assert.equal(outcome.result.explanation, 'Runtime run is active.');
+    assert.deepEqual(controlBody, { action: 'message', input: 'Où en est le build ?' });
+  } finally {
+    restore();
+  }
+});
+
+test('submitRuntimeRun reports a non-409 error without throwing or calling /control', async () => {
+  let controlCalled = false;
+  const restore = stubFetch(async (url) => {
+    if (pathOf(url) === '/control') controlCalled = true;
+    return jsonResponse(503, { error: 'runtime unavailable' });
+  });
+  try {
+    const session = createSession();
+    const outcome = await submitRuntimeRun('build the doc', { runtime: { url: 'http://runtime.test' }, session });
+    assert.equal(outcome.kind, 'error');
+    assert.match(outcome.message, /503/);
+    assert.equal(controlCalled, false);
+  } finally {
+    restore();
+  }
+});

package/src/shell/textFit.ts

@@ -0,0 +1,6 @@
+export function fit(value: string, width: number): string {
+  const max = Math.max(1, width);
+  if (value.length <= max) return value;
+  if (max <= 1) return '…';
+  return value.slice(0, max - 1) + '…';
+}

package/src/shell/tui.tsx

@@ -7,10 +7,70 @@ import { LeftPane } from './LeftPane';
 import { RightPane } from './RightPane';
 import { SlashDialog } from './SlashDialog';
 import { SetupWizard } from './SetupWizard';
+import { StartupScreen, type StartupAction } from './StartupScreen';
 import { useSession } from './useSession';
+import { buildMcpStatus } from '../core/mcp.js';
+import { loadWikircProfile, summarizeWikircConfig } from '../core/wikirc.js';
+import { listWorkspaces } from '../core/workspaces.js';
 
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
+function emptyStartupInfo(version: string, workspace: { name: string } | null, workspaces: { name: string }[]) {
+  return {
+    version,
+    model: '',
+    connectedMcpServers: 0,
+    wikiReady: false,
+    workspaceName: workspace?.name ?? null,
+    profileName: 'default',
+    workspaces: workspaces.map((item) => item.name),
+    hasWorkspace: workspace != null,
+  };
+}
+
+function startupInfo(packageJson: Record<string, unknown>) {
+  // listWorkspaces() order is filesystem-dependent (readdirSync), not stable —
+  // sort so "the default workspace" is deterministic across runs/platforms.
+  const workspaces = [...listWorkspaces()].sort((a, b) => a.name.localeCompare(b.name));
+  const workspace = workspaces[0] ?? null;
+  const version = String(packageJson.version ?? '');
+  if (!workspace) return emptyStartupInfo(version, null, []);
+
+  try {
+    const loaded = loadWikircProfile(workspace.workspacePath, 'default');
+    const summary = summarizeWikircConfig(loaded.profile, loaded.config);
+    const session = {
+      workspace: workspace.name,
+      workspacePath: workspace.workspacePath,
+      workspaceEnv: workspace.env,
+      wikirc: {
+        profile: loaded.profile.name,
+        fileName: loaded.profile.fileName,
+        path: loaded.profile.path,
+      },
+      wikircConfig: loaded.config,
+    };
+    const mcp = buildMcpStatus(session);
+    const connectedMcpServers = Object.values(mcp)
+      .filter((server: any) => server?.status && server.status !== 'missing')
+      .length;
+    const provider = summary.provider ? String(summary.provider) : '';
+    const model = summary.model ? String(summary.model) : '';
+    return {
+      version,
+      model: [provider, model].filter(Boolean).join(' / '),
+      connectedMcpServers,
+      wikiReady: true,
+      workspaceName: workspace.name,
+      profileName: loaded.profile.name,
+      workspaces: workspaces.map((item) => item.name),
+      hasWorkspace: true,
+    };
+  } catch {
+    return emptyStartupInfo(version, workspace, workspaces);
+  }
+}
+
 function copyToClipboard(text: string, renderer: unknown) {
   try {
     if ((renderer as any).copyToClipboardOSC52?.(text)) return true;
@@ -49,11 +109,16 @@ function App(props: {
   const [exitHint, setExitHint] = createSignal(false);
   const [copyHint, setCopyHint] = createSignal<string | null>(null);
   const [chatInputHeight, setChatInputHeight] = createSignal(3);
+  // The app has exactly three mutually exclusive screens; one signal makes
+  // that invariant structural instead of relying on two booleans staying in
+  // sync at every call site.
+  const [screen, setScreen] = createSignal<'startup' | 'setup' | 'main'>('startup');
   let ctrlCTimer: ReturnType<typeof setTimeout> | null = null;
   let copyHintTimer: ReturnType<typeof setTimeout> | null = null;
   let selectionCopyTimer: ReturnType<typeof setTimeout> | null = null;
   let lastCopiedSelection = '';
   const state = useSession(props);
+  const startup = createMemo(() => startupInfo(props.packageJson));
   const conversationRows = createMemo(() => Math.max(4, dimensions().height - 5 - chatInputHeight()));
   const rightColumns = createMemo(() => {
     const width = dimensions().width;
@@ -73,6 +138,71 @@ function App(props: {
     });
   };
 
+  const loadWorkspace = async (workspaceName?: string | null) => {
+    if (!workspaceName) return false;
+    if ((state.session as any).workspace === workspaceName) return true;
+    await state.submitInput(`/use ${workspaceName}`);
+    // /use does not throw on failure (e.g. a stale/deleted workspace) — it
+    // just returns an error message without switching session.workspace, so
+    // callers must check the actual post-await state rather than assume success.
+    return (state.session as any).workspace === workspaceName;
+  };
+
+  // `startup` is a memo over non-reactive fs reads (listWorkspaces() etc.),
+  // so it only ever reflects state at first mount. Action handlers that
+  // decide *which* workspace to load must re-read current state directly
+  // (startupInfo(...)) rather than trust the frozen memo, the same way
+  // closeSetup() already does.
+  const loadDefaultWorkspace = async () => loadWorkspace(startupInfo(props.packageJson).workspaceName);
+
+  // "Open a workspace" is really one composite action (load it, then bring
+  // its services up) — named here so it has one definition instead of being
+  // inlined as three sequential submitInput calls in openAction.
+  const openWorkspaceAndStartServices = async (workspaceName?: string | null) => {
+    const loaded = await loadWorkspace(workspaceName);
+    if (loaded) {
+      await state.submitInput('/start agents');
+      await state.submitInput('/start all');
+    }
+    return loaded;
+  };
+
+  const openAction = (action: StartupAction, workspaceName?: string) => {
+    if (action === 'init-workspace') {
+      setScreen('setup');
+      return;
+    }
+    setScreen('main');
+    void (async () => {
+      try {
+        if (action === 'open-workspace') {
+          await openWorkspaceAndStartServices(workspaceName ?? startupInfo(props.packageJson).workspaceName);
+        } else if (action === 'new-conversation' || action === 'run-workflow') {
+          const loaded = await loadDefaultWorkspace();
+          if (action === 'run-workflow' && loaded) {
+            await state.submitInput('/agent');
+          }
+        }
+      } catch {
+        // Individual submitInput failures already surface their own error
+        // text in the conversation transcript; just stop the sequence here
+        // instead of leaving an unhandled rejection.
+      }
+    })();
+  };
+
+  const closeSetup = () => {
+    const info = startupInfo(props.packageJson);
+    if (!info.hasWorkspace) {
+      setScreen('startup');
+      return;
+    }
+    setScreen('main');
+    // Reuse loadWorkspace (not a bare /use dispatch) so the "already on this
+    // workspace" short-circuit applies here too.
+    void loadWorkspace(info.workspaceName);
+  };
+
   const showCopyHint = (message: string) => {
     setCopyHint(message);
     if (copyHintTimer) clearTimeout(copyHintTimer);
@@ -106,6 +236,7 @@ function App(props: {
 
   useKeyboard((key) => {
     const keyName = String(key.name ?? '').toLowerCase();
+    if (screen() !== 'main') return;
     if (state.activeEditor()) {
       if (keyName === 'escape') state.closeEditor();
       return;
@@ -151,6 +282,26 @@ function App(props: {
     return null;
   };
 
+  if (screen() === 'startup') {
+    const info = startup();
+    return (
+      <StartupScreen
+        version={info.version}
+        model={info.model}
+        connectedMcpServers={info.connectedMcpServers}
+        wikiReady={info.wikiReady}
+        workspaceName={info.workspaceName}
+        profileName={info.profileName}
+        workspaces={info.workspaces}
+        hasWorkspace={info.hasWorkspace}
+        width={dimensions().width}
+        height={dimensions().height}
+        onSelect={openAction}
+        onQuit={() => renderer.destroy()}
+      />
+    );
+  }
+
   return (
     <box width="100%" height="100%" flexDirection="row">
       <LeftPane
@@ -198,6 +349,18 @@ function App(props: {
         onSave={state.saveEditor}
         onCancel={state.closeEditor}
       />
+      {screen() === 'setup' ? (
+        <SetupWizard
+          mode="setup"
+          session={state.session}
+          width={dimensions().width}
+          height={dimensions().height}
+          initialRoute="workspace-name"
+          closeOnDone
+          onComplete={closeSetup}
+          onClose={closeSetup}
+        />
+      ) : null}
     </box>
   );
 }

package/src/shell/useAgent.ts

@@ -1,6 +1,6 @@
 import { createSignal } from 'solid-js';
-import { postRuntimeCancel, postRuntimeRun } from '../runtime/client.js';
-import { conversationMessages, runLine } from './repl.js';
+import { postRuntimeCancel } from '../runtime/client.js';
+import { conversationMessages, runLine, submitRuntimeRun } from './repl.js';
 
 export function useAgent(props: { agent: unknown; packageJson: Record<string, unknown>; session: Record<string, any>; chatMode: () => boolean; runtimeUrl?: string | null; refresh: () => void; addLog: (line: string) => void; onRuntimeAccepted?: () => void }) {
   const [busy, setBusy] = createSignal(false);
@@ -19,14 +19,22 @@ export function useAgent(props: { agent: unknown; packageJson: Record<string, un
 
     try {
       if (props.runtimeUrl && !props.chatMode() && !trimmed.startsWith('/')) {
-        await postRuntimeRun(trimmed, {
-          url: props.runtimeUrl,
-          workspace: props.session.workspace ?? null,
-        });
         conversationMessages(props.session).push({ role: 'user', content: trimmed });
-        conversationMessages(props.session).push({ role: 'command', content: `Runtime run queued: ${props.runtimeUrl}` });
-        props.onRuntimeAccepted?.();
-        props.addLog('runtime: run accepted');
+        const outcome = await submitRuntimeRun(trimmed, {
+          runtime: { url: props.runtimeUrl },
+          session: props.session,
+        });
+        if (outcome.kind === 'accepted') {
+          conversationMessages(props.session).push({ role: 'command', content: `Runtime run queued: ${props.runtimeUrl}` });
+          props.onRuntimeAccepted?.();
+          props.addLog('runtime: run accepted');
+        } else if (outcome.kind === 'queued') {
+          conversationMessages(props.session).push({ role: 'command', content: 'Runtime is busy — request added to the control queue, it will start automatically.' });
+          props.addLog('runtime: control queued');
+        } else {
+          conversationMessages(props.session).push({ role: 'command', content: `Runtime error: ${outcome.message}` });
+          props.addLog(`runtime error: ${outcome.message}`);
+        }
         props.refresh();
         return { exit: false, runtime: true };
       }