@dmsdc-ai/aigentry-deliberation 0.0.37 → 0.0.39

package/README.md

@@ -111,8 +111,10 @@ Claude Code, Codex CLI, Gemini CLI의 MCP 설정을 자동 점검하고 문제
 | `deliberation_browser_llm_tabs` | List browser LLM tabs |
 | `deliberation_browser_auto_turn` | Auto-send turn to browser LLM |
 | `deliberation_route_turn` | Route turn to appropriate transport |
+| `deliberation_run_until_blocked` | Auto-run mixed transports until completion or a manual block |
 | `deliberation_request_review` | Request code review |
 | `deliberation_cli_auto_turn` | Auto-send turn to CLI speaker |
+| `deliberation_ingest_remote_reply` | Canonical semantic ingress for remote replies with explicit source metadata |
 | `deliberation_cli_config` | Configure CLI settings |
 
 ## Start Flow
@@ -133,10 +135,53 @@ Raw candidate tokens cannot start a deliberation.
 Telepty-managed sessions are now routed through the telepty bus instead of raw PTY inject guidance.
 
 - `deliberation_route_turn` publishes a typed `turn_request` envelope on `ws://localhost:3848/api/bus`
+- `deliberation_run_until_blocked` can continue across `cli_respond`, `browser_auto`, and `telepty_bus` speakers until a manual block is reached
 - transport delivery is tracked with a 5-second `inject_written` ack window
 - semantic completion is tracked with a 60-second self-submit window
 - `session_health` bus events are cached for operator visibility
 - `deliberation_synthesize` validates and emits typed `deliberation_completed` envelopes for downstream automation
+- telepty envelopes now carry top-level `version: 1` and optional `source_host`
+
+### Cross-Machine Event Catalog
+
+Canonical boundary split with telepty:
+
+- **Guaranteed (daemon-emitted):** `inject_written`, `session_health`, `session_register`, `session.replaced`, `session.idle`, `thread.opened`, `thread.closed`, `handoff.*`, `message_routed`
+- **Best-effort (bus relay only):** `turn_request`, `turn_completed`, `deliberation_completed`
+- `kind` is the canonical event discriminator
+- `target` identifies the telepty session target
+- `payload.prompt` is the canonical prompt field for `turn_request`
+- `source_host` is optional transport metadata for cross-machine tracing
+
+### Remote Reply Ingress
+
+If a remote participant cannot call local MCP tools directly, do **not** proxy-synthesize a reply. Use the deliberation-owned semantic ingress:
+
+```text
+deliberation_ingest_remote_reply(
+  session_id: "...",
+  speaker: "...",
+  turn_id: "...",
+  content: "...",
+  source_machine_id: "peer-01",
+  source_session_id: "remote-gemini-001",
+  transport_scope: "remote_mcp",
+  artifact_refs: ["results.jsonl"]
+)
+```
+
+This preserves explicit provenance instead of inferring semantics from raw bus events.
+
+### Gemini Recovery
+
+Canonical repair path today is still installer-based:
+
+```bash
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install
+```
+
+Use doctor first; if Gemini MCP registration/path/runtime drift is detected, rerun install and restart Gemini CLI.
 
 ## Experiment Retrospectives
 

package/index.js

@@ -160,9 +160,11 @@ const StructuredSynthesisSchema = z.object({
 });
 
 const StructuredExecutionContractSchema = z.object({
-  version: z.literal("v1"),
+  schema_version: z.number().int().positive(),
   source_session_id: z.string().min(1),
+  deliberation_id: z.string().min(1),
   summary: z.string(),
+  decisions: z.array(z.string()),
   tasks: z.array(StructuredActionableTaskSchema),
   experiment_outcome: StructuredExperimentOutcomeSchema.nullable().optional(),
   unresolved_questions: z.array(z.string()),
@@ -173,11 +175,13 @@ const StructuredExecutionContractSchema = z.object({
 });
 
 const TeleptyEnvelopeSchema = z.object({
+  version: z.number().int().positive().optional(),
   message_id: z.string().min(1),
   session_id: z.string().min(1),
   project: z.string().min(1),
   kind: z.string().min(1),
   source: z.string().min(1),
+  source_host: z.string().min(1).optional(),
   target: z.string().min(1),
   reply_to: z.string().nullable().optional(),
   trace: z.array(z.string()),
@@ -192,12 +196,27 @@ const TeleptyTurnRequestPayloadSchema = z.object({
   speaker: z.string().min(1),
   role: z.string().nullable().optional(),
   prompt: z.string().min(1),
+  content: z.string().min(1).describe("PTY-compatible alias for prompt field"),
   prompt_sha1: z.string().length(40),
   history_entries: z.number().int().nonnegative().optional(),
   transport_timeout_ms: z.number().int().positive(),
   semantic_timeout_ms: z.number().int().positive(),
 });
 
+const TeleptyTurnCompletedPayloadSchema = z.object({
+  turn_id: z.string().nullable().optional(),
+  speaker: z.string().min(1),
+  round: z.number().int().positive(),
+  max_rounds: z.number().int().positive(),
+  next_speaker: z.string().min(1),
+  next_round: z.number().int().positive(),
+  status: z.string().min(1),
+  total_responses: z.number().int().nonnegative(),
+  channel_used: z.string().nullable().optional(),
+  fallback_reason: z.string().nullable().optional(),
+  orchestrator_session_id: z.string().nullable().optional(),
+});
+
 const TeleptyDeliberationCompletedPayloadSchema = z.object({
   topic: z.string(),
   synthesis: z.string(),
@@ -207,6 +226,7 @@ const TeleptyDeliberationCompletedPayloadSchema = z.object({
 
 const TELEPTY_ENVELOPE_PAYLOAD_SCHEMAS = {
   turn_request: TeleptyTurnRequestPayloadSchema,
+  turn_completed: TeleptyTurnCompletedPayloadSchema,
   deliberation_completed: TeleptyDeliberationCompletedPayloadSchema,
 };
 
@@ -543,12 +563,26 @@ function hashStructuredSynthesis(structured) {
   return hashPromptText(JSON.stringify(sortJsonValue(structured || null)));
 }
 
+/**
+ * Build a deterministic execution contract from structured synthesis.
+ *
+ * Data model canonical roles:
+ * - structured_synthesis: human + reasoning canonical — rich context for
+ *   human review (decisions rationale, experiment outcomes, full task descriptions).
+ * - execution_contract: automation canonical — minimal, deterministic task list
+ *   derived from structured_synthesis via SHA-1 hash for provenance tracking.
+ *   Consumers (inbox-watcher, devkit, registry, orchestrator) MUST prefer
+ *   execution_contract when available; fall back to structured_synthesis only
+ *   when execution_contract is absent.
+ */
 function buildExecutionContract({ state, structured }) {
   if (!structured) return null;
   return {
-    version: "v1",
+    schema_version: 2,
     source_session_id: state.id,
+    deliberation_id: state.id,
     summary: structured.summary || "",
+    decisions: structured.decisions || [],
     tasks: structured.actionable_tasks || [],
     experiment_outcome: structured.experiment_outcome || null,
     unresolved_questions: [],
@@ -572,13 +606,24 @@ function validateTeleptyEnvelope(envelope) {
   return parsed;
 }
 
-function buildTeleptyEnvelope({ session_id, project, kind, source, target, reply_to = null, trace = [], payload, ts = new Date().toISOString(), message_id = createEnvelopeId(kind) }) {
+function resolveTeleptySourceHost() {
+  const explicit = process.env.TELEPTY_SOURCE_HOST;
+  if (typeof explicit === "string" && explicit.trim()) {
+    return explicit.trim();
+  }
+  const hostname = os.hostname();
+  return typeof hostname === "string" && hostname.trim() ? hostname.trim() : undefined;
+}
+
+function buildTeleptyEnvelope({ session_id, project, kind, source, source_host = resolveTeleptySourceHost(), target, reply_to = null, trace = [], payload, ts = new Date().toISOString(), message_id = createEnvelopeId(kind) }) {
   return validateTeleptyEnvelope({
+    version: 1,
     message_id,
     session_id,
     project,
     kind,
     source,
+    source_host,
     target,
     reply_to,
     trace,
@@ -611,6 +656,7 @@ function buildTeleptyTurnRequestEnvelope({ state, speaker, turnId, turnPrompt, i
       speaker,
       role,
       prompt: turnPrompt,
+      content: turnPrompt,
       prompt_sha1: hashPromptText(turnPrompt),
       history_entries: includeHistoryEntries,
       transport_timeout_ms: TELEPTY_TRANSPORT_TIMEOUT_MS,
@@ -619,6 +665,35 @@ function buildTeleptyTurnRequestEnvelope({ state, speaker, turnId, turnPrompt, i
   });
 }
 
+function buildTeleptyTurnCompletedEnvelope({ state, entry }) {
+  return buildTeleptyEnvelope({
+    session_id: state.id,
+    project: state.project || getProjectSlug(),
+    kind: "turn_completed",
+    source: `deliberation:${state.id}`,
+    target: "telepty-bus",
+    reply_to: state.orchestrator_session_id || state.id,
+    trace: [
+      `project:${state.project || getProjectSlug()}`,
+      `speaker:${entry.speaker}`,
+      `turn:${entry.turn_id || "none"}`,
+    ],
+    payload: {
+      turn_id: entry.turn_id || null,
+      speaker: entry.speaker,
+      round: entry.round,
+      max_rounds: state.max_rounds,
+      next_speaker: state.current_speaker || "none",
+      next_round: state.current_round,
+      status: state.status,
+      total_responses: Array.isArray(state.log) ? state.log.length : 0,
+      channel_used: entry.channel_used || null,
+      fallback_reason: entry.fallback_reason || null,
+      orchestrator_session_id: state.orchestrator_session_id || null,
+    },
+  });
+}
+
 function buildTeleptySynthesisEnvelope({ state, synthesis, structured, executionContract }) {
   const derivedExecutionContract =
     executionContract !== undefined
@@ -864,6 +939,24 @@ async function ensureTeleptyBusSubscriber() {
   return result;
 }
 
+async function callBrainIngest(executionContract) {
+  if (!executionContract) return { ok: false, reason: "no_contract" };
+  try {
+    const inboxDir = path.join(os.homedir(), ".aigentry", "inbox");
+    if (!fs.existsSync(inboxDir)) {
+      fs.mkdirSync(inboxDir, { recursive: true });
+    }
+    const fileName = `handoff-${executionContract.deliberation_id}.json`;
+    const filePath = path.join(inboxDir, fileName);
+    fs.writeFileSync(filePath, JSON.stringify(executionContract, null, 2), "utf8");
+    appendRuntimeLog("INFO", `BRAIN_INGEST: wrote handoff file ${filePath}`);
+    return { ok: true, path: filePath };
+  } catch (err) {
+    appendRuntimeLog("WARN", `BRAIN_INGEST: failed to write handoff file: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}
+
 async function notifyTeleptyBus(event) {
   const host = process.env.TELEPTY_HOST || "localhost";
   const port = process.env.TELEPTY_PORT || "3848";
@@ -889,6 +982,130 @@ async function notifyTeleptyBus(event) {
   }
 }
 
+function getDefaultOrchestratorSessionId() {
+  // Check multiple env vars that may indicate an orchestrator context
+  const candidates = [
+    process.env.TELEPTY_SESSION_ID,
+    process.env.DELIBERATION_ORCHESTRATOR_ID,
+    process.env.ORCHESTRATOR_SESSION_ID,
+  ];
+  for (const value of candidates) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+function buildTurnCompletionNotificationText(state, entry) {
+  const nextSpeaker = state.current_speaker || "none";
+  const turnId = entry.turn_id || "(none)";
+  if (state.status === "awaiting_synthesis") {
+    return [
+      `[deliberation turn complete]`,
+      `session_id: ${state.id}`,
+      `speaker: ${entry.speaker}`,
+      `turn_id: ${turnId}`,
+      `round: ${entry.round}/${state.max_rounds}`,
+      `status: awaiting_synthesis`,
+      `responses: ${state.log.length}`,
+      `all rounds complete; run deliberation_synthesize(session_id: "${state.id}")`,
+      `no further reply needed.`,
+    ].join("\n");
+  }
+
+  return [
+    `[deliberation turn complete]`,
+    `session_id: ${state.id}`,
+    `speaker: ${entry.speaker}`,
+    `turn_id: ${turnId}`,
+    `round: ${entry.round}/${state.max_rounds}`,
+    `status: ${state.status}`,
+    `next_speaker: ${nextSpeaker}`,
+    `next_round: ${state.current_round}/${state.max_rounds}`,
+    `responses: ${state.log.length}`,
+    `informational notification only.`,
+    `no further reply needed.`,
+  ].join("\n");
+}
+
+async function notifyTeleptySessionInject({ targetSessionId, prompt, fromSessionId, replyToSessionId = null, host = TELEPTY_DEFAULT_HOST }) {
+  if (!targetSessionId || !prompt) return { ok: false, error: "missing target or prompt" };
+  const token = loadTeleptyAuthToken();
+  if (!token) return { ok: false, error: "telepty auth token unavailable" };
+
+  try {
+    const response = await fetch(`http://${host}:${TELEPTY_PORT}/api/sessions/${encodeURIComponent(targetSessionId)}/inject`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-telepty-token": token,
+      },
+      body: JSON.stringify({
+        prompt,
+        from: fromSessionId || null,
+        reply_to: replyToSessionId || null,
+        deliberation_session_id: null,
+        thread_id: null,
+      }),
+    });
+    const data = await response.json().catch(() => null);
+    if (!response.ok) {
+      return { ok: false, error: data?.error || `HTTP ${response.status}` };
+    }
+    return { ok: true, inject_id: data?.inject_id || null };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err) };
+  }
+}
+
+async function dispatchTeleptyTurnRequest({ state, speaker, prompt = null, includeHistoryEntries = 4, awaitSemantic = false }) {
+  const { profile } = resolveTransportForSpeaker(state, speaker);
+  const turnId = state.pending_turn_id || generateTurnId();
+  const turnPrompt = buildClipboardTurnPrompt(state, speaker, prompt, includeHistoryEntries);
+  const busReady = await ensureTeleptyBusSubscriber();
+  const envelope = buildTeleptyTurnRequestEnvelope({
+    state,
+    speaker,
+    turnId,
+    turnPrompt,
+    includeHistoryEntries,
+    profile,
+  });
+  const pending = registerPendingTeleptyTurnRequest({ envelope, profile, speaker });
+  const publishResult = await notifyTeleptyBus(envelope);
+  const health = profile?.telepty_session_id ? getTeleptySessionHealth(profile.telepty_session_id) : null;
+
+  if (!publishResult.ok) {
+    cleanupPendingTeleptyTurn(envelope.message_id);
+    return {
+      ok: false,
+      stage: "publish",
+      envelope,
+      turnPrompt,
+      publishResult,
+      busReady,
+      health,
+    };
+  }
+
+  const transportResult = await pending.transportPromise;
+  let semanticResult = null;
+  if (awaitSemantic && transportResult.ok) {
+    semanticResult = await pending.semanticPromise;
+  }
+
+  return {
+    ok: !awaitSemantic ? transportResult.ok : Boolean(semanticResult?.ok),
+    stage: awaitSemantic ? (semanticResult?.ok ? "semantic" : (semanticResult?.code || "semantic_timeout")) : (transportResult.ok ? "transport" : (transportResult?.code || "transport_timeout")),
+    envelope,
+    turnPrompt,
+    publishResult,
+    transportResult,
+    semanticResult,
+    busReady,
+    health,
+  };
+}
+
 function getArchiveDir(projectSlug = getProjectSlug()) {
   const slug = normalizeProjectSlug(projectSlug);
   const obsidianDir = path.join(OBSIDIAN_PROJECTS, slug, "deliberations");
@@ -1435,19 +1652,27 @@ function detectCallerSpeaker() {
   const hinted = normalizeSpeaker(process.env.DELIBERATION_CALLER_SPEAKER);
   if (hinted) return hinted;
 
+  const envKeys = Object.keys(process.env).join(" ");
   const pathHint = process.env.PATH || "";
-  if (/\bCODEX_[A-Z0-9_]+\b/.test(Object.keys(process.env).join(" "))) {
-    return "codex";
-  }
-  if (pathHint.includes("/.codex/")) {
+
+  // Codex detection
+  if (/\bCODEX_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/.codex/")) {
     return "codex";
   }
 
-  if (/\bCLAUDE_[A-Z0-9_]+\b/.test(Object.keys(process.env).join(" "))) {
+  // Claude detection
+  if (/\bCLAUDE_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/.claude/")) {
     return "claude";
   }
-  if (pathHint.includes("/.claude/")) {
-    return "claude";
+
+  // Gemini detection
+  if (/\bGOOGLE_GENAI_[A-Z0-9_]+\b/.test(envKeys) || /\bGEMINI_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/.gemini/")) {
+    return "gemini";
+  }
+
+  // Aider detection
+  if (/\bAIDER_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/aider/")) {
+    return "aider";
   }
 
   return null;
@@ -2582,6 +2807,20 @@ function cleanupSyncMarkdown(state) {
   try { fs.unlinkSync(cwdPath); } catch { /* ignore */ }
 }
 
+function formatSourceMetadataLine(meta) {
+  if (!meta || typeof meta !== "object") return "";
+  const parts = [];
+  if (meta.source_machine_id) parts.push(`machine: ${meta.source_machine_id}`);
+  if (meta.source_session_id) parts.push(`session: ${meta.source_session_id}`);
+  if (meta.transport_scope) parts.push(`transport: ${meta.transport_scope}`);
+  if (meta.reply_origin) parts.push(`origin: ${meta.reply_origin}`);
+  if (meta.timestamp) parts.push(`timestamp: ${meta.timestamp}`);
+  if (Array.isArray(meta.artifact_refs) && meta.artifact_refs.length > 0) {
+    parts.push(`artifacts: ${meta.artifact_refs.join(", ")}`);
+  }
+  return parts.length > 0 ? `> _source: ${parts.join(" | ")}_\n\n` : "";
+}
+
 function stateToMarkdown(s) {
   const speakerOrder = buildSpeakerOrder(s.speakers, s.current_speaker, "end");
   let md = `---
@@ -2628,6 +2867,7 @@ tags: [deliberation]
       if (entry.fallback_reason) parts.push(`fallback: ${entry.fallback_reason}`);
       md += `> _${parts.join(" | ")}_\n\n`;
     }
+    md += formatSourceMetadataLine(entry.source_metadata);
     md += `${entry.content}\n\n`;
     if (entry.attachments && entry.attachments.length > 0) {
       for (const att of entry.attachments) {
@@ -2651,6 +2891,21 @@ function archiveState(state) {
   const filename = `deliberation-${ts}-${slug}.md`;
   const dest = path.join(getArchiveDir(state.project), filename);
   writeTextAtomic(dest, stateToMarkdown(state));
+
+  // Write machine-readable execution_contract sidecar for automation consumers
+  if (state.execution_contract) {
+    const contractDest = dest.replace(/\.md$/, ".contract.json");
+    writeTextAtomic(contractDest, JSON.stringify({
+      ...state.execution_contract,
+      _meta: {
+        archived_from: state.id,
+        project: state.project,
+        topic: state.topic,
+        archived_at: new Date().toISOString(),
+      },
+    }, null, 2));
+  }
+
   return dest;
 }
 
@@ -3296,6 +3551,21 @@ function buildCliAutoTurnFailureText({ state, speaker, hint, err, effectiveTimeo
   );
 }
 
+function buildActiveReportingSection(state, speaker) {
+  const orchestratorSessionId = state?.orchestrator_session_id;
+  if (!orchestratorSessionId) return "";
+
+  return `\n[active_reporting_rule]
+- After you successfully submit this turn with \`deliberation_respond(...)\`, send a brief status update to the orchestrator session.
+- Primary method (telepty available):
+\`telepty inject --from \"$TELEPTY_SESSION_ID\" --reply-to ${orchestratorSessionId} ${orchestratorSessionId} \"[deliberation status] session_id: ${state.id} speaker: ${speaker} round: ${state.current_round}/${state.max_rounds} submitted. no further reply needed.\"\`
+- Fallback (telepty unavailable): Include the status in your next tool call or response context.
+- Keep it to one short line. Do not wait for a reply.
+- This rule applies regardless of transport type (CLI, browser, telepty_bus).
+[/active_reporting_rule]
+`;
+}
+
 function buildClipboardTurnPrompt(state, speaker, prompt, includeHistoryEntries = 4) {
   const promptBudget = getPromptBudgetForSpeaker(speaker, includeHistoryEntries);
   const recent = formatRecentLogForPrompt(state, promptBudget.maxEntries, promptBudget);
@@ -3304,6 +3574,7 @@ function buildClipboardTurnPrompt(state, speaker, prompt, includeHistoryEntries
   const noToolRule = speaker === "codex"
     ? `\n- Do not inspect files, run shell commands, browse, or call tools. Answer only from the provided discussion context.`
     : "";
+  const activeReportingSection = buildActiveReportingSection(state, speaker);
 
   // Role prompt injection
   const speakerRole = (state.speaker_roles || {})[speaker] || "free";
@@ -3318,7 +3589,7 @@ project: ${state.project}
 topic: ${topic}
 round: ${state.current_round}/${state.max_rounds}
 target_speaker: ${speaker}
-required_turn: ${state.current_speaker}${roleSection}
+required_turn: ${state.current_speaker}${roleSection}${activeReportingSection}
 
 [recent_log]
 ${recent}
@@ -3334,7 +3605,7 @@ ${recent}
 `;
 }
 
-function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel_used, fallback_reason, attachments }) {
+function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel_used, fallback_reason, attachments, source_metadata }) {
   const resolved = resolveSessionId(session_id);
   if (!resolved) {
     return { content: [{ type: "text", text: t("No active deliberation.", "활성 deliberation이 없습니다.", "en") }] };
@@ -3343,7 +3614,9 @@ function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel
     return { content: [{ type: "text", text: multipleSessionsError() }] };
   }
 
-  return withSessionLock(resolved, () => {
+  let completionState = null;
+  let completionEntry = null;
+  const result = withSessionLock(resolved, () => {
     const state = loadSession(resolved);
     if (!state || state.status !== "active") {
       return { content: [{ type: "text", text: t(`Session "${resolved}" is not active.`, `세션 "${resolved}"이 활성 상태가 아닙니다.`, "en") }] };
@@ -3388,7 +3661,7 @@ function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel
     const suggestedRole = inferSuggestedRole(content);
     const assignedRole = (state.speaker_roles || {})[normalizedSpeaker] || "free";
     const roleDrift = assignedRole !== "free" && suggestedRole !== "free" && assignedRole !== suggestedRole;
-    state.log.push({
+    const logEntry = {
       round: state.current_round,
       speaker: normalizedSpeaker,
       content,
@@ -3400,13 +3673,15 @@ function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel
       suggested_next_role: suggestedRole !== "free" ? suggestedRole : undefined,
       role_drift: roleDrift || undefined,
       attachments: attachments || undefined,
-    });
+      source_metadata: source_metadata || undefined,
+    };
+    state.log.push(logEntry);
     completePendingTeleptySemantic({
       sessionId: state.id,
       speaker: normalizedSpeaker,
       turnId: state.pending_turn_id || turn_id || null,
     });
-    appendRuntimeLog("INFO", `TURN: ${state.id} | R${state.current_round} | speaker: ${normalizedSpeaker} | votes: ${votes.length > 0 ? votes.map(v => v.vote).join(",") : "none"} | channel: ${channel_used || "respond"} | attachments: ${attachments ? attachments.length : 0}`);
+    appendRuntimeLog("INFO", `TURN: ${state.id} | R${state.current_round} | speaker: ${normalizedSpeaker} | votes: ${votes.length > 0 ? votes.map(v => v.vote).join(",") : "none"} | channel: ${channel_used || "respond"} | attachments: ${attachments ? attachments.length : 0}${source_metadata?.source_machine_id ? ` | source_machine: ${source_metadata.source_machine_id}` : ""}`);
 
     state.current_speaker = selectNextSpeaker(state);
 
@@ -3434,6 +3709,17 @@ function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel
       state.pending_turn_id = generateTurnId();
     }
 
+    if (!state.orchestrator_session_id) {
+      state.orchestrator_session_id = getDefaultOrchestratorSessionId() || null;
+    }
+    completionEntry = {
+      ...logEntry,
+      turn_id: logEntry.turn_id || turn_id || null,
+    };
+    completionState = {
+      ...state,
+      log: [...state.log],
+    };
     saveSession(state);
     return {
       content: [{
@@ -3442,6 +3728,23 @@ function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel
       }],
     };
   });
+
+  if (completionState && completionEntry) {
+    const envelope = buildTeleptyTurnCompletedEnvelope({ state: completionState, entry: completionEntry });
+    notifyTeleptyBus(envelope).catch(() => {});
+
+    const orchestratorSessionId = completionState.orchestrator_session_id || null;
+    if (orchestratorSessionId) {
+      const notificationText = buildTurnCompletionNotificationText(completionState, completionEntry);
+      notifyTeleptySessionInject({
+        targetSessionId: orchestratorSessionId,
+        prompt: notificationText,
+        fromSessionId: `deliberation:${completionState.id}`,
+      }).catch(() => {});
+    }
+  }
+
+  return result;
 }
 
 // ── MCP Server ─────────────────────────────────────────────────
@@ -3525,8 +3828,11 @@ server.tool(
       (v) => (typeof v === "string" ? v === "true" : v),
       z.boolean().optional()
     ).describe("If true, automatically create a handoff task in the inbox when synthesis completes. Enables the Autonomous Deliberation Handoff pattern."),
-    },
-    safeToolHandler("deliberation_start", async ({ topic, session_id, rounds, first_speaker, selection_token, speakers, speaker_instructions, require_manual_speakers, auto_discover_speakers, include_browser_speakers, participant_types, ordering_strategy, speaker_roles, role_preset, auto_execute }) => {
+    mode: z.enum(["standard", "lite"]).default("standard").describe("Deliberation mode. 'lite' caps speakers to 3 and rounds to 2 for quick decisions."),
+    orchestrator_session_id: z.string().trim().min(1).max(128).optional()
+      .describe("Optional telepty session ID to notify on turn completion. Defaults to TELEPTY_SESSION_ID when available."),
+  },
+  safeToolHandler("deliberation_start", async ({ topic, session_id, rounds, first_speaker, selection_token, speakers, speaker_instructions, require_manual_speakers, auto_discover_speakers, include_browser_speakers, participant_types, ordering_strategy, speaker_roles, role_preset, auto_execute, mode, orchestrator_session_id }) => {
     // ── First-time onboarding guard ──
     const config = loadDeliberationConfig();
     if (!config.setup_complete) {
@@ -3649,12 +3955,22 @@ server.tool(
       || normalizeSpeaker(hasManualSpeakers ? selectedSpeakers?.[0] : callerSpeaker)
       || normalizeSpeaker(selectedSpeakers?.[0])
       || DEFAULT_SPEAKERS[0];
-    const speakerOrder = buildSpeakerOrder(selectedSpeakers, normalizedFirstSpeaker, "front");
+    let speakerOrder = buildSpeakerOrder(selectedSpeakers, normalizedFirstSpeaker, "front");
 
     if (effectiveRequireManual) {
       clearSpeakerSelectionToken();
     }
 
+    // Lite mode: cap speakers and rounds for quick decisions
+    if (mode === "lite") {
+      if (speakerOrder.length > 3) {
+        speakerOrder.splice(3);
+      }
+      if (rounds > 2) {
+        rounds = 2;
+      }
+    }
+
     // Warn if only 1 speaker — deliberation requires 2+
     if (speakerOrder.length < 2) {
       const candidateText = formatSpeakerCandidatesReport(candidateSnapshot);
@@ -3706,6 +4022,8 @@ server.tool(
       speaker_roles: speaker_roles || (role_preset ? applyRolePreset(role_preset, speakerOrder) : {}),
       degradation: degradationLevels,
       auto_execute: auto_execute || false,
+      mode: mode || "standard",
+      orchestrator_session_id: orchestrator_session_id || getDefaultOrchestratorSessionId() || null,
       created: new Date().toISOString(),
       updated: new Date().toISOString(),
     };
@@ -3994,28 +4312,22 @@ server.tool(
     let manualFallbackPrompt = false;
 
     if (transport === "telepty_bus") {
-      turnPrompt = buildClipboardTurnPrompt(state, speaker, prompt, include_history_entries);
-      const busReady = await ensureTeleptyBusSubscriber();
-      const envelope = buildTeleptyTurnRequestEnvelope({
+      const dispatchResult = await dispatchTeleptyTurnRequest({
         state,
         speaker,
-        turnId: turnId || generateTurnId(),
-        turnPrompt,
+        prompt,
         includeHistoryEntries: include_history_entries,
-        profile,
+        awaitSemantic: false,
       });
-      const pending = registerPendingTeleptyTurnRequest({ envelope, profile, speaker });
-      const publishResult = await notifyTeleptyBus(envelope);
-      const health = profile?.telepty_session_id ? getTeleptySessionHealth(profile.telepty_session_id) : null;
+      turnPrompt = dispatchResult.turnPrompt;
+      const { envelope, publishResult, transportResult, busReady, health } = dispatchResult;
 
-      if (!publishResult.ok) {
-        cleanupPendingTeleptyTurn(envelope.message_id);
+      if (!dispatchResult.ok && dispatchResult.stage === "publish") {
         manualFallbackPrompt = true;
         extra += `\n\n❌ Telepty bus publish failed: ${publishResult.error || publishResult.status || "unknown error"}\n` +
                  `Fallback: use manual telepty inject for this turn.`;
         guidance = formatTransportGuidance("manual", state, speaker);
       } else {
-        const transportResult = await pending.transportPromise;
         const healthLine = health
           ? `\n**Session health:** alive=${health.payload?.alive === true ? "yes" : "no"}, pid=${health.payload?.pid || "n/a"}, age=${Math.max(0, Math.round((health.age_ms || 0) / 1000))}s${health.stale ? " (stale)" : ""}`
           : "";
@@ -4360,6 +4672,226 @@ async function runCliAutoTurnCore(sessionId, speaker, timeoutSec = 120) {
   }
 }
 
+async function runBrowserAutoTurnCore(sessionId, speaker, timeoutSec = 45) {
+  const state = loadSession(sessionId);
+  if (!state || state.status !== "active") {
+    return { ok: false, error: "Session not active" };
+  }
+
+  const { transport, profile } = resolveTransportForSpeaker(state, speaker);
+  if (transport !== "browser_auto") {
+    return { ok: false, error: `Speaker "${speaker}" is not browser_auto type` };
+  }
+
+  const turnId = state.pending_turn_id || generateTurnId();
+  const port = getBrowserPort();
+  const effectiveProvider = profile?.provider || "chatgpt";
+  const modelSelection = getModelSelectionForTurn(state, speaker, effectiveProvider);
+  const turnPrompt = buildClipboardTurnPrompt(state, speaker, null, 3);
+  const startTime = Date.now();
+
+  try {
+    const attachResult = await port.attach(sessionId, {
+      provider: effectiveProvider,
+      url: profile?.url || undefined,
+    });
+    if (!attachResult.ok) {
+      return { ok: false, error: `attach failed: ${attachResult.error?.message || "unknown error"}` };
+    }
+
+    const loginCheck = await port.checkLogin(sessionId);
+    if (loginCheck && !loginCheck.loggedIn) {
+      await port.detach(sessionId);
+      return { ok: false, error: `login required: ${loginCheck.reason || "not logged in"}` };
+    }
+
+    if (modelSelection.model !== "default") {
+      await port.switchModel(sessionId, modelSelection.model);
+    }
+
+    const sendResult = await port.sendTurnWithDegradation(sessionId, turnId, turnPrompt);
+    if (!sendResult.ok) {
+      await port.detach(sessionId);
+      return { ok: false, error: `send failed: ${sendResult.error?.message || "unknown error"}` };
+    }
+
+    const waitResult = await port.waitTurnResult(sessionId, turnId, timeoutSec);
+    await port.detach(sessionId);
+    if (!waitResult.ok || !waitResult.data?.response) {
+      return { ok: false, error: waitResult.error?.message || "no response received" };
+    }
+
+    submitDeliberationTurn({
+      session_id: sessionId,
+      speaker,
+      content: waitResult.data.response,
+      turn_id: turnId,
+      channel_used: "browser_auto",
+    });
+
+    return {
+      ok: true,
+      response: waitResult.data.response,
+      elapsedMs: Date.now() - startTime,
+      model: modelSelection.model,
+      provider: effectiveProvider,
+    };
+  } catch (err) {
+    try { await port.detach(sessionId); } catch {}
+    return { ok: false, error: err?.message || String(err) };
+  }
+}
+
+async function runTeleptyBusAutoTurnCore(sessionId, speaker, includeHistoryEntries = 4) {
+  const state = loadSession(sessionId);
+  if (!state || state.status !== "active") {
+    return { ok: false, error: "Session not active" };
+  }
+
+  const { transport } = resolveTransportForSpeaker(state, speaker);
+  if (transport !== "telepty_bus") {
+    return { ok: false, error: `Speaker "${speaker}" is not telepty_bus type` };
+  }
+
+  const startTime = Date.now();
+  const dispatchResult = await dispatchTeleptyTurnRequest({
+    state,
+    speaker,
+    includeHistoryEntries,
+    awaitSemantic: true,
+  });
+  if (!dispatchResult.publishResult?.ok) {
+    return {
+      ok: false,
+      blocked: true,
+      error: dispatchResult.publishResult?.error || dispatchResult.publishResult?.status || "telepty bus publish failed",
+      envelope: dispatchResult.envelope,
+      turnPrompt: dispatchResult.turnPrompt,
+    };
+  }
+  if (!dispatchResult.transportResult?.ok) {
+    return {
+      ok: false,
+      blocked: true,
+      error: dispatchResult.transportResult?.code || "transport timeout",
+      envelope: dispatchResult.envelope,
+      turnPrompt: dispatchResult.turnPrompt,
+    };
+  }
+  if (!dispatchResult.semanticResult?.ok) {
+    return {
+      ok: false,
+      blocked: true,
+      error: dispatchResult.semanticResult?.code || "semantic timeout",
+      envelope: dispatchResult.envelope,
+      turnPrompt: dispatchResult.turnPrompt,
+    };
+  }
+
+  return {
+    ok: true,
+    elapsedMs: Date.now() - startTime,
+    envelope: dispatchResult.envelope,
+    publishResult: dispatchResult.publishResult,
+    transportResult: dispatchResult.transportResult,
+    semanticResult: dispatchResult.semanticResult,
+  };
+}
+
+async function runUntilBlockedCore(sessionId, {
+  maxTurns = 12,
+  cliTimeoutSec = 120,
+  browserTimeoutSec = 45,
+  includeHistoryEntries = 4,
+} = {}) {
+  const steps = [];
+
+  for (let iteration = 0; iteration < maxTurns; iteration += 1) {
+    const state = loadSession(sessionId);
+    if (!state) {
+      return { ok: false, status: "missing", error: "Session not found", steps };
+    }
+    if (state.status !== "active" || state.current_speaker === "none") {
+      return { ok: true, status: state.status, steps };
+    }
+
+    const speaker = state.current_speaker;
+    const { transport } = resolveTransportForSpeaker(state, speaker);
+    const callerSpeaker = detectCallerSpeaker();
+    if (transport === "cli_respond" && callerSpeaker && normalizeSpeaker(callerSpeaker) === normalizeSpeaker(speaker)) {
+      return {
+        ok: true,
+        status: "blocked",
+        block_reason: "self_turn",
+        speaker,
+        transport,
+        turn_prompt: buildClipboardTurnPrompt(state, speaker, null, includeHistoryEntries),
+        steps,
+      };
+    }
+
+    if (transport === "manual" || transport === "clipboard") {
+      return {
+        ok: true,
+        status: "blocked",
+        block_reason: "manual_transport",
+        speaker,
+        transport,
+        turn_prompt: buildClipboardTurnPrompt(state, speaker, null, includeHistoryEntries),
+        steps,
+      };
+    }
+
+    let result = null;
+    if (transport === "cli_respond") {
+      result = await runCliAutoTurnCore(sessionId, speaker, cliTimeoutSec);
+    } else if (transport === "browser_auto") {
+      result = await runBrowserAutoTurnCore(sessionId, speaker, browserTimeoutSec);
+    } else if (transport === "telepty_bus") {
+      result = await runTeleptyBusAutoTurnCore(sessionId, speaker, includeHistoryEntries);
+    } else {
+      return {
+        ok: true,
+        status: "blocked",
+        block_reason: "unsupported_transport",
+        speaker,
+        transport,
+        turn_prompt: buildClipboardTurnPrompt(state, speaker, null, includeHistoryEntries),
+        steps,
+      };
+    }
+
+    steps.push({
+      speaker,
+      transport,
+      ok: Boolean(result?.ok),
+      error: result?.error || null,
+      elapsedMs: result?.elapsedMs || null,
+      blocked: Boolean(result?.blocked),
+    });
+
+    if (!result?.ok) {
+      return {
+        ok: Boolean(result?.blocked),
+        status: result?.blocked ? "blocked" : "error",
+        block_reason: result?.blocked ? (result.error || "transport_blocked") : null,
+        speaker,
+        transport,
+        error: result?.error || null,
+        turn_prompt: result?.turnPrompt || null,
+        steps,
+      };
+    }
+  }
+
+  const finalState = loadSession(sessionId);
+  return {
+    ok: true,
+    status: finalState?.status === "active" ? "max_turns_reached" : (finalState?.status || "completed"),
+    steps,
+  };
+}
+
 /**
  * Generate structured synthesis by calling a CLI speaker with a synthesis prompt.
  */
@@ -4481,27 +5013,14 @@ async function runAutoHandoff(sessionId) {
 
       appendRuntimeLog("INFO", `AUTO_HANDOFF_TURN: ${sessionId} | speaker: ${speaker} | round: ${state.current_round}/${state.max_rounds}`);
 
-      const result = await runCliAutoTurnCore(sessionId, speaker);
-      if (!result.ok) {
-        appendRuntimeLog("WARN", `AUTO_HANDOFF_TURN_FAIL: ${sessionId} | speaker: ${speaker} | ${result.error}`);
-        // Skip this speaker, continue with next
-        const freshState = loadSession(sessionId);
-        if (freshState) {
-          // Advance to next speaker manually
-          const idx = freshState.speakers.indexOf(speaker);
-          const nextIdx = (idx + 1) % freshState.speakers.length;
-          freshState.current_speaker = freshState.speakers[nextIdx];
-          if (nextIdx === 0) freshState.current_round++;
-          if (freshState.current_round > freshState.max_rounds) {
-            freshState.status = "awaiting_synthesis";
-            freshState.current_speaker = "none";
-          }
-          saveSession(freshState);
-        }
-        continue;
+      const runResult = await runUntilBlockedCore(sessionId, { maxTurns: 1, includeHistoryEntries: 3 });
+      const step = runResult.steps.at(-1) || null;
+      if (!runResult.ok || runResult.status === "blocked") {
+        appendRuntimeLog("WARN", `AUTO_HANDOFF_TURN_BLOCKED: ${sessionId} | speaker: ${speaker} | ${runResult.block_reason || runResult.error || "unknown"}`);
+        break;
       }
 
-      appendRuntimeLog("INFO", `AUTO_HANDOFF_TURN_OK: ${sessionId} | speaker: ${speaker} | ${result.elapsedMs}ms`);
+      appendRuntimeLog("INFO", `AUTO_HANDOFF_TURN_OK: ${sessionId} | speaker: ${speaker} | ${step?.elapsedMs || 0}ms`);
     }
 
     // Phase 2: Generate structured synthesis
@@ -4797,6 +5316,56 @@ server.tool(
   })
 );
 
+server.tool(
+  "deliberation_run_until_blocked",
+  "Auto-run a deliberation across mixed transports until it completes or reaches a manual/blocking turn.",
+  {
+    session_id: z.string().optional().describe("Session ID (required if multiple sessions are active)"),
+    max_turns: z.number().int().min(1).max(50).default(12).describe("Maximum number of turns to auto-run before stopping"),
+    cli_timeout_sec: z.number().int().min(30).max(900).default(120).describe("CLI auto-turn timeout (seconds)"),
+    browser_timeout_sec: z.number().int().min(15).max(300).default(45).describe("Browser auto-turn timeout (seconds)"),
+    include_history_entries: z.number().int().min(0).max(12).default(4).describe("Recent log entries to include for telepty turns"),
+  },
+  safeToolHandler("deliberation_run_until_blocked", async ({ session_id, max_turns, cli_timeout_sec, browser_timeout_sec, include_history_entries }) => {
+    const resolved = resolveSessionId(session_id);
+    if (!resolved) {
+      return { content: [{ type: "text", text: t("No active deliberation.", "활성 deliberation이 없습니다.", "en") }] };
+    }
+    if (resolved === "MULTIPLE") {
+      return { content: [{ type: "text", text: multipleSessionsError() }] };
+    }
+
+    const initialState = loadSession(resolved);
+    if (!initialState || initialState.status !== "active") {
+      return { content: [{ type: "text", text: t(`Session "${resolved}" is not active.`, `세션 "${resolved}"이 활성 상태가 아닙니다.`, "en") }] };
+    }
+
+    const result = await runUntilBlockedCore(resolved, {
+      maxTurns: max_turns,
+      cliTimeoutSec: cli_timeout_sec,
+      browserTimeoutSec: browser_timeout_sec,
+      includeHistoryEntries: include_history_entries,
+    });
+    const finalState = loadSession(resolved);
+    const stepsText = (result.steps || []).length > 0
+      ? result.steps.map((step, index) => `- ${index + 1}. ${step.speaker} [${step.transport}] → ${step.ok ? "ok" : (step.blocked ? `blocked (${step.error || "blocked"})` : `error (${step.error || "unknown"})`)}${step.elapsedMs ? ` (${step.elapsedMs}ms)` : ""}`).join("\n")
+      : "- none";
+
+    let summary = `## Run Until Blocked — ${resolved}\n\n`;
+    summary += `**Result:** ${result.status}\n`;
+    summary += `**Current state:** ${finalState?.status || initialState.status}\n`;
+    summary += `**Current speaker:** ${finalState?.current_speaker || initialState.current_speaker}\n`;
+    if (result.block_reason) summary += `**Block reason:** ${result.block_reason}\n`;
+    if (result.error) summary += `**Error:** ${result.error}\n`;
+    if (result.turn_prompt) {
+      summary += `\n### [turn_prompt]\n\`\`\`markdown\n${result.turn_prompt}\n\`\`\`\n`;
+    }
+    summary += `\n### Steps\n${stepsText}\n`;
+
+    return { content: [{ type: "text", text: summary }] };
+  })
+);
+
 server.tool(
   "deliberation_respond",
   "Submit a response for the current turn.",
@@ -4880,6 +5449,51 @@ server.tool(
   })
 );
 
+server.tool(
+  "deliberation_ingest_remote_reply",
+  "Canonical semantic ingress for replies produced on another machine/session. Use this instead of reconstructing deliberation state from transport events.",
+  {
+    session_id: z.string().describe("Deliberation session ID"),
+    speaker: z.string().describe("Speaker name"),
+    turn_id: z.string().min(1).describe("Turn ID associated with the issued turn_request"),
+    content: z.string().min(1).describe("Remote reply content"),
+    source_machine_id: z.string().min(1).describe("Source machine or peer identifier"),
+    source_session_id: z.string().min(1).describe("Source remote session identifier"),
+    transport_scope: z.string().min(1).describe("Transport scope used to carry the remote reply"),
+    artifact_refs: z.array(z.string().min(1)).optional().describe("Optional artifact references the reply depends on"),
+    reply_origin: z.string().optional().describe("Optional origin hint, e.g. remote_mcp, telepty_thread"),
+    timestamp: z.string().optional().describe("Optional source timestamp"),
+  },
+  safeToolHandler("deliberation_ingest_remote_reply", async ({
+    session_id,
+    speaker,
+    turn_id,
+    content,
+    source_machine_id,
+    source_session_id,
+    transport_scope,
+    artifact_refs,
+    reply_origin,
+    timestamp,
+  }) => {
+    return submitDeliberationTurn({
+      session_id,
+      speaker,
+      content,
+      turn_id,
+      channel_used: `remote_ingress:${transport_scope}`,
+      source_metadata: {
+        source_machine_id,
+        source_session_id,
+        transport_scope,
+        artifact_refs: artifact_refs || [],
+        reply_origin: reply_origin || null,
+        timestamp: timestamp || new Date().toISOString(),
+      },
+    });
+  })
+);
+
 server.tool(
   "deliberation_list_remote_sessions",
   "List all active deliberation sessions on a remote machine (via Tailscale/IP) to find the correct session_id for context injection.",
@@ -5118,6 +5732,9 @@ server.tool(
       notifyTeleptyBus(synthesisEnvelope).catch(() => {}); // fire-and-forget
     }
 
+    // Notify brain ingest if endpoint configured
+    callBrainIngest(state.execution_contract).catch(() => {}); // fire-and-forget
+
     return {
       content: [{
         type: "text",
@@ -6102,4 +6719,4 @@ if (__entryFile && path.resolve(__currentFile) === __entryFile) {
 }
 
 // ── Test exports (used by vitest) ──
-export { selectNextSpeaker, loadRolePrompt, inferSuggestedRole, parseVotes, ROLE_KEYWORDS, ROLE_HEADING_MARKERS, loadRolePresets, applyRolePreset, detectDegradationLevels, formatDegradationReport, DEGRADATION_TIERS, DECISION_STAGES, STAGE_TRANSITIONS, createDecisionSession, advanceStage, buildConflictMap, parseOpinionFromResponse, buildOpinionPrompt, generateConflictQuestions, buildSynthesis, buildActionPlan, loadTemplates, matchTemplate, hasExplicitBrowserParticipantSelection, resolveIncludeBrowserSpeakers, confirmSpeakerSelectionToken, validateSpeakerSelectionRequest, truncatePromptText, getPromptBudgetForSpeaker, formatRecentLogForPrompt, getCliAutoTurnTimeoutSec, getCliExecArgs, buildCliAutoTurnFailureText, buildClipboardTurnPrompt, getProjectStateDir, loadSession, saveSession, listActiveSessions, multipleSessionsError, findSessionRecord, mapParticipantProfiles, formatSpeakerCandidatesReport, buildTeleptyTurnRequestEnvelope, buildTeleptySynthesisEnvelope, validateTeleptyEnvelope, registerPendingTeleptyTurnRequest, handleTeleptyBusMessage, completePendingTeleptySemantic, cleanupPendingTeleptyTurn, getTeleptySessionHealth, TELEPTY_TRANSPORT_TIMEOUT_MS, TELEPTY_SEMANTIC_TIMEOUT_MS };
+export { selectNextSpeaker, loadRolePrompt, inferSuggestedRole, parseVotes, ROLE_KEYWORDS, ROLE_HEADING_MARKERS, loadRolePresets, applyRolePreset, detectDegradationLevels, formatDegradationReport, DEGRADATION_TIERS, DECISION_STAGES, STAGE_TRANSITIONS, createDecisionSession, advanceStage, buildConflictMap, parseOpinionFromResponse, buildOpinionPrompt, generateConflictQuestions, buildSynthesis, buildActionPlan, loadTemplates, matchTemplate, hasExplicitBrowserParticipantSelection, resolveIncludeBrowserSpeakers, confirmSpeakerSelectionToken, validateSpeakerSelectionRequest, truncatePromptText, getPromptBudgetForSpeaker, formatRecentLogForPrompt, getCliAutoTurnTimeoutSec, getCliExecArgs, buildCliAutoTurnFailureText, buildClipboardTurnPrompt, getProjectStateDir, loadSession, saveSession, listActiveSessions, multipleSessionsError, findSessionRecord, mapParticipantProfiles, formatSpeakerCandidatesReport, buildTeleptyTurnRequestEnvelope, buildTeleptyTurnCompletedEnvelope, buildTeleptySynthesisEnvelope, validateTeleptyEnvelope, registerPendingTeleptyTurnRequest, handleTeleptyBusMessage, completePendingTeleptySemantic, cleanupPendingTeleptyTurn, getTeleptySessionHealth, TELEPTY_TRANSPORT_TIMEOUT_MS, TELEPTY_SEMANTIC_TIMEOUT_MS };

package/install.js

@@ -10,7 +10,7 @@
  * What it does:
  *   1. Copies server files to ~/.local/lib/mcp-deliberation/
  *   2. Installs npm dependencies
- *   3. Registers MCP server in ~/.claude/.mcp.json (Claude Code)
+ *   3. Registers MCP server via `claude mcp add` (Claude Code)
  *   4. Registers MCP server in ~/.gemini/settings.json (Gemini CLI)
  *   5. Ready to use — next Claude Code or Gemini CLI session will auto-load
  *   6. Installs skill file (~/.claude/skills/deliberation-gate/SKILL.md)
@@ -61,6 +61,15 @@ function log(msg) {
   console.log(`  ${msg}`);
 }
 
+function commandExists(cmd) {
+  try {
+    execSync(IS_WIN ? `where ${cmd}` : `command -v ${cmd}`, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function copyFileIfExists(src, dest) {
   if (fs.existsSync(src)) {
     fs.copyFileSync(src, dest);
@@ -121,32 +130,55 @@ function install() {
     log("   Manual fix: cd ~/.local/lib/mcp-deliberation && npm install");
   }
 
-  // Step 4: Register MCP server
+  // Step 4: Register MCP server (Claude Code)
   log("🔧 Registering Claude Code MCP server...");
-  const claudeDir = path.join(HOME, ".claude");
-  fs.mkdirSync(claudeDir, { recursive: true });
+  const serverEntryPoint = toForwardSlash(path.join(INSTALL_DIR, "index.js"));
+  let claudeRegistered = false;
 
-  let mcpConfig = {};
-  if (fs.existsSync(MCP_CONFIG)) {
+  // Prefer `claude mcp add` — this is the only method Claude Code reliably reads
+  if (commandExists("claude")) {
     try {
-      mcpConfig = JSON.parse(fs.readFileSync(MCP_CONFIG, "utf-8"));
-    } catch {
-      mcpConfig = {};
+      // Remove existing registration first (ignore errors if not registered)
+      try { execSync("claude mcp remove deliberation -s user", { stdio: "pipe" }); } catch { /* ok */ }
+      execSync(`claude mcp add deliberation -s user -- node "${serverEntryPoint}"`, {
+        stdio: "pipe",
+      });
+      log("   → Registered via 'claude mcp add' (user scope)");
+      claudeRegistered = true;
+    } catch (err) {
+      log(`   ⚠️ 'claude mcp add' failed: ${err.message}`);
     }
   }
 
-  if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+  // Fallback: write ~/.claude/.mcp.json (legacy, may not be read by Claude Code)
+  if (!claudeRegistered) {
+    const claudeDir = path.join(HOME, ".claude");
+    fs.mkdirSync(claudeDir, { recursive: true });
 
-  const alreadyRegistered = !!mcpConfig.mcpServers.deliberation;
-  mcpConfig.mcpServers.deliberation = {
-    command: "node",
-    args: [toForwardSlash(path.join(INSTALL_DIR, "index.js"))],
-  };
+    let mcpConfig = {};
+    if (fs.existsSync(MCP_CONFIG)) {
+      try {
+        mcpConfig = JSON.parse(fs.readFileSync(MCP_CONFIG, "utf-8"));
+      } catch {
+        mcpConfig = {};
+      }
+    }
+
+    if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+
+    const alreadyRegistered = !!mcpConfig.mcpServers.deliberation;
+    mcpConfig.mcpServers.deliberation = {
+      command: "node",
+      args: [serverEntryPoint],
+    };
 
-  fs.writeFileSync(MCP_CONFIG, JSON.stringify(mcpConfig, null, 2));
-  log(alreadyRegistered
-    ? "   → Existing registration updated"
-    : "   → Registered successfully");
+    fs.writeFileSync(MCP_CONFIG, JSON.stringify(mcpConfig, null, 2));
+    log(alreadyRegistered
+      ? "   → Fallback: existing registration updated in .mcp.json"
+      : "   → Fallback: registered in .mcp.json");
+    log("   ⚠️ Claude CLI not found. Run manually if server isn't detected:");
+    log(`     claude mcp add deliberation -s user -- node "${serverEntryPoint}"`);
+  }
 
   // Step 5: Register Gemini CLI MCP server
   log("🔧 Registering Gemini CLI MCP server...");
@@ -283,14 +315,24 @@ Skill path:   ${SKILL_DEST}
 } else if (args.includes("--uninstall") || args.includes("uninstall")) {
   console.log("\n🗑️ Deliberation MCP Server — Uninstalling\n");
 
-  // Remove from Claude MCP config
+  // Remove from Claude Code MCP registration
+  let claudeUnregistered = false;
+  if (commandExists("claude")) {
+    try {
+      execSync("claude mcp remove deliberation -s user", { stdio: "pipe" });
+      log("Claude Code MCP server unregistered via 'claude mcp remove'");
+      claudeUnregistered = true;
+    } catch { /* may not exist */ }
+  }
+
+  // Also clean up legacy .mcp.json fallback
   if (fs.existsSync(MCP_CONFIG)) {
     try {
       const mcpConfig = JSON.parse(fs.readFileSync(MCP_CONFIG, "utf-8"));
       if (mcpConfig.mcpServers?.deliberation) {
         delete mcpConfig.mcpServers.deliberation;
         fs.writeFileSync(MCP_CONFIG, JSON.stringify(mcpConfig, null, 2));
-        log("Claude Code MCP server unregistered");
+        if (!claudeUnregistered) log("Claude Code MCP server unregistered from .mcp.json");
       }
     } catch { /* ignore */ }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-deliberation",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "description": "MCP Deliberation Server — Multi-session AI deliberation with smart speaker ordering and persona roles",
   "type": "module",
   "license": "MIT",

package/skills/deliberation/SKILL.md

@@ -31,7 +31,9 @@ Claude/Codex를 포함해 MCP를 지원하는 임의 CLI들이 구조화된 토
 | `deliberation_context` | 프로젝트 컨텍스트 로드 | 불필요 |
 | `deliberation_browser_llm_tabs` | 브라우저 LLM 탭 목록 (웹 기반 LLM 참여용) | 불필요 |
 | `deliberation_route_turn` | 현재 차례 speaker의 transport(CLI/browser_auto/manual)를 자동 라우팅 | 선택적* |
+| `deliberation_run_until_blocked` | CLI/browser_auto/telepty_bus를 자동 진행하다 막히는 지점에서 중단 | 선택적 |
 | `deliberation_respond` | 현재 차례의 응답 제출 | 선택적* |
+| `deliberation_ingest_remote_reply` | 원격 머신 reply를 명시적 source metadata와 함께 semantic ingest | 선택적 |
 | `deliberation_history` | 전체 토론 기록 조회 | 선택적* |
 | `deliberation_synthesize` | 합성 보고서 생성 및 토론 완료 | 선택적* |
 | `deliberation_list` | 과거 토론 아카이브 목록 | 불필요 |
@@ -64,9 +66,11 @@ Claude/Codex를 포함해 MCP를 지원하는 임의 CLI들이 구조화된 토
    - CLI speaker → `deliberation_cli_auto_turn`으로 실제 CLI 실행
    - browser_auto → CDP로 자동 전송/수집
    - clipboard/manual → 클립보드 준비 + 사용자 안내
+   - 완전 자동으로 여러 턴을 밀고 싶으면 `deliberation_run_until_blocked`를 사용합니다. 이 도구는 `cli_respond`, `browser_auto`, `telepty_bus`를 연속 실행하고, 수동 transport 또는 self-turn에서 멈춥니다.
 3. **NEVER** — 오케스트레이터(자기 자신)가 다른 speaker를 대신하여 `deliberation_respond`에 응답을 작성하지 마세요. 이것은 "역할극"이며 실제 deliberation이 아닙니다. MCP 서버가 이를 감지하고 차단합니다.
 4. **NEVER** — `deliberation_respond`를 직접 호출하지 마세요 (자기 자신의 응답 제외). 다른 speaker의 턴은 반드시 `deliberation_route_turn` 또는 `deliberation_cli_auto_turn`/`deliberation_browser_auto_turn`을 통해 진행합니다.
 5. **MUST** — 자기 자신(오케스트레이터 역할의 claude)이 speaker인 경우에만 직접 `deliberation_respond`로 응답을 제출할 수 있습니다.
+6. **MUST** — 원격 머신/세션에서 들어온 응답을 semantic reply로 반영할 때는 raw bus event를 해석하지 말고 `deliberation_ingest_remote_reply`를 사용하세요. transport trace와 semantic ingest를 섞지 마세요.
 
 ## 워크플로우
 
@@ -95,7 +99,9 @@ Claude/Codex를 포함해 MCP를 지원하는 임의 CLI들이 구조화된 토
 5. **`deliberation_route_turn` 호출 (필수)** → 현재 차례 speaker transport 자동 결정 및 실행
    - CLI speaker → `deliberation_cli_auto_turn`이 실제 CLI를 실행하고 응답 수집
    - browser_auto → CDP로 자동 전송/수집
+   - telepty_bus → structured `turn_request` publish + remote self-submit 대기
    - 자기 자신(claude)이 speaker → 직접 `deliberation_respond`로 응답 제출
+   - 여러 턴을 한 번에 진행하려면 `deliberation_run_until_blocked(session_id)` 사용
 6. 반복 후 `deliberation_synthesize(session_id)` → 합성 완료
 7. 구현이 필요하면 `deliberation-executor` 스킬로 handoff
    예: "session_id {id} 합의안 구현해줘"
@@ -157,6 +163,20 @@ autoresearch 스타일 실험 루프를 검토할 때는 긴 컨텍스트를 `to
    })
 ```
 
+원격 reply를 semantic turn으로 넣어야 할 때:
+
+```text
+deliberation_ingest_remote_reply(
+  session_id: "<session_id>",
+  speaker: "<speaker>",
+  turn_id: "<pending_turn_id>",
+  content: "<reply markdown>",
+  source_machine_id: "peer-01",
+  source_session_id: "remote-gemini-001",
+  transport_scope: "remote_mcp"
+)
+```
+
 ### D. 자동 진행 (스크립트)
 ```bash
 # 새 토론
@@ -233,3 +253,36 @@ bash deliberation-monitor.sh --tmux
 
 - **deliberation-gate**: superpowers 워크플로우 통합 스킬. brainstorming/code-review/debugging 의사결정 지점에 멀티-AI 검증 게이트를 삽입합니다. `~/.claude/skills/deliberation-gate/SKILL.md`에 설치.
 - **deliberation-executor**: deliberation 합의안을 실제 코드 구현으로 전환하는 실행 전용 스킬.
+
+## Data Model: Canonical Roles
+
+Deliberation produces two complementary data artifacts after synthesis:
+
+| Artifact | Role | Consumers |
+|----------|------|-----------|
+| `structured_synthesis` | **Human + reasoning canonical** | Human reviewers, LLM context, decision history |
+| `execution_contract` | **Automation canonical** | inbox-watcher, devkit, registry, orchestrator agents |
+
+### structured_synthesis (Human Canonical)
+Rich context for human review. Contains:
+- `summary`: natural language overview
+- `decisions`: reasoning and rationale
+- `actionable_tasks`: full task descriptions with context
+- `experiment_outcome`: optional verdict (keep/discard/modify)
+
+### execution_contract (Automation Canonical)
+Minimal, deterministic task list for machines. Contains:
+- `version`: contract schema version (currently "v1")
+- `source_session_id`: originating deliberation session
+- `summary`: brief summary for log context
+- `tasks`: flattened actionable task list (same shape as `actionable_tasks`)
+- `generated_from.structured_synthesis_hash`: SHA-1 provenance hash
+
+**Rule**: Automation consumers MUST prefer `execution_contract` when present.
+Fall back to `structured_synthesis` only when `execution_contract` is `null`.
+
+### Archive Outputs
+When a deliberation completes:
+1. **Markdown archive**: `~/.local/lib/mcp-deliberation/state/{project}/archive/deliberation-{ts}-{slug}.md`
+2. **Contract sidecar**: `~/.local/lib/mcp-deliberation/state/{project}/archive/deliberation-{ts}-{slug}.contract.json`
+3. **Telepty envelope**: `deliberation_completed` event with both artifacts in payload