ai-whisper 0.1.3 → 0.2.0

package/README.md

@@ -50,6 +50,20 @@ It is **not** for:
 - invisible background automation you never watch.
 - people new to coding agents looking for a guided, hand-holding experience.
 
+## Prerequisites
+
+ai-whisper drives the *real* Claude and Codex CLIs, so you need both installed and authenticated first:
+
+- **[Claude Code CLI](https://claude.com/claude-code)** — the `claude` command, signed in.
+- **[Codex CLI](https://github.com/openai/codex)** — the `codex` command, signed in.
+- **Node.js 22+**.
+- **An LLM evaluator with credentials** — workflows are gated by it and refuse to start without it. See [Evaluator configuration](docs/evaluator-configuration.md).
+- **tmux** *(optional)* — only for `whisper collab start`, which auto-arranges both agents into panes. The mount flow below does not need it.
+
+## Safety & permissions
+
+ai-whisper launches each agent in **full-autonomy mode** so the relay can drive it unattended — `claude --dangerously-skip-permissions` and `codex --dangerously-bypass-approvals-and-sandbox`. Inside the mounted workspace the agents read, write, and run commands without prompting. Point it at code you're willing to let two agents change autonomously, watch the run on the dashboard, and remember you are the final gatekeeper — review the result before you ship it. The deeper rationale is in [Concepts](docs/concepts.md).
+
 ## Quickstart
 
 Install from npm:
@@ -90,6 +104,10 @@ whisper collab dashboard
 
 > Running from a repo checkout instead of a packaged install? Build first (`pnpm build`) and invoke the CLI as `node packages/cli/dist/bin/whisper.js ...` wherever these examples say `whisper ...`.
 
+## What happens if it fails?
+
+A run that stops short usually **escalates** — it does not crash. When the evaluator can't resolve a phase (the round budget is spent, an agent reports it's blocked, or confidence stays too low), the loop halts and turn ownership returns to you. That's a designed exit, not a failure: run state is durable, so you read the dashboard, fix the spec or unblock the agent, and `whisper workflow resume <id>` to pick up where it left off. Escalation is the system asking for a human exactly when it should — seeing it is normal, not a sign something broke.
+
 ## Core concepts
 
 ai-whisper is **not a swarm**. The agents never type at once — work moves by a single baton, one owner at a time. Mounted sessions are *real* Claude and Codex sessions in your terminal, and those sessions are the source of truth. Autonomy is supervised: every handoff, verdict, and round is inspectable, and runs are resumable rather than fire-and-forget. Work is organized as structured workflows — explicit loops and state transitions, not a free-form chat.

package/dist/bin/broker-daemon.js

@@ -2025,6 +2025,36 @@ Findings:           (omit this block entirely if none)
 Non-blocking risks:
 - <quality risk that does NOT block this gate, or "None.">
 --- end protocol ---`;
+var WORKFLOW_DIAGNOSIS_PROTOCOL = `--- ai-whisper diagnosis review protocol ---
+You are the gatekeeper for an ai-whisper complex-bug-fixing DIAGNOSIS gate. No human is in the loop. Do NOT trust the implementer's diagnosis \u2014 verify it yourself. The gate stays shut until YOU independently agree on the root cause and that the fix is net-safe.
+
+Required procedure:
+1. Independently reproduce: re-run the implementer's reproduction yourself; do not trust pasted output. If YOU cannot reproduce it, that is a blocking finding (the repro is not real/reliable). Speculation from reading code paths is not a valid reproduction.
+2. Attack the causal claim: is the cause PROVEN by the evidence chain, or merely asserted? Could the named cause be a correlate, or a symptom of something deeper? Demand any missing link.
+3. Attack the fix (anti-whack-a-mole): does the proposed fix remove the root cause, or just this symptom's surface? Could the bug resurface through another path? Name it if so.
+4. Attack the blast radius: is every affected area/module/contract listed? Add what is missing.
+5. Attack residual risks: are the real foreseeable risks named, or hand-waved?
+6. Mutual-agreement gate: approve ONLY when you have independently confirmed the reproduction and agree the cause is proven and the fix is net-safe (fixes more than it risks). "Plausible" is not approval.
+
+Severity: a blocking finding must tie to a concrete diagnosis-contract item (unreproducible repro, unproven cause, symptom-masking fix, incomplete blast radius, un-named risk). Suppress style/taste. Do NOT gag valuable non-contract risk signals \u2014 surface them under "Non-blocking risks:" (always last) so they reach the human at escalation/completion.
+
+Findings vs escalation: a fixable defect in the diagnosis is a FINDING (loops back for revision) \u2014 do NOT say you "cannot proceed" for a defect you can describe. ESCALATE only when you genuinely cannot review (a required reproduction input is absent and is not the implementer's to supply).
+
+Never reply with only a bare verdict; your full reply must be well over 100 characters.
+
+Output format \u2014 the verdict line MUST come before the Non-blocking risks section, which is always LAST:
+Diagnosis review matrix:
+| Claim | Required evidence | Implementer evidence | Independently verified? | Result |
+| ... |
+
+Findings:           (omit this block entirely if none)
+- <blocking finding tied to an exact diagnosis-contract item, with evidence>
+
+<verdict line: "Approved. <one or two sentences>" OR, when blocked/cannot-proceed, state you cannot proceed and why>
+
+Non-blocking risks:
+- <risk that does NOT block this gate, or "None.">
+--- end protocol ---`;
 var SDD_SPEC_REVIEW = "Review the spec at {specPath}. This is an autonomous workflow with no human in the loop.\n\n" + WORKFLOW_REVIEW_PROTOCOL;
 var SDD_CODE_REVIEW = "Review the implementer's changes for this phase \u2014 the commits in {commitRange}. The upper bound is a LIVE `HEAD`: resolve it against the current repository at review time and INCLUDE any commits added during this review round (e.g. fixes for your prior findings); do not pin the review to an earlier tip. Verify against the spec's acceptance criteria and run the project's verification/tests. This is an autonomous workflow with no human in the loop.\n\n" + WORKFLOW_REVIEW_PROTOCOL;
 var SPEC_DRIVEN_DEVELOPMENT = {
@@ -2145,13 +2175,113 @@ var RALPH_LOOP = {
     }
   ]
 };
+var BUGFIX_DIAGNOSIS_KICKOFF = `You are the implementer in an autonomous complex-bug-fixing workflow. No human is in the loop \u2014 never ask for confirmation, permission, or clarification; do the work yourself.
+
+Read the bug report at {specPath}. A human (dev or QA) already observed this bug, so you must reproduce it too \u2014 do NOT theorize from reading code paths.
+
+Write a diagnosis artifact to {diagnosisPath} (create the file) with these sections:
+1. Reproduction \u2014 an ACTUALLY OBSERVED reproduction you ran yourself. Strongly prefer a failing test (RED) failing for the right reason; commit that test in THIS phase. If the project supports e2e/real-browser (e.g. Playwright), use it. Only if no automated test can capture it, give command/log output WITH an explicit justification.
+2. Root cause \u2014 the causal chain symptom\u2192cause, each link backed by concrete evidence (stack trace, log line, failing assertion, bisect), not assertion.
+3. Proposed fix approach \u2014 what changes and WHY that removes the root cause rather than masking the symptom.
+4. Blast radius \u2014 every area/module/contract the fix could affect.
+5. Residual risks \u2014 foreseeable risks remaining after the fix.
+
+Commit the RED reproduction test (do NOT commit {bugfixDir}; it is gitignored). End your handback with a 1-2 sentence summary; your reply must be at least two sentences, well over 100 characters \u2014 never hand back only a single word.`;
+var BUGFIX_DIAGNOSIS_REVIEW = "Review the diagnosis artifact at {diagnosisPath} for the bug reported at {specPath}. This is an autonomous workflow with no human in the loop.\n\n" + WORKFLOW_DIAGNOSIS_PROTOCOL;
+var BUGFIX_DIAGNOSIS_FIX = "Apply the reviewer's findings to the diagnosis at {diagnosisPath} now. This is an autonomous workflow \u2014 no human will respond. Make the edits yourself (re-reproduce if needed) and hand back the corrected diagnosis; never ask for confirmation, permission, or clarification. If you added or changed the RED reproduction test while addressing the findings, COMMIT it in this round (do NOT commit {bugfixDir}; it is gitignored) \u2014 the next phase reviews the committed change set, so an uncommitted repro update would be invisible to it. End your handback with a 1-2 sentence summary of what you changed; your reply must be at least two sentences, well over 100 characters \u2014 never hand back only a single word.";
+var BUGFIX_FIX_KICKOFF = `The diagnosis at {diagnosisPath} is APPROVED \u2014 treat it as ground truth (re-orient from it, not prior conversation). This is an autonomous workflow \u2014 no human will respond; do the work yourself.
+
+1. Implement the fix per the APPROVED approach.
+2. Turn the reproduction GREEN \u2014 the failing test now passes for the right reason; if the repro was a non-test demonstration, re-run it and show the symptom is gone.
+3. Run the project's verification/test command PLUS targeted checks across the declared blast radius, including the full suite, to catch regressions.
+4. Commit the fix and any added happy-path/edge-case coverage tests (the RED test was committed in diagnosis). Do NOT commit {bugfixDir} (gitignored).
+
+If you discover the approved cause was WRONG, do NOT silently switch to a different fix \u2014 the cause was the agreed premise of this run. Stop and hand back that you CANNOT PROCEED because the approved cause is wrong, explaining what the evidence now shows; do not deliver a fix built on a second, unreviewed theory. This halts the run and returns control to a human, who re-opens the diagnosis (a new run, or a resume after they adjust the report) \u2014 the workflow does not loop back to the diagnosis phase on its own. Otherwise, hand back the commit SHAs + verification output + a 1-2 sentence summary; your reply must be at least two sentences, well over 100 characters.`;
+var BUGFIX_FIX_REVIEW = "The implementer claims the fix for the bug at {specPath} is complete \u2014 the changes are commits {commitRange}; resolve the upper bound against LIVE HEAD and include fix-round commits. Verify against the APPROVED diagnosis at {diagnosisPath}. Independently re-run the reproduction (it must be GREEN) and the verification suite \u2014 do not trust pasted output. Confirm: the root cause is actually removed (not just relocated \u2014 anti-whack-a-mole); every declared blast-radius area is regression-free; residual risks are handled or explicitly accepted; and COVERAGE is adequate \u2014 every happy path has at least one covering test and edge cases are covered. A case that genuinely cannot be covered must be explicitly noted (not silently passed); thin coverage is a blocking finding. This is an autonomous workflow with no human in the loop.\n\n" + WORKFLOW_REVIEW_PROTOCOL;
+var BUGFIX_FIX_FIX = "Apply the reviewer's findings to commits {commitRange} now (amend or add commits). This is an autonomous workflow \u2014 no human will respond. Do the work yourself and hand back the updated commit SHAs and verification output; never ask for confirmation, permission, or clarification. End your handback with a 1-2 sentence summary; your reply must be at least two sentences, well over 100 characters.";
+var BUGFIX_POSTMORTEM_KICKOFF = "Write a post-mortem report to {postmortemPath} (create the file) for the bug fixed in this run. This is an autonomous workflow \u2014 no human will respond; do the work yourself. Recap: confirmed root cause; the fix applied; reproduction\u2192GREEN evidence; blast radius touched; coverage gaps explicitly listed (carried from the fix review); residual risks; and lessons learned. Do NOT commit {bugfixDir} (gitignored). End your handback with a 1-2 sentence summary; your reply must be at least two sentences, well over 100 characters.";
+var BUGFIX_POSTMORTEM_REVIEW = "Review the post-mortem report at {postmortemPath}. Confirm it faithfully reflects what actually happened in this run \u2014 confirmed cause, the fix, the noted coverage gaps, and residual risks are all present and honest. This is not a rubber stamp; gloss-overs or omissions are findings. This is an autonomous workflow with no human in the loop.\n\n" + WORKFLOW_REVIEW_PROTOCOL;
+var BUGFIX_POSTMORTEM_FIX = "Apply the reviewer's findings to the post-mortem at {postmortemPath} now. This is an autonomous workflow \u2014 no human will respond. Make the edits yourself and hand back the corrected report; never ask for confirmation, permission, or clarification. End your handback with a 1-2 sentence summary; your reply must be at least two sentences, well over 100 characters.";
+var COMPLEX_BUG_FIXING = {
+  type: "complex-bug-fixing",
+  displayName: "Complex Bug Fixing",
+  description: "Reproduce \u2192 adversarially-gated diagnosis \u2192 fix & verify \u2192 post-mortem, for a reported bug whose root cause is unknown",
+  defaultImplementer: "claude",
+  defaultReviewer: "codex",
+  phases: [
+    {
+      name: "diagnosis",
+      implementerRole: "implementer",
+      reviewerRole: "reviewer",
+      maxRounds: 5,
+      initialHandoffStep: "implement",
+      kickoffTemplate: BUGFIX_DIAGNOSIS_KICKOFF,
+      stepTemplates: {
+        implement: BUGFIX_DIAGNOSIS_KICKOFF,
+        review: BUGFIX_DIAGNOSIS_REVIEW,
+        fix: BUGFIX_DIAGNOSIS_FIX
+      },
+      reviewMode: "phase-review",
+      evaluatorPromptKey: "review-loop",
+      artifactOut: { kind: "spec", pathTemplate: "{diagnosisPath}" },
+      anchorCommitBaseOnEntry: true,
+      renderFixTemplateOnFindings: true
+    },
+    {
+      name: "fix-and-verify",
+      implementerRole: "implementer",
+      reviewerRole: "reviewer",
+      maxRounds: 5,
+      initialHandoffStep: "implement",
+      kickoffTemplate: BUGFIX_FIX_KICKOFF,
+      stepTemplates: {
+        implement: BUGFIX_FIX_KICKOFF,
+        review: BUGFIX_FIX_REVIEW,
+        fix: BUGFIX_FIX_FIX
+      },
+      reviewMode: "acceptance-review",
+      evaluatorPromptKey: "review-loop",
+      artifactOut: { kind: "commit-range" },
+      renderFixTemplateOnFindings: true
+    },
+    {
+      name: "post-mortem",
+      implementerRole: "implementer",
+      reviewerRole: "reviewer",
+      maxRounds: 3,
+      initialHandoffStep: "implement",
+      kickoffTemplate: BUGFIX_POSTMORTEM_KICKOFF,
+      stepTemplates: {
+        implement: BUGFIX_POSTMORTEM_KICKOFF,
+        review: BUGFIX_POSTMORTEM_REVIEW,
+        fix: BUGFIX_POSTMORTEM_FIX
+      },
+      reviewMode: "phase-review",
+      evaluatorPromptKey: "review-loop",
+      artifactOut: { kind: "spec", pathTemplate: "{postmortemPath}" },
+      renderFixTemplateOnFindings: true
+    }
+  ]
+};
 var REGISTRY = {
   [SPEC_DRIVEN_DEVELOPMENT.type]: SPEC_DRIVEN_DEVELOPMENT,
-  [RALPH_LOOP.type]: RALPH_LOOP
+  [RALPH_LOOP.type]: RALPH_LOOP,
+  [COMPLEX_BUG_FIXING.type]: COMPLEX_BUG_FIXING
 };
 function ralphRunDir(workspaceRoot, workflowId) {
   return join(workspaceRoot, ".ai-whisper", "ralph", workflowId);
 }
+function bugfixRunDir(workspaceRoot, workflowId) {
+  return join(workspaceRoot, ".ai-whisper", "bugfix", workflowId);
+}
+function bugfixPaths(workspaceRoot, workflowId) {
+  const bugfixDir = bugfixRunDir(workspaceRoot, workflowId);
+  return {
+    bugfixDir,
+    diagnosisPath: join(bugfixDir, "diagnosis.md"),
+    postmortemPath: join(bugfixDir, "postmortem.md")
+  };
+}
 function getWorkflowDefinition(type) {
   return REGISTRY[type];
 }
@@ -2371,12 +2501,16 @@ function createWorkflowControl(deps) {
     const collab2 = getCollab(db, input.workflow.collabId);
     const ralphDir = collab2 ? ralphRunDir(collab2.workspaceRoot, input.workflow.workflowId) : "";
     const reviewMode = useAcceptance ? "acceptance-review" : input.phase.reviewMode ?? "phase-review";
+    const bf = collab2 ? bugfixPaths(collab2.workspaceRoot, input.workflow.workflowId) : { bugfixDir: "", diagnosisPath: "", postmortemPath: "" };
     return renderTemplate(tmpl, {
       specPath: input.workflow.specPath,
       planPath: safeDerivePlanPath(input.workflow.specPath, input.workflow.createdAt),
       commitRange: liveReviewCommitRange(ctx),
       ralphDir,
-      reviewMode
+      reviewMode,
+      bugfixDir: bf.bugfixDir,
+      diagnosisPath: bf.diagnosisPath,
+      postmortemPath: bf.postmortemPath
     });
   }
   function createContinuationHandoff(input) {
@@ -2413,12 +2547,16 @@ function createWorkflowControl(deps) {
     const ctx = input.workflow.workflowContext;
     const collab2 = getCollab(db, input.workflow.collabId);
     const ralphDir = collab2 ? ralphRunDir(collab2.workspaceRoot, input.workflow.workflowId) : "";
+    const bf = collab2 ? bugfixPaths(collab2.workspaceRoot, input.workflow.workflowId) : { bugfixDir: "", diagnosisPath: "", postmortemPath: "" };
     const kickoffText = renderTemplate(phase.kickoffTemplate, {
       specPath: input.workflow.specPath,
       planPath: safeDerivePlanPath(input.workflow.specPath, input.workflow.createdAt),
       commitRange: liveReviewCommitRange(ctx),
       ralphDir,
-      reviewMode: phase.reviewMode ?? "phase-review"
+      reviewMode: phase.reviewMode ?? "phase-review",
+      bugfixDir: bf.bugfixDir,
+      diagnosisPath: bf.diagnosisPath,
+      postmortemPath: bf.postmortemPath
     });
     const chainId = `relay_ch_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
     const phaseRunId = `wfp_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
@@ -2676,15 +2814,19 @@ function createWorkflowControl(deps) {
       } else if (normalized.verdict === "findings") {
         const findingsText = input.followUpMessage ?? "Address the reviewer's findings.";
         let fixRequestText;
-        if (phase.repeatUntilComplete && phase.stepTemplates.fix) {
+        if ((phase.repeatUntilComplete || phase.renderFixTemplateOnFindings) && phase.stepTemplates.fix) {
           const ctx = workflow.workflowContext;
           const collab2 = getCollab(db, workflow.collabId);
           const ralphDir = collab2 ? ralphRunDir(collab2.workspaceRoot, workflow.workflowId) : "";
+          const bf = collab2 ? bugfixPaths(collab2.workspaceRoot, workflow.workflowId) : { bugfixDir: "", diagnosisPath: "", postmortemPath: "" };
           const fixTmpl = renderTemplate(phase.stepTemplates.fix, {
             specPath: workflow.specPath,
             planPath: safeDerivePlanPath(workflow.specPath, workflow.createdAt),
             commitRange: liveReviewCommitRange(ctx),
-            ralphDir
+            ralphDir,
+            bugfixDir: bf.bugfixDir,
+            diagnosisPath: bf.diagnosisPath,
+            postmortemPath: bf.postmortemPath
           });
           fixRequestText = `${fixTmpl}
 
@@ -4512,6 +4654,23 @@ function ensureRalphWorkspace(workspaceRoot, workflowId) {
   return dir;
 }
 
+// ../broker/dist/runtime/bugfix-setup.js
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, existsSync as existsSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+function ensureBugfixWorkspace(workspaceRoot, workflowId) {
+  const dir = bugfixRunDir(workspaceRoot, workflowId);
+  mkdirSync2(dir, { recursive: true });
+  const ignorePath = join3(workspaceRoot, ".ai-whisper", ".gitignore");
+  if (!existsSync3(ignorePath)) {
+    writeFileSync2(ignorePath, "*\n");
+  }
+  const bugfixIgnorePath = join3(workspaceRoot, ".ai-whisper", "bugfix", ".gitignore");
+  if (!existsSync3(bugfixIgnorePath)) {
+    writeFileSync2(bugfixIgnorePath, "*\n");
+  }
+  return dir;
+}
+
 // ../broker/dist/runtime/workflow-driver.js
 function createWorkflowDriver(deps) {
   const { broker: broker2, headReader } = deps;
@@ -4582,7 +4741,7 @@ function createWorkflowDriver(deps) {
     const sender = phase.initialHandoffStep === "review" ? implementerAgent : reviewerAgent;
     const target = phase.initialHandoffStep === "review" ? reviewerAgent : implementerAgent;
     let executionBaseHeadSha;
-    if (phase.initialHandoffStep === "execute") {
+    if (phase.initialHandoffStep === "execute" || phase.anchorCommitBaseOnEntry === true) {
       try {
         executionBaseHeadSha = await headReader.readHead(collab2.workspaceRoot);
       } catch (err) {
@@ -4605,6 +4764,15 @@ function createWorkflowDriver(deps) {
     } else {
       ralphDir = ralphRunDir(collab2.workspaceRoot, workflowId);
     }
+    if (workflow.workflowType === "complex-bug-fixing") {
+      try {
+        ensureBugfixWorkspace(collab2.workspaceRoot, workflowId);
+      } catch (err) {
+        broker2.control.haltWorkflow({ workflowId, reason: `bugfix setup failed: ${String(err)}`, now });
+        return;
+      }
+    }
+    const bugfix = bugfixPaths(collab2.workspaceRoot, workflowId);
     const ctx = workflow.workflowContext;
     let planPath = workflow.specPath;
     try {
@@ -4616,7 +4784,10 @@ function createWorkflowDriver(deps) {
       planPath,
       commitRange: ctx.commitRange ?? "HEAD",
       ralphDir,
-      reviewMode: phase.reviewMode ?? "phase-review"
+      reviewMode: phase.reviewMode ?? "phase-review",
+      bugfixDir: bugfix.bugfixDir,
+      diagnosisPath: bugfix.diagnosisPath,
+      postmortemPath: bugfix.postmortemPath
     });
     try {
       broker2.control.beginPhaseRun({
@@ -5548,7 +5719,7 @@ function writeOwnPidToBrokerDaemon(db, input) {
 
 // src/runtime/evaluator-config.ts
 import { readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 
 // src/runtime/state-root.ts
 import os from "node:os";
@@ -5607,15 +5778,15 @@ function loadEvaluatorConfig() {
   const root = getStateRoot();
   let dotenv = {};
   try {
-    dotenv = parseDotEnv(readFileSync2(join3(root, ".env"), "utf8"));
+    dotenv = parseDotEnv(readFileSync2(join4(root, ".env"), "utf8"));
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
   const envGet = (k) => process.env[k] ?? dotenv[k];
-  const authPath = join3(root, "auth.json");
+  const authPath = join4(root, "auth.json");
   warnIfLoosePerms(authPath);
   const auth = readJsonFile(authPath, "auth.json");
-  const config = readJsonFile(join3(root, "config.json"), "config.json");
+  const config = readJsonFile(join4(root, "config.json"), "config.json");
   const evalCfg = config?.evaluator ?? {};
   const evalOllama = evalCfg.ollama ?? {};
   const provider = (envGet("AI_WHISPER_EVALUATOR_PROVIDER") ?? evalCfg.provider) === "ollama" ? "ollama" : "anthropic";