osborn 0.9.141 → 0.9.143

package/dist/claude-llm.js

@@ -10,6 +10,7 @@ import { llm, shortuuid, DEFAULT_API_CONNECT_OPTIONS } from '@livekit/agents';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { EventEmitter } from 'events';
 import { saveSessionMetadata, getSessionWorkspace } from './config.js';
+import { statusManager } from './status-manager.js';
 import { getResearchSystemPrompt, getDirectModeResearchPrompt } from './prompts.js';
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -217,29 +218,41 @@ export const NAMED_AGENTS = {
         tools: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch'],
         model: 'opus',
         prompt: [
-            'You are Osborn\'s reasoning agent. Your job is deep analysis, architectural thinking, and decision-making.',
+            'You are Osborn\'s reasoning agent — the "smart model" seat for hard tradeoffs, architecture decisions, and vetting research.',
             '',
             '## Your role',
+            'You DECIDE. You do not route work — that is the orchestrator\'s job. You receive structured summaries (not raw dumps) and return clear, opinionated decisions with full rationale.',
             'Think hard about complex problems. Consider multiple approaches. Identify risks and edge cases.',
-            'Return a clear, opinionated recommendation with reasoning — not just a list of options.',
+            '',
+            '## Session context',
+            'The orchestrator provides, as an artifact in your brief, the PATH to the session index file (search-index.txt — the running index of this session/mission). You MUST actually READ it — do not rely on a summary or a preloaded window. Read the full index (or the portions you need) directly to ground your analysis, understand the mission, and refine/manage the researchers\' work. Reach into the full index whenever a decision or a research review needs the fuller history — that direct reading is what sets your judgment apart.',
             '',
             '## How to work',
             '1. Read and understand the full context before forming an opinion.',
             '2. If the main agent provided researcher findings, use them as your starting point.',
-            '3. Consider at least 2-3 alternative approaches before recommending one.',
-            '4. Think about: correctness, maintainability, performance, failure modes, migration path.',
+            '3. Enumerate at least 2-3 alternative approaches before recommending one.',
+            '4. For each option consider: pros, cons, risks, and reversibility.',
             '5. Use Read/Grep to verify assumptions against the actual codebase when relevant.',
+            '6. Think about: correctness, maintainability, performance, failure modes, migration path.',
             '',
-            '## What to return',
-            '- RECOMMENDATION: what to do (one clear answer, not "it depends")',
-            '- REASONING: why this approach wins over alternatives (2-3 sentences)',
+            '## Decision output format',
+            'For a decision task, structure your response as:',
+            '- OPTIONS: for each option — pros / cons / risks / reversibility',
+            '- RECOMMENDATION: the chosen option (one clear answer, not "it depends")',
+            '- RATIONALE: one paragraph — why this option wins and what assumptions you are making',
             '- PLAN: step-by-step implementation instructions specific enough for the writer agent',
             '- RISKS: what could go wrong and how to mitigate',
-            '- If the problem is genuinely ambiguous, say what additional information would resolve it',
+            '',
+            '## Research-review gate',
+            'When reviewing a researcher\'s findings, judge whether the research is COMPLETE and well-sourced against the original task. If it is, pass it. If it\'s thin, missing sources, or the answer likely lives somewhere the researcher didn\'t look, report that it needs more — so the orchestrator sends the researcher back.',
+            'End every research review with exactly one of:',
+            '  GATE: PASS',
+            '  GATE: NEEDS-MORE — <what\'s missing / where to look>',
             '',
             '## What NOT to do',
             '- Do NOT edit or write files — return a plan for the writer agent',
             '- Do NOT give wishy-washy "both options are valid" non-answers — commit to a recommendation',
+            '- Do NOT consume raw session dumps; ask the orchestrator for a structured summary instead',
             '- If you need more information, ask the main agent to delegate to the researcher',
             '',
             '## When to use / handoff',
@@ -312,23 +325,35 @@ export const NAMED_AGENTS = {
             'Execute test suites, build commands, and linters. Interpret failures clearly.',
             'You are a quality gate — find out whether the code works, and say exactly what broke.',
             '',
+            '## Backward-compatibility / regression mandate (CRITICAL)',
+            'Existing test suites MUST still pass — any pre-existing test that breaks is a BLOCKER; report it as such.',
+            'The public API surface (function signatures, exported types, return shapes, behavior) must NOT silently change.',
+            'Flag any change that could break existing callers, even if no test currently covers it.',
+            '',
             '## How to work',
             '1. Identify the correct test / build command from package.json, Makefile, or the task brief.',
-            '2. Run it with Bash. Capture stdout + stderr in full.',
-            '3. If a command fails, read the relevant source files to locate the root cause.',
-            '4. Cap yourself at 6-8 tool calls unless the investigation clearly requires more.',
+            '2. Run the FULL existing test suite first to establish the regression baseline.',
+            '3. Generate and run tests targeted at the SPECIFIC diff/change provided — at both unit and integration levels where relevant.',
+            '4. Exercise edge cases: boundary values, empty inputs, error/exception paths, null/undefined.',
+            '5. Execution loop: write test → run it → read failure output → fix the test OR flag as a real bug in the code. Do NOT silently paper over a real defect.',
+            '6. If a command fails, read the relevant source files to locate the root cause.',
+            '7. Cap yourself at 6-8 tool calls unless the investigation clearly requires more.',
             '',
             '## What to return',
             '- RESULT: PASS or FAIL (one word, first line)',
-            '- COMMAND: the exact command you ran',
+            '- COMMAND: the exact command(s) you ran',
             '- OUTPUT: relevant excerpt (errors, failing test names, line numbers)',
             '- ROOT CAUSE: your diagnosis of why it failed (if applicable)',
+            '- TEST FILES: path(s) to any test files written or modified',
+            '- COVERAGE DELTA: what the change adds or leaves uncovered (before vs after where determinable); list notable uncovered lines/paths',
+            '- REGRESSIONS / COMPAT BREAKS: explicit list of any pre-existing tests that now fail or API changes that could break existing callers — tag each as BLOCKER',
             '- What you checked but found to be unrelated',
             '',
             '## What NOT to do',
-            '- Do NOT edit or write files — report failures so the writer agent can fix them',
+            '- Do NOT edit or write production files — report failures so the writer agent can fix them',
             '- Do NOT run destructive commands (no rm, no git push, no npm publish)',
             '- Do NOT guess at fixes — diagnose only',
+            '- Do NOT paper over a real defect by weakening or skipping a test',
             '',
             '## When to use / handoff',
             'Invoked in PARALLEL with reviewer, immediately after the writer returns a change.',
@@ -381,53 +406,78 @@ export const NAMED_AGENTS = {
         description: [
             'Code-review agent (Opus). Use for: the VERIFY step in a generator-verifier loop — after the',
             'writer completes a change, the reviewer reads the diff, checks correctness, spec/requirement',
-            'adherence, obvious bugs, and security issues, then returns an ACCEPT or REJECT verdict with',
-            'specific, actionable feedback. Does NOT edit files — reports so the writer can fix.',
+            'adherence, obvious bugs, and security issues, then tags each finding BLOCKER/MAJOR/MINOR/NIT',
+            'and returns an ACCEPT or REJECT verdict with specific, actionable feedback. May write documentation files (.md etc.) only.',
         ].join(' '),
-        tools: ['Read', 'Glob', 'Grep', 'Bash'],
+        tools: ['Read', 'Glob', 'Grep', 'Bash', 'Write', 'Edit'],
         model: 'opus',
         prompt: [
             'You are Osborn\'s reviewer agent. You are the VERIFY step in a generator-verifier loop.',
             '',
             '## Your role',
             'Read the writer\'s completed change (via git diff or by reading modified files), then produce',
-            'a structured verdict: ACCEPT or REJECT. You do NOT edit files — you report findings so the',
-            'single writer agent can fix them. You are the quality gate between a change and merge.',
+            'a structured verdict: ACCEPT or REJECT. You report findings so the single writer agent can fix code.',
+            'You may write documentation files (.md/.txt/etc.) only. You are the quality gate between a change and merge.',
             '',
             '## Bash is read-only inspection only',
             'You may run: git diff, git log, git status, git show, npm run build, npm test, eslint,',
             'tsc --noEmit, and similar lint/test/security-scan commands.',
             'You must NOT run: rm, git push, git commit, git add, npm publish, or any destructive command.',
             '',
+            '## Step 0 — Discover and adopt project standards (before reviewing)',
+            'Look for existing project standards, conventions, and documentation: CLAUDE.md, AGENTS.md,',
+            'docs/, README, style guides, and any gotchas/anti-pattern/decision notes in the repo or',
+            'session memory. If present, ADOPT them as the standard you review against — check the change',
+            'against these project-specific conventions and known past gotchas, not just generic best-practice.',
+            'If NO such files exist, note that in your report and fall back to the task spec + general best-practice.',
+            '',
+            '## Maintain documentation',
+            'You MAY create and maintain project standards and conventions files. Specifically: adopt an existing',
+            'standards doc if one is found, or create one (e.g. CONVENTIONS.md, docs/standards.md) when none exists',
+            'and the review reveals patterns worth recording. Keep documentation current as you review.',
+            'RESTRICTION: you may ONLY write files with documentation extensions: .md, .markdown, .mdx, .txt, .rst, .adoc.',
+            'You must NEVER write code, config, or source files (.ts, .js, .json, .env, etc.) — the write gate',
+            'enforces this at the system level and will deny any such attempt.',
+            '',
             '## How to work',
             '1. Run `git diff` (or read the files listed in the task) to see exactly what changed.',
             '2. Read any file that needs context to evaluate the diff (interfaces, callers, tests).',
             '3. Run the build or test suite if available to catch compile/runtime regressions.',
-            '4. Check against the spec or requirement provided in the task brief.',
+            '4. Check against the spec or requirement provided in the task brief AND any project standards found above.',
             '5. Look for: logic errors, missing edge cases, security issues (injection, path traversal,',
             '   credential exposure), broken types, spec deviations, unintended side-effects.',
             '6. Cap yourself at 10 tool calls unless the review clearly requires more.',
             '',
+            '## Severity taxonomy',
+            'Tag EVERY finding with exactly one of:',
+            '  BLOCKER — incorrect behavior, data loss, security hole, broken build; must fix before merge',
+            '  MAJOR   — significant bug or spec deviation that will likely cause real problems in use',
+            '  MINOR   — non-critical defect or missed edge case worth fixing but not blocking',
+            '  NIT     — style, naming, or polish; never a reason to REJECT on its own',
+            '',
             '## What to return',
             'Structure your response EXACTLY as follows:',
             '',
-            'VERDICT: ACCEPT | REJECT',
+            'VERDICT: ACCEPT | REJECT  — <one-line rationale>',
             '',
-            'ISSUES (each on its own line, only present if VERDICT is REJECT):',
-            '  - <file>:<line> — <concise description of the problem and why it matters>',
+            'ISSUES (omit section entirely if VERDICT is ACCEPT):',
+            '  [SEVERITY] <file>:<line>',
+            '  Evidence: "<short quote of the offending code>"',
+            '  Impact: <what breaks or why it matters>',
+            '  Fix: <recommended change>',
+            '  Verify: <how to confirm the fix is correct>',
             '',
             'WHAT IT CHECKED-AND-CLEARED:',
             '  - <each item you verified and found correct — be specific, not generic>',
             '',
             '## What NOT to do',
-            '- Do NOT edit or write any files — issue reports only; the writer fixes',
+            '- Do NOT write code, config, or source files — only documentation-extension files (.md/.markdown/.mdx/.txt/.rst/.adoc) are permitted',
             '- Do NOT run destructive commands (no rm, no git push, no git commit, no npm publish)',
             '- Do NOT approve a change that has a real defect just to be agreeable',
-            '- Do NOT raise trivial style nits as REJECT-worthy issues unless they break functionality',
+            '- Do NOT REJECT solely on NIT-level findings',
             '',
             '## When to use / handoff',
             'Invoked in PARALLEL with tester, immediately after the writer returns a change.',
-            'Return an ACCEPT or REJECT verdict with specific, actionable issue reports.',
             'The orchestrator waits for both reviewer and tester before synthesizing and speaking to the user.',
         ].join('\n'),
     },
@@ -505,6 +555,9 @@ export class ClaudeLLM extends llm.LLM {
     // Active queries — multiple can be running (SDK queues them internally).
     // We keep ALL references so interrupt() can stop whatever is currently executing.
     #activeQueries = new Set();
+    // Dispatcher v1 — maps tool_use_id → subagent_type for Task tool_use blocks
+    // so that when task_summary fires we know which agent type just finished.
+    #dispatchAgentTypes = new Map();
     constructor(opts = {}) {
         super();
         // Session resume/continue options
@@ -1039,6 +1092,29 @@ export class ClaudeLLM extends llm.LLM {
                                 callbacks.eventEmitter.emit('tts_say', { text: ttsChunk });
                             }
                         }
+                        // Dispatcher v1 — record Task tool_use blocks so we can correlate
+                        // the matching task_summary message to the subagent type.
+                        if (block.type === 'tool_use' && block.name === 'Task') {
+                            console.log('[DISPATCH-PROBE] task tool_use', JSON.stringify({ id: block.id, subagent_type: block.input?.subagent_type }));
+                            this.#dispatchAgentTypes.set(block.id, block.input?.subagent_type);
+                            statusManager.upsertDispatch(block.id, {
+                                owner: 'orchestrator',
+                                subagentType: block.input?.subagent_type,
+                                dispatchState: 'running',
+                            });
+                        }
+                    }
+                }
+                // Dispatcher v1 — catch sub-agent completion signals
+                if (msg.type === 'system' && msg.subtype === 'task_summary') {
+                    console.log('[DISPATCH-PROBE] task_summary raw:', JSON.stringify(msg).slice(0, 500));
+                    const tuid = msg.tool_use_id ?? msg.toolUseId;
+                    const output = msg.summary ?? msg.result ?? msg.output ?? '';
+                    const subType = tuid ? this.#dispatchAgentTypes.get(tuid) : undefined;
+                    statusManager.upsertDispatch(tuid ?? `ts-${Date.now()}`, { subagentType: subType, dispatchState: 'completed', artifact: String(output) });
+                    console.log(`[DISPATCH] completed type=${subType ?? '?'} tuid=${(tuid ?? '?').slice(0, 8)} len=${String(output).length}`);
+                    if (subType === 'writer' && output) {
+                        this.#spawnReviewer(tuid, String(output), callbacks.eventEmitter);
                     }
                 }
                 // Result — marks end of a turn (but we keep consuming for next turn)
@@ -1067,6 +1143,56 @@ export class ClaudeLLM extends llm.LLM {
             console.log('🔒 Persistent session background consumer exited');
         }
     }
+    /**
+     * Dispatcher v1 — auto-spawn a reviewer after a writer sub-agent completes.
+     * Runs a one-shot query() with the reviewer agent and emits dispatch_rejected
+     * if the verdict is REJECT. A reviewer failure must never crash the consumer.
+     */
+    async #spawnReviewer(tuid, writerOutput, emitter) {
+        try {
+            const prompt = [
+                'Use the reviewer sub-agent to review this writer output for correctness/spec-adherence/obvious bugs.',
+                'End your reply with exactly `VERDICT: ACCEPT` or `VERDICT: REJECT`.',
+                '',
+                '<writer_output>',
+                writerOutput.slice(0, 8000),
+                '</writer_output>',
+            ].join('\n');
+            const reviewerOptions = {
+                cwd: this.#opts.workingDirectory,
+                permissionMode: 'default',
+                agents: NAMED_AGENTS,
+            };
+            console.log(`[DISPATCH] spawning reviewer for tuid=${tuid.slice(0, 8)}`);
+            const reviewerQuery = query({ prompt, options: reviewerOptions });
+            this.#activeQueries.add(reviewerQuery);
+            let reviewerText = '';
+            try {
+                for await (const msg of reviewerQuery) {
+                    const m = msg;
+                    if (m.type === 'result' && m.result) {
+                        reviewerText = String(m.result);
+                    }
+                }
+            }
+            finally {
+                this.#activeQueries.delete(reviewerQuery);
+            }
+            const verdictMatch = reviewerText.match(/VERDICT:\s*(ACCEPT|REJECT)/i);
+            const verdict = verdictMatch ? verdictMatch[1].toUpperCase() : null;
+            if (verdict === 'REJECT') {
+                console.log(`[DISPATCH] review REJECT for tuid=${tuid.slice(0, 8)}`);
+                statusManager.upsertDispatch(tuid, { dispatchState: 'rejected', artifact: reviewerText });
+                emitter.emit('dispatch_rejected', { tuid, verdict: 'REJECT', review: reviewerText });
+            }
+            else {
+                console.log(`[DISPATCH] review ACCEPT for tuid=${tuid.slice(0, 8)}`);
+            }
+        }
+        catch (err) {
+            console.error('[DISPATCH] reviewer spawn failed (non-fatal):', err);
+        }
+    }
     chat({ chatCtx, toolCtx, connOptions = DEFAULT_API_CONNECT_OPTIONS, abortController, }) {
         return new ClaudeLLMStream(this, {
             chatCtx,
@@ -1285,6 +1411,21 @@ class ClaudeLLMStream extends llm.LLMStream {
                                             this.#eventEmitter.emit('tool_use', { name: toolName, input: toolInput, agentRole: agentType || 'main' });
                                             return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask' } };
                                         }
+                                        // Reviewer agent: ONLY documentation-extension files allowed — fail closed
+                                        if (agentType === 'reviewer') {
+                                            const reviewerPath = String(toolInput.file_path || '');
+                                            const DOC_EXTENSIONS = /\.(md|markdown|mdx|txt|rst|adoc)$/i;
+                                            if (!reviewerPath || !DOC_EXTENSIONS.test(reviewerPath)) {
+                                                const reason = reviewerPath
+                                                    ? `Reviewer write denied: ${reviewerPath} is not a documentation file (.md/.markdown/.mdx/.txt/.rst/.adoc). Reviewer may only write documentation.`
+                                                    : 'Reviewer write denied: could not determine target file path. Failing closed.';
+                                                console.log(`🚫 Reviewer write blocked: ${reviewerPath || '(no path)'} — not a doc extension`);
+                                                this.#eventEmitter.emit('tool_blocked', { name: toolName, reason });
+                                                return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' }, reason };
+                                            }
+                                            console.log(`📝 Reviewer doc write allowed: ${reviewerPath}`);
+                                            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask' } };
+                                        }
                                         // All other agents (main, researcher, reasoner, etc.): workspace only
                                         const filePath = String(toolInput.file_path || '');
                                         if (filePath && !filePath.includes('/osb/') && !filePath.includes('.osborn/sessions/') && !filePath.includes('.osborn/research/')) {

package/dist/index.js

@@ -3086,6 +3086,16 @@ async function main() {
                 checkpointId: data.checkpointId,
             });
         });
+        // Dispatcher v1 — writer reviewer rejected verdict → frontend
+        directLLM.events.on('dispatch_rejected', (data) => {
+            console.log(`[DISPATCH] dispatch_rejected tuid=${(data.tuid ?? '').slice(0, 8)} sending to frontend`);
+            sendToFrontend({
+                type: 'task_review',
+                tuid: data.tuid,
+                verdict: data.verdict,
+                review: data.review,
+            });
+        });
         // Create the Agent with instructions, STT, LLM, TTS
         // VAD (Silero ONNX) removed — caused 2-5s inference lag on CPU, making interruption detection worse
         // Turn detection is server-side (Deepgram endpointing), interruptions handled by STT

package/dist/pipeline-direct-llm.js

@@ -25,7 +25,7 @@ function buildSessionTail(sessionId, workingDir) {
         return '';
     if (!sessionId)
         return '';
-    const maxLines = parseInt(process.env.OSBORN_SESSION_TAIL_COUNT || '2000', 10);
+    const maxLines = parseInt(process.env.OSBORN_SESSION_TAIL_COUNT || '3000', 10);
     try {
         const indexPath = getIndexPath(sessionId, workingDir);
         if (!indexPath)

package/dist/status-manager.d.ts

@@ -18,6 +18,10 @@ export interface TaskStatus {
     progress?: number;
     progressUpdates: string[];
     lastUpdate?: string;
+    owner?: string;
+    subagentType?: string;
+    dispatchState?: 'pending' | 'running' | 'completed' | 'rejected' | 'failed';
+    artifact?: string;
 }
 export interface StatusUpdate {
     hasUpdates: boolean;
@@ -86,5 +90,16 @@ export declare class StatusManager {
      * Get context summary for the brain
      */
     getContextSummary(): string;
+    /**
+     * Dispatcher v1 — create or update a dispatch entry keyed by tool_use_id.
+     * Creates a minimal TaskStatus shell if the id doesn't yet exist so callers
+     * can upsert without a prior registerTask() call.
+     */
+    upsertDispatch(id: string, fields: {
+        owner?: string;
+        subagentType?: string;
+        dispatchState?: TaskStatus['dispatchState'];
+        artifact?: string;
+    }): void;
 }
 export declare const statusManager: StatusManager;

package/dist/status-manager.js

@@ -182,6 +182,48 @@ export class StatusManager {
     getContextSummary() {
         return this.conversationContext.slice(-5).join(' | ');
     }
+    /**
+     * Dispatcher v1 — create or update a dispatch entry keyed by tool_use_id.
+     * Creates a minimal TaskStatus shell if the id doesn't yet exist so callers
+     * can upsert without a prior registerTask() call.
+     */
+    upsertDispatch(id, fields) {
+        if (!this.tasks.has(id)) {
+            this.tasks.set(id, {
+                id,
+                type: 'execute',
+                // Use an empty query so narration never speaks a bogus "dispatch:<id>" string.
+                // Dispatch progress is tracked exclusively via dispatchState; status starts as
+                // 'pending' (not 'running') so getStatusUpdate() runningTasks narration is skipped.
+                query: '',
+                status: 'pending',
+                startedAt: Date.now(),
+                progressUpdates: [],
+            });
+        }
+        const task = this.tasks.get(id);
+        if (fields.owner !== undefined)
+            task.owner = fields.owner;
+        if (fields.subagentType !== undefined)
+            task.subagentType = fields.subagentType;
+        if (fields.dispatchState !== undefined)
+            task.dispatchState = fields.dispatchState;
+        if (fields.artifact !== undefined)
+            task.artifact = fields.artifact;
+        // Mirror dispatchState into the base status field so existing getStatusUpdate() callers see it.
+        // 'rejected' is also terminal — map it to 'failed' so the GC and readers treat it as finished.
+        if (fields.dispatchState === 'completed')
+            task.status = 'completed';
+        if (fields.dispatchState === 'failed' || fields.dispatchState === 'rejected')
+            task.status = 'failed';
+        // Fix: set completedAt when entering any terminal state so the task is GC-eligible via
+        // clearReportedTasks() and correctly surfaces in hasCompletedTasks() / getStatusUpdate().
+        // Without this the tasks Map grows unbounded (memory leak).
+        const isTerminal = task.status === 'completed' || task.status === 'failed';
+        if (isTerminal && !task.completedAt)
+            task.completedAt = Date.now();
+        console.log(`[Dispatch] upsertDispatch id=${id.slice(0, 8)} state=${fields.dispatchState ?? '-'} type=${fields.subagentType ?? '-'}`);
+    }
 }
 // Singleton instance
 export const statusManager = new StatusManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osborn",
-  "version": "0.9.141",
+  "version": "0.9.143",
   "description": "Voice AI coding assistant - local agent that connects to Osborn frontend",
   "type": "module",
   "bin": {