@nk070281sjv/cli 2.3.4 → 2.3.6

package/dist/index.js

@@ -3553,14 +3553,14 @@ var require_emoji_regex = __commonJS({
 var require_string_width = __commonJS({
   "../../node_modules/.pnpm/string-width@4.2.3/node_modules/string-width/index.js"(exports, module) {
     "use strict";
-    var stripAnsi2 = require_strip_ansi();
+    var stripAnsi3 = require_strip_ansi();
     var isFullwidthCodePoint2 = require_is_fullwidth_code_point();
     var emojiRegex2 = require_emoji_regex();
     var stringWidth2 = (string) => {
       if (typeof string !== "string" || string.length === 0) {
         return 0;
       }
-      string = stripAnsi2(string);
+      string = stripAnsi3(string);
       if (string.length === 0) {
         return 0;
       }
@@ -4695,7 +4695,7 @@ var require_wrap_ansi = __commonJS({
   "../../node_modules/.pnpm/wrap-ansi@6.2.0/node_modules/wrap-ansi/index.js"(exports, module) {
     "use strict";
     var stringWidth2 = require_string_width();
-    var stripAnsi2 = require_strip_ansi();
+    var stripAnsi3 = require_strip_ansi();
     var ansiStyles3 = require_ansi_styles();
     var ESCAPES3 = /* @__PURE__ */ new Set([
       "\x1B",
@@ -4707,7 +4707,7 @@ var require_wrap_ansi = __commonJS({
     var wrapWord2 = (rows, word, columns) => {
       const characters = [...word];
       let isInsideEscape = false;
-      let visible = stringWidth2(stripAnsi2(rows[rows.length - 1]));
+      let visible = stringWidth2(stripAnsi3(rows[rows.length - 1]));
       for (const [index, character] of characters.entries()) {
         const characterLength = stringWidth2(character);
         if (visible + characterLength <= columns) {
@@ -30779,7 +30779,7 @@ ${hint}
 }
 
 // src/lib/version.ts
-var CLI_VERSION = true ? "2.3.4" : createRequire(import.meta.url)("../../package.json").version;
+var CLI_VERSION = true ? "2.3.6" : createRequire(import.meta.url)("../../package.json").version;
 
 // src/lib/deps.ts
 init_src();
@@ -37513,6 +37513,12 @@ function buildOpenCodeRunArgs(input) {
     "--model",
     input.model
   ];
+  if (input.attachUrl) {
+    base.push("--attach", input.attachUrl, "--dir", input.cwd);
+  }
+  if (input.pure) {
+    base.push("--pure");
+  }
   const limit = input.promptArgvLimit ?? DEFAULT_PROMPT_ARGV_LIMIT;
   if (input.prompt.length <= limit) {
     return [...base, input.prompt];
@@ -37531,20 +37537,49 @@ function parseOpenCodeJsonEvents(stdout) {
   }
   return events;
 }
+function extractOpenCodeText(events) {
+  return events.map((event) => {
+    if (!isRecord(event)) return "";
+    const part = event.part;
+    if (!isRecord(part) || part.type !== "text") return "";
+    return typeof part.text === "string" ? part.text : "";
+  }).join("").trimStart();
+}
 var OpenCodeProcessRunner = class {
   spawn;
   promptArgvLimit;
+  serveReadyTimeoutMs;
+  pure;
+  server;
   constructor(options = {}) {
     this.spawn = options.spawn ?? spawnBinary;
     this.promptArgvLimit = options.promptArgvLimit ?? DEFAULT_PROMPT_ARGV_LIMIT;
+    this.serveReadyTimeoutMs = options.serveReadyTimeoutMs ?? 15e3;
+    this.pure = options.pure ?? true;
   }
   async run(request, signal) {
     const prompt = await readFile2(request.promptPath, "utf-8");
+    let attachUrl;
+    try {
+      attachUrl = await this.ensureServer(request.cwd, signal);
+    } catch (error) {
+      return {
+        id: request.id,
+        exitCode: -1,
+        stdout: "",
+        stderr: error instanceof Error ? error.message : "Failed to start OpenCode server.",
+        ndjsonEvents: [],
+        outputText: ""
+      };
+    }
     const args = buildOpenCodeRunArgs({
       agent: request.agent ?? "plan",
       model: request.model,
       prompt,
       promptPath: request.promptPath,
+      cwd: request.cwd,
+      attachUrl,
+      pure: this.pure,
       promptArgvLimit: this.promptArgvLimit
     });
     return new Promise((resolve4) => {
@@ -37554,7 +37589,8 @@ var OpenCodeProcessRunner = class {
           exitCode: -1,
           stdout: "",
           stderr: "OpenCode process aborted before spawn.",
-          ndjsonEvents: []
+          ndjsonEvents: [],
+          outputText: ""
         });
         return;
       }
@@ -37584,26 +37620,147 @@ var OpenCodeProcessRunner = class {
         stderr += chunk;
       });
       child.on("error", (err) => {
+        const ndjsonEvents = parseOpenCodeJsonEvents(stdout);
         settle({
           id: request.id,
           exitCode: -1,
           stdout,
           stderr: stderr || err.message,
-          ndjsonEvents: parseOpenCodeJsonEvents(stdout)
+          ndjsonEvents,
+          outputText: extractOpenCodeText(ndjsonEvents)
         });
       });
       child.on("close", (code) => {
+        const ndjsonEvents = parseOpenCodeJsonEvents(stdout);
         settle({
           id: request.id,
           exitCode: code ?? -1,
           stdout,
           stderr,
-          ndjsonEvents: parseOpenCodeJsonEvents(stdout)
+          ndjsonEvents,
+          outputText: extractOpenCodeText(ndjsonEvents)
         });
       });
     });
   }
+  async close() {
+    if (!this.server) return;
+    const { child } = this.server;
+    this.server = void 0;
+    if (child.exitCode !== null || child.killed) return;
+    await new Promise((resolve4) => {
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        resolve4();
+      }, 1500);
+      child.once("close", () => {
+        clearTimeout(timer);
+        resolve4();
+      });
+      child.kill();
+    });
+  }
+  ensureServer(cwd, signal) {
+    if (signal.aborted) {
+      return Promise.reject(new Error("OpenCode server start aborted before spawn."));
+    }
+    if (this.server) {
+      if (this.server.cwd !== cwd) {
+        return Promise.reject(
+          new Error(
+            `OpenCode process runner cannot reuse one server across cwd values: ${this.server.cwd} vs ${cwd}.`
+          )
+        );
+      }
+      return this.server.ready;
+    }
+    const child = this.spawn(
+      "opencode",
+      [
+        "serve",
+        "--hostname",
+        "127.0.0.1",
+        "--port",
+        "0",
+        ...this.pure ? ["--pure"] : []
+      ],
+      {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"]
+      }
+    );
+    const server = {
+      cwd,
+      child,
+      ready: Promise.resolve(""),
+      stdout: "",
+      stderr: ""
+    };
+    this.server = server;
+    server.ready = new Promise((resolve4, reject) => {
+      let settled = false;
+      const cleanup = () => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+      };
+      const fail5 = (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        this.server = void 0;
+        child.kill();
+        reject(error);
+      };
+      const succeed = (url) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve4(url);
+      };
+      const inspect = () => {
+        const url = parseServeUrl(`${server.stdout}
+${server.stderr}`);
+        if (url) succeed(url);
+      };
+      const abort = () => fail5(new Error("OpenCode server start aborted."));
+      const timer = setTimeout(() => {
+        fail5(
+          new Error(
+            `Timed out waiting for OpenCode server to start. stdout: ${server.stdout.trim()} stderr: ${server.stderr.trim()}`
+          )
+        );
+      }, this.serveReadyTimeoutMs);
+      signal.addEventListener("abort", abort, { once: true });
+      child.stdout?.setEncoding("utf-8");
+      child.stderr?.setEncoding("utf-8");
+      child.stdout?.on("data", (chunk) => {
+        server.stdout += chunk;
+        inspect();
+      });
+      child.stderr?.on("data", (chunk) => {
+        server.stderr += chunk;
+        inspect();
+      });
+      child.on("error", (error) => fail5(error));
+      child.on("close", (code) => {
+        if (!settled) {
+          fail5(
+            new Error(
+              `OpenCode server exited before it was ready with code ${code ?? -1}. stdout: ${server.stdout.trim()} stderr: ${server.stderr.trim()}`
+            )
+          );
+        }
+      });
+    });
+    return server.ready;
+  }
 };
+function parseServeUrl(output) {
+  return output.match(/opencode server listening on (https?:\/\/\S+)/)?.[1];
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
 
 // src/lib/agent-orchestrator/prompt-writer.ts
 import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
@@ -37675,11 +37832,21 @@ function reviewerPrompt(context, reviewer, promptPath, reviewPath) {
     `Round number: ${context.round}`,
     "Phase: reviews",
     "",
-    "Input files:",
-    `- ${relative3(context.roundDir, context.discoveredStandardsPath)}`,
-    `- ${relative3(context.roundDir, context.contextPath)}`,
-    `- ${relative3(context.roundDir, context.reviewBriefPath)}`,
-    ...context.requirementsPath ? [`- ${relative3(context.roundDir, context.requirementsPath)}`] : [],
+    "Input files to read before reviewing:",
+    `- ${context.discoveredStandardsPath}`,
+    `- ${context.contextPath}`,
+    `- ${context.reviewBriefPath}`,
+    ...context.requirementsPath ? [`- ${context.requirementsPath}`] : [],
+    "",
+    "Input path rules:",
+    "- Read exactly the files listed above; they are session-scoped snapshots.",
+    "- Do not look for legacy root files such as .ocr/context.md, .ocr/discovered-standards.md, or .ocr/review-brief.md.",
+    "- If a listed file is missing, report that failure in stdout instead of searching for substitutes.",
+    "- Relative equivalents from the round directory:",
+    `  - ${relative3(context.roundDir, context.discoveredStandardsPath)}`,
+    `  - ${relative3(context.roundDir, context.contextPath)}`,
+    `  - ${relative3(context.roundDir, context.reviewBriefPath)}`,
+    ...context.requirementsPath ? [`  - ${relative3(context.roundDir, context.requirementsPath)}`] : [],
     "",
     "Output contract:",
     `- Return review markdown through stdout for ${reviewPath}.`,
@@ -37705,13 +37872,25 @@ function pipelinePrompt(context, stage, agent, promptPath, artifactPath) {
     `Round number: ${context.round}`,
     `Phase: ${stage}`,
     "",
-    "Input files:",
-    `- ${relative3(context.roundDir, context.discoveredStandardsPath)}`,
-    `- ${relative3(context.roundDir, context.contextPath)}`,
-    `- ${relative3(context.roundDir, context.reviewBriefPath)}`,
-    "- reviews/*.md",
-    ...stage !== "aggregation" ? ["- aggregation.md"] : [],
-    ...stage === "synthesis" ? ["- validation.md"] : [],
+    "Input files to read before processing:",
+    `- ${context.discoveredStandardsPath}`,
+    `- ${context.contextPath}`,
+    `- ${context.reviewBriefPath}`,
+    `- ${join26(context.roundDir, "reviews")}`,
+    ...stage !== "aggregation" ? [join26(context.roundDir, "aggregation.md")] : [],
+    ...stage === "synthesis" ? [join26(context.roundDir, "validation.md")] : [],
+    "",
+    "Input path rules:",
+    "- Read exactly the files and directories listed above; they are session-scoped snapshots.",
+    "- Do not look for legacy root files such as .ocr/context.md, .ocr/discovered-standards.md, or .ocr/review-brief.md.",
+    "- If a listed file is missing, report that failure in stdout instead of searching for substitutes.",
+    "- Relative equivalents from the round directory:",
+    `  - ${relative3(context.roundDir, context.discoveredStandardsPath)}`,
+    `  - ${relative3(context.roundDir, context.contextPath)}`,
+    `  - ${relative3(context.roundDir, context.reviewBriefPath)}`,
+    "  - reviews/",
+    ...stage !== "aggregation" ? ["  - aggregation.md"] : [],
+    ...stage === "synthesis" ? ["  - validation.md"] : [],
     "",
     "Output contract:",
     `- Return markdown through stdout for ${artifactPath}.`,
@@ -37740,6 +37919,7 @@ function schemaHint(stage) {
 // src/lib/agent-orchestrator/review-orchestrator.ts
 async function runReviewerPhase(input) {
   const journal = input.journal ?? new NoopAgentLifecycleJournal();
+  const emit = input.emit ?? (() => void 0);
   const controller = new AbortController();
   const reviewerRequests = input.resolvedTeam.reviewers.map((reviewer) => {
     if (!reviewer.model.trim()) {
@@ -37768,7 +37948,26 @@ async function runReviewerPhase(input) {
       phase: "reviews"
     });
     await journal.beat(agentSessionId);
+    const startLogPaths = await writeProcessStartLog(input.context.roundDir, request);
+    emit({
+      event: "agent:start",
+      phase: "reviews",
+      id: request.id,
+      model: request.model,
+      prompt_path: request.promptPath,
+      meta_log: startLogPaths.meta
+    });
     const result = await input.runner.run(request, controller.signal);
+    const logPaths = await writeProcessLogs(input.context.roundDir, request, result);
+    emit({
+      event: "agent:complete",
+      phase: "reviews",
+      id: request.id,
+      exit_code: result.exitCode,
+      stdout_log: logPaths.stdout,
+      stderr_log: logPaths.stderr,
+      meta_log: logPaths.meta
+    });
     const vendorId = extractVendorSessionId(result.ndjsonEvents);
     if (vendorId) await journal.bindVendorId(agentSessionId, vendorId);
     await journal.endInstance(agentSessionId, {
@@ -37789,6 +37988,8 @@ async function runReviewerPhase(input) {
   );
   const failed = results.find((result) => result.exitCode !== 0);
   if (failed) {
+    const failedRequest = requests.find((request) => request.id === failed.id);
+    const diagnostic = buildFailureDiagnostic(failed, failedRequest);
     await writeRoundArtifact(
       input.context.roundDir,
       "failure-summary.json",
@@ -37798,7 +37999,12 @@ async function runReviewerPhase(input) {
           phase: "reviews",
           failed_id: failed.id,
           exit_code: failed.exitCode,
+          model: failedRequest?.model,
+          prompt_path: failedRequest?.promptPath,
+          cwd: failedRequest?.cwd,
+          diagnostic,
           stderr: failed.stderr,
+          stdout_excerpt: excerpt(failed.stdout),
           results: sortResults(results, requests).map((result) => ({
             id: result.id,
             exit_code: result.exitCode
@@ -37813,7 +38019,14 @@ async function runReviewerPhase(input) {
       failedId: failed.id,
       errors: [
         `Reviewer ${failed.id} failed with exit code ${failed.exitCode}.`,
-        ...failed.stderr.trim() ? [failed.stderr.trim()] : []
+        diagnostic.summary,
+        ...diagnostic.hint ? [diagnostic.hint] : [],
+        ...failedRequest ? [
+          `Model: ${failedRequest.model}`,
+          `Prompt: ${failedRequest.promptPath}`
+        ] : [],
+        ...diagnostic.stderr_excerpt ? [`stderr: ${diagnostic.stderr_excerpt}`] : [],
+        ...diagnostic.stdout_excerpt ? [`stdout: ${diagnostic.stdout_excerpt}`] : []
       ],
       results: sortResults(results, requests)
     };
@@ -37825,7 +38038,7 @@ async function runReviewerPhase(input) {
   for (const result of sortResults(results, requests)) {
     const reviewer = byId.get(result.id);
     if (!reviewer) continue;
-    await writeRoundArtifact(input.context.roundDir, reviewer.reviewPath, result.stdout);
+    await writeRoundArtifact(input.context.roundDir, reviewer.reviewPath, processOutput(result));
   }
   return { ok: true, results: sortResults(results, requests) };
 }
@@ -37833,75 +38046,82 @@ async function runOpenCodeProcessAgentReview(input) {
   const runner = input.runner ?? new OpenCodeProcessRunner();
   const journal = input.journal ?? new NoopAgentLifecycleJournal();
   const emit = input.emit ?? (() => void 0);
-  emit({ event: "context:start", session_id: input.sessionId, round: input.round });
-  const context = await prepareReviewContext({
-    sessionId: input.sessionId,
-    sessionDir: input.sessionDir,
-    round: input.round,
-    requirements: input.requirements
-  });
-  const snapshot = await writePromptSnapshots({
-    context,
-    reviewers: input.reviewers,
-    pipelineAgents: input.pipelineAgents
-  });
-  emit({
-    event: "prompts:written",
-    session_id: input.sessionId,
-    round: input.round,
-    reviewers: snapshot.resolvedTeam.reviewers.length
-  });
-  emit({ event: "reviews:start", session_id: input.sessionId, round: input.round });
-  const reviewerResult = await runReviewerPhase({
-    context,
-    resolvedTeam: snapshot.resolvedTeam,
-    cwd: input.cwd,
-    runner,
-    journal
-  });
-  if (!reviewerResult.ok) {
+  try {
+    emit({ event: "context:start", session_id: input.sessionId, round: input.round });
+    const context = await prepareReviewContext({
+      sessionId: input.sessionId,
+      sessionDir: input.sessionDir,
+      round: input.round,
+      requirements: input.requirements
+    });
+    const snapshot = await writePromptSnapshots({
+      context,
+      reviewers: input.reviewers,
+      pipelineAgents: input.pipelineAgents
+    });
     emit({
-      event: "reviews:failed",
+      event: "prompts:written",
       session_id: input.sessionId,
-      failed_id: reviewerResult.failedId
+      round: input.round,
+      reviewers: snapshot.resolvedTeam.reviewers.length
     });
-    return {
-      ok: false,
+    emit({ event: "reviews:start", session_id: input.sessionId, round: input.round });
+    const reviewerResult = await runReviewerPhase({
+      context,
       resolvedTeam: snapshot.resolvedTeam,
-      errors: reviewerResult.errors
-    };
-  }
-  emit({ event: "reviews:complete", session_id: input.sessionId });
-  emit({ event: "pipeline:start", session_id: input.sessionId, round: input.round });
-  const pipelineResult = await runPipelineStages({
-    context,
-    resolvedTeam: snapshot.resolvedTeam,
-    cwd: input.cwd,
-    runner,
-    journal
-  });
-  if (!pipelineResult.ok) {
-    emit({
-      event: "pipeline:failed",
-      session_id: input.sessionId,
-      failed_stage: pipelineResult.failedStage
+      cwd: input.cwd,
+      runner,
+      journal,
+      emit
     });
+    if (!reviewerResult.ok) {
+      emit({
+        event: "reviews:failed",
+        session_id: input.sessionId,
+        failed_id: reviewerResult.failedId
+      });
+      return {
+        ok: false,
+        resolvedTeam: snapshot.resolvedTeam,
+        errors: reviewerResult.errors
+      };
+    }
+    emit({ event: "reviews:complete", session_id: input.sessionId });
+    emit({ event: "pipeline:start", session_id: input.sessionId, round: input.round });
+    const pipelineResult = await runPipelineStages({
+      context,
+      resolvedTeam: snapshot.resolvedTeam,
+      cwd: input.cwd,
+      runner,
+      journal,
+      emit
+    });
+    if (!pipelineResult.ok) {
+      emit({
+        event: "pipeline:failed",
+        session_id: input.sessionId,
+        failed_stage: pipelineResult.failedStage
+      });
+      return {
+        ok: false,
+        resolvedTeam: snapshot.resolvedTeam,
+        errors: pipelineResult.errors
+      };
+    }
+    emit({ event: "pipeline:complete", session_id: input.sessionId });
     return {
-      ok: false,
+      ok: true,
       resolvedTeam: snapshot.resolvedTeam,
-      errors: pipelineResult.errors
+      reviewerResults: reviewerResult.results,
+      pipelineResults: pipelineResult.results
     };
+  } finally {
+    await runner.close?.();
   }
-  emit({ event: "pipeline:complete", session_id: input.sessionId });
-  return {
-    ok: true,
-    resolvedTeam: snapshot.resolvedTeam,
-    reviewerResults: reviewerResult.results,
-    pipelineResults: pipelineResult.results
-  };
 }
 async function runPipelineStages(input) {
   const journal = input.journal ?? new NoopAgentLifecycleJournal();
+  const emit = input.emit ?? (() => void 0);
   const missingReviews = input.resolvedTeam.reviewers.map((reviewer) => reviewer.reviewPath).filter((reviewPath) => !isNonEmptyFile(join27(input.context.roundDir, reviewPath)));
   if (missingReviews.length > 0) {
     return {
@@ -37923,36 +38143,59 @@ async function runPipelineStages(input) {
       phase: stage
     });
     await journal.beat(agentSessionId);
-    const result = await input.runner.run(
-      {
-        id: stage,
-        model: ref.model,
-        promptPath: join27(input.context.roundDir, ref.promptPath),
-        cwd: input.cwd,
-        phase: stage
-      },
-      new AbortController().signal
-    );
+    const request = {
+      id: stage,
+      model: ref.model,
+      promptPath: join27(input.context.roundDir, ref.promptPath),
+      cwd: input.cwd,
+      phase: stage
+    };
+    const startLogPaths = await writeProcessStartLog(input.context.roundDir, request);
+    emit({
+      event: "agent:start",
+      phase: stage,
+      id: request.id,
+      model: request.model,
+      prompt_path: request.promptPath,
+      meta_log: startLogPaths.meta
+    });
+    const result = await input.runner.run(request, new AbortController().signal);
+    const logPaths = await writeProcessLogs(input.context.roundDir, request, result);
+    emit({
+      event: "agent:complete",
+      phase: stage,
+      id: request.id,
+      exit_code: result.exitCode,
+      stdout_log: logPaths.stdout,
+      stderr_log: logPaths.stderr,
+      meta_log: logPaths.meta
+    });
     results.push(result);
     const vendorId = extractVendorSessionId(result.ndjsonEvents);
     if (vendorId) await journal.bindVendorId(agentSessionId, vendorId);
     if (result.exitCode !== 0) {
+      const diagnostic = buildFailureDiagnostic(result, request);
       await journal.endInstance(agentSessionId, {
         exitCode: result.exitCode,
-        note: result.stderr.trim() || void 0
+        note: diagnostic.summary
       });
-      await writePipelineFailure(input.context.roundDir, stage, result, results);
+      await writePipelineFailure(input.context.roundDir, stage, result, results, [], diagnostic);
       return {
         ok: false,
         failedStage: stage,
         errors: [
           `Pipeline stage ${stage} failed with exit code ${result.exitCode}.`,
-          ...result.stderr.trim() ? [result.stderr.trim()] : []
+          diagnostic.summary,
+          ...diagnostic.hint ? [diagnostic.hint] : [],
+          `Model: ${request.model}`,
+          `Prompt: ${request.promptPath}`,
+          ...diagnostic.stderr_excerpt ? [`stderr: ${diagnostic.stderr_excerpt}`] : [],
+          ...diagnostic.stdout_excerpt ? [`stdout: ${diagnostic.stdout_excerpt}`] : []
         ],
         results
       };
     }
-    await writeRoundArtifact(input.context.roundDir, ref.artifactPath, result.stdout);
+    await writeRoundArtifact(input.context.roundDir, ref.artifactPath, processOutput(result));
     const validationErrors = validateStageArtifact(input.context.roundDir, stage, ref.artifactPath);
     if (validationErrors.length > 0) {
       await journal.endInstance(agentSessionId, {
@@ -37985,7 +38228,71 @@ function validateStageArtifact(roundDir, stage, artifactPath) {
 function isNonEmptyFile(path2) {
   return existsSync22(path2) && statSync5(path2).isFile() && statSync5(path2).size > 0;
 }
-async function writePipelineFailure(roundDir, stage, result, results, validationErrors = []) {
+async function writeProcessStartLog(roundDir, request) {
+  const metaPath = `process-logs/${request.id}.meta.json`;
+  await writeRoundArtifact(
+    roundDir,
+    metaPath,
+    JSON.stringify(
+      {
+        schema_version: 1,
+        id: request.id,
+        phase: request.phase,
+        model: request.model,
+        prompt_path: request.promptPath,
+        status: "running",
+        started_at: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    )
+  );
+  return { meta: metaPath };
+}
+async function writeProcessLogs(roundDir, request, result) {
+  const prefix = `process-logs/${request.id}`;
+  const stdoutPath = `${prefix}.stdout.ndjson`;
+  const stderrPath = `${prefix}.stderr.log`;
+  const metaPath = `${prefix}.meta.json`;
+  await writeRoundArtifact(roundDir, stdoutPath, result.stdout);
+  await writeRoundArtifact(roundDir, stderrPath, result.stderr);
+  await writeRoundArtifact(
+    roundDir,
+    metaPath,
+    JSON.stringify(
+      {
+        schema_version: 1,
+        id: request.id,
+        phase: request.phase,
+        model: request.model,
+        prompt_path: request.promptPath,
+        status: "completed",
+        completed_at: (/* @__PURE__ */ new Date()).toISOString(),
+        exit_code: result.exitCode,
+        output_text_bytes: Buffer.byteLength(processOutput(result), "utf-8"),
+        stdout_bytes: Buffer.byteLength(result.stdout, "utf-8"),
+        stderr_bytes: Buffer.byteLength(result.stderr, "utf-8"),
+        opencode_session_ids: extractUniqueSessionIds(result.ndjsonEvents)
+      },
+      null,
+      2
+    )
+  );
+  return { stdout: stdoutPath, stderr: stderrPath, meta: metaPath };
+}
+function processOutput(result) {
+  return result.outputText ?? result.stdout;
+}
+function extractUniqueSessionIds(events) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const event of events) {
+    if (!isRecord2(event)) continue;
+    const sessionID = event.sessionID;
+    if (typeof sessionID === "string") ids.add(sessionID);
+  }
+  return [...ids];
+}
+async function writePipelineFailure(roundDir, stage, result, results, validationErrors = [], diagnostic = buildFailureDiagnostic(result)) {
   await writeRoundArtifact(
     roundDir,
     "failure-summary.json",
@@ -37995,7 +38302,9 @@ async function writePipelineFailure(roundDir, stage, result, results, validation
         phase: stage,
         failed_id: result.id,
         exit_code: result.exitCode,
+        diagnostic,
         stderr: result.stderr,
+        stdout_excerpt: excerpt(result.stdout),
         validation_errors: validationErrors,
         results: results.map((item) => ({
           id: item.id,
@@ -38007,6 +38316,63 @@ async function writePipelineFailure(roundDir, stage, result, results, validation
     )
   );
 }
+function buildFailureDiagnostic(result, request) {
+  const stderr = stripAnsi2(result.stderr).trim();
+  const stdoutError = extractOpenCodeErrorMessage(result.ndjsonEvents);
+  const combined = [stderr, stdoutError].filter(Boolean).join("\n");
+  const model = request?.model ?? "";
+  if (/session not found/i.test(combined)) {
+    return {
+      summary: 'OpenCode reported "Session not found" while running this process agent. This is an OpenCode subprocess/session error, not an OCR decision to simulate or skip reviewers.',
+      hint: "OCR uses a persistent `opencode serve` process and runs agents through `opencode run --attach`. Inspect the saved prompt path and OpenCode logs to isolate the OpenCode session failure.",
+      stderr_excerpt: excerpt(stderr),
+      stdout_excerpt: excerpt(result.stdout)
+    };
+  }
+  if (/Unexpected server error/i.test(combined)) {
+    const hint = model && !model.includes("/") ? `The configured model "${model}" does not include an OpenCode provider prefix. Use the exact id from \`opencode models\`, for example \`lumi-deep-seek/DeepSeek-V4-Pro\`.` : `Verify that the configured model "${model}" exists in \`opencode models\` and that the provider is available.`;
+    return {
+      summary: stdoutError || "OpenCode returned an unexpected server error.",
+      hint,
+      stderr_excerpt: excerpt(stderr),
+      stdout_excerpt: excerpt(result.stdout)
+    };
+  }
+  if (combined) {
+    return {
+      summary: combined,
+      stderr_excerpt: excerpt(stderr),
+      stdout_excerpt: excerpt(result.stdout)
+    };
+  }
+  return {
+    summary: "The OpenCode subprocess exited without a useful error message.",
+    hint: "Inspect failure-summary.json and rerun the saved prompt manually with the recorded model to reproduce the failure.",
+    stdout_excerpt: excerpt(result.stdout)
+  };
+}
+function extractOpenCodeErrorMessage(events) {
+  for (const event of events) {
+    if (!isRecord2(event) || event.type !== "error") continue;
+    const error = event.error;
+    if (!isRecord2(error)) continue;
+    const data = error.data;
+    if (isRecord2(data) && typeof data.message === "string") return data.message;
+    if (typeof error.message === "string") return error.message;
+  }
+  return void 0;
+}
+function excerpt(value, limit = 1200) {
+  const stripped = stripAnsi2(value ?? "").trim();
+  if (!stripped) return void 0;
+  return stripped.length > limit ? `${stripped.slice(0, limit)}...` : stripped;
+}
+function stripAnsi2(value) {
+  return value.replace(/\u001b\[[0-9;]*m/g, "");
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
 
 // src/commands/review.ts
 function fail3(message) {
@@ -38075,7 +38441,13 @@ var runAgentsSubcommand = new Command("run-agents").description("Run OCR review
         });
       } else {
         if (!sessionId) {
-          throw new Error("run-agents requires --session-id unless --fresh is set");
+          throw new Error(
+            [
+              "run-agents requires either --fresh or --session-id.",
+              "Start a new process-agent review with: ocr review run-agents --fresh",
+              "Resume a prepared workflow round with: ocr review run-agents --session-id <id> --round <n>"
+            ].join("\n")
+          );
         }
         const session = getSession(db, sessionId);
         if (!session) throw new Error(`Workflow session not found: ${sessionId}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nk070281sjv/cli",
-  "version": "2.3.4",
+  "version": "2.3.6",
   "description": "CLI for Open Code Review - Multi-environment setup and progress tracking",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.2.0",
-    "@nk070281sjv/agents": "2.3.4",
+    "@nk070281sjv/agents": "2.3.6",
     "chalk": "^5.4.1",
     "chokidar": "^4.0.3",
     "commander": "^13.0.0",