humanish 0.88.1 → 0.89.0

package/dist/program.js

@@ -36,6 +36,9 @@ import { readRunDetail } from "./run-detail.js";
 import { launchRun, readLaunchLogTail } from "./tui-launch.js";
 import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, tuiBundleUrl } from "./tui-contract.js";
 import { forTerminal } from "./terminal-encoding.js";
+import { analyzeStudy, correctStudyAnalysis, showStudyAnalysis } from "./study-analysis-service.js";
+import { listStudyAnalyses, listStudyAnalysisExecutions } from "./study-analysis-store.js";
+import { resolveRunPath } from "./run.js";
 import { detectAgentSession } from "./agent-session.js";
 import { runCommsCatchHost } from "./comms-catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "./comms-sandbox-catch.js";
@@ -395,6 +398,7 @@ export function createProgram(io = {}) {
     registerVerifyCommand(program, cliIo);
     registerCleanupCommand(program, cliIo);
     registerReviewCommand(program, cliIo);
+    registerAnalyzeCommand(program, cliIo);
     registerRunsCommand(program, cliIo);
     registerStatsCommand(program, cliIo);
     registerExportCommand(program, cliIo);
@@ -947,6 +951,128 @@ function registerReviewCommand(parent, io) {
         io.setExitCode("ok" in result && result.ok === false ? 2 : 0);
     });
 }
+/** Commander may collect a shared flag on the parent; only explicit values override leaf defaults. */
+function analysisSelection(options, command) {
+    const parent = command.parent;
+    const selected = { ...options };
+    for (const key of ["cwd", "run"]) {
+        if (parent?.getOptionValueSource(key) === "cli" && command.getOptionValueSource(key) !== "cli") {
+            selected[key] = parent.getOptionValue(key);
+        }
+    }
+    return selected;
+}
+function registerAnalyzeCommand(parent, io) {
+    const analyze = parent.command("analyze")
+        .enablePositionalOptions()
+        .description("Analyze retained participant evidence into versioned findings. Explicit opt-in: sends selected text and captures to OpenAI. Opening Observer never starts analysis.")
+        .summary("Generate evidence-linked study findings.")
+        .option("--run <id>", "Completed run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--max-cost <usd>", "Required, including with --dry-run: admission estimate ceiling in USD; not an exact billing cap.")
+        .option("--model <id>", "Supported vision analysis model; analysis uses high reasoning effort.", "gpt-6-astra")
+        .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
+        .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", "300000")
+        .option("--max-output-tokens <n>", "Bound response tokens, including reasoning, from 256 to 32768.", "16384")
+        .option("--dry-run", "Capture and validate local input and estimate admission; no request or analysis artifact.")
+        .option("--rerun", "Create a new immutable version even when the same input and configuration were analyzed.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        process.once("SIGINT", cancel);
+        try {
+            const result = await analyzeStudy(options.cwd, options.run, {
+                config: { model: options.model, maxCostUsd: Number(options.maxCost), question: options.question ?? null,
+                    timeoutMs: Number(options.timeoutMs), maxOutputTokens: Number(options.maxOutputTokens) },
+                ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+                ...(options.rerun === undefined ? {} : { rerun: options.rerun })
+            }, { signal: controller.signal, onProgress: (progress) => io.writeErr(`Analysis ${progress.phase}: ${progress.evidenceCount} evidence items, ${progress.captureCount} captures.\n`) });
+            writeResult(command, io, result, (value) => {
+                if (value.ok && value.dryRun)
+                    return `Admission estimate: $${value.admission?.estimatedCostUsd ?? "unknown"}. No request sent.\n`;
+                const lines = [];
+                if (!value.ok)
+                    lines.push(value.error?.message ?? "Analysis unavailable.", value.error?.code ?? "");
+                if (value.artifactPath)
+                    lines.push(`${value.reused ? "Reused" : "Saved"} ${value.status} analysis: ${value.artifactPath}`);
+                if (value.executionReceiptPath)
+                    lines.push(`Execution receipt: ${value.executionReceiptPath}`);
+                if (value.usage) {
+                    lines.push(`Recorded attempt usage: ${value.usage.inputTokens ?? "unknown"} input tokens, ${value.usage.outputTokens ?? "unknown"} output tokens.`);
+                    lines.push(`Estimated attempt cost: ${value.usage.estimatedCostUsd === null ? "unknown" : `$${value.usage.estimatedCostUsd}`}.`);
+                }
+                if (value.reused)
+                    lines.push("No new request sent.");
+                lines.push(...value.warnings);
+                return forTerminal(lines.filter(Boolean).join("\n") + "\n");
+            });
+            io.setExitCode(result.ok ? 0 : 2);
+        }
+        finally {
+            process.removeListener("SIGINT", cancel);
+        }
+    });
+    analyze.command("list").description("List immutable analysis versions, including failed attempts.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        options = analysisSelection(options, command);
+        const prepared = await resolveRunPath(resolve(options.cwd), options.run).catch(() => null);
+        const versions = prepared ? await listStudyAnalyses(prepared) : [];
+        const executions = prepared ? await listStudyAnalysisExecutions(prepared) : { receipts: [], warnings: [] };
+        const result = { schema: "humanish.analysis-history.v1", ok: prepared !== null, run: options.run,
+            executions: executions.receipts, warnings: executions.warnings,
+            versions: versions.map(({ id, state, analysis, warnings }) => ({ id, state, status: analysis?.status ?? null,
+                createdAt: analysis?.createdAt ?? null, findings: analysis?.result?.findings.length ?? null,
+                usage: analysis?.usage ?? null, warnings })) };
+        writeResult(command, io, result, (value) => forTerminal(JSON.stringify(value, null, 2) + "\n"));
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+    analyze.command("show").description("Read validated analysis and correction history. Defaults to the latest usable version.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--id <id>", "Exact analysis version.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        options = analysisSelection(options, command);
+        const result = await showStudyAnalysis(options.cwd, options.run, options.id);
+        writeResult(command, io, result, (value) => forTerminal(JSON.stringify(value, null, 2) + "\n"));
+        io.setExitCode(result.state === "invalid" ? 2 : 0);
+    });
+    analyze.command("correct").description("Append a human review note bound to one exact finding version; original claims remain intact.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .requiredOption("--analysis <id>", "Analysis version to review.")
+        .requiredOption("--finding <id>", "Finding to review.")
+        .addOption(new Option("--status <status>", "Review disposition.").choices(["confirmed", "dismissed", "amended"]).makeOptionMandatory())
+        .requiredOption("--reason <text>", "Why this disposition is supported.")
+        .option("--claim <text>", "Replacement claim, required only for amended findings.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        options = analysisSelection(options, command);
+        try {
+            const correction = await correctStudyAnalysis(options.cwd, options.run, { analysisId: options.analysis,
+                findingId: options.finding, status: options.status, reason: options.reason,
+                ...(options.claim === undefined ? {} : { replacementClaim: options.claim }) });
+            writeResult(command, io, { schema: "humanish.analysis-correction-result.v1", ok: true, correction }, (value) => `Saved correction ${value.correction.id}. Original analysis preserved.\n`);
+            io.setExitCode(0);
+        }
+        catch (error) {
+            const code = error instanceof Error && ["ANALYSIS_BUSY", "ANALYSIS_CORRECTION_HISTORY_UNAVAILABLE"].includes(error.message)
+                ? error.message : "ANALYSIS_CORRECTION_INVALID";
+            const message = code === "ANALYSIS_BUSY"
+                ? "Another analysis or correction holds this run's lock. Retry after it finishes."
+                : code === "ANALYSIS_CORRECTION_HISTORY_UNAVAILABLE"
+                    ? "Correction history is unavailable or full. No correction was added; existing records were preserved."
+                    : "Correction requires a current valid finding, a reason, and a replacement claim only for amended status. Sensitive text is rejected.";
+            writeResult(command, io, { schema: "humanish.analysis-correction-result.v1", ok: false,
+                error: { code, message } }, (value) => value.error.message + "\n");
+            io.setExitCode(2);
+        }
+    });
+}
 function registerExportCommand(parent, io) {
     parent
         .command("export")
@@ -1737,7 +1863,8 @@ function registerFeedbackCommands(parent, io) {
         .summary("Create public-safe feedback drafts, no GitHub API.");
     feedback
         .command("list")
-        .description("List feedback draft state for a run.")
+        .description("List recorded feedback candidates and any saved draft.")
+        .addHelpText("after", "\nWith no candidates, feedback draft and feedback issue can generate a run-summary follow-up. Public drafting still requires share_ready verification.\n")
         .option("--run <id>", "Run id or latest pointer.", "latest")
         .option("--cwd <path>", "Target project directory.", ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
@@ -1751,6 +1878,8 @@ function registerFeedbackCommands(parent, io) {
         .description("Generate a public-safe feedback draft from verified evidence.")
         .option("--run <id>", "Run id or latest pointer.", "latest")
         .option("--cwd <path>", "Target project directory.", ".")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to draft (ids from `feedback list`); default: the first.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
@@ -1763,6 +1892,8 @@ function registerFeedbackCommands(parent, io) {
         .description("Verify the feedback draft for public issue eligibility.")
         .option("--run <id>", "Run id or latest pointer.", "latest")
         .option("--cwd <path>", "Target project directory.", ".")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to verify (ids from `feedback list`); default: the first.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
@@ -1777,6 +1908,8 @@ function registerFeedbackCommands(parent, io) {
         .option("--cwd <path>", "Target project directory.", ".")
         .requiredOption("--repo <owner/repo>", "Repository slug used in rendered filing instructions.")
         .option("--format <format>", "Output format.", "markdown")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to file (ids from `feedback list`); default: the first.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
@@ -1803,6 +1936,8 @@ function registerFeedbackCommands(parent, io) {
         .option("--run <id>", "Run id or latest pointer.", "latest")
         .option("--cwd <path>", "Target project directory.", ".")
         .requiredOption("--repo <owner/repo>", "Repository slug used in the generated URL.")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to link (ids from `feedback list`); default: the first.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
@@ -3455,19 +3590,27 @@ function exitCodeForSignal(signal) {
 }
 /** `--candidate` as the module option, absent when not given (exactOptionalPropertyTypes). */
 function candidateOption(options) {
-    return options.candidate === undefined ? {} : { candidate: options.candidate };
+    return { ...(options.candidate === undefined ? {} : { candidate: options.candidate }),
+        ...(options.analysis === undefined ? {} : { analysis: options.analysis }),
+        ...(options.finding === undefined ? {} : { finding: options.finding }) };
 }
 function formatFeedbackHuman(result) {
     if (!result.ok) {
         return `${result.error?.code}: ${result.error?.message}\n`;
     }
     const candidates = result.candidates ?? [];
+    const noCandidates = result.candidates !== undefined && candidates.length === 0;
     return [
-        "humanish feedback ready",
+        noCandidates && result.draft === undefined ? "humanish feedback: no recorded candidates" : "humanish feedback ready",
         `run: ${result.run}`,
         ...(result.draftPath ? [`draft: ${result.draftPath}`] : []),
         ...(result.issuePath ? [`issue: ${result.issuePath}`] : []),
         ...(result.draft?.source_candidate_id ? [`candidate: ${result.draft.source_candidate_id}`] : []),
+        ...(noCandidates ? [
+            "candidates: none recorded",
+            "With no candidates, feedback draft and feedback issue can generate a run-summary follow-up after share_ready verification.",
+            ...(result.draft ? [`summary: ${result.draft.summary}`] : [])
+        ] : []),
         // Every finding the run produced, so the second and third are one flag away (#609).
         ...(candidates.length > 1 || (candidates.length === 1 && result.draft === undefined)
             ? [