@parallel-cli/parallel 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to Parallel are documented here.
 
+## 0.4.4 - 2026-06-23
+
+### 0.4.4 Added
+
+- Added tool-level safeguards for `/ask` and `/plan`: ask agents cannot mutate project state, and plan agents must get explicit approval before mutating files or running risky shell commands.
+- Added session-only provider setup for `/settings-session`, with an explicit choice between temporary session use and saving globally.
+- Expanded `/doctor` into actionable readiness diagnostics for provider, model, key, local endpoints, attach socket, `git`, and `gh`.
+- Added scrolling/windowing budgets to long TUI views such as board, notes, diffs, cost, skills, specialists, and sessions.
+- Added saved-session restore hints and clearer `/restore` errors.
+
+### 0.4.4 Changed
+
+- Reworked the README to render consistently on both GitHub and npm.
+- Replaced wide Markdown tables and fixed-width command blocks with npm-friendly lists.
+- Removed provider-specific environment variable guidance from the public README so provider setup remains neutral.
+- Documented DeepSeek only as one provider preset in the Chinese provider group, not as a special standalone setup path.
+- Made `@all` steer active agents directly instead of only posting a passive note.
+- Made `/plan` timeouts safe by requiring manual approval before mutations are unlocked.
+- Increased the saved sessions list window from 8 to 20 and shows `/save [name]` labels in `/sessions`.
+- Bumped the TUI header version to `0.4.4`.
+
+### 0.4.4 Fixed
+
+- Fixed `/commit message...` with exactly one agent so the first word is treated as part of the message, not as a missing agent name.
+- Fixed `/project` and `/wizard` transitions by warning when active agents are running unless `--force` is passed.
+- Fixed local/custom provider setup so localhost endpoints do not require an API key and placeholder models are not considered ready.
+- Fixed stale focus after agents disappear through clear, stop, project switch, session load, or restore.
+- Fixed `/settings-session` key entry so provider setup reaches the session-only vs global-save choice instead of returning early.
+- Fixed first-run custom provider setup so it reviews/edits endpoints and skips API keys for localhost endpoints.
+- Fixed filesystem boundary checks so agent tools reject sibling paths with a shared project-root prefix.
+- Fixed TUI clipping risks by budgeting the hub by rendered rows and applying body-height windowing to notes/diffs.
+- Fixed Settings Escape handling so typed inputs clear before navigating back.
+
 ## 0.4.3 - 2026-06-23
 
 ### 0.4.3 Added
@@ -32,7 +65,7 @@ All notable changes to Parallel are documented here.
 - Fixed session settings accidentally behaving like global provider mutation in several flows.
 - Fixed bare model IDs containing `:` such as `qwen3-coder:480b`.
 - Fixed stale default provider normalization during config load and provider removal.
-- Fixed `DEEPSEEK_API_KEY` overriding whichever provider happened to be default; it now targets DeepSeek only.
+- Fixed provider-specific environment overrides leaking into whichever provider happened to be default.
 - Fixed local endpoints being blocked by missing API keys.
 - Fixed sensitive `/key ...` entries being stored in input history.
 - Fixed tiny pseudo-TTY dimensions causing negative string repeat values in the TUI header.
@@ -49,7 +82,7 @@ All notable changes to Parallel are documented here.
 
 ### 0.4.2 Changed
 
-- Reworked the README provider section to be provider-agnostic instead of DeepSeek-centered.
+- Reworked the README provider section to be provider-agnostic.
 - Updated provider tables, endpoint documentation, and model catalog references.
 - Removed internal docs from remote tracking and kept them out of the public package.
 

package/README.md

@@ -96,13 +96,13 @@ Broadcast to every agent:
 @all stop changing public interfaces until the test agent finishes
 ```
 
+`@all` steers active agents in real time. Finished, stopped, or errored agents are not relaunched by a broadcast.
+
 ## Agent Modes
 
-| Mode | Use it for | Behavior |
-| --- | --- | --- |
-| `/ask` | Questions, reviews, audits, tradeoffs | Answers and advises without editing files. |
-| `/task` | Implementation work | Executes, edits, validates, and summarizes. |
-| `/plan` | Risky or unclear work | Inspects first, presents a plan, then edits only after approval. |
+- `/ask`: questions, reviews, audits, and tradeoffs. The agent answers and advises; mutating tools and shell commands are blocked.
+- `/task`: implementation work. The agent can execute, edit, validate, and summarize.
+- `/plan`: risky or unclear work. The agent inspects first, presents a plan, then edits only after explicit approval. A timeout does not approve the plan.
 
 Aliases:
 
@@ -124,19 +124,19 @@ The main TUI is the Parallel hub. It is designed to answer:
 
 Common hub commands:
 
-```text
-/agents              agent overview
-/focus a1            inspect and steer one agent
-/raw                 toggle raw detail in focus view
-/board               shared blackboard, claims, notes, file activity
-/diff                live diff history
-/cost                token and cost breakdown
-/sessions            saved sessions
-/settings            global settings
-/settings-session    session-only settings
-/project [folder]    change project folder
-/wizard              rerun setup wizard
-```
+- `/agents`: agent overview.
+- `/focus a1`: inspect and steer one agent.
+- `/raw`: toggle raw detail in focus view.
+- `/board`: shared blackboard, claims, notes, and file activity.
+- `/diff`: live diff history.
+- `/cost`: token and cost breakdown.
+- `/sessions`: saved sessions.
+- `/settings`: global settings.
+- `/settings-session`: session-only settings.
+- `/project [folder]`: change project folder.
+- `/wizard`: rerun setup wizard.
+
+Commands are typed in the control room input. When a long view is open, use Escape to return to the agents view/input.
 
 Keyboard behavior:
 
@@ -144,7 +144,7 @@ Keyboard behavior:
 - Up/Down selects suggestions when a suggestion menu is open.
 - Enter accepts the selected suggestion.
 - Tab or Right accepts the best completion.
-- Up/Down scrolls long views such as `/help`.
+- PgUp/PgDn scrolls the hub or focus view even while the input is active. Up/Down scrolls long views and navigates suggestions/history.
 - Escape returns to the agents view or clears the input.
 
 Best terminal size is around `120x34`. Parallel adapts to smaller terminals, but the hub is most readable with enough width for model, folder, status, and agent summaries.
@@ -202,101 +202,86 @@ Provider setup is guided in both the first-run wizard and `/settings`:
 4. Enter the provider API key if the provider requires one.
 5. Save globally or use the provider/model for the current session.
 
-Local providers such as Ollama and vLLM/SGLang do not require an API key. You can still review and edit their endpoints.
+Local providers such as Ollama, vLLM/SGLang, and custom localhost OpenAI-compatible endpoints do not require an API key. You can still review and edit their endpoints. Ollama/local OpenAI-compatible endpoints can detect models from `/models`; vLLM/SGLang requires replacing the `your-model-here` placeholder before it is considered ready.
 
 Useful settings commands:
 
-```text
-/settings            global language, providers, keys, defaults, approvals
-/settings-session    temporary model, provider, approvals, sound
-/model               show current session model
-/model provider:id   switch model for this session
-/doctor              check provider/model/API key readiness
-```
+- `/settings`: global language, providers, keys, defaults, and approvals.
+- `/settings-session`: temporary model, provider, approvals, and sound. New providers can be used for this session only or saved globally.
+- `/model`: show the current session model.
+- `/model provider:id`: switch model for this session.
+- `/doctor`: check provider, model, API key, local endpoint reachability, attach socket, `git`, and `gh`.
 
 Configuration is stored in `~/.parallel/config.json`.
 
 Environment variables:
 
-| Variable | Purpose |
-| --- | --- |
-| `PARALLEL_API_KEY` | API key for the current default provider. |
-| `DEEPSEEK_API_KEY` | API key for the DeepSeek provider only. |
-| `PARALLEL_BASE_URL` | Override the default provider base URL. |
-| `PARALLEL_MODEL` | Override the session model. |
-| `PARALLEL_NO_ALT_SCREEN=1` | Disable the alternate terminal screen. |
+- `PARALLEL_API_KEY`: API key for the current default provider.
+- `PARALLEL_BASE_URL`: override the default provider base URL.
+- `PARALLEL_MODEL`: override the session model.
+- `PARALLEL_NO_ALT_SCREEN=1`: disable the alternate terminal screen.
 
 ## Commands
 
 ### Create Agents
 
-| Command | Description |
-| --- | --- |
-| `/ask [Name:] <question> [--model=m]` | Launch an ask-only agent. |
-| `/task [Name:] <task> [--model=m] [#skill]` | Launch a task agent. Plain text does the same. |
-| `/plan [Name:] <task> [--model=m]` | Launch a plan-first agent. |
-| `/issue <n>` | Spawn a task from a GitHub issue using the `gh` CLI. |
-| `/specialist <name> <task>` | Spawn with a specialist persona. |
-| `/specialist new <name> [global]` | Create a specialist template. |
-| `/skill new <name> [global]` | Create a skill template. |
+- `/ask [Name:] <question> [--model=m]`: launch an ask-only agent.
+- `/task [Name:] <task> [--model=m] [#skill]`: launch a task agent. Plain text does the same.
+- `/plan [Name:] <task> [--model=m]`: launch a plan-first agent. It cannot mutate files or run risky shell commands until you manually approve the plan.
+- `/issue <n>`: spawn a task from a GitHub issue. Requires the `gh` CLI, a GitHub repository, and `gh auth login`.
+- `/specialist <name> <task>`: spawn with a specialist persona.
+- `/specialist new <name> [global]`: create a specialist template.
+- `/skill new <name> [global]`: create a skill template.
 
 ### Steer Agents
 
-| Command | Description |
-| --- | --- |
-| `@agent <message>` | Send a live instruction to one agent. |
-| `@all <message>` | Broadcast an instruction to all agents. |
-| `/send <agent\|all> <message>` | Command form of live steering. |
-| `/attach <agent\|on\|off>` | Open an agent terminal or toggle automatic terminals. |
-| `/focus <agent\|off>` | Route plain input to one agent instead of spawning new agents. |
-| `/pause <agent\|all>` | Pause at the next action boundary. |
-| `/resume <agent\|all>` | Resume paused agents. |
-| `/stop <agent\|all>` | Stop running agents. |
-| `/clear` | Remove finished agents from the current display. |
-| `/raw` | Toggle conversation-raw view. |
-| `/copy` | Copy the latest completed result to clipboard. |
+- `@agent <message>`: send a live instruction to one agent.
+- `@all <message>`: broadcast an instruction to all agents.
+- `/send <agent|all> <message>`: command form of live steering.
+- `/attach <agent|on|off>`: open an agent terminal or toggle automatic terminals.
+- `/focus <agent|off>`: route plain input to one agent instead of spawning new agents.
+- `/pause <agent|all>`: pause at the next action boundary.
+- `/resume <agent|all>`: resume paused agents.
+- `/stop <agent|all>`: stop running agents.
+- `/clear`: remove finished agents from the current display.
+- `/raw`: toggle conversation-raw view.
+- `/copy`: copy the latest completed result to clipboard.
 
 ### Git Safety
 
-| Command | Description |
-| --- | --- |
-| `/undo [agent]` | Revert the last file change made by an agent, with conflict detection. |
-| `/commit [agent\|all] [message]` | Commit files touched by an agent or by all agents. |
-| `/autocommit <on\|off>` | Commit each agent's changes automatically when it finishes. |
+- `/undo [agent]`: revert the last file change made by an agent, with conflict detection.
+- `/commit [agent|all] [message]`: commit only files touched by the selected agent or by all agents. It does not run `git add -A`. With exactly one agent, `/commit message...` uses that agent and treats the rest as the message.
+- `/autocommit <on|off>`: commit each agent's touched files automatically when it finishes. This is session-only.
 
 ### Views And Sessions
 
-| Command | Description |
-| --- | --- |
-| `/agents` | Agent overview. |
-| `/board` | Shared blackboard, file activity, claims, and notes. |
-| `/notes` | Full notes history. |
-| `/diff` | Live diff history. |
-| `/cost` | Token and cost breakdown. |
-| `/status` | Session model, approval mode, agents, cost snapshot. |
-| `/skills` | Available skills. |
-| `/specialists` | Available specialists. |
-| `/save [name]` | Save the current session. |
-| `/sessions` | List saved sessions. |
-| `/session <n\|latest>` | Restore a saved session. |
-| `/restore <agent>` | Relaunch a restored agent with its conversation history. |
+- `/agents`: agent overview.
+- `/board`: shared blackboard, file activity, claims, and notes.
+- `/notes`: full notes history.
+- `/diff`: live diff history.
+- `/cost`: token and cost breakdown.
+- `/status`: session model, approval mode, agents, and cost snapshot.
+- `/skills`: available skills.
+- `/specialists`: available specialists.
+- `/save [name]`: save the current session.
+- `/sessions`: list saved sessions.
+- `/session <n|latest>`: load a saved session snapshot. If active agents are running, use `/session <n|latest> --force` after saving/stopping what you need.
+- `/restore <agent>`: relaunch a restored agent with its conversation history.
 
 ### Settings And Exit
 
-| Command | Description |
-| --- | --- |
-| `/model [[provider:]model]` | Show or switch the session model. |
-| `/approvals <ask\|auto\|auto-safe\|yolo>` | Set shell approvals for this session. |
-| `/sound <on\|off>` | Toggle terminal bell notifications. |
-| `/settings` | Edit global language, providers, keys, defaults, and approvals. |
-| `/settings-session` | Edit session-only model, approvals, and sound. |
-| `/project [folder]` | Change project folder or reopen the folder picker. |
-| `/folder [folder]` | Alias for `/project`. |
-| `/wizard` | Relaunch the setup wizard. |
-| `/setup` | Alias for `/wizard`. |
-| `/doctor` | Check provider, key, and model configuration. |
-| `/help` | Full command reference. |
-| `/quit` | Save the session and exit. |
+- `/model [[provider:]model]`: show or switch the session model.
+- `/approvals <ask|auto|auto-safe|yolo>`: set shell approvals for this session.
+- `/sound <on|off>`: toggle terminal bell notifications.
+- `/settings`: edit global language, providers, keys, defaults, and approvals.
+- `/settings-session`: edit session-only model, provider, approvals, and sound.
+- `/project [folder]`: change project folder or reopen the folder picker. If agents are active, use `/project [folder] --force` after saving/stopping what you need.
+- `/folder [folder]`: alias for `/project`.
+- `/wizard`: relaunch the setup wizard. If agents are active, use `/wizard --force` after saving/stopping what you need.
+- `/setup`: alias for `/wizard`.
+- `/doctor`: run local readiness diagnostics for provider, key, model, endpoint, attach socket, and Git tooling.
+- `/help`: full command reference.
+- `/quit`: save the session and exit.
 
 When there is exactly one agent, commands such as `/undo`, `/focus`, `/pause`, `/resume`, `/stop`, and `/commit` can omit the agent name.
 
@@ -310,11 +295,9 @@ Parallel separates agent modes from shell approval behavior.
 /approvals yolo
 ```
 
-| Mode | Behavior |
-| --- | --- |
-| `ask` | Ask before shell commands unless explicitly allowed. |
-| `auto-safe` | Auto-approve safe inspection/build/test commands and ask for risky commands. |
-| `yolo` | Auto-approve every shell command. Intended for trusted/headless usage only. |
+- `ask`: ask before shell commands unless explicitly allowed.
+- `auto-safe`: auto-approve safe inspection/build/test commands and ask for risky commands.
+- `yolo`: auto-approve every shell command. Intended for trusted/headless usage only.
 
 `auto` is accepted as a compatibility spelling for `auto-safe`.
 

package/dist/agents/agent.js

@@ -27,7 +27,7 @@ ${mode === 'ask'
 - Explore first with read-only tools.
 - Before modifying any file or running mutating commands, call ask_user with a concrete implementation plan.
 - The plan must include steps, files you expect to touch, risks, and validation.
-- Use options ["Approve", "Revise"], recommended "Approve".
+- Use options ["Approve", "Revise"], recommended "Revise" so timeout never approves changes.
 - Start editing only after explicit "Approve".
 - Finish with task_complete using this user-facing structure in ${userLang}: "Plan appliqué", "Ce que j’ai modifié", "Validation", "Risques restants".`
         : `TASK MODE:
@@ -97,7 +97,7 @@ export class Agent {
         this.llm = opts.llm;
         this.board = opts.board;
         this.maxSteps = opts.maxSteps;
-        this.executor = new ToolExecutor(opts.board, opts.id, opts.name, opts.projectRoot, opts.requestApproval, opts.requestQuestion, opts.skills);
+        this.executor = new ToolExecutor(opts.board, opts.id, opts.name, opts.projectRoot, opts.requestApproval, opts.requestQuestion, opts.skills, opts.mode);
         const info = {
             id: opts.id,
             name: opts.name,

package/dist/agents/tools.js

@@ -4,6 +4,19 @@ import { exec } from 'node:child_process';
 import * as Diff from 'diff';
 const IGNORED = new Set(['node_modules', '.git', '.parallel', 'dist', '__pycache__', '.venv', 'venv']);
 const MAX_OUTPUT = 12_000;
+const MUTATING_TOOLS = new Set(['write_file', 'edit_file', 'claim_files', 'remember']);
+function isMutatingShell(command) {
+    const c = command.toLowerCase();
+    if (/\b(rm|mv|cp|chmod|chown|mkdir|touch|truncate)\b/.test(c))
+        return true;
+    if (/\b(git\s+(add|commit|push|pull|merge|rebase|checkout|switch|reset|clean|stash|tag))\b/.test(c))
+        return true;
+    if (/\b(npm|pnpm|yarn)\s+(install|add|remove|update|audit\s+fix)\b/.test(c))
+        return true;
+    if (/[>|]\s*(sh|bash)\b/.test(c) || /\b(curl|wget)\b.*\|\s*(sh|bash)/.test(c))
+        return true;
+    return false;
+}
 export const TOOL_DEFINITIONS = [
     {
         type: 'function',
@@ -228,11 +241,13 @@ export class ToolExecutor {
     requestApproval;
     requestQuestion;
     skills;
+    mode;
     /** Last content this agent has seen for each file — basis of adaptive merging. */
     lastRead = new Map();
     /** Questions already asked — capped at 3 per task. */
     questionsAsked = 0;
-    constructor(board, agentId, agentName, projectRoot, requestApproval, requestQuestion, skills) {
+    planApproved = false;
+    constructor(board, agentId, agentName, projectRoot, requestApproval, requestQuestion, skills, mode = 'task') {
         this.board = board;
         this.agentId = agentId;
         this.agentName = agentName;
@@ -240,10 +255,13 @@ export class ToolExecutor {
         this.requestApproval = requestApproval;
         this.requestQuestion = requestQuestion;
         this.skills = skills;
+        this.mode = mode;
     }
     resolve(rel) {
-        const abs = path.resolve(this.projectRoot, rel);
-        if (!abs.startsWith(path.resolve(this.projectRoot))) {
+        const root = path.resolve(this.projectRoot);
+        const abs = path.resolve(root, rel);
+        const relative = path.relative(root, abs);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
             throw new Error(`Path outside the project refused: ${rel}`);
         }
         return abs;
@@ -253,6 +271,9 @@ export class ToolExecutor {
     }
     async execute(name, args) {
         try {
+            const guard = this.guardTool(name, args);
+            if (guard)
+                return guard;
             switch (name) {
                 case 'list_files':
                     return this.listFiles(args?.path ?? '.');
@@ -293,6 +314,22 @@ export class ToolExecutor {
             return `ERROR: ${err?.message ?? String(err)}`;
         }
     }
+    guardTool(name, args) {
+        if (this.mode === 'ask') {
+            if (MUTATING_TOOLS.has(name) || name === 'run_command') {
+                return `DENIED: this agent is in /ask mode. It can inspect and advise, but cannot modify files, run shell commands, claim files, or write memory.`;
+            }
+        }
+        if (this.mode === 'plan' && !this.planApproved) {
+            if (MUTATING_TOOLS.has(name)) {
+                return `DENIED: this agent is in /plan mode and the plan has not been approved yet. Present the plan with ask_user and wait for "Approve" before modifying project state.`;
+            }
+            if (name === 'run_command' && isMutatingShell(String(args?.command ?? ''))) {
+                return `DENIED: this shell command looks mutating. In /plan mode, run only read-only inspection before approval; ask_user for plan approval first.`;
+            }
+        }
+        return null;
+    }
     /**
      * Ask the user a multiple-choice question. NEVER blocks forever: the UI shows
      * a visible 30s countdown and falls back to the recommended option (auto-run).
@@ -312,9 +349,14 @@ export class ToolExecutor {
         this.questionsAsked++;
         this.board.setAgentState(this.agentId, 'waiting', `question: ${question.slice(0, 60)}`);
         this.board.log(this.agentId, 'note', `❓ ${question}`);
-        const answer = await this.requestQuestion(this.agentId, question, options, recommended);
+        const response = await this.requestQuestion(this.agentId, question, options, recommended);
+        const answer = response.answer;
+        if (this.mode === 'plan' && !response.auto && answer.trim().toLowerCase().startsWith('approve')) {
+            this.planApproved = true;
+        }
         this.board.setAgentState(this.agentId, 'working');
-        return `The user answered: "${answer}". Act on this choice now (${3 - this.questionsAsked} question(s) left for this task).`;
+        const source = response.auto ? 'The timeout auto-selected' : 'The user answered';
+        return `${source}: "${answer}". Act on this choice now (${3 - this.questionsAsked} question(s) left for this task).`;
     }
     /** Declare (advisory) work areas — visible to the user and the other agents. */
     claimFiles(args) {

package/dist/commands.js

@@ -1,6 +1,9 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { Controller, normalizeShellApprovalMode } from './controller.js';
 import { createSkillTemplate, createSpecialistTemplate } from './skills.js';
-import { providerReady } from './config.js';
+import { isLocalProvider, isPlaceholderModel, providerNeedsApiKey } from './config.js';
 import { t } from './i18n.js';
 // Grouped by intent so /help reads as a story: create agents → steer them →
 // inspect the session → git safety net → session & config → exit.
@@ -66,6 +69,72 @@ export function matchCommands(input, opts = {}) {
 function agentList(ctl) {
     return [...ctl.board.agents.values()].map((a) => a.name).join(', ') || t('m.none');
 }
+function commandExists(name) {
+    try {
+        execFileSync('which', [name], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function localEndpointReachable(baseUrl) {
+    let timeout;
+    try {
+        const controller = new AbortController();
+        timeout = setTimeout(() => controller.abort(), 1500);
+        const resp = await fetch(baseUrl.replace(/\/+$/, '') + '/models', { signal: controller.signal });
+        return resp.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+async function doctorReport(ctl, ui) {
+    const p = ctl.sessionProvider();
+    const lines = [];
+    let level = 'ok';
+    if (!p) {
+        ui.system(t('m.doctorReport', { lines: t('m.doctorNoProvider') }), 'error');
+        return;
+    }
+    const activeModel = ctl.session.model || p.defaultModel || p.models[0] || '';
+    lines.push(t('m.doctorProvider', { provider: p.name, model: activeModel || '—' }));
+    if (providerNeedsApiKey(p) && !p.apiKey) {
+        level = 'error';
+        lines.push(t('m.doctorKeyMissing'));
+    }
+    else {
+        lines.push(providerNeedsApiKey(p) ? t('m.doctorKeyOk') : t('m.doctorKeySkipped'));
+    }
+    if (isPlaceholderModel(activeModel)) {
+        level = 'error';
+        lines.push(t('m.doctorModelMissing'));
+    }
+    else {
+        lines.push(t('m.doctorModelOk', { model: activeModel }));
+    }
+    if (isLocalProvider(p)) {
+        const reachable = await localEndpointReachable(p.baseUrl);
+        if (reachable) {
+            lines.push(t('m.doctorEndpointOk', { url: p.baseUrl }));
+        }
+        else {
+            if (level !== 'error')
+                level = 'warn';
+            lines.push(t('m.doctorEndpointFail', { url: p.baseUrl }));
+        }
+    }
+    const sock = path.join(ctl.projectRoot, '.parallel', 'session.sock');
+    lines.push(fs.existsSync(sock) ? t('m.doctorAttachOk') : t('m.doctorAttachMissing'));
+    lines.push(commandExists('git') ? t('m.doctorGitOk') : t('m.doctorGitMissing'));
+    lines.push(commandExists('gh') ? t('m.doctorGhOk') : t('m.doctorGhMissing'));
+    ui.system(t('m.doctorReport', { lines: lines.join('\n') }), level);
+}
 /**
  * Single-agent ergonomics: when the session has exactly ONE agent, commands
  * that target an agent (/undo, /focus, /pause…) work without naming it.
@@ -78,10 +147,12 @@ function spawnFrom(arg, ctl, ui, images, specialist, mode = 'task') {
     const p = ctl.sessionProvider();
     if (!p)
         return ui.system(t('m.missingProvider'), 'error');
-    if (!providerReady(p))
+    if (providerNeedsApiKey(p) && !p.apiKey)
         return ui.system(t('m.missingKey', { name: p.name }), 'error');
-    if (!ctl.session.model && !p.defaultModel && !p.models[0])
+    const activeModel = ctl.session.model || p.defaultModel || p.models[0] || '';
+    if (isPlaceholderModel(activeModel)) {
         return ui.system(t('m.missingModel', { name: p.name }), 'error');
+    }
     // optional --model=xxx flag
     let model;
     let task = arg;
@@ -129,8 +200,8 @@ export function executeInput(raw, ctl, ui, images) {
             return ui.system(t('m.usageAt'), 'warn');
         const [, target, content] = m;
         if (target.toLowerCase() === 'all') {
-            ctl.broadcast(content);
-            ui.system(t('m.broadcast'), 'ok');
+            const n = ctl.broadcast(content);
+            ui.system(t('m.broadcast', { n }), n > 0 ? 'ok' : 'warn');
         }
         else if (ctl.sendToAgent(target, content)) {
             ui.system(t('m.sent', { target }), 'ok');
@@ -217,10 +288,18 @@ export function executeInput(raw, ctl, ui, images) {
         case '/commit': {
             // Commit the files touched by one agent (or all) — staged by explicit path.
             const [target0, ...msg] = rest;
-            const target = target0 || soloAgent(ctl);
+            const solo = soloAgent(ctl);
+            const target = target0 && (target0.toLowerCase() === 'all' || ctl.board.getAgentByName(target0))
+                ? target0
+                : target0 && solo
+                    ? solo
+                    : target0 || solo;
+            const message = target0 && target === solo && target0.toLowerCase() !== solo?.toLowerCase() && !ctl.board.getAgentByName(target0)
+                ? rest.join(' ').trim()
+                : msg.join(' ').trim();
             if (!target)
                 return ui.system(t('m.usageCommit'), 'warn');
-            const r = ctl.commitFor(target, msg.join(' ').trim() || undefined);
+            const r = ctl.commitFor(target, message || undefined);
             if (r.ok)
                 return ui.system(t('m.committed', { name: target, files: String(r.files) }), 'ok');
             if (r.reason === 'not-found')
@@ -249,15 +328,19 @@ export function executeInput(raw, ctl, ui, images) {
                 ui.setView('sessions');
                 return;
             }
+            const force = rest.includes('--force');
+            const selector = rest.filter((part) => part !== '--force').join(' ').trim();
             const sessions = Controller.listSessions(ctl.projectRoot);
             if (sessions.length === 0)
                 return ui.system(t('m.usageSession'), 'warn');
-            const idx = arg.toLowerCase() === 'latest' ? 0 : Number.parseInt(arg, 10) - 1;
+            const idx = selector.toLowerCase() === 'latest' ? 0 : Number.parseInt(selector, 10) - 1;
             const session = sessions[idx];
             if (!session)
                 return ui.system(t('m.usageSession'), 'warn');
+            if (ctl.hasRunningAgents() && !force)
+                return ui.system(t('m.sessionActive'), 'warn');
             ctl.loadSession(session.data);
-            ui.system(t('m.sessionLoaded', { date: new Date(session.data.savedAt).toLocaleString() }), 'ok');
+            ui.system(t('m.sessionLoaded', { date: new Date(session.data.savedAt).toLocaleString() }) + '\n' + t('m.sessionRestoreHint'), 'ok');
             return;
         }
         case '/restore': {
@@ -267,6 +350,8 @@ export function executeInput(raw, ctl, ui, images) {
             if (!ctl.loadedSession)
                 return ui.system(t('m.usageSession'), 'warn');
             const res = ctl.respawnAgent(arg);
+            if (res === 'no-agent')
+                return ui.system(t('m.noRestoredAgent', { name: arg }), 'error');
             if (res === 'no-conversation')
                 return ui.system(t('m.noConversation', { name: arg }), 'error');
             if (!res)
@@ -315,14 +400,7 @@ export function executeInput(raw, ctl, ui, images) {
             return;
         }
         case '/doctor': {
-            const p = ctl.sessionProvider();
-            if (!p)
-                return ui.system(t('m.missingProvider'), 'error');
-            if (!providerReady(p))
-                return ui.system(t('m.missingKey', { name: p.name }), 'error');
-            if (!ctl.session.model && !p.defaultModel && !p.models[0])
-                return ui.system(t('m.missingModel', { name: p.name }), 'error');
-            ui.system(t('m.doctorOk', { pm: `${p.name}:${ctl.session.model || p.defaultModel || p.models[0]}` }), 'ok');
+            void doctorReport(ctl, ui);
             return;
         }
         case '/cost':
@@ -476,9 +554,17 @@ export function executeInput(raw, ctl, ui, images) {
             ui.setView('settings-session');
             return;
         case '/project':
-            ui.openProject?.(arg || undefined);
+            {
+                const force = rest.includes('--force');
+                const folderArg = rest.filter((part) => part !== '--force').join(' ').trim();
+                if (ctl.hasRunningAgents() && !force)
+                    return ui.system(t('m.projectActive'), 'warn');
+                ui.openProject?.(folderArg || undefined);
+            }
             return;
         case '/wizard':
+            if (ctl.hasRunningAgents() && arg !== '--force')
+                return ui.system(t('m.wizardActive'), 'warn');
             ui.openWizard?.();
             return;
         // SESSION-only approvals & sound (global defaults editable in /settings).