productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/redactGate.js

@@ -0,0 +1,209 @@
+// Prompt Redaction Safety V0 — T-003 (R-004): the fail-closed commit gate.
+// `foo self gate` scans staged content and hard-blocks high-confidence secrets
+// before they can be committed (the irreversible egress, D-001). Calibrated
+// (D-003): only HIGH confidence blocks; lower confidence is advisory and never
+// gates. Bypass requires a human-set, recorded reason (R-007 human-only).
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+import { gitRun, gitRunBuffer } from "./gitRun.js";
+import { scanText } from "./redactEngine.js";
+import { loadRepoAllowlist } from "./redactConfig.js";
+// Pure decision: block iff a high-confidence secret is present and no override
+// reason was supplied. Deterministic and side-effect-free for testability.
+export function decideGate(staged, opts = {}) {
+    const high = [];
+    for (const f of staged) {
+        for (const finding of scanText(f.text, { allowlist: opts.allowlist }).findings) {
+            if (finding.confidence === "high")
+                high.push({ file: f.file, line: finding.line, column: finding.column, detector: finding.detector });
+        }
+    }
+    if (high.length === 0)
+        return { blocked: false, overridden: false, high: [] };
+    const reason = (opts.overrideReason ?? "").trim();
+    if (reason)
+        return { blocked: false, overridden: true, high, reason };
+    return { blocked: true, overridden: false, high };
+}
+const AUDIT_DIR = ".foo";
+const AUDIT_FILE = "redaction-overrides.jsonl";
+const MAX_STAGED_BYTES = 16 * 1024 * 1024;
+const SCANNER_GIT_OPTIONS = { stdio: ["ignore", "pipe", "pipe"] };
+const REGULAR_BLOB_MODES = new Set(["100644", "100755"]);
+// With -z, raw diff records are:
+//   :<old-mode> <new-mode> <old-oid> <new-oid> <status>\0<path>\0
+// Rename/copy records carry both old and new paths after the header. Reject the
+// entire listing if Git returns anything incomplete or ambiguous: a partial
+// index view cannot support a clean result.
+function parseStagedIndex(raw) {
+    if (raw.length === 0)
+        return [];
+    if (!raw.endsWith("\0"))
+        return null;
+    const fields = raw.slice(0, -1).split("\0");
+    const entries = [];
+    const seen = new Set();
+    let cursor = 0;
+    while (cursor < fields.length) {
+        const header = fields[cursor++];
+        const match = /^:([0-7]{6}) ([0-7]{6}) ([0-9a-f]+) ([0-9a-f]+) ([A-Z])(\d*)$/.exec(header ?? "");
+        if (!match)
+            return null;
+        const sourcePath = fields[cursor++];
+        if (!sourcePath)
+            return null;
+        const status = match[5];
+        const file = status === "R" || status === "C" ? fields[cursor++] : sourcePath;
+        if (!file || seen.has(file))
+            return null;
+        seen.add(file);
+        entries.push({ file, mode: match[2] });
+    }
+    return entries;
+}
+function isProbablyText(buf) {
+    for (let i = 0; i < buf.length; i++) {
+        const byte = buf[i];
+        if (byte === 0 || (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d) || byte === 0x7f)
+            return false;
+    }
+    return true;
+}
+// Read the staged (index) content of files about to be committed. Every entry
+// either becomes scannable UTF-8 text or a metadata-only refusal record.
+export function readStaged(root, seams = {}) {
+    const run = seams.gitRun ?? gitRun;
+    const runBuffer = seams.gitRunBuffer ?? gitRunBuffer;
+    const listed = run(["diff", "--cached", "--raw", "--diff-filter=d", "-M", "-z"], { ...SCANNER_GIT_OPTIONS, cwd: root });
+    if (!listed.ok)
+        return { scanned: [], unscannable: [{ file: "[git-index]", reason: "git-index-unavailable" }] };
+    const entries = parseStagedIndex(listed.stdout);
+    if (!entries)
+        return { scanned: [], unscannable: [{ file: "[git-index]", reason: "git-index-unavailable" }] };
+    const scanned = [];
+    const unscannable = [];
+    for (const { file, mode } of entries) {
+        if (!REGULAR_BLOB_MODES.has(mode)) {
+            unscannable.push({ file, reason: "unsupported-file-type" });
+            continue;
+        }
+        // Ask git for size before reading bytes, so arbitrarily large blobs never
+        // enter this process merely to learn that they exceed the scanner bound.
+        const sized = run(["cat-file", "-s", `:${file}`], { ...SCANNER_GIT_OPTIONS, cwd: root });
+        const sizeText = sized.stdout.endsWith("\n") ? sized.stdout.slice(0, -1) : sized.stdout;
+        if (!sized.ok || !/^(?:0|[1-9]\d*)$/.test(sizeText)) {
+            unscannable.push({ file, reason: "blob-unreadable" });
+            continue;
+        }
+        const bytes = Number(sizeText);
+        if (!Number.isSafeInteger(bytes)) {
+            unscannable.push({ file, reason: "blob-unreadable" });
+            continue;
+        }
+        if (bytes > MAX_STAGED_BYTES) {
+            unscannable.push({ file, reason: "blob-too-large" });
+            continue;
+        }
+        const blob = runBuffer(["show", `:${file}`], { ...SCANNER_GIT_OPTIONS, cwd: root, maxBuffer: MAX_STAGED_BYTES + 1 });
+        if (!blob.ok) {
+            unscannable.push({ file, reason: "blob-unreadable" });
+            continue;
+        }
+        if (blob.stdout.length !== bytes) {
+            unscannable.push({ file, reason: "blob-unreadable" });
+            continue;
+        }
+        if (!isProbablyText(blob.stdout)) {
+            unscannable.push({ file, reason: "binary-or-nul" });
+            continue;
+        }
+        try {
+            scanned.push({ file, text: new TextDecoder("utf-8", { fatal: true }).decode(blob.stdout) });
+        }
+        catch {
+            unscannable.push({ file, reason: "decode-failed" });
+        }
+    }
+    return { scanned, unscannable };
+}
+function recordOverride(root, decision, at) {
+    mkdirSync(path.join(root, AUDIT_DIR), { recursive: true });
+    // Metadata-only audit record — reason + locations, never a secret value.
+    const byFile = new Map();
+    for (const f of decision.high) {
+        const list = byFile.get(f.file) ?? [];
+        list.push(f);
+        byFile.set(f.file, list);
+    }
+    const record = {
+        time: at,
+        reason: decision.reason,
+        total_high: decision.high.length,
+        files: [...byFile.entries()].map(([file, findings]) => ({
+            file,
+            findings: findings.map((x) => ({ line: x.line, column: x.column, detector: x.detector })),
+        })),
+    };
+    appendFileSync(path.join(root, AUDIT_DIR, AUDIT_FILE), `${JSON.stringify(record)}\n`);
+}
+export const UNSCANNABLE_REFUSAL = Object.freeze({
+    schema_version: "0.1",
+    status: "refused",
+    reason_code: "staged_file_unscannable",
+    message: "Staged scanning could not verify every staged file.",
+    safe_next_action: "Remove, replace, or convert each listed file to scannable UTF-8 text under 16 MiB, restage, and retry.",
+});
+function safeFilename(file) {
+    return safeJson(file);
+}
+function safeJson(value) {
+    return JSON.stringify(value).replace(/[\u007f-\u009f\u2028\u2029]/g, (char) => `\\u${char.codePointAt(0)?.toString(16).padStart(4, "0")}`);
+}
+function renderUnscannable(unscannable, machine) {
+    if (machine)
+        return safeJson({ ...UNSCANNABLE_REFUSAL, unscannable });
+    const files = unscannable.map(({ file, reason }) => `${safeFilename(file)} (${reason})`).join(", ");
+    return `blocked — ${UNSCANNABLE_REFUSAL.message} ${files}. ${UNSCANNABLE_REFUSAL.safe_next_action}`;
+}
+export function runRedactGate(root, opts = {}) {
+    const staged = readStaged(root, opts.seams);
+    if (staged.unscannable.length > 0) {
+        const machine = opts.machine ?? !process.stdout.isTTY;
+        return {
+            output: `${renderUnscannable(staged.unscannable, machine)}\n`,
+            exitCode: 1,
+            unscannable: true,
+            refusal: UNSCANNABLE_REFUSAL,
+            files: staged.unscannable,
+        };
+    }
+    const allowlist = loadRepoAllowlist(root);
+    const overrideReason = opts.overrideReason ?? process.env.FOO_REDACT_ALLOW;
+    const decision = decideGate(staged.scanned, { allowlist, overrideReason });
+    if (decision.blocked) {
+        const lines = [
+            "foo self gate — BLOCKED: high-confidence secret(s) in staged changes",
+            "",
+            ...decision.high.map((f) => `  ${f.file}:${f.line}:${f.column}  [high] ${f.detector}`),
+            "",
+            "Fix: redact before committing — `foo redact <file> --write` (review the diff), or remove the secret.",
+            'Override (human, audited): FOO_REDACT_ALLOW="why this is safe" git commit ...',
+            "Secret values are never shown or stored (R-007).",
+            "",
+        ];
+        return { output: lines.join("\n"), exitCode: 1, unscannable: false };
+    }
+    if (decision.overridden) {
+        recordOverride(root, decision, opts.at ?? new Date().toISOString());
+        const lines = [
+            `foo self gate — OVERRIDE: ${decision.high.length} high-confidence finding(s) bypassed`,
+            `  reason: ${decision.reason}`,
+            `  recorded to ${AUDIT_DIR}/${AUDIT_FILE} (metadata-only)`,
+            ...decision.high.map((f) => `  ${f.file}:${f.line} [high] ${f.detector}`),
+            "",
+        ];
+        return { output: lines.join("\n"), exitCode: 0, unscannable: false };
+    }
+    return { output: `foo self gate — ok: no high-confidence secrets in ${staged.scanned.length} staged file(s).\n`, exitCode: 0, unscannable: false };
+}

package/dist-public/src/repoRead.d.ts

@@ -0,0 +1,29 @@
+import type { Tension } from "./firstMoveTensions.js";
+export type RepoSignals = {
+    languages: string[];
+    hasTests: boolean;
+    hasCI: boolean;
+    readmeBytes: number;
+    bigFile: {
+        path: string;
+        lines: number;
+    } | null;
+    sourceFileCount: number;
+};
+export type Move = {
+    id: string;
+    title: string;
+    evidence: string[];
+    risk: number;
+    leverage: number;
+    effort: number;
+    tension?: Tension;
+};
+export declare function gatherRepoSignals(root: string): RepoSignals;
+export declare function generateMoves(signals: RepoSignals): Move[];
+export type RankedMoves = {
+    recommended: Move | null;
+    rest: Move[];
+    why: string | null;
+};
+export declare function rankMoves(moves: Move[]): RankedMoves;

package/dist-public/src/repoRead.js

@@ -0,0 +1,160 @@
+import { gitRunOrNull } from "./gitRun.js";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+function git(root, args) {
+    return gitRunOrNull(args, { cwd: root, stdio: ["ignore", "pipe", "ignore"] });
+}
+// Tracked files only — never walks untracked or ignored paths, so secrets and
+// build output stay unread.
+function trackedFiles(root) {
+    const out = git(root, ["ls-files"]);
+    if (out !== null)
+        return out.split(/\r?\n/).filter((l) => l.trim() !== "");
+    // Non-git fallback: a shallow read of the top level only.
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isFile())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+const LANG_BY_EXT = {
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".py": "Python",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".java": "Java",
+};
+const SOURCE_EXTS = new Set(Object.keys(LANG_BY_EXT));
+// Skip vendored, pinned, generated, or minified paths — they are not the
+// developer's own code and would make the read point at noise (e.g. a pinned
+// helper bundle or a 10k-line minified file).
+function isVendored(file) {
+    if (file.startsWith("."))
+        return true; // .agents/, .github/, dotfiles
+    if (/(^|\/)(vendor|third_party|node_modules|dist|build|generated)(\/|$)/.test(file))
+        return true;
+    if (/\.min\.[a-z]+$/.test(file))
+        return true;
+    return false;
+}
+function isTestPath(file) {
+    return /(^|\/)(test|tests|__tests__|spec)(\/|$)/i.test(file) || /\.(test|spec)\.[a-z]+$/i.test(file);
+}
+function countLines(root, file) {
+    try {
+        return readFileSync(path.join(root, file), "utf8").split(/\r?\n/).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export function gatherRepoSignals(root) {
+    const files = trackedFiles(root);
+    const langCounts = new Map();
+    let sourceFileCount = 0;
+    let hasTests = false;
+    let bigFile = null;
+    for (const file of files) {
+        if (isVendored(file))
+            continue;
+        const ext = path.extname(file);
+        if (SOURCE_EXTS.has(ext)) {
+            sourceFileCount += 1;
+            const lang = LANG_BY_EXT[ext];
+            langCounts.set(lang, (langCounts.get(lang) ?? 0) + 1);
+            if (isTestPath(file))
+                hasTests = true;
+        }
+    }
+    // Largest tracked source file (a documentation / decomposition candidate).
+    for (const file of files) {
+        if (isVendored(file) || !SOURCE_EXTS.has(path.extname(file)) || isTestPath(file))
+            continue;
+        const lines = countLines(root, file);
+        if (!bigFile || lines > bigFile.lines)
+            bigFile = { path: file, lines };
+    }
+    const readmePath = ["README.md", "README", "readme.md"].map((r) => path.join(root, r)).find(existsSync);
+    const readmeBytes = readmePath ? statSync(readmePath).size : 0;
+    const languages = [...langCounts.entries()].sort((a, b) => b[1] - a[1]).map(([lang]) => lang);
+    return {
+        languages,
+        hasTests,
+        hasCI: existsSync(path.join(root, ".github", "workflows")),
+        readmeBytes,
+        bigFile,
+        sourceFileCount,
+    };
+}
+// Generate candidate moves, each gated on a concrete fact. Order here is the
+// pre-ranking; scoreMoves decides the recommendation.
+export function generateMoves(signals) {
+    const moves = [];
+    if (signals.sourceFileCount > 0 && !signals.hasTests) {
+        moves.push({
+            id: "add-tests",
+            title: "Add a test safety net",
+            evidence: [`${signals.sourceFileCount} source file(s) and no tests found`],
+            risk: 3,
+            leverage: 3,
+            effort: 2,
+        });
+    }
+    if (!signals.hasCI && signals.sourceFileCount > 0) {
+        moves.push({
+            id: "add-ci",
+            title: "Set up CI so changes get checked automatically",
+            evidence: ["no .github/workflows — nothing runs on push"],
+            risk: 2,
+            leverage: 2,
+            effort: 1,
+        });
+    }
+    if (signals.readmeBytes < 400) {
+        moves.push({
+            id: "write-readme",
+            title: signals.readmeBytes === 0 ? "Write a README" : "Expand the thin README",
+            evidence: [signals.readmeBytes === 0 ? "no README found" : `README is only ${signals.readmeBytes} bytes`],
+            risk: 1,
+            leverage: 1,
+            effort: 1,
+        });
+    }
+    if (signals.bigFile && signals.bigFile.lines > 600) {
+        moves.push({
+            id: "tame-big-file",
+            title: `Break up ${signals.bigFile.path}`,
+            evidence: [`${signals.bigFile.path} is ${signals.bigFile.lines} lines — hard to change safely`],
+            risk: 2,
+            leverage: 2,
+            effort: 3,
+        });
+    }
+    return moves;
+}
+function score(move) {
+    // Favor high risk + high leverage, discount effort. Risk and leverage matter
+    // more than effort, so a risky-but-pricey fix can still win.
+    return move.risk * 2 + move.leverage * 2 - move.effort;
+}
+export function rankMoves(moves) {
+    const sorted = [...moves].sort((a, b) => score(b) - score(a) || a.id.localeCompare(b.id));
+    const recommended = sorted[0] ?? null;
+    const rest = sorted.slice(1);
+    // The why adds comparative reasoning — it does not restate the evidence line
+    // shown above it. Grounded in the ranking: top wins on leverage-per-effort.
+    let why = null;
+    if (recommended) {
+        why = rest.length
+            ? "it's the most leverage for the least effort of the options here, so the rest can wait"
+            : "it's the highest-leverage thing to settle before anything else";
+    }
+    return { recommended, rest, why };
+}

package/dist-public/src/research.d.ts

@@ -0,0 +1,242 @@
+import { type PricingTable } from "./loopBudget.js";
+import type { FetchLike, SocialSource, YtDlp } from "./social/types.js";
+export type SourceClass = "repo" | "web_free" | "web_firecrawl" | "social" | "connected";
+export type SourceStatus = "available" | "degraded" | "excluded";
+export type Depth = "fast" | "standard" | "deep";
+export interface SourceReport {
+    class: SourceClass;
+    status: SourceStatus;
+    reason: string;
+    skill: string | null;
+}
+export interface ResearchEnv {
+    firecrawlKey?: string;
+    connectedRuntime?: boolean;
+    approvedSources?: string[];
+}
+export interface DetectOptions {
+    cwd?: string;
+    env?: ResearchEnv;
+}
+export declare function resolveEnv(processEnv?: NodeJS.ProcessEnv): ResearchEnv;
+export type ClaimLabel = "primary" | "vendor" | "social" | "call";
+export declare const CLAIM_LABELS: ClaimLabel[];
+export type Confidence = "high" | "medium" | "low";
+export declare const CONFIDENCE_LEVELS: Confidence[];
+export interface Claim {
+    text: string;
+    source_class: ClaimLabel;
+    confidence: Confidence;
+    dissent: string | null;
+    source?: string;
+}
+export interface PanelFinding {
+    lens: string;
+    finding: string;
+    dissent: boolean;
+}
+export interface Theme {
+    title: string;
+    implication: string;
+    claims?: number[];
+}
+export interface Direction {
+    owner: string;
+    recommendation: string;
+    rationale: string;
+    falsifier?: string;
+    alternatives: string[];
+    status?: "proposed" | "decided";
+    decision?: string;
+}
+export interface ResearchPaper {
+    schema_version: "0.1";
+    topic: string;
+    date: string;
+    depth: Depth;
+    sources: SourceReport[];
+    claims: Claim[];
+    panel_findings: PanelFinding[];
+    open_questions: string[];
+    verdict?: string;
+    direction?: Direction;
+    themes?: Theme[];
+    recommendations?: string[];
+    self_application?: Claim;
+}
+export interface ParsedPaper {
+    topic: string;
+    date: string;
+    depth: Depth;
+    sources: Record<SourceClass, SourceStatus>;
+    claims: Claim[];
+    panel_findings: PanelFinding[];
+    open_questions: string[];
+    self_application?: Claim;
+}
+export declare function firecrawlUpsell(sources: SourceReport[]): string | null;
+export declare function assertNoPrivateToFirecrawl(routedClasses: SourceClass[]): void;
+export interface ConnectedSourceRef {
+    id: string;
+    approved: boolean;
+}
+export declare function admitApprovedSources(discovered: ConnectedSourceRef[]): string[];
+export interface ConnectedEvidence {
+    source: string;
+    redacted: boolean;
+    summary: string;
+    link?: string;
+    raw?: string;
+}
+export declare function assertRedactedTranscript(evidence: ConnectedEvidence): void;
+export declare function detectSources(root: string, options?: DetectOptions): SourceReport[];
+export declare function hasZeroConfigValue(sources: SourceReport[]): boolean;
+export declare const PANEL_ROLES: readonly ["domain-expert", "methodologist", "red-team-skeptic"];
+export interface PanelSpec {
+    always: true;
+    blocking: false;
+    depth: Depth;
+    deep_swarm: boolean;
+    lenses: string[];
+}
+export declare function buildPanel(depth: Depth): PanelSpec;
+export declare const ALLOWED_ACTIONS: readonly ["read_repo", "search_web", "fetch_web_untrusted", "read_approved_connected", "synthesize_paper", "write_scratch_paper"];
+export declare const FORBIDDEN_ACTIONS: readonly ["send", "post", "commit_secret", "push", "mutate_source", "exfiltrate_private_data", "send_private_to_firecrawl", "ungated_outbound_inference"];
+export interface SafetyPosture {
+    read_and_synthesize_only: true;
+    untrusted_web_isolated: true;
+    outbound_actions: string[];
+    allowed_actions: string[];
+    forbidden_actions: string[];
+}
+export declare function safetyPosture(): SafetyPosture;
+export declare function assertReadAndSynthesizeOnly(plannedActions: string[]): void;
+export interface ScreenResult {
+    inert_text: string;
+    stripped_directives: string[];
+    triggered: boolean;
+}
+export declare function screenUntrustedWeb(content: string): ScreenResult;
+export interface DepthBounds {
+    depth: Depth;
+    sources_max: number;
+    pages_max: number;
+    panel_size: number;
+}
+export declare function depthBounds(depth: Depth): DepthBounds;
+export interface DeepEstimate {
+    basis: "heuristic";
+    unit: "tokens";
+    expected_tokens: number;
+    ceiling_tokens: number;
+    /** Dollar range, null when the price table cannot price the worker model. */
+    expected_usd: number | null;
+    ceiling_usd: number | null;
+    priced_with: string;
+    confidence: Confidence;
+    disclosure: string;
+    /** What this number does NOT cover — stated, never implied. */
+    excludes: string[];
+}
+export declare function estimateDeep(bounds: DepthBounds, pricing?: PricingTable, worker?: string): DeepEstimate;
+export declare function estimateForDepth(depth: Depth, pricing?: PricingTable, worker?: string): DeepEstimate;
+export declare function estimatePitch(sections: number, panelSize: number, pricing?: PricingTable, worker?: string): DeepEstimate;
+export interface RecencyWindow {
+    days: number;
+    end_date: string | null;
+}
+export declare const DEFAULT_RECENCY_DAYS = 30;
+export interface ResearchArgs {
+    topic: string;
+    depth: Depth;
+    out: string | null;
+    toShape: boolean;
+    json: boolean;
+    recency: RecencyWindow;
+}
+export declare function slugifyTopic(topic: string): string;
+export declare function defaultOutPath(topic: string, date: string): string;
+export declare function parseResearchArgs(args: string[]): ResearchArgs;
+export interface ResearchPlan {
+    schema_version: "0.1";
+    stage: "plan";
+    /** B5 proof: the id of the run this plan minted. A paper must carry it as
+     *  `research_run:` or `seal`/`validate` refuse it. Null when nothing was minted. */
+    run_id: string | null;
+    topic: string;
+    depth: Depth;
+    recency: RecencyWindow;
+    out_path: string;
+    to_shape: boolean;
+    sources: SourceReport[];
+    zero_config_value: boolean;
+    upsell: string | null;
+    panel: PanelSpec;
+    /** Model execution is supplied by the active agent; no productfoo service is required. */
+    model_panel: ModelPanelPlan;
+    bounds: DepthBounds;
+    estimate: DeepEstimate;
+    safety: SafetyPosture;
+}
+export interface ModelPanelPlan {
+    mode: "multi-model" | "single-model";
+    reason: string;
+    /** The executor step the agent runs when the panel is on; null when single-model. */
+    run_hint: string | null;
+}
+export declare function modelPanelPlan(_depth: Depth, _env: ResearchEnv, _topic: string): ModelPanelPlan;
+export interface BuildPlanOptions extends DetectOptions {
+    date?: string;
+    pricing?: PricingTable;
+    worker?: string;
+    /** The receipt minted for this run. Minting is a side effect, so it belongs to the
+     *  command layer, not to this builder: a plan built directly (tests, callers that
+     *  only want the shape) has no run behind it and says so by carrying null. */
+    runId?: string | null;
+}
+export declare function buildResearchPlan(root: string, args: ResearchArgs, options?: BuildPlanOptions): ResearchPlan;
+export declare function renderResearchPlan(plan: ResearchPlan): string;
+export declare function renderResearchJson(plan: ResearchPlan): string;
+export interface ClaimValidation {
+    ok: boolean;
+    errors: string[];
+}
+export declare function validateClaims(claims: Claim[]): ClaimValidation;
+export declare function assertClaimsLabeled(claims: Claim[]): void;
+export declare function renderPaper(paper: ResearchPaper): string;
+export declare function parsePaper(markdown: string): ParsedPaper;
+export interface RealizedSummary {
+    schema_version: "0.1";
+    stage: "realized";
+    topic: string;
+    depth: Depth;
+    sources: Record<SourceClass, SourceStatus>;
+    claim_count: number;
+    panel: {
+        dissent_count: number;
+    };
+    open_questions: number;
+}
+export declare function summarizePaper(paper: ParsedPaper): RealizedSummary;
+export interface ResearchResult {
+    output: string;
+    exitCode: number;
+}
+export declare function runResearchCommand(root: string, args: string[]): ResearchResult;
+/** Public-query opt-in executes one bounded request. Planning without it stays
+ * local, with an explicit pending requirement that seal cannot skip. */
+export declare function runResearchCommandAsync(root: string, args: string[]): Promise<ResearchResult>;
+export interface GatherArgs {
+    topic: string;
+    recency: RecencyWindow;
+    sources: SocialSource[] | null;
+    limit: number | null;
+    json: boolean;
+}
+export declare function parseGatherArgs(args: string[]): GatherArgs;
+export interface GatherRuntime {
+    fetchImpl?: FetchLike;
+    ytdlp?: YtDlp;
+    now?: Date;
+}
+export declare function runResearchGather(_root: string, args: string[], runtime?: GatherRuntime): Promise<ResearchResult>;