pi-oracle 0.7.4 → 0.7.6

package/scripts/platform-smoke/crabbox-runner.mjs

@@ -0,0 +1,135 @@
+/**
+ * Thin Crabbox CLI wrapper for pi-oracle's local platform smoke targets.
+ */
+
+import { spawn } from "node:child_process";
+
+const CRABBOX_BIN = process.env.PI_ORACLE_SMOKE_CRABBOX || process.env.PLATFORM_SMOKE_CRABBOX || "crabbox";
+
+function env(name) {
+  return process.env[name] ?? "";
+}
+
+export function execCrabbox(args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(CRABBOX_BIN, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, CRABBOX_SYNC_GIT_SEED: "false", ...opts.env },
+      ...opts.spawnOpts,
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let timeout;
+    let killTimeout;
+    if (opts.timeout && opts.timeout > 0) {
+      timeout = setTimeout(() => {
+        stderrChunks.push(Buffer.from(`\n[platform-smoke] crabbox command timed out after ${opts.timeout}ms\n`));
+        try { child.kill("SIGTERM"); } catch {}
+        killTimeout = setTimeout(() => {
+          try { child.kill("SIGKILL"); } catch {}
+        }, 10_000);
+      }, opts.timeout);
+    }
+    child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    child.on("error", (error) => {
+      if (timeout) clearTimeout(timeout);
+      if (killTimeout) clearTimeout(killTimeout);
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString(),
+        stderr: `${Buffer.concat(stderrChunks).toString()}\n${error.message}`.trim(),
+        code: 1,
+        signal: null,
+      });
+    });
+    child.on("close", (code, signal) => {
+      if (timeout) clearTimeout(timeout);
+      if (killTimeout) clearTimeout(killTimeout);
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString(),
+        stderr: Buffer.concat(stderrChunks).toString(),
+        code: code ?? (signal ? 1 : 0),
+        signal,
+      });
+    });
+  });
+}
+
+export function buildTargetBaseArgs(targetName, config = {}) {
+  switch (targetName) {
+    case "macos": {
+      const host = env("PI_ORACLE_SMOKE_MAC_HOST") || env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+      const user = env("PI_ORACLE_SMOKE_MAC_USER") || env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+      const workRoot = env("PI_ORACLE_SMOKE_MAC_WORK_ROOT") || env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${env("USER")}/crabbox/${config.packageName ?? "pi-oracle"}`;
+      return [
+        "--provider", "ssh",
+        "--target", "macos",
+        "--static-host", host,
+        "--static-user", user,
+        "--static-port", "22",
+        "--static-work-root", workRoot,
+      ];
+    }
+    case "ubuntu": {
+      const image = env("PI_ORACLE_SMOKE_UBUNTU_IMAGE") || env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || "pi-oracle-platform-smoke:node24";
+      return [
+        "--provider", "local-container",
+        "--target", "linux",
+        "--local-container-image", image,
+      ];
+    }
+    case "windows-native": {
+      const vm = env("PI_ORACLE_SMOKE_WINDOWS_VM") || env("PLATFORM_SMOKE_WINDOWS_VM") || config.windowsParallels?.sourceVm || "pi-extension-windows-template";
+      const snapshot = env("PI_ORACLE_SMOKE_WINDOWS_SNAPSHOT") || env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || config.windowsParallels?.snapshot || "crabbox-ready";
+      const user = env("PI_ORACLE_SMOKE_WINDOWS_USER") || env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
+      const workRoot = env("PI_ORACLE_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${config.packageName ?? "pi-oracle"}`;
+      return [
+        "--provider", "parallels",
+        "--target", "windows",
+        "--windows-mode", "normal",
+        "--parallels-source", vm,
+        "--parallels-source-snapshot", snapshot,
+        "--parallels-user", user,
+        "--parallels-work-root", workRoot,
+      ];
+    }
+    default:
+      throw new Error(`unknown target: ${targetName}`);
+  }
+}
+
+function parseLeaseId(output) {
+  return output.match(/\bleased\s+(\S+)/)?.[1]
+    ?? output.match(/\blease=(\S+)/)?.[1]
+    ?? null;
+}
+
+export async function warmupLease(config, targetName, slug) {
+  const args = ["warmup", ...buildTargetBaseArgs(targetName, config), "--slug", slug, "--keep"];
+  if (targetName === "macos") args.push("--reclaim");
+  console.log(`  [crabbox] ${args.join(" ")}`);
+  const result = await execCrabbox(args, { timeout: 300_000 });
+  return {
+    ok: result.code === 0,
+    ...result,
+    leaseId: parseLeaseId(result.stdout) ?? parseLeaseId(result.stderr) ?? slug,
+  };
+}
+
+export async function runOnLease(config, targetName, leaseId, command, opts = {}) {
+  const args = ["run", ...buildTargetBaseArgs(targetName, config), "--id", leaseId];
+  if (targetName === "macos") args.push("--reclaim");
+  for (const name of opts.allowEnvNames ?? []) args.push("--allow-env", name);
+  if (opts.sync === false) args.push("--no-sync");
+  else args.push("--fresh-sync");
+  if (opts.shell) args.push("--shell", command);
+  else args.push("--", ...(Array.isArray(command) ? command : command.split(" ")));
+  console.log(`  [crabbox] run ${targetName} ${opts.sync === false ? "--no-sync" : "--fresh-sync"} ...`);
+  return execCrabbox(args, { timeout: opts.timeout ?? 900_000, env: opts.env });
+}
+
+export async function stopLease(config, targetName, leaseId) {
+  const args = ["stop", ...buildTargetBaseArgs(targetName, config), "--id", leaseId];
+  console.log(`  [crabbox] ${args.join(" ")}`);
+  return execCrabbox(args, { timeout: 60_000 });
+}

package/scripts/platform-smoke/doctor.mjs

@@ -0,0 +1,239 @@
+// Preflight checks for the pi-oracle Crabbox platform smoke gate.
+
+import { execFileSync, execSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+let failures = 0;
+
+function ok(label) { console.log(`  ✓ ${label}`); }
+function warn(label) { console.log(`  ⚠ ${label}`); }
+function fail(label) { console.error(`  ✗ ${label}`); failures += 1; }
+function env(name) { return process.env[name] ?? ""; }
+function truthy(value) { return /^(1|true|yes|on)$/i.test(String(value ?? "")); }
+
+function silent(command, args, opts = {}) {
+  try { return execFileSync(command, args, { timeout: 20_000, stdio: "pipe", ...opts }).toString().trim(); }
+  catch { return null; }
+}
+
+function shell(command, opts = {}) {
+  try { return execSync(command, { timeout: 20_000, stdio: "pipe", ...opts }).toString().trim(); }
+  catch { return null; }
+}
+
+function resolveCommand(command) {
+  if (!command) return null;
+  if (command.includes("/") || command.includes("\\")) return command;
+  return shell(`command -v ${command}`) ?? command;
+}
+
+function compareVersions(actual, required) {
+  const a = String(actual).split(".").map((part) => Number.parseInt(part, 10));
+  const b = String(required).split(".").map((part) => Number.parseInt(part, 10));
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const av = Number.isFinite(a[i]) ? a[i] : 0;
+    const bv = Number.isFinite(b[i]) ? b[i] : 0;
+    if (av > bv) return 1;
+    if (av < bv) return -1;
+  }
+  return 0;
+}
+
+function realSmokeProvider(config) {
+  return process.env.PI_ORACLE_REAL_TEST_PROVIDER || config.realSmoke?.defaultProvider || "zai";
+}
+
+function windowsVmName(config) {
+  return env("PI_ORACLE_SMOKE_WINDOWS_VM") || env("PLATFORM_SMOKE_WINDOWS_VM") || config.windowsParallels?.sourceVm || "pi-extension-windows-template";
+}
+
+function windowsSnapshotName(config) {
+  return env("PI_ORACLE_SMOKE_WINDOWS_SNAPSHOT") || env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || config.windowsParallels?.snapshot || "crabbox-ready";
+}
+
+function requiredRealSmokeAuthEnv(config) {
+  if (!(config.requiredSuites ?? []).includes("real-extension")) return [];
+  if (!truthy(process.env.PI_ORACLE_REAL_TEST_MODEL_AGENT)) return [];
+  const provider = realSmokeProvider(config);
+  return config.realSmoke?.authEnvByProvider?.[provider] ?? [];
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text); } catch { return undefined; }
+}
+
+function targetBaseArgs(targetName, config) {
+  if (targetName === "macos") {
+    const host = env("PI_ORACLE_SMOKE_MAC_HOST") || env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+    const user = env("PI_ORACLE_SMOKE_MAC_USER") || env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+    const workRoot = env("PI_ORACLE_SMOKE_MAC_WORK_ROOT") || env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${env("USER")}/crabbox/${config.packageName}`;
+    return ["--provider", "ssh", "--target", "macos", "--static-host", host, "--static-user", user, "--static-port", "22", "--static-work-root", workRoot];
+  }
+  if (targetName === "ubuntu") {
+    const image = env("PI_ORACLE_SMOKE_UBUNTU_IMAGE") || env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || "pi-oracle-platform-smoke:node24";
+    return ["--provider", "local-container", "--target", "linux", "--local-container-image", image];
+  }
+  const vm = windowsVmName(config);
+  const snapshot = windowsSnapshotName(config);
+  const user = env("PI_ORACLE_SMOKE_WINDOWS_USER") || env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
+  const workRoot = env("PI_ORACLE_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${config.packageName}`;
+  return ["--provider", "parallels", "--target", "windows", "--windows-mode", "normal", "--parallels-source", vm, "--parallels-source-snapshot", snapshot, "--parallels-user", user, "--parallels-work-root", workRoot];
+}
+
+function runCrabboxDoctor(cbox, label, args, timeout = 120_000) {
+  const output = silent(cbox, ["doctor", ...args, "--json"], { env: { ...process.env, CRABBOX_SYNC_GIT_SEED: "false" }, timeout });
+  if (!output) {
+    fail(`crabbox doctor ${label} failed`);
+    return;
+  }
+  const parsed = parseJson(output);
+  if (!parsed) fail(`could not parse ${label} Crabbox doctor JSON`);
+  else if (parsed.ok) ok(`${label} provider OK`);
+  else fail(`${label} doctor failed: ${parsed.error ?? "not ok"}`);
+}
+
+function runTargetToolProbe(cbox, targetName, config) {
+  const required = targetName === "windows-native"
+    ? ["node", "npm", "git", "tar", "zstd", "agent-browser"]
+    : ["node", "npm", "git", "tar", "rsync", "zstd", "agent-browser"];
+  const command = targetName === "windows-native"
+    ? `cmd.exe /c "where node && where npm && where git && where tar && where zstd && where agent-browser && zstd --version && agent-browser --version && echo tools-ok"`
+    : `missing=""; for tool in ${required.join(" ")}; do command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"; done; if [ -n "$missing" ]; then echo "missing=$missing"; exit 1; fi; zstd --version >/dev/null && agent-browser --version >/dev/null && echo tools-ok`;
+  const baseArgs = targetBaseArgs(targetName, config);
+  if (targetName === "macos") baseArgs.push("--reclaim");
+  const result = silent(cbox, ["run", ...baseArgs, "--no-sync", "--shell", command], {
+    env: { ...process.env, CRABBOX_SYNC_GIT_SEED: "false" },
+    timeout: targetName === "windows-native" ? 300_000 : 180_000,
+  });
+  result?.includes("tools-ok") ? ok(`${targetName} required target tools OK`) : fail(`${targetName} required target tools missing or probe failed${result ? `: ${result.split(/\r?\n/).slice(-3).join(" | ")}` : ""}`);
+}
+
+function verifyWindowsTemplate(config) {
+  const vm = windowsVmName(config);
+  const snapshot = windowsSnapshotName(config);
+  const prlctl = resolveCommand("prlctl");
+  if (!prlctl) {
+    fail("prlctl not found on host PATH");
+    return;
+  }
+  ok(`prlctl: ${prlctl}`);
+  const list = silent("prlctl", ["list", "--all", "-j"], { timeout: 30_000 });
+  const vms = parseJson(list);
+  const vmRecord = Array.isArray(vms) ? vms.find((entry) => entry.name === vm || entry.ID === vm) : undefined;
+  if (!vmRecord) fail(`Windows source VM not found: ${vm}`);
+  else if (vmRecord.status !== "stopped") fail(`Windows source VM ${vm} must be stopped; status=${vmRecord.status}`);
+  else ok(`Windows source VM stopped: ${vm}`);
+
+  const snapshotsText = silent("prlctl", ["snapshot-list", vm, "-j"], { timeout: 30_000 });
+  const snapshots = parseJson(snapshotsText);
+  const snapshotRecord = snapshots ? Object.values(snapshots).find((entry) => entry?.name === snapshot) : undefined;
+  if (!snapshotRecord) fail(`Windows snapshot not found: ${snapshot}`);
+  else if (snapshotRecord.state !== "poweroff") fail(`Windows snapshot ${snapshot} must be poweroff; state=${snapshotRecord.state}`);
+  else ok(`Windows snapshot poweroff/forkable: ${snapshot}`);
+}
+
+function verifyPackageExclusions() {
+  const forbiddenPatterns = [/^\.env(?:\.|$)/, /^\.artifacts(?:\/|$)/, /^\.crabbox(?:\/|$)/, /^\.debug(?:\/|$)/, /^\.platform-smoke-runs(?:\/|$)/, /\.tgz$/];
+  const output = shell("npm pack --dry-run --json", { timeout: 120_000 });
+  const parsed = parseJson(output);
+  if (!Array.isArray(parsed) || !parsed[0]?.files) {
+    warn("could not inspect npm pack file list");
+    return;
+  }
+  const files = parsed[0].files.map((file) => file.path);
+  const forbidden = files.filter((file) => forbiddenPatterns.some((pattern) => pattern.test(file)));
+  forbidden.length ? fail(`forbidden files in package: ${forbidden.join(", ")}`) : ok("package excludes local env/artifact/debug state");
+}
+
+function verifyRepoForbiddenFiles() {
+  const forbidden = shell("find . -maxdepth 3 \\( -name '.env' -o -name '.env.*' -o -name '*.tgz' \\) -print 2>/dev/null");
+  forbidden ? fail(`forbidden local secret/package artifact(s): ${forbidden}`) : ok("no .env/.env.* or package tarballs at repo root depth");
+  for (const dir of [".artifacts", ".crabbox", ".debug", ".platform-smoke-runs"]) {
+    const ignored = shell(`git check-ignore -q ${dir}/probe && echo ignored`);
+    ignored ? ok(`${dir}/ is gitignored`) : fail(`${dir}/ must be gitignored`);
+  }
+  const trackedForbidden = shell("git ls-files '.env*' '*.tgz' '.artifacts/*' '.crabbox/*' '.debug/*' '.platform-smoke-runs/*'");
+  trackedForbidden ? fail(`forbidden tracked local state: ${trackedForbidden}`) : ok("no forbidden local state is tracked");
+  verifyPackageExclusions();
+}
+
+export async function runDoctor(config) {
+  failures = 0;
+  console.log("\n── Environment ──");
+  const cbox = env("PI_ORACLE_SMOKE_CRABBOX") || env("PLATFORM_SMOKE_CRABBOX") || "crabbox";
+  ok(`Crabbox binary = ${resolveCommand(cbox) ?? cbox}${env("PI_ORACLE_SMOKE_CRABBOX") || env("PLATFORM_SMOKE_CRABBOX") ? " (env override)" : " (PATH)"}`);
+  ok(`PI_ORACLE_SMOKE_MAC_HOST = ${env("PI_ORACLE_SMOKE_MAC_HOST") || env("PLATFORM_SMOKE_MAC_HOST") || "localhost"}`);
+  ok(`PI_ORACLE_SMOKE_MAC_USER = ${env("PI_ORACLE_SMOKE_MAC_USER") || env("PLATFORM_SMOKE_MAC_USER") || env("USER")}`);
+  ok(`PI_ORACLE_SMOKE_UBUNTU_IMAGE = ${env("PI_ORACLE_SMOKE_UBUNTU_IMAGE") || env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || "pi-oracle-platform-smoke:node24"}`);
+  ok(`PI_ORACLE_SMOKE_WINDOWS_VM = ${windowsVmName(config)}`);
+  ok(`PI_ORACLE_SMOKE_WINDOWS_SNAPSHOT = ${windowsSnapshotName(config)}`);
+
+  console.log("\n── Crabbox ──");
+  const resolvedCbox = resolveCommand(cbox);
+  try { accessSync(resolvedCbox ?? cbox, constants.X_OK); ok(`binary executable: ${resolvedCbox ?? cbox}`); }
+  catch { fail(`${resolvedCbox ?? cbox} is not executable`); }
+  const version = silent(cbox, ["--version"]);
+  const versionLine = version?.split("\n")[0] ?? "";
+  version ? ok(`version: ${versionLine}`) : fail("could not read Crabbox version");
+  const requiredVersion = config.requiredCrabbox?.minVersion ?? config.requiredCrabbox?.version;
+  if (requiredVersion && versionLine) {
+    compareVersions(versionLine, requiredVersion) >= 0 ? ok(`required version: ${requiredVersion}+`) : fail(`Crabbox version mismatch: need ${requiredVersion}+, got ${versionLine}`);
+  }
+  const providers = silent(cbox, ["providers"], { timeout: 30_000 }) ?? "";
+  for (const provider of ["ssh", "local-container", "parallels"]) {
+    new RegExp(`^${provider}$`, "m").test(providers) ? ok(`provider available: ${provider}`) : fail(`crabbox providers missing ${provider}`);
+  }
+  runCrabboxDoctor(cbox, "macOS static SSH", targetBaseArgs("macos", config), 120_000);
+  runCrabboxDoctor(cbox, "Windows native Parallels", targetBaseArgs("windows-native", config), 180_000);
+  runCrabboxDoctor(cbox, "local-container", targetBaseArgs("ubuntu", config), 120_000);
+
+  console.log("\n── Host tools ──");
+  for (const [name, command] of [["Docker", "docker info --format '{{.ServerVersion}}'"], ["Node", "node --version"], ["npm", "npm --version"], ["git", "git --version"], ["tar", "tar --version"], ["rsync", "rsync --version"]]) {
+    const output = shell(command);
+    output ? ok(`${name}: ${output.split("\n")[0]}`) : fail(`${name} not found or unavailable`);
+  }
+  const nodeVersion = shell("node --version");
+  if (nodeVersion) {
+    const major = Number(nodeVersion.replace(/^v/, "").split(".")[0]);
+    if (major < (config.nodeValidationMajor ?? 24)) fail(`Node ${nodeVersion}; need ${config.nodeValidationMajor ?? 24}+ for smoke validation`);
+  }
+  verifyWindowsTemplate(config);
+
+  console.log("\n── Auth environment ──");
+  const requiredAuth = requiredRealSmokeAuthEnv(config);
+  if (requiredAuth.length === 0) ok("no real-smoke auth env required by configured suites");
+  for (const name of requiredAuth) {
+    env(name) ? ok(`${name} = (present, redacted)`) : fail(`${name} missing for required real-extension suite`);
+  }
+
+  console.log("\n── Target tools ──");
+  for (const target of config.requiredTargets ?? []) runTargetToolProbe(cbox, target, config);
+
+  console.log("\n── Artifact root ──");
+  const artifactRoot = resolve(process.cwd(), config.artifactRoot ?? ".artifacts/platform-smoke");
+  try {
+    mkdirSync(artifactRoot, { recursive: true });
+    const probe = resolve(artifactRoot, ".doctor-write-test");
+    writeFileSync(probe, "ok");
+    unlinkSync(probe);
+    ok(`writable: ${artifactRoot}`);
+  } catch (error) {
+    fail(`cannot write artifact root: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  console.log("\n── Git/package hygiene ──");
+  const branch = shell("git branch --show-current");
+  branch ? ok(`branch: ${branch}`) : warn("could not determine branch");
+  const status = shell("git status --short");
+  status ? warn(`${status.split(/\r?\n/).filter(Boolean).length} uncommitted change(s) under test`) : ok("clean worktree");
+  verifyRepoForbiddenFiles();
+
+  console.log(`\n=== Results: ${failures} failure(s) ===`);
+  if (failures > 0) {
+    process.exitCode = 1;
+    console.log("Fix the failures above before running npm run smoke:platform:all.");
+  } else {
+    console.log("Ready for npm run smoke:platform:all.");
+  }
+}

package/scripts/platform-smoke/invariants.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Cheap invariant tests for the platform-smoke harness.
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import config from "../../platform-smoke.config.mjs";
+import { writeManifest } from "./artifacts.mjs";
+import { buildPlatformBuildCommand, buildRealExtensionCommand } from "./targets.mjs";
+
+const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
+
+function runNode(args) {
+  return spawnSync(process.execPath, args, { cwd: repoRoot, encoding: "utf8" });
+}
+
+function testHelpTextIncludesTargetsAndExamples() {
+  const result = runNode(["scripts/platform-smoke.mjs", "--help"]);
+  assert.equal(result.status, 0, `help should exit cleanly: ${result.stderr}`);
+  assert.match(result.stdout, /Supported: macos,ubuntu,windows-native/, "help should list supported targets");
+  assert.match(result.stdout, /--suite\s+Suite name\. Supported: platform-build,real-extension/, "help should list supported suites");
+  assert.match(result.stdout, /npm run release:check/, "help should name the full release gate");
+  assert.match(result.stdout, /PLATFORM_SMOKE_CRABBOX/, "help should document reusable platform-smoke env knobs");
+}
+
+function testTargetSelection() {
+  const result = runNode(["scripts/platform-smoke.mjs", "run", "--target", "not-a-target", "--suite", "platform-build"]);
+  assert.notEqual(result.status, 0, "unsupported targets should fail before Crabbox runs");
+  assert.ifError(result.error);
+  assert.match(`${result.stdout ?? ""}\n${result.stderr ?? ""}`, /unsupported target: not-a-target/);
+}
+
+function testPackedInstallCommandRendering() {
+  const command = buildPlatformBuildCommand("ubuntu", config.packageName, config.nodeValidationMajor);
+  assert.match(command, /verify:oracle:platform/, "platform-build should run the platform-focused verification gate");
+  assert.doesNotMatch(command, /npm test/, "platform-build should not run the full local iteration gate on every target");
+  assert.match(command, /npm pack --silent/, "platform-build should pack the package");
+  assert.match(command, /npm install --no-save/, "platform-build should install the packed tarball");
+  assert.match(command, /install -l \.\/node_modules\/pi-oracle/, "platform-build should install through pi's package path");
+  assert.doesNotMatch(command, /\bpi\s+(?:-e|--extension)\s+\./, "release proof must not use pi -e/--extension source shortcuts");
+}
+
+function testRealExtensionPackedInstallRendering() {
+  const command = buildRealExtensionCommand("ubuntu", config);
+  assert.match(command, /smoke:real:packed/, "required real-extension suite should run packed real smoke");
+  assert.doesNotMatch(command, /smoke:real:source|extensions\/oracle\/index\.ts|\bpi\s+-e\b/, "required real-extension suite must not use source extension loading");
+}
+
+function testManifestFailure() {
+  const dir = mkdtempSync(join(tmpdir(), "pi-oracle-manifest-test-"));
+  try {
+    writeFileSync(join(dir, "present.txt"), "ok\n");
+    const manifest = writeManifest(dir, ["present.txt", "missing.txt"]);
+    assert.deepEqual(manifest.missing, ["missing.txt"], "missing manifest entries should be reported");
+    assert(manifest.expected.includes("artifact-manifest.json"), "manifest should require itself as an artifact");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function testCleanupFailureInvariant() {
+  const source = readFileSync(new URL("./targets.mjs", import.meta.url), "utf8");
+  assert.match(source, /recordStopResultOnSuite/, "multi-suite runs should record stop evidence on suite artifacts");
+  assert.match(source, /lease-stop/, "cleanup results should be asserted as lease-stop");
+  assert.match(source, /stop exit/, "cleanup failure should surface a stop exit error");
+}
+
+function testPackageExclusion() {
+  const result = spawnSync("npm", ["pack", "--dry-run", "--json"], { cwd: repoRoot, encoding: "utf8", shell: process.platform === "win32" });
+  assert.equal(result.status, 0, `npm pack dry-run failed: ${result.stderr}`);
+  const files = JSON.parse(result.stdout)[0].files.map((file) => file.path);
+  for (const forbidden of [".artifacts/", ".crabbox/", ".debug/", ".platform-smoke-runs/", ".env", "context.md"]) {
+    assert(!files.some((file) => file === forbidden || file.startsWith(forbidden)), `package should exclude ${forbidden}`);
+  }
+}
+
+function testSourceSmokeExplicitlyDebugOnly() {
+  const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+  assert.equal(pkg.scripts["smoke:real"], "npm run smoke:real:packed", "default real smoke should be packed-release proof");
+  assert.match(pkg.scripts["smoke:real:source"], /--mode source/, "source real smoke should be explicitly named");
+}
+
+function testCanonicalWorkflowConfig() {
+  const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+  assert.deepEqual(config.workflows?.everyday?.commands, ["npm run verify:oracle"], "everyday workflow should use the local verification gate");
+  assert(config.workflows?.platformSensitive?.commands?.includes("npm run smoke:platform:doctor"), "platform-sensitive workflow should start with doctor");
+  assert(config.workflows?.platformSensitive?.commands?.some((command) => command.includes("--target <target> --suite <suite>")), "platform-sensitive workflow should document focused target/suite runs");
+  assert.deepEqual(config.workflows?.platformMatrix?.commands, ["npm run smoke:platform:all"], "platform matrix workflow should use the full target matrix");
+  assert.deepEqual(config.workflows?.release?.commands, ["npm run release:check"], "release workflow should use the full local-plus-platform release gate");
+  assert.equal(config.requiredCrabbox?.minVersion, "0.26.0", "Crabbox baseline should match the documented provider contract");
+  assert.equal(pkg.scripts["smoke:platform:all"], "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native", "full platform smoke should remain doctor-first and cover all required targets");
+  assert.match(pkg.scripts["release:check"], /npm run verify:oracle && npm run smoke:platform:all/, "release check should combine local verification and full platform smoke");
+  const runnerSource = readFileSync(new URL("./crabbox-runner.mjs", import.meta.url), "utf8");
+  assert.match(runnerSource, /PLATFORM_SMOKE_CRABBOX/, "runner should honor reusable Crabbox binary override");
+  assert.match(runnerSource, /PLATFORM_SMOKE_MAC_WORK_ROOT/, "runner should honor reusable macOS work-root override");
+  assert.match(runnerSource, /PLATFORM_SMOKE_WINDOWS_WORK_ROOT/, "runner should honor reusable Windows work-root override");
+}
+
+function testRealSmokeExpensiveAgentPathsAreOptIn() {
+  const source = readFileSync(new URL("../oracle-real-smoke.mjs", import.meta.url), "utf8");
+  assert.match(source, /runDirectOracleSubmit/, "default real smoke should use deterministic installed-tool execution");
+  assert.match(source, /PI_ORACLE_REAL_TEST_MODEL_AGENT/, "real smoke should expose the optional model-agent toggle");
+  const targetsSource = readFileSync(new URL("./targets.mjs", import.meta.url), "utf8");
+  assert.match(targetsSource, /PI_ORACLE_REAL_TEST_MODEL_AGENT/, "platform real-extension command should forward the optional model-agent toggle");
+  assert.match(targetsSource, /realSmokeUsesModelAgent\(\) \? config\.realSmoke\?\.authEnvByProvider/, "platform smoke should allow provider auth env only for the optional model-agent path");
+  assert.match(source, /truthy\(env\("PI_ORACLE_REAL_TEST_MODEL_AGENT"\)\)/, "model-agent real smoke path should be opt-in");
+  assert.match(source, /PI_ORACLE_REAL_TEST_NEGATIVE_SYMLINK/, "real smoke should expose the optional negative symlink toggle");
+  assert.match(source, /truthy\(env\("PI_ORACLE_REAL_TEST_NEGATIVE_SYMLINK"\)\)/, "negative symlink real-agent check should be opt-in");
+}
+
+testHelpTextIncludesTargetsAndExamples();
+testTargetSelection();
+testPackedInstallCommandRendering();
+testRealExtensionPackedInstallRendering();
+testManifestFailure();
+testCleanupFailureInvariant();
+testPackageExclusion();
+testSourceSmokeExplicitlyDebugOnly();
+testCanonicalWorkflowConfig();
+testRealSmokeExpensiveAgentPathsAreOptIn();
+console.log("platform-smoke invariant checks passed");