@linkedclaw/cli 0.1.3 → 0.1.6

package/src/commands/converge.ts

@@ -0,0 +1,969 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { Command } from "commander";
+import { runCommand } from "../output.js";
+import { buildContext, type CliContext } from "../context.js";
+import { LinkedClawError } from "../errors.js";
+import { makeConvergeApi } from "../converge/api.js";
+import { sha256OfCanonicalJson } from "../converge/hash.js";
+import { acquireLock } from "../converge/lock.js";
+import {
+  computePaBodyHash,
+  dumpStaging,
+  listCruxFiles,
+  readStaging,
+  stagingPathFor,
+  writeStaging,
+  type StagingFrontmatter,
+} from "../converge/staging.js";
+import { readRunMeta, resolveWorkspace, writeRunMeta } from "../converge/workspace.js";
+import type {
+  CommonsLogEvent,
+  ConvergenceAttestation,
+  ConvergenceDecisionAction,
+  CruxDecisionRequest,
+  RunMeta,
+  RunStateSummary,
+  RunWorkspace,
+} from "../converge/types.js";
+
+// ─── inline helpers ──────────────────────────────────────────────────────────
+
+function resolveAbs(p: string): string {
+  return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+
+async function getMyUserId(ctx: CliContext): Promise<string> {
+  const me = await ctx.consumer.getMe();
+  if (!me.user_id) throw new LinkedClawError("no_user_id", "Could not determine user_id from /api/v1/me");
+  return me.user_id;
+}
+
+function recomputeSourceCruxMapHash(events: CommonsLogEvent[]): string | null {
+  const ev = [...events].reverse().find((e) => e.event_type === "crux_map");
+  if (!ev) return null;
+  return sha256OfCanonicalJson(ev.payload.crux_map_data);
+}
+
+function recordedSourceHash(events: CommonsLogEvent[]): string | null {
+  const ev = events.find((e) => e.event_type === "run_started");
+  if (!ev) return null;
+  return typeof ev.payload.source_crux_map_hash === "string" ? ev.payload.source_crux_map_hash : null;
+}
+
+function buildPaBody(op: Record<string, unknown>): string {
+  const synthesis = typeof op.synthesis_text === "string" ? op.synthesis_text : "";
+  const questions = Array.isArray(op.open_questions) ? op.open_questions : [];
+  const qText = questions.map((q: unknown) => `- ${String(q)}`).join("\n");
+  return `# Synthesis\n\n${synthesis}\n\n# Open questions\n\n${qText || "(none)"}\n`;
+}
+
+function countPreviouslyClarifiedSections(body: string): number {
+  const m = body.match(/^# Previously clarified \(round \d+\)/gm);
+  return m ? m.length : 0;
+}
+
+function slugify(s: string, maxLen = 64): string {
+  const base = s.trim().toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, maxLen)
+    .replace(/-+$/g, "");
+  return base || "untitled";
+}
+
+function extractSynthesisSlug(body: string, maxLen = 32): string {
+  const synthIdx = body.indexOf("# Synthesis");
+  const search = synthIdx >= 0 ? body.slice(synthIdx) : body;
+  const lines = search.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+  const first = lines[0] ?? "";
+  return slugify(first, maxLen);
+}
+
+function tryGitAdd(absPath: string): string | null {
+  try {
+    const r = spawnSync("git", ["add", absPath], { encoding: "utf8" });
+    if (r.error) return `git_add_failed: ${r.error.message}`;
+    if (r.status !== 0) return `git_add_failed: ${(r.stderr || "").trim() || `exit ${r.status}`}`;
+    return null;
+  } catch (e) {
+    return `git_add_failed: ${(e as Error).message}`;
+  }
+}
+
+function assertSafeCruxId(cruxId: string): void {
+  if (!cruxId || cruxId.includes("/") || cruxId.includes("\\") || cruxId.includes("..") || cruxId.includes("\0")) {
+    throw new LinkedClawError("invalid_crux_id", `Invalid crux_id for local file operation: ${cruxId}`);
+  }
+}
+
+function assertInside(parentDir: string, childPath: string): void {
+  const parent = resolve(parentDir);
+  const child = resolve(childPath);
+  const rel = relative(parent, child);
+  if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))) return;
+  throw new LinkedClawError("path_escape", `Refusing local path outside ${parentDir}: ${childPath}`);
+}
+
+function safeStagingPathFor(stagingDir: string, cruxId: string): string {
+  assertSafeCruxId(cruxId);
+  const path = stagingPathFor(stagingDir, cruxId);
+  assertInside(stagingDir, path);
+  return path;
+}
+
+function safeAcceptedPath(finalDir: string, cruxId: string, synthSlug: string): string {
+  assertSafeCruxId(cruxId);
+  const path = join(finalDir, `${cruxId}__${synthSlug}.md`);
+  assertInside(finalDir, path);
+  return path;
+}
+
+function computeDecisionBodyHash(
+  synthesisText: string,
+  citationsA: Array<Record<string, unknown>>,
+  citationsB: Array<Record<string, unknown>>,
+): string {
+  return sha256OfCanonicalJson({
+    citations_a: citationsA,
+    citations_b: citationsB,
+    synthesis_text: synthesisText,
+  });
+}
+
+function eventKind(ev: CommonsLogEvent): string {
+  return typeof ev.payload.event_type === "string" ? ev.payload.event_type : ev.event_type;
+}
+
+function decisionEventTypeForAction(action: ConvergenceDecisionAction): string {
+  if (action === "accept") return "accept_attestation";
+  if (action === "reject") return "reject_attestation";
+  return "attest_only";
+}
+
+function latestConvergenceMapEvent(events: CommonsLogEvent[]): CommonsLogEvent {
+  const operatorUserId = process.env.LINKEDCLAW_OPERATOR_USER_ID ?? "usr_operator";
+  const reversed = [...events].reverse();
+  const ev = reversed.find((e) => eventKind(e) === "convergence_map" && e.signed_by === operatorUserId);
+  if (!ev) {
+    throw new LinkedClawError(
+      "convergence_map_not_found",
+      `No PA-signed convergence_map event found for this run (expected signed_by=${operatorUserId}).`,
+    );
+  }
+  return ev;
+}
+
+function latestConvergenceMap(events: CommonsLogEvent[]): Record<string, unknown> {
+  return latestConvergenceMapEvent(events).payload;
+}
+
+function getCruxFromMap(map: Record<string, unknown>, cruxId: string): Record<string, unknown> {
+  const cruxes = Array.isArray(map.cruxes) ? map.cruxes : [];
+  const crux = cruxes.find(
+    (c: unknown) => c && typeof c === "object" && (c as Record<string, unknown>).crux_id === cruxId,
+  );
+  if (!crux || typeof crux !== "object") {
+    throw new LinkedClawError("crux_not_found", `crux ${cruxId} not found in latest convergence_map.`);
+  }
+  return crux as Record<string, unknown>;
+}
+
+function citationsFromCrux(value: unknown): Array<Record<string, unknown>> {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v): v is Record<string, unknown> => v != null && typeof v === "object" && !Array.isArray(v));
+}
+
+function classifyDecisionAttestation(
+  action: ConvergenceDecisionAction,
+  outcome: string,
+  bilateralMandateIntact: boolean,
+  synthesisEdited = false,
+): ConvergenceAttestation {
+  if (action === "attest") return "user_attested_no_dialog";
+  if (action === "reject") return "user_attested_with_network_context";
+  if (outcome === "already_aligned") {
+    throw new LinkedClawError(
+      "attest_required",
+      "outcome=already_aligned must be decided with `lc converge attest`.",
+    );
+  }
+  if ((outcome === "converged" || outcome === "partial_overlap") && bilateralMandateIntact && !synthesisEdited) {
+    return "bilateral_convergence";
+  }
+  return "user_attested_with_network_context";
+}
+
+function decisionPayloadCitations(value: unknown): Array<Record<string, unknown>> {
+  return citationsFromCrux(value);
+}
+
+function stringFromPayload(payload: Record<string, unknown>, key: string): string {
+  const value = payload[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new LinkedClawError("decision_payload_invalid", `terminal decision missing ${key}.`);
+  }
+  return value;
+}
+
+function booleanFromPayload(payload: Record<string, unknown>, key: string): boolean {
+  const value = payload[key];
+  if (typeof value !== "boolean") {
+    throw new LinkedClawError("decision_payload_invalid", `terminal decision missing ${key}.`);
+  }
+  return value;
+}
+
+function attestationFromPayload(payload: Record<string, unknown>): ConvergenceAttestation {
+  const value = stringFromPayload(payload, "attestation");
+  if (
+    value !== "bilateral_convergence" &&
+    value !== "user_attested_with_network_context" &&
+    value !== "user_attested_no_dialog"
+  ) {
+    throw new LinkedClawError("decision_payload_invalid", `terminal decision has invalid attestation: ${value}`);
+  }
+  return value;
+}
+
+function terminalOutcomeFromPayload(payload: Record<string, unknown>): StagingFrontmatter["outcome"] {
+  const value = stringFromPayload(payload, "terminal_outcome");
+  if (
+    value !== "converged" &&
+    value !== "partial_overlap" &&
+    value !== "needs_input" &&
+    value !== "irreconcilable" &&
+    value !== "already_aligned"
+  ) {
+    throw new LinkedClawError("decision_payload_invalid", `terminal decision has invalid outcome: ${value}`);
+  }
+  return value;
+}
+
+async function buildCruxDecisionRequest(
+  api: ReturnType<typeof makeConvergeApi>,
+  ws: RunWorkspace,
+  cruxId: string,
+  action: ConvergenceDecisionAction,
+  opts: { message?: string } = {},
+): Promise<CruxDecisionRequest> {
+  assertSafeCruxId(cruxId);
+  const { events } = await api.getCommonsLogEvents(ws.runId, { limit: 5000 });
+  const map = latestConvergenceMap(events);
+  const crux = getCruxFromMap(map, cruxId);
+  const generationId = typeof crux.generation_id === "string" ? crux.generation_id : "";
+  const sourceHash = typeof map.source_crux_map_hash === "string" ? map.source_crux_map_hash : "";
+  const outcome = typeof crux.outcome === "string" ? crux.outcome : "";
+  const latestSubDebateId =
+    typeof crux.latest_sub_debate_id === "string" ? crux.latest_sub_debate_id : null;
+  const bilateralMandateIntact =
+    typeof crux.bilateral_mandate_intact_at_outcome === "boolean"
+      ? crux.bilateral_mandate_intact_at_outcome
+      : typeof crux.bilateral_mandate_intact === "boolean"
+        ? crux.bilateral_mandate_intact
+        : false;
+  const synthesisText = typeof crux.synthesis_text === "string" ? crux.synthesis_text : "";
+  const citationsA = citationsFromCrux(crux.citations_a);
+  const citationsB = citationsFromCrux(crux.citations_b);
+
+  if (!generationId) throw new LinkedClawError("missing_generation_id", `crux ${cruxId} has no generation_id.`);
+  if (!sourceHash) throw new LinkedClawError("missing_source_hash", "latest convergence_map has no source_crux_map_hash.");
+  if (!outcome) throw new LinkedClawError("missing_outcome", `crux ${cruxId} has no outcome.`);
+  if (action === "accept" && outcome === "already_aligned") {
+    throw new LinkedClawError(
+      "attest_required",
+      "outcome=already_aligned must be decided with `lc converge attest`.",
+    );
+  }
+  if (!synthesisText) throw new LinkedClawError("missing_synthesis_text", `crux ${cruxId} has no synthesis_text.`);
+
+  const paBodyHash = computeDecisionBodyHash(synthesisText, citationsA, citationsB);
+  let acceptedSynthesisText = synthesisText;
+  let synthesisEdited = false;
+  if (action === "accept") {
+    const stagingPath = safeStagingPathFor(ws.stagingDir, cruxId);
+    if (existsSync(stagingPath)) {
+      const doc = readStaging(stagingPath);
+      synthesisEdited = computePaBodyHash(doc.body) !== doc.frontmatter.pa_body_hash;
+      if (synthesisEdited) acceptedSynthesisText = doc.body;
+    }
+  }
+  const acceptedBodyHash = computeDecisionBodyHash(acceptedSynthesisText, citationsA, citationsB);
+  return {
+    convergence_map_generation_id: generationId,
+    source_crux_map_hash: sourceHash,
+    latest_sub_debate_id: latestSubDebateId,
+    terminal_outcome: outcome as CruxDecisionRequest["terminal_outcome"],
+    bilateral_mandate_intact: bilateralMandateIntact,
+    attestation: classifyDecisionAttestation(action, outcome, bilateralMandateIntact, synthesisEdited),
+    synthesis_edited: synthesisEdited,
+    pa_body_hash: paBodyHash,
+    accepted_body_hash: acceptedBodyHash,
+    synthesis_text: acceptedSynthesisText,
+    citations_a: citationsA,
+    citations_b: citationsB,
+    ...(opts.message ? { user_message: opts.message } : {}),
+  };
+}
+
+async function postCruxDecision(
+  api: ReturnType<typeof makeConvergeApi>,
+  ws: RunWorkspace,
+  cruxId: string,
+  action: ConvergenceDecisionAction,
+  opts: { message?: string } = {},
+): Promise<{ event_id: string; body: CruxDecisionRequest }> {
+  assertSafeCruxId(cruxId);
+  const body = await buildCruxDecisionRequest(api, ws, cruxId, action, opts);
+  const resp =
+    action === "accept"
+      ? await api.acceptCruxDecision(ws.runId, cruxId, body)
+      : action === "reject"
+        ? await api.rejectCruxDecision(ws.runId, cruxId, body)
+        : await api.attestCruxDecision(ws.runId, cruxId, body);
+  return { event_id: resp.event_id, body };
+}
+
+async function materializeAcceptedCrux(
+  ctx: CliContext,
+  api: ReturnType<typeof makeConvergeApi>,
+  ws: RunWorkspace,
+  cruxId: string,
+  payload: Record<string, unknown>,
+  opts: { message?: string } = {},
+): Promise<{ accepted_path?: string; attestation?: ConvergenceAttestation; synthesis_edited?: boolean; warning?: string }> {
+  const stagingPath = safeStagingPathFor(ws.stagingDir, cruxId);
+  if (!existsSync(stagingPath)) return { warning: `staging_not_found: ${stagingPath}` };
+
+  const doc = readStaging(stagingPath);
+  const fm = doc.frontmatter;
+  const sourceDebate = await api.getDebate(ws.sourceDebateId);
+  const body = stringFromPayload(payload, "synthesis_text");
+  const citationsA = decisionPayloadCitations(payload.citations_a);
+  const citationsB = decisionPayloadCitations(payload.citations_b);
+  const acceptedBodyHash = stringFromPayload(payload, "accepted_body_hash");
+  const computedAcceptedBodyHash = computeDecisionBodyHash(body, citationsA, citationsB);
+  if (acceptedBodyHash !== computedAcceptedBodyHash) {
+    return { warning: `decision_body_hash_mismatch: ${cruxId}` };
+  }
+  const paBodyHash = stringFromPayload(payload, "pa_body_hash");
+  const synthesisEdited = booleanFromPayload(payload, "synthesis_edited");
+  const attestation = attestationFromPayload(payload);
+  const terminalOutcome = terminalOutcomeFromPayload(payload);
+  const generationId = stringFromPayload(payload, "convergence_map_generation_id");
+  const me = await getMyUserId(ctx);
+  const acceptedDoc = {
+    frontmatter: {
+      ...fm,
+      generation_id: generationId,
+      pa_body_hash: paBodyHash,
+      outcome: terminalOutcome,
+      bilateral_mandate_intact: booleanFromPayload(payload, "bilateral_mandate_intact"),
+      citations_a: citationsA,
+      citations_b: citationsB,
+      provenance: {
+        signed_off_by: me,
+        signed_off_at: new Date().toISOString(),
+        accepted_generation_id: generationId,
+        attestation,
+        synthesis_edited: synthesisEdited,
+        ...(opts.message ? { user_message: opts.message } : {}),
+        ...(synthesisEdited
+          ? { pa_body_hash: paBodyHash, accepted_body_hash: acceptedBodyHash }
+          : {}),
+      },
+    },
+    userResponse: "",
+    body,
+  };
+  const topicSlug = slugify(sourceDebate.topic ?? ws.sourceDebateId);
+  const synthSlug = extractSynthesisSlug(body);
+  const finalDir = join(ws.targetCorpus, "converged", topicSlug);
+  const finalPath = safeAcceptedPath(finalDir, cruxId, synthSlug);
+
+  if (existsSync(finalPath) && readStaging(finalPath).body !== acceptedDoc.body) {
+    return { warning: `sync_conflict: ${finalPath}` };
+  }
+  mkdirSync(finalDir, { recursive: true });
+  if (!existsSync(finalPath) || dumpStaging(readStaging(finalPath)) !== dumpStaging(acceptedDoc)) {
+    writeStaging(finalPath, acceptedDoc);
+  }
+  unlinkSync(stagingPath);
+  const gitWarning = tryGitAdd(finalPath);
+  return {
+    accepted_path: finalPath,
+    attestation,
+    synthesis_edited: synthesisEdited,
+    ...(gitWarning ? { warning: gitWarning } : {}),
+  };
+}
+
+async function syncTerminalDecisions(
+  ctx: CliContext,
+  api: ReturnType<typeof makeConvergeApi>,
+  ws: RunWorkspace,
+  opts: {
+    cruxId?: string;
+    message?: string;
+    injectedTerminal?: { cruxId: string; eventType: string; payload: Record<string, unknown> };
+  } = {},
+): Promise<{ materialized: string[]; cleaned: string[]; warnings: string[] }> {
+  if (opts.cruxId) assertSafeCruxId(opts.cruxId);
+  const { events } = await api.getCommonsLogEvents(ws.runId, { limit: 5000 });
+  const warnings: string[] = [];
+  const mapEvent = latestConvergenceMapEvent(events);
+  const map = mapEvent.payload;
+  const cruxGeneration = new Map<string, string>();
+  for (const crux of Array.isArray(map.cruxes) ? map.cruxes : []) {
+    if (!crux || typeof crux !== "object" || Array.isArray(crux)) continue;
+    const c = crux as Record<string, unknown>;
+    if (typeof c.crux_id === "string" && typeof c.generation_id === "string") {
+      cruxGeneration.set(c.crux_id, c.generation_id);
+    }
+  }
+  const terminal = new Map<string, { eventType: string; payload: Record<string, unknown> }>();
+  for (const ev of [...events].sort((a, b) => a.seq - b.seq)) {
+    if (ev.seq <= mapEvent.seq) continue;
+    if (ev.signed_by !== mapEvent.signed_by) continue;
+    const eventType = eventKind(ev);
+    if (!["accept_attestation", "reject_attestation", "attest_only"].includes(eventType)) continue;
+    const cid = typeof ev.payload.crux_id === "string" ? ev.payload.crux_id : "";
+    if (!cid || terminal.has(cid)) continue;
+    try {
+      assertSafeCruxId(cid);
+    } catch (err) {
+      warnings.push(`${cid}: ${(err as Error).message}`);
+      continue;
+    }
+    if (ev.payload.convergence_map_generation_id !== cruxGeneration.get(cid)) continue;
+    terminal.set(cid, { eventType, payload: ev.payload });
+  }
+  if (opts.injectedTerminal) {
+    assertSafeCruxId(opts.injectedTerminal.cruxId);
+    terminal.set(opts.injectedTerminal.cruxId, {
+      eventType: opts.injectedTerminal.eventType,
+      payload: opts.injectedTerminal.payload,
+    });
+  }
+
+  const materialized: string[] = [];
+  const cleaned: string[] = [];
+  const release = acquireLock(ws.stagingDir);
+  try {
+    for (const [cid, terminalEvent] of terminal.entries()) {
+      if (opts.cruxId && cid !== opts.cruxId) continue;
+      const stagingPath = safeStagingPathFor(ws.stagingDir, cid);
+      const eventType = terminalEvent.eventType;
+      if (eventType === "accept_attestation") {
+        const result = await materializeAcceptedCrux(ctx, api, ws, cid, terminalEvent.payload, opts);
+        if (result.accepted_path) materialized.push(result.accepted_path);
+        if (result.warning) warnings.push(`${cid}: ${result.warning}`);
+        continue;
+      }
+      if (existsSync(stagingPath)) {
+        unlinkSync(stagingPath);
+        cleaned.push(cid);
+      }
+    }
+  } finally {
+    release();
+  }
+  return { materialized, cleaned, warnings };
+}
+
+// ─── command registration ─────────────────────────────────────────────────────
+
+export function registerConvergeCommands(program: Command): void {
+  const converge = program
+    .command("converge")
+    .description("Convergence: bilateral merger of two crux maps into shared corpus");
+
+  converge
+    .command("run [ref]")
+    .description("Start a convergence run (Owner A) or accept (Owner B with --accept), then sync staging")
+    .option("--target-corpus <path>", "Absolute path to the target corpus directory")
+    .option("--staging-dir <path>", "Override staging directory")
+    .option("--accept", "Owner B: accept an existing run by run_id")
+    .option("--source-debate-id <id>", "Owner B fallback when /convergence/runs/{run_id} is unavailable")
+    .option("--force-regenerate", "Bypass source-hash drift check and regenerate staging files")
+    .option("--wait <secs>", "Poll until terminal_emitted or timeout", parseInt)
+    .action(
+      async (
+        ref: string | undefined,
+        opts: {
+          targetCorpus?: string;
+          stagingDir?: string;
+          accept?: boolean;
+          sourceDebateId?: string;
+          forceRegenerate?: boolean;
+          wait?: number;
+        },
+      ) => {
+        await runCommand(async () => {
+          const ctx = buildContext();
+          if (!ctx.cfg.apiKey) throw new LinkedClawError("missing_api_key", "Run `linkedclaw login` first.");
+          const api = makeConvergeApi(ctx.cfg.cloudUrl, ctx.cfg.apiKey);
+
+          let ws: RunWorkspace;
+          const resolvedStagingDir = opts.stagingDir ? resolveAbs(opts.stagingDir) : null;
+          const metaExisting = resolvedStagingDir ? readRunMeta(resolvedStagingDir) : null;
+
+          if (opts.accept) {
+            // Owner B path: ref = run_id
+            if (!ref) {
+              throw new LinkedClawError("missing_run_id", "--accept requires the run_id as a positional argument.");
+            }
+            const runId = ref;
+            if (metaExisting && resolvedStagingDir) {
+              const meta = metaExisting;
+              ws = {
+                runId: meta.run_id,
+                sourceDebateId: meta.source_debate_id,
+                paAgentId: meta.pa_agent_id,
+                targetCorpus: meta.target_corpus,
+                stagingDir: resolvedStagingDir,
+              };
+            } else {
+              if (!opts.targetCorpus) {
+                throw new LinkedClawError(
+                  "missing_target_corpus",
+                  "Owner B --accept requires --target-corpus on first call.",
+                );
+              }
+              const targetCorpus = resolveAbs(opts.targetCorpus);
+              // Owner B can't read the run-log until they accept (membership
+              // gate). Default path: GET /convergence/runs/{run_id}. Fallback:
+              // user passes --source-debate-id explicitly for older servers.
+              let sourceDebateId: string;
+              let paAgentId: string;
+              let principalAgentId: string;
+              if (opts.sourceDebateId) {
+                sourceDebateId = opts.sourceDebateId;
+                paAgentId = await api.discoverPaAgentId();
+                const sourceDebate = await api.getDebate(sourceDebateId);
+                principalAgentId = sourceDebate.agent_b_id;
+              } else {
+                const runMeta = await api.getRun(runId);
+                sourceDebateId = runMeta.source_debate_id;
+                paAgentId = runMeta.pa_agent_id;
+                principalAgentId = runMeta.agent_b_id;
+              }
+              const existing = await api.findExistingMandate(principalAgentId, paAgentId, ["debate.create", "debate.accept"]);
+              if (!existing) await api.issueMandate(principalAgentId, paAgentId, ["debate.create", "debate.accept"]);
+              await api.acceptOwnerB(runId);
+              const stagingDir = join(targetCorpus, "converged", "staging", runId);
+              mkdirSync(stagingDir, { recursive: true });
+              const meta: RunMeta = {
+                run_id: runId,
+                source_debate_id: sourceDebateId,
+                pa_agent_id: paAgentId,
+                target_corpus: targetCorpus,
+                owner_role: "b",
+              };
+              writeRunMeta(stagingDir, meta);
+              ws = { runId, sourceDebateId, paAgentId, targetCorpus, stagingDir };
+            }
+          } else if (!metaExisting) {
+            // Owner A first call: ref = source_debate_id
+            if (!ref) {
+              throw new LinkedClawError(
+                "missing_source_debate_id",
+                "First run requires a source_debate_id argument. Use --staging-dir to resume an existing run.",
+              );
+            }
+            if (!opts.targetCorpus) {
+              throw new LinkedClawError("missing_target_corpus", "First call requires --target-corpus.");
+            }
+            const targetCorpus = resolveAbs(opts.targetCorpus);
+            const paAgentId = await api.discoverPaAgentId();
+            // Owner A's principal_agent_id is the source debate's agent_a_id.
+            // start_run will look up the mandate keyed on that agent.
+            const sourceDebate = await api.getDebate(ref);
+            const principalAgentId = sourceDebate.agent_a_id;
+            const existing = await api.findExistingMandate(principalAgentId, paAgentId, ["debate.create", "debate.accept"]);
+            if (!existing) await api.issueMandate(principalAgentId, paAgentId, ["debate.create", "debate.accept"]);
+            const { run_id } = await api.startRun(ref);
+            const stagingDir = join(targetCorpus, "converged", "staging", run_id);
+            mkdirSync(stagingDir, { recursive: true });
+            const meta: RunMeta = {
+              run_id,
+              source_debate_id: ref,
+              pa_agent_id: paAgentId,
+              target_corpus: targetCorpus,
+              owner_role: "a",
+            };
+            writeRunMeta(stagingDir, meta);
+            ws = { runId: run_id, sourceDebateId: ref, paAgentId, targetCorpus, stagingDir };
+          } else {
+            // Subsequent call: use existing meta from stagingDir
+            ws = await resolveWorkspace({ stagingDir: opts.stagingDir });
+          }
+
+          // ─── helper: write per-crux staging files from current crux list ─
+          const refreshStaging = async (
+            cruxes: RunStateSummary["cruxes"],
+            canonicalSourceHash: string,
+          ): Promise<void> => {
+            for (const c of cruxes) {
+              if (!c.latest_sub_debate_id) continue;
+              const subD = await api.getDebate(c.latest_sub_debate_id);
+              const subEvs = await api.getCommonsLogEvents(subD.commons_log_id, { limit: 2000 });
+              const outcomeEv = [...subEvs.events]
+                .reverse()
+                .find(
+                  (e) =>
+                    (e.payload as any).event_type === "convergence_outcome" ||
+                    e.event_type === "convergence_outcome",
+                );
+              if (!outcomeEv) continue;
+              const op = outcomeEv.payload as Record<string, unknown>;
+              const body = buildPaBody(op);
+              const newPaBodyHash = computePaBodyHash(body);
+              const path = safeStagingPathFor(ws.stagingDir, c.crux_id);
+              const existingDoc = existsSync(path) ? readStaging(path) : null;
+              // Skip overwrite when PA hasn't emitted new content — preserves Step 1 clarification history
+              if (existingDoc && existingDoc.frontmatter.pa_body_hash === newPaBodyHash) continue;
+              const fm: StagingFrontmatter = {
+                debate_id: ws.sourceDebateId,
+                run_id: ws.runId,
+                crux_id: c.crux_id,
+                sub_debate_chain: c.sub_debate_chain,
+                latest_sub_debate_id: c.latest_sub_debate_id,
+                source_crux_map_hash: canonicalSourceHash,
+                generation_id: `gen_${ws.runId.slice(-8)}`,
+                generated_at: new Date().toISOString(),
+                pa_body_hash: newPaBodyHash,
+                outcome: (op.outcome ?? c.outcome) as StagingFrontmatter["outcome"],
+                bilateral_mandate_intact:
+                  typeof op.bilateral_mandate_intact === "boolean"
+                    ? op.bilateral_mandate_intact
+                    : (c.bilateral_mandate_intact ?? false),
+                citations_a: Array.isArray(op.citations_a) ? op.citations_a : [],
+                citations_b: Array.isArray(op.citations_b) ? op.citations_b : [],
+                mod_progress_summary:
+                  op.final_progress_signal != null &&
+                  typeof op.final_progress_signal === "object" &&
+                  !Array.isArray(op.final_progress_signal)
+                    ? (op.final_progress_signal as Record<string, unknown>)
+                    : {},
+                attested_by_user: existingDoc?.frontmatter.attested_by_user ?? false,
+              };
+              writeStaging(path, { frontmatter: fm, userResponse: existingDoc?.userResponse ?? "", body });
+            }
+          };
+
+          // ─── acquire lock for Steps 1–4 ──────────────────────────────────
+          let summary!: RunStateSummary;
+          let canonicalSourceHash = "";
+
+          {
+            const release = acquireLock(ws.stagingDir);
+            try {
+              // ─── Step 1: ingest pending _user_response blocks ──────────────
+              for (const fn of listCruxFiles(ws.stagingDir)) {
+                const path = join(ws.stagingDir, fn);
+                const doc = readStaging(path);
+                const text = (doc.userResponse || "").trim();
+                if (!text) continue;
+                const subDebateId = doc.frontmatter.latest_sub_debate_id;
+                if (!subDebateId) continue;
+                const subDebate = await api.getDebate(subDebateId);
+                await api.appendCommonsLog(subDebate.commons_log_id, "owner_clarification", {
+                  event_type: "owner_clarification",
+                  content: text,
+                  in_response_to_event_id: null,
+                });
+                const round = countPreviouslyClarifiedSections(doc.body) + 1;
+                doc.userResponse = "";
+                doc.body = doc.body.trimEnd() + `\n\n# Previously clarified (round ${round})\n\n${text}\n`;
+                writeStaging(path, doc);
+              }
+
+              // ─── Step 2: sync from run-log ─────────────────────────────────
+              const { events } = await api.getCommonsLogEvents(ws.runId, { limit: 5000 });
+              summary = reduceRunState(ws, events);
+
+              // ─── Step 3: integrity guard ───────────────────────────────────
+              const sourceDebate = await api.getDebate(ws.sourceDebateId);
+              const sourceEvents = await api.getCommonsLogEvents(sourceDebate.commons_log_id, {
+                limit: 2000,
+              });
+              const liveSourceHash = recomputeSourceCruxMapHash(sourceEvents.events);
+              const recordedHash = recordedSourceHash(events);
+              if (recordedHash && liveSourceHash && liveSourceHash !== recordedHash && !opts.forceRegenerate) {
+                throw new LinkedClawError(
+                  "source_crux_map_drift",
+                  `Source crux-map changed since run started (recorded=${recordedHash} live=${liveSourceHash}). Re-run with --force-regenerate.`,
+                );
+              }
+              canonicalSourceHash = recordedHash ?? liveSourceHash ?? "";
+
+              // ─── Step 4: per-crux staging file refresh ─────────────────────
+              await refreshStaging(summary.cruxes, canonicalSourceHash);
+            } finally {
+              release();
+            }
+          }
+
+          // ─── Step 5: optional --wait polling (outside lock) ───────────────
+          if (opts.wait && !summary.terminal_emitted) {
+            const deadline = Date.now() + opts.wait * 1000;
+            let polledEvents: CommonsLogEvent[] | null = null;
+            while (Date.now() < deadline) {
+              await new Promise((r) => setTimeout(r, 2000));
+              const { events: polled } = await api.getCommonsLogEvents(ws.runId, { limit: 5000 });
+              if (reduceRunState(ws, polled).terminal_emitted) {
+                polledEvents = polled;
+                break;
+              }
+            }
+            if (polledEvents) {
+              summary = reduceRunState(ws, polledEvents);
+              const release2 = acquireLock(ws.stagingDir);
+              try {
+                await refreshStaging(summary.cruxes, canonicalSourceHash);
+              } finally {
+                release2();
+              }
+            }
+          }
+
+          return { run_id: ws.runId, summary, terminal_emitted: summary.terminal_emitted };
+        });
+      },
+    );
+
+  converge
+    .command("clarify <sub_debate_id> <text>")
+    .description("Post owner_clarification.v1 directly to a sub-debate's Commons Log")
+    .action(async (subDebateId: string, text: string) => {
+      await runCommand(async () => {
+        const ctx = buildContext();
+        if (!ctx.cfg.apiKey) throw new LinkedClawError("missing_api_key", "Run `linkedclaw login` first.");
+        const api = makeConvergeApi(ctx.cfg.cloudUrl, ctx.cfg.apiKey);
+        const subDebate = await api.getDebate(subDebateId);
+        const { seq } = await api.appendCommonsLog(subDebate.commons_log_id, "owner_clarification", {
+          event_type: "owner_clarification",
+          content: text,
+          in_response_to_event_id: null,
+        });
+        return { sub_debate_id: subDebateId, commons_log_id: subDebate.commons_log_id, seq };
+      });
+    });
+
+  converge
+    .command("attest <crux_id>")
+    .description("POST an attest_only decision to the Convergence PA")
+    .option("--run-id <id>")
+    .option("--staging-dir <path>")
+    .action(async (cruxId: string, opts: { runId?: string; stagingDir?: string }) => {
+      await runCommand(async () => {
+        const ctx = buildContext();
+        if (!ctx.cfg.apiKey) throw new LinkedClawError("missing_api_key", "Run `linkedclaw login` first.");
+        const api = makeConvergeApi(ctx.cfg.cloudUrl, ctx.cfg.apiKey);
+        const ws = await resolveWorkspace({ runId: opts.runId, stagingDir: opts.stagingDir });
+        const { event_id } = await postCruxDecision(api, ws, cruxId, "attest");
+        return { run_id: ws.runId, crux_id: cruxId, action: "attest", event_id, synced: false };
+      });
+    });
+
+  converge
+    .command("accept <crux_id>")
+    .description("POST an accept decision to the Convergence PA")
+    .option("--run-id <id>")
+    .option("--staging-dir <path>")
+    .option("--message <text>", "Optional user_message recorded in provenance")
+    .option("--with-sync", "Compatibility: after the PA accepts, materialize local corpus files")
+    .action(async (cruxId: string, opts: { runId?: string; stagingDir?: string; message?: string; withSync?: boolean }) => {
+      await runCommand(async () => {
+        const ctx = buildContext();
+        if (!ctx.cfg.apiKey) throw new LinkedClawError("missing_api_key", "Run `linkedclaw login` first.");
+        const api = makeConvergeApi(ctx.cfg.cloudUrl, ctx.cfg.apiKey);
+        const ws = await resolveWorkspace({ runId: opts.runId, stagingDir: opts.stagingDir });
+        const { event_id, body } = await postCruxDecision(api, ws, cruxId, "accept", { message: opts.message });
+        if (opts.withSync) {
+          const sync = await syncTerminalDecisions(ctx, api, ws, {
+            cruxId,
+            message: opts.message,
+            injectedTerminal: {
+              cruxId,
+              eventType: decisionEventTypeForAction("accept"),
+              payload: { event_type: decisionEventTypeForAction("accept"), crux_id: cruxId, ...body },
+            },
+          });
+          return {
+            run_id: ws.runId,
+            crux_id: cruxId,
+            action: "accept",
+            event_id,
+            synced: true,
+            ...sync,
+          };
+        }
+        return { run_id: ws.runId, crux_id: cruxId, action: "accept", event_id, synced: false };
+      });
+    });
+
+  converge
+    .command("reject <crux_id>")
+    .description("POST a reject decision to the Convergence PA")
+    .option("--run-id <id>")
+    .option("--staging-dir <path>")
+    .action(async (cruxId: string, opts: { runId?: string; stagingDir?: string }) => {
+      await runCommand(async () => {
+        const ctx = buildContext();
+        if (!ctx.cfg.apiKey) throw new LinkedClawError("missing_api_key", "Run `linkedclaw login` first.");
+        const api = makeConvergeApi(ctx.cfg.cloudUrl, ctx.cfg.apiKey);
+        const ws = await resolveWorkspace({ runId: opts.runId, stagingDir: opts.stagingDir });
+        const { event_id } = await postCruxDecision(api, ws, cruxId, "reject");
+        return { run_id: ws.runId, crux_id: cruxId, action: "reject", event_id, synced: false };
+      });
+    });
+
+  converge
+    .command("sync")
+    .description("Materialize PA decision events into local corpus/staging files")
+    .option("--run-id <id>")
+    .option("--staging-dir <path>")
+    .option("--crux-id <id>", "Limit sync to one crux")
+    .action(async (opts: { runId?: string; stagingDir?: string; cruxId?: string }) => {
+      await runCommand(async () => {
+        const ctx = buildContext();
+        if (!ctx.cfg.apiKey) throw new LinkedClawError("missing_api_key", "Run `linkedclaw login` first.");
+        const api = makeConvergeApi(ctx.cfg.cloudUrl, ctx.cfg.apiKey);
+        const ws = await resolveWorkspace({ runId: opts.runId, stagingDir: opts.stagingDir });
+        const result = await syncTerminalDecisions(ctx, api, ws, { cruxId: opts.cruxId });
+        return { run_id: ws.runId, synced: true, ...result };
+      });
+    });
+
+  converge
+    .command("review")
+    .description("List staging cruxes; surface already_aligned cruxes prominently")
+    .option("--run-id <id>")
+    .option("--staging-dir <path>")
+    .action(async (opts: { runId?: string; stagingDir?: string }) => {
+      await runCommand(async () => {
+        const ws = await resolveWorkspace({ runId: opts.runId, stagingDir: opts.stagingDir });
+        const files = listCruxFiles(ws.stagingDir);
+        const cruxes: Array<Record<string, unknown>> = [];
+        for (const fn of files) {
+          const doc = readStaging(join(ws.stagingDir, fn));
+          const fm = doc.frontmatter;
+          cruxes.push({
+            crux_id: fm.crux_id,
+            outcome: fm.outcome,
+            bilateral_mandate_intact: fm.bilateral_mandate_intact,
+            attested_by_user: fm.attested_by_user,
+            latest_sub_debate_id: fm.latest_sub_debate_id,
+            has_user_response: (doc.userResponse || "").trim().length > 0,
+            next_action:
+              fm.outcome === "already_aligned" && !fm.attested_by_user ? "attest"
+              : fm.outcome === "needs_input" ? "clarify_or_accept"
+              : "accept_or_reject",
+          });
+        }
+        const alignedAwaitingAttest = cruxes.filter((c) => c.outcome === "already_aligned" && !c.attested_by_user);
+        return {
+          run_id: ws.runId,
+          staging_dir: ws.stagingDir,
+          cruxes,
+          already_aligned_awaiting_attest: alignedAwaitingAttest.map((c) => c.crux_id),
+        };
+      });
+    });
+
+  converge
+    .command("status")
+    .description("Show reduced run state from the convergence run-log")
+    .option("--run-id <id>")
+    .option("--staging-dir <path>")
+    .option("--all", "List every run-log event (no reduction)")
+    .action(async (opts) => {
+      await runCommand(async () => {
+        const ctx = buildContext();
+        if (!ctx.cfg.apiKey) {
+          throw new Error("missing apiKey — run `linkedclaw login` first");
+        }
+        const ws = await resolveWorkspace({ runId: opts.runId, stagingDir: opts.stagingDir });
+        const api = makeConvergeApi(ctx.cfg.cloudUrl, ctx.cfg.apiKey);
+        const { events } = await api.getCommonsLogEvents(ws.runId, { limit: 1000 });
+        if (opts.all) return { run_id: ws.runId, events };
+        return reduceRunState(ws, events);
+      });
+    });
+}
+
+export function reduceRunState(ws: RunWorkspace, events: CommonsLogEvent[]): RunStateSummary {
+  let started_at: string | null = null;
+  let owner_b_accepted = false;
+  let terminal_emitted = false;
+  const cruxMap = new Map<
+    string,
+    {
+      crux_id: string;
+      latest_sub_debate_id: string | null;
+      sub_debate_chain: string[];
+      outcome: string | null;
+      bilateral_mandate_intact: boolean | null;
+    }
+  >();
+
+  for (const ev of events) {
+    const p = ev.payload;
+    switch (ev.event_type) {
+      case "run_started":
+        started_at = ev.appended_at;
+        break;
+      case "owner_b_accepted":
+        owner_b_accepted = true;
+        break;
+      case "sub_debate_dispatched": {
+        const cruxId = p.crux_id as string;
+        const subDebateId = p.sub_debate_id as string;
+        if (!cruxMap.has(cruxId)) {
+          cruxMap.set(cruxId, {
+            crux_id: cruxId,
+            latest_sub_debate_id: subDebateId,
+            sub_debate_chain: [subDebateId],
+            outcome: null,
+            bilateral_mandate_intact: null,
+          });
+        } else {
+          const entry = cruxMap.get(cruxId)!;
+          entry.latest_sub_debate_id = subDebateId;
+          entry.sub_debate_chain.push(subDebateId);
+        }
+        break;
+      }
+      case "sub_debate_outcome_observed": {
+        const cruxId = p.crux_id as string;
+        const entry = cruxMap.get(cruxId);
+        if (entry) {
+          entry.outcome = p.outcome as string;
+          if (typeof p.bilateral_mandate_intact === "boolean") {
+            entry.bilateral_mandate_intact = p.bilateral_mandate_intact;
+          }
+        }
+        break;
+      }
+      case "convergence_map":
+        terminal_emitted = true;
+        break;
+      default:
+        if ((ev.event_type as string).startsWith("terminal_")) {
+          terminal_emitted = true;
+        }
+    }
+  }
+
+  return {
+    run_id: ws.runId,
+    source_debate_id: ws.sourceDebateId,
+    started_at,
+    owner_b_accepted,
+    cruxes: Array.from(cruxMap.values()),
+    terminal_emitted,
+  };
+}