@united-workforce/cli 0.4.0 → 0.6.0

package/examples/debate.yaml

@@ -0,0 +1,169 @@
+version: 1
+name: debate
+description: "Multi-role structured debate with critical thinking framework and host summary."
+
+# Shared frontmatter schema for debater roles (YAML anchor)
+x-debater-frontmatter: &debater-frontmatter
+  type: object
+  oneOf:
+    - properties:
+        $status: { const: speak }
+        argument: { type: string }
+      required: [$status, argument]
+    - properties:
+        $status: { const: conceded }
+        reason: { type: string }
+      required: [$status, reason]
+    - properties:
+        $status: { const: final }
+        closing: { type: string }
+      required: [$status, closing]
+
+roles:
+  proponent:
+    description: "Argues FOR the proposition"
+    goal: "Build a compelling case for the proposition through logical reasoning and evidence"
+    capabilities: []
+    procedure: |
+      You are an experienced scholar arguing FOR the proposition.
+
+      ## Critical Thinking Framework (execute before every speech)
+
+      ### A. Pre-speech reflection (internal, do not output)
+      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+      - Should I go on offense or defense this round?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, you MUST output $status: final (closing statement).
+      3. If genuinely convinced by the opponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the opponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter: *debater-frontmatter
+
+  opponent:
+    description: "Argues AGAINST the proposition"
+    goal: "Build a compelling case against the proposition through logical reasoning and evidence"
+    capabilities: []
+    procedure: |
+      You are an experienced scholar arguing AGAINST the proposition.
+
+      ## Critical Thinking Framework (execute before every speech)
+
+      ### A. Pre-speech reflection (internal, do not output)
+      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+      - Should I go on offense or defense this round?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, or when the proponent has issued a final statement, you MUST output $status: final.
+      3. If genuinely convinced by the proponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the proponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter: *debater-frontmatter
+
+  host:
+    description: "Debate moderator — delivers impartial summary and verdict"
+    goal: "Objectively review the debate, analyze both sides, and deliver a verdict"
+    capabilities: []
+    procedure: |
+      You are an experienced academic debate moderator.
+
+      ## Task
+      1. Outline each side's core arguments
+      2. Evaluate reasoning quality and evidence use
+      3. Highlight the most impactful exchanges
+      4. Analyze the deeper significance of the topic
+      5. Deliver an overall verdict
+
+      ## Style
+      - Impartial but with independent judgment
+      - Substantive, not superficial
+    output: "Debate summary report"
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        summary: { type: string }
+        highlights: { type: string }
+        verdict: { type: string }
+      required: [$status, summary, highlights, verdict]
+
+  reporter:
+    description: "Generates an HTML report of the completed debate"
+    goal: "Produce a self-contained, visually polished HTML report that faithfully reproduces the entire debate with no paraphrasing."
+    capabilities: [run_command, write_file, read_file]
+    procedure: |
+      You are a report generator for a structured debate.
+
+      ## Steps
+      1. Read Thread Progress to get the thread ID.
+      2. Run: `uwf thread read <thread-id>` to get the full debate transcript.
+      3. Design and write a self-contained HTML file that presents the debate beautifully.
+      4. Save to `/tmp/debate-report-<thread-id>.html`.
+
+      ## HTML Report Requirements
+      - Title: the debate proposition
+      - Two-column layout comparing proponent vs opponent arguments round by round
+      - Key exchanges highlighted with visual callouts
+      - Host's verdict and summary in a prominent section
+      - If a side conceded, make it visually clear
+      - Clean typography, responsive layout, dark/light theme friendly
+      - All content verbatim from `uwf thread read` — do NOT paraphrase
+
+      ## Rules
+      1. You MUST use `uwf thread read` to get the data — do NOT rely on context.
+      2. Completely self-contained (inline styles, no CDN links).
+      3. Output the file path in your response body.
+    output: "Confirmation that the report was generated, with the file path."
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        reportPath: { type: string }
+      required: [$status, reportPath]
+
+graph:
+  $START:
+    new: { role: proponent, prompt: "The debate begins. You are arguing FOR the proposition. Present your opening argument." }
+    resume: { role: proponent, prompt: "The debate continues." }
+
+  proponent:
+    speak: { role: opponent, prompt: "Proponent argues:\n\n{{ argument }}\n\nYou are the opponent. Counter this argument." }
+    conceded: { role: host, prompt: "The proponent conceded: {{ reason }}\n\nPlease summarize the debate." }
+    final: { role: opponent, prompt: "Proponent's closing statement:\n\n{{ closing }}\n\nYou are the opponent. Deliver your final response." }
+
+  opponent:
+    speak: { role: proponent, prompt: "Opponent argues:\n\n{{ argument }}\n\nYou are the proponent. Counter this argument." }
+    conceded: { role: host, prompt: "The opponent conceded: {{ reason }}\n\nPlease summarize the debate." }
+    final: { role: host, prompt: "Opponent's closing statement:\n\n{{ closing }}\n\nThe debate is over. Please summarize." }
+
+  host:
+    done: { role: reporter, prompt: "Debate summary complete.\n\nSummary: {{ summary }}\nHighlights: {{ highlights }}\nVerdict: {{ verdict }}\n\nGenerate a polished HTML report of the entire debate." }
+
+  reporter:
+    done: { role: "$END", prompt: "Report generated." }

package/examples/socratic-questioning.yaml

@@ -0,0 +1,112 @@
+version: 1
+name: socratic-questioning
+description: "Socratic dialogue — a questioner helps the thinker examine their beliefs through probing questions."
+
+roles:
+  thinker:
+    description: "Holds and defends a position, refining it through dialogue"
+    goal: "Articulate and examine your position honestly. When a question exposes a weakness, acknowledge it and refine your view rather than deflecting."
+    capabilities: []
+    procedure: |
+      You are a thoughtful person exploring your own beliefs through dialogue.
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have responded.
+      2. On your 3rd response, you MUST output $status: synthesis (your refined position).
+      3. Be honest — if a question reveals a gap, say so and adjust.
+      4. Build on previous exchanges, don't repeat yourself.
+      5. Keep responses focused (under 300 words).
+    output: "Your response to the question, or your final synthesis."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: respond }
+            insight: { type: string }
+          required: [$status, insight]
+        - properties:
+            $status: { const: synthesis }
+            revisedPosition: { type: string }
+            keyInsights: { type: string }
+          required: [$status, revisedPosition, keyInsights]
+
+  questioner:
+    description: "Asks probing questions to help the thinker examine assumptions"
+    goal: "Guide the thinker to deeper understanding through questions — never lecture, never argue, never assert your own position."
+    capabilities: []
+    procedure: |
+      You are a Socratic questioner. Your only tool is the question.
+
+      ## Questioning techniques
+      - **Clarification**: "What do you mean by...?" / "Can you give an example?"
+      - **Assumptions**: "What are you assuming here?" / "Why do you believe that's true?"
+      - **Evidence**: "What evidence supports this?" / "How would you respond to someone who says...?"
+      - **Implications**: "If that's true, what follows?" / "What would change if you're wrong?"
+      - **Perspective**: "How might someone in a different situation see this?"
+
+      ## Rules
+      1. Ask 1-2 questions per turn, not more.
+      2. NEVER state your own opinion or argue a position.
+      3. Build on the thinker's previous answer — don't jump to unrelated topics.
+      4. When the thinker reaches a synthesis, output $status: done.
+      5. Keep questions concise and sharp.
+    output: "Your probing question(s)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: ask }
+            question: { type: string }
+          required: [$status, question]
+        - properties:
+            $status: { const: done }
+            summary: { type: string }
+          required: [$status, summary]
+
+  reporter:
+    description: "Generates an HTML report of the completed Socratic dialogue"
+    goal: "Produce a self-contained, visually polished HTML report that faithfully reproduces the entire dialogue with no paraphrasing."
+    capabilities: [run_command, write_file, read_file]
+    procedure: |
+      You are a report generator for a Socratic questioning session.
+
+      ## Steps
+      1. Read Thread Progress to get the thread ID.
+      2. Run: `uwf thread read <thread-id>` to get the full dialogue transcript.
+      3. Design and write a self-contained HTML file that presents the dialogue beautifully.
+      4. Save to `/tmp/socratic-report-<thread-id>.html`.
+
+      ## HTML Report Requirements
+      - Title: the original topic/position being examined
+      - Each exchange as a dialogue card (questioner question → thinker response)
+      - Visual distinction between questions and reflections
+      - The thinker's initial position and final synthesis prominently displayed
+      - A "journey" section showing how the position evolved
+      - Clean typography, responsive layout, dark/light theme friendly
+      - All content verbatim from `uwf thread read` — do NOT paraphrase
+
+      ## Rules
+      1. You MUST use `uwf thread read` to get the data — do NOT rely on context.
+      2. Completely self-contained (inline styles, no CDN links).
+      3. Output the file path in your response body.
+    output: "Confirmation that the report was generated, with the file path."
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        reportPath: { type: string }
+      required: [$status, reportPath]
+
+graph:
+  $START:
+    new: { role: thinker, prompt: "State your initial position on the topic. Be clear about what you believe and why." }
+    resume: { role: thinker, prompt: "Continue the dialogue from where you left off." }
+
+  thinker:
+    respond: { role: questioner, prompt: "The thinker says:\n\n{{ _body }}\n\nAsk a probing question to help them examine this further." }
+    synthesis: { role: questioner, prompt: "The thinker has reached a synthesis:\n\n{{ _body }}\n\nBriefly summarize the journey of this dialogue." }
+
+  questioner:
+    ask: { role: thinker, prompt: "The questioner asks:\n\n{{ _body }}\n\nReflect on this question and respond honestly." }
+    done: { role: reporter, prompt: "Dialogue complete.\n\nSummary: {{ summary }}\n\nGenerate a polished HTML report of the entire Socratic dialogue." }
+
+  reporter:
+    done: { role: "$END", prompt: "Report generated." }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@united-workforce/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "files": [
     "src",
     "dist",
+    "examples",
     "package.json"
   ],
   "type": "module",
@@ -13,13 +14,17 @@
   "dependencies": {
     "@ocas/core": "^0.5.0",
     "@ocas/fs": "^0.4.1",
+    "@united-workforce/protocol": "workspace:^",
+    "@united-workforce/util": "workspace:^",
+    "@united-workforce/util-agent": "workspace:^",
     "commander": "^14.0.3",
     "dotenv": "^16.6.1",
     "liquidjs": "^10.27.0",
-    "yaml": "^2.8.4",
-    "@united-workforce/protocol": "^0.2.0",
-    "@united-workforce/util": "^0.1.5",
-    "@united-workforce/util-agent": "^0.2.0"
+    "yaml": "^2.8.4"
+  },
+  "scripts": {
+    "test": "vitest run src/",
+    "test:ci": "vitest run src/"
   },
   "publishConfig": {
     "access": "public"
@@ -34,9 +39,5 @@
   "bugs": {
     "url": "https://git.shazhou.work/shazhou/united-workforce/issues"
   },
-  "license": "MIT",
-  "scripts": {
-    "test": "vitest run src/",
-    "test:ci": "vitest run src/"
-  }
-}
+  "license": "MIT"
+}

package/src/__tests__/adapter-json-roundtrip.test.ts

@@ -25,12 +25,19 @@ const OUTPUT_SCHEMA = {
 // ── fixture ──────────────────────────────────────────────────────────────────
 
 let tmpDir: string;
+let savedOcasHome: string | undefined;
 
 beforeEach(async () => {
+  savedOcasHome = process.env.OCAS_HOME;
   tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-roundtrip-test-"));
 });
 
 afterEach(async () => {
+  if (savedOcasHome === undefined) {
+    delete process.env.OCAS_HOME;
+  } else {
+    process.env.OCAS_HOME = savedOcasHome;
+  }
   await rm(tmpDir, { recursive: true, force: true });
 });
 
@@ -131,7 +138,7 @@ describe("C1: adapter JSON round-trip integration", () => {
     try {
       stdout = execFileSync(
         process.execPath,
-        [cliPath, "thread", "exec", threadId, "--agent", mockAgentPath],
+        [cliPath, "--format", "raw-json", "thread", "exec", threadId, "--agent", mockAgentPath],
         {
           encoding: "utf8",
           stdio: ["ignore", "pipe", "pipe"],
@@ -162,15 +169,17 @@ describe("C1: adapter JSON round-trip integration", () => {
       throw new Error(`CLI exited with code ${exitCode}\nstdout: ${stdout}\nstderr: ${stderr}`);
     }
 
-    // Parse CLI output
+    // Parse CLI output (raw-json envelope value: { threadId, workflowHash, steps: [...] })
     const cliOutput = JSON.parse(stdout.trim());
-    expect(cliOutput).toHaveProperty("thread", threadId);
-    expect(cliOutput).toHaveProperty("head", stepHash);
-    expect(cliOutput.head).toMatch(/^[0-9A-HJ-NP-TV-Z]{13}$/);
+    expect(cliOutput).toHaveProperty("threadId", threadId);
+    expect(cliOutput.steps).toHaveLength(1);
+    const firstStep = cliOutput.steps[0];
+    expect(firstStep).toHaveProperty("head", stepHash);
+    expect(firstStep.head).toMatch(/^[0-9A-HJ-NP-TV-Z]{13}$/);
 
     // Verify the CAS step node exists and has correct metadata
     const storeAfter = await openStore(casDir);
-    const stepNode = storeAfter.cas.get(cliOutput.head as CasRef);
+    const stepNode = storeAfter.cas.get(firstStep.head as CasRef);
     expect(stepNode).not.toBeNull();
 
     const payload = stepNode!.payload as StepNodePayload;

package/src/__tests__/concurrency.test.ts

@@ -0,0 +1,266 @@
+import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import {
+  acquireSlot,
+  cleanStaleSlots,
+  countActiveSlots,
+  DEFAULT_MAX_RUNNING,
+  getSlotsDir,
+  installSlotCleanup,
+} from "../concurrency/index.js";
+
+// ── test setup ────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "concurrency-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── Spec: concurrency-acquire-slot-under-limit ──────────────────────────────
+
+describe("acquireSlot succeeds immediately when below maxRunning", () => {
+  test("creates slot file and returns SlotHandle when under limit", async () => {
+    const handle = await acquireSlot(tmpDir, 2);
+
+    // Slot file exists
+    const slotsDir = getSlotsDir(tmpDir);
+    const files = await readdir(slotsDir);
+    expect(files).toContain(`${process.pid}.slot`);
+
+    // Returns a SlotHandle with release()
+    expect(handle).toHaveProperty("release");
+    expect(typeof handle.release).toBe("function");
+
+    // countActiveSlots returns 1
+    const count = await countActiveSlots(tmpDir);
+    expect(count).toBe(1);
+
+    // Cleanup
+    await handle.release();
+  });
+
+  test("returns immediately (no blocking) when slots available", async () => {
+    const start = Date.now();
+    const handle = await acquireSlot(tmpDir, 2);
+    const elapsed = Date.now() - start;
+
+    // Should complete in well under 1 second (no polling delay)
+    expect(elapsed).toBeLessThan(500);
+
+    await handle.release();
+  });
+});
+
+// ── Spec: concurrency-acquire-slot-blocks-at-limit ──────────────────────────
+
+describe("acquireSlot blocks when at capacity", () => {
+  test("calls onWaiting when all slots are occupied", async () => {
+    // Create a slot file for a "live" process — use parent PID (same user, signalable)
+    const slotsDir = getSlotsDir(tmpDir);
+    await mkdir(slotsDir, { recursive: true });
+    const blockerPid = process.ppid;
+    await writeFile(join(slotsDir, `${blockerPid}.slot`), "", "utf8");
+
+    const onWaiting = vi.fn();
+    const onAcquired = vi.fn();
+
+    // maxRunning=1, one slot occupied → should block
+    // Release the blocking slot after a brief delay
+    setTimeout(async () => {
+      await rm(join(slotsDir, `${blockerPid}.slot`), { force: true });
+    }, 200);
+
+    const handle = await acquireSlot(tmpDir, 1, {
+      onWaiting,
+      onAcquired,
+      pollIntervalMs: 100,
+    });
+
+    expect(onWaiting).toHaveBeenCalled();
+    expect(onAcquired).toHaveBeenCalled();
+
+    await handle.release();
+  });
+
+  test("polls with interval and proceeds after slot is freed", async () => {
+    const slotsDir = getSlotsDir(tmpDir);
+    await mkdir(slotsDir, { recursive: true });
+    const blockerPid = process.ppid;
+    await writeFile(join(slotsDir, `${blockerPid}.slot`), "", "utf8");
+
+    // Remove after 250ms
+    setTimeout(async () => {
+      await rm(join(slotsDir, `${blockerPid}.slot`), { force: true });
+    }, 250);
+
+    const start = Date.now();
+    const handle = await acquireSlot(tmpDir, 1, { pollIntervalMs: 100 });
+    const elapsed = Date.now() - start;
+
+    // Should have waited at least ~200ms (polling)
+    expect(elapsed).toBeGreaterThanOrEqual(150);
+
+    await handle.release();
+  });
+});
+
+// ── Spec: concurrency-stale-slot-cleanup ────────────────────────────────────
+
+describe("cleanStaleSlots removes slot files for dead PIDs", () => {
+  test("removes slot file for dead PID, preserves live PID", async () => {
+    const slotsDir = getSlotsDir(tmpDir);
+    await mkdir(slotsDir, { recursive: true });
+
+    // Dead PID (99999999 should not exist)
+    await writeFile(join(slotsDir, "99999999.slot"), "", "utf8");
+    // Live PID (current process)
+    await writeFile(join(slotsDir, `${process.pid}.slot`), "", "utf8");
+
+    const cleaned = await cleanStaleSlots(tmpDir);
+    expect(cleaned).toBe(1);
+
+    const files = await readdir(slotsDir);
+    expect(files).not.toContain("99999999.slot");
+    expect(files).toContain(`${process.pid}.slot`);
+  });
+
+  test("countActiveSlots reflects correct count after cleanup", async () => {
+    const slotsDir = getSlotsDir(tmpDir);
+    await mkdir(slotsDir, { recursive: true });
+
+    // 1 dead + 1 live
+    await writeFile(join(slotsDir, "99999999.slot"), "", "utf8");
+    await writeFile(join(slotsDir, `${process.pid}.slot`), "", "utf8");
+
+    // Before cleanup: 2 files
+    const beforeFiles = await readdir(slotsDir);
+    expect(beforeFiles.filter((f) => f.endsWith(".slot")).length).toBe(2);
+
+    await cleanStaleSlots(tmpDir);
+
+    // After cleanup
+    const count = await countActiveSlots(tmpDir);
+    expect(count).toBe(1);
+  });
+});
+
+// ── Spec: concurrency-race-protection-rollback ──────────────────────────────
+
+describe("acquireSlot rolls back on race condition", () => {
+  test("rolls back slot file if post-write count exceeds maxRunning", async () => {
+    const slotsDir = getSlotsDir(tmpDir);
+    await mkdir(slotsDir, { recursive: true });
+
+    // Simulate: maxRunning=2, and we already have 1 slot from another live process
+    const blockerPid = process.ppid;
+    await writeFile(join(slotsDir, `${blockerPid}.slot`), "", "utf8");
+
+    // Our process writes its slot, making count=2 which equals maxRunning=2
+    // This should succeed (at limit, not over)
+    const handle = await acquireSlot(tmpDir, 2);
+    const count = await countActiveSlots(tmpDir);
+    expect(count).toBe(2);
+
+    await handle.release();
+  });
+
+  test("when another slot appears during write, rollback occurs", async () => {
+    // This tests the double-check logic. We'll simulate by pre-filling to capacity.
+    const slotsDir = getSlotsDir(tmpDir);
+    await mkdir(slotsDir, { recursive: true });
+
+    // maxRunning=1, one slot already occupied by parent PID
+    const blockerPid = process.ppid;
+    await writeFile(join(slotsDir, `${blockerPid}.slot`), "", "utf8");
+
+    // Release after delay so acquireSlot can proceed
+    setTimeout(async () => {
+      await rm(join(slotsDir, `${blockerPid}.slot`), { force: true });
+    }, 200);
+
+    const handle = await acquireSlot(tmpDir, 1, { pollIntervalMs: 100 });
+
+    // After acquiring, only our slot should exist
+    const files = await readdir(slotsDir);
+    const slotFiles = files.filter((f) => f.endsWith(".slot"));
+    expect(slotFiles).toContain(`${process.pid}.slot`);
+
+    await handle.release();
+  });
+});
+
+// ── Spec: concurrency-exec-signal-cleanup ────────────────────────────────────
+
+describe("installSlotCleanup removes slot on signal", () => {
+  test("release function removes slot file", async () => {
+    const handle = await acquireSlot(tmpDir, 2);
+
+    // Verify slot exists
+    const slotsDir = getSlotsDir(tmpDir);
+    const filesBefore = await readdir(slotsDir);
+    expect(filesBefore).toContain(`${process.pid}.slot`);
+
+    // installSlotCleanup returns a cleanup function
+    const cleanup = installSlotCleanup(handle);
+
+    // Call release directly (simulating what signal handler would do)
+    await handle.release();
+
+    const filesAfter = await readdir(slotsDir);
+    expect(filesAfter).not.toContain(`${process.pid}.slot`);
+
+    // Uninstall the cleanup handler
+    cleanup();
+  });
+});
+
+// ── Spec: concurrency-default-max-running ────────────────────────────────────
+
+describe("DEFAULT_MAX_RUNNING is 2", () => {
+  test("constant equals 2", () => {
+    expect(DEFAULT_MAX_RUNNING).toBe(2);
+  });
+});
+
+// ── Spec: concurrency-exec-uses-slot (unit level) ───────────────────────────
+
+describe("slot lifecycle during exec", () => {
+  test("acquireSlot + release = 0 active slots", async () => {
+    const handle = await acquireSlot(tmpDir, 2);
+    expect(await countActiveSlots(tmpDir)).toBe(1);
+
+    await handle.release();
+    expect(await countActiveSlots(tmpDir)).toBe(0);
+  });
+
+  test("release is idempotent", async () => {
+    const handle = await acquireSlot(tmpDir, 2);
+    await handle.release();
+    // Calling release again should not throw
+    await handle.release();
+    expect(await countActiveSlots(tmpDir)).toBe(0);
+  });
+});
+
+// ── Spec: concurrency-config-set-max-running ─────────────────────────────────
+
+describe("config set concurrency.maxRunning", () => {
+  test("concurrency config key is validated correctly", async () => {
+    // Import config module to test the key validation
+    const { parseDotPath, setNestedValue } = await import("../commands/config.js");
+
+    const config: Record<string, unknown> = {};
+    const path = parseDotPath("concurrency.maxRunning");
+    setNestedValue(config, path, 3);
+
+    expect(config).toEqual({ concurrency: { maxRunning: 3 } });
+  });
+});