@united-workforce/cli 0.7.0 → 0.8.1

package/src/__tests__/store-turn-chain.test.ts

@@ -0,0 +1,386 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, StepStartPayload, TurnNodePayload } from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { turnsOfStep, walkTurnChain, writeStepStart, writeTurnNode } from "../store.js";
+import { makeUwfStore } from "./thread-test-helpers.js";
+
+let tmpDir: string;
+let savedOcasHome: string | undefined;
+
+beforeEach(async () => {
+  savedOcasHome = process.env.OCAS_HOME;
+  tmpDir = await mkdtemp(join(tmpdir(), "uwf-turn-chain-test-"));
+});
+
+afterEach(async () => {
+  if (savedOcasHome === undefined) {
+    delete process.env.OCAS_HOME;
+  } else {
+    process.env.OCAS_HOME = savedOcasHome;
+  }
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("writeStepStart", () => {
+  test("creates step-start nodes linked via prev", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const startRef = (await uwf.store.cas.put(uwf.schemas.text, "thread-start")) as CasRef;
+
+    // Step 0: first step (prev = null)
+    const step0Payload: StepStartPayload = {
+      role: "planner",
+      edgePrompt: "Analyze the issue",
+      stepIndex: 0,
+      prev: null,
+      start: startRef,
+      startedAtMs: 1000,
+      cwd: "/repo",
+    };
+    const ss0 = writeStepStart(uwf, step0Payload);
+
+    // Step 1: linked to step 0
+    const step1Payload: StepStartPayload = {
+      role: "developer",
+      edgePrompt: "Implement the fix",
+      stepIndex: 1,
+      prev: ss0,
+      start: startRef,
+      startedAtMs: 2000,
+      cwd: "/repo",
+    };
+    const ss1 = writeStepStart(uwf, step1Payload);
+
+    // Step 2: linked to step 1
+    const step2Payload: StepStartPayload = {
+      role: "reviewer",
+      edgePrompt: "Review the changes",
+      stepIndex: 2,
+      prev: ss1,
+      start: startRef,
+      startedAtMs: 3000,
+      cwd: "/repo",
+    };
+    const ss2 = writeStepStart(uwf, step2Payload);
+
+    // Verify hashes are distinct
+    expect(ss0).not.toBe(ss1);
+    expect(ss1).not.toBe(ss2);
+    expect(ss0).not.toBe(ss2);
+
+    // Verify each is 13-char Crockford Base32
+    expect(ss0.length).toBe(13);
+    expect(ss1.length).toBe(13);
+    expect(ss2.length).toBe(13);
+
+    // Verify nodes can be retrieved and contain exact payloads
+    const node0 = uwf.store.cas.get(ss0);
+    const node1 = uwf.store.cas.get(ss1);
+    const node2 = uwf.store.cas.get(ss2);
+
+    expect(node0).not.toBeNull();
+    expect(node1).not.toBeNull();
+    expect(node2).not.toBeNull();
+
+    const payload0 = node0?.payload as StepStartPayload;
+    const payload1 = node1?.payload as StepStartPayload;
+    const payload2 = node2?.payload as StepStartPayload;
+
+    expect(payload0.role).toBe("planner");
+    expect(payload0.stepIndex).toBe(0);
+    expect(payload0.prev).toBeNull();
+
+    expect(payload1.role).toBe("developer");
+    expect(payload1.stepIndex).toBe(1);
+    expect(payload1.prev).toBe(ss0);
+
+    expect(payload2.role).toBe("reviewer");
+    expect(payload2.stepIndex).toBe(2);
+    expect(payload2.prev).toBe(ss1);
+
+    // Verify walking the chain from SS2 via prev yields [SS2, SS1, SS0]
+    const chain: CasRef[] = [];
+    let currentHash: CasRef | null = ss2;
+    while (currentHash !== null) {
+      chain.push(currentHash);
+      const node = uwf.store.cas.get(currentHash);
+      if (node === null) break;
+      const payload = node.payload as StepStartPayload;
+      currentHash = payload.prev;
+    }
+    expect(chain).toEqual([ss2, ss1, ss0]);
+
+    // Verify stepIndex values in chain order
+    expect((uwf.store.cas.get(chain[0])?.payload as StepStartPayload).stepIndex).toBe(2);
+    expect((uwf.store.cas.get(chain[1])?.payload as StepStartPayload).stepIndex).toBe(1);
+    expect((uwf.store.cas.get(chain[2])?.payload as StepStartPayload).stepIndex).toBe(0);
+  });
+});
+
+describe("walkTurnChain", () => {
+  test("traverses turns via prev pointers in chronological order", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const startRef = (await uwf.store.cas.put(uwf.schemas.text, "thread-start")) as CasRef;
+
+    // Create step-start nodes
+    const ss0 = writeStepStart(uwf, {
+      role: "planner",
+      edgePrompt: "Plan",
+      stepIndex: 0,
+      prev: null,
+      start: startRef,
+      startedAtMs: 1000,
+      cwd: "/repo",
+    });
+    const ss1 = writeStepStart(uwf, {
+      role: "developer",
+      edgePrompt: "Develop",
+      stepIndex: 1,
+      prev: ss0,
+      start: startRef,
+      startedAtMs: 2000,
+      cwd: "/repo",
+    });
+    const ss2 = writeStepStart(uwf, {
+      role: "reviewer",
+      edgePrompt: "Review",
+      stepIndex: 2,
+      prev: ss1,
+      start: startRef,
+      startedAtMs: 3000,
+      cwd: "/repo",
+    });
+
+    // Create 6 turns with prev links
+    const t0 = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Step 1 analysis",
+      prev: null,
+      owner: ss0,
+    });
+    const t1 = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Step 1 continued",
+      prev: t0,
+      owner: ss0,
+    });
+    const t2 = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Step 2 start",
+      prev: t1,
+      owner: ss1,
+    });
+    const t3 = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Step 2 continued",
+      prev: t2,
+      owner: ss1,
+    });
+    const t4 = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Step 3 start",
+      prev: t3,
+      owner: ss2,
+    });
+    const t5 = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Step 3 final",
+      prev: t4,
+      owner: ss2,
+    });
+
+    // Walk from head (t5)
+    const result = walkTurnChain(uwf, t5);
+
+    // Verify returns 6 hashes in chronological order (oldest first)
+    expect(result).toHaveLength(6);
+    expect(result).toEqual([t0, t1, t2, t3, t4, t5]);
+
+    // Verify content matches
+    const contents = result.map((h) => {
+      const node = uwf.store.cas.get(h);
+      return (node?.payload as TurnNodePayload).content;
+    });
+    expect(contents).toEqual([
+      "Step 1 analysis",
+      "Step 1 continued",
+      "Step 2 start",
+      "Step 2 continued",
+      "Step 3 start",
+      "Step 3 final",
+    ]);
+  });
+
+  test("returns single-element array for turn with null prev", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const startRef = (await uwf.store.cas.put(uwf.schemas.text, "thread-start")) as CasRef;
+
+    const ss0 = writeStepStart(uwf, {
+      role: "planner",
+      edgePrompt: "Plan",
+      stepIndex: 0,
+      prev: null,
+      start: startRef,
+      startedAtMs: 1000,
+      cwd: "/repo",
+    });
+
+    const t0 = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Single turn",
+      prev: null,
+      owner: ss0,
+    });
+
+    const result = walkTurnChain(uwf, t0);
+    expect(result).toEqual([t0]);
+  });
+});
+
+describe("turnsOfStep", () => {
+  test("returns only turns belonging to a specific step-start", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const startRef = (await uwf.store.cas.put(uwf.schemas.text, "thread-start")) as CasRef;
+
+    // Create step-start nodes
+    const ss0 = writeStepStart(uwf, {
+      role: "planner",
+      edgePrompt: "Plan",
+      stepIndex: 0,
+      prev: null,
+      start: startRef,
+      startedAtMs: 1000,
+      cwd: "/repo",
+    });
+    const ss1 = writeStepStart(uwf, {
+      role: "developer",
+      edgePrompt: "Develop",
+      stepIndex: 1,
+      prev: ss0,
+      start: startRef,
+      startedAtMs: 2000,
+      cwd: "/repo",
+    });
+    const ss2 = writeStepStart(uwf, {
+      role: "reviewer",
+      edgePrompt: "Review",
+      stepIndex: 2,
+      prev: ss1,
+      start: startRef,
+      startedAtMs: 3000,
+      cwd: "/repo",
+    });
+
+    // Create 6 turns with different owners (2 per step)
+    const t0 = writeTurnNode(uwf, { role: "assistant", content: "T0", prev: null, owner: ss0 });
+    const t1 = writeTurnNode(uwf, { role: "assistant", content: "T1", prev: t0, owner: ss0 });
+    const t2 = writeTurnNode(uwf, { role: "assistant", content: "T2", prev: t1, owner: ss1 });
+    const t3 = writeTurnNode(uwf, { role: "assistant", content: "T3", prev: t2, owner: ss1 });
+    const t4 = writeTurnNode(uwf, { role: "assistant", content: "T4", prev: t3, owner: ss2 });
+    const t5 = writeTurnNode(uwf, { role: "assistant", content: "T5", prev: t4, owner: ss2 });
+
+    // Filter for SS1's turns
+    const result = turnsOfStep(uwf, t5, ss1);
+
+    // Should return exactly T2 and T3 in chronological order
+    expect(result).toHaveLength(2);
+    expect(result).toEqual([t2, t3]);
+  });
+
+  test("returns empty array when no turns match the step", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const startRef = (await uwf.store.cas.put(uwf.schemas.text, "thread-start")) as CasRef;
+
+    const ss0 = writeStepStart(uwf, {
+      role: "planner",
+      edgePrompt: "Plan",
+      stepIndex: 0,
+      prev: null,
+      start: startRef,
+      startedAtMs: 1000,
+      cwd: "/repo",
+    });
+    const ssOther = writeStepStart(uwf, {
+      role: "other",
+      edgePrompt: "Other",
+      stepIndex: 1,
+      prev: ss0,
+      start: startRef,
+      startedAtMs: 2000,
+      cwd: "/repo",
+    });
+
+    const t0 = writeTurnNode(uwf, { role: "assistant", content: "T0", prev: null, owner: ss0 });
+    const t1 = writeTurnNode(uwf, { role: "assistant", content: "T1", prev: t0, owner: ss0 });
+
+    // Filter for ssOther's turns (should be empty)
+    const result = turnsOfStep(uwf, t1, ssOther);
+    expect(result).toEqual([]);
+  });
+});
+
+describe("legacy turn compatibility", () => {
+  test("legacy turns without prev/owner read as null", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+
+    // Simulate legacy turn by writing with null prev/owner
+    const legacyTurn = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Some output",
+      prev: null,
+      owner: null,
+    });
+
+    // Reading should succeed
+    const node = uwf.store.cas.get(legacyTurn);
+    expect(node).not.toBeNull();
+
+    const payload = node?.payload as TurnNodePayload;
+    expect(payload.prev).toBeNull();
+    expect(payload.owner).toBeNull();
+    expect(payload.role).toBe("assistant");
+    expect(payload.content).toBe("Some output");
+  });
+
+  test("walkTurnChain handles legacy turn with null prev", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+
+    const legacyTurn = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Legacy content",
+      prev: null,
+      owner: null,
+    });
+
+    // Should return single-element array
+    const result = walkTurnChain(uwf, legacyTurn);
+    expect(result).toEqual([legacyTurn]);
+  });
+
+  test("turnsOfStep returns empty for legacy turn with null owner", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const startRef = (await uwf.store.cas.put(uwf.schemas.text, "thread-start")) as CasRef;
+
+    const anyStepHash = writeStepStart(uwf, {
+      role: "planner",
+      edgePrompt: "Plan",
+      stepIndex: 0,
+      prev: null,
+      start: startRef,
+      startedAtMs: 1000,
+      cwd: "/repo",
+    });
+
+    const legacyTurn = writeTurnNode(uwf, {
+      role: "assistant",
+      content: "Legacy content",
+      prev: null,
+      owner: null,
+    });
+
+    // Legacy turn's owner is null, won't match any step
+    const result = turnsOfStep(uwf, legacyTurn, anyStepHash);
+    expect(result).toEqual([]);
+  });
+});

package/src/__tests__/thread-list-limit-offset.test.ts

@@ -0,0 +1,305 @@
+/**
+ * #451 — `uwf thread list --limit <n> / --offset <m>` pagination.
+ *
+ * Spec: specs/thread-list-limit-offset-pagination.md
+ *
+ * `thread list` already paginates internally (cmdThreadList skip/take +
+ * applyPagination over the newest-first list). #451 wires the canonical
+ * repo-wide `ListOptions` vocabulary (`--limit`/`--offset`, as used by
+ * `step turns`) through to that engine, keeping `--skip`/`--take` as
+ * backward-compatible aliases. The behavioural gap is purely at the CLI flag
+ * layer: passing `--limit` today errors with `unknown option`.
+ *
+ * This file covers:
+ *   1. The `cmdThreadList` slice semantics that `--limit`/`--offset` map onto
+ *      (offset → skip, limit → take) — equivalence with the existing
+ *      `--skip`/`--take` parameters.
+ *   2. A CLI subprocess test (`execFileSync`) proving the new flags are
+ *      registered and parsed end-to-end (the actual #451 regression), and that
+ *      `--limit`/`--offset` produce the same output as `--take`/`--skip`.
+ *
+ * Follows the subprocess pattern from step-turns-cli-subprocess.test.ts.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CasRef, ThreadId } from "@united-workforce/protocol";
+import { createThreadIndexEntry } from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdThreadList } from "../commands/thread.js";
+import { createUwfStore, setThread, type UwfStore } from "../store.js";
+import { makeUwfStore } from "./thread-test-helpers.js";
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+async function createTestWorkflow(uwf: UwfStore): Promise<CasRef> {
+  const workflowPayload = {
+    name: "test-workflow",
+    roles: {
+      role1: {
+        goal: "test goal",
+        outputSchema: { type: "object" as const, properties: {} },
+      },
+    },
+    graph: { start: "role1" },
+    conditions: {},
+  };
+  return await uwf.store.cas.put(uwf.schemas.workflow, workflowPayload);
+}
+
+/**
+ * Create a thread with an explicit ULID derived from `timestamp`, so the
+ * newest-first sort (by ULID timestamp) is deterministic.
+ */
+async function createTestThreadAt(
+  uwf: UwfStore,
+  storageRoot: string,
+  workflowHash: CasRef,
+  ulid: string,
+): Promise<ThreadId> {
+  const threadId = ulid as ThreadId;
+  const startPayload = {
+    workflow: workflowHash,
+    prompt: "test prompt",
+    cwd: storageRoot,
+  };
+  const headHash = await uwf.store.cas.put(uwf.schemas.startNode, startPayload);
+  setThread(uwf.varStore, threadId, createThreadIndexEntry(headHash));
+  return threadId;
+}
+
+// ── test setup ──────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let savedOcasHome: string | undefined;
+
+beforeEach(async () => {
+  savedOcasHome = process.env.OCAS_HOME;
+  tmpDir = await mkdtemp(join(tmpdir(), "thread-list-limit-offset-test-"));
+});
+
+afterEach(async () => {
+  if (savedOcasHome === undefined) {
+    delete process.env.OCAS_HOME;
+  } else {
+    process.env.OCAS_HOME = savedOcasHome;
+  }
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── cmdThreadList: --offset → skip, --limit → take mapping ───────────────────
+
+describe("cmdThreadList --limit/--offset mapping (#451)", () => {
+  /**
+   * Seed N threads with monotonically increasing ULID timestamps and return
+   * the thread IDs in newest-first order (the order `cmdThreadList` returns).
+   */
+  async function seedNewestFirst(count: number): Promise<{ newestFirst: ThreadId[] }> {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+    const created: ThreadId[] = [];
+    // Distinct, strictly increasing ULID timestamps (ms) → deterministic order.
+    const base = Date.UTC(2026, 0, 1, 0, 0, 0);
+    for (let i = 0; i < count; i++) {
+      // generateUlid is timestamp-prefixed; use the store's helper indirectly by
+      // constructing via createTestThreadAt with a fabricated monotonic ULID.
+      const { generateUlid } = await import("@united-workforce/util");
+      const ulid = generateUlid(base + i * 1000);
+      created.push(await createTestThreadAt(uwf, tmpDir, workflowHash, ulid));
+    }
+    // Newest-first = reverse of creation order (later timestamp = newer).
+    return { newestFirst: [...created].reverse() };
+  }
+
+  test("--limit N maps to take: returns the N newest threads", async () => {
+    const { newestFirst } = await seedNewestFirst(12);
+
+    // --limit 5 ⇒ cmdThreadList(..., skip=null, take=5)
+    const result = await cmdThreadList(tmpDir, null, null, null, null, 5);
+
+    expect(result).toHaveLength(5);
+    expect(result.map((r) => r.thread)).toEqual(newestFirst.slice(0, 5));
+  });
+
+  test("--offset M maps to skip: skips the M newest threads", async () => {
+    const { newestFirst } = await seedNewestFirst(12);
+
+    // --offset 3 ⇒ cmdThreadList(..., skip=3, take=null)
+    const result = await cmdThreadList(tmpDir, null, null, null, 3, null);
+
+    expect(result).toHaveLength(9);
+    expect(result.map((r) => r.thread)).toEqual(newestFirst.slice(3));
+  });
+
+  test("--limit 5 --offset 10 ⇒ slice [10, 15) over the newest-first list", async () => {
+    const { newestFirst } = await seedNewestFirst(20);
+
+    // skip=10 (offset), take=5 (limit)
+    const result = await cmdThreadList(tmpDir, null, null, null, 10, 5);
+
+    expect(result.map((r) => r.thread)).toEqual(newestFirst.slice(10, 15));
+  });
+
+  test("--limit/--offset are equivalent to the legacy --take/--skip params", async () => {
+    await seedNewestFirst(12);
+
+    // limit==take, offset==skip → identical underlying call → identical result.
+    const viaLimitOffset = await cmdThreadList(tmpDir, null, null, null, 4, 3);
+    const viaSkipTake = await cmdThreadList(tmpDir, null, null, null, 4, 3);
+
+    expect(viaLimitOffset.map((r) => r.thread)).toEqual(viaSkipTake.map((r) => r.thread));
+  });
+
+  test("--offset beyond total → empty list (graceful, no error)", async () => {
+    await seedNewestFirst(3);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, 5, null);
+
+    expect(result).toHaveLength(0);
+  });
+
+  test("--limit larger than remaining clamps to available range", async () => {
+    await seedNewestFirst(3);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, 10);
+
+    expect(result).toHaveLength(3);
+  });
+
+  test("ordering invariant: contiguous non-overlapping windows", async () => {
+    const { newestFirst } = await seedNewestFirst(15);
+
+    // Window A: offset 0, limit 5 → [0,5)
+    const windowA = await cmdThreadList(tmpDir, null, null, null, 0, 5);
+    // Window B: offset 5, limit 5 → [5,10)
+    const windowB = await cmdThreadList(tmpDir, null, null, null, 5, 5);
+
+    expect(windowA.map((r) => r.thread)).toEqual(newestFirst.slice(0, 5));
+    expect(windowB.map((r) => r.thread)).toEqual(newestFirst.slice(5, 10));
+    // Non-overlapping.
+    const overlap = windowA
+      .map((r) => r.thread)
+      .filter((t) => windowB.map((b) => b.thread).includes(t));
+    expect(overlap).toHaveLength(0);
+  });
+});
+
+// ── CLI subprocess: --limit/--offset flag registration (#451) ────────────────
+
+describe("uwf thread list --limit/--offset CLI subprocess (#451)", () => {
+  let cliTmp: string;
+  let storageRoot: string;
+  let casDir: string;
+  let savedUwfHome: string | undefined;
+  let savedOcas: string | undefined;
+
+  beforeEach(async () => {
+    savedUwfHome = process.env.UWF_HOME;
+    savedOcas = process.env.OCAS_HOME;
+    cliTmp = join(tmpdir(), `uwf-thread-list-limit-offset-cli-${Date.now()}`);
+    storageRoot = join(cliTmp, "storage");
+    casDir = join(cliTmp, "cas");
+    await mkdir(storageRoot, { recursive: true });
+    await mkdir(casDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (savedUwfHome === undefined) delete process.env.UWF_HOME;
+    else process.env.UWF_HOME = savedUwfHome;
+    if (savedOcas === undefined) delete process.env.OCAS_HOME;
+    else process.env.OCAS_HOME = savedOcas;
+    await rm(cliTmp, { recursive: true, force: true });
+  });
+
+  async function seedThreads(count: number): Promise<ThreadId[]> {
+    process.env.OCAS_HOME = casDir;
+    const uwf = await createUwfStore(storageRoot);
+    const workflowHash = await createTestWorkflow(uwf);
+    const { generateUlid } = await import("@united-workforce/util");
+    const created: ThreadId[] = [];
+    const base = Date.UTC(2026, 0, 1, 0, 0, 0);
+    for (let i = 0; i < count; i++) {
+      const ulid = generateUlid(base + i * 1000);
+      created.push(await createTestThreadAt(uwf, storageRoot, workflowHash, ulid));
+    }
+    // newest-first
+    return [...created].reverse();
+  }
+
+  function runCli(args: string[]): { threadIds: string[] } {
+    const pkgRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const uwfBin = join(pkgRoot, "dist", "cli.js");
+    const stdout = execFileSync(process.execPath, [uwfBin, ...args], {
+      env: { ...process.env, UWF_HOME: storageRoot, OCAS_HOME: casDir },
+      encoding: "utf8",
+    });
+    const envelope = JSON.parse(stdout) as { value: { items: Array<{ threadId: string }> } };
+    return { threadIds: envelope.value.items.map((it) => it.threadId) };
+  }
+
+  test("--limit 5 is accepted (no 'unknown option') and returns 5 newest", async () => {
+    const newestFirst = await seedThreads(12);
+
+    const { threadIds } = runCli(["thread", "list", "--format", "json", "--limit", "5"]);
+
+    expect(threadIds).toHaveLength(5);
+    expect(threadIds).toEqual(newestFirst.slice(0, 5));
+  });
+
+  test("--limit 5 --offset 10 returns the [10,15) window of the newest-first list", async () => {
+    const newestFirst = await seedThreads(20);
+
+    const { threadIds } = runCli([
+      "thread",
+      "list",
+      "--format",
+      "json",
+      "--limit",
+      "5",
+      "--offset",
+      "10",
+    ]);
+
+    expect(threadIds).toEqual(newestFirst.slice(10, 15));
+  });
+
+  test("--limit/--offset produce the same result as --take/--skip aliases", async () => {
+    await seedThreads(12);
+
+    const canonical = runCli([
+      "thread",
+      "list",
+      "--format",
+      "json",
+      "--limit",
+      "4",
+      "--offset",
+      "3",
+    ]);
+    const legacy = runCli(["thread", "list", "--format", "json", "--take", "4", "--skip", "3"]);
+
+    expect(canonical.threadIds).toEqual(legacy.threadIds);
+  });
+
+  test("non-numeric --limit is a CLI usage error (non-zero exit, flag named verbatim)", async () => {
+    await seedThreads(3);
+    const pkgRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const uwfBin = join(pkgRoot, "dist", "cli.js");
+
+    try {
+      execFileSync(
+        process.execPath,
+        [uwfBin, "thread", "list", "--format", "json", "--limit", "abc"],
+        { env: { ...process.env, UWF_HOME: storageRoot, OCAS_HOME: casDir }, encoding: "utf8" },
+      );
+      expect.fail("expected non-zero exit for non-numeric --limit");
+    } catch (err) {
+      const e = err as { status: number; stderr?: string };
+      expect(e.status).not.toBe(0);
+      expect(e.stderr ?? "").toContain("--limit");
+    }
+  });
+});