@linkedclaw/cli 0.1.3 → 0.1.5

package/test/converge-accept.test.ts

@@ -0,0 +1,206 @@
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { registerConvergeCommands } from "../src/commands/converge.js";
+import { sha256OfCanonicalJson } from "../src/converge/hash.js";
+import { computePaBodyHash, readStaging, stagingPathFor, writeStaging } from "../src/converge/staging.js";
+import { writeRunMeta } from "../src/converge/workspace.js";
+import { LinkedClawError } from "../src/errors.js";
+
+const RUN_ID = "clg_run_accept001";
+const SOURCE_DEBATE_ID = "dbt_src001";
+const PA_AGENT_ID = "agt_pa001";
+const CRUX_ID = "crux_001";
+const SUB_DEBATE_ID = "dbt_sub001";
+const SOURCE_HASH = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+const BODY = "# Synthesis\n\nBoth sides agree on X.\n\n# Open questions\n\n(none)\n";
+
+const apiRef = vi.hoisted(() => ({ current: {} as any }));
+
+vi.mock("../src/context.js", () => ({
+  buildContext: () => ({
+    cfg: { apiKey: "lc_test", cloudUrl: "http://cloud.test" },
+    consumer: { getMe: vi.fn(async () => ({ user_id: "usr_test" })) },
+  }),
+}));
+
+vi.mock("../src/converge/api.js", () => ({
+  makeConvergeApi: () => apiRef.current,
+}));
+
+function mapEvent() {
+  return {
+    seq: 10,
+    event_type: "convergence_map",
+    payload: {
+      event_type: "convergence_map",
+      source_crux_map_hash: SOURCE_HASH,
+      cruxes: [
+        {
+          crux_id: CRUX_ID,
+          outcome: "converged",
+          sub_debate_chain: [SUB_DEBATE_ID],
+          latest_sub_debate_id: SUB_DEBATE_ID,
+          synthesis_text: "Both sides agree on X.",
+          citations_a: [],
+          citations_b: [],
+          open_questions: [],
+          final_progress_signal: {},
+          generation_id: "gen_accept001",
+          bilateral_mandate_intact_at_outcome: true,
+        },
+      ],
+    },
+    appended_at: "2026-04-30T10:00:00Z",
+    signed_by: "usr_operator",
+  };
+}
+
+function terminalAcceptEvent() {
+  return {
+    seq: 11,
+    event_type: "accept_attestation",
+    payload: {
+      event_type: "accept_attestation",
+      crux_id: CRUX_ID,
+      convergence_map_generation_id: "gen_accept001",
+    },
+    appended_at: "2026-04-30T10:01:00Z",
+    signed_by: "usr_operator",
+  };
+}
+
+function makeProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerConvergeCommands(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number | undefined }> {
+  let stdout = "";
+  let stderr = "";
+  const out = vi.spyOn(process.stdout, "write").mockImplementation((chunk: any) => {
+    stdout += String(chunk);
+    return true;
+  });
+  const err = vi.spyOn(process.stderr, "write").mockImplementation((chunk: any) => {
+    stderr += String(chunk);
+    return true;
+  });
+  const prevExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    await makeProgram().parseAsync(["node", "test", ...args], { from: "node" });
+    return { stdout, stderr, exitCode: process.exitCode as number | undefined };
+  } finally {
+    process.exitCode = prevExitCode;
+    out.mockRestore();
+    err.mockRestore();
+  }
+}
+
+function writeWorkspace(tmp: string): { stagingDir: string; stagingPath: string } {
+  const stagingDir = join(tmp, "converged", "staging", RUN_ID);
+  writeRunMeta(stagingDir, {
+    run_id: RUN_ID,
+    source_debate_id: SOURCE_DEBATE_ID,
+    pa_agent_id: PA_AGENT_ID,
+    target_corpus: tmp,
+    owner_role: "a",
+  });
+  const stagingPath = stagingPathFor(stagingDir, CRUX_ID);
+  writeStaging(stagingPath, {
+    frontmatter: {
+      debate_id: SOURCE_DEBATE_ID,
+      run_id: RUN_ID,
+      crux_id: CRUX_ID,
+      sub_debate_chain: [SUB_DEBATE_ID],
+      latest_sub_debate_id: SUB_DEBATE_ID,
+      source_crux_map_hash: SOURCE_HASH,
+      generation_id: "gen_accept001",
+      generated_at: "2026-04-30T10:00:00Z",
+      pa_body_hash: computePaBodyHash(BODY),
+      outcome: "converged",
+      bilateral_mandate_intact: true,
+      citations_a: [],
+      citations_b: [],
+      mod_progress_summary: {},
+      attested_by_user: false,
+    },
+    userResponse: "",
+    body: BODY,
+  });
+  return { stagingDir, stagingPath };
+}
+
+let tmp: string;
+let runEvents: any[];
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "lc-accept-test-"));
+  runEvents = [mapEvent()];
+  apiRef.current = {
+    getCommonsLogEvents: vi.fn(async () => ({ events: runEvents, next_offset: runEvents.length })),
+    acceptCruxDecision: vi.fn(async () => {
+      runEvents = [mapEvent(), terminalAcceptEvent()];
+      return { event_id: "sig_accept001" };
+    }),
+    getDebate: vi.fn(async () => ({
+      debate_id: SOURCE_DEBATE_ID,
+      agent_a_id: "agt_a",
+      agent_b_id: "agt_b",
+      commons_log_id: "clg_src",
+      counterparty_user_id: "usr_b",
+      status: "completed",
+      topic: "Trust scoring approach",
+    })),
+  };
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe("accept --with-sync", () => {
+  it("posts the PA decision, then materializes the old accepted-file path", async () => {
+    const { stagingDir, stagingPath } = writeWorkspace(tmp);
+    const result = await run(["converge", "accept", CRUX_ID, "--staging-dir", stagingDir, "--with-sync"]);
+    expect(result.exitCode).toBeUndefined();
+    const payload = JSON.parse(result.stdout);
+    expect(apiRef.current.acceptCruxDecision).toHaveBeenCalledOnce();
+    expect(payload.event_id).toBe("sig_accept001");
+    expect(payload.synced).toBe(true);
+    expect(payload.materialized).toHaveLength(1);
+    expect(existsSync(payload.materialized[0])).toBe(true);
+    expect(existsSync(stagingPath)).toBe(false);
+    const accepted = readStaging(payload.materialized[0]);
+    expect(accepted.frontmatter.provenance?.attestation).toBe("bilateral_convergence");
+    expect(accepted.frontmatter.provenance?.signed_off_by).toBe("usr_test");
+  });
+
+  it("does not materialize local files when the PA decision is rejected", async () => {
+    const { stagingDir, stagingPath } = writeWorkspace(tmp);
+    apiRef.current.acceptCruxDecision = vi.fn(async () => {
+      throw new LinkedClawError("api_409", "HTTP 409");
+    });
+    const result = await run(["converge", "accept", CRUX_ID, "--staging-dir", stagingDir, "--with-sync"]);
+    expect(result.exitCode).toBe(1);
+    expect(existsSync(stagingPath)).toBe(true);
+    expect(readFileSync(stagingPath, "utf8")).toContain("Both sides agree on X.");
+    expect(existsSync(join(tmp, "converged", "trust-scoring-approach"))).toBe(false);
+  });
+
+  it("uses the PA-compatible canonical body hash in the endpoint request", async () => {
+    const { stagingDir } = writeWorkspace(tmp);
+    await run(["converge", "accept", CRUX_ID, "--staging-dir", stagingDir, "--with-sync"]);
+    const body = apiRef.current.acceptCruxDecision.mock.calls[0][2];
+    expect(body.pa_body_hash).toBe(
+      sha256OfCanonicalJson({ citations_a: [], citations_b: [], synthesis_text: "Both sides agree on X." }),
+    );
+    expect(body.pa_body_hash).not.toBe(computePaBodyHash(BODY));
+  });
+});

package/test/converge-decision.test.ts

@@ -0,0 +1,274 @@
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { registerConvergeCommands } from "../src/commands/converge.js";
+import { sha256OfCanonicalJson } from "../src/converge/hash.js";
+import { computePaBodyHash, stagingPathFor, writeStaging } from "../src/converge/staging.js";
+import { writeRunMeta } from "../src/converge/workspace.js";
+
+const RUN_ID = "clg_run_decision001";
+const SOURCE_DEBATE_ID = "dbt_src001";
+const PA_AGENT_ID = "agt_pa001";
+const CRUX_ID = "crux_001";
+const SOURCE_HASH = "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+const STAGING_BODY = "# Synthesis\n\nLocal edited draft that must not be posted.\n";
+
+const apiRef = vi.hoisted(() => ({ current: {} as any }));
+
+vi.mock("../src/context.js", () => ({
+  buildContext: () => ({
+    cfg: { apiKey: "lc_test", cloudUrl: "http://cloud.test" },
+    consumer: { getMe: vi.fn(async () => ({ user_id: "usr_test" })) },
+  }),
+}));
+
+vi.mock("../src/converge/api.js", () => ({
+  makeConvergeApi: () => apiRef.current,
+}));
+
+function makeMap(outcome: string, extras: Record<string, unknown> = {}) {
+  return {
+    seq: 7,
+    event_type: "convergence_map",
+    payload: {
+      event_type: "convergence_map",
+      source_crux_map_hash: SOURCE_HASH,
+      cruxes: [
+        {
+          crux_id: CRUX_ID,
+          outcome,
+          sub_debate_chain: outcome === "already_aligned" ? [] : ["dbt_sub001"],
+          latest_sub_debate_id: outcome === "already_aligned" ? null : "dbt_sub001",
+          synthesis_text: "PA canonical synthesis.",
+          citations_a: [{ file: "a.md", line_range: "1-2" }],
+          citations_b: [],
+          generation_id: "gen_decision001",
+          bilateral_mandate_intact_at_outcome: true,
+          ...extras,
+        },
+      ],
+    },
+    appended_at: "2026-04-30T10:00:00Z",
+    signed_by: "usr_operator",
+  };
+}
+
+function makeProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerConvergeCommands(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number | undefined }> {
+  let stdout = "";
+  let stderr = "";
+  const out = vi.spyOn(process.stdout, "write").mockImplementation((chunk: any) => {
+    stdout += String(chunk);
+    return true;
+  });
+  const err = vi.spyOn(process.stderr, "write").mockImplementation((chunk: any) => {
+    stderr += String(chunk);
+    return true;
+  });
+  const prevExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    await makeProgram().parseAsync(["node", "test", ...args], { from: "node" });
+    return { stdout, stderr, exitCode: process.exitCode as number | undefined };
+  } finally {
+    process.exitCode = prevExitCode;
+    out.mockRestore();
+    err.mockRestore();
+  }
+}
+
+function writeWorkspace(tmp: string): { stagingDir: string; stagingPath: string; originalText: string } {
+  const stagingDir = join(tmp, "converged", "staging", RUN_ID);
+  writeRunMeta(stagingDir, {
+    run_id: RUN_ID,
+    source_debate_id: SOURCE_DEBATE_ID,
+    pa_agent_id: PA_AGENT_ID,
+    target_corpus: tmp,
+    owner_role: "a",
+  });
+  const stagingPath = stagingPathFor(stagingDir, CRUX_ID);
+  writeStaging(stagingPath, {
+    frontmatter: {
+      debate_id: SOURCE_DEBATE_ID,
+      run_id: RUN_ID,
+      crux_id: CRUX_ID,
+      sub_debate_chain: ["dbt_sub001"],
+      latest_sub_debate_id: "dbt_sub001",
+      source_crux_map_hash: SOURCE_HASH,
+      generation_id: "gen_old",
+      generated_at: "2026-04-30T09:00:00Z",
+      pa_body_hash: computePaBodyHash(STAGING_BODY),
+      outcome: "converged",
+      bilateral_mandate_intact: true,
+      citations_a: [],
+      citations_b: [],
+      mod_progress_summary: {},
+      attested_by_user: false,
+    },
+    userResponse: "",
+    body: STAGING_BODY,
+  });
+  return { stagingDir, stagingPath, originalText: readFileSync(stagingPath, "utf8") };
+}
+
+let tmp: string;
+let runEvents: any[];
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "lc-decision-test-"));
+  runEvents = [makeMap("converged")];
+  apiRef.current = {
+    getCommonsLogEvents: vi.fn(async () => ({ events: runEvents, next_offset: runEvents.length })),
+    acceptCruxDecision: vi.fn(async () => ({ event_id: "sig_accept" })),
+    rejectCruxDecision: vi.fn(async () => ({ event_id: "sig_reject" })),
+    attestCruxDecision: vi.fn(async () => ({ event_id: "sig_attest" })),
+  };
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe("network-only convergence decisions", () => {
+  it("accept posts the PA decision endpoint and does not touch staging or final files", async () => {
+    const { stagingDir, stagingPath, originalText } = writeWorkspace(tmp);
+    const result = await run(["converge", "accept", CRUX_ID, "--staging-dir", stagingDir]);
+    expect(result.exitCode).toBeUndefined();
+    expect(apiRef.current.acceptCruxDecision).toHaveBeenCalledOnce();
+    expect(readFileSync(stagingPath, "utf8")).toBe(originalText);
+    expect(existsSync(join(tmp, "converged", "dbt-src001"))).toBe(false);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({ run_id: RUN_ID, crux_id: CRUX_ID, action: "accept", event_id: "sig_accept", synced: false });
+  });
+
+  it("reject posts the PA decision endpoint and leaves staging intact", async () => {
+    runEvents = [makeMap("irreconcilable", { bilateral_mandate_intact_at_outcome: false })];
+    const { stagingDir, stagingPath, originalText } = writeWorkspace(tmp);
+    await run(["converge", "reject", CRUX_ID, "--staging-dir", stagingDir]);
+    expect(apiRef.current.rejectCruxDecision).toHaveBeenCalledOnce();
+    expect(readFileSync(stagingPath, "utf8")).toBe(originalText);
+  });
+
+  it("attest posts the PA decision endpoint and leaves staging intact", async () => {
+    runEvents = [makeMap("already_aligned")];
+    const { stagingDir, stagingPath, originalText } = writeWorkspace(tmp);
+    await run(["converge", "attest", CRUX_ID, "--staging-dir", stagingDir]);
+    expect(apiRef.current.attestCruxDecision).toHaveBeenCalledOnce();
+    expect(readFileSync(stagingPath, "utf8")).toBe(originalText);
+  });
+
+  it("builds accept/reject/attest requests from the latest convergence_map", async () => {
+    const { stagingDir } = writeWorkspace(tmp);
+    await run(["converge", "accept", CRUX_ID, "--staging-dir", stagingDir, "--message", "reviewed"]);
+    const body = apiRef.current.acceptCruxDecision.mock.calls[0][2];
+    expect(body).toMatchObject({
+      convergence_map_generation_id: "gen_decision001",
+      source_crux_map_hash: SOURCE_HASH,
+      latest_sub_debate_id: "dbt_sub001",
+      terminal_outcome: "converged",
+      bilateral_mandate_intact: true,
+      attestation: "bilateral_convergence",
+      synthesis_edited: false,
+      synthesis_text: "PA canonical synthesis.",
+      citations_a: [{ file: "a.md", line_range: "1-2" }],
+      citations_b: [],
+      user_message: "reviewed",
+    });
+    expect(body.pa_body_hash).toBe(
+      sha256OfCanonicalJson({
+        citations_a: [{ file: "a.md", line_range: "1-2" }],
+        citations_b: [],
+        synthesis_text: "PA canonical synthesis.",
+      }),
+    );
+    expect(body.accepted_body_hash).toBe(body.pa_body_hash);
+
+    runEvents = [makeMap("irreconcilable", { bilateral_mandate_intact_at_outcome: false })];
+    await run(["converge", "reject", CRUX_ID, "--staging-dir", stagingDir]);
+    expect(apiRef.current.rejectCruxDecision.mock.calls[0][2].attestation).toBe("user_attested_with_network_context");
+
+    runEvents = [makeMap("already_aligned")];
+    await run(["converge", "attest", CRUX_ID, "--staging-dir", stagingDir]);
+    expect(apiRef.current.attestCruxDecision.mock.calls[0][2].attestation).toBe("user_attested_no_dialog");
+  });
+
+  it("accept with edited staging body sets synthesis_edited=true and posts the edited body", async () => {
+    const { stagingDir, stagingPath } = writeWorkspace(tmp);
+    const editedBody = "# Synthesis\n\nLocal edits the user made before accepting.\n";
+    const paBody = "PA canonical synthesis.";
+    writeStaging(stagingPath, {
+      frontmatter: {
+        debate_id: SOURCE_DEBATE_ID,
+        run_id: RUN_ID,
+        crux_id: CRUX_ID,
+        sub_debate_chain: ["dbt_sub001"],
+        latest_sub_debate_id: "dbt_sub001",
+        source_crux_map_hash: SOURCE_HASH,
+        generation_id: "gen_decision001",
+        generated_at: "2026-04-30T09:00:00Z",
+        pa_body_hash: computePaBodyHash(paBody),
+        outcome: "converged",
+        bilateral_mandate_intact: true,
+        citations_a: [{ file: "a.md", line_range: "1-2" }],
+        citations_b: [],
+        mod_progress_summary: {},
+        attested_by_user: false,
+      },
+      userResponse: "",
+      body: editedBody,
+    });
+
+    await run(["converge", "accept", CRUX_ID, "--staging-dir", stagingDir]);
+
+    const body = apiRef.current.acceptCruxDecision.mock.calls[0][2];
+    expect(body.synthesis_edited).toBe(true);
+    expect(body.attestation).toBe("user_attested_with_network_context");
+    expect(body.synthesis_text).toBe(editedBody);
+    expect(body.pa_body_hash).toBe(
+      sha256OfCanonicalJson({
+        citations_a: [{ file: "a.md", line_range: "1-2" }],
+        citations_b: [],
+        synthesis_text: paBody,
+      }),
+    );
+    expect(body.accepted_body_hash).toBe(
+      sha256OfCanonicalJson({
+        citations_a: [{ file: "a.md", line_range: "1-2" }],
+        citations_b: [],
+        synthesis_text: editedBody,
+      }),
+    );
+    expect(body.accepted_body_hash).not.toBe(body.pa_body_hash);
+  });
+
+  it("sync removes staging files for terminal non-accept decisions", async () => {
+    runEvents = [
+      makeMap("irreconcilable", { bilateral_mandate_intact_at_outcome: false }),
+      {
+        seq: 8,
+        event_type: "reject_attestation",
+        payload: {
+          event_type: "reject_attestation",
+          crux_id: CRUX_ID,
+          convergence_map_generation_id: "gen_decision001",
+        },
+        appended_at: "2026-04-30T10:01:00Z",
+        signed_by: "usr_operator",
+      },
+    ];
+    const { stagingDir, stagingPath } = writeWorkspace(tmp);
+    const result = await run(["converge", "sync", "--staging-dir", stagingDir]);
+    expect(result.exitCode).toBeUndefined();
+    expect(existsSync(stagingPath)).toBe(false);
+    expect(JSON.parse(result.stdout).cleaned).toEqual([CRUX_ID]);
+  });
+});

package/test/converge-hash.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import { sha256OfCanonicalJson, canonicalize } from "../src/converge/hash.js";
+
+describe("sha256OfCanonicalJson", () => {
+  it("key-order independence: {b,a} === {a,b}", () => {
+    expect(sha256OfCanonicalJson({ b: 1, a: 2 })).toBe(sha256OfCanonicalJson({ a: 2, b: 1 }));
+  });
+
+  it("output is deterministic across calls", () => {
+    const v = { x: [1, 2, 3], y: null };
+    expect(sha256OfCanonicalJson(v)).toBe(sha256OfCanonicalJson(v));
+  });
+
+  it("output starts with sha256:", () => {
+    expect(sha256OfCanonicalJson({})).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+
+  it("different values produce different hashes", () => {
+    expect(sha256OfCanonicalJson({ a: 1 })).not.toBe(sha256OfCanonicalJson({ a: 2 }));
+  });
+
+  it("canonicalize handles nested objects and arrays", () => {
+    const a = canonicalize({ z: [{ b: 1, a: 2 }] });
+    const b = canonicalize({ z: [{ a: 2, b: 1 }] });
+    expect(a).toBe(b);
+  });
+});
+
+// Python equivalence fixtures:
+//   import hashlib, json
+//   json.dumps(data, sort_keys=True, separators=(",",":"), ensure_ascii=True)
+//   "sha256:" + hashlib.sha256(canonical.encode()).hexdigest()
+describe("Python hash equivalence", () => {
+  it("matches Python for pure-ASCII crux_map fixture", () => {
+    // Python: json.dumps({"cruxes":[{"crux_id":"c1","statement":"foo"}],"version":1}, sort_keys=True, separators=(",",":"))
+    // → '{"cruxes":[{"crux_id":"c1","statement":"foo"}],"version":1}'
+    // → sha256:2e55d19757e251b4aefc7eb59ef941d99087d3cfaf7be24fe790c83a9f7ba7e7
+    const data = { cruxes: [{ crux_id: "c1", statement: "foo" }], version: 1 };
+    expect(sha256OfCanonicalJson(data)).toBe(
+      "sha256:2e55d19757e251b4aefc7eb59ef941d99087d3cfaf7be24fe790c83a9f7ba7e7",
+    );
+  });
+
+  it("matches Python for non-ASCII string (ensure_ascii=True escapes to \\uXXXX)", () => {
+    // Python (ensure_ascii=True default): {"n":2,"text":"café"}
+    // → sha256:5429b44c1e9e972c80e540b67fc1498b68b6e1afa2822736ef98b38dcecf8f6b
+    const data = { text: "café", n: 2 };
+    expect(sha256OfCanonicalJson(data)).toBe(
+      "sha256:5429b44c1e9e972c80e540b67fc1498b68b6e1afa2822736ef98b38dcecf8f6b",
+    );
+  });
+
+  it("canonicalize emits \\uXXXX for non-ASCII chars (not raw UTF-8)", () => {
+    // Node JSON.stringify does NOT escape non-ASCII by default;
+    // our canonicalize must do it explicitly to match Python.
+    expect(canonicalize("café")).toBe('"caf\\u00e9"');
+  });
+});

package/test/converge-help.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(__dirname, "../dist/bin.js");
+
+beforeAll(() => {
+  if (!existsSync(BIN)) {
+    throw new Error(`bin not built — run 'pnpm --filter @linkedclaw/cli build' first (${BIN})`);
+  }
+});
+
+function run(args: string[]): { code: number | null; stdout: string; stderr: string } {
+  const r = spawnSync("node", [BIN, ...args], { encoding: "utf8" });
+  return { code: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+describe("converge help", () => {
+  it("converge --help lists all 8 verbs", () => {
+    const { code, stdout } = run(["converge", "--help"]);
+    expect(code).toBe(0);
+    for (const verb of ["run", "clarify", "attest", "accept", "reject", "sync", "review", "status"]) {
+      expect(stdout).toContain(verb);
+    }
+  });
+
+  it("converge run --help lists expected options", () => {
+    const { code, stdout } = run(["converge", "run", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--target-corpus");
+    expect(stdout).toContain("--accept");
+    expect(stdout).toContain("--force-regenerate");
+    expect(stdout).toContain("--wait");
+  });
+
+  it("converge status --help lists --all", () => {
+    const { code, stdout } = run(["converge", "status", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--all");
+    expect(stdout).toContain("--run-id");
+    expect(stdout).toContain("--staging-dir");
+  });
+
+  it("converge accept --help lists --with-sync", () => {
+    const { code, stdout } = run(["converge", "accept", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--with-sync");
+  });
+
+  it("top-level --help still lists converge", () => {
+    const { code, stdout } = run(["--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("converge");
+  });
+});

package/test/converge-lock.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { acquireLock } from "../src/converge/lock.js";
+
+let tmp: string;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "lc-lock-test-"));
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("acquireLock", () => {
+  it("succeeds and creates .lock file", () => {
+    const release = acquireLock(tmp);
+    expect(existsSync(join(tmp, ".lock"))).toBe(true);
+    release();
+  });
+
+  it("second concurrent call throws lock_held", () => {
+    const release = acquireLock(tmp);
+    try {
+      expect(() => acquireLock(tmp)).toThrow(
+        expect.objectContaining({ code: "lock_held" }),
+      );
+    } finally {
+      release();
+    }
+  });
+
+  it("release deletes .lock file", () => {
+    const release = acquireLock(tmp);
+    release();
+    expect(existsSync(join(tmp, ".lock"))).toBe(false);
+  });
+
+  it("re-acquire after release succeeds", () => {
+    const r1 = acquireLock(tmp);
+    r1();
+    const r2 = acquireLock(tmp);
+    expect(existsSync(join(tmp, ".lock"))).toBe(true);
+    r2();
+  });
+});