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

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

@@ -0,0 +1,123 @@
+import { afterEach, expect, spyOn, test } from "bun:test";
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { PortRegistry, RegistryError } from "../../bin/modules/workspace/port_registry";
+import { runDaemon } from "../lib/service-lifecycle";
+import { serviceFixture, fixtureRelease } from "./service-fixture";
+
+const restores: Array<() => void> = [];
+afterEach(() => { for (const restore of restores.splice(0).reverse()) restore(); });
+async function fixture() {
+  const { root, state } = serviceFixture();
+  restores.push(() => rmSync(root, { recursive: true, force: true }));
+  const probe = Bun.serve({hostname: "127.0.0.1", port: 0, fetch: () => new Response()});
+  const port = probe.port!; await probe.stop(true);
+  const release = fixtureRelease(root);
+  state.saveConfig({schema_version: 1, port, registry_dir: join(root, "registry"), current_build: release.manifest.build_id, previous_build: null, agent_ttl_ms: 60000});
+  state.renew({id: "agent:fixture", kind: "agent", run_id: "fixture", thread_id: "fixture"}, 60000);
+  const ticks = new Map<number, () => unknown>();
+  const original = globalThis.setInterval;
+  const timers = spyOn(globalThis, "setInterval").mockImplementation(((fn: () => unknown, ms: number) => {
+    if (ms === 1000 || ms === 30000) { ticks.set(ms, fn); return original(() => {}, 1e9); }
+    return original(fn, ms);
+  }) as typeof setInterval);
+  restores.push(() => timers.mockRestore());
+  const daemon = await runDaemon(state, {manifest: release.manifest, assetsDir: join(release.source,"skills/multi-task-flow/dist"), revision: () => "fixture"});
+  const http = () => fetch(`http://127.0.0.1:${port}/api/v1/runs`, {signal: AbortSignal.timeout(500)});
+  const logs = () => readFileSync(join(state.paths.logs,"viewer.jsonl"),"utf8").trim().split("\n").map(line => JSON.parse(line));
+  const tick = async (ms: number, done: () => boolean) => {
+    ticks.get(ms)!();
+    const deadline = Date.now() + 2000;
+    while (!done()) {
+      if (Date.now() > deadline) throw Error("Lifecycle did not settle");
+      await Bun.sleep(5);
+    }
+  };
+  return {state, daemon, http, logs, tick};
+}
+
+test("one registry lock timeout preserves an already reachable viewer and recovers", async () => {
+  const f = await fixture();
+  const original = PortRegistry.prototype.heartbeat;
+  let calls = 0;
+  const heartbeat = spyOn(PortRegistry.prototype, "heartbeat").mockImplementation(function (input) {
+    if (++calls === 1) return Promise.reject(Object.assign(new RegistryError("sensitive path must not be logged"), {code:"REGISTRY_LOCK_TIMEOUT"}));
+    return original.call(this, input);
+  });
+  try {
+    expect((await f.http()).status).toBe(401);
+    await f.tick(30000, () => f.logs().some(e => e.event === "maintenance_failed"));
+    expect((await f.http()).status).toBe(401);
+    await f.tick(30000, () => f.logs().some(e => e.event === "maintenance_recovered"));
+    expect(f.state.runtime().phase).toBe("running");
+    expect(JSON.stringify(f.logs())).not.toContain("sensitive path");
+    expect(f.logs().some(e => e.event === "maintenance_recovered")).toBe(true);
+  } finally { heartbeat.mockRestore(); await f.daemon.stop(); }
+});
+
+test("persistent registry timeouts close after the bounded retry budget with the real reason", async () => {
+  const f = await fixture();
+  const heartbeat = spyOn(PortRegistry.prototype,"heartbeat").mockRejectedValue(Object.assign(new RegistryError("secret"),{code:"REGISTRY_LOCK_TIMEOUT"}));
+  try {
+    for(let i=0;i<3;i++) await f.tick(30000, () => f.logs().filter(e => ["maintenance_failed", "stopped"].includes(e.event)).length === i+1);
+    await expect(f.http()).rejects.toThrow();
+    const stop = f.logs().find(e=>e.event==="stopped");
+    expect(stop.stop_reason).toBe("registry_heartbeat_error");
+    expect(Date.parse(stop.stop_started_at)).toBeLessThanOrEqual(Date.parse(stop.stop_completed_at));
+    expect(stop.error_code).toBe("REGISTRY_LOCK_TIMEOUT");
+  } finally {heartbeat.mockRestore(); await f.daemon.stop();}
+});
+
+test("non-transient registry failure stops immediately rather than weakening ownership fencing", async()=>{
+ const f=await fixture(); const heartbeat=spyOn(PortRegistry.prototype,"heartbeat").mockRejectedValue(new RegistryError("lease ownership changed"));
+ try {await f.tick(30000, () => f.state.runtime().phase === "stopped"); await expect(f.http()).rejects.toThrow(); expect(f.logs().find(e=>e.event==="stopped").stop_reason).toBe("registry_heartbeat_error");}
+ finally {heartbeat.mockRestore(); await f.daemon.stop();}
+});
+
+test("lease state errors are never logged as OS signals",async()=>{
+ const f=await fixture(); const expire=spyOn(f.state,"expire").mockImplementation(()=>{throw Error("secret")});
+ try {await f.tick(1000, () => f.state.runtime().phase === "stopped"); expect(f.logs().find(e=>e.event==="stopped").stop_reason).toBe("lease_state_error");}
+ finally {expire.mockRestore();await f.daemon.stop();}
+});
+
+
+test("registry lock contention exposes a typed retryable error", async () => {
+  const {root} = serviceFixture();
+  try {
+    const registry = new PortRegistry(join(root,"contended-registry"), {lockFactory: () => null});
+    await expect(registry.heartbeat({scopeId: "fixture", service: "viewer", lockTimeoutSec: 0})).rejects.toMatchObject({code: "REGISTRY_LOCK_TIMEOUT"});
+  } finally { rmSync(root,{recursive:true,force:true}); }
+});
+
+test.each(["SIGTERM", "SIGINT"] as const)("%s gets its own shutdown reason", async (signal) => {
+  const f=await fixture();
+  try {
+    process.emit(signal);
+    await f.daemon.stop();
+    expect(f.logs().find(e=>e.event==="stopped").stop_reason).toBe(signal);
+    await expect(f.http()).rejects.toThrow();
+  } finally { await f.daemon.stop(); }
+});
+
+test("public stop cannot inject lifecycle diagnostics", async () => {
+  const f = await fixture();
+  try {
+    expect(f.daemon.stop.length).toBe(0);
+    const stopWithArguments = f.daemon.stop as unknown as (...args: string[]) => Promise<void>;
+    await stopWithArguments("sensitive path", "SECRET");
+    const records = f.logs();
+    expect(records.find((event) => event.event === "stopped").stop_reason).toBe("requested");
+    expect(JSON.stringify(records)).not.toContain("sensitive path");
+    expect(JSON.stringify(records)).not.toContain("SECRET");
+  } finally { await f.daemon.stop(); }
+});
+
+test("actual lease expiry closes with leases_expired", async () => {
+ const f=await fixture();
+ try {
+   f.state.release("agent:fixture");
+   await f.tick(1000, () => f.state.runtime().phase === "stopped");
+   expect(f.logs().find(e=>e.event==="stopped").stop_reason).toBe("leases_expired");
+   await expect(f.http()).rejects.toThrow();
+ } finally {await f.daemon.stop();}
+});

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

@@ -0,0 +1,120 @@
+import { expect, test } from "bun:test";
+import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fixtureRelease, fixtureLegacyRelease, serviceFixture } from "./service-fixture";
+import { buildId, digest, verifyRelease, requireSourceRelease } from "../lib/service-release";
+import { SKILL_VERSION } from "../lib/contract";
+
+function update(source: string, manifest: any) {
+  const { build_id, ...body } = manifest;
+  writeFileSync(join(source, "manifest.json"), JSON.stringify({ ...body, build_id: buildId(body) }));
+}
+test("v2 checks complete resources, content, links and contained import closure", () => {
+  const { root } = serviceFixture();
+  try {
+    const { source, manifest } = fixtureRelease(root);
+    expect(verifyRelease(source).schema_version).toBe(2);
+    const entry = "skills/multi-task-flow/scripts/service.ts";
+    writeFileSync(join(source, entry), 'import "./missing.ts";');
+    manifest.files[entry] = digest('import "./missing.ts";'); update(source, manifest);
+    expect(() => verifyRelease(source)).toThrow("dependency is missing");
+    writeFileSync(join(source, entry), '// restored');
+    manifest.files[entry] = digest('// restored'); update(source, manifest);
+    const asset = "skills/multi-task-flow/dist/app.js";
+    writeFileSync(join(source, asset), "tampered");
+    expect(() => verifyRelease(source)).toThrow("checksum");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("viewer contract upgrades keep old release identity verification compatible", () => {
+  const { root } = serviceFixture();
+  try {
+    const { source, manifest } = fixtureRelease(root);
+    const candidate = { ...manifest, viewer_contract: 3 as const };
+    const { build_id: _candidateBuildId, ...candidateBody } = candidate;
+    writeFileSync(join(source, "manifest.json"), JSON.stringify({ ...candidateBody, build_id: buildId(candidateBody) }));
+    expect(verifyRelease(source).viewer_contract).toBe(3);
+
+    const legacy = { ...candidate, viewer_contract: 2 as const };
+    const { build_id: _buildId, ...legacyBody } = legacy;
+    const oldIdentity = digest(JSON.stringify({
+      ...Object.fromEntries(Object.entries(legacyBody).filter(([key, value]) =>
+        key !== "viewer_contract" && !(key === "skill_id" && value === "multi-task-flow") && !(key === "skill_version" && value === SKILL_VERSION) && !(key === "ledger_contract" && value === 2),
+      )),
+      files: Object.fromEntries(Object.entries(legacy.files).filter(([key]) => key !== "viewer").sort(([a], [b]) => a.localeCompare(b))),
+    }));
+    writeFileSync(join(source, "manifest.json"), JSON.stringify({ ...legacy, build_id: oldIdentity }));
+    expect(verifyRelease(source).viewer_contract).toBe(2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("candidate discovery selects the newest verified build and ignores the current build", async () => {
+  const { root, state } = serviceFixture();
+  try {
+    const old = fixtureRelease(root, "old");
+    const newer = fixtureRelease(root, "newer");
+    const rewrite = (source: string, manifest: any, service_version: string) => {
+      const { build_id, ...body } = manifest;
+      const updated = { ...body, service_version, build_id: buildId({ ...body, service_version }) };
+      writeFileSync(join(source, "manifest.json"), JSON.stringify(updated));
+      return updated;
+    };
+    const oldManifest = rewrite(old.source, old.manifest, "1.8.0");
+    const newerManifest = rewrite(newer.source, newer.manifest, "1.10.0");
+    mkdirSync(state.paths.candidates, { recursive: true });
+    cpSync(old.source, join(state.paths.candidates, oldManifest.build_id), { recursive: true });
+    cpSync(newer.source, join(state.paths.candidates, newerManifest.build_id), { recursive: true });
+    state.saveConfig({ schema_version: 1, port: 49152, registry_dir: join(root, "registry"), current_build: oldManifest.build_id, previous_build: null, agent_ttl_ms: 3600000 });
+    const { discoverCandidate } = await import("../lib/service-maintenance");
+    expect(discoverCandidate(state)?.service_version).toBe("1.10.0");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+test("v1 packages remain diagnostic-only and reject incomplete native pairs", () => {
+  const { root } = serviceFixture();
+  try {
+    const { source, manifest } = fixtureRelease(root);
+    rmSync(join(source, "skills"), {recursive:true});
+    const names = ["viewer", "dist/index.html", "dist/app.js", "dist/app.css"];
+    for (const name of names) { mkdirSync(dirname(join(source,name)), {recursive:true}); writeFileSync(join(source,name), name); }
+    const legacy = {...manifest, schema_version:1, files:Object.fromEntries(names.map(name => [name,digest(name)]))};
+    update(source, legacy);
+    expect(verifyRelease(source).schema_version).toBe(1);
+    expect(() => requireSourceRelease(verifyRelease(source))).toThrow("diagnostic-only");
+    legacy.files["viewer.mjs"] = "a".repeat(64); update(source, legacy);
+    expect(() => verifyRelease(source)).toThrow("incomplete");
+    delete legacy.files["viewer.mjs"]; legacy.files["../escape"] = "a".repeat(64); update(source,legacy);
+    expect(() => verifyRelease(source)).toThrow();
+  } finally { rmSync(root, {recursive:true,force:true}); }
+});
+
+
+test("rollback refuses a legacy package before touching config or service control", async () => {
+  const {root,state} = serviceFixture();
+  try {
+    const legacy = fixtureLegacyRelease(root);
+    mkdirSync(state.paths.releases,{recursive:true});
+    cpSync(legacy.source,join(state.paths.releases,legacy.manifest.build_id),{recursive:true});
+    state.saveConfig({schema_version:1,port:49152,registry_dir:join(root,"registry"),current_build:"b".repeat(64),previous_build:legacy.manifest.build_id,agent_ttl_ms:3600000});
+    const before = readFileSync(join(state.paths.config,"service.json"),"utf8");
+    let calls = 0;
+    const control = {unload(){calls++;},start(){calls++;},async status(){calls++;return {} as any;}};
+    const {switchRelease} = await import("../lib/service-maintenance");
+    await expect(switchRelease(state,"",true,control)).rejects.toThrow("diagnostic-only");
+    expect(calls).toBe(0); expect(readFileSync(join(state.paths.config,"service.json"),"utf8")).toBe(before);
+  } finally { rmSync(root,{recursive:true,force:true}); }
+});
+
+test("failed v2 startup restores legacy config without restarting the legacy program", async () => {
+  const {root,state} = serviceFixture();
+  try {
+    const legacy = fixtureLegacyRelease(root); const next = fixtureRelease(root);
+    mkdirSync(state.paths.releases,{recursive:true}); cpSync(legacy.source,join(state.paths.releases,legacy.manifest.build_id),{recursive:true});
+    state.saveConfig({schema_version:1,port:49152,registry_dir:join(root,"registry"),current_build:legacy.manifest.build_id,previous_build:null,agent_ttl_ms:3600000});
+    state.transaction(runtime => {runtime.pid=process.pid;runtime.phase="running";});
+    let starts=0;
+    const control={unload(){state.transaction(runtime=>{runtime.pid=null;runtime.phase="stopped";});}, start(){starts++;throw Error("controlled startup failure");}, async status(){return {} as any;}};
+    const {switchRelease}=await import("../lib/service-maintenance");
+    await expect(switchRelease(state,next.source,false,control)).rejects.toThrow("controlled startup failure");
+    expect(starts).toBe(1); expect(state.config().current_build).toBe(legacy.manifest.build_id); expect(state.runtime().pid).toBeNull();
+  } finally { rmSync(root,{recursive:true,force:true}); }
+});

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

@@ -0,0 +1,358 @@
+import { afterEach, expect, spyOn, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { PortRegistry } from "../../bin/modules/workspace/port_registry";
+import { LedgerStore } from "../lib/store";
+import { ServiceAuth } from "../lib/service-auth";
+import { startSharedViewer, listRuns, selectAssets } from "../lib/service-http";
+import { runDaemon } from "../lib/service-lifecycle";
+import { installRelease, switchRelease, nativeServiceControl } from "../lib/service-maintenance";
+import { verifyRelease } from "../lib/service-release";
+import { importRun } from "../lib/service-import";
+import { serviceCommand } from "../scripts/service";
+import { serviceFixture, fixtureRelease, fixtureRun } from "./service-fixture";
+
+const roots: string[] = [];
+const servers: Awaited<ReturnType<typeof startSharedViewer>>[] = [];
+afterEach(async () => {
+  for (const server of servers.splice(0)) await server.stop();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+function fixture() { const value = serviceFixture(); roots.push(value.root); return value; }
+test("one-time login persists sessions and explicit rotation revokes them", () => {
+  const { state } = fixture(); const auth = new ServiceAuth(state);
+  const credential = auth.credential();
+  const ticket = auth.ticket("/runs/example/");
+  const result = auth.exchange(ticket);
+  expect(result.target).toBe("/runs/example/");
+  expect(() => auth.exchange(ticket)).toThrow();
+  const request = new Request("http://127.0.0.1/", { headers: { cookie: result.cookie.split(";")[0]! } });
+  expect(new ServiceAuth(state).authorize(request)?.kind).toBe("browser");
+  expect(new ServiceAuth(state).credential()).toBe(credential);
+  auth.rotate(); expect(auth.authorize(request)).toBeNull();
+});
+test("service login emits browser-ready target tickets", async () => {
+  const { root, state } = fixture();
+  const release = fixtureRelease(root);
+  const probe = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() });
+  const port = probe.port!;
+  await probe.stop(true);
+  mkdirSync(join(root, "registry"), { recursive: true });
+  state.saveConfig({ schema_version: 1, port, registry_dir: join(root, "registry"), current_build: release.manifest.build_id, previous_build: null, agent_ttl_ms: 60_000 });
+  let daemon: Awaited<ReturnType<typeof runDaemon>> | undefined;
+  try {
+    daemon = await runDaemon(state, { manifest: release.manifest, assetsDir: join(release.source, "skills/multi-task-flow/dist"), revision: () => "test" });
+    const check = async (input: { run_id?: string }, target: string) => {
+      const result = await serviceCommand("login", input, state) as { login_url: string; expires_in_seconds: number; single_use: boolean };
+      const url = new URL(result.login_url);
+      expect(url.origin).toBe(`http://127.0.0.1:${port}`);
+      expect(url.pathname).toBe(target);
+      expect(url.hash).toBe("");
+      expect(url.searchParams.getAll("ticket")).toHaveLength(1);
+      expect(url.searchParams.get("ticket")).toMatch(/^[A-Za-z0-9_-]+$/);
+      expect(result).toMatchObject({ expires_in_seconds: 60, single_use: true });
+      expect(new ServiceAuth(state).exchange(url.searchParams.get("ticket")!, target).target).toBe(target);
+    };
+    await check({}, "/");
+    await check({ run_id: "demo.run" }, "/runs/demo.run/");
+  } finally {
+    await daemon?.stop();
+  }
+});
+test("multi-run routing has one listener, authenticated APIs and lazy watchers", async () => {
+  const { root, state } = fixture(); const release = fixtureRelease(root);
+  fixtureRun(state.paths.data, "first"); fixtureRun(state.paths.data, "second");
+  const viewer = await startSharedViewer(state, release.manifest, join(release.source, "skills/multi-task-flow/dist"), 0); servers.push(viewer);
+  const base = `http://127.0.0.1:${viewer.port}`;
+  const credential = new ServiceAuth(state).credential();
+  const headers = { authorization: "Bearer " + credential };
+  expect((await fetch(base + "/api/v1/runs")).status).toBe(401);
+  const runs = await (await fetch(base + "/api/v1/runs", { headers })).json() as { runs: unknown[] };
+  expect(runs.runs).toHaveLength(2); expect(viewer.watcherCount).toBe(0);
+  const view = await fetch(base + "/runs/first/api/view", { headers }); expect(view.status).toBe(200);
+  expect((await fetch(base + "/api/v1/runs/second/view", { headers })).status).toBe(200);
+  expect(viewer.watcherCount).toBe(0);
+  const stream = await fetch(base + "/api/v1/runs/first/events", { headers });
+  expect(viewer.watcherCount).toBe(1);
+  const reader = stream.body!.getReader(); await reader.read(); await reader.cancel();
+  for (let attempt = 0; attempt < 20 && viewer.watcherCount; attempt++) await Bun.sleep(25);
+  expect(viewer.watcherCount).toBe(0);
+  expect((await fetch(base + "/api/v1/lease", { method: "POST", headers: { ...headers, origin: "https://foreign.example" }, body: "{}" })).status).toBe(403);
+});
+test("target tickets authenticate on the run route and recover safely", async () => {
+  const { root, state } = fixture(); const release = fixtureRelease(root); fixtureRun(state.paths.data);
+  const viewer = await startSharedViewer(state, release.manifest, join(release.source, "skills/multi-task-flow/dist"), 0); servers.push(viewer);
+  const base = `http://127.0.0.1:${viewer.port}`;
+  const noFollow = (url: string, init: RequestInit = {}) => fetch(url, { ...init, redirect: "manual" });
+  const targetLocation = (response: Response) => {
+    const location = response.headers.get("location");
+    expect(location).not.toBeNull();
+    const url = new URL(location!, base);
+    return url.pathname + url.search;
+  };
+  const ticket = new ServiceAuth(state).ticket("/runs/demo-run/");
+  const response = await noFollow(base + "/runs/demo-run/?ticket=" + encodeURIComponent(ticket));
+  expect(response.status).toBe(302);
+  expect(targetLocation(response)).toBe("/runs/demo-run/");
+  const cookie = response.headers.get("set-cookie")!.split(";")[0]!;
+  const replay = await noFollow(base + "/runs/demo-run/?ticket=" + encodeURIComponent(ticket));
+  expect(replay.status).toBe(302);
+  const failedLocation = targetLocation(replay);
+  expect(new URL(failedLocation, base).pathname).toBe("/auth/failed");
+  const failedPage = await noFollow(base + failedLocation);
+  expect(failedPage.status).toBe(401);
+  expect(await failedPage.text()).toContain("一次性登录入口已过期或已使用。");
+  const recovered = await noFollow(base + failedLocation, { headers: { cookie } });
+  expect(recovered.status).toBe(302);
+  expect(targetLocation(recovered)).toBe("/runs/demo-run/");
+  const stale = await noFollow(base + "/runs/demo-run/?ticket=stale-ticket", { headers: { cookie } });
+  expect(stale.status).toBe(302);
+  expect(targetLocation(stale)).toBe("/runs/demo-run/");
+  const retainedTicket = new ServiceAuth(state).ticket("/runs/demo-run/");
+  const retained = await noFollow(base + "/runs/demo-run/?ticket=" + encodeURIComponent(retainedTicket), { headers: { cookie } });
+  expect(retained.status).toBe(302);
+  expect(targetLocation(retained)).toBe("/runs/demo-run/");
+  expect((await noFollow(base + "/runs/demo-run/?ticket=" + encodeURIComponent(retainedTicket))).status).toBe(302);
+  const viewTicket = new ServiceAuth(state).ticket("/runs/demo-run/");
+  const withView = await noFollow(base + "/runs/demo-run/?selected=task%3AC2&detail=1&tab=actual&ticket=" + encodeURIComponent(viewTicket));
+  expect(withView.status).toBe(302);
+  expect(targetLocation(withView)).toBe("/runs/demo-run/?selected=task%3AC2&detail=1&tab=actual");
+  for (const path of ["/login", "/login.js", "/resume-task.js", "/api/v1/login"]) expect((await noFollow(base + path)).status).toBe(404);
+  for (const value of ["https://evil.test/runs/demo-run/", "http://user:pass@127.0.0.1/runs/demo-run/", "/login"]) {
+    const invalid = await noFollow(base + "/auth/failed?redirect=" + encodeURIComponent(value));
+    expect(invalid.status).toBe(400);
+    expect(invalid.headers.get("location")).toBeNull();
+  }
+});
+
+test("browser session keeps CSRF checks and credential-free resource links", async () => {
+  const { root, state } = fixture(); const release = fixtureRelease(root); fixtureRun(state.paths.data);
+  const viewer = await startSharedViewer(state, release.manifest, join(release.source, "skills/multi-task-flow/dist"), 0); servers.push(viewer);
+  const base = `http://127.0.0.1:${viewer.port}`;
+  const ticket = new ServiceAuth(state).ticket("/runs/demo-run/");
+  const response = await fetch(base + "/runs/demo-run/?ticket=" + encodeURIComponent(ticket), { redirect: "manual" });
+  expect(response.status).toBe(302);
+  const cookie = response.headers.get("set-cookie")!.split(";")[0]!;
+  expect((await fetch(base + "/api/v1/lease", { method: "POST", headers: { cookie } })).status).toBe(403);
+  expect((await fetch(base + "/api/v1/lease", { method: "POST", headers: { cookie, origin: base } })).status).toBe(200);
+  const page = await (await fetch(base + "/runs/demo-run/", { headers: { cookie } })).text();
+  expect(page).toContain("/service-client.js"); expect(page).not.toContain(ticket);
+  expect((await fetch(base + "/runs/demo-run/api/document/../../state/auth.json", { headers: { cookie } })).status).not.toBe(200);
+});
+test("legacy-view uses the previous viewer as an isolated read-only fallback", async () => {
+  const { root, state } = fixture();
+  const previous = fixtureRelease(root, "previous", { readOnly: true });
+  const installed = await installRelease(state, previous.source);
+  const target = fixtureRelease(root, "target");
+  const { store } = fixtureRun(state.paths.data, "demo-run");
+  const before = readFileSync(store.ledgerPath);
+  state.saveConfig({ ...state.config(), current_build: target.manifest.build_id, previous_build: installed.build_id });
+  const viewer = await startSharedViewer(state, target.manifest, join(target.source, "skills/multi-task-flow/dist"), 0); servers.push(viewer);
+  const base = `http://127.0.0.1:${viewer.port}`;
+  const headers = { authorization: "Bearer " + new ServiceAuth(state).credential() };
+  const response = await fetch(base + "/api/v1/runs/demo-run/legacy-view", { headers });
+  expect(response.status).toBe(200);
+  const body = await response.json() as { read_only: boolean; run_id: string; fallback_build_id: string; view: { orchestration: { id: string; revision: number } } };
+  expect(body).toMatchObject({ read_only: true, run_id: "demo-run", fallback_build_id: installed.build_id });
+  expect(body.view.orchestration).toEqual({ id: "demo-run", revision: 18 });
+  expect(readFileSync(store.ledgerPath)).toEqual(before);
+  expect((await fetch(base + "/api/v1/runs/demo-run/legacy-view", { method: "POST", headers })).status).not.toBe(200);
+});
+test("custom views require declared compatibility and malformed runs do not break discovery", () => {
+  const { root, state } = fixture(); const { store } = fixtureRun(state.paths.data);
+  const custom = join(store.runPath, "view"); mkdirSync(custom);
+  expect(selectAssets(state.paths.data, "demo-run", root).warning).not.toBeNull();
+  writeFileSync(join(custom, "view.manifest.json"), JSON.stringify({ api_version: 1, frontend_contract: 1 }));
+  expect(selectAssets(state.paths.data, "demo-run", root).path).toBe(custom);
+  mkdirSync(join(state.paths.data, "runs", "broken"));
+  const runs = listRuns(state.paths.data); expect(runs.total).toBe(2);
+  expect(runs.runs.find(run => run.id === "broken")).toHaveProperty("error");
+});
+test("install persists a fixed port without starting a process and rejects corrupt bundles", async () => {
+  const { root, state } = fixture(); const bundle = fixtureRelease(root);
+  const result = await installRelease(state, bundle.source);
+  expect(result.started).toBe(false); expect(state.config().port).toBe(result.port);
+  expect(state.runtime().phase).toBe("stopped");
+  expect(readFileSync(join(state.paths.config, "viewer.plist"), "utf8")).toContain("<key>RunAtLoad</key><false/>");
+  writeFileSync(join(bundle.source, "skills/multi-task-flow/dist/app.js"), "corrupt");
+  expect(() => verifyRelease(bundle.source)).toThrow("checksum");
+});
+test("code health failure restores config and preserves leases without touching ledger", async () => {
+  const { root, state } = fixture(); const bundle = fixtureRelease(root);
+  await installRelease(state, bundle.source); const previous = state.config();
+  const next = fixtureRelease(root, "next"); const { store } = fixtureRun(state.paths.data);
+  const bytes = readFileSync(store.ledgerPath, "utf8");
+  state.renew({ id: "agent:x:y", kind: "agent", run_id: "y", thread_id: "x" }, 60_000);
+  const deadline = state.runtime().leases[0]!.expires_at;
+  let healthCalls = 0;
+  const control = { ...nativeServiceControl, startupTimeoutMs: 25, unload: () => {}, start: () => {}, status: async () => { healthCalls++; throw new Error("unhealthy"); } };
+  // Deterministic failure exercises the same switch code without OS service mutation.
+  await expect(switchRelease(state, next.source, false, control)).rejects.toThrow("healthy");
+  expect(healthCalls).toBeGreaterThan(0); expect(state.config()).toEqual(previous);
+  expect(state.runtime().leases[0]!.expires_at).toBe(deadline);
+  expect(readFileSync(store.ledgerPath, "utf8")).toBe(bytes);
+}, 20_000);
+test("maintenance lease covers the readiness window and startup failure removes only that lease", async () => {
+  const { root, state } = fixture();
+  await installRelease(state, fixtureRelease(root).source);
+  state.renew({ id: "existing-agent", kind: "agent", run_id: null, thread_id: null }, 180_000);
+  const before = state.runtime().leases;
+  const control = {
+    ...nativeServiceControl,
+    unload: () => {},
+    start: () => {
+      expect(state.runtime().leases.find(lease => lease.id === "maintenance")!.expires_at).toBeGreaterThan(Date.now() + 60_000);
+      throw new Error("controlled startup failure");
+    },
+  };
+  await expect(switchRelease(state, fixtureRelease(root, "lease-window").source, false, control)).rejects.toThrow("controlled startup failure");
+  expect(state.runtime().leases).toEqual(before);
+});
+for (const recover of [false, true]) test(`slow native ${recover ? "recovery" : "startup"} renews maintenance coverage without extending users`, async () => {
+  const { root, state } = fixture();
+  await installRelease(state, fixtureRelease(root).source);
+  const original = state.config().current_build;
+  state.renew({ id: "agent:slow:run", kind: "agent", run_id: "run", thread_id: "slow" }, 180_000);
+  const before = state.runtime().leases;
+  state.transaction(runtime => { runtime.phase = "running"; runtime.pid = process.pid; runtime.generation = "slow-test"; });
+  let now = Date.now();
+  const clock = spyOn(Date, "now").mockImplementation(() => now);
+  let starts = 0;
+  let remaining = 0;
+  const control = {
+    unload: () => state.transaction(runtime => { runtime.phase = "stopped"; runtime.pid = null; }),
+    start: () => {
+      starts++;
+      now += 75_000;
+      if (recover && starts === 1) throw new Error("controlled slow startup failure");
+      state.transaction(runtime => { runtime.phase = "running"; runtime.pid = process.pid; });
+    },
+    status: async () => {
+      if (starts > 0) remaining = state.runtime().leases.find(lease => lease.id === "maintenance")!.expires_at - now;
+      return { ok: true, build_id: state.config().current_build, source_sha: "a".repeat(40), compatibility: { api_versions: [1] }, generation: "slow-test", pid: process.pid, port: state.config().port };
+    },
+  };
+  try {
+    const operation = switchRelease(state, fixtureRelease(root, `slow-${recover}`).source, false, control);
+    if (recover) await expect(operation).rejects.toThrow("controlled slow startup failure");
+    else await operation;
+    expect(starts).toBe(recover ? 2 : 1);
+    expect(remaining).toBe(90_000);
+    expect(state.runtime().leases).toEqual(before);
+    expect(state.config().current_build === original).toBe(recover);
+  } finally { clock.mockRestore(); }
+});
+test("failed recovery unload still releases the maintenance lease without extending users", async () => {
+  const { root, state } = fixture();
+  await installRelease(state, fixtureRelease(root).source);
+  state.renew({ id: "existing-agent", kind: "agent", run_id: null, thread_id: null }, 180_000);
+  const before = state.runtime().leases;
+  let unloads = 0;
+  const control = {
+    ...nativeServiceControl,
+    unload: () => { if (++unloads > 1) throw new Error("controlled unload failure"); },
+    start: () => { throw new Error("controlled startup failure"); },
+  };
+  await expect(switchRelease(state, fixtureRelease(root, "unload-failure").source, false, control)).rejects.toThrow("controlled unload failure");
+  expect(state.runtime().leases).toEqual(before);
+});
+test("import seals old writes, retains backup and is idempotent", async () => {
+  const { root, state } = fixture(); await installRelease(state, fixtureRelease(root).source);
+  const source = join(root, "legacy"); const { store } = fixtureRun(source);
+  const imported = importRun(state, source, "demo-run");
+  expect(existsSync(join(imported.backup, "ledger.json"))).toBe(true);
+  expect(() => store.update(() => {})).toThrow();
+  expect(importRun(state, source, "demo-run").already_imported).toBe(true);
+  expect(imported.url).toMatch(/\/runs\/demo-run\/$/);
+});
+test("import rejects conflicting IDs and symlinks before changing the source", async () => {
+  const { root, state } = fixture(); await installRelease(state, fixtureRelease(root).source);
+  const source = join(root, "legacy"); const { store } = fixtureRun(source);
+  const target = fixtureRun(state.paths.data).store;
+  target.update(ledger => { ledger.revision++; });
+  expect(() => importRun(state, source, "demo-run")).toThrow("different content");
+  expect(existsSync(store.ledgerPath)).toBe(true);
+  const another = fixtureRun(source, "symlinked").store;
+  symlinkSync(store.ledgerPath, join(another.runPath, "unsafe"));
+  expect(() => importRun(state, source, "symlinked")).toThrow("symlinks");
+  expect(existsSync(another.ledgerPath)).toBe(true);
+});
+test("interrupted sealed-source migration resumes without restoring over new data", async () => {
+  const { root, state } = fixture(); await installRelease(state, fixtureRelease(root).source);
+  const source = join(root, "interrupted"); fixtureRun(source);
+  expect(() => importRun(state, source, "demo-run", stage => { if (stage === "source_sealed") throw new Error("injected interruption"); })).toThrow("injected interruption");
+  expect(existsSync(join(source, "runs", "demo-run", "ledger.json"))).toBe(false);
+  const resumed = importRun(state, source, "demo-run");
+  expect(resumed.already_imported).toBe(true);
+  // Target is authoritative and may advance after migration.
+  const target = new LedgerStore(state.paths.data, "demo-run");
+  target.update(ledger => { ledger.revision++; });
+  expect(importRun(state, source, "demo-run").already_imported).toBe(true);
+});
+test("fixed user port can restart offline without overwriting an active PID", async () => {
+  const { state } = fixture();
+  let listening = false;
+  const registry = new PortRegistry(join(state.paths.state, "registry-regression"), { portListening: () => listening });
+  const allocated = await registry.allocate({ scopeId: state.paths.scope, service: "viewer", project: "multi-task-flow", repoRoot: "", branch: "", worktreePath: "" });
+  const port = Number(allocated.port);
+  await registry.releaseService(state.paths.scope, "viewer");
+  await registry.register({ scopeId: state.paths.scope, service: "viewer", port, expectedPid: null, createIfMissing: true });
+  try {
+    listening = true;
+    await expect(registry.claimAndRun({ scopeId: state.paths.scope, service: "viewer", port, pid: process.pid }, () => { throw new Error("must not bind an occupied port"); })).rejects.toThrow("LISTENing");
+    listening = false;
+    await registry.claimAndRun({ scopeId: state.paths.scope, service: "viewer", port, pid: process.pid }, () => {
+      listening = true;
+    });
+    await expect(registry.register({ scopeId: state.paths.scope, service: "viewer", port, expectedPid: null, createIfMissing: true })).rejects.toThrow("pid no longer matches");
+    await expect(registry.releaseService(state.paths.scope, "viewer", 24, 10, { port, pid: null })).rejects.toThrow("pid no longer matches");
+    await registry.releaseService(state.paths.scope, "viewer", 24, 10, { port, pid: process.pid });
+  } finally { listening = false; }
+});
+test("failed live upgrade verifies the recovered old build and retains exact deadlines", async () => {
+  const { root, state } = fixture(); await installRelease(state, fixtureRelease(root).source);
+  const original = state.config().current_build;
+  state.renew({ id: "agent:live:run", kind: "agent", run_id: "run", thread_id: "live" }, 90_000);
+  state.transaction(runtime => { runtime.phase = "running"; runtime.pid = process.pid; runtime.generation = "live-test"; });
+  const deadline = state.runtime().leases[0]!.expires_at;
+  let restoredChecks = 0;
+  const control = {
+    startupTimeoutMs: 25,
+    unload: () => state.transaction(runtime => { runtime.phase = "stopped"; runtime.pid = null; }),
+    start: () => state.transaction(runtime => { runtime.phase = "running"; runtime.pid = process.pid; }),
+    status: async () => {
+      if (state.config().current_build !== original) throw new Error("new build unhealthy");
+      restoredChecks++;
+      return { ok: true, build_id: original, source_sha: "a".repeat(40), compatibility: { api_versions: [1] }, generation: "live-test", pid: process.pid, port: state.config().port };
+    },
+  };
+  await expect(switchRelease(state, fixtureRelease(root, "unhealthy-live").source, false, control)).rejects.toThrow("healthy");
+  expect(restoredChecks).toBe(2);
+  expect(state.config().current_build).toBe(original);
+  expect(state.runtime().leases).toHaveLength(1);
+  expect(state.runtime().leases[0]!.expires_at).toBe(deadline);
+}, 20_000);
+test("future ledger contracts are refused before read or write", () => {
+  const { state } = fixture(); const { store } = fixtureRun(state.paths.data);
+  const ledger = JSON.parse(readFileSync(store.ledgerPath, "utf8"));
+  ledger.contract_version = 99; writeFileSync(store.ledgerPath, JSON.stringify(ledger));
+  const bytes = readFileSync(store.ledgerPath, "utf8");
+  expect(() => store.read()).toThrow("not supported");
+  expect(() => store.update(value => { value.revision++; })).toThrow("not supported");
+  expect(readFileSync(store.ledgerPath, "utf8")).toBe(bytes);
+});
+
+
+test("launchd definition preserves the installing caller PATH without assuming tool locations", async () => {
+  const { writeLaunchdDefinition } = await import("../lib/service-launchd");
+  const { readFileSync } = await import("node:fs");
+  const { root, state } = fixture();
+  await installRelease(state, fixtureRelease(root).source);
+  const previous = process.env.PATH;
+  try {
+    process.env.PATH = "/caller/tools&extensions:/usr/bin";
+    const xml = readFileSync(writeLaunchdDefinition(state), "utf8");
+    expect(xml).toContain("<key>PATH</key><string>/caller/tools&amp;extensions:/usr/bin</string>");
+    expect(xml).not.toContain("<string>/usr/bin:/bin</string>");
+  } finally { if (previous === undefined) delete process.env.PATH; else process.env.PATH = previous; }
+});