feat: improve agent retry flow — previous review injection, no-commit completion, task logger

- Inject previous review feedback into agent prompt on retry so agents
  know what went wrong last time (NEEDS_CHANGES reason)
- Add allow_no_commit_completion template flag: agents that complete
  without code changes (e.g. task already done) go to review instead
  of infinite NEEDS_CHANGES loop
- Extract completion from stream-json result when COMPLETION_JSON is
  not explicitly output by the agent
- Record NEEDS_CHANGES failures to Failure DB via recordFailure()
- Add per-task execution logger (~/.toban/logs/tasks/) for debugging
  agent pickup, completion parse, post_action results, and stdout

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: recuu-pfeg

src/agent-templates.ts

@@ -56,6 +56,8 @@ export interface AgentTemplate {
     /** Additional rules injected into the prompt */
     rules?: string[];
   };
+  /** Allow task to pass review when agent reports completion without code commits */
+  allow_no_commit_completion?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -68,6 +70,7 @@ const DEFAULT_TEMPLATES: AgentTemplate[] = [
     name: "Implementation (default)",
     match: {},
     tools: "all",
+    allow_no_commit_completion: true,
     pre_actions: [
       { type: "git_auth_check", label: "Verify git push credentials" },
       { type: "inject_memory", label: "Inject agent memory into CLAUDE.md" },
@@ -103,6 +106,7 @@ The CLI will automatically update the task status and submit this data. Do NOT m
   {
     id: "research",
     name: "Research / Investigation",
+    allow_no_commit_completion: true,
     match: {
       task_types: ["research", "investigation", "analysis", "audit"],
     },
@@ -143,6 +147,7 @@ DO NOT: git add, git commit, git push, or modify any files. Only read and analyz
   {
     id: "content",
     name: "Content / Documentation",
+    allow_no_commit_completion: true,
     match: {
       task_types: ["content", "docs", "documentation"],
     },
@@ -183,6 +188,7 @@ COMPLETION_JSON:{"review_comment":"<summary: what docs were created/updated, key
   {
     id: "strategy",
     name: "Strategy / Planning",
+    allow_no_commit_completion: true,
     match: {
       task_types: ["strategy", "planning"],
     },
@@ -339,6 +345,12 @@ export interface ActionContext {
   preMergeHash?: string;
   /** Set to true if git_merge was skipped (no agent commits or metadata-only) */
   mergeSkipped?: boolean;
+  /** Parsed COMPLETION_JSON from agent output (set by cli.ts after agent finishes) */
+  completionJson?: { review_comment?: string; commits?: string };
+  /** The matched template for this task */
+  template?: AgentTemplate;
+  /** Per-task logger for debugging */
+  taskLog?: { event(name: string, data?: Record<string, unknown>): void };
   /** Merge function (injected from runner) */
   onMerge?: () => boolean;
   /** Retro submit function (injected from runner) */
@@ -376,9 +388,24 @@ export async function executeActions(
             const MAX_RETRIES = 3;
             const retryCount = (retryTracker.get(ctx.task.id) ?? 0) + 1;
             retryTracker.set(ctx.task.id, retryCount);
+
+            // Record failure to Failure DB
+            const reviewComment = typeof ctx.task.review_comment === "string" ? ctx.task.review_comment : undefined;
+            ctx.api.recordFailure({
+              task_id: ctx.task.id,
+              failure_type: "reject",
+              summary: retryCount >= MAX_RETRIES
+                ? `Blocked after ${retryCount} failed attempts: ${ctx.task.title}`
+                : `NEEDS_CHANGES (attempt ${retryCount}): ${ctx.task.title}`,
+              agent_name: ctx.config.agentName,
+              sprint: typeof ctx.task.sprint === "number" ? ctx.task.sprint : undefined,
+              review_comment: reviewComment,
+            }).catch(() => { /* best-effort */ });
+
             if (retryCount >= MAX_RETRIES) {
-              updates.status = "blocked";
-              ui.error(`[${phase}] Task failed ${retryCount} times — blocked for human review`);
+              updates.status = "review";
+              updates.review_comment = `Blocked: task failed ${retryCount} times. Needs human intervention.`;
+              ui.error(`[${phase}] Task failed ${retryCount} times — moved to review for human intervention`);
             } else {
               updates.status = "todo";
               ui.warn(`[${phase}] Review verdict: NEEDS_CHANGES (attempt ${retryCount}/${MAX_RETRIES}) — resetting to todo`);
@@ -568,8 +595,13 @@ export async function executeActions(
         }
         case "spawn_reviewer": {
           if (ctx.mergeSkipped) {
-            ui.info(`[${phase}] ${label}: skipped (no merge)`);
-            ctx.reviewVerdict = "NEEDS_CHANGES";
+            const allowNoCommit = ctx.template?.allow_no_commit_completion ?? false;
+            if (allowNoCommit && ctx.completionJson?.review_comment) {
+              ui.info(`[${phase}] ${label}: no code changes, agent reported completion — sending to human review`);
+            } else {
+              ui.info(`[${phase}] ${label}: skipped (no merge${!ctx.completionJson ? ", no completion" : ""})`);
+              ctx.reviewVerdict = "NEEDS_CHANGES";
+            }
             break;
           }
           ctx.onReviewUpdate?.(ctx.task.id, "started");
@@ -1093,9 +1125,11 @@ ${outputFormat}`;
         default:
           ui.warn(`[template] Unknown action type: ${action.type}`);
       }
+      ctx.taskLog?.event("action_ok", { action: action.type, label });
     } catch (err) {
       logError(CLI_ERR.ACTION_FAILED, `${phase} action "${label}" failed`, { taskId: ctx.task.id, action: action.type, phase }, err);
       ui.warn(`[template] ${phase} action "${label}" failed: ${err}`);
+      ctx.taskLog?.event("action_error", { action: action.type, label, error: err instanceof Error ? err.message : String(err) });
     }
   }
 }

src/api-client.ts

@@ -102,6 +102,7 @@ export interface ApiClient {
   fetchAgentMemories(agentName: string): Promise<AgentMemory[]>;
   putAgentMemory(agentName: string, key: string, data: { type: string; content: string }): Promise<void>;
   fetchRelevantFailures(): Promise<Array<{ summary: string; failure_type: string; agent_name: string | null; created_at: string }>>;
+  recordFailure(data: { task_id: string; failure_type: string; summary: string; agent_name?: string; sprint?: number; review_comment?: string; files_involved?: string }): Promise<void>;
 }
 
 export function createApiClient(apiUrl: string, apiKey: string): ApiClient {
@@ -330,5 +331,15 @@ export function createApiClient(apiUrl: string, apiKey: string): ApiClient {
         return [];
       }
     },
+
+    async recordFailure(data: { task_id: string; failure_type: string; summary: string; agent_name?: string; sprint?: number; review_comment?: string; files_involved?: string }): Promise<void> {
+      try {
+        await fetch(`${apiUrl}/api/v1/failures`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(data),
+        });
+      } catch { /* best-effort */ }
+    },
   };
 }

src/cli.ts

@@ -18,6 +18,7 @@ import { ChatPoller } from "./chat-poller.js";
 import { MessagePoller } from "./message-poller.js";
 import { WS_MSG } from "./ws-types.js";
 import { resolveTaskWorkingDir } from "./git-ops.js";
+import { createTaskLogger } from "./task-logger.js";
 import { logError, CLI_ERR } from "./error-logger.js";
 import { ensureGitUser } from "./spawner.js";
 import { setup, type CliArgs, type SetupResult } from "./setup.js";
@@ -268,8 +269,11 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
       const isReadOnly = agentTemplate.tools !== "all";
       ui.info(`[task] Template: "${agentTemplate.id}"${isReadOnly ? ` (read-only: ${(agentTemplate.tools as string[]).join(", ")})` : ""}`);
 
+      const taskLog = createTaskLogger(task.id);
+      taskLog.event("pickup", { agent: agentName, template: agentTemplate.id, title: task.title, taskType, hasReviewComment: !!(task as Record<string, unknown>).review_comment });
+
       const actionCtx: ActionContext = {
-        api, task, agentName,
+        api, task, agentName, template: agentTemplate, taskLog,
         config: { apiUrl: cliArgs.apiUrl, apiKey: cliArgs.apiKey, workingDir: taskWorkingDir, baseBranch: cliArgs.baseBranch, sprintNumber: sprintData.sprint.number, language: ctx.language, engine: cliArgs.engine },
         onDataUpdate: (entity, id, changes) => {
           ctx.wsServer?.broadcast({
@@ -308,6 +312,31 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
       let pastFailures: Array<{ summary: string; failure_type: string; agent_name: string | null }> = [];
       try { pastFailures = await api.fetchRelevantFailures(); } catch { /* non-fatal */ }
 
+      // Extract previous review feedback for retry injection
+      let previousReview: string | undefined;
+      const taskReviewComment = (task as Record<string, unknown>).review_comment as string | undefined;
+      if (taskReviewComment) {
+        try {
+          const r = JSON.parse(taskReviewComment);
+          if (r.verdict === "NEEDS_CHANGES") {
+            const parts = [`Verdict: ${r.verdict}`];
+            if (r.requirement_match) parts.push(`Requirements: ${r.requirement_match}`);
+            if (r.code_quality) parts.push(`Code quality: ${r.code_quality}`);
+            if (r.risks) parts.push(`Risks: ${r.risks}`);
+            previousReview = parts.join("\n");
+          }
+        } catch {
+          if (taskReviewComment.startsWith("Blocked:") || taskReviewComment.includes("NEEDS_CHANGES")) {
+            previousReview = taskReviewComment;
+          }
+        }
+      }
+
+      if (previousReview) {
+        ui.warn(`Injecting previous review feedback into agent prompt`);
+        taskLog.event("previous_review_injected", { preview: previousReview.slice(0, 200) });
+      }
+
       const prompt = buildAgentPrompt({
         role: agentName, projectName: ctx.workspaceName, projectSpec: ctx.workspaceSpec,
         taskId: task.id, taskTitle: task.title,
@@ -319,6 +348,7 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
         targetRepo: task.target_repo ?? undefined,
         apiDocs: apiDocs || undefined, engineHint: getEngine(cliArgs.engine).promptHint,
         pastFailures: pastFailures.length > 0 ? pastFailures : undefined,
+        previousReview,
       });
 
       try {
@@ -386,6 +416,30 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
           });
         };
         // Extract COMPLETION_JSON from agent stdout → enrich post_action update_task
+        // Extract COMPLETION_JSON or stream result from agent stdout
+        // Fallback: if no COMPLETION_JSON found, check stream-json result event
+        if (!actionCtx.completionJson) {
+          for (const l of runningAgent.stdout) {
+            try {
+              const ev = JSON.parse(l);
+              if (ev.type === "result" && ev.subtype === "success" && typeof ev.result === "string") {
+                // Agent completed successfully but didn't output COMPLETION_JSON
+                // Use the result text as review_comment
+                const resultText = ev.result.slice(0, 2000);
+                actionCtx.completionJson = { review_comment: resultText, commits: "" };
+                for (const action of agentTemplate.post_actions) {
+                  if (action.type === "update_task" && action.when === "success" && action.params?.status === "review") {
+                    action.params = { ...action.params, review_comment: resultText, commits: "" };
+                    break;
+                  }
+                }
+                ui.info(`[completion] Extracted completion from stream result (no COMPLETION_JSON)`);
+                taskLog.event("completion_parse", { source: "stream_result", review_comment: resultText.slice(0, 200) });
+                break;
+              }
+            } catch { /* skip */ }
+          }
+        }
         for (const line of runningAgent.stdout) {
           const completionLine = line.startsWith("COMPLETION_JSON:") ? line : null;
           if (completionLine) {
@@ -398,7 +452,9 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
                   break;
                 }
               }
+              actionCtx.completionJson = { review_comment: json.review_comment, commits: json.commits };
               ui.info(`[completion] Parsed COMPLETION_JSON: ${json.review_comment?.slice(0, 80)}...`);
+              taskLog.event("completion_parse", { source: "completion_json", review_comment: json.review_comment?.slice(0, 200), commits: json.commits });
               // Broadcast review comment immediately for real-time dashboard update
               if (json.review_comment) {
                 actionCtx.onReviewUpdate?.(task.id, "agent_submitted", json.review_comment);
@@ -419,6 +475,7 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
                     break;
                   }
                 }
+                actionCtx.completionJson = { review_comment: json.review_comment, commits: json.commits };
                 ui.info(`[completion] Parsed COMPLETION_JSON from stream: ${json.review_comment?.slice(0, 80)}...`);
                 // Broadcast review comment immediately for real-time dashboard update
                 if (json.review_comment) {
@@ -493,13 +550,18 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
             }
           }
         };
+        taskLog.stdout(runningAgent.stdout);
+        taskLog.event("post_actions_start", { exitCode, mergeSkipped: actionCtx.mergeSkipped, hasCompletion: !!actionCtx.completionJson, reviewVerdict: actionCtx.reviewVerdict });
         await executeActions(agentTemplate.post_actions, actionCtx, "post");
+        taskLog.event("post_actions_done", { reviewVerdict: actionCtx.reviewVerdict });
+        taskLog.close();
       } catch (err) {
         logError(CLI_ERR.AGENT_SPAWN_FAILED, `Error spawning agent for task ${task.id}: ${err}`, { taskId: task.id, agentName }, err);
         ui.error(`Error spawning agent for task ${task.id}: ${err}`);
-        // Use failure post_actions to reset task and notify user
+        taskLog.event("error", { message: err instanceof Error ? err.message : String(err) });
         actionCtx.exitCode = 1;
         await executeActions(agentTemplate.post_actions, actionCtx, "post");
+        taskLog.close();
       } finally {
         scheduler.releaseSlot(slotName);
       }

src/prompt.ts

@@ -46,6 +46,8 @@ export interface PromptContext {
   engineHint?: string;
   /** Past failures relevant to this task (from Failure Database) */
   pastFailures?: Array<{ summary: string; failure_type: string; agent_name: string | null }>;
+  /** Previous review comment from a failed attempt (injected on retry) */
+  previousReview?: string;
 }
 
 const ROLE_DESCRIPTIONS: Record<string, string> = {
@@ -189,13 +191,18 @@ export function buildAgentPrompt(ctx: PromptContext): string {
     ? `\n\n## Past Failures (avoid repeating these)\n${ctx.pastFailures.map((f) => `- [${f.failure_type}] ${f.summary}`).join("\n")}\n`
     : "";
 
+  const previousReviewBlock = ctx.previousReview
+    ? `\n\n## Previous Review (IMPORTANT — fix these issues)\nThis task was previously attempted and rejected. You MUST address the reviewer's feedback:\n${ctx.previousReview}\n`
+    : "";
+
   // Context budget: estimate tokens (chars / 4) and trim low-priority sections
   const TOKEN_BUDGET = 30_000;
   const estimateTokens = (s: string) => Math.ceil(s.length / 4);
 
   // Fixed sections (always included)
   const fixedParts = [roleDesc, langLine, projectLine, modeHeader, extraRules, engineHintLine,
     `\nYour task: ${ctx.taskTitle}${priorityLine}${typeLine}${targetRepoLine}${descriptionBlock}`,
+    previousReviewBlock,
     completionInstructions];
   const fixedCost = fixedParts.reduce((sum, p) => sum + estimateTokens(p), 0);
 

src/task-logger.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-task execution logger.
+ *
+ * Creates a JSON log file per task execution at ~/.toban/logs/tasks/{taskId}.jsonl
+ * Each line is a timestamped event. Claude Code can read these files for debugging.
+ *
+ * Usage:
+ *   const log = createTaskLogger(taskId);
+ *   log.event("pickup", { agent: "builder", template: "implementation" });
+ *   log.event("completion_parse", { source: "stream_result", review_comment: "..." });
+ *   log.event("post_action", { action: "spawn_reviewer", result: "skipped", reason: "no merge" });
+ *   log.stdout(lines);  // persist last N stdout lines
+ *   log.close();
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const TASKS_LOG_DIR = path.join(os.homedir(), ".toban", "logs", "tasks");
+const MAX_STDOUT_LINES = 50;
+const MAX_FILES = 100; // keep last 100 task logs
+
+interface TaskEvent {
+  ts: string;
+  event: string;
+  data?: Record<string, unknown>;
+}
+
+export interface TaskLogger {
+  event(name: string, data?: Record<string, unknown>): void;
+  stdout(lines: string[]): void;
+  close(): void;
+}
+
+function ensureDir() {
+  try {
+    fs.mkdirSync(TASKS_LOG_DIR, { recursive: true });
+  } catch { /* best effort */ }
+}
+
+function cleanOldLogs() {
+  try {
+    const files = fs.readdirSync(TASKS_LOG_DIR)
+      .filter((f) => f.endsWith(".jsonl"))
+      .map((f) => ({ name: f, time: fs.statSync(path.join(TASKS_LOG_DIR, f)).mtimeMs }))
+      .sort((a, b) => b.time - a.time);
+
+    for (const f of files.slice(MAX_FILES)) {
+      fs.unlinkSync(path.join(TASKS_LOG_DIR, f.name));
+    }
+  } catch { /* best effort */ }
+}
+
+function write(filePath: string, entry: TaskEvent) {
+  try {
+    fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+  } catch { /* best effort */ }
+}
+
+export function createTaskLogger(taskId: string): TaskLogger {
+  ensureDir();
+  cleanOldLogs();
+
+  const shortId = taskId.slice(0, 8);
+  const filePath = path.join(TASKS_LOG_DIR, `${shortId}.jsonl`);
+
+  return {
+    event(name: string, data?: Record<string, unknown>) {
+      write(filePath, { ts: new Date().toISOString(), event: name, data });
+    },
+
+    stdout(lines: string[]) {
+      const tail = lines.slice(-MAX_STDOUT_LINES);
+      write(filePath, {
+        ts: new Date().toISOString(),
+        event: "stdout_snapshot",
+        data: { line_count: lines.length, tail },
+      });
+    },
+
+    close() {
+      write(filePath, { ts: new Date().toISOString(), event: "close" });
+    },
+  };
+}