pi-session-mcp 0.0.0-stage → 0.6.2

package/dist/setup.js

@@ -0,0 +1,327 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createClaudeCodeAdapter, createCodexAdapter } from "./client-adapters/index.js";
+import { runDoctor } from "./doctor.js";
+import { createMcpStdioLauncher } from "./setup-process.js";
+import { verifyMcpCapabilities } from "./client-adapters/mcp-verifier.js";
+import { PACKAGE_VERSION, readLockfile, readPackageMetadata } from "./package-metadata.js";
+import { DurableOwnershipStore, MemoryOwnershipStore } from "./setup-ownership.js";
+import { result } from "./setup-result.js";
+export const isSupportedTarget = (target) => target.alias === "pi-session-mcp" &&
+    (target.client === "codex" ? target.scope === "user" :
+        target.client === "claude-code" && ["user", "project", "local"].includes(target.scope));
+export class SetupOrchestrator {
+    dependencies;
+    ownership;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.ownership = dependencies.ownership ?? new MemoryOwnershipStore();
+    }
+    async run(request) {
+        const operation = request.operation ?? "dry-run";
+        const targets = request.targets.filter(isSupportedTarget).filter((target, index, all) => all.findIndex((candidate) => candidate.client === target.client && candidate.scope === target.scope && candidate.alias === target.alias) === index);
+        if (targets.length !== request.targets.length || targets.length === 0)
+            return result(operation, [{ target: { client: "invalid", scope: "invalid", alias: "invalid" }, status: "failed", code: "target_invalid" }], "failed");
+        if (operation === "dry-run")
+            return this.plan(targets, this.ownership);
+        if (operation === "apply")
+            return this.ownership.transaction((ownership) => this.apply(targets, ownership));
+        if (operation === "verify")
+            return this.ownership.transaction((ownership) => this.verify(targets, ownership));
+        if (operation === "rollback")
+            return this.ownership.transaction((ownership) => this.restore(targets, "rolled_back", ownership));
+        return this.ownership.transaction((ownership) => this.restore(targets, "removed", ownership));
+    }
+    adapter(t) { return this.dependencies.adapters?.find((a) => a.name === t.client && a.supportedScopes.includes(t.scope)); }
+    assertOwnershipHealthy(ownership) { ownership.assertHealthy?.(); }
+    signal(ownership) { return ownership.signal?.(); }
+    execution(ownership) { const signal = this.signal(ownership); return { ...(signal ? { signal } : {}), ...(ownership.mutationRunner ? { runner: ownership.mutationRunner } : {}) }; }
+    async plan(targets, ownership) {
+        const findings = [];
+        if (this.dependencies.doctor) {
+            const doctor = await this.safe(() => this.dependencies.doctor.check());
+            if (!doctor?.ok)
+                return result("dry-run", targets.map((target) => ({ target, status: "failed", code: doctor?.code ?? "doctor_failed" })), "failed");
+        }
+        for (const target of targets) {
+            this.assertOwnershipHealthy(ownership);
+            const adapter = this.adapter(target);
+            if (!adapter) {
+                findings.push({ target, status: "unsupported", code: "client_unsupported" });
+                continue;
+            }
+            const inspected = await this.safe(() => adapter.inspect(target, this.dependencies.intendedFingerprint));
+            if (!inspected) {
+                findings.push({ target, status: "failed", code: "inspect_failed" });
+                continue;
+            }
+            let owned;
+            try {
+                owned = await ownership.get(target);
+            }
+            catch {
+                findings.push({ target, status: "failed", code: "ownership_unavailable" });
+                continue;
+            }
+            if (owned && owned.fingerprint !== this.dependencies.intendedFingerprint) {
+                findings.push({ target, status: "divergent", code: "release_binding_mismatch" });
+                continue;
+            }
+            if (inspected.state === "absent" && owned?.phase === "owned") {
+                findings.push({ target, status: "divergent", code: "ownership_diverged" });
+                continue;
+            }
+            findings.push({ target, status: inspected.state === "equivalent" ? "unchanged" : inspected.state, code: inspected.state });
+        }
+        const failed = findings.some((finding) => ["failed", "unsupported", "divergent"].includes(finding.status));
+        return result("dry-run", findings, failed ? "failed" : "planned");
+    }
+    async apply(targets, ownership) {
+        const plan = await this.plan(targets, ownership);
+        if (plan.status === "failed") {
+            const findings = plan.findings.map((finding) => finding.status === "divergent" && finding.code === "divergent"
+                ? { ...finding, code: "divergence_requires_replacement" }
+                : finding);
+            return result("apply", findings, "failed");
+        }
+        const findings = [];
+        for (const target of targets) {
+            this.assertOwnershipHealthy(ownership);
+            const adapter = this.adapter(target);
+            if (!adapter) {
+                findings.push({ target, status: "unsupported", code: "client_unsupported" });
+                continue;
+            }
+            const current = await this.safe(() => adapter.inspect(target, this.dependencies.intendedFingerprint));
+            let owned;
+            try {
+                owned = await ownership.get(target);
+            }
+            catch {
+                findings.push({ target, status: "failed", code: "ownership_unavailable" });
+                continue;
+            }
+            if (!current) {
+                findings.push({ target, status: "failed", code: "inspect_failed" });
+                continue;
+            }
+            if (owned && owned.fingerprint !== this.dependencies.intendedFingerprint) {
+                findings.push({ target, status: "failed", code: "release_binding_mismatch" });
+                continue;
+            }
+            if (current.state === "absent" && owned?.phase === "owned") {
+                findings.push({ target, status: "failed", code: "ownership_diverged" });
+                continue;
+            }
+            if (current.state === "equivalent") {
+                if (current.fingerprint !== this.dependencies.intendedFingerprint) {
+                    findings.push({ target, status: "failed", code: "registration_fingerprint_mismatch" });
+                    continue;
+                }
+                if (owned?.phase === "pending" && owned.fingerprint === this.dependencies.intendedFingerprint) {
+                    try {
+                        this.assertOwnershipHealthy(ownership);
+                        await ownership.put({ ...owned, phase: "owned" });
+                        this.assertOwnershipHealthy(ownership);
+                        findings.push({ target, status: "ok", code: "pending_recovered" });
+                    }
+                    catch {
+                        findings.push({ target, status: "failed", code: "ownership_unavailable" });
+                    }
+                }
+                else
+                    findings.push({ target, status: "unchanged", code: "already_equivalent" });
+                continue;
+            }
+            if (current.state !== "absent") {
+                findings.push({ target, status: "divergent", code: "divergence_requires_replacement" });
+                continue;
+            }
+            const pending = { target, fingerprint: this.dependencies.intendedFingerprint, previous: "absent", phase: "pending", transactionId: randomUUID() };
+            try {
+                this.assertOwnershipHealthy(ownership);
+                await ownership.put(pending);
+                this.assertOwnershipHealthy(ownership);
+                await adapter.apply(target, this.execution(ownership));
+                this.assertOwnershipHealthy(ownership);
+                const after = await adapter.inspect(target, this.dependencies.intendedFingerprint);
+                this.assertOwnershipHealthy(ownership);
+                if (!after || after.state !== "equivalent" || after.fingerprint !== this.dependencies.intendedFingerprint)
+                    throw new Error("post_apply_mismatch");
+                await ownership.put({ ...pending, phase: "owned" });
+                findings.push({ target, status: "ok", code: "applied" });
+            }
+            catch {
+                findings.push({ target, status: "failed", code: "apply_failed_recovery_pending" });
+            }
+        }
+        return result("apply", findings);
+    }
+    async verify(targets, ownership) {
+        const findings = [];
+        for (const target of targets) {
+            this.assertOwnershipHealthy(ownership);
+            const adapter = this.adapter(target);
+            if (!adapter) {
+                findings.push({ target, status: "unsupported", code: "client_unsupported" });
+                continue;
+            }
+            let owned;
+            try {
+                owned = await ownership.get(target);
+            }
+            catch {
+                findings.push({ target, status: "failed", code: "ownership_unavailable" });
+                continue;
+            }
+            if (owned && owned.fingerprint !== this.dependencies.intendedFingerprint) {
+                findings.push({ target, status: "failed", code: "release_binding_mismatch" });
+                continue;
+            }
+            const doctor = this.dependencies.doctor ? await this.safe(() => this.dependencies.doctor.check()) : { ok: true, code: "doctor_skipped" };
+            const inspected = await this.safe(() => adapter.inspect(target, this.dependencies.intendedFingerprint));
+            const equivalent = inspected?.state === "equivalent" && inspected.fingerprint === this.dependencies.intendedFingerprint;
+            const verified = equivalent ? await this.safe(() => adapter.verify(target)) : undefined;
+            findings.push({ target, status: doctor?.ok && equivalent && verified?.ok ? "ok" : "failed", code: !doctor?.ok ? doctor?.code ?? "doctor_failed" : !equivalent ? "registration_not_equivalent" : verified?.code ?? "verify_failed" });
+        }
+        return result("verify", findings);
+    }
+    async restore(targets, success, ownership) {
+        const findings = [];
+        for (const target of targets) {
+            this.assertOwnershipHealthy(ownership);
+            const adapter = this.adapter(target);
+            let owned;
+            try {
+                owned = await ownership.get(target);
+            }
+            catch {
+                findings.push({ target, status: "failed", code: "ownership_unavailable" });
+                continue;
+            }
+            if (!adapter) {
+                findings.push({ target, status: "unsupported", code: "client_unsupported" });
+                continue;
+            }
+            if (!owned || (owned.phase !== "owned" && owned.phase !== "pending")) {
+                findings.push({ target, status: "failed", code: "ownership_unavailable" });
+                continue;
+            }
+            const inspected = await this.safe(() => adapter.inspect(target, owned.fingerprint));
+            this.assertOwnershipHealthy(ownership);
+            if (!inspected || (inspected.state !== "equivalent" && inspected.state !== "absent") || (inspected.state === "equivalent" && inspected.fingerprint !== owned.fingerprint)) {
+                findings.push({ target, status: "failed", code: "ownership_diverged" });
+                continue;
+            }
+            try {
+                if (inspected.state === "equivalent") {
+                    this.assertOwnershipHealthy(ownership);
+                    await adapter.remove(target, this.execution(ownership));
+                    this.assertOwnershipHealthy(ownership);
+                    const after = await adapter.inspect(target, owned.fingerprint);
+                    this.assertOwnershipHealthy(ownership);
+                    if (!after || after.state !== "absent")
+                        throw new Error("post_remove_mismatch");
+                }
+                this.assertOwnershipHealthy(ownership);
+                await ownership.delete(target);
+                findings.push({ target, status: "ok", code: success });
+            }
+            catch {
+                findings.push({ target, status: "failed", code: "cleanup_failed" });
+            }
+        }
+        return result(success === "removed" ? "remove" : "rollback", findings);
+    }
+    async safe(call) { try {
+        return await call();
+    }
+    catch {
+        return undefined;
+    } }
+}
+export function registrationFingerprint(intent, releaseBinding = "unbound") {
+    return createHash("sha256")
+        .update(JSON.stringify({ node: intent.nodePath, entry: intent.entryPath, config: intent.configPath, releaseBinding }))
+        .digest("hex");
+}
+/** Bind setup ownership to the exact package manifests and built runtime tree. */
+export async function immutableReleaseBinding(packageRoot) {
+    const metadata = await readPackageMetadata(packageRoot, readFile);
+    if (metadata.version !== PACKAGE_VERSION || (metadata.lockVersion !== undefined && metadata.lockVersion !== PACKAGE_VERSION))
+        throw new Error("release_version_mismatch");
+    const runtimeRoot = join(packageRoot, "dist");
+    const runtimeFiles = await listRuntimeFiles(runtimeRoot);
+    for (const required of ["main.js", "setup-command-guardian.js"]) {
+        if (!runtimeFiles.includes(required))
+            throw new Error("release_entry_missing");
+        const entry = await lstat(join(runtimeRoot, required));
+        if (!entry.isFile() || entry.isSymbolicLink())
+            throw new Error("release_entry_invalid");
+    }
+    const hash = createHash("sha256");
+    hash.update("package.json").update("\0").update(await readFile(join(packageRoot, "package.json"))).update("\0");
+    // A Git checkout binds its lockfile too; an npm installation has none to bind.
+    const lock = await readLockfile(packageRoot, readFile);
+    if (lock !== undefined)
+        hash.update("package-lock.json").update("\0").update(lock).update("\0");
+    for (const relativePath of runtimeFiles) {
+        hash.update(relativePath).update("\0").update(await readFile(join(runtimeRoot, ...relativePath.split("/")))).update("\0");
+    }
+    return hash.digest("hex");
+}
+async function listRuntimeFiles(directory, prefix = "") {
+    const files = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isSymbolicLink())
+            throw new Error("release_symlink_invalid");
+        if (entry.isDirectory())
+            files.push(...await listRuntimeFiles(join(directory, entry.name), relativePath));
+        else if (entry.isFile() && entry.name.endsWith(".js"))
+            files.push(relativePath);
+    }
+    return files.sort();
+}
+export async function createProductionSetup(runner, packageRoot, configPath, ownershipPath = join(homedir(), ".local", "state", "pi-session-mcp", "ownership.json"), signal) {
+    const nodePath = process.execPath;
+    const entryPath = join(packageRoot, "dist", "main.js");
+    const makeIntent = (target) => ({ scope: target.scope, nodePath, entryPath, configPath });
+    const fingerprintFor = async (target) => registrationFingerprint(makeIntent(target), await immutableReleaseBinding(packageRoot));
+    const wrap = (adapter) => ({
+        name: adapter.client,
+        supportedScopes: adapter.client === "codex" ? ["user"] : ["user", "project", "local"],
+        async inspect(target, expectedFingerprint) {
+            const capabilities = await adapter.discover();
+            if (!capabilities.supportsAdd || !capabilities.supportsRemove || !capabilities.scopes.includes(target.scope))
+                return { state: "unsupported" };
+            const inspected = await adapter.inspect(target.scope, makeIntent(target));
+            if (inspected.state !== "equivalent")
+                return { state: inspected.state };
+            const currentFingerprint = await fingerprintFor(target);
+            return currentFingerprint === expectedFingerprint ? { state: "equivalent", fingerprint: currentFingerprint } : { state: "divergent" };
+        },
+        async apply(target, execution) { await adapter.add(makeIntent(target), execution); },
+        async remove(target, execution) { await adapter.remove(target.scope, execution); },
+        async verify() {
+            const verification = await verifyMcpCapabilities({ launch: createMcpStdioLauncher({ nodePath, entryPath, configPath }) });
+            return { ok: verification.status === "verified", code: verification.status === "verified" ? "mcp_verified" : `mcp_${verification.status}` };
+        },
+    });
+    const referenceTarget = { client: "codex", scope: "user", alias: "pi-session-mcp" };
+    const dependencies = {
+        adapters: [wrap(createCodexAdapter({ runner })), wrap(createClaudeCodeAdapter({ runner }))],
+        doctor: {
+            async check() {
+                const doctor = await runDoctor({ packageRoot, loadConfig: async () => { const { loadConfig } = await import("./config.js"); return loadConfig(configPath); } });
+                return { ok: doctor.ok, code: doctor.ok ? "doctor_ok" : "doctor_failed" };
+            },
+        },
+        ownership: new DurableOwnershipStore(ownershipPath, { ...(signal ? { signal } : {}) }),
+        intendedFingerprint: await fingerprintFor(referenceTarget),
+    };
+    return new SetupOrchestrator(dependencies);
+}
+export { result } from "./setup-result.js";

package/dist/shutdown.d.ts

@@ -0,0 +1,10 @@
+export declare const PROCESS_SHUTDOWN_TIMEOUT_MS = 15000;
+export type ShutdownResult = "completed" | "failed" | "timed_out";
+export interface TerminationHooks {
+    readonly report: (result: ShutdownResult) => void;
+    readonly terminate: (code: number) => void;
+}
+/** Bounds how long the signal handler waits; it does not prove SDK/provider termination. */
+export declare function shutdownWithDeadline(registryShutdown: () => Promise<void>, transportClose: () => Promise<void>, timeoutMs?: number): Promise<ShutdownResult>;
+/** Reports the bounded result and then applies the explicit process-termination policy. */
+export declare function shutdownAndTerminate(registryShutdown: () => Promise<void>, transportClose: () => Promise<void>, exitCode: number, hooks: TerminationHooks, timeoutMs?: number): Promise<void>;

package/dist/shutdown.js

@@ -0,0 +1,52 @@
+export const PROCESS_SHUTDOWN_TIMEOUT_MS = 15_000;
+/** Bounds how long the signal handler waits; it does not prove SDK/provider termination. */
+export async function shutdownWithDeadline(registryShutdown, transportClose, timeoutMs = PROCESS_SHUTDOWN_TIMEOUT_MS) {
+    let timer;
+    let transportPromise;
+    const closeTransport = () => {
+        transportPromise ??= Promise.resolve().then(transportClose);
+        return transportPromise;
+    };
+    const operation = (async () => {
+        let failed = false;
+        try {
+            await registryShutdown();
+        }
+        catch {
+            failed = true;
+        }
+        try {
+            await closeTransport();
+        }
+        catch {
+            failed = true;
+        }
+        return failed ? "failed" : "completed";
+    })();
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            void closeTransport().catch(() => undefined);
+            resolve("timed_out");
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([operation, deadline]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Reports the bounded result and then applies the explicit process-termination policy. */
+export async function shutdownAndTerminate(registryShutdown, transportClose, exitCode, hooks, timeoutMs = PROCESS_SHUTDOWN_TIMEOUT_MS) {
+    const result = await shutdownWithDeadline(registryShutdown, transportClose, timeoutMs);
+    try {
+        hooks.report(result);
+    }
+    catch {
+        // Reporting must not prevent the terminal process policy.
+    }
+    finally {
+        hooks.terminate(exitCode);
+    }
+}

package/docs/acceptance.md

@@ -0,0 +1,227 @@
+# Acceptance
+
+This document defines how Pi Session MCP is accepted before a release, what each
+acceptance level establishes, and which rules apply to evidence.
+
+Acceptance has three levels. Each level answers a different question, and a
+higher level never replaces a lower one.
+
+| Level | Question | Needs |
+| --- | --- | --- |
+| 1. Repository checks | Does this source build and pass its provider-free tests? | Node.js and npm only |
+| 2. Setup acceptance | Can real clients register, verify and remove this build without touching anything else? | Real Codex and Claude Code clients, no model |
+| 3. Live two-client acceptance | Do real clients complete real delegated work through this build? | Real clients, local Pi authentication and a model endpoint |
+
+Provider-free tests exercise the real Pi SDK and real stdio child processes with
+a scripted model. They do not establish live client or model acceptance. State
+only what was run.
+
+## Level 1: repository checks
+
+Run on a clean checkout of the exact source under test:
+
+```bash
+npm ci
+npm run typecheck
+npm run build:cli
+npm test
+npm run build
+npm audit
+git diff --check
+git status --short
+```
+
+Pass criteria:
+
+- Every command exits with `0`, and `git status --short` prints nothing.
+- `npm audit` reports 0 vulnerabilities. CI does not run `npm audit`, so this is
+  a manual gate. The advisory database changes over time: a result is valid for
+  the moment it was taken.
+
+CI (`.github/workflows/ci.yml`) runs the steps from `npm ci` through
+`npm run build`, without `npm audit` and the two Git checks, on Node.js 22.19.0
+for every push and pull request. A result is valid for the commit it ran on.
+
+The nightly Pi SDK canary (`.github/workflows/pi-sdk-canary.yml`) checks the
+unchanged sources against the newest published Pi SDK. It is an early warning
+for upstream drift, not part of accepting a given source; see
+[Releasing](releasing.md#update-the-pi-sdk).
+
+## Level 2: setup acceptance
+
+Setup acceptance runs the complete registration lifecycle with real clients
+against isolated client state. It starts no session and needs no provider.
+
+### Isolation
+
+- Use a disposable home directory for each client and a separate scratch project
+  directory. Run every client and `setup` command with `HOME` pointing at the
+  disposable home, and for Codex also `CODEX_HOME` inside it.
+- Place a disposable Codex home outside `/tmp`. Codex CLI `0.159.2` refuses to
+  create helper binaries below a temporary directory and adds a warning to its
+  version output, which the strict version parser rejects as `unsupported`.
+- Use a separate mode-`0600` configuration with one workspace alias and one
+  default `read-only` execution profile with inert provider and model names. It
+  must contain no credential and no real provider configuration.
+- Add one harmless, unrelated registration to each disposable client home
+  before the first step. It is the sentinel that must survive.
+- Record a digest of the real client registrations before the first step.
+
+### Sequence
+
+Run the nine operations in this order for every target under test, each with
+`--json`:
+
+| # | Operation | Overall status | Finding: status (code) | Exit |
+| ---: | --- | --- | --- | ---: |
+| 1 | no operation (default) | `planned` | `absent (absent)` | 0 |
+| 2 | `--dry-run` | `planned` | `absent (absent)` | 0 |
+| 3 | `--apply` | `ok` | `ok (applied)` | 0 |
+| 4 | `--apply` again | `ok` | `unchanged (already_equivalent)` | 0 |
+| 5 | `--verify` | `ok` | `ok (mcp_verified)` | 0 |
+| 6 | `--rollback` | `ok` | `ok (rolled_back)` | 0 |
+| 7 | `--apply` | `ok` | `ok (applied)` | 0 |
+| 8 | `--verify` | `ok` | `ok (mcp_verified)` | 0 |
+| 9 | `--remove` | `ok` | `ok (removed)` | 0 |
+
+Targets are `codex:user:pi-session-mcp` and the three Claude Code scopes
+`claude-code:user:pi-session-mcp`, `claude-code:project:pi-session-mcp` and
+`claude-code:local:pi-session-mcp`. Call the built entry point directly from the
+scratch project so that the project and local scopes resolve there:
+
+```bash
+env -i HOME="$DISPOSABLE_HOME" PATH="$PATH" PI_SESSION_MCP_CONFIG="$ACCEPTANCE_CONFIG" \
+  node /path/to/build/dist/setup-main.js --apply --json --target claude-code:project:pi-session-mcp
+```
+
+### Pass criteria
+
+- All nine operations report the expected overall status, finding and exit
+  status.
+- Steps 1 and 2 leave the client state unchanged.
+- After step 9 the `pi-session-mcp` registration is absent, the sentinel is still
+  present, and the ownership record set is empty. The ownership directory has
+  mode `0700` and the ownership file mode `0600`.
+- No server, setup or guardian process of the build under test remains.
+- The digest of the real client registrations is unchanged.
+- No report contains a path, the configuration location, an environment value
+  or a secret.
+
+### Working-tree and published-release variants
+
+A working-tree run accepts a change, for example a newly supported client
+version. It proves nothing about published bytes.
+
+A published-package run installs the published npm package into a temporary
+prefix (`npm install -g --prefix <dir> pi-session-mcp@<version>`) and runs the
+lifecycle through the installed `pi-session-mcp-setup`, which also proves the
+executables and the entry-point detection through npm's symlinks.
+
+A published-release run uses a fresh clone of the published tag instead of an
+existing branch or local tag. It additionally records the tag object and the
+peeled commit, confirms `git describe --tags --exact-match`, passes Level 1 on
+that checkout with Doctor reporting the release version, and confirms that the
+manifests and built runtime files are byte-identical before and after the
+client cycles.
+
+## Level 3: live two-client acceptance
+
+Live acceptance delegates real work from Codex and from Claude Code to Pi
+sessions and verifies the outcome independently of the clients' own reports.
+
+The harness for this level is not part of this repository: prompts, oracles,
+snapshot and digest tools and the scan for leaked values are prepared per cycle.
+
+### Preconditions
+
+- Server: a separate detached checkout of the release under test, built with
+  `npm ci`, `npm run build` and `npm run build:cli`. Record the commit, the tag
+  object if there is one, and the SHA-256 of `dist/main.js`.
+- Configuration: temporary, credential-free, with synthetic workspace aliases
+  and one `read-only` and one `coding` execution profile. Offline Doctor must
+  pass for it.
+- Model endpoint: run one bounded preflight before the first task. If the
+  endpoint is shared, record the loaded model before and after the cycle and
+  never force-load a model that another session is using. If the preflight
+  fails, stop and record the cycle as blocked; do not start a turn.
+- Clients: record the exact client versions and how each client reached the
+  server. Prefer a temporary per-invocation MCP configuration, so that no
+  global registration changes.
+- Pre-registration: fix the plan, the acceptance criteria per task, the prompts,
+  the oracles, the tools, the configurations and the fixture digests before the
+  first task.
+
+### Task matrix
+
+Each client runs the same five tasks on disposable synthetic fixtures:
+
+| Task | What it shows |
+| --- | --- |
+| Capability-led read-only analysis | Discovery through `pi_capabilities_get`, explicit workspace and profile selection, prompt, result |
+| Same-session read-only follow-up | A useful second turn in the same session; the first turn's terminal view stays unchanged |
+| Bounded coding change | A `coding` profile changes only the allowed files |
+| Same-session coding follow-up | A second coding turn in the same session |
+| Abort and recovery | Running, abort, `aborted`, close, empty session list, then a fresh session that starts `idle` |
+
+Run strictly sequentially: one client invocation at a time, three invocations
+per client (read-only with follow-up, coding with follow-up, abort). Do not
+repeat a task.
+
+### Independent verification
+
+- Read-only invariance: a path, mode and content digest of each analysis
+  fixture is identical before and after every invocation that used it.
+- Coding barrier: after each coding turn, take a snapshot before the next
+  prompt is sent. Run oracles and fixture tests on the snapshot, not on the live
+  workspace. Git status must show only the allowed files as modified.
+- Public results: scan every Pi Session MCP tool result in the client transcripts
+  for local paths, the endpoint address, key and token markers, stack frames,
+  network error strings and configuration file names. Expect zero hits.
+- Cleanup: no Pi Session MCP server of this run exists before each invocation or
+  shortly after each client exit, and no outer client process remains.
+- Liveness: a running turn whose `updatedAt` advanced beyond `startedAt` shows
+  observable activity. Its absence only means that the turn finished between
+  two polls.
+
+### Gate
+
+The cycle is accepted when all of the following hold:
+
+- At least 8 of the 10 tasks reach their intended outcome without a Pi Session MCP
+  defect.
+- Both clients complete discovery, start, prompt, result and close.
+- Both clients complete a useful sequential second turn.
+- Both clients complete a bounded, independently verified coding workflow.
+- No change exists outside the approved diff.
+- No credential, path, raw provider error, prompt or transcript appears in
+  public metadata.
+- No public session and no server process remains after a verified close.
+- Lifecycle errors are stable and sanitized.
+- Level 1 is green for the release source.
+
+The ten fixture tasks are deliberately small. They qualify the control path, not
+model capability on larger work. Not covered are interactive approval dialogs,
+external MCP grants, and client restart or resume.
+
+A narrower live check can cover a single path. It must state its scope and does
+not count as a ten-task cycle.
+
+## Evidence rules
+
+- Record only sanitized evidence: statuses, booleans, counts, durations,
+  versions, release and build identifiers, digests, and method and tool names.
+- Never publish prompts, assistant responses, transcripts, public session or
+  turn identifiers, credentials, authentication locations, absolute local paths,
+  the endpoint address, raw provider errors or raw client output.
+- Bind every record to the exact source commit, the commands, the exit codes and
+  the observed counts. A result for one commit is not evidence for another.
+- Keep failed, blocked and partial runs on record. A new attempt gets a new
+  record; never overwrite an earlier one or merge two attempts into one result.
+- Name what a run does not cover.
+
+## Status
+
+Release notes state which levels were run for a release and what was not
+covered. Pi Session MCP has passed all three levels in earlier private cycles. The
+live two-client acceptance has not yet been repeated on a build with Pi SDK
+`1.x`.

package/docs/adr/0001-stdio-first.md

@@ -0,0 +1,12 @@
+# ADR 0001: stdio first
+
+**Status:** Accepted
+
+## Decision
+
+Phase 0 serves MCP exclusively with the server SDK's `serveStdio` helper. stdout is reserved for MCP and diagnostics use stderr.
+
+## Rationale and consequences
+
+Inherited stdio keeps the server local, gives the launcher control of process lifetime, and avoids prematurely designing HTTP authentication, origin validation, tenancy, and deployment. Only one trusted local peer is supported. Remote clients and browser access require a future security review and ADR.
+

package/docs/adr/0002-embedded-pi-sdk.md

@@ -0,0 +1,11 @@
+# ADR 0002: embedded Pi SDK
+
+**Status:** Accepted
+
+## Decision
+
+Embed Pi through documented package-root SDK exports and encapsulate it behind `PiSessionAdapter`. Each managed embedded session owns an `AgentSession` created with `SessionManager.inMemory`, `SettingsManager.inMemory`, an explicit profile tool allowlist, and a `DefaultResourceLoader` that disables executable extensions and all project resources except non-executable `AGENTS.md` context.
+
+## Rationale and consequences
+
+Embedding avoids subprocess/RPC translation and exposes the documented preflight callback needed for non-blocking MCP prompts. The adapter makes lifecycle tests deterministic and credential-free. Pi shares the MCP process and OS privileges; this is management, not process isolation, and a crash or runaway operation affects the server. `AGENTS.md` remains model-influencing, untrusted context. Undocumented internal imports are prohibited, so transcript/result retrieval remains out of scope until supported publicly.