@parallel-cli/parallel 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to Parallel are documented here.
 
+## 0.4.7 - 2026-06-24
+
+### 0.4.7 Added
+
+- Added file revision safety for shared-tree co-editing so stale `write_file` retries and `edit_file` calls must re-read and merge concurrent work before mutating.
+- Added immediate agent-to-agent note nudging with duplicate-note suppression, active-agent checks, and rate-limit safeguards.
+- Added visible coordination signals in the Hub, `/board`, `/diff`, and timelines for claims, work-map warnings, notes, approvals, and questions.
+- Added `/review [agent|all] [prompt]`, a lightweight ask-mode reviewer that returns `APPROVE`, `REVISE`, or `BLOCK` with risks, tests to run, and files to inspect.
+- Added Cursor-style per-agent progress steps through `update_steps`, visible in the Hub and attached terminals.
+- Added batched read-only inspection tools (`read_many`, `inspect_project`) plus lightweight performance counters for model turns, tool calls, shell commands, and context usage.
+
+### 0.4.7 Changed
+
+- Reworked `/board` into a coordination surface with Work map warnings first, agent/path/time metadata, and suggestions to inspect `/focus` or `/diff`.
+- Prioritized incoming notes and work-map context in agent live context so coordination updates are handled before ordinary activity.
+- Updated product messaging around shared awareness: agents work like a live team on one working tree, not isolated background jobs.
+- Reworked agent rows to keep the Hub compact with cropped summaries, cream bullet recaps capped at four lines, mode badges, and visible `full /focus aN` plus `term /attach aN` shortcuts.
+- Reworked dedicated agent terminals with a launch header, hidden raw launch noise in normal mode, append-only final results, and a small live status region so native scrollback remains usable.
+- Tuned agent prompts by mode so `/ask`, `/task`, `/plan`, and `/review` use clearer contracts, early progress steps, batched inspection, and less redundant shell micro-commanding.
+
+### 0.4.7 Fixed
+
+- Fixed the previous collision retry weakness where a stale writer could receive an adaptation diff and then overwrite without a real re-read.
+- Fixed `edit_file` allowing targeted edits on a stale file as long as `old_string` still existed.
+- Fixed timeline narration being hardcoded in French by routing narration through i18n.
+- Fixed `claim_files` appearing as generic file activity instead of coordination activity.
+- Fixed completed attached terminals repainting large dynamic result panels that could trap mouse-wheel scroll at the top.
+
 ## 0.4.6 - 2026-06-24
 
 ### 0.4.6 Added

package/README.md

@@ -1,10 +1,10 @@
 # Parallel
 
-Real-time multi-agent coding from one terminal control room.
+Real-time coding agents that work like a live team, not isolated background jobs.
 
-Parallel lets you run several AI coding agents on the same repository at the same time. Each agent has its own task, mode, live activity timeline, model, and shared session context. The TUI stays keyboard-first so you can launch work, inspect progress, answer approvals, steer agents, and review changes without leaving the terminal.
+Parallel lets several AI coding agents co-edit the same repository at the same time with shared awareness injected before every model action. Each agent has its own task, mode, live activity timeline, model, and visible coordination context. The TUI stays keyboard-first so you can launch work, inspect progress, answer approvals, steer agents, review risks, and reconcile changes without leaving the terminal.
 
-> One hub. Many agents. Shared context. Human in control.
+> One working tree. Many agents. Shared awareness. Human in control.
 
 [![npm version](https://img.shields.io/npm/v/@parallel-cli/parallel?color=blue)](https://www.npmjs.com/package/@parallel-cli/parallel)
 ![node version](https://img.shields.io/node/v/@parallel-cli/parallel)
@@ -13,14 +13,18 @@ Parallel lets you run several AI coding agents on the same repository at the sam
 
 ## Highlights
 
-- Run multiple agents in parallel on one project.
-- Choose explicit modes: `/ask`, `/task`, and `/plan`.
+- Run multiple agents as a live team on one shared working tree.
+- Choose explicit modes: `/ask`, `/task`, `/plan`, and `/review`.
 - Type plain text to launch a task agent immediately.
 - Use context-aware input in the hub, focus view, and attached agent terminals.
 - Steer one agent with `@a1 ...` or broadcast with `@all ...`.
 - Open dedicated agent terminals with native scrollback.
 - Use a cleaner Codex-like hub with a framed header, focused prompt bar, and quieter empty state.
 - Review agents, notes, file activity, diffs, cost, skills, specialists, and saved sessions from the TUI.
+- Use `/review [agent|all]` to spawn a lightweight ask-mode reviewer with verdict, risks, tests, and files to inspect.
+- Avoid lost work with file revision safety: stale `write_file` and `edit_file` calls must re-read and merge before retrying.
+- Nudge agents immediately when another agent posts a targeted note, with dedupe and rate-limit safeguards.
+- See overlapping claims and repeated co-edit conflicts in the Hub, `/board`, `/diff`, and agent timelines.
 - Track shell-created file mutations in the same live diff feed as agent edits.
 - Configure OpenAI-compatible providers through a guided wizard and settings panel.
 - Use 29 provider presets across Western, Chinese, Gateway, Inference, and Local categories.
@@ -86,6 +90,7 @@ Use explicit modes when intent matters:
 /ask Reviewer: should we split the CLI parser?
 /plan Migration: propose the safest rollout for the config change
 /task Builder: implement the approved plan
+/review all before we commit
 ```
 
 Steer a running agent:
@@ -102,11 +107,36 @@ Broadcast to every agent:
 
 `@all` steers active agents in real time. Finished, stopped, or errored agents are not relaunched by a broadcast.
 
+## Best Use Case: Coupled Work
+
+Parallel is strongest when the work is too coupled for isolated fan-out and too large for one agent.
+
+Example live-team flow:
+
+```text
+/task API: define the new billing quote contract in src/api/quotes.ts
+/task Client: build the UI client against the quote contract
+/task Tests: write integration coverage for quote creation and validation
+```
+
+The API agent can claim `src/api`, post a note with the proposed signature, and update the contract. The client agent sees that note and the diff before its next model action, re-reads the file, and adapts without inventing a second interface. The tests agent watches both sides, adds coverage, and can ask for clarification before the three agents collide.
+
+Before committing:
+
+```text
+/review all verify the API contract, client usage, and tests agree
+```
+
+The reviewer is ask-only: it does not edit, does not gate the session globally, and returns a structured verdict with risks and validation steps.
+
 ## Agent Modes
 
 - `/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.
+- `/task`: implementation work. The agent can execute, edit, validate, and summarize. It may also conclude that no file change is needed when the task is a verification.
 - `/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.
+- `/review`: lightweight reviewer around `/ask`. It inspects the current shared-tree work and returns `APPROVE`, `REVISE`, or `BLOCK` with risks, tests to run, and files to inspect.
+
+Task and plan agents maintain a small Cursor-style checklist with one active step at a time. The runtime also encourages batched inspection through `read_many` and `inspect_project` so agents avoid slow chains of tiny read-only shell commands.
 
 Aliases:
 
@@ -118,7 +148,7 @@ Plain text is equivalent to `/task`.
 
 ## Control Room
 
-The main TUI is the Parallel hub. The default view stays intentionally quiet: a Codex-like framed header, cream-toned accents, a focused prompt block, and detailed status moved into explicit views.
+The main TUI is the Parallel hub. The default view stays intentionally quiet: a Codex-like framed header, cream-toned accents, a focused prompt block, compact cropped agent rows, and detailed status moved into explicit views.
 
 It is designed to answer:
 
@@ -128,6 +158,11 @@ It is designed to answer:
 - what changed in the project
 - what model, provider, shell mode, and cost are active
 
+Agent rows stay compact even when summaries are long. Use the row shortcuts to expand the right level of detail:
+
+- `full /focus a1`: open the full in-Hub transcript and result for one agent.
+- `term /attach a1`: reopen that agent's dedicated terminal.
+
 Input has three explicit contexts:
 
 - Hub: plain text launches a new `/task` agent. Slash suggestions show hub commands and agent arguments autocomplete for `/focus`, `/send`, `/attach`, `/pause`, `/resume`, `/stop`, `/restore`, and `/commit`.
@@ -146,6 +181,8 @@ Common hub commands:
 - `/agents`: agent overview.
 - `/focus a1`: inspect and steer one agent.
 - `/raw`: toggle raw detail in focus view.
+- `/attach a1`: open or reopen an agent's dedicated terminal.
+- `/review all`: ask-mode reviewer with verdict, risks, tests, and files to inspect.
 - `/board`: shared blackboard, claims, notes, and file activity.
 - `/diff`: live diff history.
 - `/cost`: token and cost breakdown.
@@ -180,8 +217,10 @@ parallel attach a1 --root .
 
 Attached terminals show:
 
+- a launch header with agent, mode, model, and task
 - the selected agent's live timeline
 - native terminal scrollback
+- append-only final results after `done`, `error`, or `stopped`
 - model, elapsed time, context, and cost
 - other agents' current state
 - approval and question prompts for that agent
@@ -197,6 +236,7 @@ plain text sends a message to this agent
 /task Tests: write parser regression tests
 /ask Reviewer: is this result safe to merge?
 /plan Migration: prepare a migration plan
+/review all before commit
 /raw
 /quit
 ```
@@ -265,6 +305,7 @@ If the update succeeds, restart Parallel to run the new version. Use `parallel -
 - `/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.
+- `/review [agent|all] [prompt]`: launch a lightweight ask-mode reviewer for one agent or the whole shared tree.
 - `/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.
@@ -293,7 +334,7 @@ If the update succeeds, restart Parallel to run the new version. Use `parallel -
 ### Views And Sessions
 
 - `/agents`: agent overview.
-- `/board`: shared blackboard, file activity, claims, and notes.
+- `/board`: shared blackboard, work-map warnings, claims, file activity, and notes.
 - `/notes`: full notes history.
 - `/diff`: live diff history.
 - `/cost`: token and cost breakdown.
@@ -375,15 +416,21 @@ When an agent writes a file:
 
 1. Parallel checks whether the file changed since that agent last read it.
 2. If the file is unchanged, the write proceeds.
-3. If another agent changed it, the write is rejected once.
-4. The agent receives the other change as context, re-reads the file, merges both intentions, and retries.
+3. If another agent or shell command changed it, the write is rejected with an adaptation diff.
+4. The stale baseline is not silently synchronized. The agent must call `read_file`, merge both intentions on top of the current revision, and retry.
 
-This keeps agents moving without allowing silent overwrites.
+The same stale-read guard applies to `edit_file`, even when `old_string` still exists. This keeps agents moving without allowing silent overwrites.
 
 Commands run through `run_command` are also snapshotted before and after execution. If a shell command edits, creates, or deletes tracked project files, Parallel records those mutations in `/diff`, `/board`, and `/commit` ownership just like tool-based edits.
 
 The work map is advisory, not a lock. Agents can declare claims with `claim_files`; Parallel detects overlapping claims and repeated conflicts, then shows non-blocking warnings in `/board` and injects them into agent context so agents can coordinate before collisions become expensive.
 
+## Shared-Tree Vs Isolated Agents
+
+Use Parallel's shared-tree mode when agents need to negotiate live contracts: API and client, schema and tests, parser and docs, or any change where one agent's edit should affect another agent's next step.
+
+Use isolated agents or separate worktrees for embarrassingly parallel work: unrelated files, independent chores, or experiments you only want to merge after review. Parallel's identity is the shared-tree team workflow; isolation is a future complement, not the default.
+
 ## Headless Mode
 
 For CI and scripts, run without the TUI:

package/dist/agents/agent.js

@@ -19,12 +19,14 @@ AGENT MODE: ${mode}
 ${mode === 'ask'
     ? `ASK MODE:
 - You are advisory only. Do not modify files.
-- You may inspect with list_files/read_file/search and safe read-only commands when useful.
+- Prefer search/read_file/read_many/inspect_project over shell. Use safe read-only commands only when internal tools are insufficient.
+- Keep the investigation short and targeted. Do not run heavy validation loops unless the user explicitly asks.
 - Do not run mutating commands, write files, edit files, claim files, or commit.
 - Finish with task_complete using this user-facing structure in ${userLang}: "Réponse courte", "Recommandation", "Pourquoi", "Prochaines étapes".`
     : mode === 'plan'
         ? `PLAN MODE:
 - Explore first with read-only tools.
+- Batch independent reads/searches with read_many or inspect_project. Keep exploration broad enough to be correct but bounded.
 - 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 "Revise" so timeout never approves changes.
@@ -32,7 +34,8 @@ ${mode === 'ask'
 - Finish with task_complete using this user-facing structure in ${userLang}: "Plan appliqué", "Ce que j’ai modifié", "Validation", "Risques restants".`
         : `TASK MODE:
 - Execute the user's objective end-to-end.
-- Explore, edit, validate, and summarize.
+- Use this loop: create visible steps, batch inspect, act, batch validate, summarize.
+- If the task is a verification/audit and the correct outcome is no file changes, that is valid task work. Say explicitly in task_complete that no modification was necessary and why.
 - Ask the user only when blocked or when a risky product decision cannot be inferred.
 - Finish with task_complete using this user-facing structure in ${userLang}: "Ce que j’ai fait", "Ce que j’ai vérifié", "Résultat", "Détails techniques".`}
 ${skillsList
@@ -59,13 +62,16 @@ PARALLEL'S PHILOSOPHY — REAL-TIME CO-EDITING, NEVER ANY BLOCKING:
 8. MAKE THE SHARED AWARENESS VISIBLE: when another agent's work influenced a decision of yours (you reused their function, adapted to their diff, avoided their work area), SAY IT explicitly — in a post_note to them ("I saw you changed X, so I did Y") and in your task_complete summary (name the agent and what you built on). The user must be able to SEE that you worked as a team, not as isolated bots.
 
 WORK METHOD:
-- Explore first (list_files, read_file, search) before modifying.
+- For non-trivial work, call update_steps early with 3-6 concrete steps. Keep exactly one step active and mark steps done as you complete them.
+- Explore first before modifying. Decide all independent reads/searches you need, then batch them with read_many or inspect_project instead of calling tools one by one.
+- Use run_command for builds/tests/validation and genuinely useful shell scripts. Do NOT spend many turns running grep/head/tail/wc/awk cascades; batch independent shell checks into one labelled command or use inspect_project.
 - Declare your work area with claim_files when you start (and when it changes): it prevents collisions without ever locking anything.
 - If you discover a durable, non-obvious fact about the project (convention, decision, pitfall), save it with remember(fact) for future agents.
 - wait_for_agent exists for hard dependencies only — prefer progressing on another part of your task over waiting.
 - Prefer edit_file (targeted changes) over write_file (full rewrite): targeted edits coexist better in parallel.
 - Make minimal changes; do not rewrite what already works.
 - Verify your work when relevant (run_command for tests/build), then finish with task_complete.
+- Performance discipline: minimize model turns. If multiple tool calls are independent, make them in the same assistant turn. If several shell checks are independent, run one labelled command.
 - The task_complete summary is user-facing. Make it structured and specific in ${userLang}, not just "done":
   1. What I did — concrete outcome in 1-2 sentences.
   2. Files changed or inspected — mention paths when relevant.
@@ -76,6 +82,29 @@ WORK METHOD:
 LANGUAGE: write notes addressed to "user" and your task_complete summary in ${userLang}. Notes to other agents and code stay in English.`;
 /** Assumed context window (tokens) when the provider does not advertise one. */
 const CONTEXT_WINDOW = 128_000;
+const EMPTY_PERF = {
+    modelTurns: 0,
+    toolCalls: 0,
+    shellCommands: 0,
+    shellMs: 0,
+    readOnlyShellCommands: 0,
+};
+function noChangeTaskLine() {
+    switch (getLang()) {
+        case 'fr':
+            return 'Mode task: vérification sans changement de fichier nécessaire.';
+        case 'es':
+            return 'Modo task: verificación sin cambios de archivos necesarios.';
+        case 'zh':
+            return 'Task 模式：已完成验证，无需修改文件。';
+        case 'en':
+        default:
+            return 'Task mode: verification completed with no file changes needed.';
+    }
+}
+function isReadOnlyShell(command) {
+    return /\b(grep|rg|head|tail|wc|awk|sed|cat|ls|find)\b/.test(command) && !/[>|;]/.test(command);
+}
 export class Agent {
     opts;
     id;
@@ -90,6 +119,7 @@ export class Agent {
     stopped = false;
     lastNoteId = 0;
     lastChangeId = 0;
+    readOnlyShellStreak = 0;
     constructor(opts) {
         this.opts = opts;
         this.id = opts.id;
@@ -114,6 +144,8 @@ export class Agent {
             cost: opts.price ? 0 : null,
             startedAt: Date.now(),
             specialist: opts.specialist?.name,
+            progressSteps: [],
+            perf: { ...EMPTY_PERF },
         };
         this.board.registerAgent(info);
         // Skip notes/changes that existed before this agent was born
@@ -165,9 +197,13 @@ export class Agent {
      * A note addressed to this agent just arrived: interrupt the current model
      * call so the next turn (which injects unread notes) starts immediately.
      */
-    nudge() {
+    nudge(reason = 'reading team update') {
+        if (this.finished || this.stopped || this.paused)
+            return false;
         this.steered = true;
+        this.board.setAgentState(this.id, 'listening', reason);
         this.llmAbort?.abort();
+        return true;
     }
     /**
      * Append a message to the in-memory history AND to the conversation file
@@ -189,6 +225,18 @@ export class Agent {
             await new Promise((r) => setTimeout(r, 300));
         }
     }
+    updatePerf(delta) {
+        const current = this.board.agents.get(this.id)?.perf ?? EMPTY_PERF;
+        this.board.updateAgent(this.id, {
+            perf: {
+                modelTurns: current.modelTurns + (delta.modelTurns ?? 0),
+                toolCalls: current.toolCalls + (delta.toolCalls ?? 0),
+                shellCommands: current.shellCommands + (delta.shellCommands ?? 0),
+                shellMs: current.shellMs + (delta.shellMs ?? 0),
+                readOnlyShellCommands: current.readOnlyShellCommands + (delta.readOnlyShellCommands ?? 0),
+            },
+        });
+    }
     /**
      * Build the live context injected before EVERY model call:
      * other agents' status + their fresh diffs + unread notes.
@@ -197,6 +245,15 @@ export class Agent {
     liveContext() {
         let hasNews = false;
         const parts = ['[REAL TIME]', this.board.snapshotFor(this.id)];
+        const notes = this.board.notesFor(this.name, this.lastNoteId);
+        if (notes.length > 0) {
+            this.lastNoteId = notes[notes.length - 1].id;
+            hasNews = true;
+            parts.push('\n[PRIORITY NOTES RECEIVED — take them into account now]');
+            for (const n of notes) {
+                parts.push(`  • from ${n.from}: ${n.content}`);
+            }
+        }
         const changes = this.board.changesSince(this.id, this.lastChangeId);
         if (changes.length > 0) {
             this.lastChangeId = changes[changes.length - 1].id;
@@ -219,15 +276,6 @@ export class Agent {
             }
             parts.push('Analyze these diffs: if any of them touches your work area, re-read the affected file and adapt. NEVER undo these changes.');
         }
-        const notes = this.board.notesFor(this.name, this.lastNoteId);
-        if (notes.length > 0) {
-            this.lastNoteId = notes[notes.length - 1].id;
-            hasNews = true;
-            parts.push('\n[NOTES RECEIVED — take them into account now]');
-            for (const n of notes) {
-                parts.push(`  • from ${n.from}: ${n.content}`);
-            }
-        }
         parts.push('\nContinue your task taking the above into account. Use tools, or task_complete if finished.');
         return { text: parts.join('\n'), hasNews };
     }
@@ -322,6 +370,7 @@ export class Agent {
                     this.llmAbort = null;
                 }
                 this.steered = false;
+                this.updatePerf({ modelTurns: 1 });
                 const a = this.board.agents.get(this.id);
                 if (a) {
                     // Real-time financial view: accrue the cost of this round immediately.
@@ -378,11 +427,40 @@ export class Agent {
                         this.board.log(this.id, 'tool', label);
                     }
                     this.board.updateAgent(this.id, { currentAction: label.slice(0, 80) });
+                    const shellStartedAt = tc.function.name === 'run_command' ? Date.now() : 0;
                     const result = await this.executor.execute(tc.function.name, args);
+                    const shellMs = shellStartedAt ? Date.now() - shellStartedAt : 0;
+                    const readOnlyShell = tc.function.name === 'run_command' && isReadOnlyShell(String(args.command ?? ''));
+                    this.updatePerf({
+                        toolCalls: 1,
+                        shellCommands: tc.function.name === 'run_command' ? 1 : 0,
+                        shellMs,
+                        readOnlyShellCommands: readOnlyShell ? 1 : 0,
+                    });
+                    if (readOnlyShell) {
+                        this.readOnlyShellStreak++;
+                        if (this.readOnlyShellStreak >= 3) {
+                            this.record({
+                                role: 'user',
+                                content: '[PERFORMANCE CORRECTION] You are using several read-only shell micro-commands. Batch the next inspection with read_many/inspect_project or a single labelled shell command, then continue.',
+                            });
+                            this.readOnlyShellStreak = 0;
+                        }
+                    }
+                    else if (tc.function.name !== 'update_status' && tc.function.name !== 'update_steps') {
+                        this.readOnlyShellStreak = 0;
+                    }
                     if (result === '__TASK_COMPLETE__') {
                         completed = true;
                         const summary = String(args.summary ?? 'Task complete.');
-                        this.board.updateAgent(this.id, { lastResult: summary });
+                        const changedByThisAgent = this.board.changes.filter((c) => c.agentId === this.id).length;
+                        const noChangePrefix = this.opts.mode === 'task' && changedByThisAgent === 0
+                            ? `${noChangeTaskLine()}\n\n`
+                            : '';
+                        this.board.updateAgent(this.id, {
+                            lastResult: `${noChangePrefix}${summary}`,
+                            progressSteps: (this.board.agents.get(this.id)?.progressSteps ?? []).map((s) => ({ ...s, status: 'done' })),
+                        });
                         // ONE short headline note (the full summary lives in lastResult and
                         // is rendered as the agent's recap) — no duplicated walls of text.
                         const headline = summary.split('\n').find((l) => l.trim())?.trim() ?? 'Task complete.';
@@ -419,6 +497,8 @@ export class Agent {
         switch (name) {
             case 'read_file':
                 return `📖 read ${args.path}`;
+            case 'read_many':
+                return `📚 read ${Array.isArray(args.paths) ? args.paths.slice(0, 3).join(', ') : 'files'}`;
             case 'write_file':
                 return `✏ write ${args.path}`;
             case 'edit_file':
@@ -427,12 +507,16 @@ export class Agent {
                 return `📁 ls ${args.path ?? '.'}`;
             case 'search':
                 return `🔍 search /${args.pattern}/`;
+            case 'inspect_project':
+                return `🔎 inspect project`;
             case 'run_command':
                 return `$ ${args.command}`;
             case 'post_note':
                 return `✉ note → ${args.to}`;
             case 'update_status':
                 return `📢 ${args.status}`;
+            case 'update_steps':
+                return `☑ update steps`;
             case 'ask_user':
                 return `❓ ${String(args.question ?? '').slice(0, 60)}`;
             case 'load_skill':