ai-whisper 0.1.1 → 0.1.3

package/README.md

@@ -21,7 +21,7 @@ Run spec-driven-development using docs/spec.md
 
 From there ai-whisper runs the workflow autonomously:
 
-- **Implementer / reviewer assignment** — one agent is the implementer, the other the reviewer (for `spec-driven-development` the default is implementer = Claude, reviewer = Codex). The baton passes between them; only one owns the turn at a time.
+- **Implementer / reviewer assignment** — the agent you trigger the workflow from becomes the implementer and the other agent becomes the reviewer; pass `--implementer` / `--reviewer` to choose explicitly. (Started outside a mounted session with no flags, it falls back to a default pairing and warns.) The baton passes between them; only one owns the turn at a time.
 - **Autonomous execution** — the implementer does each step in its real session and hands the result back. An LLM evaluator judges whether the deliverable meets the request.
 - **Review loops** — when work isn't good enough yet, the reviewer's findings are composed into a follow-up handoff and the implementer iterates. The loop repeats until the work is approved or the round budget is exhausted.
 - **Resumability** — workflow and chain state is durable. If the broker restarts or you stop for the day, you recover and reconnect rather than starting over.
@@ -100,6 +100,7 @@ For the full mental model, read [Concepts](docs/concepts.md).
 
 ## Learn more
 
+- [Workflows](docs/workflows.md) — how to use the workflows well: choosing between `spec-driven-development` and `ralph-loop`, and authoring the spec or goal that drives the run.
 - [Concepts](docs/concepts.md) — the mental model: baton handoff, real mounted sessions, supervised autonomy, workflow-first execution.
 - [Relay & handoff flows](docs/relay-handoff-flows.md) — the complete handoff state machine, capture-status table, hotkey reference, per-step verdicts, and troubleshooting.
 - [Evaluator configuration](docs/evaluator-configuration.md) — required credentials and options for the LLM evaluator that gates workflows.

package/dist/bin/broker-daemon.js

@@ -1702,7 +1702,32 @@ function listActiveCollabSummaries(db, input) {
 			     OR EXISTS (SELECT 1 FROM workflows w
 			                 WHERE w.collab_id = c.collab_id AND w.status = 'running')`).all(cutoff);
   const out = [];
+  const seen = /* @__PURE__ */ new Set();
   for (const e of eligible) {
+    out.push(buildCollabSummary(db, e.collabId));
+    seen.add(e.collabId);
+  }
+  const minResults = input.minResults ?? 3;
+  if (out.length < minResults) {
+    const finished = db.prepare(`SELECT collab_id AS collabId, MAX(created_at) AS lastCreated
+				   FROM workflows
+				  WHERE status IN ('done','halted','canceled')
+				  GROUP BY collab_id
+				  ORDER BY lastCreated DESC, collab_id DESC`).all();
+    for (const f of finished) {
+      if (out.length >= minResults)
+        break;
+      if (seen.has(f.collabId))
+        continue;
+      out.push(buildCollabSummary(db, f.collabId));
+      seen.add(f.collabId);
+    }
+  }
+  return out;
+}
+function buildCollabSummary(db, collabId2) {
+  {
+    const e = { collabId: collabId2 };
     const collab2 = db.prepare(`SELECT display_name AS displayName, workspace_root AS workspaceRoot
 				   FROM collab WHERE collab_id = ?`).get(e.collabId);
     const wf = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,
@@ -1756,7 +1781,7 @@ function listActiveCollabSummaries(db, input) {
 						   FROM relay_handoff
 						  WHERE collab_id = ? AND workflow_id IS NULL`).get(e.collabId);
     const runLastAct = runLastActRow?.lastAct ?? "";
-    out.push({
+    return {
       collabId: e.collabId,
       label,
       workflowId: wf?.workflowId ?? null,
@@ -1775,9 +1800,8 @@ function listActiveCollabSummaries(db, input) {
       },
       sessions,
       lastActivityAt: runLastAct
-    });
+    };
   }
-  return out;
 }
 function listWorkflowsForCollab(db, collabId2) {
   const rows = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,

package/dist/bin/companion-agent.js

@@ -1735,7 +1735,32 @@ function listActiveCollabSummaries(db, input) {
 			     OR EXISTS (SELECT 1 FROM workflows w
 			                 WHERE w.collab_id = c.collab_id AND w.status = 'running')`).all(cutoff);
   const out = [];
+  const seen = /* @__PURE__ */ new Set();
   for (const e of eligible) {
+    out.push(buildCollabSummary(db, e.collabId));
+    seen.add(e.collabId);
+  }
+  const minResults = input.minResults ?? 3;
+  if (out.length < minResults) {
+    const finished = db.prepare(`SELECT collab_id AS collabId, MAX(created_at) AS lastCreated
+				   FROM workflows
+				  WHERE status IN ('done','halted','canceled')
+				  GROUP BY collab_id
+				  ORDER BY lastCreated DESC, collab_id DESC`).all();
+    for (const f of finished) {
+      if (out.length >= minResults)
+        break;
+      if (seen.has(f.collabId))
+        continue;
+      out.push(buildCollabSummary(db, f.collabId));
+      seen.add(f.collabId);
+    }
+  }
+  return out;
+}
+function buildCollabSummary(db, collabId) {
+  {
+    const e = { collabId };
     const collab = db.prepare(`SELECT display_name AS displayName, workspace_root AS workspaceRoot
 				   FROM collab WHERE collab_id = ?`).get(e.collabId);
     const wf = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,
@@ -1789,7 +1814,7 @@ function listActiveCollabSummaries(db, input) {
 						   FROM relay_handoff
 						  WHERE collab_id = ? AND workflow_id IS NULL`).get(e.collabId);
     const runLastAct = runLastActRow?.lastAct ?? "";
-    out.push({
+    return {
       collabId: e.collabId,
       label,
       workflowId: wf?.workflowId ?? null,
@@ -1808,9 +1833,8 @@ function listActiveCollabSummaries(db, input) {
       },
       sessions,
       lastActivityAt: runLastAct
-    });
+    };
   }
-  return out;
 }
 function listWorkflowsForCollab(db, collabId) {
   const rows = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,
@@ -5866,12 +5890,16 @@ function createNodePty(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath
   });
-  return spawn2(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn2(input.config.executable, input.config.execArgs, buildClaudePtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildClaudePtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "claude";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createClaudeLiveSession(input) {
   let pty = null;
@@ -6169,12 +6197,16 @@ function createNodePty2(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath2
   });
-  return spawn4(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn4(input.config.executable, input.config.execArgs, buildCodexPtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildCodexPtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "codex";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createCodexLiveSession(input) {
   let pty = null;

package/dist/bin/relay-monitor.js

@@ -1705,7 +1705,32 @@ function listActiveCollabSummaries(db, input) {
 			     OR EXISTS (SELECT 1 FROM workflows w
 			                 WHERE w.collab_id = c.collab_id AND w.status = 'running')`).all(cutoff);
   const out = [];
+  const seen = /* @__PURE__ */ new Set();
   for (const e of eligible) {
+    out.push(buildCollabSummary(db, e.collabId));
+    seen.add(e.collabId);
+  }
+  const minResults = input.minResults ?? 3;
+  if (out.length < minResults) {
+    const finished = db.prepare(`SELECT collab_id AS collabId, MAX(created_at) AS lastCreated
+				   FROM workflows
+				  WHERE status IN ('done','halted','canceled')
+				  GROUP BY collab_id
+				  ORDER BY lastCreated DESC, collab_id DESC`).all();
+    for (const f of finished) {
+      if (out.length >= minResults)
+        break;
+      if (seen.has(f.collabId))
+        continue;
+      out.push(buildCollabSummary(db, f.collabId));
+      seen.add(f.collabId);
+    }
+  }
+  return out;
+}
+function buildCollabSummary(db, collabId2) {
+  {
+    const e = { collabId: collabId2 };
     const collab = db.prepare(`SELECT display_name AS displayName, workspace_root AS workspaceRoot
 				   FROM collab WHERE collab_id = ?`).get(e.collabId);
     const wf = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,
@@ -1759,7 +1784,7 @@ function listActiveCollabSummaries(db, input) {
 						   FROM relay_handoff
 						  WHERE collab_id = ? AND workflow_id IS NULL`).get(e.collabId);
     const runLastAct = runLastActRow?.lastAct ?? "";
-    out.push({
+    return {
       collabId: e.collabId,
       label,
       workflowId: wf?.workflowId ?? null,
@@ -1778,9 +1803,8 @@ function listActiveCollabSummaries(db, input) {
       },
       sessions,
       lastActivityAt: runLastAct
-    });
+    };
   }
-  return out;
 }
 function listWorkflowsForCollab(db, collabId2) {
   const rows = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,
@@ -5076,7 +5100,9 @@ function computeLiveness(snap) {
   let why = null;
   let stuck = false;
   let liveOverride = null;
-  if (terminal === "halted" || terminal === "canceled") {
+  if (terminal === "done") {
+    return { stuck: false, why: null, liveText: "done" };
+  } else if (terminal === "halted" || terminal === "canceled") {
     stuck = true;
     why = snap.workflow?.haltReason ? `${terminal}: ${snap.workflow.haltReason}` : `workflow ${terminal}`;
   } else if (chainStatus === "escalated" || chainStatus === "abandoned") {

package/dist/bin/whisper.js

@@ -1775,7 +1775,32 @@ function listActiveCollabSummaries(db, input) {
 			     OR EXISTS (SELECT 1 FROM workflows w
 			                 WHERE w.collab_id = c.collab_id AND w.status = 'running')`).all(cutoff);
   const out = [];
+  const seen = /* @__PURE__ */ new Set();
   for (const e of eligible) {
+    out.push(buildCollabSummary(db, e.collabId));
+    seen.add(e.collabId);
+  }
+  const minResults = input.minResults ?? 3;
+  if (out.length < minResults) {
+    const finished = db.prepare(`SELECT collab_id AS collabId, MAX(created_at) AS lastCreated
+				   FROM workflows
+				  WHERE status IN ('done','halted','canceled')
+				  GROUP BY collab_id
+				  ORDER BY lastCreated DESC, collab_id DESC`).all();
+    for (const f of finished) {
+      if (out.length >= minResults)
+        break;
+      if (seen.has(f.collabId))
+        continue;
+      out.push(buildCollabSummary(db, f.collabId));
+      seen.add(f.collabId);
+    }
+  }
+  return out;
+}
+function buildCollabSummary(db, collabId) {
+  {
+    const e = { collabId };
     const collab = db.prepare(`SELECT display_name AS displayName, workspace_root AS workspaceRoot
 				   FROM collab WHERE collab_id = ?`).get(e.collabId);
     const wf = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,
@@ -1829,7 +1854,7 @@ function listActiveCollabSummaries(db, input) {
 						   FROM relay_handoff
 						  WHERE collab_id = ? AND workflow_id IS NULL`).get(e.collabId);
     const runLastAct = runLastActRow?.lastAct ?? "";
-    out.push({
+    return {
       collabId: e.collabId,
       label,
       workflowId: wf?.workflowId ?? null,
@@ -1848,9 +1873,8 @@ function listActiveCollabSummaries(db, input) {
       },
       sessions,
       lastActivityAt: runLastAct
-    });
+    };
   }
-  return out;
 }
 function listWorkflowsForCollab(db, collabId) {
   const rows = db.prepare(`SELECT workflow_id AS workflowId, workflow_type AS workflowType,
@@ -6168,12 +6192,16 @@ function createNodePty(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath
   });
-  return spawn3(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn3(input.config.executable, input.config.execArgs, buildClaudePtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildClaudePtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "claude";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createClaudeLiveSession(input) {
   let pty = null;
@@ -6471,12 +6499,16 @@ function createNodePty2(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath2
   });
-  return spawn5(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn5(input.config.executable, input.config.execArgs, buildCodexPtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildCodexPtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "codex";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createCodexLiveSession(input) {
   let pty = null;
@@ -9157,7 +9189,9 @@ function computeLiveness(snap) {
   let why = null;
   let stuck = false;
   let liveOverride = null;
-  if (terminal === "halted" || terminal === "canceled") {
+  if (terminal === "done") {
+    return { stuck: false, why: null, liveText: "done" };
+  } else if (terminal === "halted" || terminal === "canceled") {
     stuck = true;
     why = snap.workflow?.haltReason ? `${terminal}: ${snap.workflow.haltReason}` : `workflow ${terminal}`;
   } else if (chainStatus === "escalated" || chainStatus === "abandoned") {
@@ -9938,6 +9972,8 @@ function createDashboardRuntime(input) {
   let lastSig = null;
   let renderCount = 0;
   let recycles = 0;
+  let lastRenderedMode = "wall";
+  let clearCount = 0;
   const recycleEvery = Math.max(1, input.__recycleEveryRenders ?? 750);
   function toPhaseRuns(raw) {
     return raw.map((p) => ({
@@ -10143,6 +10179,11 @@ function createDashboardRuntime(input) {
       lastSig = pendingSig;
       renderCount += 1;
       const full = createElement2(DashboardApp, { node: el, onKey: handleKey });
+      if (mode !== lastRenderedMode) {
+        ink.clear();
+        clearCount += 1;
+        lastRenderedMode = mode;
+      }
       if (renderCount % recycleEvery === 0) {
         ink.unmount();
         ink = render2(full, inkOptions);
@@ -10252,7 +10293,8 @@ function createDashboardRuntime(input) {
       lastError: lastPollError
     }),
     __renderCount: () => renderCount,
-    __recycles: () => recycles
+    __recycles: () => recycles,
+    __clears: () => clearCount
   };
 }
 
@@ -10802,21 +10844,62 @@ async function runWorkflowStart(deps) {
     }
   }
   const def = getWorkflowDefinition(deps.workflowType);
-  const implementer = deps.implementer ?? def?.defaultImplementer;
-  const reviewer = deps.reviewer ?? def?.defaultReviewer;
-  if (!implementer || !reviewer) {
-    throw new Error(
-      `Workflow type "${deps.workflowType}" has no default role bindings. Pass --implementer and --reviewer explicitly.`
-    );
+  let resolved;
+  try {
+    resolved = resolveRoleBindings({
+      explicitImplementer: deps.implementer,
+      explicitReviewer: deps.reviewer,
+      callerAgent: deps.callerAgent ?? null,
+      def
+    });
+  } catch (e) {
+    if (e instanceof Error && /no default role bindings/.test(e.message)) {
+      throw new Error(
+        `Workflow type "${deps.workflowType}" has no default role bindings. Pass --implementer and --reviewer explicitly.`
+      );
+    }
+    throw e;
   }
-  return deps.broker.control.createWorkflow({
+  const { workflowId } = deps.broker.control.createWorkflow({
     collabId: deps.collabId,
     workflowType: deps.workflowType,
     specPath: deps.specPath,
-    roleBindings: { implementer, reviewer },
+    roleBindings: { implementer: resolved.implementer, reviewer: resolved.reviewer },
     ...deps.name ? { name: deps.name } : {},
     now: deps.now
   });
+  return { workflowId, ...resolved.warning ? { roleWarning: resolved.warning } : {} };
+}
+var otherAgent = (a) => a === "claude" ? "codex" : "claude";
+function resolveRoleBindings(input) {
+  const { explicitImplementer, explicitReviewer, callerAgent, def } = input;
+  if (explicitImplementer || explicitReviewer) {
+    const implementer2 = explicitImplementer ?? (explicitReviewer ? otherAgent(explicitReviewer) : void 0);
+    const reviewer2 = explicitReviewer ?? (explicitImplementer ? otherAgent(explicitImplementer) : void 0);
+    if (implementer2 && reviewer2) {
+      if (implementer2 === reviewer2) {
+        throw new Error("implementer and reviewer cannot be the same agent");
+      }
+      return { implementer: implementer2, reviewer: reviewer2, source: "explicit" };
+    }
+  }
+  if (callerAgent) {
+    return { implementer: callerAgent, reviewer: otherAgent(callerAgent), source: "caller" };
+  }
+  const implementer = def?.defaultImplementer;
+  const reviewer = def?.defaultReviewer;
+  if (!implementer || !reviewer) {
+    throw new Error("no default role bindings");
+  }
+  return {
+    implementer,
+    reviewer,
+    source: "default",
+    warning: `No triggering agent detected; defaulted to implementer=${implementer} / reviewer=${reviewer}. Pass --implementer / --reviewer to choose explicitly.`
+  };
+}
+function parseCallerAgent(raw) {
+  return raw === "claude" || raw === "codex" ? raw : null;
 }
 
 // src/commands/workflow/list.ts
@@ -11184,8 +11267,10 @@ Not attached (stdin/stdout is not a TTY). To view the tmux session, run:
           ...opts.implementer ? { implementer: opts.implementer } : {},
           ...opts.reviewer ? { reviewer: opts.reviewer } : {},
           ...opts.name ? { name: opts.name } : {},
+          callerAgent: parseCallerAgent(process.env.AI_WHISPER_AGENT),
           now: (/* @__PURE__ */ new Date()).toISOString()
         });
+        if (result.roleWarning) console.error(result.roleWarning);
         console.log(`Workflow started: ${result.workflowId}`);
       } finally {
         await broker.stop();

package/dist/skills/ai-whisper-ralph/SKILL.md

@@ -97,7 +97,7 @@ Run:
 whisper workflow start --type=ralph-loop --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills ralph defaults: implementer=claude, reviewer=codex. `--spec` names the goal file.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override. `--spec` names the goal file.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/dist/skills/ai-whisper-sdd/SKILL.md

@@ -94,7 +94,7 @@ Run:
 whisper workflow start --type=spec-driven-development --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills SDD defaults: implementer=claude, reviewer=codex.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-whisper",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Terminal-first relay for paired AI coding agents (Claude + Codex), driven by structured workflows.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,11 +29,11 @@
     "@types/better-sqlite3": "^7.6.12",
     "@types/react": "^19.2.14",
     "ink-testing-library": "^4.0.0",
-    "@ai-whisper/adapter-codex": "0.0.0",
-    "@ai-whisper/broker": "0.0.0",
-    "@ai-whisper/shared": "0.0.0",
     "@ai-whisper/adapter-claude": "0.0.0",
-    "@ai-whisper/companion-core": "0.0.0"
+    "@ai-whisper/shared": "0.0.0",
+    "@ai-whisper/adapter-codex": "0.0.0",
+    "@ai-whisper/companion-core": "0.0.0",
+    "@ai-whisper/broker": "0.0.0"
   },
   "files": [
     "dist",

package/skills/ai-whisper-ralph/SKILL.md

@@ -97,7 +97,7 @@ Run:
 whisper workflow start --type=ralph-loop --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills ralph defaults: implementer=claude, reviewer=codex. `--spec` names the goal file.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override. `--spec` names the goal file.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/skills/ai-whisper-sdd/SKILL.md

@@ -94,7 +94,7 @@ Run:
 whisper workflow start --type=spec-driven-development --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills SDD defaults: implementer=claude, reviewer=codex.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).