@longtable/cli 0.1.24 → 0.1.26

package/README.md

@@ -20,8 +20,7 @@ npm install -g @longtable/cli
 ```
 
 The npm install only installs the CLI. It does not write Codex skills, MCP
-config, hooks, tmux state, or provider runtime files without explicit setup
-approval.
+config, hooks, or provider runtime files without explicit setup approval.
 
 ## Primary Flow
 
@@ -91,8 +90,7 @@ longtable roles
 longtable ask --cwd "<project-path>" --prompt "..."
 longtable panel --prompt "..."
 longtable sentinel --prompt "Should I define a new measurement construct?"
-longtable hud --watch
-longtable team --tmux --prompt "Review this measurement plan."
+longtable team --prompt "Review this measurement plan." --role editor,measurement_auditor --json
 longtable team --debate --prompt "Review this measurement plan." --role editor,measurement_auditor --json
 longtable codex install-skills
 longtable claude install-skills
@@ -110,6 +108,16 @@ longtable ask --prompt "lt panel: show the disagreement before I commit" --json
 
 Natural language should be the default.
 
+Codex UI Researcher Checkpoints are a core LongTable feature when enabled:
+
+```bash
+longtable setup --provider codex --surfaces skills_mcp --checkpoint-ui strong
+```
+
+That setup writes the MCP configuration and Codex elicitation approval needed
+for form-style checkpoint prompts. Without it, LongTable keeps the same
+`QuestionRecord` pending and falls back to numbered text.
+
 Explicit short forms are available when needed:
 
 ```text
@@ -151,10 +159,6 @@ Inside a LongTable project workspace, panel planning also appends an
 `InvocationRecord` to `.longtable/state.json`, creates a pending follow-up
 `QuestionRecord`, and refreshes `CURRENT.md`.
 
-```bash
-longtable decide --answer evidence --rationale "Need citation support before continuing."
-```
-
 Default panel roles include:
 
 - `reviewer`
@@ -164,26 +168,25 @@ Default panel roles include:
 
 Use `--role` to constrain the panel when the research problem is already clear.
 
-## Sentinel, HUD, And Tmux Team
+## Sentinel And Agent Team
 
 `longtable sentinel` is an explicit gap/tacit check for prompts that may contain
 measurement, theory, method, evidence, authorship, or tacit-assumption risks.
 Use `--record` inside a LongTable workspace to store the finding as an
 unconfirmed inferred hypothesis.
 
-`longtable hud --watch` renders a compact view of the current project goal,
-blocker, pending checkpoints, recent decisions, and invocation counts.
-`longtable hud --tmux` opens that view in a tmux pane.
-
-`longtable team --tmux` opens role-specific panes for research discussion and
-writes logs under `.longtable/team/<id>/`. This is panel discussion, not merely
-parallel execution: role panes are prompted to state claims, objections, open
-questions, and likely disagreement.
+`longtable team` creates a file-backed agent-team review under
+`.longtable/team/<id>/`: independent review, cross-review, and
+synthesis/checkpoint. Use it when roles should inspect each other's concerns
+before LongTable proposes a researcher decision.
 
 `longtable team --debate` creates a fixed five-round debate record under
 `.longtable/team/<id>/`: independent review, cross-review, rebuttal,
-convergence, and synthesis/checkpoint. Tmux can show live role panes, but the
-file-backed artifact directory is the source of truth.
+convergence, and synthesis/checkpoint. The file-backed artifact directory is
+the source of truth.
+
+See `docs/AGENT-TEAM-README.md` in the repository for a user-facing guide to
+panel, team, and debate surfaces.
 
 ## Evidence And Search Direction
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { execFileSync, execSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output, cwd, exit } from "node:process";
@@ -15,8 +15,8 @@ import { installCodexPromptAliases, listInstalledCodexPromptAliases, removeCodex
 import { buildPersonaGuidance, parseInvocationDirective } from "./persona-router.js";
 import { PERSONA_DEFINITIONS, listRoleDefinitions } from "./personas.js";
 import { buildPanelFallback, renderPanelSummary } from "./panel.js";
-import { appendInvocationRecordToWorkspace, assertWorkspaceNotBlocked, answerWorkspaceQuestion, createWorkspaceClarificationCard, createWorkspaceQuestion, createOrUpdateProjectWorkspace, inspectProjectWorkspace, loadWorkspaceState, loadProjectContextFromDirectory, renderProjectWorkspaceSummary, syncCurrentWorkspaceView } from "./project-session.js";
-import { buildTeamDebate, renderTeamDebateSummary } from "./debate.js";
+import { appendInvocationRecordToWorkspace, assertWorkspaceNotBlocked, answerWorkspaceQuestion, createWorkspaceFollowUpQuestions, createWorkspaceQuestion, createOrUpdateProjectWorkspace, inspectProjectWorkspace, loadWorkspaceState, loadProjectContextFromDirectory, renderProjectWorkspaceSummary, syncCurrentWorkspaceView } from "./project-session.js";
+import { buildTeamDebate, buildTeamReview, renderTeamDebateSummary } from "./debate.js";
 const VALID_MODES = new Set([
     "explore",
     "review",
@@ -42,7 +42,7 @@ const ANSI = {
     green: "\u001B[32m"
 };
 const LONGTABLE_MCP_SERVER_NAME = "longtable-state";
-const LONGTABLE_MCP_PACKAGE_VERSION = "0.1.24";
+const LONGTABLE_MCP_PACKAGE_VERSION = "0.1.26";
 const LONGTABLE_MCP_MARKER_START = "# LongTable state MCP START";
 const LONGTABLE_MCP_MARKER_END = "# LongTable state MCP END";
 function style(text, prefix) {
@@ -89,7 +89,7 @@ function usage() {
         "  longtable install [--json] [--path <file>] [--runtime-path <file>]",
         "  longtable mcp install [--provider codex|claude|all] [--write] [--checkpoint-ui off|interactive|strong] [--json] [--codex-config <path>] [--claude-settings <path>] [--package <spec>]",
         "  longtable sentinel --prompt <text> [--cwd <path>] [--json] [--record]",
-        "  longtable team --prompt <text> [--role <role[,role]>] [--tmux] [--debate] [--rounds 5] [--cwd <path>] [--json]",
+        "  longtable team --prompt <text> [--role <role[,role]>] [--debate] [--rounds 3|5] [--cwd <path>] [--json]",
         "  longtable ask [--prompt <text>] [--print] [--json] [--setup <path>] [--cwd <path>]",
         "  longtable clarify --prompt <task-context> [--provider codex|claude] [--required|--advisory] [--print] [--cwd <path>] [--json] [--force]",
         "  longtable question --prompt <decision-context> [--title <text>] [--text <question>] [--provider codex|claude] [--required|--advisory] [--print] [--cwd <path>] [--json]",
@@ -622,12 +622,12 @@ function buildPermissionSetupChoices() {
             {
                 id: "strong",
                 label: "Strong Researcher Checkpoint UI",
-                description: "Why: uses Codex MCP elicitation for high-responsibility research decisions. What you get: clickable checkpoints with other/rationale. Tradeoff: requires Codex MCP elicitation approval."
+                description: "Why: makes Codex UI checkpoints the default for high-responsibility research decisions. What you get: MCP form checkpoints with a single decision field. Tradeoff: requires Codex MCP elicitation approval."
             },
             {
                 id: "interactive",
                 label: "Interactive checkpoint UI",
-                description: "Why: keeps UI prompts available for required checkpoints. What you get: MCP form checkpoints when supported. Tradeoff: requires Codex MCP elicitation approval."
+                description: "Why: keeps Codex UI prompts available for required checkpoints. What you get: MCP form checkpoints when supported. Tradeoff: requires Codex MCP elicitation approval."
             },
             {
                 id: "off",
@@ -768,7 +768,6 @@ async function runSetup(args) {
             interventionPosture: effectiveIntervention,
             checkpointUiMode: checkpointUi,
             workspaceCreationPreference: workspacePreference,
-            tmuxMode: "standard",
             teamMode: "panel"
         };
         if (surfaces === "skills_mcp_sentinel") {
@@ -1769,6 +1768,38 @@ function inferModeFromPrompt(prompt) {
     }
     return "explore";
 }
+function inferCollaborationRoute(prompt) {
+    const normalized = prompt.toLowerCase();
+    const explicitDebate = /\bdebate\b|\bdebated\b|\brebuttal\b|\bconvergence\b|\bargue both sides\b/i.test(prompt) ||
+        /토론|논쟁|반박|재반박|수렴/.test(prompt);
+    if (explicitDebate) {
+        return "debate";
+    }
+    const explicitTeam = /\bagent team\b|\bresearch team\b|\bteam review\b|\bteam-style\b|\buse a team\b/i.test(prompt) ||
+        /에이전트\s*팀|연구\s*팀|팀\s*(리뷰|검토)|팀으로/.test(prompt);
+    if (explicitTeam) {
+        return "team";
+    }
+    const panelCue = /\bpanel\b|\bmulti[- ]?role\b|\bmultiple perspectives\b|\brole disagreement\b|\bdisagreement\b|\bconflict\b/i.test(prompt) ||
+        /패널|여러\s*관점|복수\s*관점|역할.*불일치|불일치|충돌/.test(prompt);
+    const multiPerspectiveCue = panelCue ||
+        /\bperspectives?\b|\broles?\b|\breviewer and editor\b|\beditor and reviewer\b|\bmethods and measurement\b/i.test(prompt) ||
+        /관점|역할|리뷰어.*에디터|에디터.*리뷰어|방법.*측정|측정.*방법/.test(prompt);
+    if (!multiPerspectiveCue) {
+        return null;
+    }
+    const trigger = classifyCheckpointTrigger(prompt, {});
+    const highStakes = trigger.signal.artifactStakes === "external_submission" ||
+        trigger.signal.artifactStakes === "study_protocol" ||
+        trigger.requiresQuestionBeforeClosure;
+    if (panelCue && trigger.signal.artifactStakes === "external_submission") {
+        return "debate";
+    }
+    if (highStakes) {
+        return "team";
+    }
+    return "panel";
+}
 function parsePanelVisibility(value) {
     if (value === "synthesis_only" ||
         value === "show_on_conflict" ||
@@ -1820,6 +1851,9 @@ async function runModeCommand(mode, args) {
     }
     const setup = await loadOptionalSetup(typeof args.setup === "string" ? args.setup : undefined);
     const projectContext = await loadProjectContextFromDirectory(workingDirectory);
+    if (projectContext) {
+        await assertWorkspaceNotBlocked(projectContext);
+    }
     const projectAware = await buildProjectAwarePrompt(prompt, workingDirectory);
     const panelPreference = setup?.profileSeed.panelPreference;
     const panelRequested = args.panel === true ||
@@ -2019,9 +2053,9 @@ function questionRecordToChoices(record) {
             : [])
     ];
 }
-function renderClarificationCard(questions) {
+function renderFollowUpQuestions(questions) {
     if (questions.length === 0) {
-        return "No new clarification questions are pending for this prompt.";
+        return "No new follow-up questions are pending for this prompt.";
     }
     const width = 44;
     const boxLine = (text = "") => `│ ${text.padEnd(width, " ")} │`;
@@ -2072,13 +2106,13 @@ function renderClarificationCard(questions) {
     lines.push("Answer in a terminal with `longtable clarify --prompt ...`, or record choices with `longtable decide --question <id> --answer <value>`.");
     return lines.join("\n");
 }
-async function answerClarificationCardInTerminal(context, questions, provider) {
+async function answerFollowUpQuestionsInTerminal(context, questions, provider) {
     if (questions.length === 0) {
         return;
     }
     const rl = createInterface({ input, output });
     try {
-        console.log(renderBrandBanner("LongTable", "Clarification Card"));
+        console.log(renderBrandBanner("LongTable", "Follow-up Questions"));
         console.log("");
         for (let index = 0; index < questions.length; index += 1) {
             const question = questions[index];
@@ -2109,7 +2143,7 @@ async function runClarify(args) {
     }
     const provider = args.provider === "claude" ? "claude" : args.provider === "codex" ? "codex" : undefined;
     const required = args.required === true ? true : args.advisory === true ? false : undefined;
-    const result = await createWorkspaceClarificationCard({
+    const result = await createWorkspaceFollowUpQuestions({
         context,
         prompt,
         provider,
@@ -2129,17 +2163,17 @@ async function runClarify(args) {
         return;
     }
     if (args.print === true || !isInteractiveTerminal()) {
-        console.log(renderClarificationCard(result.questions));
+        console.log(renderFollowUpQuestions(result.questions));
         return;
     }
-    await answerClarificationCardInTerminal(context, result.questions, provider);
+    await answerFollowUpQuestionsInTerminal(context, result.questions, provider);
     console.log("");
-    console.log("LongTable clarification decisions recorded");
+    console.log("LongTable follow-up decisions recorded");
     console.log(`- answered: ${result.questions.length}`);
     console.log(`- state: ${context.stateFilePath}`);
     console.log(`- current: ${context.currentFilePath}`);
 }
-async function runAutomaticClarificationIfNeeded(prompt, args) {
+async function runAutomaticFollowUpIfNeeded(prompt, args) {
     if (args["no-clarify"] === true || args.print === true || args.json === true) {
         return false;
     }
@@ -2149,7 +2183,7 @@ async function runAutomaticClarificationIfNeeded(prompt, args) {
         return false;
     }
     const provider = args.provider === "claude" ? "claude" : args.provider === "codex" ? "codex" : undefined;
-    const result = await createWorkspaceClarificationCard({
+    const result = await createWorkspaceFollowUpQuestions({
         context,
         prompt,
         provider,
@@ -2159,17 +2193,22 @@ async function runAutomaticClarificationIfNeeded(prompt, args) {
         return false;
     }
     if (!isInteractiveTerminal()) {
-        console.log(renderClarificationCard(result.questions));
+        console.log(renderFollowUpQuestions(result.questions));
         return true;
     }
-    await answerClarificationCardInTerminal(context, result.questions, provider);
+    await answerFollowUpQuestionsInTerminal(context, result.questions, provider);
     return false;
 }
 async function runAsk(args) {
+    const workingDirectory = typeof args.cwd === "string" ? args.cwd : cwd();
     const prompt = await resolvePrompt(typeof args.prompt === "string" ? args.prompt : undefined);
     if (!prompt) {
         throw new Error("A prompt is required.");
     }
+    const projectContext = await loadProjectContextFromDirectory(workingDirectory);
+    if (projectContext) {
+        await assertWorkspaceNotBlocked(projectContext);
+    }
     const directive = parseInvocationDirective(prompt);
     const effectivePrompt = directive.cleanedPrompt;
     const inferred = directive.mode ?? inferModeFromPrompt(effectivePrompt);
@@ -2178,7 +2217,7 @@ async function runAsk(args) {
         return;
     }
     const mode = inferred === "panel" ? "review" : inferred;
-    if (await runAutomaticClarificationIfNeeded(effectivePrompt, args)) {
+    if (await runAutomaticFollowUpIfNeeded(effectivePrompt, args)) {
         return;
     }
     const delegatedArgs = {
@@ -2188,7 +2227,18 @@ async function runAsk(args) {
     if (directive.roles.length > 0 && typeof delegatedArgs.role !== "string") {
         delegatedArgs.role = directive.roles.join(",");
     }
-    if (inferred === "panel" || directive.panel || delegatedArgs.panel === true) {
+    const collaborationRoute = directive.collaboration ??
+        (directive.panel || delegatedArgs.panel === true
+            ? "panel"
+            : inferCollaborationRoute(effectivePrompt) ?? (inferred === "panel" ? "panel" : null));
+    if (collaborationRoute === "team" || collaborationRoute === "debate") {
+        await runTeam({
+            ...delegatedArgs,
+            debate: collaborationRoute === "debate"
+        });
+        return;
+    }
+    if (collaborationRoute === "panel") {
         await runPanelCommand({
             ...delegatedArgs,
             visibility: "always_visible"
@@ -2200,9 +2250,6 @@ async function runAsk(args) {
 function localId(prefix) {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
-function shellEscape(value) {
-    return `'${value.replaceAll("'", "'\\''")}'`;
-}
 async function writeJsonFile(path, value) {
     await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
@@ -2305,9 +2352,13 @@ async function runTeam(args) {
     if (!prompt) {
         throw new Error("A prompt is required.");
     }
-    const rounds = typeof args.rounds === "string" ? Number(args.rounds) : 5;
-    if (!Number.isInteger(rounds) || rounds !== 5) {
-        throw new Error("LongTable team debate v1 supports `--rounds 5` only.");
+    const isDebate = args.debate === true;
+    const expectedRounds = isDebate ? 5 : 3;
+    const rounds = typeof args.rounds === "string" ? Number(args.rounds) : expectedRounds;
+    if (!Number.isInteger(rounds) || rounds !== expectedRounds) {
+        throw new Error(isDebate
+            ? "LongTable team debate v1 supports `--rounds 5` only."
+            : "LongTable team v1 supports `--rounds 3` cross-review only.");
     }
     const setup = await loadOptionalSetup(typeof args.setup === "string" ? args.setup : undefined);
     const projectContext = await loadProjectContextFromDirectory(workingDirectory);
@@ -2315,16 +2366,9 @@ async function runTeam(args) {
         await assertWorkspaceNotBlocked(projectContext);
     }
     const projectAware = await buildProjectAwarePrompt(prompt, workingDirectory);
-    const fallback = buildPanelFallback({
-        prompt,
-        mode: "review",
-        roleFlag: typeof args.role === "string" ? args.role : undefined,
-        provider: setup?.providerSelection.provider,
-        visibility: "always_visible"
-    });
     const teamId = localId("team");
     const teamDir = join(workingDirectory, ".longtable", "team", teamId);
-    if (args.debate === true) {
+    if (isDebate) {
         const debate = buildTeamDebate({
             teamId,
             teamDir,
@@ -2332,8 +2376,7 @@ async function runTeam(args) {
             roleFlag: typeof args.role === "string" ? args.role : undefined,
             provider: setup?.providerSelection.provider,
             visibility: "always_visible",
-            roundCount: rounds,
-            tmux: args.tmux === true
+            roundCount: rounds
         });
         await writeTeamDebateArtifacts(debate, teamDir, prompt);
         const canRecordWorkspace = projectAware.projectContextFound && projectContext && existsSync(projectContext.stateFilePath);
@@ -2357,87 +2400,44 @@ async function runTeam(args) {
             }, null, 2));
             return;
         }
-        if (args.tmux === true) {
-            const sessionName = `longtable-${teamId.replaceAll("_", "-")}`;
-            const shell = process.env.SHELL || "/bin/sh";
-            const launcher = process.argv[1] ?? "longtable";
-            const leaderCommand = [
-                `echo ${shellEscape(`LongTable debate ${teamId}`)}`,
-                `echo ${shellEscape(`Artifacts: ${teamDir}`)}`,
-                `echo ${shellEscape("Fixed rounds are recorded. Role panes can add live review logs.")}`,
-                `echo ${shellEscape(`Checkpoint: ${debate.questionRecord.id}`)}`,
-                `exec ${shellEscape(shell)}`
-            ].join("; ");
-            execFileSync("tmux", ["new-session", "-d", "-s", sessionName, "-c", workingDirectory, leaderCommand], { stdio: "inherit" });
-            for (const member of debate.plan.members) {
-                const rolePrompt = [
-                    `LongTable autonomous debate role: ${member.label} (${member.role}).`,
-                    "Use the fixed debate artifacts as the shared record. Add live notes only; do not answer the researcher checkpoint.",
-                    `Artifacts: ${teamDir}`,
-                    "",
-                    projectAware.prompt
-                ].join("\n");
-                const logPath = join(teamDir, `${member.role}.debate.log`);
-                const command = [
-                    `node ${shellEscape(launcher)} review --role ${shellEscape(member.role)} --prompt ${shellEscape(rolePrompt)} --cwd ${shellEscape(workingDirectory)} 2>&1 | tee ${shellEscape(logPath)}`,
-                    `echo ${shellEscape(`Debate role log written to ${logPath}`)}`,
-                    `exec ${shellEscape(shell)}`
-                ].join("; ");
-                execFileSync("tmux", ["split-window", "-t", sessionName, "-c", workingDirectory, command], { stdio: "inherit" });
-                execFileSync("tmux", ["select-layout", "-t", sessionName, "tiled"], { stdio: "ignore" });
-            }
-            console.log(`LongTable tmux debate launched: ${sessionName}`);
-            console.log(`Attach with: tmux attach -t ${sessionName}`);
-            console.log(`Artifacts: ${teamDir}`);
-            return;
-        }
         console.log(renderTeamDebateSummary(debate.run));
         console.log(`- checkpoint: ${debate.questionRecord.id}`);
         return;
     }
-    await mkdir(teamDir, { recursive: true });
-    await writeFile(join(teamDir, "prompt.txt"), prompt, "utf8");
-    await writeFile(join(teamDir, "plan.json"), JSON.stringify(fallback.plan, null, 2), "utf8");
-    if (args.json === true) {
-        console.log(JSON.stringify({ teamId, teamDir, plan: fallback.plan }, null, 2));
-        return;
+    const team = buildTeamReview({
+        teamId,
+        teamDir,
+        prompt: projectAware.prompt,
+        roleFlag: typeof args.role === "string" ? args.role : undefined,
+        provider: setup?.providerSelection.provider,
+        visibility: "always_visible",
+        roundCount: rounds
+    });
+    await writeTeamDebateArtifacts(team, teamDir, prompt);
+    const canRecordWorkspace = projectAware.projectContextFound && projectContext && existsSync(projectContext.stateFilePath);
+    if (canRecordWorkspace) {
+        await appendInvocationRecordToWorkspace(projectContext, team.invocationRecord, [team.questionRecord]);
     }
-    if (args.tmux !== true) {
-        console.log(renderPanelSummary(fallback.plan));
-        console.log("");
-        console.log("Run with `--tmux` to launch role panes for parallel discussion.");
+    if (args.json === true) {
+        console.log(JSON.stringify({
+            teamId,
+            teamDir,
+            plan: team.plan,
+            run: team.run,
+            questionRecord: team.questionRecord,
+            invocationRecord: team.invocationRecord,
+            execution: {
+                status: "completed",
+                surface: team.run.surface,
+                interactionDepth: team.run.interactionDepth,
+                projectContextFound: projectAware.projectContextFound,
+                invocationLogged: canRecordWorkspace
+            }
+        }, null, 2));
         return;
     }
-    const sessionName = `longtable-${teamId.replaceAll("_", "-")}`;
-    const shell = process.env.SHELL || "/bin/sh";
-    const launcher = process.argv[1] ?? "longtable";
-    const leaderCommand = [
-        `echo ${shellEscape(`LongTable team ${teamId}`)}`,
-        `echo ${shellEscape(`Logs: ${teamDir}`)}`,
-        "echo 'Role panes are running. Review logs, then run:'",
-        `echo ${shellEscape(`longtable panel --role ${fallback.plan.members.map((member) => member.role).join(",")} --prompt ${JSON.stringify(prompt)}`)}`,
-        `exec ${shellEscape(shell)}`
-    ].join("; ");
-    execFileSync("tmux", ["new-session", "-d", "-s", sessionName, "-c", workingDirectory, leaderCommand], { stdio: "inherit" });
-    for (const member of fallback.plan.members) {
-        const rolePrompt = [
-            `LongTable team discussion role: ${member.label} (${member.role}).`,
-            "Give claims, objections, open questions, and evidence needs. Address likely disagreement with other roles.",
-            "",
-            prompt
-        ].join("\n");
-        const logPath = join(teamDir, `${member.role}.log`);
-        const command = [
-            `node ${shellEscape(launcher)} review --role ${shellEscape(member.role)} --prompt ${shellEscape(rolePrompt)} --cwd ${shellEscape(workingDirectory)} 2>&1 | tee ${shellEscape(logPath)}`,
-            `echo ${shellEscape(`Role log written to ${logPath}`)}`,
-            `exec ${shellEscape(shell)}`
-        ].join("; ");
-        execFileSync("tmux", ["split-window", "-t", sessionName, "-c", workingDirectory, command], { stdio: "inherit" });
-        execFileSync("tmux", ["select-layout", "-t", sessionName, "tiled"], { stdio: "ignore" });
-    }
-    console.log(`LongTable tmux team launched: ${sessionName}`);
-    console.log(`Attach with: tmux attach -t ${sessionName}`);
-    console.log(`Logs: ${teamDir}`);
+    console.log(renderTeamDebateSummary(team.run));
+    console.log(`- checkpoint: ${team.questionRecord.id}`);
 }
 async function runDecide(args) {
     const workingDirectory = typeof args.cwd === "string" ? args.cwd : cwd();

package/dist/debate.d.ts

@@ -7,7 +7,6 @@ export interface BuildTeamDebateOptions {
     provider?: ProviderKind;
     visibility?: PanelVisibility;
     roundCount?: number;
-    tmux?: boolean;
 }
 export interface TeamDebateBundle {
     plan: PanelPlan;
@@ -17,5 +16,6 @@ export interface TeamDebateBundle {
     questionRecord: QuestionRecord;
 }
 export declare function createTeamDebateQuestionRecord(run: TeamDebateRun, provider?: ProviderKind): QuestionRecord;
+export declare function buildTeamReview(options: BuildTeamDebateOptions): TeamDebateBundle;
 export declare function buildTeamDebate(options: BuildTeamDebateOptions): TeamDebateBundle;
 export declare function renderTeamDebateSummary(run: TeamDebateRun): string;

package/dist/debate.js

@@ -68,15 +68,18 @@ function independentContribution(roundId, plan, role, label, artifactPath) {
         checkpointTriggers: tags.map((tag) => `${tag}_commitment`)
     });
 }
-function crossReviewContribution(roundId, plan, role, label, targetRole, targetLabel, artifactPath) {
+function crossReviewContribution(roundId, plan, role, label, targetRole, targetLabel, targetContribution, artifactPath) {
     return contribution({
         roundId,
         role,
         label,
         targetRole,
+        respondsToContributionId: targetContribution.id,
+        stance: "conditional",
         artifactPath,
-        summary: `${label} challenges ${targetLabel}'s likely blind spot before synthesis.`,
+        summary: `${label} cross-reviews ${targetLabel}'s independent contribution (${targetContribution.id}) before synthesis.`,
         claims: [
+            `Responds to ${targetLabel}'s claim: ${targetContribution.claims[0]}`,
             `${targetLabel}'s concern is useful only if it does not erase ${label}'s domain-specific risk.`,
             "The debate should expose disagreement as a researcher decision point rather than normalize it away."
         ],
@@ -160,12 +163,13 @@ function convergenceContribution(roundId, plan, role, label, artifactPath) {
         checkpointTriggers: ["panel_next_decision"]
     });
 }
-function buildSynthesis(plan, artifactPath) {
+function buildSynthesis(plan, artifactPath, kind) {
     const labels = plan.members.map((member) => member.label);
     const highSensitivity = plan.checkpointSensitivity === "high";
+    const runLabel = kind === "debate" ? "debate" : "team review";
     return {
         artifactPath,
-        summary: `The debate completed fixed 5-round review across ${labels.join(", ")}. It should slow closure by turning role disagreement into an explicit researcher decision.`,
+        summary: `The ${runLabel} completed across ${labels.join(", ")}. It should slow closure by turning role disagreement into an explicit researcher decision.`,
         consensus: [
             "The researcher should see role disagreement before LongTable drafts, commits, or submits a conclusion.",
             "Evidence gaps and tacit assumptions should remain visible instead of being smoothed into fluent prose."
@@ -183,12 +187,13 @@ function buildSynthesis(plan, artifactPath) {
             "Choose whether the debate should affect the current artifact, the research design, or only the decision log."
         ],
         recommendedCheckpoint: highSensitivity
-            ? "The debate surfaced high-sensitivity disagreement. What should LongTable treat as the next human decision before closure?"
-            : "The debate surfaced role disagreement. Should LongTable revise, verify evidence, proceed, or keep the tension open?"
+            ? `The ${runLabel} surfaced high-sensitivity disagreement. What should LongTable treat as the next human decision before closure?`
+            : `The ${runLabel} surfaced role disagreement. Should LongTable revise, verify evidence, proceed, or keep the tension open?`
     };
 }
 export function createTeamDebateQuestionRecord(run, provider) {
     const createdAt = nowIso();
+    const isDebate = run.interactionDepth === "debated";
     return {
         id: createId("question_record"),
         createdAt,
@@ -197,7 +202,7 @@ export function createTeamDebateQuestionRecord(run, provider) {
         prompt: {
             id: createId("question_prompt"),
             checkpointKey: "team_debate_next_decision",
-            title: "Team debate follow-up decision",
+            title: isDebate ? "Team debate follow-up decision" : "Agent team follow-up decision",
             question: run.synthesis.recommendedCheckpoint,
             type: "single_choice",
             options: [
@@ -229,10 +234,15 @@ export function createTeamDebateQuestionRecord(run, provider) {
                 return key ? getPersonaDefinition(key).checkpointSensitivity === "high" : false;
             }),
             source: "runtime_guidance",
+            displayReason: isDebate
+                ? "Role rebuttals and convergence should connect to an explicit researcher decision."
+                : "Cross-review created role disagreement that should connect to an explicit researcher decision.",
             rationale: [
-                "Autonomous team debate is a research harness surface, not a substitute for researcher judgment.",
-                "The fixed debate rounds created disagreement that should connect to an explicit researcher decision.",
-                `Team debate run: ${run.id}.`
+                "Agent team orchestration is a research harness surface, not a substitute for researcher judgment.",
+                isDebate
+                    ? "The fixed debate rounds created disagreement that should connect to an explicit researcher decision."
+                    : "The cross-review round created disagreement that should connect to an explicit researcher decision.",
+                `Agent team run: ${run.id}.`
             ],
             preferredSurfaces: provider === "claude"
                 ? ["native_structured", "numbered"]
@@ -240,10 +250,13 @@ export function createTeamDebateQuestionRecord(run, provider) {
         }
     };
 }
-export function buildTeamDebate(options) {
-    const roundCount = options.roundCount ?? 5;
-    if (roundCount !== 5) {
-        throw new Error("LongTable debate v1 supports fixed 5-round debate only.");
+function buildTeamBundle(options, kind) {
+    const roundCount = options.roundCount ?? (kind === "debate" ? 5 : 3);
+    const expectedRounds = kind === "debate" ? 5 : 3;
+    if (roundCount !== expectedRounds) {
+        throw new Error(kind === "debate"
+            ? "LongTable debate v1 supports fixed 5-round debate only."
+            : "LongTable team v1 supports fixed 3-round cross-review only.");
     }
     const createdAt = nowIso();
     const plan = buildPanelPlan({
@@ -255,6 +268,7 @@ export function buildTeamDebate(options) {
     });
     const rounds = [];
     const round1Id = createId("team_round");
+    const independentContributions = plan.members.map((member) => independentContribution(round1Id, plan, member.role, member.label, join("round-1-independent", `${member.role}.json`)));
     rounds.push({
         id: round1Id,
         index: 1,
@@ -262,12 +276,12 @@ export function buildTeamDebate(options) {
         title: "Independent review",
         status: "completed",
         artifactDir: join(options.teamDir, "round-1-independent"),
-        contributions: plan.members.map((member) => independentContribution(round1Id, plan, member.role, member.label, join("round-1-independent", `${member.role}.json`)))
+        contributions: independentContributions
     });
     const round2Id = createId("team_round");
     const crossContributions = plan.members.flatMap((member) => plan.members
         .filter((target) => target.role !== member.role)
-        .map((target) => crossReviewContribution(round2Id, plan, member.role, member.label, target.role, target.label, join("round-2-cross-review", `${member.role}-on-${target.role}.json`))));
+        .map((target) => crossReviewContribution(round2Id, plan, member.role, member.label, target.role, target.label, independentContributions.find((contribution) => contribution.role === target.role), join("round-2-cross-review", `${member.role}-on-${target.role}.json`))));
     rounds.push({
         id: round2Id,
         index: 2,
@@ -277,27 +291,29 @@ export function buildTeamDebate(options) {
         artifactDir: join(options.teamDir, "round-2-cross-review"),
         contributions: crossContributions
     });
-    const round3Id = createId("team_round");
-    rounds.push({
-        id: round3Id,
-        index: 3,
-        kind: "rebuttal",
-        title: "Rebuttal and revision",
-        status: "completed",
-        artifactDir: join(options.teamDir, "round-3-rebuttal"),
-        contributions: plan.members.map((member) => rebuttalContribution(round3Id, member.role, member.label, join("round-3-rebuttal", `${member.role}.json`)))
-    });
-    const round4Id = createId("team_round");
-    rounds.push({
-        id: round4Id,
-        index: 4,
-        kind: "convergence",
-        title: "Convergence and unresolved gaps",
-        status: "completed",
-        artifactDir: join(options.teamDir, "round-4-convergence"),
-        contributions: plan.members.map((member) => convergenceContribution(round4Id, plan, member.role, member.label, join("round-4-convergence", `${member.role}.json`)))
-    });
-    const synthesis = buildSynthesis(plan, "synthesis.json");
+    if (kind === "debate") {
+        const round3Id = createId("team_round");
+        rounds.push({
+            id: round3Id,
+            index: 3,
+            kind: "rebuttal",
+            title: "Rebuttal and revision",
+            status: "completed",
+            artifactDir: join(options.teamDir, "round-3-rebuttal"),
+            contributions: plan.members.map((member) => rebuttalContribution(round3Id, member.role, member.label, join("round-3-rebuttal", `${member.role}.json`)))
+        });
+        const round4Id = createId("team_round");
+        rounds.push({
+            id: round4Id,
+            index: 4,
+            kind: "convergence",
+            title: "Convergence and unresolved gaps",
+            status: "completed",
+            artifactDir: join(options.teamDir, "round-4-convergence"),
+            contributions: plan.members.map((member) => convergenceContribution(round4Id, plan, member.role, member.label, join("round-4-convergence", `${member.role}.json`)))
+        });
+    }
+    const synthesis = buildSynthesis(plan, "synthesis.json", kind);
     const run = {
         id: createId("team_debate_run"),
         teamId: options.teamId,
@@ -306,15 +322,16 @@ export function buildTeamDebate(options) {
         prompt: options.prompt,
         roles: plan.members,
         status: "completed",
-        surface: options.tmux ? "tmux_console" : "file_backed_debate",
-        roundPolicy: "fixed",
+        surface: "file_backed_debate",
+        interactionDepth: kind === "debate" ? "debated" : "cross_reviewed",
+        roundPolicy: kind === "debate" ? "fixed" : "team_cross_review",
         roundCount,
         artifactRoot: options.teamDir,
         rounds: [
             ...rounds,
             {
                 id: createId("team_round"),
-                index: 5,
+                index: roundCount,
                 kind: "synthesis",
                 title: "Coordinator synthesis and checkpoint",
                 status: "completed",
@@ -335,11 +352,13 @@ export function buildTeamDebate(options) {
         visibility: plan.visibility,
         checkpointSensitivity: plan.checkpointSensitivity,
         rationale: [
-            "Autonomous debate requested through LongTable team orchestration.",
-            "File-backed fixed rounds keep disagreement inspectable before researcher closure."
+            kind === "debate"
+                ? "Autonomous debate requested through LongTable team orchestration."
+                : "Agent team cross-review requested through LongTable team orchestration.",
+            "File-backed rounds keep disagreement inspectable before researcher closure."
         ]
     });
-    intent.kind = "team_debate";
+    intent.kind = kind === "debate" ? "team_debate" : "team";
     intent.requestedSurface = run.surface;
     const invocationRecord = {
         id: createId("invocation_record"),
@@ -349,11 +368,10 @@ export function buildTeamDebate(options) {
         status: "completed",
         provider: options.provider,
         surface: run.surface,
+        interactionDepth: run.interactionDepth,
         panelPlan: plan,
         teamDebateRun: run,
-        degradationReason: options.tmux
-            ? undefined
-            : "Tmux was not requested; file-backed debate artifacts are the canonical execution record."
+        degradationReason: "File-backed team artifacts are the canonical execution record."
     };
     return {
         plan,
@@ -363,12 +381,19 @@ export function buildTeamDebate(options) {
         questionRecord
     };
 }
+export function buildTeamReview(options) {
+    return buildTeamBundle(options, "team");
+}
+export function buildTeamDebate(options) {
+    return buildTeamBundle(options, "debate");
+}
 export function renderTeamDebateSummary(run) {
     return [
         "LongTable Team Debate",
         `- team: ${run.teamId}`,
         `- surface: ${run.surface}`,
-        `- rounds: ${run.roundCount} fixed`,
+        `- interaction depth: ${run.interactionDepth}`,
+        `- rounds: ${run.roundCount} ${run.roundPolicy}`,
         `- roles: ${run.roles.map((role) => `${role.label} (${role.role})`).join(", ")}`,
         `- artifacts: ${run.artifactRoot}`,
         "",

package/dist/panel.js

@@ -143,6 +143,7 @@ export function createPlannedPanelQuestionRecord(plan, provider) {
                 "Panel review creates disagreement or risk visibility that should connect to an explicit researcher decision.",
                 `Panel checkpoint sensitivity: ${plan.checkpointSensitivity}.`
             ],
+            displayReason: "Panel review can surface role disagreement that should not be collapsed without researcher approval.",
             preferredSurfaces: provider === "claude"
                 ? ["native_structured", "numbered"]
                 : ["mcp_elicitation", "numbered"]
@@ -159,6 +160,7 @@ export function createPlannedPanelResult(plan, provider, linkedQuestionRecordIds
         provider,
         surface: "sequential_fallback",
         status: "planned",
+        interactionDepth: "independent",
         memberResults: plan.members.map((member) => ({
             role: member.role,
             label: member.label,
@@ -178,6 +180,7 @@ export function createPlannedInvocationRecord(options) {
         status: "planned",
         provider: options.provider,
         surface: "sequential_fallback",
+        interactionDepth: "independent",
         panelPlan: options.plan,
         panelResult: options.result,
         degradationReason: "Native provider team execution is optional; sequential fallback is the stable LongTable surface."

package/dist/persona-router.d.ts

@@ -12,6 +12,7 @@ export interface LongTableInvocationDirective {
     explicit: boolean;
     cleanedPrompt: string;
     mode?: InteractionMode | "panel" | "status";
+    collaboration?: "panel" | "team" | "debate";
     roles: CanonicalPersona[];
     panel: boolean;
     showConflicts: boolean;

package/dist/persona-router.js

@@ -7,7 +7,9 @@ const DIRECTIVE_MAP = [
     { key: "critique", mode: "critique" },
     { key: "draft", mode: "draft" },
     { key: "commit", mode: "commit" },
-    { key: "panel", mode: "panel", panel: true, showConflicts: true },
+    { key: "panel", mode: "panel", collaboration: "panel", panel: true, showConflicts: true },
+    { key: "team", mode: "review", collaboration: "team", panel: true, showConflicts: true },
+    { key: "debate", mode: "review", collaboration: "debate", panel: true, showConflicts: true },
     { key: "status", mode: "status" },
     { key: "editor", mode: "review", roles: ["editor"] },
     { key: "reviewer", mode: "review", roles: ["reviewer"] },
@@ -72,6 +74,7 @@ export function parseInvocationDirective(prompt) {
         explicit: true,
         cleanedPrompt: body || prompt,
         mode: directive.mode,
+        collaboration: directive.collaboration,
         roles: directive.roles ?? [],
         panel: directive.panel === true,
         showConflicts: directive.showConflicts === true

package/dist/project-session.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionRecord, InvocationRecord, ProviderKind, QuestionSurface, QuestionRecord, ResearchState } from "@longtable/core";
+import type { DecisionRecord, InvocationRecord, ProviderKind, QuestionOption, QuestionSurface, QuestionRecord, ResearchState } from "@longtable/core";
 import type { SetupPersistedOutput } from "@longtable/setup";
 export type ProjectDisagreementPreference = "synthesis_only" | "show_on_conflict" | "always_visible";
 export interface LongTableProjectRecord {
@@ -113,7 +113,7 @@ export declare function syncCurrentWorkspaceView(context: LongTableProjectContex
 export declare function appendInvocationRecordToWorkspace(context: LongTableProjectContext, invocation: InvocationRecord, questions?: QuestionRecord[]): Promise<ResearchState>;
 export declare function listBlockingWorkspaceQuestions(context: LongTableProjectContext): Promise<QuestionRecord[]>;
 export declare function assertWorkspaceNotBlocked(context: LongTableProjectContext): Promise<void>;
-export declare function createWorkspaceClarificationCard(options: {
+export declare function createWorkspaceFollowUpQuestions(options: {
     context: LongTableProjectContext;
     prompt: string;
     provider?: ProviderKind;
@@ -130,6 +130,9 @@ export declare function createWorkspaceQuestion(options: {
     prompt: string;
     title?: string;
     question?: string;
+    checkpointKey?: string;
+    questionOptions?: QuestionOption[];
+    displayReason?: string;
     provider?: ProviderKind;
     required?: boolean;
 }): Promise<{

package/dist/project-session.js

@@ -647,10 +647,10 @@ function optionsForCheckpointTrigger(family, checkpointKey) {
 function includesAny(prompt, patterns) {
     return patterns.some((pattern) => pattern.test(prompt));
 }
-function clarificationOptions(first, second, third, fourth) {
+function followUpQuestionOptions(first, second, third, fourth) {
     return [first, second, third, ...(fourth ? [fourth] : [])];
 }
-function buildClarificationQuestionSpecs(prompt) {
+function buildFollowUpQuestionSpecs(prompt) {
     const normalized = prompt.toLowerCase();
     const specs = [];
     function push(spec) {
@@ -664,7 +664,7 @@ function buildClarificationQuestionSpecs(prompt) {
             title: "Rubric update basis",
             question: "How should LongTable use the available materials to update the rubric?",
             whyNow: "Rubric updates can silently change grading criteria if LongTable guesses the calibration basis.",
-            options: clarificationOptions({ value: "calibrate_to_exemplars", label: "Calibrate criteria to exemplars", description: "Use strong submissions to refine what each criterion means.", recommended: true }, { value: "polish_existing", label: "Polish existing rubric only", description: "Keep criteria stable and improve wording or consistency." }, { value: "rewrite_structure", label: "Restructure the rubric", description: "Change categories or levels where the materials suggest a better structure." })
+            options: followUpQuestionOptions({ value: "calibrate_to_exemplars", label: "Calibrate criteria to exemplars", description: "Use strong submissions to refine what each criterion means.", recommended: true }, { value: "polish_existing", label: "Polish existing rubric only", description: "Keep criteria stable and improve wording or consistency." }, { value: "rewrite_structure", label: "Restructure the rubric", description: "Change categories or levels where the materials suggest a better structure." })
         });
     }
     if (includesAny(normalized, [/\bexemplar\b/, /\bbest submission\b/, /\bselected submission\b/, /\bTA\b/i, /우수\s*답안|예시|선정|조교/])) {
@@ -673,7 +673,7 @@ function buildClarificationQuestionSpecs(prompt) {
             title: "Exemplar use",
             question: "How should LongTable use selected exemplars or TA guidance?",
             whyNow: "Exemplars can either calibrate criteria privately or become visible evidence inside the output.",
-            options: clarificationOptions({ value: "calibrate_only", label: "Use as private calibration", description: "Adjust criteria using exemplars without quoting them.", recommended: true }, { value: "include_deidentified_excerpts", label: "Include de-identified excerpts", description: "Add short anonymized examples where they clarify quality." }, { value: "separate_notes", label: "Keep examples in separate notes", description: "Use exemplars outside the main artifact." })
+            options: followUpQuestionOptions({ value: "calibrate_only", label: "Use as private calibration", description: "Adjust criteria using exemplars without quoting them.", recommended: true }, { value: "include_deidentified_excerpts", label: "Include de-identified excerpts", description: "Add short anonymized examples where they clarify quality." }, { value: "separate_notes", label: "Keep examples in separate notes", description: "Use exemplars outside the main artifact." })
         });
     }
     if (includesAny(normalized, [/\binstruction/, /\bguidance\b/, /\bsource\b/, /\bfile\b/, /\bdocx?\b/, /지침|가이드|문서|파일|자료/])) {
@@ -682,7 +682,7 @@ function buildClarificationQuestionSpecs(prompt) {
             title: "Source authority",
             question: "If sources conflict or leave gaps, which source should LongTable privilege?",
             whyNow: "Without an authority rule, LongTable may resolve conflicts by convenience rather than researcher intent.",
-            options: clarificationOptions({ value: "explicit_user_instruction", label: "Your explicit instruction", description: "Use the researcher's current instruction as the highest authority.", recommended: true }, { value: "project_files", label: "Project files", description: "Treat supplied files or existing artifacts as authoritative." }, { value: "external_guidance", label: "TA or external guidance", description: "Prioritize instructor, TA, venue, or policy guidance." })
+            options: followUpQuestionOptions({ value: "explicit_user_instruction", label: "Your explicit instruction", description: "Use the researcher's current instruction as the highest authority.", recommended: true }, { value: "project_files", label: "Project files", description: "Treat supplied files or existing artifacts as authoritative." }, { value: "external_guidance", label: "TA or external guidance", description: "Prioritize instructor, TA, venue, or policy guidance." })
         });
     }
     if (includesAny(normalized, [/\bdeliver\b/, /\boutput\b/, /\btracked?[- ]?change/, /\bdocx?\b/, /\bmarkdown\b/, /\btable\b/, /전달|산출물|결과물|수정\s*표시|트랙|형식|포맷/])) {
@@ -691,7 +691,7 @@ function buildClarificationQuestionSpecs(prompt) {
             title: "Delivery format",
             question: "How should LongTable deliver the clarified output?",
             whyNow: "Format and change-tracking choices affect whether the result is usable for review or handoff.",
-            options: clarificationOptions({ value: "tracked_changes", label: "Tracked-change artifact", description: "Produce a reviewable changed version where possible.", recommended: true }, { value: "clean_final", label: "Clean final artifact", description: "Deliver the final version without change markup." }, { value: "summary_plus_artifact", label: "Summary plus artifact", description: "Include a concise change summary with the output." })
+            options: followUpQuestionOptions({ value: "tracked_changes", label: "Tracked-change artifact", description: "Produce a reviewable changed version where possible.", recommended: true }, { value: "clean_final", label: "Clean final artifact", description: "Deliver the final version without change markup." }, { value: "summary_plus_artifact", label: "Summary plus artifact", description: "Include a concise change summary with the output." })
         });
     }
     if (includesAny(normalized, [/\bupdate\b/, /\bchange\b/, /\bedit\b/, /\bfix\b/, /\bimplement\b/, /\bbuild\b/, /\bcreate\b/, /업데이트|수정|변경|구현|만들|고쳐/])) {
@@ -700,7 +700,7 @@ function buildClarificationQuestionSpecs(prompt) {
             title: "Autonomy boundary",
             question: "How much should LongTable do before checking back with you?",
             whyNow: "Execution requests can move from advice to authorship or artifact ownership unless the boundary is explicit.",
-            options: clarificationOptions({ value: "ask_then_act", label: "Clarify first, then act", description: "Ask needed questions before changing the artifact.", recommended: true }, { value: "act_with_defaults", label: "Act with visible defaults", description: "Proceed using recommended defaults and record them." }, { value: "recommend_only", label: "Recommend only", description: "Describe changes but do not alter artifacts." })
+            options: followUpQuestionOptions({ value: "ask_then_act", label: "Clarify first, then act", description: "Ask needed questions before changing the artifact.", recommended: true }, { value: "act_with_defaults", label: "Act with visible defaults", description: "Proceed using recommended defaults and record them." }, { value: "recommend_only", label: "Recommend only", description: "Describe changes but do not alter artifacts." })
         });
     }
     if (includesAny(normalized, [/\bperformance\b/, /\btest\b/, /\bevaluate\b/, /\bcheck\b/, /\bbenchmark\b/, /성능|테스트|평가|체크|검증/])) {
@@ -709,7 +709,7 @@ function buildClarificationQuestionSpecs(prompt) {
             title: "Evaluation target",
             question: "What should LongTable treat as the main performance target?",
             whyNow: "Performance checks can optimize for UX, correctness, trigger sensitivity, or delivery reliability.",
-            options: clarificationOptions({ value: "question_sensitivity", label: "Question sensitivity", description: "Check whether LongTable asks at the right knowledge-gap moments.", recommended: true }, { value: "renderer_convenience", label: "Renderer convenience", description: "Check whether the most convenient question UI is used." }, { value: "state_reliability", label: "State reliability", description: "Check whether questions and answers persist correctly." })
+            options: followUpQuestionOptions({ value: "question_sensitivity", label: "Question sensitivity", description: "Check whether LongTable asks at the right knowledge-gap moments.", recommended: true }, { value: "renderer_convenience", label: "Renderer convenience", description: "Check whether the most convenient question UI is used." }, { value: "state_reliability", label: "State reliability", description: "Check whether questions and answers persist correctly." })
         });
     }
     if (specs.length === 0) {
@@ -718,19 +718,19 @@ function buildClarificationQuestionSpecs(prompt) {
             title: "Missing context",
             question: "What should LongTable clarify before proceeding?",
             whyNow: "The request can be answered in multiple ways, and choosing silently would hide a researcher judgment.",
-            options: clarificationOptions({ value: "scope", label: "Clarify scope first", description: "Ask what is included and excluded before acting.", recommended: true }, { value: "criteria", label: "Clarify success criteria", description: "Ask what would count as a good result." }, { value: "proceed", label: "Proceed with visible assumptions", description: "Continue, but make assumptions explicit." })
+            options: followUpQuestionOptions({ value: "scope", label: "Clarify scope first", description: "Ask what is included and excluded before acting.", recommended: true }, { value: "criteria", label: "Clarify success criteria", description: "Ask what would count as a good result." }, { value: "proceed", label: "Proceed with visible assumptions", description: "Continue, but make assumptions explicit." })
         });
     }
     return specs;
 }
-const CLARIFICATION_PROMPT_PREFIX = "Clarification prompt:";
-function hasClarificationPrompt(record, prompt) {
-    return record.prompt.rationale.includes(`${CLARIFICATION_PROMPT_PREFIX} ${prompt}`);
+const FOLLOW_UP_PROMPT_PREFIX = "Follow-up prompt:";
+function hasFollowUpPrompt(record, prompt) {
+    return record.prompt.rationale.includes(`${FOLLOW_UP_PROMPT_PREFIX} ${prompt}`);
 }
-export async function createWorkspaceClarificationCard(options) {
+export async function createWorkspaceFollowUpQuestions(options) {
     const state = await loadResearchState(options.context.stateFilePath);
     if (!options.force) {
-        const existing = (state.questionLog ?? []).filter((record) => hasClarificationPrompt(record, options.prompt));
+        const existing = (state.questionLog ?? []).filter((record) => hasFollowUpPrompt(record, options.prompt));
         const pending = existing.filter((record) => record.status === "pending");
         if (pending.length > 0) {
             return { questions: pending, state, created: false, alreadyAnswered: false };
@@ -743,14 +743,14 @@ export async function createWorkspaceClarificationCard(options) {
     const preferredSurfaces = options.provider === "claude"
         ? ["native_structured", "terminal_selector", "numbered"]
         : ["mcp_elicitation", "terminal_selector", "numbered"];
-    const questions = buildClarificationQuestionSpecs(options.prompt).map((spec) => ({
+    const questions = buildFollowUpQuestionSpecs(options.prompt).map((spec) => ({
         id: createId("question_record"),
         createdAt,
         updatedAt: createdAt,
         status: "pending",
         prompt: {
             id: createId("question_prompt"),
-            checkpointKey: `clarification_${spec.key}`,
+            checkpointKey: `follow_up_${spec.key}`,
             title: spec.title,
             question: spec.question,
             type: "single_choice",
@@ -761,7 +761,7 @@ export async function createWorkspaceClarificationCard(options) {
             source: "runtime_guidance",
             rationale: [
                 spec.whyNow,
-                `${CLARIFICATION_PROMPT_PREFIX} ${options.prompt}`
+                `${FOLLOW_UP_PROMPT_PREFIX} ${options.prompt}`
             ],
             preferredSurfaces: preferredSurfaces
         }
@@ -777,6 +777,7 @@ export async function createWorkspaceQuestion(options) {
         unresolvedTensions: state.openTensions ?? [],
         studyContract: state.studyContract
     });
+    const checkpointKey = options.checkpointKey ?? trigger.signal.checkpointKey;
     const createdAt = nowIso();
     const question = {
         id: createId("question_record"),
@@ -785,15 +786,16 @@ export async function createWorkspaceQuestion(options) {
         status: "pending",
         prompt: {
             id: createId("question_prompt"),
-            checkpointKey: trigger.signal.checkpointKey,
-            title: options.title ?? questionTitleForCheckpoint(trigger.family, trigger.signal.checkpointKey),
-            question: options.question ?? questionTextForCheckpoint(trigger.family, options.prompt, trigger.signal.checkpointKey),
+            checkpointKey,
+            title: options.title ?? questionTitleForCheckpoint(trigger.family, checkpointKey),
+            question: options.question ?? questionTextForCheckpoint(trigger.family, options.prompt, checkpointKey),
             type: "single_choice",
-            options: optionsForCheckpointTrigger(trigger.family, trigger.signal.checkpointKey),
+            options: options.questionOptions ?? optionsForCheckpointTrigger(trigger.family, checkpointKey),
             allowOther: true,
             otherLabel: "Other decision",
             required: options.required ?? trigger.requiresQuestionBeforeClosure,
             source: "checkpoint",
+            displayReason: options.displayReason ?? trigger.rationale[0],
             rationale: [
                 ...trigger.rationale,
                 `Trigger family: ${trigger.family}.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/cli",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "private": false,
   "description": "Researcher-facing LongTable CLI",
   "type": "module",
@@ -28,12 +28,12 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@longtable/checkpoints": "0.1.24",
-    "@longtable/core": "0.1.24",
-    "@longtable/memory": "0.1.24",
-    "@longtable/provider-claude": "0.1.24",
-    "@longtable/provider-codex": "0.1.24",
-    "@longtable/setup": "0.1.24"
+    "@longtable/checkpoints": "0.1.26",
+    "@longtable/core": "0.1.26",
+    "@longtable/memory": "0.1.26",
+    "@longtable/provider-claude": "0.1.26",
+    "@longtable/provider-codex": "0.1.26",
+    "@longtable/setup": "0.1.26"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",