humanish 0.105.0 → 0.106.0

package/dist/cli/commands/analyze.js

@@ -0,0 +1,212 @@
+import { resolveAutomaticAnalysis, DEFAULT_ANALYSIS_MODEL, DEFAULT_ANALYSIS_TIMEOUT_MS, } from "../../analysis/automatic-config.js";
+import { Command, Option } from "commander";
+import { forTerminal } from "../../routes/terminal/encoding.js";
+import { analyzeRun, correctAnalysis, dryRunBundleRefusal, showAnalysis, } from "../../analysis/service.js";
+import { listAnalyses } from "../../analysis/store.js";
+import { listStudyAnalysisExecutions } from "../../analysis/store-executions.js";
+import { resolveRunPath } from "../../run/locate.js";
+import { discoverCliKeys, JSON_OPTION_DESCRIPTION, writeResult } from "../io.js";
+import { resolvePhysicalCwd } from "../../run/paths.js";
+/** 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;
+}
+export function registerAnalyzeCommand(parent, io) {
+    const analyze = parent
+        .command("analyze")
+        .enablePositionalOptions()
+        .description("Analyze retained participant evidence into versioned findings. Selected text and captures go to the chosen remote analyst. 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("--provider <name>", "Analyst: openai (default) or restricted codex account. No provider fallback.")
+        .option("--max-cost <usd>", "Required for OpenAI, including dry-run: USD admission estimate ceiling, not a billing cap. Unsupported for Codex.")
+        .option("--model <id>", "Supported vision model. OpenAI uses high effort; qualified Codex account analysis uses low effort.", DEFAULT_ANALYSIS_MODEL)
+        .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
+        .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", String(DEFAULT_ANALYSIS_TIMEOUT_MS))
+        .option("--max-output-tokens <n>", "OpenAI response-token limit including reasoning, 256–32768. Omit for admission-based sizing. Unsupported for Codex.")
+        .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((options, command) => handleAnalyze(io, options, command));
+    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((options, command) => handleAnalyzeList(io, options, command));
+    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((options, command) => handleAnalyzeShow(io, options, command));
+    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((options, command) => handleAnalyzeCorrect(io, options, command));
+}
+async function handleAnalyze(io, options, command) {
+    const selected = resolveAutomaticAnalysis({
+        ...(options.provider === undefined ? {} : { provider: options.provider }),
+        model: options.model,
+        ...(options.question === undefined ? {} : { question: options.question }),
+        timeoutMs: Number(options.timeoutMs),
+        ...(options.provider === "codex" && options.maxCost === undefined
+            ? {}
+            : { maxCostUsd: Number(options.maxCost) }),
+        ...(options.maxOutputTokens === undefined
+            ? {}
+            : { maxOutputTokens: Number(options.maxOutputTokens) }),
+    });
+    if (!selected.ok || !selected.config) {
+        const refusal = await dryRunBundleRefusal(await resolvePhysicalCwd(options.cwd), options.run, options.dryRun === true);
+        if (refusal) {
+            writeResult(command, io, refusal, (value) => forTerminal(`${value.error?.message ?? ""}\n${value.error?.code ?? ""}\n`));
+            io.setExitCode(2);
+            return;
+        }
+        const result = {
+            schema: "humanish.analyze-result.v1",
+            ok: false,
+            run: options.run,
+            dryRun: options.dryRun === true,
+            reused: false,
+            warnings: [],
+            error: {
+                code: "ANALYSIS_CONFIG_INVALID",
+                message: selected.ok ? "Analysis is disabled." : selected.message,
+            },
+        };
+        writeResult(command, io, result, (value) => `${value.error.message}\n`);
+        io.setExitCode(2);
+        return;
+    }
+    // Only a live OpenAI analysis sends OPENAI_API_KEY. A dry run and the Codex account analyst
+    // read no provider key, so they skip discovery and its `gh auth token` spawn.
+    if (options.dryRun !== true && selected.config.provider !== "codex")
+        await discoverCliKeys({ io, cwd: options.cwd });
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once("SIGINT", cancel);
+    try {
+        const result = await analyzeRun(options.cwd, options.run, {
+            config: selected.config,
+            preferLargerOutput: selected.preferLargerOutput === true,
+            ...(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 && selected.config?.provider === "codex")
+                return "Local evidence and configuration passed admission. Codex CLI, login and model access were not checked. Dollar cost and output-token ceiling are unknown. No provider request sent.\n";
+            if (value.ok && value.dryRun)
+                return `Admission estimate: $${value.admission?.estimatedCostUsd ?? "unknown"}; output allowance: ${value.admission?.outputTokenAllowance ?? "unknown"} tokens including reasoning. 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.usageComplete ? "" : " (incomplete)"}: ${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);
+    }
+}
+async function handleAnalyzeList(io, options, command) {
+    options = analysisSelection(options, command);
+    const prepared = await resolveRunPath(await resolvePhysicalCwd(options.cwd), options.run).catch(() => null);
+    const versions = prepared ? await listAnalyses(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);
+}
+async function handleAnalyzeShow(io, options, command) {
+    options = analysisSelection(options, command);
+    const result = await showAnalysis(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);
+}
+async function handleAnalyzeCorrect(io, options, command) {
+    options = analysisSelection(options, command);
+    try {
+        const correction = await correctAnalysis(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);
+    }
+}

package/dist/cli/commands/codex.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerCodexCommands(parent: Command, io: CliIo): void;

package/dist/cli/commands/codex.js

@@ -0,0 +1,145 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Command, Option } from "commander";
+import { startCodexAppServerUi } from "../../actors/codex/app-server-ui.js";
+import { redactText } from "../../evidence/redaction.js";
+import { JSON_OPTION_DESCRIPTION, parseObserverPort, parseTimeoutMs, writeResult, } from "../io.js";
+export function registerCodexCommands(parent, io) {
+    const codex = parent
+        .command("codex")
+        .description("Run Codex-native humanish integration surfaces.")
+        .summary("Run Codex-native humanish integration surfaces.");
+    codex
+        .command("app-server")
+        .description("Run a browser-visible Codex app-server actor surface and write redacted protocol artifacts.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--prompt <text>", "Prompt to submit to Codex app-server.")
+        .option("--prompt-file <path>", "Read the Codex app-server prompt from a file.")
+        .option("--run-root <path>", "Artifact directory for redacted app-server evidence.")
+        .option("--state-file <path>", "State JSON file for external observers.")
+        .option("--timeout-ms <ms>", "Actor timeout in milliseconds.", String(900_000))
+        .option("--port <port>", "Local browser UI port.", "0")
+        .option("--model <model>", "Optional Codex model override.")
+        .addOption(new Option("--sandbox <mode>", "Turn sandbox policy.")
+        .choices(["read-only", "workspace-write", "danger-full-access"])
+        .default("read-only"))
+        .option("--actor-command <command>", "Override app-server command. Defaults to codex app-server --listen stdio://.")
+        .option("--keep-open", "Keep the browser UI process alive after the actor finishes.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const timeoutMs = parseTimeoutMs(options.timeoutMs);
+        const port = parseObserverPort(options.port);
+        if (timeoutMs === null) {
+            const result = codexAppServerUiError(options.cwd, "HUMANISH_INVALID_TIMEOUT", "--timeout-ms must be an integer between 1 and 3600000.");
+            writeResult(command, io, result, formatCodexAppServerUiHuman);
+            io.setExitCode(2);
+            return;
+        }
+        if (port === null) {
+            const result = codexAppServerUiError(options.cwd, "HUMANISH_INVALID_PORT", "--port must be an integer between 0 and 65535.");
+            writeResult(command, io, result, formatCodexAppServerUiHuman);
+            io.setExitCode(2);
+            return;
+        }
+        const prompt = await readCodexAppServerPrompt(options);
+        if (!prompt) {
+            const result = codexAppServerUiError(options.cwd, "HUMANISH_CODEX_APP_SERVER_PROMPT_REQUIRED", "Provide --prompt or --prompt-file.");
+            writeResult(command, io, result, formatCodexAppServerUiHuman);
+            io.setExitCode(2);
+            return;
+        }
+        const controller = await startCodexAppServerUi({
+            ...(options.actorCommand === undefined ? {} : { actorCommand: options.actorCommand }),
+            cwd: options.cwd,
+            keepOpen: options.keepOpen === true,
+            ...(options.model === undefined ? {} : { model: options.model }),
+            port,
+            prompt,
+            ...(options.runRoot === undefined ? {} : { runRoot: options.runRoot }),
+            sandbox: options.sandbox,
+            ...(options.stateFile === undefined ? {} : { stateFile: options.stateFile }),
+            timeoutMs,
+        });
+        const initial = {
+            schema: "humanish.codex-app-server-ui-result.v1",
+            ok: true,
+            cwd: resolve(options.cwd),
+            stateFile: controller.stateFile,
+            url: controller.url,
+            status: controller.initialState.status,
+            reason: controller.initialState.reason,
+        };
+        if (options.keepOpen === true) {
+            writeResult(command, io, initial, formatCodexAppServerUiHuman);
+            io.setExitCode(0);
+            try {
+                // Local hardening for the known double-envelope path: the "running"
+                // envelope above has already reached stdout, so a rejection here
+                // (src/actors/codex/app-server-ui.ts's persistState() write can fail on either
+                // branch of session completion) must not go through the
+                // command-boundary catch-all's --json branch, which would otherwise
+                // append a second JSON document to stdout. Handling it here directly
+                // means this known path stays correct even if that general guard is
+                // ever weakened; it does not replace it.
+                await controller.completion;
+                await new Promise((resolveWait) => {
+                    process.once("SIGINT", () => {
+                        void controller.close().finally(resolveWait);
+                    });
+                });
+            }
+            catch (error) {
+                io.writeErr(`HUMANISH_UNEXPECTED: ${redactText(error instanceof Error ? error.message : String(error))}\n`);
+                io.setExitCode(2);
+            }
+            return;
+        }
+        const completed = await controller.completion;
+        const output = codexAppServerUiResultFromState(completed);
+        writeResult(command, io, output, formatCodexAppServerUiHuman);
+        io.setExitCode(output.ok ? 0 : 2);
+    });
+}
+function formatCodexAppServerUiHuman(result) {
+    if (!result.ok) {
+        return `${result.error?.code}: ${result.error?.message}\n`;
+    }
+    return ([
+        "humanish codex app-server",
+        `url: ${result.url ?? "not-started"}`,
+        `status: ${result.status ?? "unknown"}`,
+        `state: ${result.stateFile ?? "none"}`,
+        `reason: ${result.reason}`,
+    ].join("\n") + "\n");
+}
+async function readCodexAppServerPrompt(options) {
+    if (options.prompt !== undefined && options.prompt.trim()) {
+        return options.prompt;
+    }
+    if (options.promptFile !== undefined && options.promptFile.trim()) {
+        const promptPath = resolve(options.cwd, options.promptFile);
+        const text = await readFile(promptPath, "utf8");
+        return text.trim() || null;
+    }
+    return null;
+}
+function codexAppServerUiError(cwd, code, message) {
+    return {
+        schema: "humanish.codex-app-server-ui-result.v1",
+        ok: false,
+        cwd: resolve(cwd),
+        reason: message,
+        error: { code, message },
+    };
+}
+function codexAppServerUiResultFromState(state) {
+    return {
+        schema: "humanish.codex-app-server-ui-result.v1",
+        ok: state.status === "passed",
+        cwd: state.cwd,
+        reason: state.reason,
+        stateFile: state.stateFile,
+        status: state.status,
+        ...(state.url === undefined ? {} : { url: state.url }),
+    };
+}

package/dist/cli/commands/comms.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerCommsCommands(parent: Command, io: CliIo): void;

package/dist/cli/commands/comms.js

@@ -0,0 +1,225 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { COMMS_PROVIDERS, saveCommsConnection } from "../../comms/connections.js";
+import { readCommsSetup } from "../../comms/setup.js";
+import { checkCommsConnection, configureCommsLab } from "../../comms/setup.js";
+import { inspectCommsRecovery, recoverCommsReceiving } from "../../comms/receiving-recovery.js";
+import { resolveReceivingConnection } from "../../comms/receiving-runtime.js";
+import { resolveLabManifest } from "../../lab/discover.js";
+import { runCommsCatchHost } from "../../comms/catch-host.js";
+import { DEFAULT_SANDBOX_CATCH_PORT } from "../../comms/sandbox-catch.js";
+import { applyEnvFileOption, JSON_OPTION_DESCRIPTION, writeResult } from "../io.js";
+export function registerCommsCommands(parent, io) {
+    const comms = parent
+        .command("comms")
+        .description("Local email capture, real receiving connections, checks and cleanup recovery.")
+        .summary("Off-app comms surfaces.");
+    comms
+        .command("providers")
+        .description("List installed communication provider capabilities. No network requests.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((_options, command) => handleCommsProviders(io, _options, command));
+    const connections = comms
+        .command("connections")
+        .description("Manage project-local non-secret connection profiles. A lab explicitly selects its receiving connection.");
+    connections
+        .command("list")
+        .description("Show saved connections and local credential status; does not authenticate with a provider.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load credentials for local status without printing values.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleCommsList(io, options, command));
+    connections
+        .command("add")
+        .argument("[name]", "Project connection name.", "agentmail")
+        .description("Save an AgentMail connection profile. Does not write a key, alter a lab or contact the provider.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--provider <id>", "Installed provider id.", "agentmail")
+        .option("--api-key-env <name>", "Environment variable NAME, never its value.", "AGENTMAIL_API_KEY")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((name, options, command) => handleCommsAdd(io, name, options, command));
+    comms
+        .command("check")
+        .description("Check connection and credential presence; --online authenticates without creating inboxes.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--connection <name>", "Saved connection name.", "agentmail")
+        .option("--lab <path>", "Check the connection selected by this exact lab.")
+        .option("--online", "Make a read-only provider authentication request.")
+        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleCommsCheck(io, options, command));
+    comms
+        .command("configure")
+        .description("Preview or save a local receiving-enabled copy of a supported lab. No provider requests.")
+        .requiredOption("--lab <path>", "Exact source lab path or handle.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--connection <name>", "Saved connection name.", "agentmail")
+        .option("--apply", "Save the local copy; original lab remains unchanged.")
+        .option("--plan-token <digest>", "Require the source and destination to match a previous preview.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleCommsConfigure(io, options, command));
+    comms
+        .command("recover")
+        .description("Inspect interrupted email leases; --apply deletes only privately recorded resources owned by this project and account.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", "One run to inspect or recover.")
+        .option("--apply", "Recover the selected inactive run and verify mailbox deletion.")
+        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleCommsRecover(io, options, command));
+    comms
+        .command("catch")
+        .description("Run the email catch on this host so humanish can study an app it does not provision. Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your lab's comms.email.external.catchBaseUrl at this server.")
+        .summary("Run the adopter-hosted email catch.")
+        .option("--port <port>", "Port for capture + inbox (default 8025).", String(DEFAULT_SANDBOX_CATCH_PORT))
+        .option("--dir <path>", "Directory for the deliveries log and rendered inbox.", ".humanish/comms-catch")
+        .option("--token <value>", "Require this bearer token on GET /deliveries (recommended when reachable off-host).")
+        .option("--smtp-port <port>", "Also capture SMTP mail on 127.0.0.1:<port>. Point your app's SMTP transport here.")
+        .option("--inbox-port <port>", "Also serve a READ-ONLY inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
+        .option("--recipient <address>", "Only render mail sent to this address (repeatable). Default: render whatever the app actually mailed.", (value, previous) => [...(previous ?? []), value])
+        .action((options) => handleCommsCatch(io, options));
+}
+function handleCommsProviders(io, _options, command) {
+    const result = {
+        schema: "humanish.comms-providers.v1",
+        ok: true,
+        providers: COMMS_PROVIDERS,
+    };
+    writeResult(command, io, result, () => COMMS_PROVIDERS.map((provider) => `${provider.label}: ${provider.limitation}\nKey: ${provider.keyEnv}\nSetup: ${provider.setupUrl}\n`).join("\n"));
+}
+async function handleCommsList(io, options, command) {
+    if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+        return;
+    const result = await readCommsSetup(resolve(options.cwd), process.env);
+    writeResult(command, io, result, (value) => `${value.message}\nAgentMail key: ${value.credential.present ? "present" : "missing"}\n${value.connections.map((connection) => `${connection.name}: ${connection.provider} (${connection.apiKeyEnv})\n`).join("")}`);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleCommsAdd(io, name, options, command) {
+    const result = {
+        schema: "humanish.comms-connection-result.v1",
+        ...(options.provider === "agentmail"
+            ? await saveCommsConnection(resolve(options.cwd), name, options.apiKeyEnv)
+            : { ok: false, message: "Only AgentMail connection setup is currently available." }),
+    };
+    writeResult(command, io, result, (value) => `${value.message}\n`);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleCommsCheck(io, options, command) {
+    if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+        return;
+    let connection = options.connection;
+    if (options.lab) {
+        const lab = await resolveLabManifest(options.cwd, options.lab);
+        if (!lab.ok || lab.config.comms?.email?.kind !== "real") {
+            const result = {
+                ok: false,
+                message: "This lab does not select a real email connection.",
+            };
+            writeResult(command, io, result, (value) => `${value.message}\n`);
+            io.setExitCode(2);
+            return;
+        }
+        connection = lab.config.comms.email.connection;
+    }
+    const result = await checkCommsConnection({
+        cwd: resolve(options.cwd),
+        connection,
+        env: process.env,
+        online: options.online === true,
+    });
+    writeResult(command, io, result, (value) => `${value.message}\n`);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleCommsConfigure(io, options, command) {
+    const result = await configureCommsLab({ ...options, cwd: resolve(options.cwd) });
+    writeResult(command, io, result, (value) => `${value.message}\n`);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleCommsRecover(io, options, command) {
+    if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+        return;
+    const cwd = resolve(options.cwd);
+    try {
+        const entries = (await inspectCommsRecovery({ cwd })).filter((entry) => !options.run || entry.runId === options.run);
+        if (!options.apply) {
+            const result = { schema: "humanish.comms-recovery.v1", ok: true, entries };
+            writeResult(command, io, result, (value) => value.entries.length
+                ? value.entries
+                    .map((entry) => `${entry.runId}: ${entry.unresolvedCount} unresolved; ${entry.activeOwner === null ? "unknown owner" : entry.activeOwner ? "active owner" : "inactive"}\n`)
+                    .join("")
+                : "No recoverable email leases in this project.\n");
+            return;
+        }
+        if (!options.run || entries.length !== 1)
+            throw new Error("selection");
+        const entry = entries[0];
+        const { connection, adapter } = await resolveReceivingConnection(cwd, entry.connectionName, process.env);
+        const result = {
+            schema: "humanish.comms-recovery-result.v1",
+            ...(await recoverCommsReceiving({
+                cwd,
+                runId: options.run,
+                connectionName: entry.connectionName,
+                apiKeyEnv: connection.apiKeyEnv,
+                adapter,
+            })),
+        };
+        writeResult(command, io, result, (value) => `${value.message}\n`);
+        io.setExitCode(result.ok ? 0 : 2);
+    }
+    catch {
+        const result = {
+            schema: "humanish.comms-recovery-result.v1",
+            ok: false,
+            message: "Recovery could not complete. Select one recorded run with --run, check its connection, and retry. No unrecorded resources are eligible.",
+        };
+        writeResult(command, io, result, (value) => `${value.message}\n`);
+        io.setExitCode(2);
+    }
+}
+async function handleCommsCatch(io, options) {
+    const port = Number.parseInt(options.port, 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_534) {
+        io.writeErr("--port must be an integer between 1 and 65534.\n");
+        io.setExitCode(2);
+        return;
+    }
+    let inboxPort;
+    if (options.inboxPort !== undefined) {
+        inboxPort = Number.parseInt(options.inboxPort, 10);
+        if (!Number.isInteger(inboxPort) || inboxPort <= 0 || inboxPort > 65_534) {
+            io.writeErr("--inbox-port must be an integer between 1 and 65534.\n");
+            io.setExitCode(2);
+            return;
+        }
+        if (inboxPort === port) {
+            io.writeErr("--inbox-port must differ from --port (the capture listener is loopback-only; the inbox listener is not).\n");
+            io.setExitCode(2);
+            return;
+        }
+    }
+    let smtpPort;
+    if (options.smtpPort !== undefined) {
+        smtpPort = Number(options.smtpPort);
+        if (!Number.isInteger(smtpPort) || smtpPort <= 0 || smtpPort > 65_534) {
+            io.writeErr("--smtp-port must be an integer between 1 and 65534.\n");
+            io.setExitCode(2);
+            return;
+        }
+        if (smtpPort === port || smtpPort === inboxPort) {
+            io.writeErr("--smtp-port must differ from --port and --inbox-port.\n");
+            io.setExitCode(2);
+            return;
+        }
+    }
+    await runCommsCatchHost({
+        port,
+        dir: options.dir,
+        ...(options.token ? { token: options.token } : {}),
+        ...(inboxPort === undefined ? {} : { inboxPort }),
+        ...(smtpPort === undefined ? {} : { smtpPort }),
+        ...(options.recipient && options.recipient.length > 0
+            ? { recipients: options.recipient }
+            : {}),
+    }, io);
+}

package/dist/cli/commands/feedback.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerFeedbackCommands(parent: Command, io: CliIo): void;