pi-pstack-native 0.0.0-stage → 1.0.0

package/src/workflow/graph.ts

@@ -0,0 +1,53 @@
+import type { WorkflowNodeSpec } from "../runtime/types.ts";
+
+export function validateGraph(nodes: WorkflowNodeSpec[]): void {
+  if (!Array.isArray(nodes) || nodes.length === 0) throw new Error("Workflow requires at least one node.");
+  const keys = new Set<string>();
+  for (const node of nodes) {
+    if (!node.key || ['__proto__','constructor','prototype'].includes(node.key) || !/^[a-zA-Z0-9._-]+$/.test(node.key)) throw new Error(`Invalid workflow node key: ${node.key || "(empty)"}`);
+    if (keys.has(node.key)) throw new Error(`Duplicate workflow node key: ${node.key}`);
+    keys.add(node.key);
+    if (!node.task?.trim()) throw new Error(`Workflow node ${node.key} has no task.`);
+  }
+  for (const node of nodes) {
+    for (const dep of node.dependsOn ?? []) {
+      if (!keys.has(dep)) throw new Error(`Workflow node ${node.key} depends on unknown node ${dep}.`);
+      if (dep === node.key) throw new Error(`Workflow node ${node.key} cannot depend on itself.`);
+    }
+  }
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const byKey = new Map(nodes.map((node) => [node.key, node]));
+  const visit = (key: string): void => {
+    if (visited.has(key)) return;
+    if (visiting.has(key)) throw new Error(`Workflow contains a dependency cycle at ${key}.`);
+    visiting.add(key);
+    for (const dep of byKey.get(key)?.dependsOn ?? []) visit(dep);
+    visiting.delete(key);
+    visited.add(key);
+  };
+  for (const key of keys) visit(key);
+}
+
+export function chainNodes(tasks: Array<Omit<WorkflowNodeSpec, "dependsOn">>): WorkflowNodeSpec[] {
+  return tasks.map((task, index) => ({ ...task, dependsOn: index === 0 ? [] : [tasks[index - 1]!.key] }));
+}
+
+export function dependencyEdges(nodes: WorkflowNodeSpec[]): Array<{ from: string; to: string }> {
+  return nodes.flatMap((node) => (node.dependsOn ?? []).map((dep) => ({ from: dep, to: node.key })));
+}
+
+export function downstreamKeys(nodes: Record<string, { dependsOn: string[] }>, root: string): Set<string> {
+  const result = new Set<string>();
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [key, node] of Object.entries(nodes)) {
+      if (key === root || result.has(key)) continue;
+      if (node.dependsOn.some((dep) => dep === root || result.has(dep))) {
+        result.add(key); changed = true;
+      }
+    }
+  }
+  return result;
+}

package/src/worktree/manager.ts

@@ -0,0 +1,60 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { worktreeRoot } from "../runtime/home.ts";
+
+const execFileAsync = promisify(execFile);
+
+export interface WorktreeInfo { path: string; branch: string; repoRoot: string; baseRef: string; }
+
+function safe(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "call";
+}
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const result = await execFileAsync("git", args, { cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+  return result.stdout.trim();
+}
+
+export async function gitRoot(cwd: string): Promise<string | undefined> {
+  try { return await git(cwd, ["rev-parse", "--show-toplevel"]); } catch { return undefined; }
+}
+
+export async function createWorktree(cwd: string, ownerId: string, baseRef = "HEAD"): Promise<WorktreeInfo> {
+  const repoRoot = await gitRoot(cwd);
+  if (!repoRoot) throw new Error(`Worktree isolation requires a Git repository: ${cwd}`);
+  const root = worktreeRoot();
+  mkdirSync(root, { recursive: true });
+  const suffix = safe(ownerId);
+  const branch = `pstack-native/${suffix}`;
+  const path = resolve(join(root, `${safe(basename(repoRoot))}-${suffix}`));
+  if (existsSync(path)) throw new Error(`Refusing to overwrite existing worktree path: ${path}`);
+  try {
+    await git(repoRoot, ["worktree", "add", "-b", branch, path, baseRef]);
+  } catch (error) {
+    rmSync(path, { recursive: true, force: true });
+    throw error;
+  }
+  return { path, branch, repoRoot, baseRef };
+}
+
+export async function isWorktreeDirty(path: string): Promise<boolean> {
+  return (await git(path, ["status", "--porcelain"])) !== "";
+}
+
+export async function removeWorktree(info: WorktreeInfo, force = false): Promise<void> {
+  if (!existsSync(info.path)) return;
+  if (!force && await isWorktreeDirty(info.path)) throw new Error(`Refusing to remove dirty worktree: ${info.path}`);
+  await git(info.repoRoot, ["worktree", "remove", ...(force ? ["--force"] : []), info.path]);
+}
+
+export async function auditWorktree(info:WorktreeInfo,comparisonBase=info.baseRef):Promise<{path:string;branch:string;comparisonBase:string;baseSha:string;headSha:string;dirty:boolean;ahead:number;merged:boolean}> {
+  if(!comparisonBase || comparisonBase.startsWith('-') || !/^[A-Za-z0-9_./-]+$/.test(comparisonBase))throw new Error('Invalid comparison base');
+  const headSha=await git(info.path,['rev-parse','HEAD']),baseSha=await git(info.repoRoot,['rev-parse','--verify',`${comparisonBase}^{commit}`]);
+  const actualBranch=await git(info.path,['branch','--show-current']);
+  if(actualBranch!==info.branch)throw new Error('Worktree branch changed');
+  const ahead=Number(await git(info.path,['rev-list','--count',`${baseSha}..${headSha}`]));
+  let merged=true;try{await git(info.path,['merge-base','--is-ancestor',headSha,baseSha]);}catch{merged=false;}
+  return {path:info.path,branch:actualBranch,comparisonBase,baseSha,headSha,dirty:await isWorktreeDirty(info.path),ahead,merged};
+}

package/src/worktree/snapshot.ts

@@ -0,0 +1,35 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { copyFileSync, lstatSync, mkdirSync, readlinkSync, realpathSync, symlinkSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fingerprint, sameFingerprint } from '../artifacts/fingerprint.ts';
+
+/** Copy the exact staged, unstaged and untracked review target into a new Git worktree. */
+export function copyReviewSnapshot(source: string, target: string): void {
+  const root = realpathSync(execFileSync('git', ['-C', source, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim());
+  const dest = realpathSync(target);
+  const before = fingerprint(root);
+  const git = (args: string[]) => execFileSync('git', ['-C', root, ...args], { maxBuffer: 32 * 1024 * 1024 });
+  const apply = (patch: Buffer, staged: boolean) => {
+    if (!patch.length) return;
+    const result = spawnSync('git', ['-C', dest, 'apply', '--binary', ...(staged ? ['--index'] : [])], { input: patch, maxBuffer: 32 * 1024 * 1024 });
+    if (result.status !== 0) throw new Error(`REVIEW_SNAPSHOT_PATCH_FAILED: ${result.stderr.toString('utf8').slice(0, 1000)}`);
+  };
+  apply(git(['diff', '--no-ext-diff', '--binary', '--cached', 'HEAD', '--']), true);
+  apply(git(['diff', '--no-ext-diff', '--binary', '--']), false);
+  const untracked = git(['ls-files', '--others', '--exclude-standard', '-z']).toString('utf8').split('\0').filter(Boolean);
+  for (const path of untracked) {
+    if (isAbsolute(path) || path.split('/').some(part => !part || part === '.' || part === '..')) throw new Error('REVIEW_SNAPSHOT_UNSAFE_PATH');
+    const from = join(root, path), to = join(dest, path);
+    const parent = realpathSync(dirname(from));
+    const rel = relative(root, parent);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error('REVIEW_SNAPSHOT_UNSAFE_PATH');
+    mkdirSync(dirname(to), { recursive: true });
+    const destParent = realpathSync(dirname(to));
+    if (!destParent.startsWith(`${dest}${sep}`) && destParent !== dest) throw new Error('REVIEW_SNAPSHOT_UNSAFE_PATH');
+    const stat = lstatSync(from);
+    if (stat.isSymbolicLink()) symlinkSync(readlinkSync(from), to);
+    else if (stat.isFile()) copyFileSync(from, to);
+    else throw new Error('REVIEW_SNAPSHOT_UNSUPPORTED_FILE');
+  }
+  if (!sameFingerprint(before, fingerprint(root)) || !sameFingerprint(before, fingerprint(dest))) throw new Error('REVIEW_SNAPSHOT_CHANGED');
+}

package/test/baseline-owner.test.ts

@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { capture, fingerprint, git, ownerOf } from "../src/artifacts/fingerprint.ts";
+import { protocol, transact } from "../src/runtime/protocol.ts";
+import { verify } from "../src/verification/runner.ts";
+import type { TaskBrief } from "../src/contracts/types.ts";
+
+function fixture() {
+  const root = mkdtempSync(join(process.cwd(), ".test-baseline-"));
+  const repo = join(root, "repo");
+  mkdirSync(repo);
+  process.env.PSTACK_NATIVE_HOME = join(root, "state");
+  git(repo, ["init", "-q"]);
+  git(repo, ["config", "user.name", "Test"]);
+  git(repo, ["config", "user.email", "test@example.invalid"]);
+  writeFileSync(join(repo, "allowed.txt"), "baseline");
+  git(repo, ["add", "."]);
+  git(repo, ["commit", "-qm", "baseline"]);
+  return { root, repo, cleanup() { rmSync(root, { recursive: true, force: true }); delete process.env.PSTACK_NATIVE_HOME; } };
+}
+
+function brief(repo: string, revision = 1): TaskBrief {
+  return {
+    id: "task", revision, contractLevel: "strict", goal: "Check scope",
+    scope: { repoId: fingerprint(repo).repoId, include: ["allowed.txt"], exclude: [] },
+    contextRefs: [], acceptance: [{ id: "scope", description: "Scope", required: true, gateIds: ["diff"] }],
+    verification: [{ id: "diff", kind: "diff", maxFiles: 0 }], forbidden: [], standingOrders: [],
+    reportFormat: "task-report-v1", timeboxSeconds: 10,
+  };
+}
+
+function baseline(repo: string, owner: Parameters<typeof ownerOf>[0], extra: { workflowId?: string; callKey?: string } = {}) {
+  return capture(repo, undefined, [], "working", { kind: "baseline", owner: ownerOf(owner, extra) }).fingerprint;
+}
+
+function reasonOf(ledger: { evidenceRefs: string[] }): string | undefined {
+  return protocol().evidence[ledger.evidenceRefs[0]!]?.reason;
+}
+
+test("a baseline captured for one workflow cannot verify another workflow", async () => {
+  const f = fixture();
+  try {
+    const b = brief(f.repo);
+    const captured = baseline(f.repo, b, { workflowId: "wf_alpha", callKey: "write" });
+    const ledger = await verify(f.repo, b, { before: captured, owner: ownerOf(b, { workflowId: "wf_beta", callKey: "write" }) });
+    assert.equal(ledger.status, "blocked");
+    assert.equal(reasonOf(ledger), "BASELINE_NOT_OWNED");
+    assert.equal(ledger.contractAccepted, false);
+  } finally { f.cleanup(); }
+});
+
+test("a workflow baseline cannot be consumed outside its workflow", async () => {
+  const f = fixture();
+  try {
+    const b = brief(f.repo);
+    const captured = baseline(f.repo, b, { workflowId: "wf_alpha", callKey: "write" });
+    const ledger = await verify(f.repo, b, { before: captured, owner: { briefId: b.id, briefRevision: b.revision } });
+    assert.equal(ledger.status, "blocked");
+    assert.equal(reasonOf(ledger), "BASELINE_NOT_OWNED");
+  } finally { f.cleanup(); }
+});
+
+test("a baseline captured under an older brief revision is refused", async () => {
+  const f = fixture();
+  try {
+    const captured = baseline(f.repo, brief(f.repo, 1));
+    const ledger = await verify(f.repo, brief(f.repo, 2), { before: captured });
+    assert.equal(ledger.status, "blocked");
+    assert.equal(reasonOf(ledger), "BASELINE_NOT_OWNED");
+  } finally { f.cleanup(); }
+});
+
+test("a baseline captured without an owner is refused", async () => {
+  const f = fixture();
+  try {
+    const b = brief(f.repo);
+    const captured = baseline(f.repo, b);
+    transact("test-owner-stripped", "artifact", "test", (state) => {
+      delete state.artifacts[(captured as { baselineId?: string }).baselineId!]!.owner;
+      return null;
+    });
+    const ledger = await verify(f.repo, b, { before: captured });
+    assert.equal(ledger.status, "blocked");
+    assert.equal(reasonOf(ledger), "BASELINE_NOT_OWNED");
+  } finally { f.cleanup(); }
+});
+
+test("a baseline captured in another checkout is refused there", async () => {
+  const f = fixture();
+  try {
+    const other = join(f.root, "other");
+    mkdirSync(other);
+    git(other, ["init", "-q"]);
+    git(other, ["config", "user.name", "Test"]);
+    git(other, ["config", "user.email", "test@example.invalid"]);
+    writeFileSync(join(other, "allowed.txt"), "baseline");
+    git(other, ["add", "."]);
+    git(other, ["commit", "-qm", "baseline"]);
+    const b = brief(f.repo);
+    const captured = baseline(f.repo, b);
+    const ledger = await verify(other, brief(other), { before: captured, owner: ownerOf(brief(other)) });
+    assert.equal(ledger.status, "blocked");
+    assert.equal(reasonOf(ledger), "DIFF_BASE_UNAVAILABLE");
+  } finally { f.cleanup(); }
+});
+
+test("the same task keeps its baseline across a recovery", async () => {
+  const f = fixture();
+  try {
+    const b = brief(f.repo);
+    const owner = ownerOf(b, { workflowId: "wf_alpha", callKey: "write" });
+    const captured = baseline(f.repo, b, { workflowId: "wf_alpha", callKey: "write" });
+    const report = (artifact: typeof captured) => ({ status: "completed" as const, base: artifact.commitSha, head: artifact.commitSha, artifactRefs: [], commandsRun: [], evidenceRefs: [], deviations: [], unresolved: [], nextActions: [] });
+    for (const attempt of [1, 2]) {
+      const ledger = await verify(f.repo, b, { before: captured, owner, report: report(captured) });
+      assert.equal(ledger.status, "passed", `recovery attempt ${attempt} keeps the owned baseline`);
+      assert.equal(ledger.contractAccepted, true, `recovery attempt ${attempt} accepts the contract`);
+    }
+  } finally { f.cleanup(); }
+});

package/test/benchmark.test.ts

@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { caseEvidence, exitCode, parseArgs } from "../scripts/benchmark.mjs";
+
+test("parser defaults the output path and rejects missing required flags", () => {
+  assert.deepEqual(parseArgs(["--agent-dir", "/tmp/agent", "--model", "provider/model"]), { agentDir: "/tmp/agent", model: "provider/model", output: "benchmark-output" });
+  assert.equal(parseArgs(["--agent-dir", "/tmp/agent", "--model", "provider/model", "--output", "/tmp/out"]).output, "/tmp/out");
+  assert.throws(() => parseArgs(["--agent-dir", "/tmp/agent"]));
+  assert.throws(() => parseArgs(["--model", "provider/model"]));
+  assert.throws(() => parseArgs([]));
+  assert.equal(parseArgs(["--agent-dir", "a", "--model", "p/m", "--limit", "3", "--max-tokens", "1000"]).limit, 3);
+  assert.throws(() => parseArgs(["--agent-dir", "a", "--model", "p/m", "--limit", "0"]), /Invalid --limit/);
+  assert.throws(() => parseArgs(["--agent-dir", "a", "--model", "p/m", "--limt", "3"]), /Unknown/);
+  assert.throws(() => parseArgs(["--agent-dir", "a", "--model", "p/m", "--limit"]), /missing/i);
+});
+
+test("exit policy fails closed", () => {
+  assert.equal(exitCode([{ verified: true }, { verified: true }], []), 0);
+  assert.equal(exitCode([{ verified: true }, { verified: false }], []), 1);
+  assert.equal(exitCode([{ verified: false }], [{ status: "blocked", reason: "AUTHENTICATION_UNAVAILABLE" }]), 1);
+  assert.equal(exitCode([{ verified: true }, { verified: true }], [{ status: "blocked", reason: "AUTHENTICATION_UNAVAILABLE" }]), 1);
+  assert.equal(exitCode([], []), 1);
+});
+
+test("benchmark distinguishes passing test evidence from a rejected task report", () => {
+  const call = { verification: { ledgerId: "ledger", reason: "TASK_REPORT_INCOMPLETE_OR_MISMATCH" }, reportError: "TASK_REPORT_INCOMPLETE" };
+  const state = { ledgers: { ledger: { evidenceRefs: ["other", "test"], contractAccepted: false } }, evidence: { other: { gateId: "other", status: "passed" }, test: { gateId: "tests", status: "passed" } } };
+  assert.deepEqual(caseEvidence(call, state), { testEvidence: "passed", contractAccepted: false, verificationReason: "TASK_REPORT_INCOMPLETE_OR_MISMATCH", reportError: "TASK_REPORT_INCOMPLETE" });
+  assert.equal(caseEvidence({}, state).testEvidence, "not-run");
+});
+
+const copyPackage = (dir) => {
+  const repo = process.cwd();
+  mkdirSync(join(dir, "scripts"), { recursive: true });
+  for (const script of ["benchmark.mjs", "check-benchmark.mjs"]) cpSync(join(repo, "scripts", script), join(dir, "scripts", script));
+  cpSync(join(repo, "UPSTREAM.json"), join(dir, "UPSTREAM.json"));
+  cpSync(join(repo, "benchmarks"), join(dir, "benchmarks"), { recursive: true });
+  cpSync(join(repo, "dist"), join(dir, "dist"), { recursive: true });
+  symlinkSync(join(repo, "node_modules"), join(dir, "node_modules"), "dir");
+  return dir;
+};
+const runCheck = (root) => spawnSync(process.execPath, [join(root, "scripts/check-benchmark.mjs")], { env: { ...process.env, PSTACK_BENCHMARK_ROOT: root }, encoding: "utf8" });
+
+test("check-benchmark proves the entry links against a tampered root", () => {
+  const base = mkdtempSync(join(tmpdir(), "pstack-benchmark-"));
+  try {
+    const pristine = copyPackage(join(base, "pristine"));
+    const tampered = join(base, "tampered");
+    cpSync(pristine, tampered, { recursive: true });
+    const service = join(tampered, "dist/runner/service.js");
+    writeFileSync(service, readFileSync(service, "utf8").replace("export async function runnerOnce", "async function runnerOnce"));
+    const bad = runCheck(tampered);
+    assert.notEqual(bad.status, 0, `tampered root unexpectedly passed\n${bad.stdout}${bad.stderr}`);
+    const good = runCheck(pristine);
+    assert.equal(good.status, 0, `pristine root failed\n${good.stdout}${good.stderr}`);
+  } finally { rmSync(base, { recursive: true, force: true }); }
+});
+
+test("a symlinked entry runs the benchmark instead of exiting green", () => {
+  const base = mkdtempSync(join(tmpdir(), "pstack-benchmark-link-"));
+  try {
+    const pkg = copyPackage(join(base, "pkg"));
+    symlinkSync(join(pkg, "scripts/benchmark.mjs"), join(pkg, "scripts/benchmark-link.mjs"));
+    for (const argv of [["scripts/benchmark-link.mjs"], ["--preserve-symlinks-main", "scripts/benchmark-link.mjs"]]) {
+      const linked = spawnSync(process.execPath, argv, { cwd: pkg, encoding: "utf8" });
+      assert.notEqual(linked.status, 0, `${argv.join(" ")} exited green without running\n${linked.stdout}${linked.stderr}`);
+      assert.match(linked.stderr, /benchmark requires explicit --agent-dir/, `${argv.join(" ")} did not reach the benchmark argument guard\n${linked.stderr}`);
+    }
+    const output = join(base, "out");
+    const ran = spawnSync(process.execPath, ["scripts/benchmark-link.mjs", "--agent-dir", join(base, "agent"), "--model", "test/model", "--output", output], { cwd: pkg, encoding: "utf8" });
+    assert.equal(ran.status, 1, `symlinked benchmark run reported success\n${ran.stdout}${ran.stderr}`);
+    assert.match(ran.stderr, /AUTHENTICATION_UNAVAILABLE/);
+    const results = JSON.parse(readFileSync(join(output, "results.json"), "utf8"));
+    assert.equal(results.rows.length, 20);
+    assert.equal(results.rows.filter((row: { verified: boolean }) => row.verified).length, 0);
+  } finally { rmSync(base, { recursive: true, force: true }); }
+});

package/test/cancellation.test.ts

@@ -0,0 +1,92 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { WorkflowEngine, type AgentRunner } from "../src/workflow/engine.ts";
+import type { AgentRecord } from "../src/runtime/types.ts";
+
+async function inHome(fn: () => Promise<void>) {
+  const old = process.env.PSTACK_NATIVE_HOME;
+  const dir = mkdtempSync(join(process.cwd(), ".pstack-cancel-"));
+  process.env.PSTACK_NATIVE_HOME = dir;
+  try { await fn(); } finally {
+    if (old === undefined) delete process.env.PSTACK_NATIVE_HOME;
+    else process.env.PSTACK_NATIVE_HOME = old;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+const ctx = { sessionManager: { getSessionId: () => "owner" } } as any;
+function agent(spec: Parameters<AgentRunner["run"]>[0], state: AgentRecord["state"]): AgentRecord {
+  return { id: spec.id!, workflowId: spec.workflowId, callKey: spec.callKey, profile: spec.profile,
+    task: spec.task, state, cwd: spec.cwd, isolation: spec.isolation ?? "shared", attempt: spec.attempt ?? 1,
+    depth: 1, createdAt: new Date().toISOString() };
+}
+
+test("cancel without acknowledgement reports cancelling, never a false terminal success", async () => inHome(async () => {
+  let release!: () => void;
+  const started = new Promise<void>((resolve) => { release = resolve; });
+  let signal!: () => void;
+  const gate = new Promise<void>((resolve) => { signal = resolve; });
+  const records = new Map<string, AgentRecord>();
+  const agents: AgentRunner = {
+    async run(spec) { records.set(spec.id!, agent(spec, "running")); release(); await gate; return agent(spec, "cancelled"); },
+    get(id) { return records.get(id); },
+    async stop(id) { return { ...records.get(id)!, state: "cancelling" }; },
+    async recover(record) { return record; },
+  };
+  const engine = new WorkflowEngine(agents);
+  const wf = engine.create({ cwd: "/repo", nodes: [{ key: "a", task: "edit" }, { key: "b", task: "later", dependsOn: ["a"] }] });
+  const running = engine.run(wf.id, ctx);
+  await started;
+  const pending = await engine.cancel(wf.id);
+  assert.equal(pending.state, "cancelling");
+  assert.equal(pending.calls.a.state, "running");
+  assert.equal(pending.calls.b.state, "cancelled");
+  assert.throws(() => engine.retry(wf.id, "b"), /stop all agents/);
+  signal();
+  assert.equal((await running).state, "cancelled");
+}));
+
+test("pause/cancel does not discard a concurrent call settlement", async () => inHome(async () => {
+  let trigger!: () => void;
+  let started!: () => void;
+  const gate = new Promise<void>((resolve) => { trigger = resolve; });
+  const ready = new Promise<void>((resolve) => { started = resolve; });
+  const records = new Map<string, AgentRecord>();
+  const agents: AgentRunner = {
+    async run(spec) { records.set(spec.id!, agent(spec, "running")); started(); await gate; return agent(spec, "completed"); },
+    get(id) { return records.get(id); },
+    async stop(id) { return { ...records.get(id)!, state: "cancelling" }; },
+    async recover(record) { return record; },
+  };
+  const engine = new WorkflowEngine(agents);
+  const wf = engine.create({ cwd: "/repo", nodes: [{ key: "a", task: "edit" }] });
+  const running = engine.run(wf.id, ctx);
+  await ready;
+  engine.pause(wf.id);
+  trigger();
+  assert.equal((await running).state, "paused");
+  assert.equal(engine.get(wf.id)!.calls.a.state, "completed");
+}));
+
+test("resume during a paused active call does not strand or spin the executor", async () => inHome(async () => {
+  let unblock!: () => void;
+  let started!: () => void;
+  const gate = new Promise<void>((resolve) => { unblock = resolve; });
+  const seen = new Promise<void>((resolve) => { started = resolve; });
+  const runner: AgentRunner = {
+    async run(spec) { if (spec.callKey === "a") { started(); await gate; } return agent(spec, "completed"); },
+    get() { return undefined; },
+    async stop() { throw new Error("not needed"); },
+    async recover(record) { return record; },
+  };
+  const engine = new WorkflowEngine(runner);
+  const wf = engine.create({ cwd: "/repo", nodes: [{ key: "a", task: "a" }, { key: "b", task: "b", dependsOn: ["a"] }] });
+  const run = engine.run(wf.id, ctx);
+  await seen;
+  engine.pause(wf.id);
+  engine.resume(wf.id, ctx);
+  unblock();
+  assert.equal((await run).state, "completed");
+  assert.equal(engine.get(wf.id)!.calls.b.state, "completed");
+}));

package/test/candidate-port.test.ts

@@ -0,0 +1,18 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {existsSync,readFileSync} from 'node:fs';
+import {loadSkillsFromDir} from '@earendil-works/pi-coding-agent';
+
+test('pinned candidate accounts for every diff without advancing baseline or claiming integration',()=>{
+ const report=JSON.parse(readFileSync('docs/upstream-sync/reports/978ca6e9c0e0_837067b75aa2.json','utf8'));
+ const receipt=JSON.parse(readFileSync('docs/upstream-sync/candidate-0.15.23.json','utf8'));
+ assert.deepEqual(receipt.tasks.map((t:any)=>t.upstreamPath).sort(),report.changes.map((c:any)=>c.path).sort());
+ assert.equal(receipt.candidateSha,report.candidate.sha);assert.equal(receipt.integrated,false);assert.equal(receipt.status,'proposed');
+ for(const file of ['UPSTREAM.json','PARITY.json']) {
+   let previous=JSON.parse(readFileSync(file,'utf8')).previousBaseline;
+   while(previous && previous.commit!==report.baseline.sha)previous=previous.previousBaseline;
+   assert.equal(previous?.commit,report.baseline.sha);
+ }
+ for(const task of receipt.tasks){const evidence=report.changes.find((c:any)=>c.id===task.taskId);assert.equal(task.newBlob,evidence.newBlob);assert.equal(task.semanticReview,'pending');assert.equal(task.behavioralEquivalence,'not_claimed');assert.ok(task.rationale);for(const file of task.localFiles)assert.ok(existsSync(file),file);}
+ const loaded=loadSkillsFromDir({dir:process.cwd()+'/skills',source:'path'});assert.deepEqual(loaded.diagnostics,[]);assert.ok(loaded.skills.some(s=>s.name==='in-your-own-words'));
+});

package/test/check-plan.test.ts

@@ -0,0 +1,99 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+// Retain upstream regression fixtures with Node assertions, without a Bun dependency.
+const expect=(value:any)=>({toBe:(expected:any)=>assert.equal(value,expected),toContain:(part:string)=>assert.ok(value.includes(part))});
+
+const checker = join(process.cwd(), "scripts", "check-plan.mjs");
+const rule =
+	"Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.";
+
+const validPlan = `# Demo
+
+## How to read this
+One box is one unit of work and names the evidence. Check a box only when its evidence exists. See playbooks/.
+${rule}
+
+## Program checklist
+### Arm the program
+### Spawn owners
+### PR mechanics
+### Verdict and merge
+### Boot recipe
+\`git show origin/main:\` /pstack-loop 1h status message
+
+## PR 1
+**Depends on.** None.
+**Files.**
+- [ ] Do the thing.
+**Build.**
+- [ ] Do the thing.
+**You see.**
+- [ ] Do the thing.
+**Verify, unit.** ${rule}
+- [ ] Check the thing.
+**Verify, live.** ${rule} Ten lanes on \`example-model\` at the PR head
+${Array.from({ length: 10 }, (_, i) => `- [ ] Lane ${i + 1}. Save \`lane-${i + 1}.png\`. Pass when evidence exists.`).join("\n")}
+**Verify, perf.** ${rule}
+- [ ] Metric. Recorded.
+- [ ] Probe. Recorded.
+- [ ] Baseline. Recorded.
+- [ ] Rule. Recorded.
+**Review gate.** None.
+**Merge.**
+- [ ] Merge when approved.
+
+## Close the program
+Close.
+
+## Appendix Prototype evidence
+Recorded.
+`;
+
+const runPlan = (example: string, expectedExit: number) => {
+	const directory = mkdtempSync(join(process.cwd(), ".check-plan-test-"));
+	const file = join(directory, "plan.md");
+	writeFileSync(file, validPlan + example);
+	try {
+		const result = spawnSync("node", [checker, file], { encoding: "utf8" });
+		expect(result.status).toBe(expectedExit);
+		return result;
+	} finally {
+		rmSync(directory, { recursive: true, force: true });
+	}
+};
+
+test("accepts ordinary, indented, and longer closing fences", () => {
+	for (const indent of ["", " ", "  ", "   "])
+		runPlan(`${indent}\`\`\`markdown\n## Example only\n${indent}\`\`\`\n`, 0);
+	runPlan("```markdown\n## Example only\n````\n", 0);
+});
+
+test("accepts nested backticks and tilde info strings", () => {
+	runPlan("````markdown\n```markdown\n## Example only\n```\n````\n", 0);
+	runPlan("~~~markdown `info`\n## Example only\n ~~~\n", 0);
+});
+
+test("keeps mismatched, shorter, and suffixed closers inside the fence", () => {
+	runPlan("````markdown\n~~~\n## Example only\n````\n", 0);
+	runPlan("````markdown\n```\n## Example only\n````\n", 0);
+	runPlan("````markdown\n``` info\n## Example only\n````\n", 0);
+});
+
+test("rejects headings and prose outside a proper close", () => {
+	for (const suffix of ["  ", "\t"]) {
+		const heading = runPlan(`\`\`\`markdown\n## Example only\n\`\`\`${suffix}\n## Example only\n`, 1);
+		expect(heading.stderr).toContain('"## Example only" after Close the program is not an appendix');
+	}
+
+	const prose = runPlan("```markdown\nThis prose has a mid-sentence colon: inside code\n```\nThis prose has a mid-sentence colon: bad.\n", 1);
+	expect(prose.stderr).toContain("mid-sentence colon");
+});
+
+test("rejects backtick info strings containing a backtick", () => {
+	const result = runPlan("```markdown `invalid`\n## Example only\n```\n", 1);
+	expect(result.stderr).toContain('"## Example only" after Close the program is not an appendix');
+});

package/test/checkout.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { checkoutIdentity, writerLockKey } from "../src/runtime/checkout.ts";
+
+test("checkout identity collapses nested paths and symlink aliases", () => {
+  const base = mkdtempSync(join(process.cwd(), ".pstack-checkout-"));
+  const repo = join(base, "repo");
+  mkdirSync(repo);
+  mkdirSync(join(repo, "sub"));
+  symlinkSync(repo, join(base, "alias"), "dir");
+  try {
+    execFileSync("git", ["init", "-q", repo]);
+    assert.equal(checkoutIdentity(join(base, "alias", "sub")), checkoutIdentity(repo));
+    assert.equal(writerLockKey(join(repo, "sub")), writerLockKey(repo));
+  } finally { rmSync(base, { recursive: true, force: true }); }
+});