pi-pstack-native 0.0.0-stage → 1.0.1

package/scripts/check-plan.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// Adapted from cursor/plugins pstack 99b609a72323b70204eab407c622f436e858e112 (MIT; see NOTICE.md).
+import fs from "node:fs";
+import process from "node:process";
+
+const RULE =
+	"Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.";
+const LANES = /Ten lanes on `[^`<>]+` at the PR head/;
+const SUB_BLOCKS = [
+	"Depends on.",
+	"Files.",
+	"Build.",
+	"You see.",
+	"Verify, unit.",
+	"Verify, live.",
+	"Verify, perf.",
+	"Review gate.",
+	"Merge.",
+];
+const PROGRAM_H3 = ["Arm the program", "Spawn owners", "PR mechanics", "Verdict and merge", "Boot recipe"];
+const PROGRAM_MARKERS = ["git show origin/main:", "/pstack-loop 1h", "status message"];
+const HOW_TO_READ_MARKERS = [
+	"One box is one unit of work",
+	"names the evidence",
+	"Check a box only when its evidence exists",
+	"playbooks/",
+	RULE,
+];
+const PERF_ITEMS = ["Metric.", "Probe.", "Baseline.", "Rule."];
+const BOX = /^\s*- \[[ x]\] (.*)$/;
+
+const file = process.argv[2];
+if (!file) {
+	console.error("Usage: node check-plan.mjs <plan.md>");
+	process.exit(2);
+}
+
+const raw = fs.readFileSync(file, "utf8").split(/\r?\n/);
+const problems = [];
+const fail = (line, message) => problems.push(`${file}:${line}: ${message}`);
+
+let start = 0;
+if (raw[0] === "---") {
+	start = raw.indexOf("---", 1) + 1;
+}
+
+const lines = [];
+let fence = null;
+const openingFence = (text) => {
+	const match = text.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+	if (!match || (match[1][0] === "`" && match[2].includes("`"))) return null;
+	return { char: match[1][0], length: match[1].length };
+};
+const closingFence = (text, opening) => {
+	const match = text.match(/^ {0,3}(`+|~+)[ \t]*$/);
+	return Boolean(
+		match &&
+		match[1][0] === opening.char &&
+		match[1].length >= opening.length,
+	);
+};
+for (let i = start; i < raw.length; i++) {
+	const text = raw[i];
+	const n = i + 1;
+	let code = Boolean(fence);
+	if (fence && closingFence(text, fence)) {
+		code = false;
+		fence = null;
+	} else if (!fence) {
+		fence = openingFence(text);
+		code = Boolean(fence);
+	}
+	lines.push({ n, text, code });
+	if (code) continue;
+	const prose = text
+		.replace(/(?<!`)(`+)(?!`)(.*?)(?<!`)\1(?!`)/g, "`")
+		.replace(/!\[[^\]]*\]\([^)]*\)/g, "")
+		.replace(/\]\([^)]*\)/g, "]");
+	if (/[\u2013\u2014]/.test(prose)) fail(n, "long dash");
+	if (/[\u2018\u2019\u201c\u201d]/.test(prose)) fail(n, "curly quote");
+	if (/: \S/.test(prose)) fail(n, "mid-sentence colon");
+}
+
+const h2 = (l) => (!l.code && l.text.startsWith("## ") ? l.text.slice(3).trim() : null);
+const sections = [];
+for (const l of lines) {
+	const title = h2(l);
+	if (title !== null) sections.push({ title, n: l.n, body: [] });
+	else if (sections.length) sections.at(-1).body.push(l);
+}
+const find = (title) => sections.find((s) => s.title === title);
+const bodyText = (s) => s.body.map((l) => l.text).join("\n");
+const boxes = (ls) => ls.filter((l) => !l.code && BOX.test(l.text)).map((l) => ({ n: l.n, text: l.text.match(BOX)[1] }));
+
+const h1 = lines.findIndex((l) => !l.code && l.text.startsWith("# "));
+if (h1 === -1) fail(1, "no H1 title");
+const howToRead = find("How to read this");
+if (!howToRead) fail(1, 'no "## How to read this" section');
+if (h1 !== -1 && howToRead) {
+	const intro = lines.slice(h1 + 1).filter((l) => l.n < howToRead.n && l.text.trim() !== "");
+	if (intro.length >= 10) fail(lines[h1].n, `intro is ${intro.length} lines, under ten required`);
+	for (const marker of HOW_TO_READ_MARKERS) {
+		if (!bodyText(howToRead).includes(marker)) fail(howToRead.n, `How to read this lacks "${marker}"`);
+	}
+}
+
+const program = find("Program checklist");
+if (!program) fail(1, 'no "## Program checklist" section');
+else {
+	const h3s = program.body.filter((l) => !l.code && l.text.startsWith("### ")).map((l) => l.text.slice(4).trim());
+	let cursor = 0;
+	for (const name of PROGRAM_H3) {
+		const at = h3s.findIndex((t, i) => i >= cursor && t.startsWith(name));
+		if (at === -1) fail(program.n, `Program checklist lacks "### ${name}" in order`);
+		else cursor = at + 1;
+	}
+	for (const marker of PROGRAM_MARKERS) {
+		if (!bodyText(program).includes(marker)) fail(program.n, `Program checklist lacks "${marker}"`);
+	}
+}
+
+const close = find("Close the program");
+if (!close) fail(1, 'no "## Close the program" section');
+const programIndex = sections.indexOf(program);
+const closeIndex = sections.indexOf(close);
+const prSections = programIndex === -1 || closeIndex === -1 ? [] : sections.slice(programIndex + 1, closeIndex);
+if (prSections.length === 0) fail(1, "no PR sections between Program checklist and Close the program");
+
+const report = [];
+for (const pr of prSections) {
+	const heads = [];
+	for (const l of pr.body) {
+		if (l.code) continue;
+		const m = l.text.match(/^\*\*([^*]+)\*\*(.*)$/);
+		if (m && SUB_BLOCKS.includes(m[1])) heads.push({ name: m[1], n: l.n, rest: m[2].trim(), lines: [] });
+		else if (heads.length) heads.at(-1).lines.push(l);
+	}
+	const names = heads.map((h) => h.name);
+	if (names.join("|") !== SUB_BLOCKS.join("|")) {
+		fail(pr.n, `${pr.title}: sub-blocks are [${names.join(", ")}], expected [${SUB_BLOCKS.join(", ")}]`);
+	}
+	const block = (name) => heads.find((h) => h.name === name);
+	const counts = {};
+	for (const h of heads) counts[h.name] = boxes(h.lines).length;
+
+	const depends = block("Depends on.");
+	if (depends && depends.rest === "") fail(depends.n, `${pr.title}: Depends on names nothing`);
+	for (const name of ["Files.", "Build.", "You see.", "Verify, unit.", "Merge."]) {
+		const b = block(name);
+		if (b && boxes(b.lines).length === 0) fail(b.n, `${pr.title}: ${name} has no box`);
+	}
+	for (const name of ["Verify, unit.", "Verify, live.", "Verify, perf."]) {
+		const b = block(name);
+		if (b && !b.rest.startsWith(RULE)) fail(b.n, `${pr.title}: ${name} does not open with the rule`);
+	}
+
+	const live = block("Verify, live.");
+	if (live) {
+		if (!LANES.test(live.rest)) fail(live.n, `${pr.title}: Verify, live lacks "Ten lanes on \`<swarm workers model>\` at the PR head" with the model filled in`);
+		const lanes = boxes(live.lines).map((b) => ({ ...b, m: b.text.match(/^Lane (\d+)\. /) }));
+		const numbers = lanes.filter((b) => b.m).map((b) => Number(b.m[1])).sort((a, b) => a - b);
+		if (numbers.join(",") !== "1,2,3,4,5,6,7,8,9,10") fail(live.n, `${pr.title}: lanes are [${numbers.join(",")}], expected 1 to 10`);
+		for (const lane of lanes) {
+			if (!lane.m) fail(lane.n, `${pr.title}: live box is not a lane`);
+			else if (!/Save `[^`]+`/.test(lane.text)) fail(lane.n, `${pr.title}: lane ${lane.m[1]} names no screenshot`);
+			else if (!lane.text.includes("Pass when")) fail(lane.n, `${pr.title}: lane ${lane.m[1]} has no pass predicate`);
+		}
+	}
+
+	const perf = block("Verify, perf.");
+	if (perf) {
+		const items = boxes(perf.lines).map((b) => b.text.split(" ")[0]);
+		if (items.join("|") !== PERF_ITEMS.join("|")) fail(perf.n, `${pr.title}: perf boxes are [${items.join(", ")}], expected [${PERF_ITEMS.join(", ")}]`);
+	}
+
+	const gate = block("Review gate.");
+	if (gate) {
+		const gateBoxes = boxes(gate.lines);
+		if (gate.rest.startsWith("None.")) {
+			if (gateBoxes.length) fail(gate.n, `${pr.title}: Review gate says None but has boxes`);
+		} else {
+			const text = gate.lines.map((l) => l.text).join("\n");
+			if (gateBoxes.length === 0) fail(gate.n, `${pr.title}: Review gate has no box`);
+			for (const word of ["screenshot", "video", "operator"]) {
+				if (!text.includes(word)) fail(gate.n, `${pr.title}: Review gate lacks "${word}"`);
+			}
+		}
+	}
+
+	const total = boxes(pr.body).length;
+	const cells = SUB_BLOCKS.filter((s) => s !== "Depends on.").map((s) => `${s.replace(/[ ,.]+/g, "-").replace(/-$/, "").toLowerCase()}=${counts[s] ?? 0}`);
+	report.push(`${pr.title}  boxes=${total}  ${cells.join(" ")}`);
+}
+
+if (closeIndex !== -1) {
+	const tail = sections.slice(closeIndex + 1);
+	for (const s of tail) {
+		if (!s.title.startsWith("Appendix")) fail(s.n, `"## ${s.title}" after Close the program is not an appendix`);
+	}
+	if (!tail.some((s) => s.title.includes("Prototype evidence"))) fail(close.n, 'no "## Appendix ... Prototype evidence" section');
+}
+
+for (const line of report) console.log(line);
+console.log(`${prSections.length} PR sections, ${problems.length} problems`);
+for (const p of problems) console.error(p);
+process.exit(problems.length ? 1 : 0);

package/scripts/check-records.mjs

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { writeConfined } from './upstream/core.mjs';
+import { buildRecords, recordsPath, validateRecords } from './upstream/records.mjs';
+
+const serialize = document => `${JSON.stringify(document, null, 2)}\n`;
+
+export function checkRecords(root) {
+  if (!existsSync(join(root, recordsPath))) throw new Error(`RECORDS_MISSING in ${recordsPath}; run npm run registry:records`);
+  validateRecords(JSON.parse(readFileSync(join(root, recordsPath), 'utf8')), { root });
+  const fresh = validateRecords(buildRecords({ root }), { root });
+  if (readFileSync(join(root, recordsPath), 'utf8') !== serialize(fresh)) throw new Error(`RECORDS_Drift in ${recordsPath}; run npm run registry:records`);
+  return fresh;
+}
+function writeRecords(root) {
+  const fresh = validateRecords(buildRecords({ root }), { root });
+  writeConfined(root, recordsPath, serialize(fresh));
+  return fresh;
+}
+if (import.meta.url === pathToFileURL(resolve(process.argv[1] ?? '')).href) {
+  const root = process.cwd();
+  try {
+    if (process.argv.includes('--write')) {
+      const document = writeRecords(root);
+      console.log(JSON.stringify({ status: 'written', path: recordsPath, records: document.records.length }));
+    } else {
+      const document = checkRecords(root);
+      console.log(JSON.stringify({ status: 'in-sync', path: recordsPath, records: document.records.length }));
+    }
+  } catch (error) {
+    console.error('Records check failed: ' + error.message);
+    process.exitCode = 1;
+  }
+}

package/scripts/check-semantics.mjs

@@ -0,0 +1,7 @@
+import { checkSemantics, drift } from './semantics/core.mjs';
+const args=process.argv.slice(2);
+if(args.length) {
+  if(args.length!==4 || args[0]!=='--from' || args[2]!=='--commit')throw new Error('usage: check-semantics.mjs [--from upstream-git-repository --commit full-sha]');
+  const report=drift(process.cwd(),args[1],args[3]);console.log(JSON.stringify(report,null,2));
+  if(report.status==='needs-review')process.exitCode=3;
+} else console.log(JSON.stringify(checkSemantics(process.cwd()),null,2));

package/scripts/check-statechart.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// The pinned upstream TypeScript suite skips its live-TLC lanes when TLA2TOOLS
+// is absent. Do not convert those skips into a claim of real model checking.
+const root = resolve('skills/statechart/scripts/test');
+const files = readdirSync(root).filter(name => name.endsWith('.test.ts')).sort().map(name => resolve(root, name));
+const args = ['--disable-warning=ExperimentalWarning', '--test', '--test-timeout=120000', ...process.argv.slice(2), ...files];
+const result = spawnSync(process.execPath, args, { cwd: process.cwd(), stdio: 'inherit', env: process.env });
+if (result.error) throw result.error;
+process.exitCode = result.status ?? 1;

package/scripts/check-syntax.mjs

@@ -0,0 +1,9 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+const roots=["src","test","scripts"];
+const files=[];
+function walk(p){ for(const n of readdirSync(p)){ const f=join(p,n),s=statSync(f); if(s.isDirectory()) walk(f); else if(/\.(ts|mjs)$/.test(n)) files.push(f); } }
+for(const root of roots) walk(root);
+for(const file of files){ const args=file.endsWith('.ts')?["--experimental-strip-types","--check",file]:["--check",file]; const r=spawnSync(process.execPath,args,{encoding:"utf8"}); if(r.status!==0){ process.stderr.write(r.stderr||r.stdout); throw new Error(`syntax check failed: ${file}`); } }
+console.log(`syntax ok: ${files.length} files`);

package/scripts/check-windows-build.mjs

@@ -0,0 +1,12 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+for (const path of ['dist/agent/grep-worker.mjs', 'dist/verification/process.mjs', 'dist/runner/cli.mjs']) {
+  if (!existsSync(path)) throw new Error(`Missing built file: ${path}`);
+}
+for (const path of ['src/agent/grep-worker.mj', 'src/verification/process.mj', 'src/runner/cli.mj']) {
+  if (existsSync(path)) throw new Error(`Build created an unexpected source path: ${path}`);
+}
+if (/\.ts['"]/.test(readFileSync('dist/runner/cli.mjs', 'utf8'))) throw new Error('Built CLI still imports TypeScript');
+const cli = spawnSync(process.execPath, ['dist/runner/cli.mjs'], { encoding: 'utf8' });
+if (cli.status !== 1 || !cli.stderr.includes('Usage: pstack-runner')) throw new Error(`CLI failed to load: ${cli.stderr}`);
+console.log('Windows build artifacts and CLI import: PASS');

package/scripts/e2e-live.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const index = argv.indexOf(`--${name}`);
+  return index === -1 ? undefined : argv[index + 1];
+};
+const repo = flag("repo");
+const confirm = flag("confirm");
+const base = flag("base") ?? "main";
+const pr = flag("pr");
+const clone = flag("clone") ? resolve(flag("clone")) : undefined;
+const merge = argv.includes("--merge");
+const write = argv.includes("--write") || merge;
+const home = flag("home") ? resolve(flag("home")) : mkdtempSync(join(tmpdir(), "pstack-e2e-live-"));
+
+if (!repo || !confirm) {
+  process.stderr.write("usage: node --experimental-strip-types scripts/e2e-live.mjs --repo owner/name --confirm owner/name [--base main] [--pr 12] [--clone /path --write] [--merge] [--home /path]\n");
+  process.exit(2);
+}
+if (repo !== confirm) {
+  process.stderr.write(`refusing to run: --confirm must repeat --repo exactly (${repo})\n`);
+  process.exit(2);
+}
+if (write && !clone) {
+  process.stderr.write("refusing to run: --write requires an explicit --clone of the named repository\n");
+  process.exit(2);
+}
+mkdirSync(home, { recursive: true });
+const auth = spawnSync("gh", ["auth", "status"], { encoding: "utf8" });
+if (auth.status !== 0) {
+  process.stderr.write(`refusing to run: gh is not authenticated\n${auth.stderr || auth.stdout}`);
+  process.exit(2);
+}
+
+const env = {
+  ...process.env,
+  PSTACK_E2E_LIVE: "1",
+  PSTACK_E2E_LIVE_REPO: repo,
+  PSTACK_E2E_LIVE_CONFIRM: confirm,
+  PSTACK_E2E_LIVE_BASE: base,
+  PSTACK_E2E_LIVE_WRITE: write ? "1" : "0",
+  PSTACK_E2E_LIVE_MERGE: merge ? "1" : "0",
+  PSTACK_NATIVE_HOME: home,
+  ...(pr ? { PSTACK_E2E_LIVE_PR: pr } : {}),
+  ...(clone ? { PSTACK_E2E_LIVE_CLONE: clone } : {}),
+};
+delete env.NODE_TEST_CONTEXT;
+delete env.NODE_TEST_WORKER_ID;
+
+process.stdout.write(`live tier target ${repo} base ${base} write ${write} merge ${merge} home ${home}\n`);
+const run = spawnSync(process.execPath, ["--experimental-strip-types", "--test", join("test", "live", "github-live.test.ts")], { cwd: process.cwd(), env, stdio: "inherit" });
+process.stdout.write(`\nlive tier exit ${run.status}\ncleanup: close any pull request opened by this run, delete its branch, then remove ${write ? "the probe commit in " + clone + " and " : ""}${home}\n`);
+process.exit(run.status ?? 1);

package/scripts/e2e-reporter.mjs

@@ -0,0 +1,17 @@
+/**
+ * Emits one JSON line per top level test result to the file named by E2E_EVENTS, so the caller can
+ * bind each result to the file that actually ran it instead of inferring ownership from source text.
+ */
+export default async function* reporter(source) {
+  const { appendFileSync } = await import('node:fs');
+  const target = process.env.E2E_EVENTS;
+  for await (const event of source) {
+    if (event.type !== 'test:pass' && event.type !== 'test:fail') continue;
+    const data = event.data ?? {};
+    if (data.nesting !== 0 || !data.file) continue;
+    if (data.name === data.file || data.name === data.file.split('/').pop()) continue;
+    if (target) {
+      appendFileSync(target, `${JSON.stringify({ status: event.type === 'test:pass' ? 'pass' : 'fail', name: data.name, file: data.file, todo: Boolean(data.todo), skip: Boolean(data.skip) })}\n`);
+    }
+  }
+}

package/scripts/review.mjs

@@ -0,0 +1,26 @@
+// This script deliberately avoids claiming that source-string matches prove
+// runtime correctness. Behavioral verification lives in npm test / host smoke.
+import { readFileSync, writeFileSync } from "node:fs";
+const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+const known = [
+  "The real SDK lifecycle test uses a loopback protocol fixture for completion, HTTP 401, cancellation, and recovery; it does not perform authenticated external LLM inference.",
+  "A cross-process cancellation request is cooperative, not a preemptive OS sandbox. While cancellation is unconfirmed the state remains `cancelling`, and any already running external side effect may finish.",
+  "Path-constrained read tools are not an operating-system sandbox: hard links, external extension side effects, and malicious filesystem races require OS-level isolation for untrusted agents.",
+  "Regex execution is bounded with a killable worker; matching large repositories may time out rather than returning partial results.",
+  "User-owned or agent-owned remote side effects cannot be made exactly-once solely by a local workflow journal.",
+  "Loop occurrences are claimed before send for at-most-once dispatch attempts; a Pi host crash between the durable claim and accepted delivery can lose that occurrence. Disabling or deleting a loop cannot recall a message already submitted to Pi.",
+  "Loop execution locks coordinate cooperating Pi processes and remain held through sendUserMessage settlement; lock-file storage must be on a filesystem with atomic exclusive file creation and rename semantics.",
+  "Minimum supported Node is >=22.19.0; verification from an older local runtime must be repeated on an officially supported runtime.",
+  "Project integrators remain probabilistic AI systems and need evidence-driven integration and test verification."
+];
+const md = `# v${pkg.version} review & validation\n\n` +
+  `## Verified by the default local check\n\n` +
+  `- JS/TS syntax checks and package/parity policy checks\n` +
+  `- Unit and subprocess behavioral tests (not actual Pi inference)\n\n` +
+  `## Additional release gates\n\n` +
+  "- `npm run check:types` (needs installed Pi peer and TypeScript development dependencies)\n" +
+  "- Real Pi AgentSession lifecycle integration and final installed-tarball load smoke\n" +
+  "- Authenticated external LLM inference remains a separate gate when authorized credentials are available\n\n" +
+  `## Residual risks\n\n${known.map((item) => `- ${item}`).join("\n")}\n`;
+writeFileSync("REVIEW.md", md);
+console.log(`Review metadata updated for ${pkg.version}; runtime truth is established by tests, not matching source snippets.`);

package/scripts/semantics/core.mjs

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CORE_RESOURCES, CAPABILITIES } from '../../src/compatibility/adapter.ts';
+import { generateCore, generatedResources } from './generate.mjs';
+export const REVIEWED_FILES = ["src/compatibility/adapter.ts", "src/compatibility/source.ts", "src/compatibility/tool.ts", "src/agent/resources.ts", "src/extension.ts", "src/agent/profiles.ts", "src/agent/host.ts", "src/models/router.ts", "src/runtime/config.ts", "src/runtime/lock.ts", "src/contracts/brief.ts", "src/contracts/types.ts", "src/runtime/types.ts", "src/templates/build.ts", "src/workflow/engine.ts", "src/workflow/artifacts.ts", "src/verification/runner.ts", "src/delivery/frontier.ts", "docs/PI-SEMANTIC-ADAPTER.md", "scripts/upstream/cli.mjs", "scripts/check-semantics.mjs", "scripts/benchmark.mjs", "scripts/check-benchmark.mjs", "scripts/semantics/core.mjs", "scripts/semantics/generate.mjs", "test/semantic-compatibility.test.ts", "test/fixtures/semantics/scenarios.json", "scripts/semantics/real-pi-smoke.mjs", "test/e2e/workflow.test.ts", "test/e2e/shipping.test.ts", "test/protocol.test.ts", "test/verification.test.ts", "test/latest-upstream.test.ts", "test/statechart.test.ts", "test/model-router.test.ts", "test/setup-command.test.ts", "test/transaction.test.ts", "test/benchmark.test.ts", "scripts/check-statechart.mjs"];
+REVIEWED_FILES.push('src/tools/agents.ts', 'src/tools/workflow.ts', 'src/agent/candidates.ts', 'src/worktree/snapshot.ts', 'test/model-panels.test.ts', 'test/review-snapshot.test.ts', 'test/swarm-race.test.ts', 'test/e2e/harness.ts', 'test/e2e/parent-context.ts', 'scripts/check-e2e.mjs', 'scripts/build.mjs', 'scripts/build-statechart.mjs');
+REVIEWED_FILES.push('src/setup/command.ts', 'test/setup-rpc.test.ts');
+export const digest = value => createHash('sha256').update(value).digest('hex');
+export const blob = bytes => createHash('sha1').update(`blob ${Buffer.byteLength(bytes)}\0`).update(bytes).digest('hex');
+export function units(body) {
+  const lines=body.split('\n'), starts=[];
+  lines.forEach((line,i)=>{if(/^#{1,6} |^\d+\. /.test(line))starts.push(i);});
+  if(starts[0]!==0)starts.unshift(0);
+  return starts.map((start,i)=>({id:`L${start+1}`,start:start+1,end:starts[i+1]??lines.length,label:lines[start],hash:digest(lines.slice(start,starts[i+1]??lines.length).join('\n'))}));
+}
+export function checkSemantics(root, document=JSON.parse(readFileSync(join(root,'SEMANTICS.json'),'utf8'))) {
+  const read=path=>{
+    if(typeof path!=='string' || path.startsWith('/') || path.split('/').some(p=>!p || p==='.' || p==='..'))throw new Error('SEMANTIC_PATH_INVALID');
+    let file=root;for(const part of path.split('/')){file=join(file,part);if(lstatSync(file).isSymbolicLink())throw new Error('SEMANTIC_SYMLINK_REFUSED');}
+    return readFileSync(file);
+  };
+  const upstream=JSON.parse(read('UPSTREAM.json'));
+  if(document.schemaVersion!==1 || document.snapshot.commit!==upstream.commit || document.snapshot.version!==upstream.version)throw new Error('SEMANTIC_BASELINE_MISMATCH');
+  if(document.baselineAdvancement!=='requires-explicit-semantic-signoff' || !['pending-maintainer-signoff','signed-off'].includes(document.review.status))throw new Error('SEMANTIC_SIGNOFF_REQUIRED');
+  if(document.review.status==='signed-off' && (!document.review.reviewer || !document.review.rationale || !document.review.at))throw new Error('SEMANTIC_SIGNOFF_REQUIRED');
+  const names=document.workflows.map(w=>w.resource).sort();
+  if(JSON.stringify(names)!==JSON.stringify([...CORE_RESOURCES].sort()))throw new Error('SEMANTIC_CORE_COVERAGE_MISMATCH');
+  if(JSON.stringify(Object.keys(document.reviewedFiles).sort())!==JSON.stringify([...REVIEWED_FILES].sort()))throw new Error('SEMANTIC_REVIEW_SCOPE_MISMATCH');
+  const files=new Map();
+  for(const file of document.snapshot.files) {
+    if(files.has(file.path))throw new Error('SEMANTIC_DUPLICATE_SOURCE');
+    const bytes=read(`${document.snapshot.root}/${file.path}`);
+    if(blob(bytes)!==file.sha || bytes.length!==file.size)throw new Error(`SEMANTIC_SOURCE_DRIFT: ${file.path}`);
+    files.set(file.path,bytes.toString('utf8'));
+  }
+  if(!files.has('pstack/LICENSE'))throw new Error('SEMANTIC_LICENSE_MISSING');
+  for(const [path,hash] of Object.entries(document.reviewedFiles))if(digest(read(path))!==hash)throw new Error(`SEMANTIC_REVIEW_REQUIRED: ${path}`);
+  if(JSON.stringify(document.capabilities)!==JSON.stringify(CAPABILITIES))throw new Error('SEMANTIC_CAPABILITY_DRIFT');
+  if(!Array.isArray(document.overrides) || JSON.stringify(document.overrides.map(o=>o.name).sort())!==JSON.stringify(Object.keys(CAPABILITIES).sort()))throw new Error('SEMANTIC_OVERRIDE_COVERAGE');
+  for(const override of document.overrides) {
+    const capability=CAPABILITIES[override.name];
+    if(override.status!==capability.status || override.mapping!==capability.mapping || override.rationale!==capability.reason || !override.scope || !override.tests?.length)throw new Error('SEMANTIC_OVERRIDE_INVALID');
+    const source=files.get(override.upstream?.path),span=override.upstream;
+    if(!source || !Number.isInteger(span.start) || !Number.isInteger(span.end) || span.start<1 || span.end<span.start)throw new Error('SEMANTIC_OVERRIDE_SOURCE');
+    const slice=source.split('\n').slice(span.start-1,span.end).join('\n');
+    if(!slice.includes(span.quote) || digest(slice)!==span.hash)throw new Error('SEMANTIC_OVERRIDE_SOURCE');
+    for(const test of override.tests)if(!document.reviewedFiles[test.file] || !read(test.file).toString().includes(test.name))throw new Error('SEMANTIC_OVERRIDE_TEST');
+  }
+
+  const ids=new Set();
+  const statuses=['equivalent','adapted-with-deviation','unsupported','not-yet-verified'];
+  for(const workflow of document.workflows) {
+    const source=`pstack/skills/${workflow.resource}`, body=files.get(source);
+    if(!body || workflow.coverage!=='critical-rules-only' || workflow.fullBehavioralParity!=='not-claimed')throw new Error('SEMANTIC_SCOPE_INVALID');
+    if(JSON.stringify(workflow.units)!==JSON.stringify(units(body)))throw new Error(`SEMANTIC_STEP_DRIFT: ${source}`);
+    if(!workflow.rules.length)throw new Error('SEMANTIC_RULES_MISSING');
+    for(const rule of workflow.rules) {
+      if(ids.has(rule.id) || !rule.id || !statuses.includes(rule.status) || !rule.mapping || !rule.rationale || !rule.scope || !rule.tests?.length)throw new Error('SEMANTIC_RULE_INVALID');
+      ids.add(rule.id);
+      const slice=body.split('\n').slice(rule.upstream.start-1,rule.upstream.end).join('\n');
+      if(rule.upstream.path!==source || rule.upstream.start<1 || rule.upstream.end<rule.upstream.start || !slice.includes(rule.upstream.quote) || digest(slice)!==rule.upstream.hash)throw new Error(`SEMANTIC_RULE_SOURCE_DRIFT: ${rule.id}`);
+      for(const ref of rule.tests){
+        if(!document.reviewedFiles[ref.file] || !read(ref.file).toString().includes(ref.name))throw new Error(`SEMANTIC_TEST_UNBOUND: ${rule.id}`);
+      }
+    }
+  }
+  for(const cap of Object.values(document.capabilities))if(!cap.reason || !cap.mapping || !statuses.includes(cap.status))throw new Error('SEMANTIC_OVERRIDE_INVALID');
+  if(JSON.stringify(document.generatedResources)!==JSON.stringify(generatedResources(root)))throw new Error('SEMANTIC_GENERATED_SCOPE_DRIFT');
+  generateCore(root);
+  return {generatedEntrypoints:document.generatedResources.length,workflows:names.length,rules:ids.size,sourceFiles:files.size,fullBehavioralParity:'not-claimed',realModel:document.evidence.realModel};
+}
+/** Candidate contents are read from Git objects, never from a possibly dirty working tree. */
+export function drift(root, repository, commit) {
+  if(!/^[a-f0-9]{40}$/.test(commit))throw new Error('FULL_CANDIDATE_COMMIT_REQUIRED');
+  const document=JSON.parse(readFileSync(join(root,'SEMANTICS.json'),'utf8'));
+  checkSemantics(root,document);
+  const git=args=>execFileSync('git',['-C',repository,...args],{encoding:'utf8',maxBuffer:16*1024*1024});
+  if(git(['rev-parse',`${commit}^{commit}`]).trim()!==commit)throw new Error('CANDIDATE_COMMIT_MISMATCH');
+  const paths=git(['ls-tree','-r','--name-only',commit,'--','pstack/skills']).trim().split('\n');
+  const parity=JSON.parse(readFileSync(join(root,'PARITY.json'),'utf8'));
+  const inventory=JSON.parse(readFileSync(join(root,parity.coverage.targetInventory),'utf8'));
+  const testCorpus=new Map(inventory.blobs.filter(b=>b.path.startsWith('skills/statechart/scripts/test/')).map(b=>[`pstack/${b.path}`,{path:`pstack/${b.path}`,sha:b.blob}]));
+  const relevant=p=>p.startsWith('pstack/skills/statechart/scripts/') || document.overrides.some(o=>o.upstream.path===p) || document.workflows.some(w=>p===`pstack/skills/${w.resource}`) || /^pstack\/skills\/(architect|interrogate|poteto-mode)\/references\/.*\.md$/.test(p);
+  const all=new Set([...document.snapshot.files.map(f=>f.path),...testCorpus.keys(),...paths.filter(p=>p.endsWith('.md') || p.startsWith('pstack/skills/statechart/scripts/'))]);
+  const changes=[];
+  for(const path of [...all].sort()) {
+    if(!path.startsWith('pstack/skills/'))continue;
+    const entry=document.snapshot.files.find(f=>f.path===path) ?? testCorpus.get(path);
+    const after=paths.includes(path)?git(['show',`${commit}:${path}`]):null;
+    if(entry?.sha=== (after===null?null:blob(after)))continue;
+    if(!entry && after===null)continue;
+    const before=entry?readFileSync(testCorpus.has(path) ? join(root,path.slice('pstack/'.length)) : join(root,document.snapshot.root,path),'utf8'):null;
+    if (entry && blob(before)!==entry.sha) throw new Error(`SEMANTIC_SOURCE_DRIFT: ${path}`);
+    const beforeBlob=entry?.sha??null,afterBlob=after===null?null:blob(after);
+    const review=document.driftReviews.find(r=>r.commit===commit && r.path===path && r.before===beforeBlob && r.after===afterBlob && r.status==='signed-off' && r.reviewer && r.rationale && r.tests?.length && r.tests.every(t=>document.reviewedFiles[t]));
+    changes.push({path,relevant:relevant(path),reviewed:Boolean(review),before:beforeBlob,after:afterBlob,beforeSteps:before===null?[]:units(before),afterSteps:after===null?[]:units(after),diff:after===before?'':{before,after}});
+  }
+  return {candidate:commit,baseline:document.snapshot.commit,status:changes.some(c=>c.relevant&&!c.reviewed)?'needs-review':'reviewed-or-irrelevant',changes};
+}

package/scripts/semantics/generate.mjs

@@ -0,0 +1,47 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CORE_RESOURCES } from '../../src/compatibility/adapter.ts';
+export function renderCore(root, resource) {
+  const metadata=JSON.parse(readFileSync(join(root,'SEMANTICS.json'),'utf8')).snapshot;
+  const original=readFileSync(join(root,metadata.root,'pstack/skills',resource),'utf8');
+  const adapter=readFileSync(join(root,'docs/PI-SEMANTIC-ADAPTER.md'),'utf8');
+  const skill=resource.endsWith('/SKILL.md');
+  const front=skill ? original.match(/^---\n[\s\S]*?\n---\n/)[0] : '';
+  const body=original.slice(front.length);
+  const piFront=front.replace(/^name:.*$/m,`name: ${resource.split('/')[0]}`);
+  const questions = resource === 'automate-me/SKILL.md' ? '\n## Pi question interaction\n\nCursor `AskQuestion` is not a Pi tool supplied by this package. Ask in chat using clearly described options and let the user reply in their own words. For multiple selections, explicitly invite any combination; do not claim a multi-select UI was shown. Preserve the user’s answers before proceeding.\n' : resource === 'poteto-help/SKILL.md' ? '\n## Pi question and setup interaction\n\nAsk clarification questions in chat with clearly described options and accept a free-form answer; do not assume Cursor `AskQuestion` is available. Direct users to Pi’s `/setup-pstack` for reasoning budgets, role models and model panels. It maps the budget to Pi reasoning levels rather than rewriting Cursor model slugs. The command suggests optional verification Skills; model support varies.\n' : resource === 'setup-pstack/SKILL.md' ? '\n## Pi setup interaction\n\nUse the native `/setup-pstack` command. Review its suggested role models, task overrides and panels, and edit only choices that need changing. Existing settings are preserved. Panel seats may repeat or inherit the parent; repeated models do not provide model diversity. Budget presets set Pi thinkingLevel rather than rewriting Cursor model slugs. The command mentions optional verification Skills; do not claim they ran unless invoked.\n' : '';
+  const panelNames = { 'arena/SKILL.md': 'arena', 'architect/SKILL.md': 'architect', 'interrogate/SKILL.md': 'interrogate' };
+  const panelName = panelNames[resource];
+  const panelGuide = panelName ? '\n## Pi panel execution\n\nUse `/setup-pstack` to review or change the ' + panelName + ' panel. Unconfigured panels use disclosed session-available suggestions. Use `pstack_semantics` with action `panel` and name `' + panelName + '` to resolve the configured seats against the model registry; this does not check authentication or run inference. Then use `pstack_workflow` with template.kind `' + panelName + '`; it loads those seats automatically. Create the strict brief and, for arena/architect, a rubric. Plan first and inspect the resulting models. A plan or preflight does not mean execution ran. Arena/architect use one read-only cross-judge when an eligible different-family model is available. When skipped, inspect and select candidates yourself. Interrogate uses isolated adversaries and separate repro sessions; inspect their real command evidence.\n' : '';
+  const engineeringOverlay = resource === 'poteto-mode/SKILL.md' ? `
+## Pi engineering checkpoints for code-changing tasks
+
+The coordinator applies these checkpoints within the selected pstack playbook; they are not extra agents, DAG nodes, or mandatory external tools. Pass applicable checkpoints and evidence requirements into each writing subagent's task brief.
+
+1. **First make it work.** Define observable success and the data shape. For a bug, reproduce the failure and, when practical, run a test that fails for the expected reason before editing. If that is impractical, explain why and use the closest useful executable check. Make the smallest evidence-backed change and verify its behavior.
+2. **Then make it right.** Fix the root cause; subtract needless branches and abstractions before adding new ones. Check domain types, boundaries, and shared state. Preserve proven behavior through refactoring and rerun relevant checks. Use authorized complexity, duplication, or mutation tools when available and justified; do not assume they exist or silently install them.
+3. **Practice.** Work in small verifiable units. Record significant decisions, commands, and evidence references. Clean only owned, safe worktrees. Respect existing authorization for commits and remote operations.
+
+**Failed premise:** If two fixes sharing an assumption fail the same gate, write down and test that assumption before trying a third fix based on it.
+
+**Completion:** Verify the integrated artifact after parallel writers converge. Distinguish behavioral evidence, design review, and agent reports; disclose skipped, blocked, or inconclusive checks. The existing task contract, verification policy, fingerprints, and evidence ledger remain authoritative; this guidance does not itself make a gate pass.
+
+Skip these code-change checkpoints for read-only investigations or prose-only tasks.
+` : '';
+  const prelude=`\n<!-- Generated by scripts/semantics/generate.mjs; edit the source mapping/adapter, not this file. -->\n\n${adapter}\n${questions}${panelGuide}${engineeringOverlay}\n---\n\n## Pinned upstream instructions\n\nSource: cursor/plugins@${metadata.commit}, pstack/skills/${resource}. The following body is retained verbatim.\n\n`;
+  const runtime='\n\n## Pi execution tools\n\nUse `pstack_agents` for one child and `pstack_workflow` / `pstack_graph` for an explicit DAG. Roles are `architect`, `worker`, `reviewer`, `verifier`, `synthesizer` and `integrator`. Parallel writers use isolated worktrees, then an integrator. A verifier directly depends on the artifact owner. Inspect workflow status on recovery; completed nodes are not replayed. Check remote state before retrying external effects. `pstack_worktrees` cleans only owned clean worktrees.\n';
+  // A wrapper heading makes upstream numbered steps available to the existing contract extractor.
+  return piFront+prelude+(skill?'':'## Steps\n\n')+body+runtime;
+}
+export function generatedResources(root) {
+  const registry=JSON.parse(readFileSync(join(root,'PARITY.json'),'utf8'));
+  return [...Object.entries(registry.skills).filter(([,status])=>status==='ADAPTED').map(([name])=>`${name}/SKILL.md`),...Object.entries(registry.playbooks).filter(([,status])=>status==='ADAPTED').map(([name])=>`poteto-mode/playbooks/${name}.md`)].sort();
+}
+export function generateCore(root, write=false) {
+  for(const resource of generatedResources(root)) {
+    const file=join(root,'skills',resource),expected=renderCore(root,resource);
+    if(write)writeFileSync(file,expected);
+    else if(readFileSync(file,'utf8')!==expected)throw new Error(`SEMANTIC_ENTRYPOINT_DRIFT: ${resource}; regenerate after review`);
+  }
+}
+if(process.argv[1]?.endsWith('/semantics/generate.mjs'))generateCore(process.cwd(),process.argv.includes('--write'));

package/scripts/semantics/real-pi-smoke.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/** Opt-in, read-only real-model probe. No forge, workflow execution, filesystem mutation or shell tool. */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createAgentSession, DefaultResourceLoader, ModelRegistry, SessionManager, getAgentDir } from '@earendil-works/pi-coding-agent';
+import { createResourceTools } from '../../src/agent/resources.ts';
+import { registerSemanticTool } from '../../src/compatibility/tool.ts';
+const args=process.argv.slice(2);
+if(args.length!==2 || args[0]!=='--model' || !/^[^/\s]+\/[^\s]+$/.test(args[1])) {
+  console.error('usage: node --experimental-strip-types scripts/semantics/real-pi-smoke.mjs --model provider/model');process.exit(2);
+}
+const root=resolve('.'),cwd=mkdtempSync(join(tmpdir(),'pstack-semantic-real-'));
+const tools=[createResourceTools(join(root,'skills'))[0]];
+registerSemanticTool({registerTool:tool=>tools.push(tool)});
+const agentDir=getAgentDir();
+const loader=new DefaultResourceLoader({cwd,agentDir,noExtensions:true,noSkills:true,noPromptTemplates:true,noThemes:true});
+let session,timer;
+try {
+  await loader.reload();
+  ({session}=await createAgentSession({cwd,agentDir,resourceLoader:loader,sessionManager:SessionManager.inMemory(),customTools:tools,tools:['pstack_skill','pstack_semantics'],thinkingLevel:'off'}));
+  const registry=new ModelRegistry(session.modelRuntime),slash=args[1].indexOf('/');
+  const model=registry.find(args[1].slice(0,slash),args[1].slice(slash+1));
+  if(!model || !registry.hasConfiguredAuth(model)) {
+    console.log(JSON.stringify({tier:'real-pi-real-model',status:'blocked',reason:'Requested model or configured authentication unavailable',model:args[1],inference:false}));process.exitCode=2;
+  } else {
+    await session.setModel(model);
+    const observed=[],started=new Map();let modelError=false;
+    session.subscribe(event=>{
+      if(event.type==='tool_execution_start')started.set(event.toolCallId,event.args);
+      if(event.type==='tool_execution_end')observed.push({tool:event.toolName,args:started.get(event.toolCallId),isError:event.isError,details:event.result?.details});
+      if(event.type==='message_end' && event.message.role==='assistant' && event.message.stopReason==='error')modelError=true;
+    });
+    timer=setTimeout(()=>void session.abort(),90_000);
+    await session.prompt('Read the entire pinned shipping playbook using pstack_skill resource upstream/skills/poteto-mode/playbooks/shipping.md. Continue every page until hasMore=false. Then call pstack_semantics action capability with name Cursor-watch-READY. Do not invent success for that unsupported operation. Finally call pstack_semantics action route name status. Return a short report. Use no other tools.');
+    const reads=observed.filter(o=>o.tool==='pstack_skill' && !o.isError && o.details?.resource==='upstream/skills/poteto-mode/playbooks/shipping.md');
+    const lines=new Set(reads.flatMap(o=>o.details.lines.map(l=>l.line)));
+    const total=reads[0]?.details?.totalLines;
+    const complete=total>0 && lines.size===total && reads.some(o=>o.details.hasMore===false);
+    const refused=observed.some(o=>o.tool==='pstack_semantics' && o.args?.action==='capability' && o.args?.name==='Cursor-watch-READY' && o.isError);
+    const routed=observed.some(o=>o.tool==='pstack_semantics' && o.details?.playbook==='babysit');
+    const passed=complete && refused && routed && !modelError;
+    console.log(JSON.stringify({tier:'real-pi-real-model',status:passed?'passed':'failed',model:args[1],completeSourceRead:complete,unsupportedRefused:refused,statusRoutedToBabysit:routed,inference:true,boundary:'One read-only shipping/source/capability/routing probe; no implementation, live surface, review swarm, merge or full behavioral parity.'},null,2));
+    if(!passed)process.exitCode=1;
+  }
+} finally {clearTimeout(timer);session?.dispose();rmSync(cwd,{recursive:true,force:true});}

package/scripts/smoke-host.mjs

@@ -0,0 +1,10 @@
+/** Optional installed-SDK smoke test; requires a configured model/provider for actual inference. */
+import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(), tools: [], customTools: [],
+});
+try {
+  if (!Array.isArray(session.messages)) throw new Error("Pi AgentSession.messages contract changed");
+  if (typeof session.prompt !== "function" || typeof session.abort !== "function") throw new Error("Pi AgentSession lifecycle contract changed");
+  console.log("Pi SDK session creation contract: PASS (no provider inference performed)");
+} finally { session.dispose(); }