@united-workforce/cli 0.3.0 → 0.5.0

package/src/__tests__/thread-list-filters.test.ts

@@ -1,11 +1,11 @@
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { CasRef, ThreadId } from "@united-workforce/protocol";
 import { createThreadIndexEntry } from "@united-workforce/protocol";
 import { extractUlidTimestamp, generateUlid } from "@united-workforce/util";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import { createMarker, deleteMarker } from "../background/index.js";
+import { createMarker, deleteMarker, getProcessStartTime } from "../background/index.js";
 import { cmdThreadList } from "../commands/thread.js";
 import { parseTimeInput } from "../commands/thread-time-parser.js";
 import type { UwfStore } from "../store.js";
@@ -13,19 +13,13 @@ import {
   completeThread as completeThreadInStore,
   createUwfStore,
   loadAllThreads,
+  saveWorkflowRegistry,
   setThread,
 } from "../store.js";
+import { makeUwfStore } from "./thread-test-helpers.js";
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
-async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
-  const casDir = join(storageRoot, "cas");
-  await mkdir(casDir, { recursive: true });
-  // Set OCAS_HOME to use the test's CAS directory
-  process.env.OCAS_HOME = casDir;
-  return createUwfStore(storageRoot);
-}
-
 async function createTestWorkflow(uwf: UwfStore): Promise<CasRef> {
   const workflowPayload = {
     name: "test-workflow",
@@ -66,6 +60,7 @@ async function markThreadRunning(storageRoot: string, threadId: ThreadId, workfl
     workflow,
     pid: process.pid, // Use current process PID so isPidAlive returns true
     startedAt: Date.now(),
+    processStartTime: getProcessStartTime(process.pid),
   });
 }
 
@@ -76,18 +71,25 @@ async function completeThread(
   _headHash: CasRef,
 ) {
   const uwfIdx = await createUwfStore(storageRoot);
-  completeThreadInStore(uwfIdx.varStore, threadId, "completed");
+  completeThreadInStore(uwfIdx.varStore, threadId, "end");
 }
 
 // ── test setup ────────────────────────────────────────────────────────────────
 
 let tmpDir: string;
+let savedOcasHome: string | undefined;
 
 beforeEach(async () => {
+  savedOcasHome = process.env.OCAS_HOME;
   tmpDir = await mkdtemp(join(tmpdir(), "thread-list-filters-test-"));
 });
 
 afterEach(async () => {
+  if (savedOcasHome === undefined) {
+    delete process.env.OCAS_HOME;
+  } else {
+    process.env.OCAS_HOME = savedOcasHome;
+  }
   await rm(tmpDir, { recursive: true, force: true });
 });
 
@@ -135,7 +137,7 @@ describe("cmdThreadList status filter", () => {
     if (thread3Head === undefined) throw new Error("thread3 head not found");
     await completeThread(tmpDir, thread3, workflowHash, thread3Head);
 
-    const result = await cmdThreadList(tmpDir, ["idle", "completed"], null, null, null, null);
+    const result = await cmdThreadList(tmpDir, ["idle", "end"], null, null, null, null);
 
     // Clean up marker
     await deleteMarker(tmpDir, thread2);
@@ -160,14 +162,14 @@ describe("cmdThreadList status filter", () => {
     if (thread3Head === undefined) throw new Error("thread3 head not found");
     await completeThread(tmpDir, thread3, workflowHash, thread3Head);
 
-    const result = await cmdThreadList(tmpDir, ["completed"], null, null, null, null);
+    const result = await cmdThreadList(tmpDir, ["end"], null, null, null, null);
 
     expect(result).toHaveLength(1);
     expect(result[0]?.thread).toBe(thread3);
-    expect(result[0]?.status).toBe("completed");
+    expect(result[0]?.status).toBe("end");
   });
 
-  test("should return all threads when no status filter provided", async () => {
+  test("should return only active threads when no filter and no --all", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const workflowHash = await createTestWorkflow(uwf);
 
@@ -185,8 +187,290 @@ describe("cmdThreadList status filter", () => {
 
     const result = await cmdThreadList(tmpDir, null, null, null, null, null);
 
+    // Default behavior (issue #147): only active threads (idle + running)
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread2].sort());
+
+    // Clean up marker
+    await deleteMarker(tmpDir, thread2);
+  });
+
+  test("should return all threads when --all (showAll=true)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const thread3 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    await markThreadRunning(tmpDir, thread2, workflowHash);
+
+    const uwfIdx = await createUwfStore(tmpDir);
+    const index = loadAllThreads(uwfIdx.varStore);
+    const thread3Head = index[thread3]!.head;
+    if (thread3Head === undefined) throw new Error("thread3 head not found");
+    await completeThread(tmpDir, thread3, workflowHash, thread3Head);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, true);
+
     expect(result).toHaveLength(3);
     expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread2, thread3].sort());
+
+    // Clean up marker
+    await deleteMarker(tmpDir, thread2);
+  });
+});
+
+// ── default behavior tests (issue #147) ───────────────────────────────────────
+
+describe("cmdThreadList default behavior (issue #147)", () => {
+  test("default returns only idle + running threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const threadA = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 4000);
+    const threadB = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const threadC = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const threadD = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    await markThreadRunning(tmpDir, threadB, workflowHash);
+
+    const uwfIdx = await createUwfStore(tmpDir);
+    const index = loadAllThreads(uwfIdx.varStore);
+    const threadCHead = index[threadC]!.head;
+    if (threadCHead === undefined) throw new Error("threadC head not found");
+    await completeThread(tmpDir, threadC, workflowHash, threadCHead);
+
+    // Cancel threadD
+    const threadDHead = index[threadD]!.head;
+    if (threadDHead === undefined) throw new Error("threadD head not found");
+    const uwfCancel = await createUwfStore(tmpDir);
+    completeThreadInStore(uwfCancel.varStore, threadD, "cancelled");
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([threadA, threadB].sort());
+
+    await deleteMarker(tmpDir, threadB);
+  });
+
+  test("default excludes completed threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 6000);
+    const completedThreads: ThreadId[] = [];
+    for (let i = 0; i < 5; i++) {
+      const t = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (5 - i) * 1000);
+      completedThreads.push(t);
+      const uwfIdx = await createUwfStore(tmpDir);
+      const index = loadAllThreads(uwfIdx.varStore);
+      const head = index[t]!.head;
+      if (head === undefined) throw new Error("head not found");
+      await completeThread(tmpDir, t, workflowHash, head);
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(idleThread);
+  });
+
+  test("default excludes cancelled threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 4000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const cancelled: ThreadId[] = [];
+    for (let i = 0; i < 3; i++) {
+      const t = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (3 - i) * 1000);
+      cancelled.push(t);
+      const uwfIdx = await createUwfStore(tmpDir);
+      completeThreadInStore(uwfIdx.varStore, t, "cancelled");
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(runningThread);
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("--all (showAll=true) returns every status", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 4000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const cancelledThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    completeThreadInStore(uwfIdx.varStore, cancelledThread, "cancelled");
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, true);
+
+    expect(result).toHaveLength(4);
+    expect(result.map((r) => r.thread).sort()).toEqual(
+      [idleThread, runningThread, completedThread, cancelledThread].sort(),
+    );
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("explicit --status overrides default (still returns just the filtered statuses)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const _idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const result = await cmdThreadList(tmpDir, ["end"], null, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(completedThread);
+    expect(result[0]?.status).toBe("end");
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("--status active keeps working", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const result = await cmdThreadList(tmpDir, ["idle", "running"], null, null, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([idleThread, runningThread].sort());
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("--status + --all — explicit status wins", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const _idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const result = await cmdThreadList(tmpDir, ["end"], null, null, null, null, true);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(completedThread);
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("default returns empty when no threads", async () => {
+    await makeUwfStore(tmpDir);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(0);
+  });
+
+  test("default + time range filter composes correctly", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const ts1 = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const ts2 = Date.UTC(2026, 4, 21, 0, 0, 0);
+    const ts3 = Date.UTC(2026, 4, 22, 0, 0, 0);
+    const ts4 = Date.UTC(2026, 4, 23, 0, 0, 0);
+    const ts5 = Date.UTC(2026, 4, 24, 0, 0, 0);
+
+    const _t1 = await createTestThread(uwf, tmpDir, workflowHash, ts1);
+    const t2 = await createTestThread(uwf, tmpDir, workflowHash, ts2);
+    const t3 = await createTestThread(uwf, tmpDir, workflowHash, ts3);
+    const t4 = await createTestThread(uwf, tmpDir, workflowHash, ts4);
+    const _t5 = await createTestThread(uwf, tmpDir, workflowHash, ts5);
+
+    // Mark t3 running
+    await markThreadRunning(tmpDir, t3, workflowHash);
+
+    // Complete t4 (should be excluded by default)
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const t4head = idx[t4]!.head;
+    if (t4head === undefined) throw new Error("t4 head not found");
+    await completeThread(tmpDir, t4, workflowHash, t4head);
+
+    // afterMs in middle of range to exclude _t1
+    const afterMs = Date.UTC(2026, 4, 20, 12, 0, 0);
+    const result = await cmdThreadList(tmpDir, null, afterMs, null, null, null);
+
+    // Expected: t2 (idle), t3 (running), _t5 (idle); excludes t4 (completed) and _t1 (filtered by time)
+    expect(result).toHaveLength(3);
+    const ids = result.map((r) => r.thread).sort();
+    expect(ids).toEqual([t2, t3, _t5].sort());
+
+    await deleteMarker(tmpDir, t3);
+  });
+
+  test("default + pagination composes correctly", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    // Create 10 idle threads + 5 completed threads
+    const idleThreads: ThreadId[] = [];
+    for (let i = 0; i < 10; i++) {
+      idleThreads.push(
+        await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (15 - i) * 1000),
+      );
+    }
+    for (let i = 0; i < 5; i++) {
+      const t = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (5 - i) * 1000);
+      const uwfIdx = await createUwfStore(tmpDir);
+      const idx = loadAllThreads(uwfIdx.varStore);
+      const head = idx[t]!.head;
+      if (head === undefined) throw new Error("head not found");
+      await completeThread(tmpDir, t, workflowHash, head);
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, 2, 3);
+
+    expect(result).toHaveLength(3);
+    // All results should be idle (default excludes completed)
+    for (const r of result) {
+      expect(r.status).toBe("idle");
+    }
   });
 });
 
@@ -382,11 +666,11 @@ describe("combined filters", () => {
       await completeThread(tmpDir, thread, workflowHash, headHash);
     }
 
-    const result = await cmdThreadList(tmpDir, ["completed"], null, null, 3, 5);
+    const result = await cmdThreadList(tmpDir, ["end"], null, null, 3, 5);
 
     expect(result).toHaveLength(5);
     for (const r of result) {
-      expect(r.status).toBe("completed");
+      expect(r.status).toBe("end");
     }
   });
 
@@ -570,3 +854,145 @@ describe("ISO date parsing", () => {
     expect(() => parseTimeInput("invalid", nowMs)).toThrow();
   });
 });
+
+// ── corrupt thread resilience (#250) ──────────────────────────────────────────
+
+describe("corrupt thread resilience (#250)", () => {
+  test("thread list returns corrupt entry when CAS node is missing", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+
+    // Create a valid thread
+    const workflowHash = await createTestWorkflow(uwf);
+    const now = Date.now();
+    const _validId = await createTestThread(uwf, tmpDir, workflowHash, now);
+
+    // Create another thread with a unique start node, then delete its workflow CAS to corrupt it
+    const corruptThreadId = generateUlid(now + 1000) as ThreadId;
+    const startPayload = {
+      workflow: workflowHash,
+      prompt: "corrupt thread prompt — unique to avoid CAS hash collision",
+      cwd: tmpDir,
+    };
+    const headHash = await uwf.store.cas.put(uwf.schemas.startNode, startPayload);
+    setThread(uwf.varStore, corruptThreadId, createThreadIndexEntry(headHash));
+
+    // Delete the workflow CAS node — start node still exists but workflow ref dangles
+    uwf.store.cas.delete(workflowHash);
+
+    // thread list should NOT throw — it should return both threads
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, true);
+
+    // Both threads should appear (the valid one is now also corrupt since workflow is shared)
+    // In practice: both become corrupt because they share the same workflow CAS node
+    // This matches the real scenario from issue #250 — gc deleted a shared node
+    expect(result.length).toBeGreaterThanOrEqual(2);
+    const corruptItems = result.filter((r) => r.status === "corrupt");
+    expect(corruptItems.length).toBeGreaterThanOrEqual(1);
+    for (const item of corruptItems) {
+      expect(item.statusDisplay).toBe("corrupt");
+    }
+  });
+
+  test("corrupt threads appear in default filter (without --all)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    // Create a thread then corrupt it
+    const corruptId = await createTestThread(uwf, tmpDir, workflowHash, Date.now());
+    const corruptEntry = loadAllThreads(uwf.varStore)[corruptId];
+    uwf.store.cas.delete(corruptEntry.head);
+
+    // Default filter (no --all, no --status) should include corrupt
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, false);
+    expect(result).toHaveLength(1);
+    expect(result[0].status).toBe("corrupt");
+  });
+});
+
+// ── orphan thread detection (#286) ────────────────────────────────────────────
+
+describe("orphan thread detection (#286)", () => {
+  test("thread list includes workflowName when workflow is in registry", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    // Register the workflow in registry
+    saveWorkflowRegistry(uwf.varStore, "test-workflow", workflowHash);
+
+    const threadId = await createTestThread(uwf, tmpDir, workflowHash, Date.now());
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, false);
+    expect(result).toHaveLength(1);
+    expect(result[0].thread).toBe(threadId);
+    expect(result[0].workflowName).toBe("test-workflow");
+  });
+
+  test("thread list returns workflowName: null for orphaned threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    // Do NOT register the workflow — thread is orphaned
+    const threadId = await createTestThread(uwf, tmpDir, workflowHash, Date.now());
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, false);
+    expect(result).toHaveLength(1);
+    expect(result[0].thread).toBe(threadId);
+    expect(result[0].workflowName).toBeNull();
+  });
+
+  test("mixed registered and orphaned threads in the same list", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    // Register the workflow
+    saveWorkflowRegistry(uwf.varStore, "test-workflow", workflowHash);
+
+    // Create a thread using the registered workflow
+    const now = Date.now();
+    const registeredId = await createTestThread(uwf, tmpDir, workflowHash, now);
+
+    // Create a second workflow (different hash), not registered
+    const orphanWorkflowPayload = {
+      name: "orphan-workflow",
+      roles: {
+        role1: {
+          goal: "orphan goal",
+          outputSchema: { type: "object" as const, properties: {} },
+        },
+      },
+      graph: { start: "role1" },
+      conditions: {},
+    };
+    const orphanHash = await uwf.store.cas.put(uwf.schemas.workflow, orphanWorkflowPayload);
+    const orphanId = await createTestThread(uwf, tmpDir, orphanHash, now + 1000);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, false);
+    expect(result).toHaveLength(2);
+
+    // Sorted newest first, so orphan (later timestamp) comes first
+    const orphanItem = result.find((r) => r.thread === orphanId);
+    const registeredItem = result.find((r) => r.thread === registeredId);
+
+    expect(orphanItem).toBeDefined();
+    expect(orphanItem!.workflowName).toBeNull();
+
+    expect(registeredItem).toBeDefined();
+    expect(registeredItem!.workflowName).toBe("test-workflow");
+  });
+
+  test("corrupt threads have workflowName: null", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+    saveWorkflowRegistry(uwf.varStore, "test-workflow", workflowHash);
+
+    // Create a thread then corrupt it by deleting its head CAS node
+    const corruptId = await createTestThread(uwf, tmpDir, workflowHash, Date.now());
+    const corruptEntry = loadAllThreads(uwf.varStore)[corruptId];
+    uwf.store.cas.delete(corruptEntry.head);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, false);
+    expect(result).toHaveLength(1);
+    expect(result[0].status).toBe("corrupt");
+    expect(result[0].workflowName).toBeNull();
+  });
+});

package/src/__tests__/thread-list-template-ms-date.test.ts

@@ -0,0 +1,110 @@
+import { OUTPUT_TEMPLATES } from "@united-workforce/protocol";
+import { Liquid } from "liquidjs";
+import { describe, expect, test } from "vitest";
+
+/**
+ * Issue #351 — `uwf thread list --format text` rendered the `STARTED` column
+ * as `58414-12-06` because `THREAD_LIST_TEMPLATE` piped `item.startedAt` (Unix
+ * **ms** per `THREAD_LIST_OUTPUT_SCHEMA`) directly into LiquidJS's `| date`
+ * filter, which expects Unix **seconds**.
+ *
+ * This integration test renders the template against a known ms timestamp
+ * and asserts the year falls within the realistic 20xx range, confirming
+ * the ms→s conversion is in place at the protocol layer.
+ */
+
+function makeEngine(): Liquid {
+  return new Liquid({ cache: false, strictFilters: false, strictVariables: false });
+}
+
+describe("THREAD_LIST_TEMPLATE rendering — issue #351 ms→s for `| date`", () => {
+  test("renders item.startedAt=1781229932779 as a 2026 calendar date (not 58414)", async () => {
+    const engine = makeEngine();
+    const out = await engine.parseAndRender(OUTPUT_TEMPLATES["thread-list"], {
+      items: [
+        {
+          threadId: "01K5HMKZQB7VDA8E2K9P3R5XBC",
+          workflowHash: "WF1234567890A",
+          workflowName: null,
+          status: "idle",
+          currentRole: "planner",
+          startedAt: 1781229932779,
+          completedAt: null,
+        },
+      ],
+    });
+
+    expect(out).not.toContain("58414");
+    expect(out).toMatch(/\b20\d{2}-\d{2}-\d{2}\b/);
+    // The STARTED cell must NOT begin with a 5-digit year.
+    expect(out).not.toMatch(/\b\d{5}-\d{2}-\d{2}\b/);
+  });
+
+  test("renders `-` for items with startedAt=null (null guard preserved)", async () => {
+    const engine = makeEngine();
+    const out = await engine.parseAndRender(OUTPUT_TEMPLATES["thread-list"], {
+      items: [
+        {
+          threadId: "01K5HMKZQB7VDA8E2K9P3R5XBC",
+          workflowHash: "WF1234567890A",
+          workflowName: null,
+          status: "idle",
+          currentRole: "planner",
+          startedAt: null,
+          completedAt: null,
+        },
+      ],
+    });
+
+    expect(out).not.toContain("58414");
+    expect(out).not.toContain("Invalid Date");
+    expect(out).not.toContain("1970-01-01");
+    // Last token of the row is the rendered STARTED cell — must be `-`.
+    const dataRow = out
+      .split("\n")
+      .find((line: string) => line.includes("01K5HMKZQB7VDA8E2K9P3R5XBC"));
+    expect(dataRow).toBeDefined();
+    expect(dataRow?.trimEnd().endsWith("-")).toBe(true);
+  });
+
+  test("renders multiple ms timestamps across years 2020–2030 with correct year prefix", async () => {
+    const engine = makeEngine();
+    const items = [
+      {
+        threadId: "ID1",
+        workflowHash: "WF",
+        workflowName: null,
+        status: "idle",
+        currentRole: null,
+        startedAt: Date.UTC(2020, 0, 1, 0, 0, 0),
+        completedAt: null,
+      },
+      {
+        threadId: "ID2",
+        workflowHash: "WF",
+        workflowName: null,
+        status: "idle",
+        currentRole: null,
+        startedAt: Date.UTC(2026, 5, 12, 5, 25, 0),
+        completedAt: null,
+      },
+      {
+        threadId: "ID3",
+        workflowHash: "WF",
+        workflowName: null,
+        status: "idle",
+        currentRole: null,
+        startedAt: Date.UTC(2030, 11, 31, 23, 59, 0),
+        completedAt: null,
+      },
+    ];
+
+    const out = await engine.parseAndRender(OUTPUT_TEMPLATES["thread-list"], { items });
+
+    expect(out).toContain("2020-");
+    expect(out).toContain("2026-");
+    expect(out).toContain("2030-");
+    expect(out).not.toContain("58414");
+    expect(out).not.toMatch(/\b\d{5}-\d{2}-\d{2}\b/);
+  });
+});