pi-pstack-native 0.0.0-stage → 1.0.0

package/docs/upstream-upgrade-0.15.32.md

@@ -0,0 +1,23 @@
+# pstack 0.15.32 and Pi SDK 1.4.0 upgrade
+
+Checked on 2026-10-26. The active pstack source is cursor/plugins@99b609a72323b70204eab407c622f436e858e112, the upstream main pin at that check. npm latest is @earendil-works/pi-coding-agent 1.4.0. The dependency is locked exactly for development and the consumer peer minimum is ^1.4.0.
+
+## What changed
+
+All 57 supported Skills and all 23 playbooks now retain their latest source body. The 58th Skill, make-bot-ui, stays explicitly Cursor-only. Statechart now includes its full 27-file upstream toolchain; no top-level target Skill remains pending. The vendored registry contains 141 source artifacts and original blob IDs, while provenance verifies all 200 upstream files. The 0.15.17 source remains historical provenance.
+
+The [machine-readable audit](upstream-upgrade-0.15.32.json) records all 118 changed upstream files with before/after blob IDs, section/step fingerprints, dispositions, native mappings and test references. It is an implementation audit, not maintainer approval or full model equivalence.
+
+## Critical decisions
+
+- Autopilot runs a full swarm for initial/major changes. A minor fix, conflict resolution or rebase can use a single new independent reviewer only with a clean prior full round. Fresh gates and live proof still cover the current head/base. Authors and replacement owners cannot countersign their own code.
+- Native exact-head/base ledger invalidation remains stricter than upstream patch-ID/build-noise reuse. Old round receipts are not reused as current proof. The native full round retains two distinct diff lanes and trunk-context proof as additional safeguards.
+- Stack topology has one owner. New upstream landing-in-flight rules are retained verbatim; coordinator duties and the distinction between local DAG preparation and remote stack delivery remain explicit.
+- Model effort maps to explicit native thinkingLevel. Provider/model selectors stay explicit; Cursor fast-slug/family rewriting is not silently emulated.
+- All changed references are pinned and readable. Cursor watcher, private provenance, cleanup and cloud runtime surfaces stay declared platform limits. Native DAG, AgentSession, worktree isolation, Frontier authorization and recovery are retained.
+
+## Verification and boundary
+
+The repository check passed 182 tests, plus its upstream-tooling and document-contract suites. Typecheck, all 15 offline/fake-provider E2E cases, SDK host creation, build and clean-tarball installation passed on Pi 1.4.0. The installed-package smoke read the pinned source through the public resource API and invoked the bundled statechart CLI. [Statechart validation](STATECHART.md) ran the unchanged upstream suite with real Java 21, checksummed TLC 1.7.4 and PNG rendering: 149 passed, zero failed, one mise-only discovery case skipped. A native test preflight resolves Java to an absolute path and applies a per-test deadline, fixing an upstream async fixture hang exposed by CI without altering its assertions. The formerly hanging case passed separately after the fix. CI adds a separate statechart toolchain job alongside Node 22.19/24 source, host, E2E and install checks.
+
+The authenticated real-model tier remains not-run because no model credentials are configured. Source availability, deterministic gates, toolchain behavior, maintainer semantic sign-off and real-model evidence are separate claims. No approval is inferred from this upgrade request or from passing tests. See [acceptance status](SEMANTIC-COMPATIBILITY.md).

package/docs/upstream-upgrade-0.15.36.md

@@ -0,0 +1,7 @@
+# pstack 0.15.36 upgrade
+
+The active source is `cursor/plugins` commit `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. The full 573-file Git tree was hashed against the checkout; the [provenance record](upstream-provenance-0.15.36.json) and [inventory](upstream-inventory-0.15.36.json) separate source metadata from executable Pi capabilities. The 0.15.32 and 0.15.17 snapshots remain historical records.
+
+The update includes the new Interrogate, Arena judge rules, agentic Orchestrate instructions, and the rewritten TypeScript Statechart runtime and corpus. Pi-specific execution behavior and remaining limits are documented in [the adapter](PI-SEMANTIC-ADAPTER.md). The source upgrade is not maintainer semantic sign-off and does not prove that a model obeyed the instructions.
+
+The compiled 0.15.36 Statechart CLI was smoke-tested with Java 17 and checksummed TLC 1.7.4 on the upstream Counter example, including from an installed package under node_modules. Real-model inference and live remote PR delivery for this revision require separate evidence. The complete upstream Statechart test suite may require Java/TLC, a working process-inspection environment, and optional runtime tools; skipped or environment-blocked tests do not count as passes.

package/docs/validate-pr.mjs

@@ -0,0 +1,74 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const required = ["Why", "What changed", "Scope", "Blast Radius", "Verification"];
+
+export function validatePR(body, state) {
+  const errors = [];
+  const sections = new Map();
+  let current;
+  let fence;
+  for (const line of body.split(/\r?\n/)) {
+    const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1];
+      else if (marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = undefined;
+      continue;
+    }
+    if (fence) continue;
+    const heading = line.match(/^##\s+(.+?)\s*#*\s*$/);
+    if (heading) {
+      current = heading[1].toLowerCase();
+      if (sections.has(current)) errors.push(`duplicate section ${heading[1]}`);
+      sections.set(current, "");
+    } else if (/^#\s/.test(line)) {
+      current = undefined;
+    } else if (current) {
+      sections.set(current, sections.get(current) + line.trim());
+    }
+  }
+  for (const heading of required) {
+    const content = sections.get(heading.toLowerCase());
+    if (content === undefined) errors.push(`missing section ${heading}`);
+    else if (!content) errors.push(`empty section ${heading}`);
+  }
+  if (state !== undefined) {
+    const fields = {
+      isDraft: (value) => typeof value === "boolean",
+      base: (value) => typeof value === "string" && value.length > 0,
+      parentBranch: (value) => value === null || (typeof value === "string" && value.length > 0),
+      trunk: (value) => typeof value === "string" && value.length > 0,
+      babysit: (value) => typeof value === "boolean",
+      phaseComplete: (value) => typeof value === "boolean",
+      ownerFullAutonomy: (value) => typeof value === "boolean",
+    };
+    for (const [field, valid] of Object.entries(fields)) {
+      if (!valid(state?.[field])) errors.push(`invalid state ${field}`);
+    }
+    if (errors.some((error) => error.startsWith("invalid state"))) return errors;
+    if (state.isDraft) errors.push("PR must be ready, not draft");
+    const base = state.parentBranch ?? state.trunk;
+    if (state.base !== base) errors.push(`PR base must be ${base}`);
+    if (state.babysit && !state.phaseComplete && !state.ownerFullAutonomy) {
+      errors.push("babysit must wait for phase or stack completion");
+    }
+  }
+  return errors;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const [bodyPath, statePath] = process.argv.slice(2);
+  if (!bodyPath) {
+    console.error("Usage: node docs/validate-pr.mjs <body.md> [state.json]");
+    process.exitCode = 2;
+  } else {
+    const errors = validatePR(readFileSync(bodyPath, "utf8"), statePath ? JSON.parse(readFileSync(statePath, "utf8")) : undefined);
+    if (errors.length) {
+      console.error(errors.join("\n"));
+      process.exitCode = 1;
+    } else {
+      console.log("PR protocol ok");
+    }
+  }
+}

package/examples/README.md

@@ -0,0 +1,45 @@
+# Quick start
+
+Install the tarball into Pi using its normal package installation flow, or install into a project containing the official Pi peer SDK. Node >=22.19 is required.
+
+1. In the repository, use `pstack_verify {"action":"fingerprint"}` to obtain repoId.
+2. Fill `strict-brief.json` with that repoId, real paths and tests. Every strict node receives a full Brief. Legacy ordinary graph calls remain supported; legacy completed is never verified.
+3. Operator-managed `verification-policy.json` lives under PSTACK_NATIVE_HOME (default `~/.pi/agent/pstack-native`). Copy the example only after reviewing the exact command argv. Agents cannot supply their own policy through a tool call.
+4. Run or plan `pstack_workflow` with `contractLevel: strict`, nodes carrying `brief`, or a typed `template`.
+5. Inspect `pstack_verify` ledger and `pstack_context`. After a commit, run `pstack_verify` action `run-pr` with workflow id, key, actual repo and PR number to bind new clean-commit evidence to the live head. A changed commit requires a matching structured report/contract and fresh verification.
+6. `pstack_delivery` returns blockers only. Actual merge is `pstack-runner ship stack.json --approve --pr NUMBER`; without approval it is dry-run. Each next PR needs a new refreshed authorization. Babysit consists of querying these blockers, fixing via a new workflow and stopping at merge-ready.
+
+## API examples
+
+```json
+{"action":"plan","mode":"arena","template":{"kind":"arena","brief":"REPLACE_WITH_FULL_BRIEF_OBJECT","models":["provider/model-a","provider/model-b"],"judgeModel":"provider/model-judge","rubric":[{"criterion":"correctness","weight":1}],"candidateCount":2}}
+```
+
+The placeholder must be replaced by a full JSON object, not a reference string. `swarm` requires swarmMode race/partition. `review` reviewers are readonly. `autopilot-stack` takes strict slice briefs and builds sequential writers; `autopilot-full` takes slices and isolated PR-owner implementation lanes followed by integration/verification. Actual PR creation remains explicit CLI.
+
+## CLI
+
+```sh
+pstack-runner migrate                 # preview
+pstack-runner migrate --apply         # backups; quiescent records only
+pstack-runner run runner.json --once
+pstack-runner run runner.json         # supervised polling; SIGINT/SIGTERM stop polling
+pstack-runner approve-gate /repo brief.json approve --approve
+pstack-runner ship stack.json         # dry-run
+pstack-runner ship stack.json --approve --pr 123
+pstack-runner open-pr /repo VERIFICATION_ID pr-details.json
+pstack-runner open-pr /repo VERIFICATION_ID pr-details.json --approve
+pstack-runner export audit.json
+```
+
+Runner config: `{ "agentDir": "/absolute/dedicated/pi-agent", "model": "provider/model", "workflowIds": ["wf_..."], "pollMs": 5000 }`. Agent dir must have separately configured SDK auth/models; do not rely on an interactive session's implicit credentials.
+
+Stack config: `{ "id":"my-stack", "repoId":"FINGERPRINT_REPO_ID", "repo":"owner/repository", "numbers":[123,124], "owner":"YOUR_SCOPE", "requireReview":true, "requireBehavior":true }` in dependency order. PR details: `{ "repo":"owner/repository", "base":"main", "head":"feature-branch", "title":"Describe verified change" }`.
+
+## Benchmark
+
+```sh
+npm run benchmark -- --agent-dir /absolute/dedicated/pi-agent --model provider/model --output /absolute/benchmark-output
+```
+
+Twenty seeded bug-fix repositories and immutable independent tests are generated. Each case uses the same test/contract protocol and records execution, current verification and provider usage. Missing credentials remain blocked. The supplied fixtures measure simple bug fixes, not Cursor parity or complex multi-PR efficacy. For full comparative research use identical models/snapshots, repeated trials and additional cross-module, arena and real PR tasks.

package/examples/strict-brief.json

@@ -0,0 +1,14 @@
+{
+  "id": "feature-contract",
+  "revision": 1,
+  "contractLevel": "strict",
+  "goal": "Implement the requested behavior and pass independent regression tests",
+  "scope": { "repoId": "REPLACE_WITH_PSTACK_FINGERPRINT_REPO_ID", "include": ["src/**", "test/**"], "exclude": ["infra/**"] },
+  "contextRefs": ["README.md"],
+  "acceptance": [{ "id": "regression", "description": "Required regression suite passes", "required": true, "gateIds": ["tests"] }],
+  "verification": [{ "id": "tests", "kind": "command", "command": ["npm", "test"], "timeoutSeconds": 120, "sideEffect": "local", "category": "behavior" }],
+  "timeboxSeconds": 600,
+  "forbidden": ["force-push", "remote-merge", "change infra"],
+  "standingOrders": ["Preserve unrelated user changes", "Return a task-report-v1 JSON block"],
+  "reportFormat": "task-report-v1"
+}

package/examples/verification-policy.json

@@ -0,0 +1,8 @@
+{
+  "commands": [["npm", "test"], ["npm", "run", "check:types"]],
+  "allowLocal": true,
+  "allowRemote": false,
+  "maxTimeoutSeconds": 300,
+  "maxOutputBytes": 65536,
+  "environment": { "CI": "1" }
+}

package/package.json

@@ -1,6 +1,154 @@
 {
   "name": "pi-pstack-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "pi-pstack-native: pstack semantics rebuilt on Pi's official AgentSession APIs with native durable workflows, worktree isolation, model routing, and scheduling.",
+  "type": "module",
+  "license": "MIT",
+  "author": "2333sky",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/2333sky/pi-pstack-native.git"
+  },
+  "bugs": "https://github.com/2333sky/pi-pstack-native/issues",
+  "homepage": "https://github.com/2333sky/pi-pstack-native#readme",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pstack",
+    "poteto-mode",
+    "agents",
+    "workflow",
+    "durable",
+    "worktree"
+  ],
+  "files": [
+    "src/",
+    "skills/",
+    "agents/",
+    "scripts/",
+    "test/",
+    "tsconfig.json",
+    "CHANGELOG.md",
+    "UPSTREAM.json",
+    "PARITY.json",
+    "PARITY.md",
+    "PRD.md",
+    "README.md",
+    "README.zh-CN.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "REVIEW.md",
+    "NOTICE.md",
+    "LICENSE",
+    "examples/",
+    "benchmarks/",
+    "IMPLEMENTATION.md",
+    "ACCEPTANCE.md",
+    "docs/DEPENDENCIES.md",
+    "docs/README.md",
+    "docs/ML-WORKFLOWS.zh-CN.md",
+    "docs/REFERENCE.md",
+    "docs/PUBLISHING.md",
+    "docs/VALIDATION.md",
+    "docs/PR-PROTOCOL.md",
+    "docs/LIVE-TEST-PLAN.zh-CN.md",
+    "docs/WINDOWS-MODEL-TEST.zh-CN.md",
+    "docs/UPSTREAM-0.15.17.md",
+    "docs/parity.test.mjs",
+    "docs/stacked-pr-body.md",
+    "docs/upstream-provenance-0.15.17.json",
+    "docs/upstream-sync-0.15.17.json",
+    "docs/validate-pr.mjs",
+    "dist/",
+    "tsconfig.build.json",
+    "INSTALLATION-CHECK.md",
+    "docs/upstream-sync/",
+    "vendor/",
+    "SEMANTICS.json",
+    "docs/PI-SEMANTIC-ADAPTER.md",
+    "docs/SEMANTIC-COMPATIBILITY.md",
+    "docs/evidence/",
+    "docs/upstream-provenance-0.15.32.json",
+    "docs/upstream-provenance-0.15.36.json",
+    "docs/upstream-sync-0.15.36.json",
+    "docs/upstream-target-0.15.36.json",
+    "docs/upstream-dispositions-0.15.36.json",
+    "docs/upstream-inventory-0.15.36.json",
+    "docs/upstream-upgrade-0.15.36.md",
+    "docs/registry-records-0.15.36.json",
+    "docs/registry-records-0.15.32.json",
+    "docs/PR-41-ALIGNMENT-PLAN.zh-CN.md",
+    "docs/upstream-sync-0.15.32.json",
+    "docs/upstream-upgrade-0.15.32.md",
+    "docs/STATECHART.md",
+    "docs/upstream-upgrade-0.15.32.json"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.4.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "check:syntax": "node scripts/check-syntax.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "check:parity": "node scripts/check-parity.mjs",
+    "check:inventory": "node scripts/check-inventory.mjs",
+    "review": "node scripts/review.mjs",
+    "check": "npm run check:syntax && npm run check:package && npm run check:parity && npm run check:semantics && npm run check:inventory && npm run check:contracts && npm run check:records && npm run check:playbooks && npm run test:upstream && npm test && npm run review",
+    "check:playbooks": "node scripts/check-e2e.mjs playbooks",
+    "check:pr-body": "node docs/validate-pr.mjs",
+    "prepack": "npm run check:release",
+    "sync:upstream": "node scripts/sync-upstream.mjs",
+    "check:types": "tsc --noEmit -p tsconfig.json",
+    "check:host": "node scripts/smoke-host.mjs",
+    "benchmark": "node scripts/benchmark.mjs",
+    "build": "node scripts/build.mjs",
+    "benchmark:smoke": "node scripts/check-benchmark.mjs",
+    "test:e2e:offline": "node scripts/check-e2e.mjs offline",
+    "test:e2e:fake": "node scripts/check-e2e.mjs fake",
+    "check:e2e": "npm run test:e2e:offline && npm run test:e2e:fake",
+    "test:live": "node --experimental-strip-types scripts/e2e-live.mjs",
+    "smoke:installed": "node scripts/smoke-install.mjs",
+    "check:release": "npm run check && npm run check:types && npm run check:e2e && npm run build && npm run check:host && npm run benchmark:smoke && npm run smoke:installed",
+    "upstream:inventory": "node scripts/upstream/cli.mjs inventory",
+    "upstream:scan": "node scripts/upstream/cli.mjs scan",
+    "upstream:plan": "node scripts/upstream/cli.mjs plan",
+    "upstream:verify": "node scripts/upstream/cli.mjs verify",
+    "upstream:prepare": "node scripts/upstream/cli.mjs prepare",
+    "upstream:propose": "node scripts/upstream/cli.mjs propose",
+    "test:upstream": "node --experimental-strip-types --test scripts/upstream/*.test.mjs",
+    "check:plan": "node scripts/check-plan.mjs",
+    "check:contracts": "node --experimental-strip-types scripts/check-contracts.mjs",
+    "upstream:contracts": "node --experimental-strip-types scripts/check-contracts.mjs --write",
+    "check:records": "node scripts/check-records.mjs",
+    "registry:records": "node scripts/check-records.mjs --write",
+    "check:semantics": "node --experimental-strip-types scripts/check-semantics.mjs",
+    "test:semantics": "node --experimental-strip-types --test test/semantic-compatibility.test.ts",
+    "smoke:semantics:real": "node --experimental-strip-types scripts/semantics/real-pi-smoke.mjs",
+    "test:statechart": "node scripts/check-statechart.mjs"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "^22.0.0",
+    "fast-check": "4.5.3",
+    "typescript": "^5.8.0"
+  },
+  "bin": {
+    "pstack-runner": "./dist/runner/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/scripts/benchmark.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync, readFileSync, realpathSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { WorkflowEngine } from '../dist/workflow/engine.js';
+import { AgentHost } from '../dist/agent/host.js';
+import { fingerprint } from '../dist/artifacts/fingerprint.js';
+import { runnerOnce } from '../dist/runner/service.js';
+import { protocol } from '../dist/runtime/protocol.js';
+const usage='benchmark requires explicit --agent-dir PATH --model provider/model';
+export function parseArgs(argv){const opts={};for(let i=0;i<argv.length;i++){const key=argv[i];if(!['--agent-dir','--model','--output','--limit','--max-tokens'].includes(key)||opts[key]!==undefined||!argv[i+1]||argv[i+1].startsWith('--'))throw new Error(`Unknown, repeated, or missing benchmark argument: ${key}`);opts[key]=argv[++i];}const agentDir=opts['--agent-dir'],model=opts['--model'];if(!agentDir||!model)throw new Error(usage);const positive=(name)=>{const value=opts[name];if(value===undefined)return undefined;if(!/^[1-9]\d*$/.test(value)||!Number.isSafeInteger(Number(value)))throw new Error(`Invalid ${name}`);return Number(value);};const limit=positive('--limit'),maxTokens=positive('--max-tokens');return{agentDir,model,output:opts['--output']??'benchmark-output',...(limit===undefined?{}:{limit}),...(maxTokens===undefined?{}:{maxTokens})};}
+export function runnerBlocked(runnerResults=[]){return runnerResults.some(r=>r?.reason==='AUTHENTICATION_UNAVAILABLE');}
+export function exitCode(rows,runnerResults=[]){if(runnerBlocked(runnerResults))return 1;return rows.length>0&&rows.every(r=>r.verified)?0:1;}
+export function caseEvidence(call,state){const ledger=call.verification?.ledgerId ? state.ledgers[call.verification.ledgerId] : undefined;const testEvidence=ledger?.evidenceRefs.map(id=>state.evidence[id]).find(item=>item?.gateId==='tests');return {testEvidence:testEvidence?.status ?? 'not-run',contractAccepted:ledger?.contractAccepted ?? null,verificationReason:call.verification?.reason ?? null,reportError:call.reportError ?? null};}
+export async function runBenchmark({agentDir,model,output,limit,maxTokens=200000}) {
+const root=resolve(output);mkdirSync(root,{recursive:true});
+process.env.PSTACK_NATIVE_HOME=join(root,'state');mkdirSync(process.env.PSTACK_NATIVE_HOME,{recursive:true});
+const cases=JSON.parse(readFileSync(new URL('../benchmarks/cases.json',import.meta.url),'utf8'));
+const engine=new WorkflowEngine(new AgentHost());const rows=[];const runnerResults=[];
+for(const c of cases.slice(0,limit)) {
+  const cwd=join(root,c.id);mkdirSync(cwd,{recursive:true});
+  const source=`export function solve(${c.params}) { return ${c.seed}; }\n`;writeFileSync(join(cwd,'source.mjs'),source);
+  writeFileSync(join(cwd,'checks.test.mjs'),`import {solve} from './source.mjs';\nimport assert from 'node:assert/strict';\n${c.assertions.map(a=>`assert.deepEqual(solve(${a.args}),${a.expected});`).join('\n')}\n`);
+  const git=(...a)=>execFileSync('git',['-C',cwd,...a],{stdio:'ignore'});git('init','-q');git('config','user.name','Benchmark');git('config','user.email','benchmark@example.invalid');git('add','.');git('commit','-qm','fixture');
+  const command=['node','--test','checks.test.mjs'];writeFileSync(join(process.env.PSTACK_NATIVE_HOME,'verification-policy.json'),JSON.stringify({commands:[command]}));
+  const fp=fingerprint(cwd);
+  const brief={id:c.id,revision:1,contractLevel:'strict',goal:c.goal,scope:{include:['source.mjs'],exclude:['checks.test.mjs'],repoId:fp.repoId},contextRefs:['checks.test.mjs'],acceptance:[{id:'behavior',description:c.goal,required:true,gateIds:['tests']}],verification:[{id:'tests',kind:'command',command,timeoutSeconds:30,sideEffect:'none',category:'behavior'}],timeboxSeconds:600,forbidden:['change tests','remote-write'],standingOrders:['Only change source.mjs; commit the change locally without pushing; emit task-report-v1.'],reportFormat:'task-report-v1'};
+  const wf=engine.create({cwd,parentSessionId:`benchmark-${c.id}`,contractLevel:'strict',budget:{maxTimeSeconds:600,maxTokens},nodes:[{key:'fix',profile:'worker',task:c.goal,model,brief}]});
+  runnerResults.push(...await runnerOnce({agentDir:resolve(agentDir),model,workflowIds:[wf.id]}));
+  const result=engine.get(wf.id);const call=result.calls.fix;
+  rows.push({caseId:c.id,workflowId:wf.id,execution:result.state,verified:engine.acceptedWorkflow(result),...caseEvidence(call,protocol()),usage:call.usage ?? null,error:result.error ?? null});
+  writeFileSync(join(root,'results.json'),JSON.stringify({platform:'pi-pstack-native',model,rows},null,2));
+}
+console.log(JSON.stringify({cases:rows.length,verified:rows.filter(r=>r.verified).length,results:join(root,'results.json')},null,2));
+return {rows,runnerResults};
+}
+export function isEntry(argv1=process.argv[1]){if(!argv1)return false;const self=fileURLToPath(import.meta.url);if(argv1===self)return true;try{return realpathSync(argv1)===realpathSync(self);}catch{return false;}}
+if(isEntry()){const {rows,runnerResults}=await runBenchmark(parseArgs(process.argv.slice(2)));const code=exitCode(rows,runnerResults);if(runnerBlocked(runnerResults))console.error('benchmark blocked: AUTHENTICATION_UNAVAILABLE');process.exit(code);}

package/scripts/build-statechart.mjs

@@ -0,0 +1,30 @@
+/** Compile the pinned, type-only upstream runtime so Node can execute it inside node_modules. */
+import { readdirSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import ts from 'typescript';
+
+const source = 'skills/statechart/scripts', output = 'dist/statechart';
+const check = process.argv.includes('--check');
+function compile(directory) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.name === 'test') continue;
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) { compile(path); continue; }
+    if (!entry.name.endsWith('.ts')) continue;
+    const destination = join(output, relative(source, path).replace(/\.ts$/, '.js'));
+    let text = ts.transpileModule(readFileSync(path, 'utf8'), { compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, rewriteRelativeImportExtensions: true } }).outputText;
+    if (entry.name === 'statechart.ts') {
+      const before = 'path.join(import.meta.dirname, "worker.ts")';
+      if (!text.includes(before)) throw new Error('STATECHART_WORKER_PATH_DRIFT');
+      text = text.replace(before, 'path.join(import.meta.dirname, "worker.js")');
+    }
+    if (check) {
+      if (readFileSync(destination, 'utf8') !== text) throw new Error(`STATECHART_BUILD_DRIFT: ${destination}`);
+    } else {
+      mkdirSync(dirname(destination), { recursive: true });
+      writeFileSync(destination, text);
+    }
+  }
+}
+compile(source);
+console.log(check ? 'Statechart compiled runtime matches the pinned TypeScript source.' : 'Statechart TypeScript runtime compiled for installed Node packages.');

package/scripts/build.mjs

@@ -0,0 +1,11 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, chmodSync, rmSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+rmSync('dist',{recursive:true,force:true});
+const result=spawnSync(process.execPath,['node_modules/typescript/bin/tsc','-p','tsconfig.build.json'],{stdio:'inherit'});
+if(result.status!==0)process.exit(result.status ?? 1);
+function copy(dir){for(const entry of readdirSync(dir,{withFileTypes:true})){const path=join(dir,entry.name);if(entry.isDirectory())copy(path);else if(entry.name.endsWith('.mjs')){const rel=relative('src',path),out=join('dist',rel);mkdirSync(dirname(out),{recursive:true});if(rel===join('runner','cli.mjs')){writeFileSync(out,readFileSync(path,'utf8').replace(/\.ts(['"])/g,'.js$1'));chmodSync(out,0o755);}else copyFileSync(path,out);}}}
+copy('src');
+await import('./build-statechart.mjs');
+function declarations(dir){for(const entry of readdirSync(dir,{withFileTypes:true})){const path=join(dir,entry.name);if(entry.isDirectory())declarations(path);else if(path.endsWith('.d.ts'))writeFileSync(path,readFileSync(path,'utf8').replace(/\.ts(['"])/g,'.js$1'));}}
+declarations('dist');console.log('JavaScript runtime and declarations built.');

package/scripts/check-benchmark.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/** Offline verification of the packaged benchmark entrypoint (no model calls). */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+const root = resolve(process.env.PSTACK_BENCHMARK_ROOT ?? resolve(dirname(fileURLToPath(import.meta.url)), '..'));
+const benchmark = readFileSync(resolve(root, 'scripts/benchmark.mjs'), 'utf8');
+const imports = [...benchmark.matchAll(/from ['"](\.\.\/dist\/[^'"\s]+)['"]/g)].map(m => m[1]);
+if (imports.length !== 5) throw new Error(`Expected 5 compiled runtime imports, received ${imports.length}`);
+for (const specifier of imports) {
+  if (!specifier.endsWith('.js')) throw new Error(`Not a compiled JS import: ${specifier}`);
+  const filepath = resolve(root, 'scripts', specifier);
+  if (!existsSync(filepath)) throw new Error(`Missing built benchmark dependency: ${filepath}`);
+}
+const entry = pathToFileURL(resolve(root, 'scripts/benchmark.mjs')).href;
+const linked = spawnSync(process.execPath, ['--input-type=module', '-e', `import(${JSON.stringify(entry)}).then(() => {}, error => { console.error(error.message); process.exit(1); })`], { cwd: root, encoding: 'utf8' });
+if (linked.status !== 0) throw new Error(`Benchmark entry failed to link: ${`${linked.stderr}${linked.stdout}`.trim()}`);
+const cases = JSON.parse(readFileSync(resolve(root, 'benchmarks/cases.json'), 'utf8'));
+if (!Array.isArray(cases) || !cases.length) throw new Error('No benchmark cases');
+const ids = new Set();
+for (const c of cases) {
+  if (typeof c.id !== 'string' || !c.id || ids.has(c.id)) throw new Error('Duplicate/invalid benchmark id');
+  ids.add(c.id);
+  if (!c.goal || !c.params || !Array.isArray(c.assertions) || !c.assertions.length) throw new Error(`Incomplete case: ${c.id}`);
+}
+console.log(`Benchmark entry imports validated: ${imports.length}; link: ok; fixtures: ${cases.length}. No external model was called.`);

package/scripts/check-contracts.mjs

@@ -0,0 +1,15 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildContracts, contractPath, validateContracts } from './upstream/playbooks.mjs';
+
+const root = process.cwd();
+const fresh = buildContracts({ root });
+if (process.argv.includes('--write')) {
+  writeFileSync(join(root, contractPath), `${JSON.stringify(fresh, null, 2)}\n`);
+  console.log(JSON.stringify({ status: 'written', contracts: fresh.contracts.length }));
+} else {
+  const committed = JSON.parse(readFileSync(join(root, contractPath), 'utf8'));
+  validateContracts(committed, { root });
+  if (JSON.stringify(committed) !== JSON.stringify(fresh)) throw new Error(`CONTRACT_DRIFT in ${contractPath}; run npm run upstream:contracts`);
+  console.log(JSON.stringify({ status: 'in-sync', contracts: fresh.contracts.length }));
+}

package/scripts/check-e2e.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Runs one verification tier file by file and binds each result to the file that really ran it.
+ * A custom reporter emits the path and name of every top level test, so a deleted file, an emptied
+ * file, an imported substitute, a renamed test, a skipped test, a duplicate or a symlink alias
+ * cannot make the tier report success. Whether a body asserts anything is outside what a test
+ * runner can prove, because the test files are part of the repository.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const tiers = {
+  playbooks: {
+    files: [{
+      file: 'docs/parity.test.mjs',
+      tests: ['ketchup loads with valid Pi frontmatter and required sections', 'opening and babysit document ready stacked PRs and deferred handoff', 'ready child targets its parent and waits for phase completion', 'reject a draft PR', 'reject a child with the wrong base', 'reject premature babysit', 'reject missing Scope or Verification', 'reject empty sections and headings inside fenced code', 'reject malformed snapshots instead of treating strings as authorization', 'PR body CLI validates the sample file'].map((name) => ({ name, state: 'pass' })),
+    }],
+  },
+  offline: {
+    files: [
+      {
+        file: 'test/e2e/offline.test.ts',
+        tests: ['[offline] the credentialed live tier never runs without an explicit operator target', '[offline] the live tier is skipped by default when its own file runs', '[offline] every refused live-tier environment runs no external command and enters no write path', '[offline] every test in the live tier consults only the guard gate', '[offline] GitHubCLI rejects invalid repository and pull request inputs before it touches gh', '[offline] the GitHub provider refuses a merge whose expected head is stale', '[offline] a disposable fixture repository never carries credentials in captured output'].map((name) => ({ name, state: 'pass' })),
+      },
+      {
+        file: 'test/e2e/reported-defects.test.ts',
+        tests: ['[offline] reported src defect: read-only child profiles receive no read-only tools', '[offline] reported src defect: a captured evidence log leaks a credential embedded in a URL'].map((name) => ({ name, state: 'pass' })),
+      },
+    ],
+  },
+  fake: {
+    files: [
+      {
+        file: 'test/e2e/shipping.test.ts',
+        tests: ['[fake-provider] a verified commit opens a pull request and its base, head, CI and review state are read back', '[fake-provider] a stale head SHA blocks the merge', '[fake-provider] a crash before the external side effect replays exactly once and never double-merges', '[fake-provider] a crash after the external side effect is at most once because recovery reads the remote first'].map((name) => ({ name, state: 'pass' })),
+      },
+      {
+        file: 'test/e2e/workflow.test.ts',
+        tests: ['[fake-provider] a strict workflow runs two worktrees, an integrator and deterministic verification', '[fake-provider] a workflow resumes after SIGKILL without replaying completed calls or external effects', '[fake-provider] malformed task reports expose diagnostics and stay blocked', '[fake-provider] configured review panels dispatch distinct models through Pi sessions', '[fake-provider] panel model fallback is visible in the durable workflow', '[fake-provider] one cross-judge inspects isolated candidates before integration', '[fake-provider] interrogate copies dirty changes and reruns findings in isolated sessions', '[fake-provider] swarm first-pass cancels an in-flight Pi session after verified acceptance'].map((name) => ({ name, state: 'pass' })),
+      },
+    ],
+  },
+};
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const tier = process.argv[2];
+const spec = tiers[tier];
+if (!spec) throw new Error(`TIER_UNKNOWN: ${tier ?? '(none)'}; expected one of ${Object.keys(tiers).join(', ')}`);
+const listed = spec.files.map((entry) => entry.file);
+if (new Set(listed).size !== listed.length) throw new Error(`TIER_MANIFEST_DUPLICATE: ${listed.join(', ')}`);
+
+let passed = 0;
+let todo = 0;
+for (const entry of spec.files) {
+  const path = resolve(root, entry.file);
+  if (!existsSync(path)) throw new Error(`TIER_FILE_MISSING: ${entry.file}`);
+  const expected = new Map(entry.tests.map((test) => [test.name, test.state]));
+  const events = join(mkdtempSync(join(tmpdir(), 'e2e-events-')), 'events.jsonl');
+  let observed;
+  try {
+    execFileSync(process.execPath, ['--experimental-strip-types', '--test', '--test-reporter=./scripts/e2e-reporter.mjs', entry.file], { cwd: root, env: { ...process.env, E2E_EVENTS: events }, stdio: ['ignore', 'pipe', 'inherit'] });
+    observed = readFileSync(events, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+  } finally {
+    rmSync(dirname(events), { recursive: true, force: true });
+  }
+  const self = realpathSync(path);
+  const seen = new Map();
+  for (const event of observed) {
+    const state = event.todo ? 'todo' : event.status === 'pass' ? 'pass' : 'fail';
+    if (seen.has(event.name)) throw new Error(`TIER_DUPLICATE_TEST: ${entry.file} reported ${event.name} twice`);
+    seen.set(event.name, { state, file: realpathSync(event.file) });
+  }
+  for (const [name, found] of seen) {
+    if (found.file !== self) throw new Error(`TIER_FOREIGN_TEST: ${entry.file} ran a test owned by ${found.file}: ${name}`);
+    if (!expected.has(name)) throw new Error(`TIER_UNEXPECTED_TEST: ${entry.file} ran ${name}`);
+    if (expected.get(name) !== found.state) throw new Error(`TIER_TEST_STATE: ${entry.file} ${name} was ${found.state}, expected ${expected.get(name)}`);
+    if (found.state === 'pass') passed += 1;
+    if (found.state === 'todo') todo += 1;
+  }
+  for (const name of expected.keys()) if (!seen.has(name)) throw new Error(`TIER_MISSING_TEST: ${entry.file} never ran ${name}`);
+  console.log(`${entry.file} ok: ${seen.size} tests, ${['pass', 'todo', 'fail'].map((state) => `${[...seen.values()].filter((found) => found.state === state).length} ${state}`).join(', ')}`);
+}
+console.log(`${tier} tier ok: ${spec.files.length} files, ${passed} pass, ${todo} todo`);

package/scripts/check-inventory.mjs

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readJSON } from './upstream/core.mjs';
+import { buildInventory, readSnapshot, validateInventory } from './upstream/inventory.mjs';
+
+export function checkInventory(root) {
+  const snapshot = readSnapshot(root), parity = readJSON(join(root,'PARITY.json'));
+  const path = 'docs/upstream-inventory-0.15.36.json', committed = readFileSync(join(root,path),'utf8');
+  const inputs = {snapshot,parity,localRoot:root};
+  validateInventory(JSON.parse(committed),inputs);
+  const inventory = validateInventory(buildInventory(inputs),inputs);
+  if(committed !== JSON.stringify(inventory,null,2)+'\n') throw new Error('INVENTORY_Drift in '+path+'; run npm run upstream:inventory');
+  return inventory;
+}
+if(import.meta.url === pathToFileURL(resolve(process.argv[1] ?? '')).href) {
+  try {
+    const inventory = checkInventory(process.cwd());
+    console.log(JSON.stringify({status:'in-sync',files:inventory.counts.files}));
+  } catch(error) {
+    console.error('Inventory check failed: '+error.message);
+    process.exitCode = 1;
+  }
+}

package/scripts/check-package.mjs

@@ -0,0 +1,17 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+const pkg=JSON.parse(readFileSync("package.json","utf8"));
+const lock=JSON.parse(readFileSync("package-lock.json","utf8"));
+if(pkg.name!=="pi-pstack-native" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(pkg.version) || lock.name!==pkg.name || lock.version!==pkg.version || lock.packages?.[""]?.name!==pkg.name || lock.packages?.[""]?.version!==pkg.version) throw new Error("package identity drift");
+const versionLine=readFileSync("src/extension.ts","utf8").split("\n").find(line=>line.startsWith("const VERSION ="));
+if(!versionLine || !versionLine.includes('"package.json"')) throw new Error("src/extension.ts must read VERSION from package.json instead of hardcoding it");
+if(pkg.dependencies && Object.keys(pkg.dependencies).length) throw new Error("runtime dependencies; Pi host APIs belong in peerDependencies");
+for(const name of Object.keys(pkg.peerDependencies??{})) if(!name.startsWith("@earendil-works/")) throw new Error(`non-official peer dependency: ${name}`);
+if(!pkg.peerDependencies?.["@earendil-works/pi-coding-agent"]) throw new Error("missing Pi coding-agent peer dependency");
+if(JSON.stringify(pkg.pi).includes("skills")) throw new Error("skills must be discovered by the extension so /pstack on|off can work");
+const forbidden=["@whamp/pi-pstack","pi-subagents","pi-durable-subagents","pi-agents"];
+const texts=[];
+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|json)$/.test(n)) texts.push([f,readFileSync(f,"utf8")]);}}
+walk("src");
+for(const [file,text] of texts) for(const dep of forbidden) if(text.includes(`from \"${dep}`)||text.includes(`from '${dep}`)||text.includes(`require(\"${dep}`)) throw new Error(`forbidden runtime import ${dep} in ${file}`);
+console.log("package policy ok: official Pi peer runtime only");

package/scripts/check-parity.mjs

@@ -0,0 +1,4 @@
+import { checkParity } from './upstream/parity.mjs';
+const counts = checkParity(process.cwd());
+const pending = [...counts.pendingTarget.skills, ...counts.pendingTarget.playbooks];
+console.log(`parity manifest ok: ${counts.skills} skills and ${counts.playbooks} playbooks registered; ${pending.length ? `pending target: ${pending.join(', ')}` : 'no pending target'}; auxiliary file-level parity not claimed`);