@tiangong-ai/cli 0.0.32 → 0.0.33

package/AGENTS.md

@@ -15,8 +15,8 @@ checkPaths:
   - .docpact/config.yaml
   - docs/agents/**
   - src/**
-lastReviewedAt: 2026-08-10
-lastReviewedCommit: bef62f8d48c42eaff14fa2bd7eba1be83a46a58b
+lastReviewedAt: 2026-08-11
+lastReviewedCommit: 2ce7ad7cd36c1aeba577bc72e4095ed3a81debd6
 ---
 
 # Tiangong AI CLI Contract

package/README.md

@@ -332,8 +332,9 @@ full source. Symlinks, duplicate content, changed hashes, and context above
 `maxInputContextTokens` are rejected.
 
 The workspace stores its current protocol state under `.tiangong-research/`.
-Each project follows five ordered stages: evidence discovery, analysis,
-synthesis, independent review, and mechanical closure. Discover, analyze, and
+Each project follows the evidence-first sequence: broad discovery, strict
+admission, acquisition audit, immutable evidence freeze, analysis, synthesis,
+independent review, and mechanical closure. Discover, acquire, analyze, and
 synthesize run in the current interactive Codex app/session or Claude Code
 session. The CLI never launches a nested producer process. Independent review
 runs through the other configured agent family's CLI, and execution is blocked
@@ -369,6 +370,31 @@ tiangong-ai research project stage submit gpu-resource-impact \
 tiangong-ai research status --workspace /absolute/path/to/workspace --json
 ```
 
+The discover packet derives a bounded multi-channel plan from reviewed evidence
+requirements. Required channels run first; exact repeated requests reuse the
+project cache without another provider call but still consume a bounded context
+view; remaining views are spent only on explicit coverage,
+counterevidence, date, applicability, or full-text gaps. Native Web/Browser
+leads may be registered as supplemental candidates, but they cannot be admitted
+until the same canonical URL/DOI has an immutable broker occurrence. Registered
+inputs are formal candidates under their own content-hash identity.
+The acquire packet audits every provisional source and registers only explicit
+files—never a directory or “latest download.” PDF and Office artifacts are
+structurally verified and content-addressed. A registered binary full file is
+review-bound but is not counted as producer-readable full text unless an
+admitted UTF-8 text/JSON/HTML/CSV/Markdown derivative exists. Such a derivative
+names its registered parent and inherits that parent's canonical source URL;
+it does not invent a second network-download binding, and a conflicting URL is
+rejected.
+
+Successful acquisition freezes an immutable evidence snapshot before analysis.
+The reviewer and mechanical closure bind and recheck the snapshot chain,
+ledger, receipts, selected artifacts, excerpts, analysis, and report. Refresh a
+closed result with `research project addendum SOURCE --to TARGET`; the original
+closure remains unchanged, the child snapshot records a mechanical delta, and
+default status hides the superseded project (`research status --all` shows full
+lineage).
+
 Use `research run --project <id>` for an auditable project-scoped run: only
 that project is checked, scheduled, summarized, and bound to the top-level
 JSON/JSONL `projectId`, so historical blocked siblings do not alter its exit
@@ -405,8 +431,9 @@ the resolved target path and independently hashes the target executable, route
 launcher/wrapper, and internal adapter. A wrapper that performs an unpinned
 PATH lookup is not a reproducible route.
 
-The CLI owns the authoritative JSON Schemas for discovery, analysis,
-synthesis, and review. Inspect one with `research schema show <stage> --json`.
+The CLI owns the authoritative JSON Schemas for discovery, acquisition,
+analysis, synthesis, and review. Inspect one with
+`research schema show <stage> --json`.
 Native producer preparation returns the exact schema and prompt to the current
 host; `stage submit` validates and atomically materializes its JSON. A rejected
 native submission keeps the bound session for an explicit correction and never
@@ -418,12 +445,16 @@ repair with no research tools.
 Total, per-package, output, repair, broker-response bytes, estimated broker
 context tokens, context items, wall-time, output-count, output-size, and attempt
 limits live in `.tiangong-research/config.json`.
-New workspaces reserve 550,000 total tokens by default, including 230,000 for
-discovery; the remaining package defaults are 60,000 for analysis, 70,000 for
-synthesis, and 175,000 for review. Primary output is bounded at 6,000 tokens
-and a separately invoked repair at 4,000. These are admission ceilings rather
-than a target spend and can be lowered only when the resulting pre-call
-reservations still fit.
+New production workspaces use generous but finite runaway ceilings: 20,000,000
+total tokens and package ceilings of 12,000,000 for discovery, 2,000,000 for
+acquisition, 1,500,000 each for analysis and synthesis, and 2,500,000 for
+review. Primary output is bounded at 32,000 tokens and a separately invoked
+repair at 16,000. The production broker hard ceiling is 256 bounded views with
+32,000 context tokens per view; input context is bounded at 128,000 tokens.
+These values are not a target spend. Coverage-derived working plans and early
+stop control ordinary use, while the finite ceilings, three attempts per
+package, and explicit confirmation above the cost threshold stop runaway work.
+Smoke-test workspaces retain their smaller low-cost defaults.
 Before project initialization and every executable package, the control plane
 requires the complete token and conservative price reservation to fit. Native
 producer stages reserve prompt, schema, admitted context, bounded broker
@@ -438,13 +469,16 @@ Independent review uses the pre-call reservation calculator and the reviewer's
 provider-side structured-output/turn controls where available. Review admission
 reserves three maximum-size generated artifacts plus one globally bounded
 evidence-excerpt bundle, and formatting repair remains one separately budgeted,
-tool-free JSON correction. New workspaces also enforce a six-call broker budget
-mechanically; every successful native evidence fetch reports the remaining
-calls and excess calls are rejected before another provider request or evidence
-promotion. Reviewer usage records separate input, cached-input, and output
-tokens; configured pricing fills cost when the provider omits it. Run records
-and JSONL progress preserve sanitized accounting mode, event/item counts,
-provider turns, tool calls, reasoning tokens, and bounded provider errors.
+tool-free JSON correction. Production workspaces enforce a finite 256-view
+broker ceiling mechanically, while each project derives a much smaller working
+budget from its reviewed coverage requirements and stops early when they are
+supportable. Every successful native evidence fetch reports the remaining
+working budget; excess calls are rejected before another provider request or
+evidence promotion. Reviewer usage records separate input, cached-input, and
+output tokens; configured pricing fills cost when the provider omits it. Run
+records and JSONL progress preserve sanitized accounting mode, event/item
+counts, provider turns, tool calls, reasoning tokens, and bounded provider
+errors.
 
 Every evidence source must resolve to an admitted input or a completed broker
 receipt. Successful broker bodies are immutable content-addressed objects under

package/dist/research/orchestration.js

@@ -1,5 +1,5 @@
 import { lstat, readFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { CliError } from "../errors.js";
 import { stringifyJson, write } from "../io.js";
 import { parseStrictArgs, strictBoolean, strictString } from "../strict-args.js";
@@ -10,12 +10,19 @@ import { setCapabilityCredentialFromEnvironment } from "./workspace/credentials.
 import { configureExternalSkillProfile, doctorExternalCapabilities, EXTERNAL_SKILL_CONTEXT_PROFILE, EXTERNAL_SKILL_MEDIA_PROFILE, EXTERNAL_SKILL_PROFILE, importExternalCapability, inspectExternalSkillCatalog, } from "./workspace/external-skills.js";
 import { appendJournalEvent } from "./workspace/journal.js";
 import { fetchNativeCandidateSource } from "./workspace/broker.js";
+import { registerEvidenceArtifact } from "./workspace/artifacts.js";
+import { loadCurrentEvidenceSnapshot } from "./workspace/acquisition.js";
+import { inspectDiscoveryProgress } from "./workspace/discovery-status.js";
+import { recordDiscoveryAssessmentBatch } from "./workspace/discovery.js";
+import { bindEvidenceDownload } from "./workspace/downloads.js";
+import { registerNativeDiscoveryCandidate } from "./workspace/evidence-ledger.js";
+import { recordNativeResearchActivity } from "./workspace/native-activity.js";
 import { readAndVerifyProjectInputPlan } from "./workspace/input-plan.js";
-import { addProjectInput, initializeProject, forkProject, listProjects, loadProject, nextReadyPackage, normalizeEvidenceRequirements, refreshProject, retryProjectPackage, } from "./workspace/projects.js";
+import { addProjectInput, createProjectAddendum, initializeProject, forkProject, listProjects, loadProject, nextReadyPackage, normalizeEvidenceRequirements, refreshProject, retryProjectPackage, setProjectDisposition, } from "./workspace/projects.js";
 import { evaluateProjectPreflight } from "./workspace/preflight.js";
-import { abortNativeResearchStage, prepareNativeResearchStage, runResearchWorkspace, submitNativeResearchStage, } from "./workspace/runtime.js";
+import { abortNativeResearchStage, inspectNativeResearchStage, prepareNativeResearchStage, requestResearchHandoff, resolveResearchHandoff, runResearchWorkspace, submitNativeResearchStage, } from "./workspace/runtime.js";
 import { schemaForStage } from "./workspace/schemas.js";
-import { sha256Text, workspacePaths } from "./workspace/storage.js";
+import { pathExists, sha256Text, workspacePaths } from "./workspace/storage.js";
 import { doctorResearchWorkspace, initializeResearchWorkspace, requireResearchWorkspace, withWorkspaceLock, } from "./workspace/workspace.js";
 const COMMON_OPTIONS = { help: "boolean", json: "boolean" };
 const WORKSPACE_OPTIONS = { ...COMMON_OPTIONS, workspace: "string" };
@@ -56,13 +63,23 @@ export function researchOrchestrationHelp() {
   tiangong-ai research project preflight --question <question> [--requirements <absolute-json>] [--input-plan <absolute-json>] [--workspace <path>] [--json]
   tiangong-ai research project input add <project-id> --path <absolute-file> [--role primary|reference|replication] [--workspace <path>] [--json]
   tiangong-ai research project retry <project-id> [--package <package-id>] [--workspace <path>] [--json]
-  tiangong-ai research project fork <source-project-id> --to <target-project-id> [--resume-through discover|analyze|synthesize] [--workspace <path>] [--json]
-  tiangong-ai research project stage prepare <project-id> --stage discover|analyze|synthesize --host-agent codex|claude [--workspace <path>] [--json]
+  tiangong-ai research project fork <source-project-id> --to <target-project-id> [--resume-through discover|acquire|analyze|synthesize] [--workspace <path>] [--json]
+  tiangong-ai research project addendum <closed-project-id> --to <target-project-id> [--workspace <path>] [--json]
+  tiangong-ai research project archive <project-id> --reason <text> [--workspace <path>] [--json]
+  tiangong-ai research project abandon <project-id> --reason <text> [--workspace <path>] [--json]
+  tiangong-ai research project handoff request <project-id> --record <absolute-json> [--workspace <path>] [--json]
+  tiangong-ai research project handoff resolve <project-id> --note <text> [--workspace <path>] [--json]
+  tiangong-ai research project stage prepare <project-id> --stage discover|acquire|analyze|synthesize --host-agent codex|claude [--workspace <path>] [--json]
   tiangong-ai research project stage submit <project-id> --session <id> --output <absolute-json> [--confirm-model <id>] [--workspace <path>] [--json]
   tiangong-ai research project stage abort <project-id> --session <id> [--workspace <path>] [--json]
   tiangong-ai research project evidence fetch <project-id> --request <absolute-json> [--workspace <path>] [--json]
-  tiangong-ai research schema show <discover|analyze|synthesize|review|doctor> [--json]
-  tiangong-ai research status [--project <project-id>] [--workspace <absolute-path>] [--json]
+  tiangong-ai research project evidence activity record <project-id> --record <absolute-json> [--workspace <path>] [--json]
+  tiangong-ai research project evidence candidate register <project-id> --record <absolute-json> [--workspace <path>] [--json]
+  tiangong-ai research project evidence assessment record <project-id> --record <absolute-json> [--workspace <path>] [--json]
+  tiangong-ai research project evidence download bind <project-id> --candidate <id> --record <absolute-json> [--workspace <path>] [--json]
+  tiangong-ai research project evidence artifact register <project-id> --candidate <id> --path <absolute-file> [--download-binding <id> | --derived-from-artifact <id>] [--media-type <type>] [--source-url <https-url>] [--license <declared-license>] [--license-url <https-url>] [--host-type <type>] [--article-version <version>] [--workspace <path>] [--json]
+  tiangong-ai research schema show <discover|acquire|analyze|synthesize|review|doctor> [--json]
+  tiangong-ai research status [--project <project-id>] [--all] [--workspace <absolute-path>] [--json]
   tiangong-ai research run [--project <project-id>] [--max-parallel <1-8>] [--max-cycles <1-100>] [--dry-run] [--progress-jsonl] [--workspace <absolute-path>] [--json]
 
 ${researchSetupHelp()}
@@ -79,6 +96,7 @@ async function runSchema(argv, io) {
         return writeHelp(io);
     const stage = onePositional(args.positionals, "research schema show");
     if (stage !== "discover" &&
+        stage !== "acquire" &&
         stage !== "analyze" &&
         stage !== "synthesize" &&
         stage !== "review" &&
@@ -281,6 +299,45 @@ async function runProject(argv, io) {
     const [action, ...rest] = argv;
     if (!action || action === "--help" || action === "-h")
         return writeHelp(io);
+    if (action === "handoff") {
+        const [handoffAction, ...handoffRest] = rest;
+        if (handoffAction === "request") {
+            const args = parseStrictArgs(handoffRest, { ...WORKSPACE_OPTIONS, record: "string" }, "research project handoff request");
+            if (strictBoolean(args, "help"))
+                return writeHelp(io);
+            const projectId = onePositional(args.positionals, "research project handoff request");
+            const recordPath = strictString(args, "record");
+            if (!recordPath) {
+                throw new CliError("handoff request requires --record.", {
+                    code: "RESEARCH_PROJECT_HANDOFF_INVALID",
+                    exitCode: 2,
+                });
+            }
+            const root = await workspaceFromArgs(args);
+            const record = await readBoundedJsonRecord(recordPath, "--record", "RESEARCH_PROJECT_HANDOFF_INVALID");
+            const result = await requestResearchHandoff({ root, projectId, value: record });
+            writeJson(io, result, args);
+            return 0;
+        }
+        if (handoffAction === "resolve") {
+            const args = parseStrictArgs(handoffRest, { ...WORKSPACE_OPTIONS, note: "string" }, "research project handoff resolve");
+            if (strictBoolean(args, "help"))
+                return writeHelp(io);
+            const projectId = onePositional(args.positionals, "research project handoff resolve");
+            const note = strictString(args, "note");
+            if (!note) {
+                throw new CliError("handoff resolve requires --note.", {
+                    code: "RESEARCH_PROJECT_HANDOFF_INVALID",
+                    exitCode: 2,
+                });
+            }
+            const root = await workspaceFromArgs(args);
+            const result = await resolveResearchHandoff({ root, projectId, note });
+            writeJson(io, result, args);
+            return 0;
+        }
+        throw unknownAction("research project handoff", handoffAction ?? "");
+    }
     if (action === "stage") {
         const [stageAction, ...stageRest] = rest;
         if (stageAction === "prepare") {
@@ -345,6 +402,156 @@ async function runProject(argv, io) {
     }
     if (action === "evidence") {
         const [evidenceAction, ...evidenceRest] = rest;
+        if (evidenceAction === "activity") {
+            const [activityAction, ...activityRest] = evidenceRest;
+            if (activityAction !== "record") {
+                throw unknownAction("research project evidence activity", activityAction ?? "");
+            }
+            const args = parseStrictArgs(activityRest, { ...WORKSPACE_OPTIONS, record: "string" }, "research project evidence activity record");
+            if (strictBoolean(args, "help"))
+                return writeHelp(io);
+            const projectId = onePositional(args.positionals, "research project evidence activity record");
+            const recordPath = strictString(args, "record");
+            if (!recordPath) {
+                throw new CliError("activity record requires --record.", {
+                    code: "RESEARCH_NATIVE_ACTIVITY_INVALID",
+                    exitCode: 2,
+                });
+            }
+            const root = await workspaceFromArgs(args);
+            const record = await readBoundedJsonRecord(recordPath, "--record", "RESEARCH_NATIVE_ACTIVITY_INVALID");
+            const result = await withWorkspaceLock(root, "research.native-activity.record", () => recordNativeResearchActivity({ root, projectId, value: record }));
+            writeJson(io, result, args);
+            return 0;
+        }
+        if (evidenceAction === "candidate") {
+            const [candidateAction, ...candidateRest] = evidenceRest;
+            if (candidateAction !== "register") {
+                throw unknownAction("research project evidence candidate", candidateAction ?? "");
+            }
+            const args = parseStrictArgs(candidateRest, { ...WORKSPACE_OPTIONS, record: "string" }, "research project evidence candidate register");
+            if (strictBoolean(args, "help"))
+                return writeHelp(io);
+            const projectId = onePositional(args.positionals, "research project evidence candidate register");
+            const recordPath = strictString(args, "record");
+            if (!recordPath) {
+                throw new CliError("candidate register requires --record.", {
+                    code: "RESEARCH_NATIVE_CANDIDATE_INVALID",
+                    exitCode: 2,
+                });
+            }
+            const root = await workspaceFromArgs(args);
+            const record = await readBoundedJsonRecord(recordPath, "--record", "RESEARCH_NATIVE_CANDIDATE_INVALID");
+            const result = await withWorkspaceLock(root, "research.native-candidate.register", () => registerNativeDiscoveryCandidate({ root, projectId, value: record }));
+            writeJson(io, result, args);
+            return 0;
+        }
+        if (evidenceAction === "assessment") {
+            const [assessmentAction, ...assessmentRest] = evidenceRest;
+            if (assessmentAction !== "record") {
+                throw unknownAction("research project evidence assessment", assessmentAction ?? "");
+            }
+            const args = parseStrictArgs(assessmentRest, { ...WORKSPACE_OPTIONS, record: "string" }, "research project evidence assessment record");
+            if (strictBoolean(args, "help"))
+                return writeHelp(io);
+            const projectId = onePositional(args.positionals, "research project evidence assessment record");
+            const recordPath = strictString(args, "record");
+            if (!recordPath) {
+                throw new CliError("assessment record requires --record.", {
+                    code: "RESEARCH_DISCOVERY_ASSESSMENT_INVALID",
+                    exitCode: 2,
+                });
+            }
+            const root = await workspaceFromArgs(args);
+            const record = await readBoundedJsonRecord(recordPath, "--record", "RESEARCH_DISCOVERY_ASSESSMENT_INVALID");
+            const result = await withWorkspaceLock(root, "research.discovery-assessment.record", () => recordDiscoveryAssessmentBatch({ root, projectId, value: record }));
+            writeJson(io, result, args);
+            return 0;
+        }
+        if (evidenceAction === "download") {
+            const [downloadAction, ...downloadRest] = evidenceRest;
+            if (downloadAction !== "bind") {
+                throw unknownAction("research project evidence download", downloadAction ?? "");
+            }
+            const args = parseStrictArgs(downloadRest, { ...WORKSPACE_OPTIONS, candidate: "string", record: "string" }, "research project evidence download bind");
+            if (strictBoolean(args, "help"))
+                return writeHelp(io);
+            const projectId = onePositional(args.positionals, "research project evidence download bind");
+            const candidateId = strictString(args, "candidate");
+            const recordPath = strictString(args, "record");
+            if (!candidateId || !recordPath) {
+                throw new CliError("download bind requires --candidate and --record.", {
+                    code: "RESEARCH_DOWNLOAD_BINDING_INVALID",
+                    exitCode: 2,
+                });
+            }
+            const root = await workspaceFromArgs(args);
+            const record = await readBoundedJsonRecord(recordPath, "--record", "RESEARCH_DOWNLOAD_BINDING_INVALID");
+            const result = await withWorkspaceLock(root, "research.download.bind", () => bindEvidenceDownload({ root, projectId, candidateId, value: record }));
+            writeJson(io, result, args);
+            return result.status === "completed" ? 0 : 3;
+        }
+        if (evidenceAction === "artifact") {
+            const [artifactAction, ...artifactRest] = evidenceRest;
+            if (artifactAction !== "register") {
+                throw unknownAction("research project evidence artifact", artifactAction ?? "");
+            }
+            const args = parseStrictArgs(artifactRest, {
+                ...WORKSPACE_OPTIONS,
+                candidate: "string",
+                path: "string",
+                "media-type": "string",
+                "source-url": "string",
+                license: "string",
+                "license-url": "string",
+                "host-type": "string",
+                "article-version": "string",
+                "download-binding": "string",
+                "derived-from-artifact": "string",
+            }, "research project evidence artifact register");
+            if (strictBoolean(args, "help"))
+                return writeHelp(io);
+            const projectId = onePositional(args.positionals, "research project evidence artifact register");
+            const candidateId = strictString(args, "candidate");
+            const path = strictString(args, "path");
+            if (!candidateId || !path) {
+                throw new CliError("artifact register requires --candidate and --path.", {
+                    code: "RESEARCH_ARTIFACT_PATH_INVALID",
+                    exitCode: 2,
+                });
+            }
+            const root = await workspaceFromArgs(args);
+            const result = await withWorkspaceLock(root, "research.artifact.register", () => registerEvidenceArtifact({
+                root,
+                projectId,
+                candidateId,
+                path,
+                ...(strictString(args, "media-type")
+                    ? { mediaType: strictString(args, "media-type") }
+                    : {}),
+                ...(strictString(args, "source-url")
+                    ? { sourceUrl: strictString(args, "source-url") }
+                    : {}),
+                ...(strictString(args, "license") ? { license: strictString(args, "license") } : {}),
+                ...(strictString(args, "license-url")
+                    ? { licenseUrl: strictString(args, "license-url") }
+                    : {}),
+                ...(strictString(args, "host-type")
+                    ? { hostType: strictString(args, "host-type") }
+                    : {}),
+                ...(strictString(args, "article-version")
+                    ? { articleVersion: strictString(args, "article-version") }
+                    : {}),
+                ...(strictString(args, "download-binding")
+                    ? { downloadBindingId: strictString(args, "download-binding") }
+                    : {}),
+                ...(strictString(args, "derived-from-artifact")
+                    ? { derivedFromArtifactId: strictString(args, "derived-from-artifact") }
+                    : {}),
+            }));
+            writeJson(io, result, args);
+            return 0;
+        }
         if (evidenceAction !== "fetch") {
             throw unknownAction("research project evidence", evidenceAction ?? "");
         }
@@ -466,33 +673,180 @@ async function runProject(argv, io) {
         writeJson(io, project, args);
         return 0;
     }
+    if (action === "addendum") {
+        const args = parseStrictArgs(rest, { ...WORKSPACE_OPTIONS, to: "string" }, "research project addendum");
+        if (strictBoolean(args, "help"))
+            return writeHelp(io);
+        const sourceProjectId = onePositional(args.positionals, "research project addendum");
+        const targetProjectId = strictString(args, "to");
+        if (!targetProjectId) {
+            throw new CliError("research project addendum requires --to.", {
+                code: "RESEARCH_PROJECT_ADDENDUM_INVALID",
+                exitCode: 2,
+            });
+        }
+        const root = await workspaceFromArgs(args);
+        const project = await createProjectAddendum(root, sourceProjectId, targetProjectId);
+        writeJson(io, project, args);
+        return 0;
+    }
+    if (action === "archive" || action === "abandon") {
+        const args = parseStrictArgs(rest, { ...WORKSPACE_OPTIONS, reason: "string" }, `research project ${action}`);
+        if (strictBoolean(args, "help"))
+            return writeHelp(io);
+        const projectId = onePositional(args.positionals, `research project ${action}`);
+        const reason = strictString(args, "reason");
+        if (!reason) {
+            throw new CliError(`research project ${action} requires --reason.`, {
+                code: "RESEARCH_PROJECT_DISPOSITION_INVALID",
+                exitCode: 2,
+            });
+        }
+        const root = await workspaceFromArgs(args);
+        const project = await setProjectDisposition(root, projectId, action === "archive" ? "archived" : "abandoned", reason);
+        writeJson(io, project, args);
+        return 0;
+    }
     throw unknownAction("research project", action);
 }
 async function runStatus(argv, io) {
-    const args = parseStrictArgs(argv, { ...WORKSPACE_OPTIONS, project: "string" }, "research status");
+    const args = parseStrictArgs(argv, { ...WORKSPACE_OPTIONS, project: "string", all: "boolean" }, "research status");
     if (strictBoolean(args, "help"))
         return writeHelp(io);
     rejectPositionals(args.positionals, "research status");
     const root = await workspaceFromArgs(args);
     const selectedProject = strictString(args, "project");
-    const projects = selectedProject
-        ? [await loadProject(root, selectedProject)]
-        : await listProjects(root);
+    const workspaceProjects = await listProjects(root);
+    const allProjects = selectedProject
+        ? [
+            workspaceProjects.find((project) => project.id === selectedProject) ??
+                (await loadProject(root, selectedProject)),
+        ]
+        : workspaceProjects;
+    const projects = selectedProject || strictBoolean(args, "all")
+        ? allProjects
+        : allProjects.filter((project) => project.lineage.supersededBy === null &&
+            project.status !== "archived" &&
+            project.status !== "abandoned");
     const result = {
         workspace: root,
-        projects: projects.map((project) => ({
-            id: project.id,
-            question: project.question,
-            status: refreshProject(project).status,
-            readyPackage: nextReadyPackage(project)?.id ?? null,
-            usage: project.usage,
-            inputs: project.inputs,
-            packages: project.packages,
+        hiddenSupersededProjects: selectedProject || strictBoolean(args, "all")
+            ? 0
+            : workspaceProjects.filter((project) => project.lineage.supersededBy !== null).length,
+        hiddenArchivedProjects: selectedProject || strictBoolean(args, "all")
+            ? 0
+            : workspaceProjects.filter((project) => project.status === "archived").length,
+        hiddenAbandonedProjects: selectedProject || strictBoolean(args, "all")
+            ? 0
+            : workspaceProjects.filter((project) => project.status === "abandoned").length,
+        projects: await Promise.all(projects.map(async (project) => {
+            const current = refreshProject(project);
+            const nativeStage = await inspectNativeResearchStage(root, current);
+            const snapshot = await inspectSnapshotForStatus(root, current.id);
+            const readyPackage = nextReadyPackage(current)?.id ?? null;
+            return {
+                id: current.id,
+                question: current.question,
+                status: current.status,
+                authority: projectAuthority(current, workspaceProjects),
+                lineage: current.lineage,
+                handoff: current.handoff,
+                evidenceState: current.evidenceState,
+                snapshot,
+                nativeStage,
+                readyPackage,
+                recommendedAction: projectRecommendedAction(root, current, readyPackage, nativeStage),
+                usage: current.usage,
+                inputs: current.inputs,
+                packages: current.packages,
+                discovery: await inspectDiscoveryProgress(root, current),
+            };
         })),
     };
     writeJson(io, result, args);
     return 0;
 }
+function projectAuthority(project, projects) {
+    const byId = new Map(projects.map((candidate) => [candidate.id, candidate]));
+    const visited = new Set([project.id]);
+    let current = project;
+    while (current.lineage.supersededBy) {
+        if (visited.has(current.lineage.supersededBy))
+            break;
+        visited.add(current.lineage.supersededBy);
+        const next = byId.get(current.lineage.supersededBy);
+        if (!next)
+            return { state: "superseded", projectId: current.lineage.supersededBy };
+        current = next;
+    }
+    if (project.status === "archived")
+        return { state: "archived", projectId: current.id };
+    if (project.status === "abandoned")
+        return { state: "abandoned", projectId: current.id };
+    return {
+        state: project.id === current.id ? "authoritative" : "superseded",
+        projectId: current.id,
+    };
+}
+async function inspectSnapshotForStatus(root, projectId) {
+    const currentPath = join(workspacePaths(root).projects, projectId, "outputs", "evidence-snapshot.json");
+    if (!(await pathExists(currentPath)))
+        return { status: "absent" };
+    try {
+        const snapshot = await loadCurrentEvidenceSnapshot(root, projectId);
+        return {
+            status: "verified",
+            snapshotId: snapshot.snapshotId,
+            snapshotSha256: snapshot.snapshotSha256,
+            parentSnapshotId: snapshot.parentSnapshotId,
+            sourceCount: snapshot.sources.length,
+            artifactCount: snapshot.artifacts.length,
+            delta: snapshot.delta,
+        };
+    }
+    catch (error) {
+        const code = error instanceof CliError ? error.code : "RESEARCH_EVIDENCE_SNAPSHOT_INVALID";
+        return {
+            status: "invalid",
+            code,
+        };
+    }
+}
+function projectRecommendedAction(root, project, readyPackage, nativeStage) {
+    if (project.lineage.supersededBy) {
+        return `Continue with superseding project ${project.lineage.supersededBy}.`;
+    }
+    if (project.status === "archived" || project.status === "abandoned") {
+        return `Project is ${project.status}; inspect with research status --all and continue only from an authoritative project.`;
+    }
+    if (project.handoff.state === "user-action-required") {
+        return `User action required: ${project.handoff.summary ?? "review the requested action"} Resolve only after completion: tiangong-ai research project handoff resolve ${project.id} --note <resolution-note> --workspace ${root}`;
+    }
+    if (project.handoff.state === "external-response-required") {
+        return `Waiting for an external response: ${project.handoff.summary ?? "external evidence is pending"} Do not continue substitute searching; resolve after the response is registered.`;
+    }
+    if (nativeStage.status === "stale" || nativeStage.status === "invalid") {
+        return nativeStage.recommendedAction ?? "Recover the stale native session explicitly.";
+    }
+    if (nativeStage.status === "active") {
+        return nativeStage.recommendedAction ?? "Resume the active native stage.";
+    }
+    if (project.status === "complete") {
+        return `Create an immutable evidence addendum only when new evidence exists: tiangong-ai research project addendum ${project.id} --to <new-project-id> --workspace ${root}`;
+    }
+    if (project.status === "blocked") {
+        const failed = project.packages.find((workPackage) => workPackage.status === "failed");
+        return failed
+            ? `Review ${failed.lastFailureKind ?? "deterministic"} failure for ${failed.id}, then run the explicit project retry command if corrected.`
+            : "Inspect the blocking package and use explicit retry or fork recovery.";
+    }
+    if (readyPackage && ["discover", "acquire", "analyze", "synthesize"].includes(readyPackage)) {
+        return `Prepare native ${readyPackage}: tiangong-ai research project stage prepare ${project.id} --stage ${readyPackage} --host-agent <codex|claude> --workspace ${root}`;
+    }
+    return readyPackage === "review"
+        ? `Run the independent reviewer package: tiangong-ai research run --project ${project.id} --workspace ${root}`
+        : "Continue the next ready package.";
+}
 async function runWorkspaceExecution(argv, io) {
     const args = parseStrictArgs(argv, {
         ...WORKSPACE_OPTIONS,
@@ -582,7 +936,7 @@ function researchMode(value) {
 function resumeStage(value) {
     if (!value)
         return undefined;
-    if (value === "discover" || value === "analyze" || value === "synthesize")
+    if (value === "discover" || value === "acquire" || value === "analyze" || value === "synthesize")
         return value;
     throw new CliError(`Unsupported --resume-through stage: ${value}`, {
         code: "RESEARCH_PROJECT_FORK_INVALID",
@@ -590,9 +944,9 @@ function resumeStage(value) {
     });
 }
 function nativeProducerStage(value) {
-    if (value === "discover" || value === "analyze" || value === "synthesize")
+    if (value === "discover" || value === "acquire" || value === "analyze" || value === "synthesize")
         return value;
-    throw new CliError("--stage must be discover, analyze, or synthesize.", {
+    throw new CliError("--stage must be discover, acquire, analyze, or synthesize.", {
         code: "RESEARCH_NATIVE_STAGE_INVALID",
         exitCode: 2,
     });
@@ -606,17 +960,20 @@ function nativeHostAgent(value) {
     });
 }
 async function readNativeEvidenceRequest(path) {
+    return readBoundedJsonRecord(path, "--request", "RESEARCH_BROKER_REQUEST_INVALID");
+}
+async function readBoundedJsonRecord(path, label, code) {
     if (!isAbsolute(path)) {
-        throw new CliError("--request must be an absolute JSON file path.", {
-            code: "RESEARCH_BROKER_REQUEST_INVALID",
+        throw new CliError(`${label} must be an absolute JSON file path.`, {
+            code,
             exitCode: 2,
         });
     }
     const selected = resolve(path);
     const info = await lstat(selected).catch(() => undefined);
     if (!info?.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) {
-        throw new CliError("--request must be a bounded regular non-symlink JSON file.", {
-            code: "RESEARCH_BROKER_REQUEST_INVALID",
+        throw new CliError(`${label} must be a bounded regular non-symlink JSON file.`, {
+            code,
             exitCode: 2,
         });
     }
@@ -625,14 +982,14 @@ async function readNativeEvidenceRequest(path) {
         value = JSON.parse(await readFile(selected, "utf8"));
     }
     catch {
-        throw new CliError("--request contains invalid JSON.", {
-            code: "RESEARCH_BROKER_REQUEST_INVALID",
+        throw new CliError(`${label} contains invalid JSON.`, {
+            code,
             exitCode: 2,
         });
     }
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new CliError("--request must contain one JSON object.", {
-            code: "RESEARCH_BROKER_REQUEST_INVALID",
+        throw new CliError(`${label} must contain one JSON object.`, {
+            code,
             exitCode: 2,
         });
     }