@dmsdc-ai/aigentry-deliberation 0.0.43 → 0.0.47

package/doctor.js

@@ -62,6 +62,54 @@ const LOG_LOCATIONS = [
   path.join(HOME, ".local", "lib", "mcp-deliberation", "runtime.log"),
 ];
 
+// Runtime log size-check thresholds (env-configurable).
+// Doctor DIAGNOSES only — it never mutates log files.
+const LOG_SIZE_WARN_MB = Number(process.env.DELIBERATION_LOG_SIZE_WARN_MB) > 0
+  ? Number(process.env.DELIBERATION_LOG_SIZE_WARN_MB)
+  : 50;
+const LOG_SIZE_ERROR_MB = Number(process.env.DELIBERATION_LOG_SIZE_ERROR_MB) > 0
+  ? Number(process.env.DELIBERATION_LOG_SIZE_ERROR_MB)
+  : 500;
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "? B";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+/**
+ * Inspect ~/.local/lib/mcp-deliberation/ for runtime.log* files and report on
+ * total footprint. Returns { level, totalBytes, topFiles } without mutating
+ * anything (doctor is diagnostic-only).
+ */
+function checkRuntimeLogFootprint(installDir) {
+  const result = { level: "ok", totalBytes: 0, topFiles: [], dir: installDir };
+  try {
+    if (!fs.existsSync(installDir)) return result;
+    const entries = [];
+    for (const name of fs.readdirSync(installDir)) {
+      if (!/^runtime\.log(\.|$)/.test(name)) continue;
+      const p = path.join(installDir, name);
+      try {
+        const st = fs.statSync(p);
+        if (!st.isFile()) continue;
+        entries.push({ path: p, size: st.size });
+        result.totalBytes += st.size;
+      } catch { /* skip */ }
+    }
+    entries.sort((a, b) => b.size - a.size);
+    result.topFiles = entries.slice(0, 3);
+    if (result.totalBytes >= LOG_SIZE_ERROR_MB * 1024 * 1024) {
+      result.level = "error";
+    } else if (result.totalBytes >= LOG_SIZE_WARN_MB * 1024 * 1024) {
+      result.level = "warn";
+    }
+  } catch { /* ignore */ }
+  return result;
+}
+
 // ── TOML parser (minimal, mcp_servers only) ────────────────────
 
 function parseMcpServersFromToml(content) {
@@ -381,6 +429,34 @@ function runDiagnostics() {
       )
     : path.join(HOME, ".local", "lib", "mcp-deliberation");
 
+  // Runtime log footprint check — diagnose only, never mutate.
+  const logCheck = checkRuntimeLogFootprint(installDir);
+  if (logCheck.totalBytes > 0) {
+    const sizeStr = formatBytes(logCheck.totalBytes);
+    if (logCheck.level === "error") {
+      totalIssues++;
+      console.log(`   ❌ runtime.log footprint: ${sizeStr} (>= ${LOG_SIZE_ERROR_MB} MB ERROR threshold)`);
+    } else if (logCheck.level === "warn") {
+      totalIssues++;
+      console.log(`   ⚠️  runtime.log footprint: ${sizeStr} (>= ${LOG_SIZE_WARN_MB} MB WARN threshold)`);
+    } else {
+      console.log(`   ✅ runtime.log footprint: ${sizeStr}`);
+    }
+    if (logCheck.level !== "ok" && logCheck.topFiles.length > 0) {
+      console.log(`      top offenders:`);
+      for (const f of logCheck.topFiles) {
+        console.log(`        - ${formatBytes(f.size).padStart(10)}  ${f.path}`);
+      }
+      console.log(`      fix: upgrade to v0.0.45+ and let normal rotation / budget enforcement reclaim space. Immediate: rm ${path.join(installDir, 'runtime.log.old')} && : > ${path.join(installDir, 'runtime.log')}`);
+      allIssues.push({
+        config: "logs",
+        server: "runtime.log",
+        issue: logCheck.level === "error" ? "log dir >= 500 MB" : "log dir >= 50 MB",
+        fix: "upgrade to v0.0.45+ or manual cleanup",
+      });
+    }
+  }
+
   const selfPath = path.join(installDir, "index.js");
   if (checkPathExists(selfPath)) {
     console.log(`   ✅ Server file: ${selfPath}`);

package/index.js

@@ -69,6 +69,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { execFileSync, spawn } from "child_process";
+import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -112,6 +113,7 @@ import {
   clearSpeakerSelectionToken,
   validateSpeakerSelectionSnapshot,
   confirmSpeakerSelectionToken,
+  markSelectionTokenConsumed,
   validateSpeakerSelectionRequest,
   // Browser participant helpers
   hasExplicitBrowserParticipantSelection,
@@ -234,6 +236,9 @@ import {
 } from "./decision-engine.js";
 import { detectLang, t } from "./i18n.js";
 import { checkToolEntitlement } from "./lib/entitlement.js";
+// δ2 (#440) — telemetry emit wrapper. emit-skip-with-warning when role
+// is unset; failures swallowed; never blocks the synthesis path.
+import { emitSynthesisEvent, emitHandoffEvent } from "./logger-emit.js";
 import {
   initTeleptyDeps,
   // Schemas
@@ -406,6 +411,179 @@ function getSpeakerSelectionFile(projectSlug = getProjectSlug()) {
   return path.join(getProjectStateDir(projectSlug), SPEAKER_SELECTION_FILE);
 }
 
+// ── ADR-264 helpers ─────────────────────────────────────────────
+
+// §2.2 Proxy Response Submission: verify external_output via SHA-256 digest
+// so an orchestrator that pre-spawned a CLI/browser can submit responses
+// without the server re-running the CLI. `verify: "none"` + source
+// "trusted_orchestrator" is an explicit opt-out used only at a trust boundary.
+export function verifyExternalOutputProof({
+  external_output,
+  external_output_proof,
+  verify = "hash",
+} = {}) {
+  if (typeof external_output !== "string" || external_output.length === 0) {
+    return { ok: false, code: "E_EXTERNAL_OUTPUT_MISSING" };
+  }
+
+  if (verify === "none") {
+    if (external_output_proof?.source !== "trusted_orchestrator") {
+      return { ok: false, code: "E_EXTERNAL_OUTPUT_PROOF_SOURCE_REQUIRED" };
+    }
+    return {
+      ok: true,
+      audit: {
+        source: "trusted_orchestrator",
+        verify: "none",
+        length: Buffer.byteLength(external_output, "utf-8"),
+      },
+    };
+  }
+
+  if (!external_output_proof || typeof external_output_proof !== "object") {
+    return { ok: false, code: "E_EXTERNAL_OUTPUT_PROOF_MISSING" };
+  }
+  if (external_output_proof.algo !== "sha256") {
+    return { ok: false, code: "E_EXTERNAL_OUTPUT_PROOF_ALGO_UNSUPPORTED", algo: external_output_proof.algo };
+  }
+  const expected = String(external_output_proof.digest || "").toLowerCase();
+  const actual = crypto.createHash("sha256").update(external_output, "utf-8").digest("hex");
+  if (expected !== actual) {
+    return { ok: false, code: "E_EXTERNAL_OUTPUT_PROOF_MISMATCH", expected, actual };
+  }
+  return {
+    ok: true,
+    audit: {
+      source: external_output_proof.source || "unspecified",
+      verify: "hash",
+      digest: actual,
+    },
+  };
+}
+
+// §2.3 step 5 — reuse the same safeId regex as withSessionLock (lib/speaker-discovery
+// invariant: only a-z A-Z 0-9 가-힣 . _ - survive). Prevents `../`, `/`, and
+// null-byte path traversal when a caller supplies session_id.
+export function sanitizeSessionDirName(sessionId) {
+  return String(sessionId).replace(/[^a-zA-Z0-9가-힣._-]/g, "_");
+}
+
+// §2.3 steps 1-4, 7, 8 — resolve and audit an optional spawn_cwd against a
+// prefix allowlist. Symlinks are allowed only if the realpath still satisfies
+// the prefix check. Caller passes `allowedPrefixes` derived from
+// ~/.config/mcp-deliberation/allowed-cwd-prefixes.json when present; otherwise
+// defaults to $HOME + $TMPDIR so bench harnesses in /tmp work out of the box.
+export function validateSpawnCwd(input, { allowedPrefixes } = {}) {
+  if (typeof input !== "string" || input.length === 0) {
+    return { ok: false, code: "E_CWD_NOT_ABSOLUTE", input };
+  }
+  if (!path.isAbsolute(input)) {
+    return { ok: false, code: "E_CWD_NOT_ABSOLUTE", input };
+  }
+
+  let resolved;
+  try {
+    resolved = fs.realpathSync(input);
+  } catch (err) {
+    const code = err && err.code === "ENOENT" ? "E_CWD_NOT_FOUND" : "E_CWD_NOT_FOUND";
+    return { ok: false, code, input, error: err?.message };
+  }
+
+  const prefixesUnresolved = Array.isArray(allowedPrefixes) && allowedPrefixes.length > 0
+    ? allowedPrefixes
+    : [os.homedir(), os.tmpdir()];
+
+  // Resolve the prefixes themselves so callers can pass "/tmp" and still match
+  // realpath'd children like "/private/tmp/foo" on macOS.
+  const prefixesResolved = prefixesUnresolved.map((p) => {
+    try { return fs.realpathSync(p); } catch { return p; }
+  });
+  const prefixesAll = Array.from(new Set([...prefixesUnresolved, ...prefixesResolved]));
+
+  const matches = (candidate, prefixList) =>
+    prefixList.some((prefix) =>
+      candidate === prefix || candidate.startsWith(prefix + path.sep),
+    );
+
+  const inputLooksAllowed = matches(input, prefixesAll);
+  const resolvedLooksAllowed = matches(resolved, prefixesResolved);
+  const symlinkCrossed = resolved !== input;
+
+  // §2.3 step 3 — input path itself must be under an allowed prefix, so
+  // passing "/etc/passwd" when tmpRoot is allowed immediately fails.
+  if (!inputLooksAllowed) {
+    return { ok: false, code: "E_CWD_NOT_ALLOWED", input, resolved, allowed_prefixes: prefixesResolved };
+  }
+
+  // §2.3 step 4 — input looked allowed, but realpath escapes → symlink attack.
+  if (!resolvedLooksAllowed) {
+    return { ok: false, code: "E_CWD_SYMLINK_ESCAPE", input, resolved, allowed_prefixes: prefixesResolved };
+  }
+
+  return { ok: true, input, resolved, allowed_prefixes: prefixesResolved, symlink_crossed: symlinkCrossed };
+}
+
+// §2.3 step 6 — create a per-session subdir under the resolved cwd so two
+// concurrent cli_auto_turn calls do not share working state. Idempotent when
+// the caller has already pointed at a matching session folder.
+export function ensureSessionSubdir(resolvedCwd, sessionId) {
+  let safe = sanitizeSessionDirName(sessionId);
+  // `.` and `..` survive the ADR-specified regex but would climb out of
+  // resolvedCwd when joined. Rewrite to a literal segment so the subdir is
+  // always strictly nested.
+  if (safe === "." || safe === "..") {
+    safe = `_${safe.length === 2 ? "dotdot" : "dot"}`;
+  }
+  if (path.basename(resolvedCwd) === safe) {
+    return resolvedCwd;
+  }
+  const target = path.join(resolvedCwd, safe);
+  fs.mkdirSync(target, { recursive: true });
+  return target;
+}
+
+// §2.4 — normalize observability data into the {value, status} envelope that
+// downstream aggregators skip (status !== "ok") before arithmetic. Fields not
+// provided default to `adapter_missing`.
+const OBS_FIELDS = [
+  "tokens_in",
+  "tokens_out",
+  "estimated_cost_usd",
+  "model_reported_by_cli",
+  "actual_model_id",
+];
+
+export function buildObservabilityEnvelope(adapter) {
+  const src = adapter && typeof adapter === "object" ? adapter : {};
+  const out = {};
+  for (const field of OBS_FIELDS) {
+    const entry = src[field];
+    if (entry && typeof entry === "object" && "status" in entry) {
+      out[field] = { value: entry.value ?? null, status: String(entry.status) };
+    } else {
+      out[field] = { value: null, status: "adapter_missing" };
+    }
+  }
+  return out;
+}
+
+function loadAllowedCwdPrefixes() {
+  const overridePath = path.join(os.homedir(), ".config", "mcp-deliberation", "allowed-cwd-prefixes.json");
+  try {
+    const raw = fs.readFileSync(overridePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.prefixes) && parsed.prefixes.every((p) => typeof p === "string")) {
+      return parsed.prefixes;
+    }
+    appendRuntimeLog("WARN", `ALLOWED_CWD_PREFIXES_SCHEMA: ${overridePath} lacks { prefixes: string[] }, falling back to defaults`);
+  } catch (err) {
+    if (err && err.code !== "ENOENT") {
+      appendRuntimeLog("WARN", `ALLOWED_CWD_PREFIXES_LOAD: ${overridePath} parse failed (${err.message}), falling back to defaults`);
+    }
+  }
+  return null;
+}
+
 function formatRuntimeError(error) {
   if (error instanceof Error) {
     return error.stack || error.message;
@@ -413,22 +591,154 @@ function formatRuntimeError(error) {
   return String(error);
 }
 
-function appendRuntimeLog(level, message) {
+// ── Runtime log configuration (env-overridable) ────────────────
+const LOG_MAX_SIZE_MB = Number(process.env.DELIBERATION_LOG_MAX_SIZE_MB) > 0
+  ? Number(process.env.DELIBERATION_LOG_MAX_SIZE_MB)
+  : 1;
+const LOG_TOTAL_BUDGET_MB = Number(process.env.DELIBERATION_LOG_TOTAL_BUDGET_MB) > 0
+  ? Number(process.env.DELIBERATION_LOG_TOTAL_BUDGET_MB)
+  : 10;
+const LOG_DEDUP_MS = Number.isFinite(Number(process.env.DELIBERATION_LOG_DEDUP_MS)) && Number(process.env.DELIBERATION_LOG_DEDUP_MS) >= 0
+  ? Number(process.env.DELIBERATION_LOG_DEDUP_MS)
+  : 1000;
+const LOG_HARD_CAP_BYTES = LOG_MAX_SIZE_MB * 2 * 1024 * 1024; // race fallback: 2× per-file threshold
+const LOG_TAIL_BYTES = 500 * 1024; // truncate to last 500 KB on hard-cap overflow
+const LOG_PRE_UPGRADE_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// Module-level dedup state
+let _dedupLastKey = null;
+let _dedupLastWriteMs = 0;
+let _dedupLastMessage = null;
+let _dedupPendingCount = 0;
+
+// Module-level upgrade-safety guard (once per process)
+let _logUpgradeSafetyRan = false;
+
+function _flushDedupToFile() {
+  if (_dedupPendingCount <= 0) return;
   try {
-    fs.mkdirSync(path.dirname(GLOBAL_RUNTIME_LOG), { recursive: true });
-    
-    // Simple rotation: if log > 1MB, truncate it
+    const elapsed = Date.now() - _dedupLastWriteMs;
+    const summary = `${new Date().toISOString()} [DEDUP] [${_dedupPendingCount}x in ${elapsed}ms] ${_dedupLastMessage || ""}\n`;
+    fs.appendFileSync(GLOBAL_RUNTIME_LOG, summary, "utf-8");
+  } catch { /* ignore */ }
+  _dedupPendingCount = 0;
+}
+
+function _runLogUpgradeSafetyOnce() {
+  if (_logUpgradeSafetyRan) return;
+  _logUpgradeSafetyRan = true;
+  try {
+    const dir = path.dirname(GLOBAL_RUNTIME_LOG);
+    if (!fs.existsSync(dir)) return;
+    const markerPath = path.join(dir, ".log-upgrade-v0.0.45");
+    if (!fs.existsSync(markerPath)) {
+      let totalSize = 0;
+      const candidates = [];
+      for (const name of fs.readdirSync(dir)) {
+        if (!/^runtime\.log(\.|$)/.test(name)) continue;
+        if (name.startsWith("runtime.log.pre-")) continue;
+        const p = path.join(dir, name);
+        try {
+          const s = fs.statSync(p).size;
+          totalSize += s;
+          candidates.push(p);
+        } catch { /* skip */ }
+      }
+      if (totalSize > 1024 * 1024) {
+        const preBackup = GLOBAL_RUNTIME_LOG + ".pre-0.0.45";
+        try {
+          if (fs.existsSync(GLOBAL_RUNTIME_LOG) && !fs.existsSync(preBackup)) {
+            fs.renameSync(GLOBAL_RUNTIME_LOG, preBackup);
+          }
+          // Any other rotated files (runtime.log.old etc.) — removed so normal
+          // rotation can start fresh. The .pre-0.0.45 backup retains the latest.
+          for (const p of candidates) {
+            if (p === preBackup) continue;
+            if (!fs.existsSync(p)) continue;
+            try { fs.unlinkSync(p); } catch { /* ignore */ }
+          }
+        } catch { /* ignore */ }
+      }
+      try { fs.writeFileSync(markerPath, new Date().toISOString()); } catch { /* ignore */ }
+    }
+    // Expire .pre-0.0.45 after 7 days OR on budget overflow
     try {
-      if (fs.existsSync(GLOBAL_RUNTIME_LOG)) {
-        const stats = fs.statSync(GLOBAL_RUNTIME_LOG);
-        if (stats.size > 1024 * 1024) { // 1MB
-          const oldLog = GLOBAL_RUNTIME_LOG + ".old";
-          fs.renameSync(GLOBAL_RUNTIME_LOG, oldLog);
+      const preBackup = GLOBAL_RUNTIME_LOG + ".pre-0.0.45";
+      if (fs.existsSync(preBackup)) {
+        const preStat = fs.statSync(preBackup);
+        let totalDir = preStat.size;
+        try {
+          for (const name of fs.readdirSync(dir)) {
+            if (!/^runtime\.log(\.|$)/.test(name)) continue;
+            if (name === "runtime.log.pre-0.0.45") continue;
+            try { totalDir += fs.statSync(path.join(dir, name)).size; } catch { /* skip */ }
+          }
+        } catch { /* skip */ }
+        const age = Date.now() - preStat.mtimeMs;
+        if (age > LOG_PRE_UPGRADE_EXPIRY_MS || totalDir > LOG_TOTAL_BUDGET_MB * 1024 * 1024) {
+          try { fs.unlinkSync(preBackup); } catch { /* ignore */ }
         }
       }
-    } catch { /* ignore rotation failures */ }
+    } catch { /* ignore */ }
+  } catch { /* ignore */ }
+}
 
-    const line = `${new Date().toISOString()} [${level}] ${message}\n`;
+function _rotateOrTruncate() {
+  try {
+    if (!fs.existsSync(GLOBAL_RUNTIME_LOG)) return;
+    const stats = fs.statSync(GLOBAL_RUNTIME_LOG);
+    // Hard cap: if file exceeds 2× per-file threshold (race under concurrent writers),
+    // truncate in place to the last LOG_TAIL_BYTES to prevent runaway growth.
+    if (stats.size > LOG_HARD_CAP_BYTES) {
+      try {
+        const fd = fs.openSync(GLOBAL_RUNTIME_LOG, "r");
+        try {
+          const tailStart = Math.max(0, stats.size - LOG_TAIL_BYTES);
+          const buf = Buffer.alloc(stats.size - tailStart);
+          fs.readSync(fd, buf, 0, buf.length, tailStart);
+          fs.writeFileSync(GLOBAL_RUNTIME_LOG, buf, "utf-8");
+        } finally {
+          try { fs.closeSync(fd); } catch { /* ignore */ }
+        }
+      } catch { /* fall through */ }
+      return;
+    }
+    if (stats.size > LOG_MAX_SIZE_MB * 1024 * 1024) {
+      const oldLog = GLOBAL_RUNTIME_LOG + ".old";
+      // Explicit cleanup: delete previous .old before rename (robustness over
+      // atomic-rename-overwrite assumption, especially under concurrent writers).
+      try {
+        if (fs.existsSync(oldLog)) fs.unlinkSync(oldLog);
+      } catch { /* ignore */ }
+      try { fs.renameSync(GLOBAL_RUNTIME_LOG, oldLog); } catch { /* ignore */ }
+    }
+  } catch { /* ignore rotation failures */ }
+}
+
+function appendRuntimeLog(level, message) {
+  try {
+    fs.mkdirSync(path.dirname(GLOBAL_RUNTIME_LOG), { recursive: true });
+    _runLogUpgradeSafetyOnce();
+
+    const safeMessage = String(message ?? "");
+    const key = `${level}:${safeMessage.slice(0, 200)}`;
+    const now = Date.now();
+
+    // Dedup: suppress repeated identical messages within window
+    if (_dedupLastKey === key && (now - _dedupLastWriteMs) < LOG_DEDUP_MS) {
+      _dedupPendingCount += 1;
+      return;
+    }
+
+    // New key or window expired — flush prior suppression summary first
+    if (_dedupPendingCount > 0) _flushDedupToFile();
+    _dedupLastKey = key;
+    _dedupLastWriteMs = now;
+    _dedupLastMessage = `[${level}] ${safeMessage}`;
+
+    _rotateOrTruncate();
+
+    const line = `${new Date(now).toISOString()} [${level}] ${safeMessage}\n`;
     fs.appendFileSync(GLOBAL_RUNTIME_LOG, line, "utf-8");
   } catch {
     // ignore logging failures
@@ -582,34 +892,48 @@ for (const stream of [process.stdout, process.stderr]) {
   });
 }
 
+// Module-level reentrance guard. Once a fatal handler has fired, subsequent
+// invocations become no-ops. This breaks the EPIPE self-amplifying loop where
+// writing the previous error's log line itself triggered another EPIPE.
+let _hasHandledFatalError = false;
+
+function _isBrokenStdioError(err) {
+  if (!err) return false;
+  const code = err.code;
+  if (code === "EPIPE" || code === "ERR_STREAM_DESTROYED" || code === "ERR_STREAM_WRITE_AFTER_END") return true;
+  const message = String(err?.message ?? err ?? "");
+  return /EPIPE|write after end/i.test(message);
+}
+
 process.on("uncaughtException", (error) => {
-  // EPIPE = MCP client disconnected (normal shutdown). Exit cleanly.
-  if (error?.code === "EPIPE" || error?.code === "ERR_STREAM_DESTROYED") {
+  if (_hasHandledFatalError) return;
+  if (_isBrokenStdioError(error)) {
+    _hasHandledFatalError = true;
+    try { _flushDedupToFile(); } catch { /* noop */ }
     try { appendRuntimeLog("INFO", "Client disconnected (EPIPE). Shutting down."); } catch { /* noop */ }
-    process.exit(0);
-  }
-  const message = formatRuntimeError(error);
-  appendRuntimeLog("UNCAUGHT_EXCEPTION", message);
-  try {
-    process.stderr.write(`[mcp-deliberation] uncaughtException: ${message}\n`);
-  } catch {
-    // ignore stderr write failures
+    try { process.exit(0); } catch { /* noop */ }
+    return;
   }
+  // Non-stdio fatal: log to file only. process.stderr.write was REMOVED here
+  // because it was the re-trigger source when stdio was the broken channel.
+  try { appendRuntimeLog("UNCAUGHT_EXCEPTION", formatRuntimeError(error)); } catch { /* noop */ }
 });
 
 process.on("unhandledRejection", (reason) => {
-  // EPIPE = MCP client disconnected (normal shutdown). Exit cleanly.
-  if (reason?.code === "EPIPE" || reason?.code === "ERR_STREAM_DESTROYED") {
+  if (_hasHandledFatalError) return;
+  if (_isBrokenStdioError(reason)) {
+    _hasHandledFatalError = true;
+    try { _flushDedupToFile(); } catch { /* noop */ }
     try { appendRuntimeLog("INFO", "Client disconnected (EPIPE). Shutting down."); } catch { /* noop */ }
-    process.exit(0);
-  }
-  const message = formatRuntimeError(reason);
-  appendRuntimeLog("UNHANDLED_REJECTION", message);
-  try {
-    process.stderr.write(`[mcp-deliberation] unhandledRejection: ${message}\n`);
-  } catch {
-    // ignore stderr write failures
+    try { process.exit(0); } catch { /* noop */ }
+    return;
   }
+  try { appendRuntimeLog("UNHANDLED_REJECTION", formatRuntimeError(reason)); } catch { /* noop */ }
+});
+
+// Flush any pending dedup summary on graceful exit so the tail summary is not lost
+process.on("exit", () => {
+  try { _flushDedupToFile(); } catch { /* noop */ }
 });
 
 // Read version from package.json (single source of truth)
@@ -783,11 +1107,21 @@ server.tool(
     const manualSpeakersProvided = Array.isArray(speakers) && speakers.length > 0;
     let selectionValidation = { ok: true };
     if (effectiveRequireManual && manualSpeakersProvided) {
-      selectionValidation = validateSpeakerSelectionRequest({
-        selectionState: loadSpeakerSelectionToken(),
-        selection_token,
-        speakers,
-        includeBrowserSpeakers,
+      // ADR-264 §2.1 — read-validate-consume wrapped in withProjectLock so two
+      // MCP server processes racing on the same speaker-selection.json cannot
+      // both observe the same token as unconsumed.
+      selectionValidation = withProjectLock(getProjectSlug(), () => {
+        const persistedState = loadSpeakerSelectionToken();
+        const result = validateSpeakerSelectionRequest({
+          selectionState: persistedState,
+          selection_token,
+          speakers,
+          includeBrowserSpeakers,
+        });
+        if (result.ok) {
+          markSelectionTokenConsumed({ selectionState: persistedState });
+        }
+        return result;
       });
     }
     const hasManualSpeakers = manualSpeakersProvided && (!effectiveRequireManual || selectionValidation.ok);
@@ -855,9 +1189,10 @@ server.tool(
       || DEFAULT_SPEAKERS[0];
     let speakerOrder = buildSpeakerOrder(selectedSpeakers, normalizedFirstSpeaker, "front");
 
-    if (effectiveRequireManual) {
-      clearSpeakerSelectionToken();
-    }
+    // ADR-264 §2.1 — selection token has already been stamped `consumed_at`
+    // inside withProjectLock above. Leaving the file in place with the tombstone
+    // lets any racing caller surface `token_already_consumed` instead of the
+    // more ambiguous `missing_selection_state`. TTL garbage-collects it.
 
     // Lite mode: cap speakers and rounds for quick decisions
     if (mode === "lite") {
@@ -1020,9 +1355,21 @@ server.tool(
   },
   async ({ include_cli, include_browser }) => {
     const snapshot = await collectSpeakerCandidates({ include_cli, include_browser });
-    const selection = issueSpeakerSelectionToken({
-      candidates: snapshot.candidates,
-      include_browser,
+    // ADR-264 §2.1 — issue inside withProjectLock and warn when overwriting a
+    // confirmed-but-not-consumed state so racing consumers cannot silently
+    // invalidate a token already promised to a start call in flight.
+    const selection = withProjectLock(getProjectSlug(), () => {
+      const existing = loadSpeakerSelectionToken();
+      if (existing?.phase === "confirmed" && !existing.consumed_at) {
+        appendRuntimeLog(
+          "WARN",
+          `SELECTION_OVERWRITE_CONFIRMED: project=${getProjectSlug()} | token=${existing.token} | selected=${(existing.selected_speakers || []).join(",")}`,
+        );
+      }
+      return issueSpeakerSelectionToken({
+        candidates: snapshot.candidates,
+        include_browser,
+      });
     });
     const text = formatSpeakerCandidatesReport(snapshot);
     return {
@@ -1493,8 +1840,14 @@ server.tool(
   {
     session_id: z.string().optional().describe("Session ID (required if multiple sessions are active)"),
     timeout_sec: z.number().optional().default(120).describe("CLI response wait timeout (seconds)"),
+    // ADR-264 §2.3 — optional working directory for the spawned CLI. Validated
+    // against an allowlist (default: $HOME + $TMPDIR; override via
+    // ~/.config/mcp-deliberation/allowed-cwd-prefixes.json). The server creates
+    // a session-unique subdirectory under the resolved cwd so concurrent
+    // cli_auto_turn calls do not share working files.
+    spawn_cwd: z.string().optional().describe("Absolute path under an allowed prefix to use as CLI working directory. Used to isolate project CLAUDE.md/GEMINI.md context from the server's cwd."),
   },
-  safeToolHandler("deliberation_cli_auto_turn", async ({ session_id, timeout_sec }) => {
+  safeToolHandler("deliberation_cli_auto_turn", async ({ session_id, timeout_sec, spawn_cwd }) => {
     const resolved = resolveSessionId(session_id);
     if (!resolved) {
       return { content: [{ type: "text", text: t("No active deliberation.", "활성 deliberation이 없습니다.", "en") }] };
@@ -1555,6 +1908,34 @@ server.tool(
       priorTurns: speakerPriorTurns,
     });
 
+    // ADR-264 §2.3 — validate optional spawn_cwd and allocate a session-unique
+    // subdirectory before we spawn the child. Structured error codes (E_CWD_*)
+    // surface via the return envelope so orchestrators can diagnose misuse.
+    let resolvedSpawnCwd;
+    if (typeof spawn_cwd === "string" && spawn_cwd.length > 0) {
+      const override = loadAllowedCwdPrefixes();
+      const cwdCheck = validateSpawnCwd(spawn_cwd, override ? { allowedPrefixes: override } : undefined);
+      if (!cwdCheck.ok) {
+        appendRuntimeLog(
+          "WARN",
+          `SPAWN_CWD_REJECTED: ${resolved} | speaker=${speaker} | code=${cwdCheck.code} | input=${cwdCheck.input} | resolved=${cwdCheck.resolved || "n/a"}`,
+        );
+        return {
+          content: [{
+            type: "text",
+            text: `❌ **spawn_cwd rejected**: \`${cwdCheck.code}\`\n\nInput: \`${cwdCheck.input}\`\nResolved: \`${cwdCheck.resolved || "n/a"}\`\nAllowed prefixes: ${(cwdCheck.allowed_prefixes || []).map((p) => `\`${p}\``).join(", ") || "(none)"}\n\nProvide an absolute path under one of the allowed prefixes, or configure \`~/.config/mcp-deliberation/allowed-cwd-prefixes.json\`.`,
+          }],
+        };
+      }
+      if (cwdCheck.symlink_crossed) {
+        appendRuntimeLog(
+          "WARN",
+          `SPAWN_CWD_SYMLINK: ${resolved} | speaker=${speaker} | input=${cwdCheck.input} | resolved=${cwdCheck.resolved}`,
+        );
+      }
+      resolvedSpawnCwd = ensureSessionSubdir(cwdCheck.resolved, resolved);
+    }
+
     // Spawn CLI process
     const startTime = Date.now();
     try {
@@ -1564,6 +1945,8 @@ server.tool(
         if (hint.envPrefix?.includes("CLAUDECODE=")) {
           delete env.CLAUDECODE;
         }
+        const spawnOpts = { env, windowsHide: true };
+        if (resolvedSpawnCwd) spawnOpts.cwd = resolvedSpawnCwd;
 
         let child;
         let stdout = "";
@@ -1587,22 +1970,22 @@ server.tool(
         // Different invocation patterns per CLI
         switch (speaker) {
           case "claude":
-            child = spawn("claude", getCliExecArgs("claude"), { env, windowsHide: true });
+            child = spawn("claude", getCliExecArgs("claude"), spawnOpts);
             child.stdin.write(turnPrompt);
             child.stdin.end();
             break;
           case "codex":
-            child = spawn("codex", getCliExecArgs("codex"), { env, windowsHide: true });
+            child = spawn("codex", getCliExecArgs("codex"), spawnOpts);
             child.stdin.write(turnPrompt);
             child.stdin.end();
             break;
           case "gemini":
-            child = spawn("gemini", ["-p", turnPrompt], { env, windowsHide: true });
+            child = spawn("gemini", ["-p", turnPrompt], spawnOpts);
             break;
           default: {
             // Generic: try command with prompt as argument
             const flags = hint.flags ? hint.flags.split(/\s+/) : [];
-            child = spawn(hint.cmd, [...flags, turnPrompt], { env, windowsHide: true });
+            child = spawn(hint.cmd, [...flags, turnPrompt], spawnOpts);
             break;
           }
         }
@@ -1682,11 +2065,26 @@ server.tool(
         fallback_reason: null,
       });
 
+      // ADR-264 §2.4 — Phase 0 observability envelope. Per-CLI adapters
+      // (claude/codex/gemini) that parse usage from stdout are a follow-up;
+      // until then every field reports `adapter_missing` so downstream
+      // aggregators can skip non-`ok` entries without NaN propagation.
+      const observability = buildObservabilityEnvelope(null);
+
       return {
         content: [{
           type: "text",
-          text: `✅ CLI auto-turn complete!\n\n**Speaker:** ${speaker}\n**CLI:** ${hint.cmd}\n**Turn ID:** ${turnId}\n**Response length:** ${response.length} chars\n**Elapsed:** ${elapsedMs}ms\n\n${result.content[0].text}`,
+          text: `✅ CLI auto-turn complete!\n\n**Speaker:** ${speaker}\n**CLI:** ${hint.cmd}\n**Turn ID:** ${turnId}\n**Response length:** ${response.length} chars\n**Elapsed:** ${elapsedMs}ms${resolvedSpawnCwd ? `\n**spawn_cwd:** \`${resolvedSpawnCwd}\`` : ""}\n\n**Observability (ADR-264 §2.4, Phase 0):**\n- tokens_in: ${observability.tokens_in.status}\n- tokens_out: ${observability.tokens_out.status}\n- estimated_cost_usd: ${observability.estimated_cost_usd.status}\n- model_reported_by_cli: ${observability.model_reported_by_cli.status}\n- actual_model_id: ${observability.actual_model_id.status}\n\n${result.content[0].text}`,
         }],
+        structuredContent: {
+          speaker,
+          cli: hint.cmd,
+          turn_id: turnId,
+          response_length: response.length,
+          elapsed_ms: elapsedMs,
+          spawn_cwd: resolvedSpawnCwd ?? null,
+          ...observability,
+        },
       };
 
     } catch (err) {
@@ -1769,10 +2167,22 @@ server.tool(
     use_clipboard: z.boolean().optional().describe("Read content from system clipboard (alternative to content/content_file)"),
     include_clipboard_image: z.boolean().optional().describe("Capture and include image from system clipboard"),
     turn_id: z.string().optional().describe("Turn verification ID (value received from deliberation_route_turn)"),
+    // ADR-264 §2.2 — optional proxy submission. An orchestrator that pre-spawned
+    // the CLI/browser itself can submit the collected response here instead of
+    // asking the server to re-run the CLI. Default behavior (fields absent) is
+    // unchanged: proxy is blocked.
+    external_output: z.string().optional().describe("Pre-collected response body that the orchestrator obtained from a CLI/browser it spawned itself. Requires external_output_proof."),
+    external_output_proof: z.object({
+      algo: z.literal("sha256"),
+      digest: z.string().describe("Lowercase hex sha256 digest of external_output bytes."),
+      source: z.enum(["cli_stdout", "browser_dom", "trusted_orchestrator"]),
+    }).optional().describe("Proof payload for external_output. sha256 of the raw UTF-8 bytes."),
+    verify: z.enum(["hash", "none"]).optional().default("hash").describe("Proof verification mode. 'none' requires source=trusted_orchestrator and logs an explicit audit entry."),
   },
-  safeToolHandler("deliberation_respond", async ({ session_id, speaker, content, content_file, use_clipboard, include_clipboard_image, turn_id }) => {
+  safeToolHandler("deliberation_respond", async ({ session_id, speaker, content, content_file, use_clipboard, include_clipboard_image, turn_id, external_output, external_output_proof, verify }) => {
     // Guard: prevent orchestrator from fabricating responses for CLI/browser speakers
     const resolved = resolveSessionId(session_id);
+    let externalAcceptedContent = null;
     if (resolved && resolved !== "MULTIPLE") {
       const state = loadSession(resolved);
       if (state) {
@@ -1782,22 +2192,55 @@ server.tool(
           const callerSpeaker = detectCallerSpeaker();
           const callerIsSpeaker = callerSpeaker && (speaker === callerSpeaker);
           if (!callerIsSpeaker) {
-            return {
-              content: [{
-                type: "text",
-                text: t(
-                  `⚠️ **Proxy response blocked**: Speaker "${speaker}" has ${transport} transport.\n\nThe orchestrator is not allowed to write responses on behalf of other speakers.\nUse the following tools instead:\n- CLI speaker → \`deliberation_route_turn\` or \`deliberation_cli_auto_turn\`\n- Browser speaker → \`deliberation_route_turn\` or \`deliberation_browser_auto_turn\`\n\nThese tools run the actual CLI/browser to collect genuine responses.`,
-                  `⚠️ **대리 응답 차단**: speaker "${speaker}"는 ${transport} transport입니다.\n\n오케스트레이터가 다른 speaker를 대신하여 응답을 작성하는 것은 허용되지 않습니다.\n대신 다음 도구를 사용하세요:\n- CLI speaker → \`deliberation_route_turn\` 또는 \`deliberation_cli_auto_turn\`\n- 브라우저 speaker → \`deliberation_route_turn\` 또는 \`deliberation_browser_auto_turn\`\n\n이 도구들이 실제 CLI/브라우저를 실행하여 진짜 응답을 수집합니다.`,
-                  state?.lang),
-              }],
-            };
+            // ADR-264 §2.2 — accept pre-collected external_output when a proof
+            // is supplied. Failed verification surfaces a structured error code
+            // instead of falling back to the opaque "proxy blocked" message.
+            if (typeof external_output === "string" && external_output.length > 0) {
+              const proof = verifyExternalOutputProof({ external_output, external_output_proof, verify });
+              if (proof.ok) {
+                externalAcceptedContent = external_output;
+                appendRuntimeLog(
+                  "INFO",
+                  `EXTERNAL_OUTPUT_ACCEPTED: ${resolved} | speaker=${speaker} | transport=${transport} | source=${proof.audit?.source} | verify=${proof.audit?.verify} | len=${external_output.length}`,
+                );
+              } else {
+                const digestDetail = proof.expected
+                  ? `\n\nExpected digest: ${proof.expected}\nActual digest: ${proof.actual}`
+                  : "";
+                appendRuntimeLog(
+                  "WARN",
+                  `EXTERNAL_OUTPUT_REJECTED: ${resolved} | speaker=${speaker} | code=${proof.code}${proof.expected ? ` | expected=${proof.expected} | actual=${proof.actual}` : ""}`,
+                );
+                return {
+                  content: [{
+                    type: "text",
+                    text: t(
+                      `⚠️ **Proxy response rejected**: \`${proof.code}\`\n\nThe supplied external_output did not pass verification (verify=\"${verify || "hash"}\").${digestDetail}\n\nSupply a correct sha256 proof, or call \`deliberation_cli_auto_turn\` / \`deliberation_browser_auto_turn\` to let the server run the transport.`,
+                      `⚠️ **대리 응답 거부**: \`${proof.code}\`\n\n제공된 external_output 검증 실패 (verify=\"${verify || "hash"}\").${digestDetail}\n\n올바른 sha256 proof를 제공하거나, \`deliberation_cli_auto_turn\` / \`deliberation_browser_auto_turn\` 으로 서버가 직접 transport를 실행하게 하세요.`,
+                      state?.lang),
+                  }],
+                };
+              }
+            } else {
+              return {
+                content: [{
+                  type: "text",
+                  text: t(
+                    `⚠️ **Proxy response blocked**: Speaker "${speaker}" has ${transport} transport.\n\nThe orchestrator is not allowed to write responses on behalf of other speakers.\nUse the following tools instead:\n- CLI speaker → \`deliberation_route_turn\` or \`deliberation_cli_auto_turn\`\n- Browser speaker → \`deliberation_route_turn\` or \`deliberation_browser_auto_turn\`\n\nThese tools run the actual CLI/browser to collect genuine responses.\n\nAlternatively, the orchestrator can submit a response it spawned itself via \`external_output\` + \`external_output_proof\` (sha256 hex of the UTF-8 bytes).`,
+                    `⚠️ **대리 응답 차단**: speaker "${speaker}"는 ${transport} transport입니다.\n\n오케스트레이터가 다른 speaker를 대신하여 응답을 작성하는 것은 허용되지 않습니다.\n대신 다음 도구를 사용하세요:\n- CLI speaker → \`deliberation_route_turn\` 또는 \`deliberation_cli_auto_turn\`\n- 브라우저 speaker → \`deliberation_route_turn\` 또는 \`deliberation_browser_auto_turn\`\n\n이 도구들이 실제 CLI/브라우저를 실행하여 진짜 응답을 수집합니다.\n\n또는 오케스트레이터가 직접 spawn한 결과는 \`external_output\` + \`external_output_proof\` (sha256 hex) 로 제출할 수 있습니다.`,
+                    state?.lang),
+                }],
+              };
+            }
           }
         }
       }
     }
 
     // Support reading content from file or clipboard to avoid JSON escaping issues
-    let finalContent = content;
+    // ADR-264 §2.2 — external_output (when verified) takes precedence so proxy
+    // submissions don't conflict with stale content/content_file values.
+    let finalContent = externalAcceptedContent ?? content;
     if (use_clipboard && !content) {
       try {
         finalContent = readClipboardText();
@@ -2117,6 +2560,27 @@ server.tool(
     }
 
     appendRuntimeLog("INFO", `SYNTHESIZED: ${resolved} | turns: ${state.log.length} | rounds: ${state.max_rounds}`);
+    emitSynthesisEvent(
+      {
+        session: resolved,
+        turns: state.log.length,
+        max_rounds: state.max_rounds,
+        speakers: state.speakers || [],
+        auto_execute: !!state.auto_execute,
+        has_structured: !!structured,
+      },
+      resolved,
+    );
+    if (state.execution_contract) {
+      emitHandoffEvent(
+        {
+          session: resolved,
+          tasks_total: state.execution_contract?.tasks?.length ?? 0,
+          auto_execute: !!state.auto_execute,
+        },
+        resolved,
+      );
+    }
     const synthesisEnvelope = buildTeleptySynthesisEnvelope({
       state,
       synthesis,
@@ -3109,4 +3573,4 @@ if (__entryFile && path.resolve(__currentFile) === __entryFile) {
 }
 
 // ── Test exports (used by vitest) ──
-export { checkToolEntitlement, 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 };
+export { appendRuntimeLog, _flushDedupToFile, _isBrokenStdioError, checkToolEntitlement, 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, markSelectionTokenConsumed, 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

@@ -41,6 +41,7 @@ function toForwardSlash(p) {
 
 const FILES_TO_COPY = [
   "index.js",
+  "logger-emit.js",
   "observer.js",
   "clipboard.js",
   "decision-engine.js",

package/lib/session.js

@@ -30,6 +30,9 @@ import {
   normalizeSessionActors,
 } from "./speaker-discovery.js";
 import { t } from "../i18n.js";
+// δ2 (#440) — telemetry emit wrapper. emit-skip-with-warning when role
+// is unset; failures swallowed; never blocks the turn-submission path.
+import { emitTurnEvent } from "../logger-emit.js";
 
 // ── Dependency injection ────────────────────────────────────────
 // Functions that live in index.js but are needed here.  Injected once
@@ -633,6 +636,18 @@ export function submitDeliberationTurn({ session_id, speaker, content, turn_id,
   });
 
   if (completionState && completionEntry) {
+    emitTurnEvent(
+      "turn_complete",
+      {
+        session: completionState.id,
+        speaker: completionEntry.speaker,
+        round: completionEntry.round,
+        max_rounds: completionState.max_rounds,
+        next_speaker: completionState.current_speaker,
+        votes_count: Array.isArray(completionEntry.votes) ? completionEntry.votes.length : 0,
+      },
+      completionEntry.turn_id || undefined,
+    );
     const envelope = buildTeleptyTurnCompletedEnvelope({ state: completionState, entry: completionEntry });
     notifyTeleptyBus(envelope).catch(() => {});
 

package/lib/speaker-discovery.js

@@ -106,6 +106,8 @@ export const CLI_INVOCATION_HINTS = {
   claude: { cmd: "claude", flags: '-p --output-format text', example: 'CLAUDECODE= claude -p --output-format text "prompt"', envPrefix: 'CLAUDECODE=', modelFlag: '--model', defaultModel: null, provider: 'claude' },
   codex: { cmd: "codex", flags: 'exec -', example: 'echo "prompt" | codex exec -', stdinMode: true, modelFlag: '-m', defaultModel: 'gpt-5.4', provider: 'chatgpt' },
   gemini: { cmd: "gemini", flags: '', example: 'gemini "prompt"', modelFlag: '-m', defaultModel: null, provider: 'gemini' },
+  grok: { cmd: "grok", flags: '-p', example: 'grok -p "prompt"', modelFlag: '-m', defaultModel: null, provider: 'grok' },
+  agy: { cmd: "agy", flags: '-p', example: 'agy -p "prompt"', modelFlag: '--model', defaultModel: null, provider: 'gemini' },
   aider: { cmd: "aider", flags: '--message', example: 'aider --message "prompt"', modelFlag: '--model', provider: 'chatgpt' },
   cursor: { cmd: "cursor", flags: '', example: 'cursor "prompt"', modelFlag: null, provider: 'chatgpt' },
 };
@@ -379,6 +381,12 @@ export function validateSpeakerSelectionSnapshot({ selectionState, selection_tok
     return { ok: false, code: "token_mismatch" };
   }
 
+  // ADR-264 §2.1 — token_already_consumed precedes TTL/mode checks so the
+  // caller can distinguish "was already used" from "expired" or "wrong mode".
+  if (selectionState.consumed_at) {
+    return { ok: false, code: "token_already_consumed", consumed_at: selectionState.consumed_at };
+  }
+
   const createdAtMs = Date.parse(selectionState.created_at || "");
   if (!Number.isFinite(createdAtMs) || (nowMs - createdAtMs) > SPEAKER_SELECTION_TTL_MS) {
     return { ok: false, code: "expired_token" };
@@ -424,6 +432,21 @@ export function confirmSpeakerSelectionToken({ selectionState, selection_token,
   return { ok: true, selectionState: confirmedSelection };
 }
 
+// ADR-264 §2.1 — atomic consume: stamp `consumed_at` onto the confirmed state
+// file so cross-process races surface as `token_already_consumed` instead of
+// allowing silent double-start. Callers MUST wrap the read+validate+mark
+// sequence in `withProjectLock` (index.js) to be cross-process safe.
+export function markSelectionTokenConsumed({ selectionState, nowMs = Date.now(), persist = true }) {
+  if (!selectionState || typeof selectionState !== "object") {
+    return selectionState;
+  }
+  const consumed = { ...selectionState, consumed_at: new Date(nowMs).toISOString() };
+  if (persist) {
+    _deps.writeJsonFileAtomic(_deps.getSpeakerSelectionFile(), consumed);
+  }
+  return consumed;
+}
+
 export function validateSpeakerSelectionRequest({ selectionState, selection_token, speakers, includeBrowserSpeakers, nowMs = Date.now() }) {
   const snapshotValidation = validateSpeakerSelectionSnapshot({
     selectionState,

package/lib/transport.js

@@ -89,6 +89,59 @@ export function tmuxWindowName(sessionId) {
   return sessionId.replace(/[^a-zA-Z0-9가-힣-]/g, "").slice(0, 25);
 }
 
+// #610 — Resolve the tmux window TARGET for select-window by INDEX rather than by
+// name. Window names may contain Hangul (가-힣, see tmuxWindowName), and when the
+// select-window target string is injected through the
+// osascript -> Terminal.app -> zsh -> tmux path the non-ASCII bytes get corrupted,
+// so `select-window -t "deliberation:<corrupted>"` never matches. The window INDEX
+// is pure ASCII digits and survives that path intact. node reads window names back
+// correctly (no osascript layer), so we map name -> index here.
+
+// Pure: pick the index whose window name matches `windowName` from the raw output
+// of `tmux list-windows -F '#{window_index}\t#{window_name}'`. Returns null when
+// the window is not present.
+export function parseTmuxWindowIndex(listWindowsOutput, windowName) {
+  for (const line of String(listWindowsOutput).split("\n")) {
+    const tabIdx = line.indexOf("\t");
+    if (tabIdx === -1) continue;
+    const index = line.slice(0, tabIdx).trim();
+    const name = line.slice(tabIdx + 1).trim();
+    if (name === windowName && /^\d+$/.test(index)) {
+      return Number.parseInt(index, 10);
+    }
+  }
+  return null;
+}
+
+// Pure: build the select-window target ("deliberation:<index>") from a session id
+// and the raw list-windows output. Falls back to the window name when the window
+// is not yet listed (no regression vs. prior name-based behavior).
+export function buildTmuxAttachTarget(sessionId, listWindowsOutput) {
+  const winName = tmuxWindowName(sessionId);
+  const index = parseTmuxWindowIndex(listWindowsOutput, winName);
+  const suffix = index !== null ? String(index) : winName;
+  return `${TMUX_SESSION}:${suffix}`;
+}
+
+// Impure wrapper: read the current tmux window listing. Empty string on failure
+// so buildTmuxAttachTarget falls back to the window name.
+export function listTmuxWindowsRaw(sessionName) {
+  try {
+    return execFileSync(
+      "tmux",
+      ["list-windows", "-t", sessionName, "-F", "#{window_index}\t#{window_name}"],
+      { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true }
+    );
+  } catch {
+    return "";
+  }
+}
+
+// Resolve the live select-window target for a session's monitor window.
+export function resolveTmuxWindowTarget(sessionId) {
+  return buildTmuxAttachTarget(sessionId, listTmuxWindowsRaw(TMUX_SESSION));
+}
+
 export function appleScriptQuote(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
@@ -187,10 +240,11 @@ export function tmuxWindowCount(name) {
 }
 
 export function buildTmuxAttachCommand(sessionId) {
-  const winName = tmuxWindowName(sessionId);
+  // #610 — target the window by INDEX (ASCII-safe), not by the possibly-Hangul name.
+  const winTarget = resolveTmuxWindowTarget(sessionId);
   // Use grouped session (new-session -t) so each terminal has independent active window.
   // This prevents window-switching conflicts when multiple deliberations run concurrently.
-  return `tmux new-session -t ${shellQuote(TMUX_SESSION)} \\; select-window -t ${shellQuote(`${TMUX_SESSION}:${winName}`)}`;
+  return `tmux new-session -t ${shellQuote(TMUX_SESSION)} \\; select-window -t ${shellQuote(winTarget)}`;
 }
 
 export function listPhysicalTerminalWindowIds() {
@@ -231,8 +285,12 @@ export function listPhysicalTerminalWindowIds() {
 
 export function openPhysicalTerminal(sessionId) {
   const winName = tmuxWindowName(sessionId);
+  // #610 — target the window by INDEX (ASCII-safe across the osascript path), not
+  // by the possibly-Hangul name. winName is still used below for node-side window
+  // matching (isTmuxWindowViewed / logging), which reads names correctly.
+  const winTarget = resolveTmuxWindowTarget(sessionId);
   // Use grouped session (new-session -t) for independent active window per client
-  const attachCmd = `tmux new-session -t "${TMUX_SESSION}" \\; select-window -t "${TMUX_SESSION}:${winName}"`;
+  const attachCmd = `tmux new-session -t "${TMUX_SESSION}" \\; select-window -t "${winTarget}"`;
 
   // Prevent duplicate windows for the SAME session:
   // If a client is already viewing this specific window, just activate Terminal.app
@@ -250,7 +308,7 @@ export function openPhysicalTerminal(sessionId) {
   // instead of select-window (which would hijack all attached clients' views).
   if (tmuxHasAttachedClients(TMUX_SESSION)) {
     if (process.platform === "darwin") {
-      const groupAttachCmd = `tmux new-session -t "${TMUX_SESSION}" \\; select-window -t "${TMUX_SESSION}:${winName}"`;
+      const groupAttachCmd = `tmux new-session -t "${TMUX_SESSION}" \\; select-window -t "${winTarget}"`;
       try {
         execFileSync(
           "osascript",
@@ -780,7 +838,23 @@ export async function runCliAutoTurnCore(sessionId, speaker, timeoutSec = 120) {
       channel_used: "cli_auto",
     });
 
-    return { ok: true, response, elapsedMs: Date.now() - startTime };
+    // ADR-264 §2.4 — Phase 0 observability: return envelope-ready fields so
+    // callers that aggregate results across transports see a uniform shape.
+    // CLI-specific adapters (claude/codex/gemini) are a follow-up; for now
+    // every field reports `adapter_missing` and downstream aggregators MUST
+    // skip entries where status !== "ok" before arithmetic.
+    return {
+      ok: true,
+      response,
+      elapsedMs: Date.now() - startTime,
+      observability: {
+        tokens_in: { value: null, status: "adapter_missing" },
+        tokens_out: { value: null, status: "adapter_missing" },
+        estimated_cost_usd: { value: null, status: "adapter_missing" },
+        model_reported_by_cli: { value: null, status: "adapter_missing" },
+        actual_model_id: { value: null, status: "adapter_missing" },
+      },
+    };
   } catch (err) {
     return { ok: false, error: err.message };
   }
@@ -1128,6 +1202,22 @@ export async function runAutoHandoff(sessionId) {
   const retryConfig = { maxRetries: 2, retryDelayMs: 10000 };
 
   try {
+    // Pre-flight: if every speaker matches the orchestrator's CLI identity, there is
+    // no one to auto-dispatch. Halt Phase 1 and skip Phase 2 synthesis so the session
+    // remains `active` and the orchestrator can provide turns manually.
+    {
+      const initialState = loadSession(sessionId);
+      const callerId = detectCallerSpeaker();
+      if (initialState && callerId && Array.isArray(initialState.speakers) && initialState.speakers.length > 0) {
+        const normalizedCaller = normalizeSpeaker(callerId);
+        const allSelf = initialState.speakers.every(s => normalizeSpeaker(s) === normalizedCaller);
+        if (allSelf) {
+          _deps.appendRuntimeLog("WARN", `AUTO_HANDOFF_ALL_SELF_TURN: ${sessionId} | all speakers match caller identity "${normalizedCaller}" | halting auto-dispatch; orchestrator must proceed manually`);
+          return;
+        }
+      }
+    }
+
     // Phase 1: Run all deliberation turns
     let maxIterations = 100; // safety limit
     while (maxIterations-- > 0) {
@@ -1157,10 +1247,19 @@ export async function runAutoHandoff(sessionId) {
           break;
         }
 
-        // self_turn blocks should break immediately — the orchestrator itself is the speaker
+        // self_turn: orchestrator is the speaker. The defensive guard at runUntilBlockedCore
+        // prevented a recursive CLI spawn; here we submit a visible placeholder so the session
+        // can advance to the next speaker rather than aborting Phase 1 entirely.
         if (runResult.block_reason === "self_turn") {
-          _deps.appendRuntimeLog("WARN", `AUTO_HANDOFF_SELF_TURN: ${sessionId} | speaker: ${speaker} | breaking`);
-          turnSucceeded = false;
+          _deps.appendRuntimeLog("WARN", `AUTO_HANDOFF_SELF_TURN_SKIP: ${sessionId} | speaker: ${speaker} | submitting placeholder and advancing`);
+          submitDeliberationTurn({
+            session_id: sessionId,
+            speaker,
+            content: `[SELF_TURN_SKIP] Speaker ${speaker} matches the orchestrator identity; auto-dispatch skipped to avoid recursive self-spawn. The orchestrator may contribute this speaker's input manually via deliberation_respond before synthesis.`,
+            channel_used: "self_turn_skip",
+            fallback_reason: "caller_identity_match",
+          });
+          turnSucceeded = true; // placeholder submitted, advance to next speaker
           break;
         }
 

package/logger-emit.js

@@ -0,0 +1,119 @@
+// δ2 Phase 3 (#440) — deliberation emitter wrapper.
+//
+// Library-context emit. The deliberation MCP server is consumed by many
+// session roles (orchestrator/coder/architect/...), so we cannot
+// fabricate a Role when AIGENTRY_ROLE is unset: per the Phase 2 ACK
+// decision (option B), we emit-skip-with-warning so telemetry stays
+// clean of synthetic attribution. Warning fires once per process.
+//
+// Schema mapping per orchestrator A1 decision:
+//   spec event       → ssot kind        + payload.subtype
+//   turn_event       → state-change     + turn_start | turn_complete
+//   synthesis_event  → report           + synthesis
+//   handoff_event    → report           + handoff_v2
+//
+// ESM module (package.json "type": "module"). @dmsdc-ai/aigentry-logger is also
+// ESM — direct `import` works.
+//
+// Failure mode (§9 독립): transport errors swallowed via try/catch.
+
+import { emit as loggerEmit } from "@dmsdc-ai/aigentry-logger";
+
+const VALID_ROLES = new Set([
+  "orchestrator",
+  "architect",
+  "coder",
+  "tester",
+  "builder",
+  "analyst",
+  "researcher",
+  "reviewer",
+  "logger",
+]);
+
+let _warnedRoleUnset = false;
+function warnOnceRoleUnset() {
+  if (_warnedRoleUnset) return;
+  _warnedRoleUnset = true;
+  try {
+    console.warn(
+      "[logger] emit skipped: AIGENTRY_ROLE unset (this is normal for library context)",
+    );
+  } catch (_e) {
+    /* noop */
+  }
+}
+
+export function __resetRoleWarningForTests() {
+  _warnedRoleUnset = false;
+}
+
+export function resolveContext(env = process.env) {
+  const session_id = env.AIGENTRY_SESSION_ID || `pid-${process.pid}`;
+  const rawRole = env.AIGENTRY_ROLE;
+  if (rawRole && VALID_ROLES.has(rawRole)) {
+    return { session_id, role: rawRole };
+  }
+  return { session_id, role: null };
+}
+
+export function emitTelemetry(input, opts = {}) {
+  const env = opts.env || process.env;
+  if (env.AIGENTRY_LOGGER_DISABLED === "1") return;
+  const ctx = resolveContext(env);
+  if (ctx.role === null) {
+    warnOnceRoleUnset();
+    return;
+  }
+  const now = opts.now || (() => new Date());
+  const event = {
+    schema_version: "1",
+    kind: input.kind,
+    session_id: ctx.session_id,
+    role: ctx.role,
+    emitted_at: now().toISOString(),
+    payload: input.payload || {},
+  };
+  if (input.correlation_id) event.correlation_id = input.correlation_id;
+  const sink = opts.__emit || loggerEmit;
+  try {
+    sink(event);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    try {
+      console.error(`[deliberation:logger-emit] telemetry emit failed: ${msg}`);
+    } catch (_e) {
+      /* noop */
+    }
+  }
+}
+
+export function emitTurnEvent(subtype, payload, correlationId) {
+  emitTelemetry(
+    {
+      kind: "state-change",
+      payload: { subtype, ...(payload || {}) },
+      ...(correlationId ? { correlation_id: correlationId } : {}),
+    },
+  );
+}
+
+export function emitSynthesisEvent(payload, correlationId) {
+  emitTelemetry(
+    {
+      kind: "report",
+      payload: { subtype: "synthesis", ...(payload || {}) },
+      ...(correlationId ? { correlation_id: correlationId } : {}),
+    },
+  );
+}
+
+export function emitHandoffEvent(payload, correlationId) {
+  emitTelemetry(
+    {
+      kind: "report",
+      payload: { subtype: "handoff_v2", ...(payload || {}) },
+      ...(correlationId ? { correlation_id: correlationId } : {}),
+    },
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-deliberation",
-  "version": "0.0.43",
+  "version": "0.0.47",
   "description": "MCP server for structured multi-AI discussions — deliberate across Claude, GPT, Gemini and more before committing to decisions",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,7 @@
     "observer.js",
     "browser-control-port.js",
     "degradation-state-machine.js",
+    "logger-emit.js",
     "session-monitor.sh",
     "session-monitor-win.js",
     "selectors/**",
@@ -59,6 +60,7 @@
     "release:major": "npm version major && git push && git push --tags"
   },
   "dependencies": {
+    "@dmsdc-ai/aigentry-logger": "^0.2.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ws": "^8.18.0"
   },