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

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

@@ -0,0 +1,194 @@
+import { createServer } from "node:net";
+import { mkdtemp, mkdir, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, test } from "bun:test";
+import { PortRegistry } from "../../bin/modules/workspace/port_registry";
+import { createDemoLedger } from "../examples/orchestration-viewer/ledger";
+import { LedgerStore } from "../lib/store";
+
+async function freePort(): Promise<number> {
+  const listener = createServer();
+  await new Promise<void>((resolvePromise, reject) => {
+    listener.once("error", reject);
+    listener.listen(0, "127.0.0.1", () => resolvePromise());
+  });
+  const address = listener.address();
+  const port =
+    typeof address === "object" && address !== null ? address.port : 0;
+  await new Promise<void>((resolvePromise, reject) => {
+    listener.close((error) => (error ? reject(error) : resolvePromise()));
+  });
+  return port;
+}
+
+async function readLine(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let output = "";
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done)
+        throw new Error("serve.ts exited before announcing its URL");
+      output += decoder.decode(chunk.value, { stream: true });
+      const newline = output.indexOf("\n");
+      if (newline >= 0) return output.slice(0, newline);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+describe("multi-task dashboard service wrapper", () => {
+  test("records its pid/session and releases its lease on SIGTERM", async () => {
+    const root = await mkdtemp(
+      join(await realpath(tmpdir()), "multi-task-serve-"),
+    );
+    const dataRoot = join(root, "data");
+    const registryRoot = join(root, "registry");
+    const repoRoot = resolve(import.meta.dir, "../../..");
+    const run = createDemoLedger();
+    const runStore = new LedgerStore(dataRoot, run.orchestration_id);
+    const viewRoot = join(runStore.runPath, "view");
+    const port = await freePort();
+    let child: ReturnType<typeof Bun.spawn> | undefined;
+    let duplicate: ReturnType<typeof Bun.spawn> | undefined;
+    try {
+      runStore.create(run);
+      await mkdir(viewRoot, { recursive: true });
+      await writeFile(
+        join(viewRoot, "index.html"),
+        "<!doctype html><title>test</title>",
+      );
+      await writeFile(join(viewRoot, "app.js"), "");
+      await writeFile(join(viewRoot, "app.css"), "");
+
+      const registry = new PortRegistry(registryRoot);
+      await registry.register({
+        scopeId: "scope-test",
+        service: "dashboard",
+        port,
+        project: "test",
+        repoRoot,
+        branch: "test",
+        worktreePath: repoRoot,
+      });
+
+      child = Bun.spawn(
+        [
+          process.execPath,
+          join(import.meta.dir, "../scripts/serve.ts"),
+          "--run",
+          run.orchestration_id,
+          "--scope-id",
+          "scope-test",
+          "--service",
+          "dashboard",
+          "--port",
+          String(port),
+          "--agent-session",
+          "native-session-test",
+          "--custom-view",
+        ],
+        {
+          cwd: repoRoot,
+          env: {
+            ...process.env,
+            CODEX_HOME: repoRoot,
+            CODEX_PORT_REGISTRY_DIR: registryRoot,
+            TASK_ORCHESTRATION_DATA_ROOT: dataRoot,
+          },
+          stdout: "pipe",
+          stderr: "pipe",
+        },
+      );
+
+      const stdout = child.stdout;
+      if (stdout === undefined || typeof stdout === "number")
+        throw new Error("serve.ts stdout is not piped");
+      const announcement = JSON.parse(await readLine(stdout));
+      expect(announcement).toMatchObject({
+        ok: true,
+        port,
+        scope_id: "scope-test",
+        service: "dashboard",
+        agent_session_recorded: true,
+      });
+
+      const runningRows = await registry.readRows();
+      expect(runningRows).toHaveLength(1);
+      expect(runningRows[0]).toMatchObject({
+        scope_id: "scope-test",
+        service: "dashboard",
+        port: String(port),
+        agent_session: "native-session-test",
+        pid: String(child.pid),
+      });
+
+      duplicate = Bun.spawn(
+        [
+          process.execPath,
+          join(import.meta.dir, "../scripts/serve.ts"),
+          "--run",
+          run.orchestration_id,
+          "--scope-id",
+          "scope-test",
+          "--service",
+          "dashboard",
+          "--port",
+          String(port),
+          "--agent-session",
+          "native-session-test-duplicate",
+          "--custom-view",
+        ],
+        {
+          cwd: repoRoot,
+          env: {
+            ...process.env,
+            CODEX_HOME: repoRoot,
+            CODEX_PORT_REGISTRY_DIR: registryRoot,
+            TASK_ORCHESTRATION_DATA_ROOT: dataRoot,
+          },
+          stdout: "pipe",
+          stderr: "pipe",
+        },
+      );
+      const duplicateExit = await duplicate.exited;
+      const duplicateStderr = duplicate.stderr;
+      const duplicateOutput =
+        duplicateStderr === undefined || typeof duplicateStderr === "number"
+          ? ""
+          : await new Response(duplicateStderr).text();
+      duplicate = undefined;
+      expect(duplicateExit).toBe(5);
+      expect(duplicateOutput).toContain('"code":"LEASE_UNAVAILABLE"');
+      expect(await registry.readRows()).toEqual(runningRows);
+
+      process.kill(child.pid, "SIGTERM");
+      const stderr = child.stderr;
+      const exitCode = await child.exited;
+      child = undefined;
+      if (exitCode !== 0 && stderr !== undefined && typeof stderr !== "number")
+        throw new Error(
+          `serve.ts exited with ${exitCode}: ${await new Response(stderr).text()}`,
+        );
+      expect(exitCode).toBe(0);
+      expect(await registry.readRows()).toHaveLength(0);
+    } finally {
+      if (duplicate) {
+        try {
+          process.kill(duplicate.pid, "SIGKILL");
+        } catch {}
+        await duplicate.exited;
+      }
+      if (child) {
+        try {
+          process.kill(child.pid, "SIGKILL");
+        } catch {}
+        await child.exited;
+      }
+      await rm(root, { recursive: true, force: true });
+    }
+  }, 10_000);
+});

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

@@ -0,0 +1,166 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LedgerStore } from "../lib/store";
+import { apply } from "../lib/engine";
+import { validateLedger } from "../lib/schema";
+import { startDashboard } from "../lib/server";
+
+const paths: string[] = [];
+const at = "2026-01-01T00:00:00.000Z";
+const token = "0123456789abcdefghijklmnopqrstuv";
+afterEach(() => { for (const path of paths.splice(0)) rmSync(path, { recursive: true, force: true }); });
+
+function setup() {
+  const root = mkdtempSync(join(realpathSync(tmpdir()), "orchestration-server-")); paths.push(root);
+  const assets = join(root, "assets"); mkdirSync(assets);
+  writeFileSync(join(assets, "index.html"), "<h1>Demo</h1>");
+  const store = new LedgerStore(root, "run");
+  store.create({
+    schema_version: 2, source_schema_version: null, contract_version: 2, orchestration_id: "run", revision: 0,
+    repository: { provider: "github", host: "github.com", owner: "example", name: "repo", target_branch: "main" },
+    control: { owner_thread_id: "main-thread", ownership: "bound", approval_id: null },
+    config: { execution_profile: { model: "gpt-6.1-sol", thinking: "medium" }, max_running_tasks: 3, display_timezone: "Asia/Shanghai" },
+    plans: [{ lifecycle: "proposed", revision: null, id: "plan", supersedes_id: null, approval_id: null, created_at: at, start_at: null, atoms: [], atomic_edges: [], nodes: [], edges: [], cut_rules: [], actions: [] }],
+    active_plan_id: "plan", execution_plan_id: "plan", groups: [], tasks: [], follow_prs: [], facts: [], operations: [], events: [], milestones: [], requests: [], notifications: [], resources: [], updated_at: at,
+  });
+  return { root, assets, store };
+}
+
+describe("read-only dashboard server", () => {
+  test("requires a token and rejects writes and foreign origins", async () => {
+    const { root, assets } = setup();
+    const server = await startDashboard({ root, assetsDir: assets, runId: "run", port: 0, token });
+    const base = `http://127.0.0.1:${server.port}`;
+    try {
+      expect((await fetch(`${base}/s/wrong/api/view`)).status).toBe(404);
+      expect((await fetch(`${base}/s/${token}/api/view`, { method: "POST" })).status).toBe(405);
+      expect((await fetch(`${base}/s/${token}/api/view`, { headers: { origin: "https://example.invalid" } })).status).toBe(403);
+      const view = await fetch(`${base}/s/${token}/api/view`);
+      expect(view.status).toBe(200);
+      expect((await view.json() as any).revision).toBe(0);
+      expect((await (await fetch(`${base}/s/${token}/api/view`)).json() as any)).toMatchObject({ active_plan_id: "plan", execution_plan_id: "plan", view: { execution_phase: "planning" } });
+      expect((await fetch(`${base}/s/${token}/api/view?plan=bad%2Fplan`)).status).toBe(404);
+      const page = await fetch(`${base}/s/${token}/`);
+      expect(page.headers.get("content-security-policy")).toContain("default-src 'self'");
+      expect(page.headers.get("content-security-policy")).not.toContain("fonts.googleapis.com");
+      expect((await fetch(`${base}/s/${token}/api/document/task-a`)).status).toBe(404);
+    } finally { await server.stop(); }
+  });
+
+  test("pushes the new revision after an atomic ledger replacement", async () => {
+    const { root, assets, store } = setup();
+    const server = await startDashboard({ root, assetsDir: assets, runId: "run", port: 0, token });
+    try {
+      const response = await fetch(`http://127.0.0.1:${server.port}/s/${token}/api/events`);
+      const reader = response.body!.getReader();
+      const initial = await reader.read();
+      expect(new TextDecoder().decode(initial.value)).toContain('"revision":0');
+      store.update((ledger) => { ledger.revision = 1; });
+      let payload = "";
+      const waitForRevision = (async () => {
+        while (!payload.includes('"revision":1')) {
+          const changed = await reader.read();
+          if (changed.done) break;
+          payload += new TextDecoder().decode(changed.value);
+        }
+        return payload;
+      })();
+      await Promise.race([
+        waitForRevision,
+        new Promise<never>((_, reject) => setTimeout(() => reject(new Error("No revision notification")), 5_000)),
+      ]);
+      expect(payload).toContain('"revision":1');
+      await reader.cancel();
+    } finally { await server.stop(); }
+  });
+
+  test("serves tokenized theme preferences without changing the ledger", async () => {
+    const { root, assets, store } = setup();
+    const before = JSON.stringify(store.read());
+    const server = await startDashboard({ root, assetsDir: assets, runId: "run", port: 0, token });
+    const base = `http://127.0.0.1:${server.port}/s/${token}`;
+    try {
+      expect(await (await fetch(`${base}/api/preferences`)).json()).toEqual({ schema_version: 1, theme: "system" });
+      expect((await fetch(`${base}/api/preferences`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ theme: "dark" }) })).status).toBe(200);
+      expect(await (await fetch(`${base}/api/preferences`)).json()).toEqual({ schema_version: 1, theme: "dark" });
+      expect((await fetch(`${base}/api/preferences`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ theme: "blue" }) })).status).toBe(400);
+      expect((await fetch(`${base}/api/preferences`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ theme: "light", extra: true }) })).status).toBe(400);
+      expect((await fetch(`${base}/api/preferences`, { method: "POST", headers: { "content-type": "application/json" }, body: "x".repeat(1025) })).status).toBe(413);
+      expect((await fetch(`${base}/api/preferences`, { method: "POST", headers: { origin: "https://example.invalid", "content-type": "application/json" }, body: JSON.stringify({ theme: "light" }) })).status).toBe(403);
+      expect(JSON.stringify(store.read())).toBe(before);
+    } finally { await server.stop(); }
+  });
+  test("authenticated profile writes enforce capabilities, owner identity, revision and source read-only", async () => {
+    const { root, assets, store } = setup();
+    const capabilities = async () => [{ model: "gpt-6.1-sol", thinking: ["medium", "high"] }];
+    const server = await startDashboard({ root, assetsDir: assets, runId: "run", port: 0, token, getProfileCapabilities: capabilities });
+    const base = `http://127.0.0.1:${server.port}/s/${token}/api/execution-profile`;
+    const write = (changes: Record<string, unknown> = {}) => fetch(base, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ run_id: "run", actor: { role: "main", thread_id: "main-thread" }, request_id: "profile-request", expected_revision: 0, payload: { target_type: "run", execution_profile: { model: "gpt-6.1-sol", thinking: "high" } }, ...changes }) });
+    try {
+      expect((await (await fetch(base)).json() as any).capabilities).toEqual(await capabilities());
+      expect((await write({ payload: { target_type: "run", execution_profile: { model: "invalid", thinking: "high" } } })).status).toBe(400);
+      expect((await write({ actor: { role: "main", thread_id: "stranger" } })).status).toBe(403);
+      expect((await write({ run_id: "another-run" })).status).toBe(400);
+      expect((await write()).status).toBe(200);
+      expect(store.read().config.execution_profile).toEqual({ model: "gpt-6.1-sol", thinking: "high" });
+      expect((await write({ request_id: "stale-profile" })).status).toBe(409);
+    } finally { await server.stop(); }
+    const source = await startDashboard({ root, assetsDir: assets, runId: "run", port: 0, token, readOnly: true, getProfileCapabilities: capabilities });
+    try {
+      const response = await fetch(`http://127.0.0.1:${source.port}/s/${token}/api/execution-profile`, { method: "POST", body: "{}" });
+      expect(response.status).toBe(403);
+    } finally { await source.stop(); }
+  });
+
+});
+
+
+test("authenticated loopback edits replace claims, emit revisions and freeze on native identity", async () => {
+  const { root, assets, store } = setup();
+  store.update((raw) => {
+    raw.groups = [{ id: "g", title: "Group", agent_thread_id: "group-thread", state: "active", parent_branch: null, parent_pr: null, cut_sha: null, current_sha: null, merge_sha: null, requirements_path: null }];
+    raw.tasks = ["a", "b"].map((id) => ({ id, title: id, kind: "coordination", group_id: "g", thread_id: null, state: "planned", atoms: [{ id: `atom-${id}`, title: id, status: "planned" }], owned_surfaces: [], base_sha: null, pr: null, requirements_path: null, execution_owner: "main", conversation_policy: "main_owned", delivery_policy: "evidence", started_at: null, finished_at: null, blocker: null, assignment_history: [] }));
+    raw.plans[0].atoms = ["a", "b"].map((id) => ({ id: `atom-${id}`, title: id, task_id: id, purpose: "fixture task", output: "fixture output" }));
+    raw.plans[0].nodes = ["a", "b"].map((id) => ({ id: `node-${id}`, kind: "task", ref_id: id, group_id: "g", label: id, estimate_minutes: 30, estimate_basis: "fixture estimate", estimate_confidence: "medium" }));
+  });
+  const mutate = (command: string, payload: Record<string, unknown>) => store.update((raw) => apply(raw, command, { run_id: "run", actor: { role: "main", thread_id: "main-thread" }, request_id: crypto.randomUUID(), expected_revision: raw.revision, payload }));
+  mutate("plan-approve", { plan_id: "plan", approval_id: "approved", authorized_actions: ["dispatch"], authorized_action_ids: [] });
+  mutate("dispatch-claim", { task_id: "a", operation_id: "old-claim" });
+  const server = await startDashboard({ root, assetsDir: assets, runId: "run", port: 0, token, getProfileCapabilities: async () => [{ model: "gpt-6.1-sol", thinking: ["medium", "high"] }] });
+  const base = `http://127.0.0.1:${server.port}/s/${token}`;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  try {
+    reader = (await fetch(`${base}/api/events`)).body!.getReader();
+    await reader.read();
+    const update = () => fetch(`${base}/api/execution-profile`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ run_id: "run", actor: { role: "main", thread_id: "main-thread" }, request_id: crypto.randomUUID(), expected_revision: store.read().revision, payload: { target_type: "task", target_id: "a", execution_profile: { model: "gpt-6.1-sol", thinking: "high" } } }) });
+    expect((await update()).status).toBe(200);
+    const changed = validateLedger(store.read());
+    expect(changed.operations.find((op) => op.id === "old-claim")?.status).toBe("failed");
+    expect(changed.events.some((event) => event.type === "dispatch_claim_replaced")).toBe(true);
+    const streamRevision = await Promise.race([reader.read(), new Promise<never>((_, reject) => setTimeout(() => reject(new Error("SSE revision missing")), 2000))]);
+    expect(new TextDecoder().decode(streamRevision.value)).toContain('event: revision');
+    mutate("dispatch-claim", { task_id: "a", operation_id: "new-claim" });
+    mutate("dispatch-bind-request", { operation_id: "new-claim", native_request_id: "native-loopback" });
+    expect((await update()).status).toBe(409);
+    const view = await (await fetch(`${base}/api/view`)).json() as any;
+    expect(view.view.tasks.find((task: any) => task.id === "a").profile_freeze_reason).toContain("须先对账");
+    expect(view.view.tasks.find((task: any) => task.id === "b").effective_execution_profile).toEqual({ model: "gpt-6.1-sol", thinking: "medium" });
+  } finally { await reader?.cancel(); await server.stop(); }
+});
+
+test("resource details inherit dashboard authorization and reject unbound targets", async () => {
+  const { root, assets, store } = setup();
+  const before = JSON.stringify(store.read());
+  const server = await startDashboard({ root, assetsDir: assets, runId: "run", port: 0, token });
+  const base = `http://127.0.0.1:${server.port}`;
+  try {
+    expect((await fetch(`${base}/s/invalid/api/resource-details?kind=task&id=other`)).status).toBe(404);
+    expect((await fetch(`${base}/s/${token}/api/resource-details?kind=task&id=other`)).status).toBe(404);
+    expect((await fetch(`${base}/s/${token}/api/resource-details?kind=task&id=other&url=https://evil.test`)).status).toBe(400);
+    expect((await fetch(`${base}/s/${token}/api/resource-details?kind=group&id=other`, { method: "POST" })).status).toBe(405);
+    expect((await fetch(`${base}/s/${token}/api/resource-details?kind=task&id=other`, { headers: { origin: "https://evil.test" } })).status).toBe(403);
+    expect(JSON.stringify(store.read())).toBe(before);
+  } finally { await server.stop(); }
+});

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

@@ -0,0 +1,208 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { servicePaths, orchestrationRoot } from "../lib/service-paths";
+import { requireApi, requireLedgerCompatibility } from "../lib/service-contract";
+import { ServiceState } from "../lib/service-state";
+import { serviceCommand } from "../scripts/service";
+
+const roots: string[] = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+function fixture() {
+  const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "mtf-contract-")));
+  roots.push(root);
+  return new ServiceState(servicePaths({ MULTI_TASK_FLOW_PROFILE: "test", MULTI_TASK_FLOW_ROOT: root }));
+}
+test("production root and identity are independent of CODEX_HOME", () => {
+  expect(servicePaths({ CODEX_HOME: "/one" })).toEqual(servicePaths({ CODEX_HOME: "/two" }));
+  expect(orchestrationRoot({})).toEndWith("/.local/share/multi-task-flow/data");
+  expect(() => servicePaths({ MULTI_TASK_FLOW_ROOT: "/test" })).toThrow();
+  expect(() => servicePaths({ MULTI_TASK_FLOW_PROFILE: "test" })).toThrow();
+});
+test("test instances have separate roots and service identities", () => {
+  const a = fixture(), b = fixture();
+  expect(a.paths.label).not.toBe(b.paths.label);
+  expect(a.paths.scope).not.toBe(servicePaths({}).scope);
+});
+test("compatibility rejects future data instead of migrating it", () => {
+  requireLedgerCompatibility({ schema_version: 1 });
+  requireLedgerCompatibility({ schema_version: 1, contract_version: 1 });
+  requireLedgerCompatibility({ schema_version: 2, contract_version: 2 }, "write");
+  expect(() => requireLedgerCompatibility({ schema_version: 2, contract_version: 1 }, "write")).toThrow("explicit migration");
+  expect(() => requireLedgerCompatibility({ schema_version: 1 }, "write")).toThrow();
+  expect(() => requireLedgerCompatibility({ schema_version: 2 })).toThrow("explicit migration");
+  expect(() => requireLedgerCompatibility({ schema_version: 1, contract_version: 2 }, "write")).toThrow();
+  expect(() => requireApi(2)).toThrow("explicit maintenance");
+});
+test("schema2 contract2 ledgers without task policy fields are read-only", () => {
+  requireLedgerCompatibility({ schema_version: 2, contract_version: 2, tasks: [] }, "write");
+  expect(() => requireLedgerCompatibility({ schema_version: 2, contract_version: 2, tasks: [{ id: "legacy" }] }, "write")).toThrow("read-only");
+  requireLedgerCompatibility({ schema_version: 2, contract_version: 2, tasks: [{ execution_owner: null, conversation_policy: null, delivery_policy: null }] }, "write");
+});
+test("schema2 contract2 ledgers with incomplete declared task policies stay read-only", () => {
+  let error: any;
+  try {
+    requireLedgerCompatibility({
+      schema_version: 2,
+      contract_version: 2,
+      tasks: [{ execution_owner: "main", conversation_policy: null, delivery_policy: null }],
+    }, "write");
+  } catch (caught) {
+    error = caught;
+  }
+  expect(error).toMatchObject({ code: "TASK_EXECUTION_POLICY_INCOMPLETE" });
+});
+test("leases are idempotent and preserve independent owners and deadlines", () => {
+  const state = fixture();
+  const agent = { id: "agent:thread:run", kind: "agent" as const, thread_id: "thread", run_id: "run" };
+  state.renew(agent, 3_600_000, 10);
+  state.renew(agent, 3_600_000, 20);
+  state.renewBrowser("session", 30);
+  expect(state.runtime().leases).toHaveLength(2);
+  expect(state.runtime().leases[0]!.expires_at).toBe(3_600_020);
+  const reopened = new ServiceState(state.paths);
+  expect(reopened.runtime()).toEqual(state.runtime());
+  state.release(agent.id);
+  expect(state.runtime().leases[0]!.kind).toBe("browser");
+});
+test("expiry fences generations and refuses renewals during exit", () => {
+  const state = fixture();
+  state.transaction(runtime => { runtime.phase = "running"; runtime.pid = process.pid; runtime.generation = "current"; });
+  state.renewBrowser("session", 0);
+  expect(state.expire("current", 299_999)).toBe(false);
+  expect(state.expire("current", 300_000)).toBe(true);
+  expect(() => state.renewBrowser("next")).toThrow("stopping");
+  expect(() => state.expire("old")).toThrow("replaced");
+  state.stopped("old");
+  expect(state.runtime().phase).toBe("stopping");
+  state.stopped("current");
+  expect(state.runtime().phase).toBe("stopped");
+});
+
+
+test("schema2/contract2 ledgers without idle or archive diagnostics remain readable", async () => {
+  const { createDemoLedger } = await import("../examples/orchestration-viewer/ledger");
+  const { validateLedger } = await import("../lib/schema");
+  const ledger = JSON.parse(JSON.stringify(createDemoLedger()));
+  ledger.contract_version = 2;
+  for (const task of ledger.tasks) delete task.agent_resume_state;
+  for (const resource of ledger.resources) for (const key of ["archive_policy", "error", "last_attempt_at", "operation_id"]) delete resource[key];
+  expect(validateLedger(ledger).schema_version).toBe(2);
+  expect(validateLedger(ledger).contract_version).toBe(2);
+  expect(() => requireLedgerCompatibility(ledger)).not.toThrow();
+});
+
+test("viewer reader commands validate and render without a mutation boundary", async () => {
+  const { createDemoLedger } = await import("../examples/orchestration-viewer/ledger");
+  const ledger = createDemoLedger();
+  const checked = await serviceCommand("reader-check", { ledger });
+  expect(checked).toMatchObject({ contract: "schema-2/contract-1", revision: ledger.revision });
+  const rendered = await serviceCommand("read-only-view", { ledger });
+  expect(rendered).toHaveProperty("view");
+});
+
+test("viewer labels use the Loomhelm namespace and maintenance retires the matching legacy profile", async () => {
+  const { unloadUserService } = await import("../lib/service-launchd");
+  expect(servicePaths({}).label).toBe("cc.ivanli.loomhelm.multi-task-flow.viewer");
+  const state = fixture();
+  expect(state.paths.label).toStartWith("cc.ivanli.loomhelm.multi-task-flow.viewer.");
+  const calls: string[][] = [];
+  const legacy = state.paths.label.replace("cc.ivanli.loomhelm.multi-task-flow.viewer", "cn.ivan.multi-task-flow.viewer");
+  unloadUserService(state, (args) => { calls.push(args); return true; }, "gui/123");
+  expect(calls).toEqual([
+    ["print", `gui/123/${state.paths.label}`],
+    ["bootout", `gui/123/${state.paths.label}`],
+    ["print", `gui/123/${legacy}`],
+    ["bootout", `gui/123/${legacy}`],
+  ]);
+  calls.length = 0;
+  unloadUserService(state, (args) => { calls.push(args); return false; }, "gui/123");
+  expect(calls.every(args => args[0] === "print")).toBe(true);
+});
+
+test("ordinary startup rejects the legacy plist before calling launchctl", async () => {
+  const { writeFileSync, mkdirSync } = await import("node:fs");
+  const { startUserService } = await import("../lib/service-launchd");
+  const state = fixture();
+  mkdirSync(state.paths.config, { recursive: true });
+  writeFileSync(join(state.paths.config, "viewer.plist"), '<key>Label</key><string>cn.ivan.multi-task-flow.viewer</string>');
+  expect(() => startUserService(state)).toThrow("explicit upgrade");
+});
+
+test("readiness tolerates delayed health but stops at a finite elapsed-time budget", async () => {
+  const { waitForServiceHealth } = await import("../lib/service-lifecycle");
+  const started = performance.now();
+  expect(await waitForServiceHealth(async () => {
+    if (performance.now() - started < 20) throw new Error("still starting");
+    return "healthy";
+  }, 500)).toBe("healthy");
+  const failure = new Error("unhealthy");
+  const deadlineStarted = performance.now();
+  await expect(waitForServiceHealth(async () => { throw failure; }, 25)).rejects.toBe(failure);
+  expect(performance.now() - deadlineStarted).toBeLessThan(500);
+  await expect(waitForServiceHealth(async () => "healthy", Infinity)).rejects.toThrow("finite");
+});
+
+test.skipIf(process.platform !== "darwin" || process.env.GITHUB_ACTIONS !== "true" || !process.env.LOOMHELM_VIEWER_LABEL_BEFORE || !process.env.LOOMHELM_VIEWER_LABEL_AFTER)("native launchd label transition preserves port and retires legacy registration", async () => {
+  const { installRelease, switchRelease, nativeServiceControl } = await import("../lib/service-maintenance");
+  const { writeLaunchdDefinition, startUserService, unloadUserService, launchdDomain, launchctl } = await import("../lib/service-launchd");
+  const { serviceStatus, waitForServiceHealth } = await import("../lib/service-lifecycle");
+  const { processAlive } = await import("../../bin/modules/workspace/port_registry");
+  const state = fixture();
+  // Cleanup must wait for the actual launchd child, not just test completion.
+  roots.splice(roots.indexOf(state.paths.root), 1);
+  const legacyLabel = state.paths.label.replace("cc.ivanli.loomhelm.multi-task-flow.viewer", "cn.ivan.multi-task-flow.viewer");
+  const legacyState = new ServiceState({ ...state.paths, label: legacyLabel });
+  const domain = launchdDomain();
+  const stderr = join(state.paths.logs, "native-startup-stderr.log");
+  const startWithDiagnostics = (instance: ServiceState) => {
+    const plist = join(instance.paths.config, "viewer.plist");
+    writeFileSync(plist, readFileSync(plist, "utf8").replace(
+      "<key>StandardErrorPath</key><string>/dev/null</string>",
+      `<key>StandardErrorPath</key><string>${stderr}</string>`,
+    ));
+    startUserService(instance);
+  };
+  try {
+    const installed = await installRelease(state, process.env.LOOMHELM_VIEWER_LABEL_BEFORE!);
+    state.renew({ id: "native-label", kind: "agent", run_id: null, thread_id: null }, 180_000);
+    // Reproduce the legacy registration independently of program build identity.
+    writeLaunchdDefinition(legacyState);
+    startWithDiagnostics(legacyState);
+    await waitForServiceHealth(() => serviceStatus(state));
+    const previousPid = state.runtime().pid;
+    expect(launchctl(["print", `${domain}/${legacyLabel}`], true)).toBe(true);
+    await switchRelease(state, process.env.LOOMHELM_VIEWER_LABEL_AFTER!, false, {
+      ...nativeServiceControl,
+      start: startWithDiagnostics,
+    });
+    await serviceStatus(state);
+    expect(state.config().port).toBe(installed.port);
+    expect(state.config().current_build).not.toBe(installed.build_id);
+    expect(state.runtime().pid).not.toBe(previousPid);
+    expect(launchctl(["print", `${domain}/${legacyLabel}`], true)).toBe(false);
+    expect(launchctl(["print", `${domain}/${state.paths.label}`], true)).toBe(true);
+  } catch (error) {
+    // Only this disposable CI instance is inspected; never print credentials or environment.
+    const runtime = state.runtime();
+    console.error("native label diagnostics", JSON.stringify({ phase: runtime.phase, pid: runtime.pid }));
+    for (const label of [legacyLabel, state.paths.label]) {
+      const result = Bun.spawnSync(["/bin/launchctl", "print", `${domain}/${label}`]);
+      const text = result.stdout.toString();
+      console.error("native launchd diagnostics", label, text.split("\n").filter(line => /^\s*(state|pid|runs|last exit code|last terminating signal) =/.test(line)).join("\n"));
+      const pid = text.match(/^\s*pid = (\d+)$/m)?.[1];
+      if (pid) console.error("native process diagnostics", Bun.spawnSync(["/bin/ps", "-p", pid, "-o", "pid=,ppid=,etime=,comm="]).stdout.toString());
+    }
+    for (const path of [stderr, join(state.paths.state, "startup-failure.json"), join(state.paths.logs, "viewer.jsonl")]) {
+      if (existsSync(path)) console.error(path, readFileSync(path, "utf8").slice(-8000));
+    }
+    throw error;
+  } finally {
+    const pid = state.runtime().pid;
+    unloadUserService(state);
+    for (let attempt = 0; pid && processAlive(pid) && attempt < 200; attempt++) await Bun.sleep(100);
+    if (pid && processAlive(pid)) throw new Error(`Isolated viewer did not stop; retained ${state.paths.root}`);
+    rmSync(state.paths.root, { recursive: true, force: true });
+  }
+}, 360_000);

package/toolkit/skills/multi-task-flow/tests/service-fixture.ts

@@ -0,0 +1,81 @@
+import { mkdtempSync, realpathSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { servicePaths } from "../lib/service-paths";
+import { ServiceAuth } from "../lib/service-auth";
+import { ServiceState } from "../lib/service-state";
+import { compatibility } from "../lib/service-contract";
+import { versionEnvelope } from "../lib/contract";
+import { buildId, digest, releaseFiles } from "../lib/service-release";
+import { LedgerStore } from "../lib/store";
+import { createDemoLedger } from "../examples/orchestration-viewer/ledger";
+import type { View } from "../web/model";
+
+export function serviceFixture(profile: "test" | "production" = "test") {
+  const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "mtf-service-")));
+  const state = new ServiceState(servicePaths({ MULTI_TASK_FLOW_PROFILE: profile, MULTI_TASK_FLOW_ROOT: root }));
+  state.initialize(); new ServiceAuth(state).initialize();
+  return { root, state };
+}
+export function fixtureRelease(root: string, name = "bundle", options: { readOnly?: boolean } = {}) {
+  const source = join(root, name); mkdirSync(join(source, "dist"), { recursive: true });
+  const viewer = `#!/usr/bin/env bun\nconst input = await new Response(Bun.stdin.stream()).json();\nconst ledger = input.ledger;\nif (Bun.argv[2] === "read-only-view") ${options.readOnly ? 'console.log(JSON.stringify({ok:true,code:"OK",result:{view:{orchestration:{id:ledger.orchestration_id,revision:ledger.revision}}}}));' : 'process.exit(2);'}\nelse console.log(JSON.stringify({ok:true,code:"OK",result:{contract:\`schema-2/contract-\${ledger.contract_version === 2 ? 2 : 1}\`,revision:ledger.revision}}));\n`;
+  for (const file of releaseFiles) { mkdirSync(dirname(join(source,file)),{recursive:true}); writeFileSync(join(source, file), file === "viewer" ? viewer : file === "skills/multi-task-flow/dist/index.html" ? "<!doctype html><html><body><h1>Run</h1></body></html>" : "// " + file + name); }
+  chmodSync(join(source, "viewer"), 0o700);
+  const manifest = { schema_version: 2 as const, source_sha: "a".repeat(40), service_version: "0.0.0-test", platform: `${process.platform}-${process.arch}` as "darwin-arm64" | "darwin-x64" | "linux-arm64" | "linux-x64", ...versionEnvelope, ...compatibility, files: Object.fromEntries(releaseFiles.map(file => [file, digest(file === "viewer" ? viewer : file === "skills/multi-task-flow/dist/index.html" ? "<!doctype html><html><body><h1>Run</h1></body></html>" : "// " + file + name)])) };
+  const result = { ...manifest, build_id: buildId(manifest) };
+  writeFileSync(join(source, "manifest.json"), JSON.stringify(result));
+  return { source, manifest: result };
+}
+export function fixtureRun(root: string, id = "demo-run") {
+  const run = createDemoLedger(); run.orchestration_id = id;
+  run.schema_version = 2;
+  run.source_schema_version = null;
+  run.contract_version = 2;
+  const store = new LedgerStore(root, id); store.create(run);
+  return { run, store };
+}
+
+export function fixtureLegacyRelease(root: string) {
+  const source = join(root, "legacy-bundle");
+  const names = ["viewer", "dist/index.html", "dist/app.js", "dist/app.css"];
+  for (const file of names) { mkdirSync(dirname(join(source,file)), {recursive:true}); writeFileSync(join(source,file), file); }
+  const body = {schema_version:1 as const, source_sha:"a".repeat(40), service_version:"0.0.0-test", platform:`${process.platform}-${process.arch}` as "darwin-arm64" | "linux-x64", ...compatibility, files:Object.fromEntries(names.map(file => [file,digest(file)]))};
+  const manifest = {...body,build_id:buildId(body)};
+  writeFileSync(join(source,"manifest.json"),JSON.stringify(manifest));
+  return {source,manifest};
+}
+
+export function emptyBootstrapView(): View {
+  const groups: View["groups"] = [
+    { id: "bootstrap", title: "版本化 Skill 发布合同", delivery_unit_kind: "bootstrap", owner_kind: "main", agent_thread_id: null, state: "active", parent_pr: null, requirements_path: null },
+    { id: "regular", title: "后续交付", delivery_unit_kind: "regular", owner_kind: "group", agent_thread_id: null, state: "active", parent_pr: null, requirements_path: null },
+  ];
+  const tasks: View["tasks"] = [{
+    id: "later-task", title: "后续实现任务", kind: "contribution", group_id: "regular", thread_id: null, state: "planned", is_ready: false,
+    pr: null, requirements_path: null, started_at: null, finished_at: null, blocker: null,
+  }];
+  const nodes: View["nodes"] = [
+    { id: "main-start", kind: "main_start", ref_id: null, group_id: null, planned_group_id: null, label: "主任务开始" },
+    { id: "bootstrap-start", kind: "group_start", ref_id: "bootstrap", group_id: "bootstrap", planned_group_id: "bootstrap", label: "bootstrap 开始" },
+    { id: "bootstrap-end", kind: "group_end", ref_id: "bootstrap", group_id: "bootstrap", planned_group_id: "bootstrap", label: "bootstrap 收口" },
+    { id: "regular-start", kind: "group_start", ref_id: "regular", group_id: "regular", planned_group_id: "regular", label: "regular 开始" },
+    { id: "later-task-node", kind: "task", ref_id: "later-task", group_id: "regular", planned_group_id: "regular", label: "后续实现任务" },
+    { id: "regular-end", kind: "group_end", ref_id: "regular", group_id: "regular", planned_group_id: "regular", label: "regular 收口" },
+    { id: "main-end", kind: "main_end", ref_id: null, group_id: null, planned_group_id: null, label: "主任务完成" },
+  ];
+  const edge = (id: string, from_node_id: string, to_node_id: string, requires: string): View["edges"][number] => ({ id, from_node_id, to_node_id, requires });
+  return {
+    orchestration: { id: "empty-bootstrap-run", repository: { owner: "example", name: "loomhelm", host: "github.com" }, revision: 1, updated_at: "2026-01-01T00:00:00.000Z", display_timezone: "UTC", max_running_tasks: 1, conversation_links_verified: true },
+    groups, tasks, plans: [], selected_plan_id: "", follow_prs: [], nodes,
+    edges: [
+      edge("main-to-bootstrap", "main-start", "bootstrap-start", "completed"),
+      edge("bootstrap-through", "bootstrap-start", "bootstrap-end", "completed"),
+      edge("bootstrap-to-regular", "bootstrap-end", "regular-start", "merged"),
+      edge("regular-to-task", "regular-start", "later-task-node", "completed"),
+      edge("task-to-regular-end", "later-task-node", "regular-end", "completed"),
+      edge("regular-to-main-end", "regular-end", "main-end", "completed"),
+    ],
+    planned_intervals: [], actual_intervals: [], actual_milestones: [], warnings: [],
+  };
+}