@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/multi-task-flow/tests/conversation-archive.test.ts

@@ -0,0 +1,188 @@
+import { test, expect } from "bun:test";
+import { apply } from "../lib/engine";
+import { rmSync } from "node:fs";
+import { fixtureRun, serviceFixture } from "./service-fixture";
+import { retryConversationArchive, retryConversationUnarchive, sweepConversationArchives, type ArchiveProvider } from "../lib/conversation-archive";
+
+function fixture() {
+  const { root, state } = serviceFixture();
+  const { store } = fixtureRun(state.paths.data);
+  const ledger = store.read();
+  const task = ledger.tasks.find((task: any) => task.thread_id)!;
+  store.update(raw => {
+    raw.tasks.find((item: any) => item.id === task.id).state = "completed";
+    raw.operations = raw.operations.filter((op: any) => !["claimed", "unknown"].includes(op.status));
+    raw.notifications = [];
+    raw.follow_prs = [];
+  });
+  return { store, task, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+const success: ArchiveProvider = {
+  archive: async () => ({ outcome: "succeeded", evidence_ref: "fixture:archive" }),
+  isArchived: async () => true,
+};
+
+test("archive persists unknown intent before provider call and closes without changing task state", async () => {
+  const f = fixture();
+  try {
+    const result = await retryConversationArchive(f.store, f.task.id, {
+      ...success,
+      archive: async () => {
+        expect(f.store.read().resources.find((r: any) => r.target === f.task.thread_id)?.status).toBe("archive_unknown");
+        return { outcome: "succeeded", evidence_ref: "fixture:archive" };
+      },
+    });
+    expect(result.status).toBe("closed");
+    expect(f.store.read().tasks.find((t: any) => t.id === f.task.id).state).toBe("completed");
+    let calls = 0;
+    await retryConversationArchive(f.store, f.task.id, { ...success, archive: async () => { calls++; return { outcome: "succeeded", evidence_ref: "duplicate" }; } });
+    expect(calls).toBe(0);
+  } finally { f.cleanup(); }
+});
+
+test("definite failure can retry; unknown result reconciles without sending twice", async () => {
+  const f = fixture();
+  try {
+    expect((await retryConversationArchive(f.store, f.task.id, { ...success, archive: async () => ({ outcome: "failed", evidence_ref: "fixture:failed", error: "rejected" }) })).status).toBe("archive_failed");
+    expect((await retryConversationArchive(f.store, f.task.id, { ...success, archive: async () => ({ outcome: "unknown", evidence_ref: "fixture:lost", error: "connection lost" }) })).status).toBe("archive_unknown");
+    let calls = 0;
+    const api: ArchiveProvider = { archive: async () => { calls++; return { outcome: "succeeded", evidence_ref: "unexpected" }; }, isArchived: async () => false };
+    expect((await retryConversationArchive(f.store, f.task.id, api)).status).toBe("archive_unknown");
+    expect(calls).toBe(0);
+    expect((await retryConversationArchive(f.store, f.task.id, { ...api, isArchived: async () => true })).status).toBe("closed");
+    expect(calls).toBe(0);
+  } finally { f.cleanup(); }
+});
+
+test("concurrent archive attempts cannot cross the provider boundary", async () => {
+  const f = fixture();
+  try {
+    let finish!: (value: Awaited<ReturnType<ArchiveProvider["archive"]>>) => void;
+    const first = retryConversationArchive(f.store, f.task.id, { ...success, archive: () => new Promise(resolve => { finish = resolve; }) });
+    await expect(retryConversationArchive(f.store, f.task.id, success)).rejects.toThrow("already in progress");
+    finish({ outcome: "succeeded", evidence_ref: "fixture:done" });
+    expect((await first).status).toBe("closed");
+  } finally { f.cleanup(); }
+});
+
+test("pending active turns can be retried after termination", async () => {
+  const f = fixture();
+  try {
+    let calls = 0;
+    const api: ArchiveProvider = { ...success, archive: async () => { calls++; return calls === 1 ? { outcome: "deferred", evidence_ref: "fixture:active" } : { outcome: "succeeded", evidence_ref: "fixture:idle" }; } };
+    expect((await retryConversationArchive(f.store, f.task.id, api)).status).toBe("pending");
+    await retryConversationArchive(f.store, f.task.id, api);
+    expect(calls).toBe(2);
+    expect(f.store.read().resources.find((r: any) => r.target === f.task.thread_id).status).toBe("closed");
+  } finally { f.cleanup(); }
+});
+
+test("unrelated in-flight operations do not block an eligible task", async () => {
+  const f = fixture();
+  try {
+    f.store.update(raw => { raw.operations.push({ id: "other", kind: "dispatch", actor_id: "other", target_id: "other-task", status: "unknown", request: {}, expected_sha: null, receipt_fact_id: null, created_at: new Date().toISOString(), updated_at: new Date().toISOString() } as any); });
+    expect((await retryConversationArchive(f.store, f.task.id, success)).status).toBe("closed");
+  } finally { f.cleanup(); }
+});
+
+test("active tasks cannot archive their conversation", async () => {
+  const f = fixture();
+  try {
+    f.store.update(raw => { raw.tasks.find((t: any) => t.id === f.task.id).state = "running"; });
+    await expect(retryConversationArchive(f.store, f.task.id, { ...success, archive: async () => { throw new Error("must not call"); } })).rejects.toMatchObject({ code: "TASK_NOT_TERMINAL" });
+  } finally { f.cleanup(); }
+});
+
+
+test("unarchive keeps the terminal task intact and manual restoration survives lifecycle sweeps", async () => {
+  const f = fixture();
+  try {
+    let calls = 0;
+    const api: ArchiveProvider = { ...success, unarchive: async () => { calls++; return { outcome: "succeeded", evidence_ref: "fixture:unarchive" }; }, isUnarchived: async () => true };
+    await retryConversationArchive(f.store, f.task.id, api);
+    const resource = await retryConversationUnarchive(f.store, f.task.id, api);
+    expect(resource.status).toBe("active");
+    expect(resource.archive_policy).toBe("manual");
+    await retryConversationUnarchive(f.store, f.task.id, api);
+    expect(calls).toBe(1);
+    await sweepConversationArchives(f.store, { ...api, archive: async () => { throw new Error("manual restore must not rearchive"); } });
+    expect(f.store.read().resources.find((r: any) => r.id === resource.id).status).toBe("active");
+    expect(f.store.read().tasks.find((t: any) => t.id === f.task.id).state).toBe("completed");
+  } finally { f.cleanup(); }
+});
+
+test("unarchive failure retries; unknown delivery requires positive reconciliation and blocks opposite archive", async () => {
+  const f = fixture();
+  try {
+    await retryConversationArchive(f.store, f.task.id, success);
+    const api: ArchiveProvider = { ...success, unarchive: async () => ({ outcome: "failed", evidence_ref: "fixture:rejected" }), isUnarchived: async () => false };
+    expect((await retryConversationUnarchive(f.store, f.task.id, api)).status).toBe("unarchive_failed");
+    expect((await retryConversationUnarchive(f.store, f.task.id, { ...api, unarchive: async () => ({ outcome: "unknown", evidence_ref: "fixture:lost" }) })).status).toBe("unarchive_unknown");
+    await expect(retryConversationArchive(f.store, f.task.id, api)).rejects.toMatchObject({ code: "ARCHIVE_STATE_CONFLICT" });
+    const noResend = { ...api, unarchive: async () => { throw new Error("must only reconcile"); } };
+    expect((await retryConversationUnarchive(f.store, f.task.id, noResend)).status).toBe("unarchive_unknown");
+    expect((await retryConversationUnarchive(f.store, f.task.id, { ...noResend, isUnarchived: async () => true })).status).toBe("active");
+  } finally { f.cleanup(); }
+});
+
+for (const claimed of [false, true]) {
+  test(`archive atomically rejects a notification that wins before intent (claimed=${claimed})`, async () => {
+    const f = fixture();
+    try {
+      const update = f.store.update.bind(f.store);
+      let injected = false, archiveCalls = 0;
+      f.store.update = ((callback: any) => {
+        if (!injected) {
+          injected = true;
+          update(raw => {
+            const sender = raw.tasks.find((task: any) => task.id === "deploy");
+            const actor = { role: "task", thread_id: sender.thread_id };
+            apply(raw, "task-update", { run_id: raw.orchestration_id, actor, request_id: "racing-notice", expected_revision: raw.revision, payload: { task_id: sender.id, state: "waiting", detail: "Notify before archive intent", notification: { mode: "deliver", recipient: { thread_id: f.task.thread_id } } } });
+            if (claimed) apply(raw, "notification-deliver", { run_id: raw.orchestration_id, actor, request_id: "racing-claim", expected_revision: raw.revision, payload: { notification_id: raw.notifications[0].id, delivery_attempt_id: "racing-attempt", outcome: "unknown", provider_receipt: { provider: "codex-app-server", evidence_ref: "fixture:in-flight" } } });
+          });
+        }
+        return update(callback);
+      }) as typeof f.store.update;
+      await expect(retryConversationArchive(f.store, f.task.id, { ...success, archive: async () => { archiveCalls++; return { outcome: "succeeded", evidence_ref: "must-not-archive" }; } })).rejects.toMatchObject({ code: "NOTIFICATIONS_PENDING" });
+      expect(archiveCalls).toBe(0);
+      const ledger = f.store.read();
+      expect(ledger.tasks.find((task: any) => task.id === f.task.id).state).toBe("completed");
+      expect(ledger.resources.find((resource: any) => resource.target === f.task.thread_id)?.status).not.toBe("archive_unknown");
+      expect(ledger.notifications[0].delivery_status).toBe(claimed ? "unknown" : "pending");
+    } finally { f.cleanup(); }
+  });
+}
+
+test("integrated tasks stay ineligible in the view and manual archive path", async () => {
+  const f = fixture();
+  try {
+    const { buildView } = await import("../lib/view");
+    f.store.update(raw => { raw.tasks.find((t: any) => t.id === f.task.id).state = "integrated"; });
+    expect(buildView(f.store.read()).tasks.find(t => t.id === f.task.id)?.conversation_archive.eligible).toBe(false);
+    await expect(retryConversationArchive(f.store, f.task.id, success)).rejects.toMatchObject({ code: "TASK_NOT_TERMINAL" });
+  } finally { f.cleanup(); }
+});
+
+test("eligible terminal task projects first archive without a conversation resource", async () => {
+  const f = fixture();
+  try {
+    const { buildView } = await import("../lib/view");
+    const task = buildView(f.store.read()).tasks.find(t => t.id === f.task.id)!;
+    expect(task.conversation_resource).toBeNull();
+    expect(task.conversation_archive).toEqual({ eligible: true, reason: null });
+  } finally { f.cleanup(); }
+});
+
+test("reconciliation and restoration survive lost archive eligibility", async () => {
+  const f = fixture();
+  try {
+    let sends = 0;
+    await retryConversationArchive(f.store, f.task.id, { ...success, archive: async () => ({ outcome: "unknown", evidence_ref: "fixture:lost" }) });
+    f.store.update(raw => { raw.tasks.find((t: any) => t.id === f.task.id).state = "running"; });
+    const api: ArchiveProvider = { ...success, archive: async () => { throw Error("must not resend"); }, unarchive: async () => { sends++; return { outcome: "succeeded", evidence_ref: "fixture:restored" }; }, isUnarchived: async () => true };
+    expect((await retryConversationArchive(f.store, f.task.id, api)).status).toBe("closed");
+    expect((await retryConversationUnarchive(f.store, f.task.id, api)).status).toBe("active");
+    expect(sends).toBe(1);
+    expect(f.store.read().tasks.find((t: any) => t.id === f.task.id).state).toBe("running");
+  } finally { f.cleanup(); }
+});

package/toolkit/skills/multi-task-flow/tests/conversation-output.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, test } from "bun:test";
+import { ConversationOutputs, messageOutput, type ConnectObserver } from "../lib/conversation-output";
+import type { JsonRecord } from "../lib/codex-agent-api";
+const tick = () => new Promise(resolve => setTimeout(resolve, 0));
+const message = (id: string, text: string, phase = "commentary") => ({ turnId: "turn", item: { type: "agentMessage", id, text, phase } });
+function fixture(read: (method: string, params: JsonRecord) => Promise<JsonRecord> = async () => ({ data: [] })) {
+  let notify!: (event: JsonRecord) => void;
+  let lost!: () => void;
+  let closed = 0;
+  let connections = 0;
+  const connect: ConnectObserver = async (n, c) => { notify = n; lost = c; connections++; return { request: (method, params) => method === "thread/read" ? read(method, params).then(value => ({ ...value, thread: { name: "真实对话标题", ...(value.thread as JsonRecord ?? {}) } })) : read(method, params), close: () => { closed++; c(); } }; };
+  const published: unknown[] = [];
+  const provider = new ConversationOutputs(s => published.push(s), connect, 20);
+  provider.bind([{ id: "a", thread_id: "thread" }, { id: "b", thread_id: "thread" }, { id: "none", thread_id: null }]);
+  provider.start();
+  return { provider, published, event: (method: string, params: JsonRecord) => notify({ method, params: { threadId: "thread", ...params } }), lost: () => lost(), get connections() { return connections; }, get closed() { return closed; } };
+}
+
+describe("conversation output projection", () => {
+  test("accepts public commentary/final text only", () => {
+    for (const phase of ["commentary", "final_answer"]) expect(messageOutput("thread", message("a", "hello", phase))?.text).toBe("hello");
+    for (const type of ["reasoning", "userMessage", "commandExecution", "system"]) expect(messageOutput("thread", { item: { id: "a", type, text: "private" } })).toBeNull();
+    expect(messageOutput("thread", message("a", " \n"))).toBeNull();
+  });
+  test("uses only the actual assistant item timestamp, never the observation time", () => {
+    const startedAtMs = Date.parse("2026-11-07T01:02:03Z");
+    expect(messageOutput("thread", { ...message("a", "hello"), startedAtMs })?.sent_at).toBe("2026-11-07T01:02:03.000Z");
+    expect(messageOutput("thread", message("a", "hello"))?.sent_at).toBeNull();
+    expect(messageOutput("thread", { ...message("a", "hello"), startedAtMs: Infinity })?.sent_at).toBeNull();
+  });
+  test("paginates past tools and whitespace, deduplicates bound threads", async () => {
+    const calls: JsonRecord[] = [];
+    const f = fixture(async (_m, params) => { if (_m === "thread/read") return {}; calls.push(params); return params.cursor ? { data: [message("latest", "progress"), message("older", "old")] } : { data: [message("blank", " "), { item: { type: "reasoning", text: "hidden" } }], nextCursor: "page2" }; });
+    try {
+      await tick();
+      expect(calls).toHaveLength(2);
+      expect(calls[0]).toMatchObject({ sortDirection: "desc", threadId: "thread" });
+      const s = f.provider.snapshot();
+      expect(s.outputs.a?.text).toBe("progress"); expect(s.outputs.b).toEqual(s.outputs.a);
+      expect(s.outputs.none?.state).toBe("no_conversation");
+    } finally { f.provider.stop(); }
+  });
+  test("history without a completion timestamp accepts later deltas for the same item", async () => {
+    for (const completion of [{}, { completedAtMs: null }]) {
+      const f = fixture(async () => ({ data: [{ ...message("live", "partial"), ...completion }] }));
+      try {
+        await tick();
+        expect(f.provider.snapshot().outputs.a?.message_status).toBe("in_progress");
+        f.event("item/agentMessage/delta", { turnId: "turn", itemId: "live", delta: " continued" });
+        expect(f.provider.snapshot().outputs.a?.text).toBe("partial continued");
+        expect(f.provider.receivedDelta).toBe(true);
+        f.event("item/completed", message("live", "complete", "final_answer"));
+        f.event("item/agentMessage/delta", { turnId: "turn", itemId: "live", delta: " late" });
+        expect(f.provider.snapshot().outputs.a).toMatchObject({ text: "complete", message_status: "completed" });
+      } finally { f.provider.stop(); }
+    }
+    expect(messageOutput("thread", { ...message("saved", "final"), completedAtMs: 0 })?.message_status).toBe("completed");
+  });
+  test("marks a confirmed completed turn as agent idle", async () => {
+    const f = fixture(async (method) => method === "thread/read" ? { thread: { status: { type: "idle" } } } : method === "thread/turns/list" ? { data: [{ id: "latest-turn", status: "completed", items: [] }] } : { data: [{ ...message("done", "finished"), completedAtMs: 1 }] });
+    try { await tick(); expect(f.provider.snapshot().outputs.a?.agent_state).toBe("idle");
+        expect(f.provider.snapshot().outputs.a?.runtime_turn_id).toBe("latest-turn");
+        expect(f.provider.snapshot().outputs.a?.observed_at).toBeTruthy(); } finally { f.provider.stop(); }
+  });
+  test("idle requires the latest terminated turn, independently of older public text", async () => {
+    for (const latest of [null, { id: "latest", status: "inProgress" }, { status: "completed" }, { id: "latest", status: "unknown" }, ...["completed", "failed", "interrupted"].map(status => ({ id: "latest", status }))]) {
+      const f = fixture(async method => method === "thread/read" ? { thread: { status: { type: "idle" } } } : method === "thread/turns/list" ? { data: latest ? [latest] : [] } : { data: [{ ...message("old", "older public text"), completedAtMs: 1 }] });
+      try {
+        await tick();
+        const output = f.provider.snapshot().outputs.a!;
+        const expected = latest?.id && ["completed", "failed", "interrupted"].includes(latest.status!) ? "idle" : latest?.id && ["inProgress", "started", "running"].includes(latest.status!) ? "active" : "unknown";
+        expect(output.agent_state).toBe(expected);
+        expect(output.runtime_turn_id).toBe(output.agent_state === "idle" || output.agent_state === "active" ? "latest" : null);
+        expect(output.turn_id).toBe("turn");
+      } finally { f.provider.stop(); }
+    }
+    const f = fixture();
+    try { await tick(); f.event("thread/status/changed", { status: { type: "idle" } }); expect(f.provider.snapshot().outputs.a?.agent_state).toBe("unknown"); } finally { f.provider.stop(); }
+  });
+  test("terminal turn events expose idle; obsolete turns and unknown runtime do not", async () => {
+    for (const status of ["completed", "interrupted", "failed"]) {
+      const f = fixture();
+      try {
+        await tick();
+        f.event("turn/started", { turn: { id: "new", status: "inProgress" } });
+        expect(f.provider.snapshot().outputs.a?.agent_state).toBe("active");
+        f.event("turn/completed", { turn: { id: "old", status } });
+        expect(f.provider.snapshot().outputs.a?.agent_state).toBe("active");
+        f.event("turn/completed", { turn: { id: "new", status } });
+        expect(f.provider.snapshot().outputs.a?.agent_state).toBe("idle");
+        f.event("thread/status/changed", { status: { type: "notLoaded" } });
+        expect(f.provider.snapshot().outputs.a?.agent_state).toBe("unknown");
+        f.lost();
+        expect(f.provider.snapshot().outputs.a?.stale).toBe(true);
+      } finally { f.provider.stop(); }
+    }
+  });
+  test("completed public messages do not prove an idle runtime", async () => {
+    for (const type of ["active", "notLoaded", "systemError"]) {
+      const f = fixture(async method => method === "thread/read" ? { thread: { status: { type } } } : { data: [{ ...message("done", "final"), completedAtMs: 1 }] });
+      try { await tick(); expect(f.provider.snapshot().outputs.a?.agent_state).toBe(type === "active" ? "active" : "unknown"); } finally { f.provider.stop(); }
+    }
+  });
+  test("confirms idle for an unloaded thread with a terminal latest turn", async () => {
+    const f = fixture(async method => method === "thread/read"
+      ? { thread: { status: { type: "notLoaded" } } }
+      : method === "thread/turns/list"
+        ? { data: [{ id: "latest-turn", status: "completed", items: [] }] }
+        : { data: [{ ...message("done", "final"), completedAtMs: 1 }] });
+    try {
+      await tick();
+      expect(f.provider.snapshot().outputs.a).toMatchObject({ agent_state: "idle", runtime_turn_id: "latest-turn" });
+    } finally { f.provider.stop(); }
+  });
+  test("confirms active for an unloaded thread with an in-progress latest turn", async () => {
+    const f = fixture(async method => method === "thread/read"
+      ? { thread: { status: { type: "notLoaded" } } }
+      : method === "thread/turns/list"
+        ? { data: [{ id: "active-turn", status: "inProgress", items: [] }] }
+        : { data: [{ ...message("old", "old final"), completedAtMs: 1 }] });
+    try {
+      await tick();
+      expect(f.provider.snapshot().outputs.a).toMatchObject({ agent_state: "active", runtime_turn_id: "active-turn" });
+    } finally { f.provider.stop(); }
+  });
+  test("does not let an unloaded history read overwrite a later active status", async () => {
+    const f = fixture(async method => method === "thread/read"
+      ? { thread: { status: { type: "notLoaded" } } }
+      : method === "thread/turns/list"
+        ? { data: [{ id: "old-turn", status: "completed", items: [] }] }
+        : { data: [{ ...message("done", "old final"), completedAtMs: 1 }] });
+    try {
+      await tick();
+      f.event("thread/status/changed", { status: { type: "active" } });
+      await tick();
+      expect(f.provider.snapshot().outputs.a).toMatchObject({ agent_state: "active", runtime_turn_id: null });
+    } finally { f.provider.stop(); }
+  });
+  test("full turn fallback happens only on an explicit unsupported-method error", async () => {
+    const calls: string[] = [];
+    const f = fixture(async (method, params) => { if (method === "thread/read") return {}; calls.push(method); if (method === "thread/items/list") throw new Error("method not found"); expect(params.itemsView).toBe("full"); return { data: [{ id: "turn", status: "completed", items: [message("old", "old").item, message("new", "final", "final_answer").item] }] }; });
+    try { await tick(); expect(calls).toEqual(["thread/items/list", "thread/turns/list"]); expect(f.provider.snapshot().outputs.a?.text).toBe("final"); } finally { f.provider.stop(); }
+  });
+  test("streamed text wins over in-flight history; completion replaces deltas and duplicates do not regress", async () => {
+    let resolve!: (r: JsonRecord) => void;
+    const f = fixture(() => new Promise(r => { resolve = r; }));
+    try {
+      await tick();
+      f.event("item/started", message("live", ""));
+      f.event("item/agentMessage/delta", { turnId: "turn", itemId: "live", delta: "working" });
+      resolve({ data: [message("old", "old final")] }); await tick();
+      expect(f.provider.snapshot().outputs.a).toMatchObject({ text: "working", phase: "commentary", message_status: "in_progress" });
+      f.event("item/completed", message("live", "complete", "final_answer"));
+      f.event("item/agentMessage/delta", { turnId: "turn", itemId: "live", delta: "duplicate late" });
+      f.event("item/started", message("next", "newer"));
+      f.event("item/completed", message("live", "complete", "final_answer"));
+      expect(f.provider.snapshot().outputs.a?.text).toBe("newer");
+      expect(f.provider.receivedDelta).toBe(true);
+    } finally { f.provider.stop(); }
+  });
+  test("rebinding immediately clears text and rejects old requests including remove/re-add", async () => {
+    const resolvers: Array<(r: JsonRecord) => void> = [];
+    const f = fixture(() => new Promise(r => resolvers.push(r)));
+    try {
+      await tick();
+      f.provider.bind([{ id: "a", thread_id: "replacement" }]);
+      expect(f.provider.snapshot().outputs.a).toMatchObject({ thread_id: "replacement", text: null });
+      f.provider.bind([{ id: "a", thread_id: "thread" }]);
+      resolvers[0]!({ data: [message("old-binding", "must not leak")] }); await tick();
+      expect(f.provider.snapshot().outputs.a?.text).toBeNull();
+    } finally { f.provider.stop(); resolvers.forEach(r => r({ data: [] })); }
+  });
+  test("history catch-up updates independently and idle reads do not churn revision", async () => {
+    let text = "progress";
+    const f = fixture(async () => ({ data: [message(text, text)] }));
+    try {
+      await tick(); const before = f.provider.snapshot().output_revision;
+      await new Promise(r => setTimeout(r, 25)); expect(f.provider.snapshot().output_revision).toBe(before);
+      text = "final"; await new Promise(r => setTimeout(r, 25));
+      expect(f.provider.snapshot().outputs.a?.text).toBe("final"); expect(f.provider.snapshot().output_revision).toBeGreaterThan(before);
+      expect(f.provider.receivedDelta).toBe(false);
+    } finally { f.provider.stop(); }
+  });
+  test("read failure retains successful content with an explicit unavailable marker", async () => {
+    let fail = false;
+    const f = fixture(async () => { if (fail) throw new Error("access denied"); return { data: [message("a", "saved")] }; });
+    try { await tick(); fail = true; await new Promise(r => setTimeout(r, 25)); expect(f.provider.snapshot().outputs.a).toMatchObject({ text: "saved", state: "unavailable", stale: true }); } finally { f.provider.stop(); }
+  });
+  test("empty conversation differs from read failure and stop closes the observer", async () => {
+    const f = fixture(); await tick();
+    expect(f.provider.snapshot().outputs.a?.state).toBe("empty");
+    f.lost(); expect(f.provider.snapshot().outputs.a?.state).toBe("unavailable");
+    f.provider.stop(); const count = f.connections; await tick(); expect(f.connections).toBe(count);
+  });
+  test("history cannot introduce an unseen older item after native completion", async () => {
+    let read = 0;
+    const f = fixture(async () => ({ data: read++ ? [message("unseen-old", "old persisted")] : [] }));
+    try {
+      await tick();
+      f.event("item/started", message("live", "partial"));
+      f.event("item/completed", message("live", "fresh completed", "final_answer"));
+      await new Promise(r => setTimeout(r, 25));
+      expect(f.provider.snapshot().outputs.a?.text).toBe("fresh completed");
+    } finally { f.provider.stop(); }
+  });
+  test("unbound thread notifications never enter the snapshot", async () => {
+    const f = fixture();
+    try { await tick(); f.event("item/completed", { ...message("a", "unrelated"), threadId: "unbound" }); expect(f.provider.snapshot().outputs.a?.state).toBe("empty"); } finally { f.provider.stop(); }
+  });
+});
+
+test("namespaced task and group bindings share one observer while preserving task aliases", async () => {
+  let metadataReads = 0, itemReads = 0;
+  const provider = new ConversationOutputs(() => {}, async () => ({ request: async method => { if (method === "thread/read") { metadataReads++; return { thread: { name: "真实主对话" } }; } itemReads++; return { data: [message("latest", "shared reply")] }; }, close() {} }), 10000);
+  provider.bind([{ id: "task:same", thread_id: "thread" }, { id: "group:same", thread_id: "thread" }]); provider.start();
+  try { await tick(); const outputs = provider.snapshot().outputs; expect(outputs["task:same"]).toEqual(outputs.same); expect(outputs["group:same"]?.text).toBe("shared reply"); expect(outputs["group:same"]?.thread_title).toBe("真实主对话"); expect(metadataReads).toBe(1); expect(itemReads).toBe(1); } finally { provider.stop(); }
+});
+
+test("pending title metadata never delays latest message catch-up", async () => {
+  let finish!: (value: JsonRecord) => void;
+  const provider = new ConversationOutputs(() => {}, async () => ({ request: async method => method === "thread/read" ? new Promise<JsonRecord>(resolve => { finish = resolve; }) : { data: [message("latest", "message without title")] }, close() {} }), 10000);
+  provider.bind([{ id: "a", thread_id: "thread" }]); provider.start();
+  try { await tick(); expect(provider.snapshot().outputs.a?.text).toBe("message without title"); provider.stop(); finish({ thread: { name: "late title" } }); await tick(); expect(provider.snapshot().outputs.a?.thread_title).toBeNull(); } finally { provider.stop(); }
+});

package/toolkit/skills/multi-task-flow/tests/crash-worker.ts

@@ -0,0 +1,9 @@
+import { LedgerStore } from "../lib/store";
+
+const requestedStage = process.argv[3];
+const ledgerPath = process.argv[2];
+if (!ledgerPath) throw new Error("ledger path is required");
+const store = new LedgerStore(ledgerPath, "test-run", (stage) => {
+  if (stage === requestedStage) process.kill(process.pid, "SIGKILL");
+});
+store.update((ledger) => { ledger.revision = 1; });

package/toolkit/skills/multi-task-flow/tests/demo-archive.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from "bun:test";
+import { archiveFixtureScript } from "../lib/demo-archive";
+
+test("static archive fixture creates a resource and restores it without changing task state", async () => {
+  const fixture = { revision: 1, view: { tasks: [{ id: "scheduler", thread_id: "demo-scheduler", state: "closed", conversation_resource: null }] } };
+  const target = {} as { fetch: typeof fetch; demoArchiveCalls: string[] };
+  new Function("window", "Response", archiveFixtureScript(JSON.stringify(fixture), "{}", "{}"))(target, Response);
+  const operate = async (action: string) => (await target.fetch("api/conversation-archive", {
+    method: "POST", body: JSON.stringify({ task_id: "scheduler", action }),
+  })).json();
+
+  expect(await operate("archive")).toMatchObject({ status: "closed", target: "demo-scheduler", error: null });
+  expect(await operate("unarchive")).toMatchObject({ status: "active", archive_policy: "manual" });
+  expect(await operate("archive")).toMatchObject({ status: "closed", archive_policy: "auto" });
+  const state = await (await target.fetch("api/view")).json();
+  expect(state.view.tasks[0].state).toBe("closed");
+  expect(state.revision).toBe(4);
+  expect(target.demoArchiveCalls).toEqual(["scheduler", "scheduler", "scheduler"]);
+});

package/toolkit/skills/multi-task-flow/tests/demo.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createDemoLedger, createPlanningDemoLedger } from "../examples/orchestration-viewer/ledger";
+import { startDashboard } from "../lib/server";
+import { LedgerStore } from "../lib/store";
+import { actualIntervals, buildView } from "../lib/view";
+import { conversationUrl } from "../web/links";
+
+describe("dashboard example", () => {
+  test("the planning preview does not fabricate execution facts", () => {
+    const ledger = createPlanningDemoLedger(Date.parse("2026-10-31T00:00:00.000Z"));
+    const view = buildView(ledger) as { execution_phase: string; planned_intervals: unknown[]; actual_intervals: unknown[] };
+    expect(view.execution_phase).toBe("planning");
+    expect(ledger.events.filter((event) => event.type === "task_started")).toHaveLength(0);
+    expect(ledger.tasks.every((task) => task.state === "planned" && task.started_at === null && task.finished_at === null)).toBe(true);
+    expect(view.planned_intervals.length).toBeGreaterThan(0);
+    expect(view.actual_intervals).toEqual([]);
+  });
+
+  test("uses distinct UUID-shaped Codex conversation addresses", () => {
+    const ledger = createDemoLedger();
+    const ids = [ledger.control.owner_thread_id, ...ledger.groups.map((group) => group.agent_thread_id), ...ledger.tasks.map((task) => task.thread_id)].filter((id): id is string => id !== null);
+    const verification = JSON.parse(readFileSync(join(import.meta.dir, "..", "examples", "orchestration-viewer", "link-verification.json"), "utf8")) as { results: { thread_id: string; navigated: boolean }[] };
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(verification.results).toHaveLength(ids.length);
+    expect(new Set(verification.results.filter((result) => result.navigated).map((result) => result.thread_id))).toEqual(new Set(ids));
+    for (const id of ids) {
+      const url = new URL(conversationUrl(id)!);
+      expect(url.protocol).toBe("codex:");
+      expect(url.hostname).toBe("threads");
+      expect(url.pathname).toMatch(/^\/[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+    }
+  });
+  test("uses same-document native conversation links like the working dashboard", () => {
+    expect(conversationUrl("01a18bf3-feb7-7d52-98b3-dc25f8549f69")).toBe("codex://threads/01a18bf3-feb7-7d52-98b3-dc25f8549f69");
+    expect(conversationUrl(" 01a18bf3-feb7-7d52-98b3-dc25f8549f69 ")).toBe("codex://threads/01a18bf3-feb7-7d52-98b3-dc25f8549f69");
+  });
+  test("does not build native URLs for synthetic conversation IDs", () => {
+    expect(conversationUrl("mock-thread-task-reader")).toBeNull();
+    expect(conversationUrl(" mock-thread-search-service ")).toBeNull();
+  });
+  test("keeps the cut history and post-merge work in the right groups", () => {
+    const ledger = createDemoLedger(Date.parse("2026-10-31T00:00:00.000Z"));
+    const view = buildView(ledger);
+    const intervals = actualIntervals(ledger).filter((interval) => interval.task_id === "dashboard-ui");
+    expect(intervals.map((interval) => interval.group_id)).toEqual(["core", "dashboard"]);
+    expect(intervals).toHaveLength(2);
+    expect(intervals[0]!.end).toBe(intervals[1]!.start);
+    expect(ledger.tasks.filter((task) => ["release", "deploy", "verify"].includes(task.id)).map((task) => task.group_id)).toEqual(["core", "core", "core"]);
+    expect(ledger.follow_prs).toHaveLength(1);
+    expect(ledger.follow_prs[0]!.origin_group_id).toBe("core");
+    expect((view.orchestration as { conversation_links_verified: boolean }).conversation_links_verified).toBe(true);
+    expect(ledger.events.find((event) => event.type === "link_verification")?.data.evidence_ref).toBe("examples/orchestration-viewer/link-verification.json");
+    expect(ledger.tasks.every((task) => task.atoms.length > 0)).toBe(true);
+  });
+
+  test("observed starts respect dependencies and the running limit", () => {
+    const reference = Date.parse("2026-10-31T00:00:00.000Z");
+    const ledger = createDemoLedger(reference);
+    const task = (id: string) => ledger.tasks.find((item) => item.id === id)!;
+    expect(Date.parse(task("scheduler").started_at!)).toBeGreaterThanOrEqual(Date.parse(task("model").finished_at!));
+    expect(Date.parse(task("scheduler").started_at!)).toBeGreaterThanOrEqual(Date.parse(task("ledger").finished_at!));
+    expect(Date.parse(task("release").started_at!)).toBeGreaterThanOrEqual(Date.parse(ledger.facts.find((fact) => fact.id === "parent-merged")!.observed_at));
+    expect(Date.parse(task("deploy").started_at!)).toBeGreaterThanOrEqual(Date.parse(task("release").finished_at!));
+    const changes = actualIntervals(ledger).filter((interval) => interval.state === "running").flatMap((interval) => [
+      { at: Date.parse(interval.start), delta: 1 },
+      { at: interval.end ? Date.parse(interval.end) : reference, delta: -1 },
+    ]).sort((a, b) => a.at - b.at || a.delta - b.delta);
+    let running = 0;
+    for (const change of changes) { running += change.delta; expect(running).toBeLessThanOrEqual(ledger.config.max_running_tasks); }
+    expect(running).toBe(0);
+  });
+
+  test("uses the approved Chinese-first display titles without changing machine identity", () => {
+    const ledger = createDemoLedger();
+    expect(ledger.tasks.map((task) => ({ id: task.id, kind: task.kind, title: task.title }))).toEqual([
+      { id: "model", kind: "contribution", title: "依赖模型与任务图" },
+      { id: "ledger", kind: "contribution", title: "账本持久化与并发控制" },
+      { id: "scheduler", kind: "contribution", title: "调度与 PR 合并协调" },
+      { id: "release", kind: "release", title: "核心能力版本发布" },
+      { id: "deploy", kind: "deployment", title: "运行环境部署与验证" },
+      { id: "verify", kind: "verification", title: "发布后核心能力验证" },
+      { id: "dashboard-ui", kind: "contribution", title: "依赖图与甘特图交互验证" },
+      { id: "server", kind: "contribution", title: "只读视图服务与实时更新" },
+      { id: "integration", kind: "contribution", title: "动态切割端到端验证" },
+      { id: "acceptance", kind: "verification", title: "页面验收与发布核对" },
+    ]);
+  });
+
+  test("serves the registered example requirements without exposing other files", async () => {
+    const root = mkdtempSync(join(realpathSync(tmpdir()), "orchestration-demo-docs-"));
+    const ledger = createDemoLedger(Date.parse("2026-10-31T00:00:00.000Z"));
+    const store = new LedgerStore(root, ledger.orchestration_id);
+    store.create(ledger);
+    cpSync(join(import.meta.dir, "..", "examples", "orchestration-viewer", "requirements"), join(store.runPath, "requirements"), { recursive: true });
+    const assetsDir = join(root, "assets"); mkdirSync(assetsDir);
+    const server = await startDashboard({ root, runId: ledger.orchestration_id, port: 0, assetsDir, demoFrame: true });
+    try {
+      const base = `http://127.0.0.1:${server.port}/s/${server.token}/`;
+      const view = await (await fetch(`${base}api/view`)).json() as { view: { tasks: { id: string }[] } };
+      expect(view.view.tasks).toHaveLength(ledger.tasks.length);
+      expect(view.view).not.toHaveProperty("is_demo");
+      for (const item of [...ledger.groups, ...ledger.tasks]) {
+        const type = ledger.groups.some((group) => group.id === item.id) ? "group" : "task";
+        const response = await fetch(`${base}api/document/${type}-${item.id}`);
+        expect(response.status).toBe(200);
+        expect(await response.text()).toContain(item.title);
+      }
+      expect((await fetch(`${base}api/document/task-unknown`)).status).toBe(404);
+    } finally { await server.stop(); rmSync(root, { recursive: true, force: true }); }
+  });
+});
+
+test("idle/archive example is synthetic and supports real archive reconciliation", async () => {
+  const { createIdleArchiveExample } = await import("../examples/orchestration-viewer");
+  const { retryConversationArchive } = await import("../lib/conversation-archive");
+  const example = createIdleArchiveExample();
+  expect(example.ledger.tasks.find(t => t.id === "dashboard-ui")?.state).toBe("agent_idle");
+  expect(example.ledger.tasks.every(t => !t.thread_id || t.thread_id.startsWith("example-thread-"))).toBe(true);
+  const connection = await example.dashboard.connectObserver(() => {}, () => {});
+  const thread = example.ledger.tasks.find(t => t.id === "dashboard-ui")!.thread_id;
+  expect(await connection.request("thread/read", {threadId: thread})).toMatchObject({thread: {status: {type: "idle"}}});
+  const root = mkdtempSync(join(realpathSync(tmpdir()), "idle-archive-example-test-"));
+  try {
+    const store = new LedgerStore(root, example.ledger.orchestration_id); store.create(example.ledger);
+    for (const taskId of ["model", "ledger"]) {
+      const state = store.read().tasks.find((t: any) => t.id === taskId).state;
+      expect((await retryConversationArchive(store, taskId, example.dashboard.archiveProvider)).status).toBe("closed");
+      expect(store.read().tasks.find((t: any) => t.id === taskId).state).toBe(state);
+    }
+  } finally { rmSync(root, {recursive: true, force: true}); }
+});

package/toolkit/skills/multi-task-flow/tests/desktop-output-state.test.ts

@@ -0,0 +1,20 @@
+import { expect, test } from "bun:test";
+import { DesktopOutputState } from "../lib/desktop-output-state";
+const agent=(id:string,text:string,completedAtMs:number|null=null)=>({type:"agentMessage",id,text,phase:"commentary",completedAtMs});
+const snapshot=(revision=1)=>({type:"snapshot",revision,conversationState:{turns:[],turnHistory:{history:{islands:[{entries:[{key:"old",value:"old"},{key:"new",value:"new"}]}],entitiesByKey:{new:{turnId:"t2",status:"inProgress",items:[{type:"reasoning",id:"secret",text:"hidden"},agent("a","partial")],completedItemIds:{}},old:{turnId:"t1",status:"completed",items:[agent("old","final",10)]}}}}}});
+const path=["turnHistory","history","entitiesByKey","new","items",1];
+test("follows platform island/item order, ignores private items, and applies contiguous streaming patches",()=>{
+ const state=new DesktopOutputState();expect(state.update(snapshot())).toMatchObject({turnId:"t2",item:{id:"a",text:"partial"},complete:false});
+ expect(state.update({type:"patches",baseRevision:1,revision:2,patches:[{op:"replace",path:[...path,"text"],value:"partial answer"}]})).toMatchObject({item:{text:"partial answer"},complete:false});
+ expect(state.update({type:"patches",baseRevision:2,revision:3,patches:[{op:"replace",path,value:agent("a","complete",20)}]})).toMatchObject({item:{text:"complete"},complete:true});
+ expect(state.update({type:"patches",baseRevision:1,revision:2,patches:[]})).toBeNull();
+ expect(()=>state.update({type:"patches",baseRevision:4,revision:5,patches:[]})).toThrow("gap");
+ expect(state.update(snapshot(6))).toMatchObject({item:{text:"partial"}});
+ expect(JSON.stringify(state)).not.toContain("hidden");
+});
+test("rejects unsafe paths and unsupported patches without exposing private updates",()=>{
+ const state=new DesktopOutputState();state.update(snapshot());
+ expect(()=>state.update({type:"patches",baseRevision:1,revision:2,patches:[{op:"replace",path:["__proto__","polluted"],value:true}]})).toThrow("path");
+ expect(state.update({type:"patches",baseRevision:1,revision:3,patches:[{op:"replace",path:[...path.slice(0,-1),0,"text"],value:"new secret"}]})).toMatchObject({item:{text:"partial"}});
+ expect(JSON.stringify(state)).not.toContain("new secret");
+});