@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/test/cli-notifier.test.ts

@@ -0,0 +1,235 @@
+import { access, chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, test, vi } from "vitest";
+import cliNotifierPlugin from "../src/plugins/cli-notifier.js";
+import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+
+type PluginConfig = { enabled?: boolean; title?: string; timeoutMs?: number };
+
+async function createNotifier(config: PluginConfig = { enabled: false }): Promise<{
+  context: Context;
+  panels: PiPluginUiRegistry;
+  tool: ReturnType<PiToolRegistry["snapshot"]>["customTools"][number];
+  tools: PiToolRegistry;
+}> {
+  const context = new Context();
+  const panels = new PiPluginUiRegistry();
+  const tools = new PiToolRegistry();
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(cliNotifierPlugin, config);
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "cli_notify");
+  if (tool === undefined) throw new Error("cli_notify was not registered");
+  return { context, panels, tool, tools };
+}
+
+async function waitForFile(path: string): Promise<void> {
+  await vi.waitFor(
+    async () => {
+      await expect(access(path)).resolves.toBeUndefined();
+    },
+    { timeout: 5_000, interval: 10 },
+  );
+}
+
+describe("cli-notifier", () => {
+  test("declares message and title bounds in the tool schema", async () => {
+    const fixture = await createNotifier();
+    try {
+      expect(fixture.tool.parameters).toMatchObject({
+        properties: {
+          message: { type: "string", minLength: 1, maxLength: 2_048 },
+          title: { type: "string", minLength: 1, maxLength: 256 },
+        },
+      });
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("rejects malformed notification inputs before recording them", async () => {
+    const fixture = await createNotifier();
+    try {
+      await expect(fixture.tool.execute("null", null, undefined, undefined, {} as never)).rejects.toThrow(/message must be a string/iu);
+      for (const message of [7, "", "   ", "x".repeat(2_049), "contains\0null"]) {
+        await expect(fixture.tool.execute("message", { message }, undefined, undefined, {} as never)).rejects.toThrow(/notification message/iu);
+      }
+      for (const title of [7, "", "   ", "x".repeat(257), "contains\0null"]) {
+        await expect(fixture.tool.execute("title", { message: "valid", title }, undefined, undefined, {} as never)).rejects.toThrow(/notification title/iu);
+      }
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { notifications: [] } }]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("accepts exact input boundaries and keeps only isolated recent history", async () => {
+    const fixture = await createNotifier({ enabled: false });
+    try {
+      await expect(fixture.tool.execute("minimum", { message: "x", title: "y" }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { delivered: false, reason: "disabled" },
+      });
+      for (let index = 0; index < 20; index += 1) {
+        await fixture.tool.execute(
+          String(index),
+          { message: index === 19 ? "x".repeat(2_048) : `message-${index}`, title: "t".repeat(256) },
+          undefined,
+          undefined,
+          {} as never,
+        );
+      }
+      const [firstPanel] = await fixture.panels.snapshot();
+      if (firstPanel === undefined) throw new Error("cli-notifier-panel was not registered");
+      const data = firstPanel.data as { notifications: Array<{ message: string }>; timeoutMs: number };
+      expect(data.timeoutMs).toBe(10_000);
+      expect(data.notifications).toHaveLength(20);
+      data.notifications[0]!.message = "mutated";
+
+      const [secondPanel] = await fixture.panels.snapshot();
+      expect((secondPanel?.data as { notifications: Array<{ message: string }> }).notifications[0]?.message).toBe("x".repeat(2_048));
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("rejects non-finite notification timeouts at the config boundary", async () => {
+    const context = new Context();
+    context.provide("piTools", new PiToolRegistry());
+    context.provide("piPluginUi", new PiPluginUiRegistry());
+    try {
+      await expect(context.plugin(cliNotifierPlugin, { enabled: false, timeoutMs: Number.NaN })).rejects.toThrow(/timeoutMs.*number|multiple/iu);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("labels aborted turns and ignores intermediate retry failures", async () => {
+    const fixture = await createNotifier();
+    try {
+      fixture.context.emit("pi/session-event", {
+        type: "agent_end",
+        willRetry: true,
+        messages: [{ role: "assistant", stopReason: "error", errorMessage: "temporary" }],
+      } as never);
+      fixture.context.emit("pi/session-event", {
+        type: "agent_end",
+        willRetry: false,
+        messages: [{ role: "assistant", stopReason: "aborted" }],
+      } as never);
+
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { notifications: [{ message: "Agent turn aborted." }] } }]);
+      const [panel] = await fixture.panels.snapshot();
+      expect((panel?.data as { notifications: unknown[] }).notifications).toHaveLength(1);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("propagates caller cancellation to the desktop command", async () => {
+    if (process.platform === "win32") return;
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-notifier-cancel-"));
+    const bin = join(root, "bin");
+    const started = join(root, "started");
+    const executable = join(bin, process.platform === "darwin" ? "osascript" : "notify-send");
+    const originalPath = process.env.PATH;
+    const controller = new AbortController();
+    let fixture: Awaited<ReturnType<typeof createNotifier>> | undefined;
+    try {
+      await mkdir(bin);
+      await writeFile(executable, `#!/bin/sh\n: > ${JSON.stringify(started)}\nsleep 2\n`, "utf8");
+      await chmod(executable, 0o700);
+      process.env.PATH = `${bin}${delimiter}${originalPath ?? ""}`;
+      fixture = await createNotifier({ enabled: true, timeoutMs: 5_000 });
+      const execution = fixture.tool.execute("cancel", { message: "cancel me" }, controller.signal, undefined, {} as never);
+      await waitForFile(started);
+
+      controller.abort(new Error("caller cancelled notification"));
+
+      await expect(execution).rejects.toThrow(/caller cancelled notification/iu);
+    } finally {
+      process.env.PATH = originalPath;
+      await fixture?.context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("passes Windows notification text as data instead of PowerShell source", async () => {
+    if (process.platform === "win32") return;
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-notifier-windows-"));
+    const bin = join(root, "bin");
+    const argumentsPath = join(root, "arguments");
+    const messagePath = join(root, "message");
+    const titlePath = join(root, "title");
+    const executable = join(bin, "powershell.exe");
+    const originalPath = process.env.PATH;
+    const originalPlatform = process.platform;
+    let fixture: Awaited<ReturnType<typeof createNotifier>> | undefined;
+    try {
+      await mkdir(bin);
+      await writeFile(
+        executable,
+        `#!/bin/sh\nprintf '%s\\n' "$@" > ${JSON.stringify(argumentsPath)}\nprintf '%s' "$PI_HARNESS_NOTIFICATION_MESSAGE" > ${JSON.stringify(messagePath)}\nprintf '%s' "$PI_HARNESS_NOTIFICATION_TITLE" > ${JSON.stringify(titlePath)}\n`,
+        "utf8",
+      );
+      await chmod(executable, 0o700);
+      process.env.PATH = `${bin}${delimiter}${originalPath ?? ""}`;
+      Object.defineProperty(process, "platform", { configurable: true, value: "win32" });
+      fixture = await createNotifier({ enabled: true });
+      const message = "message'; Write-Output INJECTED; #";
+      const title = "title'; Write-Output INJECTED; #";
+
+      await expect(fixture.tool.execute("windows", { message, title }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { delivered: true, platform: "win32" },
+      });
+      expect(await readFile(argumentsPath, "utf8")).not.toContain(message);
+      expect(await readFile(argumentsPath, "utf8")).not.toContain(title);
+      await expect(readFile(messagePath, "utf8")).resolves.toBe(message);
+      await expect(readFile(titlePath, "utf8")).resolves.toBe(title);
+    } finally {
+      Object.defineProperty(process, "platform", { configurable: true, value: originalPlatform });
+      process.env.PATH = originalPath;
+      await fixture?.context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("terminates Linux command options before user-controlled text", async () => {
+    if (process.platform === "win32") return;
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-notifier-linux-"));
+    const bin = join(root, "bin");
+    const argumentsPath = join(root, "arguments");
+    const executable = join(bin, "notify-send");
+    const originalPath = process.env.PATH;
+    const originalPlatform = process.platform;
+    let fixture: Awaited<ReturnType<typeof createNotifier>> | undefined;
+    try {
+      await mkdir(bin);
+      await writeFile(executable, `#!/bin/sh\nprintf '%s\\n' "$@" > ${JSON.stringify(argumentsPath)}\n`, "utf8");
+      await chmod(executable, 0o700);
+      process.env.PATH = `${bin}${delimiter}${originalPath ?? ""}`;
+      Object.defineProperty(process, "platform", { configurable: true, value: "linux" });
+      fixture = await createNotifier({ enabled: true });
+
+      await expect(fixture.tool.execute("linux", { message: "--help", title: "-danger" }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { delivered: true, platform: "linux" },
+      });
+      await expect(readFile(argumentsPath, "utf8")).resolves.toBe("--\n-danger\n--help\n");
+    } finally {
+      Object.defineProperty(process, "platform", { configurable: true, value: originalPlatform });
+      process.env.PATH = originalPath;
+      await fixture?.context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("unregisters all surfaces and invalidates retained tool references on disposal", async () => {
+    const fixture = await createNotifier();
+    await fixture.context.fiber.dispose();
+
+    expect(fixture.tools.snapshot().customTools).toEqual([]);
+    await expect(fixture.panels.snapshot()).resolves.toEqual([]);
+    await expect(fixture.tool.execute("stale", { message: "should not send" }, undefined, undefined, {} as never)).rejects.toThrow(/disposed/iu);
+  });
+});

package/packages/core/test/code2skill.test.ts

@@ -0,0 +1,264 @@
+import { access, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
+import { parse } from "yaml";
+import { describe, expect, test } from "vitest";
+import code2SkillPlugin from "../src/plugins/code2skill.js";
+import { PiPluginUiRegistry, PiToolRegistry, provideLaunchContext } from "../src/services.js";
+
+async function createCode2Skill(): Promise<{
+  context: Context;
+  cwd: string;
+  panels: PiPluginUiRegistry;
+  root: string;
+  tool: ReturnType<PiToolRegistry["snapshot"]>["customTools"][number];
+  tools: PiToolRegistry;
+}> {
+  const root = await mkdtemp(join(tmpdir(), "pi-harness-code2skill-"));
+  const cwd = join(root, "workspace");
+  const agentDir = join(root, "agent");
+  await mkdir(cwd);
+  await mkdir(agentDir);
+  const context = new Context();
+  const panels = new PiPluginUiRegistry();
+  const tools = new PiToolRegistry();
+  provideLaunchContext(context, { cwd, agentDir, args: [], requestExit() {} });
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(code2SkillPlugin);
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "skill_pack_create");
+  if (tool === undefined) throw new Error("skill_pack_create was not registered");
+  return { context, cwd, panels, root, tool, tools };
+}
+
+async function dispose(fixture: Awaited<ReturnType<typeof createCode2Skill>>): Promise<void> {
+  await fixture.context.fiber.dispose();
+  await rm(fixture.root, { recursive: true, force: true });
+}
+
+describe("code2skill", () => {
+  test("declares complete skill input bounds", async () => {
+    const fixture = await createCode2Skill();
+    try {
+      expect(fixture.tool.parameters).toMatchObject({
+        properties: {
+          name: { type: "string", minLength: 1, maxLength: 128 },
+          description: { type: "string", minLength: 1, maxLength: 1_024 },
+          files: { type: "array", minItems: 1, maxItems: 32, items: { type: "string", minLength: 1, maxLength: 4_096 } },
+        },
+      });
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("rejects accessor parameters without invoking them", async () => {
+    const fixture = await createCode2Skill();
+    let accessed = false;
+    const params = { description: "Safe description", files: ["source.ts"] } as { name?: string; description: string; files: string[] };
+    Object.defineProperty(params, "name", {
+      enumerable: true,
+      get() {
+        accessed = true;
+        throw new Error("skill name getter executed");
+      },
+    });
+    try {
+      await expect(fixture.tool.execute("accessor", params, undefined, undefined, {} as never)).rejects.toThrow(/data properties/iu);
+      expect(accessed).toBe(false);
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("rejects unknown parameter keys before creating a skill", async () => {
+    const fixture = await createCode2Skill();
+    try {
+      await writeFile(join(fixture.cwd, "source.ts"), "export {};\n", "utf8");
+
+      await expect(
+        fixture.tool.execute(
+          "unknown",
+          { name: "Unknown", description: "Must be rejected", files: ["source.ts"], unexpected: true },
+          undefined,
+          undefined,
+          {} as never,
+        ),
+      ).rejects.toThrow(/unknown property/iu);
+      await expect(access(join(fixture.cwd, ".pi"))).rejects.toThrow();
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("rejects malformed parameters before creating an output directory", async () => {
+    const fixture = await createCode2Skill();
+    try {
+      await writeFile(join(fixture.cwd, "source.ts"), "export {};\n", "utf8");
+      const invalid: unknown[] = [
+        null,
+        { name: 7, description: "valid", files: ["source.ts"] },
+        { name: " ", description: "valid", files: ["source.ts"] },
+        { name: "x".repeat(129), description: "valid", files: ["source.ts"] },
+        { name: "valid", description: 7, files: ["source.ts"] },
+        { name: "valid", description: " ", files: ["source.ts"] },
+        { name: "valid", description: "x".repeat(1_025), files: ["source.ts"] },
+        { name: "valid", description: "valid", files: null },
+        { name: "valid", description: "valid", files: [] },
+        { name: "valid", description: "valid", files: Array.from({ length: 33 }, () => "source.ts") },
+        { name: "valid", description: "valid", files: [7] },
+        { name: "valid", description: "valid", files: ["x".repeat(4_097)] },
+        { name: "valid", description: "valid", files: ["source\n.ts"] },
+      ];
+      for (const params of invalid) {
+        await expect(fixture.tool.execute("invalid", params, undefined, undefined, {} as never)).rejects.toThrow(/skill|source|file|description|name/iu);
+      }
+      await expect(access(join(fixture.cwd, ".pi"))).rejects.toThrow();
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("writes valid YAML and safe Markdown for adversarial metadata and file names", async () => {
+    const fixture = await createCode2Skill();
+    try {
+      const source = "docs/a](evil).ts";
+      await mkdir(join(fixture.cwd, "docs"));
+      await writeFile(join(fixture.cwd, source), "export {};\n", "utf8");
+      const result = await fixture.tool.execute(
+        "create",
+        { name: "Parser\n# injected", description: "parse: safely\n---\n# not frontmatter", files: [source] },
+        undefined,
+        undefined,
+        {} as never,
+      );
+      const details = result.details as { directory: string; slug: string };
+      expect(details.directory).toBe(join(".pi", "skills", details.slug));
+      const manifest = await readFile(join(fixture.cwd, details.directory, "SKILL.md"), "utf8");
+      const frontmatter = manifest.match(/^---\n([\s\S]*?)\n---\n/u)?.[1];
+      expect(frontmatter).toBeDefined();
+      expect(parse(frontmatter!)).toEqual({ name: details.slug, description: "parse: safely --- # not frontmatter" });
+      expect(manifest).toContain("- [docs/a\\](evil).ts](references/docs/a%5D%28evil%29.ts)");
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("accepts exact source limits and rejects the first byte over either limit", async () => {
+    const fixture = await createCode2Skill();
+    try {
+      const exactFiles = Array.from({ length: 8 }, (_, index) => `exact-${index}.bin`);
+      await Promise.all(exactFiles.map((file) => writeFile(join(fixture.cwd, file), Buffer.alloc(256 * 1024, 0x61))));
+      const exact = await fixture.tool.execute(
+        "exact",
+        { name: "n".repeat(128), description: "d".repeat(1_024), files: exactFiles },
+        undefined,
+        undefined,
+        {} as never,
+      );
+      const exactDetails = exact.details as { bytes: number; files: Array<{ bytes: number }> };
+      expect(exactDetails.bytes).toBe(2 * 1024 * 1024);
+      expect(exactDetails.files).toHaveLength(8);
+      expect(exactDetails.files.every((file) => file.bytes === 256 * 1024)).toBe(true);
+
+      await writeFile(join(fixture.cwd, "oversized.bin"), Buffer.alloc(256 * 1024 + 1, 0x62));
+      await expect(
+        fixture.tool.execute("file-over", { name: "File Over", description: "Must fail", files: ["oversized.bin"] }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/262144-byte limit/iu);
+      await writeFile(join(fixture.cwd, "one-more.bin"), Buffer.from("x"));
+      await expect(
+        fixture.tool.execute(
+          "total-over",
+          { name: "Total Over", description: "Must fail", files: [...exactFiles, "one-more.bin"] },
+          undefined,
+          undefined,
+          {} as never,
+        ),
+      ).rejects.toThrow(/2097152 bytes/iu);
+      await expect(access(join(fixture.cwd, ".pi", "skills", "file-over"))).rejects.toThrow();
+      await expect(access(join(fixture.cwd, ".pi", "skills", "total-over"))).rejects.toThrow();
+
+      const emptyFiles = Array.from({ length: 32 }, (_, index) => `empty-${index}.txt`);
+      await Promise.all(emptyFiles.map((file) => writeFile(join(fixture.cwd, file), "")));
+      const counted = await fixture.tool.execute(
+        "file-count",
+        { name: "File Count", description: "Exact file count", files: emptyFiles },
+        undefined,
+        undefined,
+        {} as never,
+      );
+      const countedFiles = (counted.details as { files: Array<{ bytes: number; path: string }> }).files;
+      expect(countedFiles).toHaveLength(32);
+      expect(countedFiles.at(-1)).toEqual({ path: "empty-31.txt", bytes: 0 });
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("serializes concurrent creation of the same complete skill", async () => {
+    const fixture = await createCode2Skill();
+    try {
+      await writeFile(join(fixture.cwd, "source.ts"), "export {};\n", "utf8");
+      const params = { name: "Concurrent", description: "Complete artifact", files: ["source.ts"] };
+      const outcomes = await Promise.allSettled([
+        fixture.tool.execute("first", params, undefined, undefined, {} as never),
+        fixture.tool.execute("second", params, undefined, undefined, {} as never),
+      ]);
+      expect(outcomes.map((outcome) => outcome.status).sort()).toEqual(["fulfilled", "rejected"]);
+      const failure = outcomes.find((outcome): outcome is PromiseRejectedResult => outcome.status === "rejected");
+      expect(String(failure?.reason)).toMatch(/already exists/iu);
+      await expect(readFile(join(fixture.cwd, ".pi", "skills", "concurrent", "SKILL.md"), "utf8")).resolves.toContain("Complete artifact");
+      await expect(readFile(join(fixture.cwd, ".pi", "skills", "concurrent", "references", "source.ts"), "utf8")).resolves.toBe("export {};\n");
+      expect((await readdir(join(fixture.cwd, ".pi", "skills"))).filter((name) => name.startsWith(".code2skill-"))).toEqual([]);
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("honors caller cancellation without writing output", async () => {
+    const fixture = await createCode2Skill();
+    const controller = new AbortController();
+    try {
+      await writeFile(join(fixture.cwd, "source.ts"), "export {};\n", "utf8");
+      controller.abort(new Error("caller cancelled skill creation"));
+      await expect(
+        fixture.tool.execute("cancel", { name: "Cancelled", description: "No output", files: ["source.ts"] }, controller.signal, undefined, {} as never),
+      ).rejects.toThrow(/caller cancelled skill creation/iu);
+      await expect(access(join(fixture.cwd, ".pi"))).rejects.toThrow();
+    } finally {
+      await dispose(fixture);
+    }
+  });
+
+  test("isolates tool and panel reports and unregisters them on disposal", async () => {
+    const fixture = await createCode2Skill();
+    try {
+      await writeFile(join(fixture.cwd, "source.ts"), "export {};\n", "utf8");
+      const result = await fixture.tool.execute(
+        "create",
+        { name: "Isolated", description: "State remains internal", files: ["source.ts"] },
+        undefined,
+        undefined,
+        {} as never,
+      );
+      (result.details as { files: Array<{ path: string }> }).files[0]!.path = "mutated";
+      const [firstPanel] = await fixture.panels.snapshot();
+      const latest = (firstPanel?.data as { latest: { files: Array<{ path: string }> } }).latest;
+      expect(latest.files[0]?.path).toBe("source.ts");
+      latest.files[0]!.path = "panel-mutated";
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { latest: { files: [{ path: "source.ts" }] } } }]);
+      const retained = fixture.tool;
+
+      await fixture.context.fiber.dispose();
+
+      expect(fixture.tools.snapshot().customTools).toEqual([]);
+      await expect(fixture.panels.snapshot()).resolves.toEqual([]);
+      await expect(
+        retained.execute("stale", { name: "Stale", description: "No output", files: ["source.ts"] }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/disposed/iu);
+    } finally {
+      await dispose(fixture);
+    }
+  });
+});

package/packages/core/test/colleague-skill.test.ts

@@ -4,6 +4,30 @@ import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
 import { createColleagueHandoff } from "../src/plugins/colleague-skill.js";
 import colleagueSkillPlugin from "../src/plugins/colleague-skill.js";
 
+async function createHarness(entries: unknown[] = []): Promise<{
+  context: Context;
+  entries: unknown[];
+  panels: PiPluginUiRegistry;
+  tool: ReturnType<PiToolRegistry["snapshot"]>["customTools"][number];
+  tools: PiToolRegistry;
+}> {
+  const context = new Context();
+  const tools = new PiToolRegistry();
+  const panels = new PiPluginUiRegistry();
+  context.provide("piSession", {
+    manager: {
+      getEntries: () => entries,
+      appendCustomEntry: (_type: string, data: unknown) => entries.push({ type: "custom", customType: "pi-harness/colleague-handoff", data }),
+    },
+  } as never);
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(colleagueSkillPlugin);
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "colleague_handoff");
+  if (tool === undefined) throw new Error("colleague_handoff was not registered");
+  return { context, entries, panels, tool, tools };
+}
+
 describe("colleague skill", () => {
   test("normalizes a bounded handoff packet for another role", () => {
     expect(
@@ -42,6 +66,149 @@ describe("colleague skill", () => {
     ).toThrow("files must contain 20 items");
   });
 
+  test("accepts every exact handoff boundary", () => {
+    const handoff = createColleagueHandoff(
+      {
+        toRole: "r".repeat(128),
+        objective: "o".repeat(4_000),
+        context: "c".repeat(4_000),
+        constraints: Array.from({ length: 20 }, () => "x".repeat(1_000)),
+        files: Array.from({ length: 20 }, () => "f".repeat(4_096)),
+        acceptance: Array.from({ length: 20 }, () => "a".repeat(1_000)),
+      },
+      "handoff-boundary",
+      "2026-09-03T00:00:00.000Z",
+    );
+    expect(handoff.toRole).toHaveLength(128);
+    expect(handoff.objective).toHaveLength(4_000);
+    expect(handoff.context).toHaveLength(4_000);
+    expect(handoff.constraints).toHaveLength(20);
+    expect(handoff.constraints[0]).toHaveLength(1_000);
+    expect(handoff.files[0]).toHaveLength(4_096);
+    expect(handoff.acceptance[0]).toHaveLength(1_000);
+  });
+
+  test("declares complete packet bounds in the tool schema", async () => {
+    const fixture = await createHarness();
+    try {
+      expect(fixture.tool.parameters).toMatchObject({
+        properties: {
+          toRole: { type: "string", minLength: 1, maxLength: 128 },
+          objective: { type: "string", minLength: 1, maxLength: 4_000 },
+          context: { type: "string", maxLength: 4_000 },
+          constraints: { type: "array", maxItems: 20, items: { type: "string", minLength: 1, maxLength: 1_000 } },
+          files: { type: "array", maxItems: 20, items: { type: "string", minLength: 1, maxLength: 4_096 } },
+          acceptance: { type: "array", maxItems: 20, items: { type: "string", minLength: 1, maxLength: 1_000 } },
+        },
+      });
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("rejects malformed packet fields before writing session state", async () => {
+    const fixture = await createHarness();
+    const invalid: unknown[] = [
+      null,
+      { toRole: 7, objective: "valid" },
+      { toRole: " ", objective: "valid" },
+      { toRole: "r".repeat(129), objective: "valid" },
+      { toRole: "reviewer", objective: 7 },
+      { toRole: "reviewer", objective: "o".repeat(4_001) },
+      { toRole: "reviewer", objective: "valid", context: 7 },
+      { toRole: "reviewer", objective: "valid", constraints: null },
+      { toRole: "reviewer", objective: "valid", constraints: [7] },
+      { toRole: "reviewer", objective: "valid", constraints: [" "] },
+      { toRole: "reviewer", objective: "valid", constraints: ["x".repeat(1_001)] },
+      { toRole: "reviewer", objective: "valid", files: ["x".repeat(4_097)] },
+      { toRole: "reviewer", objective: "valid", acceptance: Array.from({ length: 21 }, () => "done") },
+    ];
+    try {
+      for (const params of invalid) {
+        await expect(fixture.tool.execute("invalid", params, undefined, undefined, {} as never)).rejects.toThrow(
+          /handoff|role|objective|context|constraints|files|acceptance/iu,
+        );
+      }
+      expect(fixture.entries).toEqual([]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("creates unique IDs even when the clock does not advance", async () => {
+    const fixture = await createHarness();
+    const originalNow = Date.now;
+    Date.now = () => 1_000;
+    try {
+      const first = await fixture.tool.execute("first", { toRole: "reviewer", objective: "First" }, undefined, undefined, {} as never);
+      const second = await fixture.tool.execute("second", { toRole: "reviewer", objective: "Second" }, undefined, undefined, {} as never);
+      expect((first.details as { id: string }).id).not.toBe((second.details as { id: string }).id);
+    } finally {
+      Date.now = originalNow;
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("skips malformed persisted records and isolates durable state", async () => {
+    const persisted = {
+      id: "handoff-valid",
+      toRole: "reviewer",
+      objective: "Review the change",
+      context: "Context",
+      constraints: ["No API changes"],
+      files: ["src/index.ts"],
+      acceptance: ["Tests pass"],
+      createdAt: "2026-09-03T00:00:00.000Z",
+    };
+    const entries: unknown[] = [
+      { type: "custom", customType: "pi-harness/colleague-handoff", data: persisted },
+      { type: "custom", customType: "pi-harness/colleague-handoff", data: { id: 7 } },
+    ];
+    const fixture = await createHarness(entries);
+    try {
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { latest: { id: "handoff-valid" } } }]);
+      const result = await fixture.tool.execute(
+        "create",
+        { toRole: "frontend", objective: "Implement UI", files: ["src/view.tsx"] },
+        undefined,
+        undefined,
+        {} as never,
+      );
+      (result.details as { files: string[] }).files[0] = "mutated";
+      const appended = entries.at(-1) as { data: { files: string[] } };
+      expect(appended.data.files).toEqual(["src/view.tsx"]);
+      const [firstPanel] = await fixture.panels.snapshot();
+      const latest = (firstPanel?.data as { latest: { files: string[] } }).latest;
+      expect(latest.files).toEqual(["src/view.tsx"]);
+      latest.files[0] = "panel-mutated";
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { latest: { files: ["src/view.tsx"] } } }]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("honors cancellation and invalidates retained tools on disposal", async () => {
+    const fixture = await createHarness();
+    const controller = new AbortController();
+    controller.abort(new Error("caller cancelled handoff"));
+    try {
+      await expect(
+        fixture.tool.execute("cancel", { toRole: "reviewer", objective: "Do not persist" }, controller.signal, undefined, {} as never),
+      ).rejects.toThrow(/caller cancelled handoff/iu);
+      expect(fixture.entries).toEqual([]);
+      const retained = fixture.tool;
+      await fixture.context.fiber.dispose();
+      expect(fixture.tools.snapshot().customTools).toEqual([]);
+      await expect(fixture.panels.snapshot()).resolves.toEqual([]);
+      await expect(retained.execute("stale", { toRole: "reviewer", objective: "Do not persist" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /disposed/iu,
+      );
+      expect(fixture.entries).toEqual([]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
   test("persists a handoff through the registered Pi tool and panel", async () => {
     const context = new Context();
     const tools = new PiToolRegistry();