@tryinget/pi-agent-vent 0.1.2 → 0.2.1

package/scripts/release-artifact-check.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: validates packed file whitelists and local links in published markdown
+// read_when:
+//   - changing pi-agent-vent package contents or release artifact policy
+// ---
+
 import fs from "node:fs";
 import path from "node:path";
 
@@ -10,7 +16,7 @@ export const assertSafePackPath = (filePath) => {
   return filePath;
 };
 
-export const parsePackJson = (packJsonText) => {
+export const parsePackJson = (packJsonText, expectedIdentity = null) => {
   let pack;
   try {
     pack = JSON.parse(packJsonText || "[]");
@@ -18,11 +24,30 @@ export const parsePackJson = (packJsonText) => {
     throw new Error(`Could not parse npm pack --dry-run --json output: ${error.message}`);
   }
 
-  if (!Array.isArray(pack) || !pack[0] || !Array.isArray(pack[0].files)) {
+  let packEntry = null;
+  if (Array.isArray(pack) && pack.length === 1) {
+    [packEntry] = pack;
+  } else if (pack && typeof pack === "object") {
+    const entries = Object.entries(pack);
+    if (entries.length === 1 && entries[0][0] === entries[0][1]?.name) {
+      packEntry = entries[0][1];
+    }
+  }
+  if (!packEntry || !Array.isArray(packEntry.files)) {
     throw new Error("Could not parse npm pack --dry-run --json output.");
   }
+  if (
+    expectedIdentity &&
+    (packEntry.name !== expectedIdentity.name ||
+      packEntry.version !== expectedIdentity.version ||
+      packEntry.id !== `${expectedIdentity.name}@${expectedIdentity.version}`)
+  ) {
+    throw new Error(
+      `npm pack identity mismatch: expected ${expectedIdentity.name}@${expectedIdentity.version}.`,
+    );
+  }
 
-  return pack[0].files
+  return packEntry.files
     .map((file) => normalizePackPath(String(file.path || "")))
     .filter(Boolean)
     .map(assertSafePackPath)
@@ -182,8 +207,13 @@ export const runReleaseArtifactCheck = ({
   cwd = process.cwd(),
   log = console.log,
 }) => {
-  const actualFiles = parsePackJson(packJsonText);
-  const filesEntries = readPackageFilesContract(path.join(cwd, "package.json"));
+  const manifestPath = path.join(cwd, "package.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const actualFiles = parsePackJson(packJsonText, {
+    name: manifest.name,
+    version: manifest.version,
+  });
+  const filesEntries = readPackageFilesContract(manifestPath);
   const whitelist = validatePackageFilesWhitelist({ actualFiles, filesEntries, cwd });
 
   if (whitelist.missing.length || whitelist.extra.length) {

package/scripts/release-check.sh

@@ -1,14 +1,121 @@
 #!/usr/bin/env bash
+# ---
+# summary: exercises pi-agent-vent packaging, isolated installation, and release smoke gates
+# read_when:
+#   - preparing a release or investigating tarball and pi installation failures
+# ---
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPO_ROOT="$(cd "$ROOT_DIR/../.." && pwd)"
 cd "$ROOT_DIR"
 
+# Scratch-root resolution, from first principles:
+# the invariant is "release-check scratch lands on a managed, disposable root",
+# NOT "the TMPDIR variable happens to be exported". A GitHub-hosted runner is
+# single-tenant and ephemeral; its RUNNER_TEMP is exactly a managed scratch
+# root for that job, so CI satisfies the invariant even though runners never
+# export TMPDIR. Locally the strict rule is unchanged: no TMPDIR, no run.
+if [[ -n "${TMPDIR:-}" ]]; then
+  TMP_ROOT="$TMPDIR"
+elif [[ "${GITHUB_ACTIONS:-}" == "true" && -n "${RUNNER_TEMP:-}" && -d "${RUNNER_TEMP:-}" ]]; then
+  TMP_ROOT="$RUNNER_TEMP"
+else
+  echo "TMPDIR must name the managed scratch root for release checks" >&2
+  exit 1
+fi
+mkdir -p "$TMP_ROOT"
+TMP_ROOT="$(cd "$TMP_ROOT" && pwd -P)"
+case "$TMP_ROOT" in
+  /|"$ROOT_DIR"|"$ROOT_DIR"/*)
+    echo "Release check refused unsafe TMPDIR: $TMP_ROOT" >&2
+    exit 1
+    ;;
+esac
+release_tmp_dir() {
+  local label="$1"
+  mktemp -d "$TMP_ROOT/pi-agent-vent-${label}-XXXXXX"
+}
+
 NAME="$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).name")"
 VERSION="$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).version")"
 REPOSITORY_URL="$(node -p "(() => { const pkg = JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')); const repo = pkg.repository; if (typeof repo === 'string') return repo.trim(); if (repo && typeof repo === 'object' && typeof repo.url === 'string') return repo.url.trim(); return ''; })()")"
 
+HOST_VERSION="$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).devDependencies['@earendil-works/pi-coding-agent'] || ''")"
+
+# One release-only policy membrane. Every dependency-resolving command, including
+# Pi's nested npm invocation, must enter through here with disposable cache/prefix.
+RELEASE_MIN_AGE=0
+with_release_npm_policy() {
+  local cache="$1"
+  local prefix="$2"
+  shift 2
+  case "$cache" in
+    "$TMP_ROOT"/pi-agent-vent-*-npm-cache-*) ;;
+    *)
+      echo "Release command refused non-isolated npm cache: $cache" >&2
+      return 1
+      ;;
+  esac
+  if [[ "$prefix" != "-" ]]; then
+    case "$prefix" in
+      "$TMP_ROOT"/pi-agent-vent-*-npm-prefix-*) ;;
+      *)
+        echo "Release command refused non-isolated npm prefix: $prefix" >&2
+        return 1
+        ;;
+    esac
+    (
+      export NPM_CONFIG_PREFIX="$prefix" NPM_CONFIG_CACHE="$cache"
+      export NPM_CONFIG_MIN_RELEASE_AGE="$RELEASE_MIN_AGE"
+      "$@"
+    )
+  else
+    (
+      export NPM_CONFIG_CACHE="$cache" NPM_CONFIG_MIN_RELEASE_AGE="$RELEASE_MIN_AGE"
+      "$@"
+    )
+  fi
+}
+
+release_npm_install() {
+  local cache="$1"
+  local prefix="$2"
+  shift 2
+  with_release_npm_policy "$cache" "$prefix" npm install \
+    --include=optional --ignore-scripts --no-audit --fund=false "$@"
+}
+
+CONTROL_NPM_CACHE="$(release_tmp_dir control-npm-cache)"
+TEST_AGENT_DIR=""
+TEST_NPM_PREFIX=""
+TEST_NPM_CACHE=""
+ARTIFACT_NPM_PREFIX=""
+ARTIFACT_NPM_CACHE=""
+ARTIFACT_TOOL_VENT_DIR=""
+TARBALL_CHECK_DIR=""
+TARBALL_NPM_CACHE=""
+TARBALL_PATH=""
+cleanup() {
+  if [[ "${KEEP_RELEASE_ARTIFACTS:-0}" != "1" ]]; then
+    for path_to_remove in "$CONTROL_NPM_CACHE" "$TEST_AGENT_DIR" "$TEST_NPM_PREFIX" \
+      "$TEST_NPM_CACHE" "$ARTIFACT_NPM_PREFIX" "$ARTIFACT_NPM_CACHE" \
+      "$ARTIFACT_TOOL_VENT_DIR" "$TARBALL_CHECK_DIR" "$TARBALL_NPM_CACHE"; do
+      if [[ -n "$path_to_remove" && -d "$path_to_remove" ]]; then
+        rm -rf "$path_to_remove"
+      fi
+    done
+    if [[ -n "$TARBALL_PATH" && -f "$TARBALL_PATH" ]]; then
+      rm -f "$TARBALL_PATH"
+    fi
+  fi
+}
+trap cleanup EXIT
+
 echo "== release-check: ${NAME}@${VERSION}"
+node ./scripts/release-smoke-check.mjs assert-exact-host-contract \
+  --package-json package.json \
+  --host-version "$HOST_VERSION"
 
 if [[ -z "$REPOSITORY_URL" ]]; then
   echo "package.json repository.url is required for provenance release publishing." >&2
@@ -21,14 +128,17 @@ if [[ "$NAME" != "${NAME,,}" ]]; then
 fi
 
 echo "== npm pack --dry-run --json"
-PACK_JSON="$(npm pack --dry-run --json)"
+PACK_JSON="$(npm --cache "$CONTROL_NPM_CACHE" pack --dry-run --json)"
 echo "$PACK_JSON"
+if [[ -f "$REPO_ROOT/scripts/npm-pack-json.mjs" ]]; then
+  PACK_JSON="$(printf '%s' "$PACK_JSON" | node "$REPO_ROOT/scripts/npm-pack-json.mjs")"
+fi
 
 PACK_JSON="$PACK_JSON" node ./scripts/release-artifact-check.mjs
 
 echo "== npm publish --dry-run"
 set +e
-PUBLISH_DRY_RUN_OUTPUT="$(npm publish --dry-run 2>&1)"
+PUBLISH_DRY_RUN_OUTPUT="$(npm --cache "$CONTROL_NPM_CACHE" publish --dry-run 2>&1)"
 PUBLISH_DRY_RUN_EXIT=$?
 set -e
 echo "$PUBLISH_DRY_RUN_OUTPUT"
@@ -41,61 +151,26 @@ if [[ "$PUBLISH_DRY_RUN_EXIT" -ne 0 ]]; then
   fi
 fi
 
-TEST_AGENT_DIR=""
-TEST_NPM_PREFIX=""
-TEST_NPM_CACHE=""
-ARTIFACT_NPM_PREFIX=""
-ARTIFACT_NPM_CACHE=""
-ARTIFACT_TOOL_VENT_DIR=""
-TARBALL_CHECK_DIR=""
-TARBALL_PATH=""
-cleanup() {
-  if [[ "${KEEP_RELEASE_ARTIFACTS:-0}" != "1" ]]; then
-    if [[ -n "$TEST_AGENT_DIR" && -d "$TEST_AGENT_DIR" ]]; then
-      rm -rf "$TEST_AGENT_DIR"
-    fi
-    if [[ -n "$TEST_NPM_PREFIX" && -d "$TEST_NPM_PREFIX" ]]; then
-      rm -rf "$TEST_NPM_PREFIX"
-    fi
-    if [[ -n "$TEST_NPM_CACHE" && -d "$TEST_NPM_CACHE" ]]; then
-      rm -rf "$TEST_NPM_CACHE"
-    fi
-    if [[ -n "$ARTIFACT_NPM_PREFIX" && -d "$ARTIFACT_NPM_PREFIX" ]]; then
-      rm -rf "$ARTIFACT_NPM_PREFIX"
-    fi
-    if [[ -n "$ARTIFACT_NPM_CACHE" && -d "$ARTIFACT_NPM_CACHE" ]]; then
-      rm -rf "$ARTIFACT_NPM_CACHE"
-    fi
-    if [[ -n "$ARTIFACT_TOOL_VENT_DIR" && -d "$ARTIFACT_TOOL_VENT_DIR" ]]; then
-      rm -rf "$ARTIFACT_TOOL_VENT_DIR"
-    fi
-    if [[ -n "$TARBALL_CHECK_DIR" && -d "$TARBALL_CHECK_DIR" ]]; then
-      rm -rf "$TARBALL_CHECK_DIR"
-    fi
-    if [[ -n "$TARBALL_PATH" && -f "$TARBALL_PATH" ]]; then
-      rm -f "$TARBALL_PATH"
-    fi
-  fi
-}
-trap cleanup EXIT
-
 echo "== npm pack"
-TARBALL="$(npm pack --silent | tail -n 1)"
+TARBALL="$(npm --cache "$CONTROL_NPM_CACHE" pack --silent | tail -n 1)"
 TARBALL_PATH="$ROOT_DIR/$TARBALL"
 echo "Tarball: $TARBALL_PATH"
 
-TARBALL_CHECK_DIR="$(mktemp -d /tmp/pi-agent-vent-tarball-check-XXXXXX)"
+TARBALL_CHECK_DIR="$(release_tmp_dir tarball-check)"
+TARBALL_NPM_CACHE="$(release_tmp_dir tarball-npm-cache)"
 echo "== unpacked tarball package contract"
 tar -xzf "$TARBALL_PATH" -C "$TARBALL_CHECK_DIR"
 (
   cd "$TARBALL_CHECK_DIR/package"
-  npm install --ignore-scripts --no-audit --fund=false
+  # This isolated artifact probe intentionally selects the exact host contract above.
+  # Ordinary installs retain the workstation's npm release-age policy.
+  release_npm_install "$TARBALL_NPM_CACHE" -
   npm run check
 )
 
-ARTIFACT_NPM_PREFIX="$(mktemp -d /tmp/pi-agent-vent-artifact-npm-prefix-XXXXXX)"
-ARTIFACT_NPM_CACHE="$(mktemp -d /tmp/pi-agent-vent-artifact-npm-cache-XXXXXX)"
-ARTIFACT_TOOL_VENT_DIR="$(mktemp -d /tmp/pi-agent-vent-artifact-tool-store-XXXXXX)"
+ARTIFACT_NPM_PREFIX="$(release_tmp_dir artifact-npm-prefix)"
+ARTIFACT_NPM_CACHE="$(release_tmp_dir artifact-npm-cache)"
+ARTIFACT_TOOL_VENT_DIR="$(release_tmp_dir artifact-tool-store)"
 ARTIFACT_PACKAGE_ROOT="$(npm --prefix "$ARTIFACT_NPM_PREFIX" root -g)/$NAME"
 
 case "$ARTIFACT_PACKAGE_ROOT" in
@@ -107,8 +182,8 @@ case "$ARTIFACT_PACKAGE_ROOT" in
 esac
 
 echo "== npm installed artifact shadow registered-tool smoke (no Pi auth)"
-npm --prefix "$ARTIFACT_NPM_PREFIX" --cache "$ARTIFACT_NPM_CACHE" \
-  install --global --ignore-scripts --no-audit --fund=false "$TARBALL_PATH"
+release_npm_install "$ARTIFACT_NPM_CACHE" "$ARTIFACT_NPM_PREFIX" \
+  --prefix "$ARTIFACT_NPM_PREFIX" --global "$TARBALL_PATH"
 node ./scripts/release-smoke-check.mjs assert-installed-artifact \
   --package-root "$ARTIFACT_PACKAGE_ROOT" \
   --package-name "$NAME" \
@@ -124,15 +199,19 @@ else
     echo "pi CLI not found in PATH." >&2
     exit 1
   fi
+  INSTALLED_PI_VERSION="$(pi --version)"
+  node ./scripts/release-smoke-check.mjs assert-exact-host-contract \
+    --package-json package.json \
+    --host-version "$INSTALLED_PI_VERSION"
   if [[ ! -f "$HOME/.pi/agent/auth.json" ]]; then
     echo "Missing $HOME/.pi/agent/auth.json (needed for isolated pi smoke tests)." >&2
     echo "Tip: set SKIP_PI_SMOKE=1 for artifact-only checks." >&2
     exit 1
   fi
 
-  TEST_AGENT_DIR="$(mktemp -d /tmp/pi-extension-release-check-XXXXXX)"
-  TEST_NPM_PREFIX="$(mktemp -d /tmp/pi-extension-release-npm-prefix-XXXXXX)"
-  TEST_NPM_CACHE="$(mktemp -d /tmp/pi-extension-release-npm-cache-XXXXXX)"
+  TEST_AGENT_DIR="$(release_tmp_dir pi-agent-dir)"
+  TEST_NPM_PREFIX="$(release_tmp_dir pi-npm-prefix)"
+  TEST_NPM_CACHE="$(release_tmp_dir pi-npm-cache)"
 
   cp "$HOME/.pi/agent/auth.json" "$TEST_AGENT_DIR/auth.json"
 
@@ -153,8 +232,8 @@ JSON
 
   echo "== pi install tarball (isolated PI_CODING_AGENT_DIR and npm prefix)"
   PACKAGE_SPEC="npm:$TARBALL_PATH"
-  NPM_CONFIG_PREFIX="$TEST_NPM_PREFIX" NPM_CONFIG_CACHE="$TEST_NPM_CACHE" \
-    PI_CODING_AGENT_DIR="$TEST_AGENT_DIR" pi install "$PACKAGE_SPEC"
+  PI_CODING_AGENT_DIR="$TEST_AGENT_DIR" \
+    with_release_npm_policy "$TEST_NPM_CACHE" "$TEST_NPM_PREFIX" pi install "$PACKAGE_SPEC"
 
   echo "== verify tarball package recorded in settings"
   TEST_AGENT_DIR="$TEST_AGENT_DIR" PACKAGE_SPEC="$PACKAGE_SPEC" node <<'NODE'
@@ -178,14 +257,16 @@ NODE
 
   if [[ -x "./scripts/release-smoke.sh" ]]; then
     echo "== extension-specific smoke checks (scripts/release-smoke.sh)"
+    PI_INSTALLED_PACKAGE_ROOT="$TEST_AGENT_DIR/npm/node_modules/$NAME"
     NPM_CONFIG_PREFIX="$TEST_NPM_PREFIX" NPM_CONFIG_CACHE="$TEST_NPM_CACHE" \
-      PI_CODING_AGENT_DIR="$TEST_AGENT_DIR" PACKAGE_SPEC="$PACKAGE_SPEC" bash ./scripts/release-smoke.sh
+      PI_CODING_AGENT_DIR="$TEST_AGENT_DIR" PACKAGE_SPEC="$PACKAGE_SPEC" \
+      INSTALLED_PACKAGE_ROOT="$PI_INSTALLED_PACKAGE_ROOT" bash ./scripts/release-smoke.sh
   fi
 fi
 
 echo "== npm view ${NAME} version (pre-publish may be 404)"
 set +e
-npm view "$NAME" version --json --registry https://registry.npmjs.org/
+npm --cache "$CONTROL_NPM_CACHE" view "$NAME" version --json --registry https://registry.npmjs.org/
 VIEW_EXIT=$?
 set -e
 echo "npm view exit: $VIEW_EXIT"

package/scripts/release-smoke-check.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: supplies assertions and isolated tool-path probes for release smoke testing
+// read_when:
+//   - changing installed-artifact validation or agent_vent release smoke behavior
+// ---
+
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -5,6 +11,22 @@ import { pathToFileURL } from "node:url";
 
 export const readJsonFile = (filePath) => JSON.parse(fs.readFileSync(filePath, "utf8"));
 
+export const assertExactHostContract = ({ packageJson, hostVersion }) => {
+  const piAi = packageJson?.devDependencies?.["@earendil-works/pi-ai"];
+  const codingAgent = packageJson?.devDependencies?.["@earendil-works/pi-coding-agent"];
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(hostVersion || "")) {
+    throw new Error(
+      `Release smoke requires an exact Pi host version, got: ${hostVersion || "(empty)"}`,
+    );
+  }
+  if (piAi !== hostVersion || codingAgent !== hostVersion) {
+    throw new Error(
+      `Release smoke host contract mismatch: pi=${hostVersion}, pi-ai=${piAi || "(missing)"}, pi-coding-agent=${codingAgent || "(missing)"}`,
+    );
+  }
+  return hostVersion;
+};
+
 export const packageSourcesFromSettings = (settings) => {
   const packages = Array.isArray(settings?.packages) ? settings.packages : [];
   return packages
@@ -292,6 +314,15 @@ const readArgValue = (args, name) => {
 const runCli = async () => {
   const [command, ...args] = process.argv.slice(2);
 
+  if (command === "assert-exact-host-contract") {
+    const packageJsonPath = readArgValue(args, "--package-json");
+    const hostVersion = readArgValue(args, "--host-version");
+    if (!packageJsonPath) throw new Error("--package-json is required");
+    assertExactHostContract({ packageJson: readJsonFile(packageJsonPath), hostVersion });
+    console.log(`Exact Pi host contract selected: ${hostVersion}.`);
+    return;
+  }
+
   if (command === "assert-settings") {
     const settingsPath = readArgValue(args, "--settings");
     const packageSpec = readArgValue(args, "--package-spec");
@@ -353,7 +384,7 @@ const runCli = async () => {
   }
 
   throw new Error(
-    "Usage: node ./scripts/release-smoke-check.mjs <assert-settings|assert-local-tarball-install-source|assert-installed-artifact|prepare-local-path-artifact-settings|assert-command-output|assert-installed-tool-path> ...",
+    "Usage: node ./scripts/release-smoke-check.mjs <assert-exact-host-contract|assert-settings|assert-local-tarball-install-source|assert-installed-artifact|prepare-local-path-artifact-settings|assert-command-output|assert-installed-tool-path> ...",
   );
 };
 

package/scripts/release-smoke.sh

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+# ---
+# summary: smoke-tests the installed agent_vent package through isolated pi discovery
+# read_when:
+#   - verifying tarball installation, command output, or registered-tool execution
+# ---
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -14,6 +19,11 @@ if [[ -z "${PI_CODING_AGENT_DIR:-}" ]]; then
   exit 1
 fi
 
+if [[ -z "${INSTALLED_PACKAGE_ROOT:-}" ]]; then
+  echo "INSTALLED_PACKAGE_ROOT is required; the caller must provide Pi's isolated installed-artifact path." >&2
+  exit 1
+fi
+
 if ! command -v pi >/dev/null 2>&1; then
   echo "pi CLI not found in PATH." >&2
   exit 1
@@ -38,23 +48,15 @@ SMOKE_TOOL_VENT_DIR="$SMOKE_DIR/agent-vent-tool-store"
 SMOKE_LOCAL_PATH_OUTPUT="$SMOKE_DIR/agent-vent-local-path.out"
 PACKAGE_NAME="$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).name")"
 PACKAGE_VERSION="$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).version")"
-if [[ -n "${NPM_CONFIG_PREFIX:-}" ]]; then
-  GLOBAL_NODE_MODULES="$(npm --prefix "$NPM_CONFIG_PREFIX" root -g)"
-else
-  GLOBAL_NODE_MODULES="$(npm root -g)"
-fi
-INSTALLED_PACKAGE_ROOT="$GLOBAL_NODE_MODULES/$PACKAGE_NAME"
 INSTALLED_EXTENSION_PATH="$INSTALLED_PACKAGE_ROOT/extensions/agent-vent.ts"
 
-if [[ -n "${NPM_CONFIG_PREFIX:-}" ]]; then
-  case "$INSTALLED_PACKAGE_ROOT" in
-    "$NPM_CONFIG_PREFIX"/*) ;;
-    *)
-      echo "Installed package root escaped isolated npm prefix: $INSTALLED_PACKAGE_ROOT" >&2
-      exit 1
-      ;;
-  esac
-fi
+case "$(realpath -m "$INSTALLED_PACKAGE_ROOT")" in
+  "$(realpath "$PI_CODING_AGENT_DIR")"/*) ;;
+  *)
+    echo "Installed package root escaped isolated Pi agent directory: $INSTALLED_PACKAGE_ROOT" >&2
+    exit 1
+    ;;
+esac
 
 node ./scripts/release-smoke-check.mjs assert-settings \
   --settings "$PI_CODING_AGENT_DIR/settings.json" \

package/scripts/validate-structure.mjs

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+// ---
+// summary: enforces pi-agent-vent manifest, script, extension, and lane structure contracts
+// read_when:
+//   - editing package metadata, copier answers, publish files, or required npm scripts
+// ---
 
 import fs from "node:fs";
 
@@ -92,7 +97,7 @@ function validatePackageJson() {
     }
   }
 
-  const requiredPeers = ["@mariozechner/pi-coding-agent", "@mariozechner/pi-ai"];
+  const requiredPeers = ["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai"];
   for (const peer of requiredPeers) {
     if (typeof p.peerDependencies?.[peer] !== "string") {
       fail(`package.json peerDependencies must include ${peer}`);
@@ -129,8 +134,8 @@ function validatePackageJson() {
     fail("package.json publishConfig.access must be 'public'");
   }
 
-  if (p.engines?.node !== ">=22") {
-    fail("package.json engines.node must be '>=22'");
+  if (p.engines?.node !== ">=22.19.0") {
+    fail("package.json engines.node must be '>=22.19.0'");
   }
 
   const expectedWorkspacePath = readCopierAnswer("workspace_relative_path");

package/scripts/validate-structure.sh

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+# ---
+# summary: verifies the pi-agent-vent scaffold tree, executables, and markdown frontmatter
+# read_when:
+#   - checking filesystem conformance after package scaffold or documentation changes
+# ---
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -33,8 +38,8 @@ required_files=(
   "scripts/validate-structure.sh"
   "scripts/validate-structure.mjs"
   "scripts/quality-gate.sh"
-  "prompts/implementation-planning.md"
-  "prompts/security-review.md"
+  "prompts/pi-agent-vent-implementation-planning.md"
+  "prompts/pi-agent-vent-security-review.md"
 )
 
 required_dirs=(

package/src/vent-store.js

@@ -1,3 +1,9 @@
+// ---
+// summary: implements private agent vent storage, review projections, and retention safeguards
+// read_when:
+//   - changing diagnostic record schemas, redaction, curation, review, export, or retention logic
+// ---
+
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
@@ -22,6 +28,19 @@ export const CATEGORIES = [
   "workflow",
   "other",
 ];
+export const CATEGORY_ALIASES = Object.freeze({
+  workflow_friction: "workflow",
+  operator_friction: "workflow",
+  process_friction: "workflow",
+  missing_affordance: "missing_capability",
+  missing_feature: "missing_capability",
+  documentation_gap: "documentation",
+  docs_gap: "documentation",
+  context_window: "context_loss",
+  context_friction: "context_loss",
+  context_alignment: "other",
+  tooling_friction: "friction",
+});
 export const SEVERITIES = ["low", "medium", "high", "critical"];
 export const REVIEW_STATES = ["new", "acknowledged", "dismissed", "escalation_drafted"];
 export const CURATION_ACTIONS = ["merge", "rename", "remove"];
@@ -71,12 +90,22 @@ export function defaultBackupDir(env = process.env) {
   return path.join(defaultStoreDir(env), BACKUP_DIR_NAME);
 }
 
-export function normalizeCategory(value) {
-  const normalized = String(value || "other")
+export function normalizeCategoryToken(value) {
+  return String(value || "")
     .trim()
     .toLowerCase()
     .replaceAll("-", "_");
-  return CATEGORIES.includes(normalized) ? normalized : "other";
+}
+
+export function resolveCategoryFilter(value) {
+  const normalized = normalizeCategoryToken(value);
+  if (!normalized) return undefined;
+  const candidate = CATEGORY_ALIASES[normalized] || normalized;
+  return CATEGORIES.includes(candidate) ? candidate : undefined;
+}
+
+export function normalizeCategory(value) {
+  return resolveCategoryFilter(value || "other") || "other";
 }
 
 export function normalizeSeverity(value) {
@@ -227,6 +256,56 @@ function collectRedactionMetadata(fields) {
   return { redacted, redactionPatterns: [...redactionPatterns].sort() };
 }
 
+function hasDiagnosticAnchor(input = {}) {
+  return Boolean(
+    compactText(input?.frustration, 1200) ||
+      compactText(input?.evidence, 1600) ||
+      compactText(input?.expected, 800) ||
+      compactText(input?.actual, 800) ||
+      compactText(input?.reproduction, 1200) ||
+      compactText(input?.tool || input?.toolName, 160) ||
+      compactText(input?.packageName, 200) ||
+      compactText(input?.recurrenceKey, 200) ||
+      (Array.isArray(input?.tags) && input.tags.some((tag) => compactText(tag, 120))),
+  );
+}
+
+export function assessVentRecordQuality(input = {}, record = undefined) {
+  const summary = compactText(input?.summary ?? record?.summary, 600) || "";
+  const normalizedSummary = summary.toLowerCase();
+  const wordCount = normalizedSummary.split(/\s+/).filter(Boolean).length;
+  const anchored = hasDiagnosticAnchor(input);
+  const issues = [];
+  const warnings = [];
+
+  if (
+    /^(done|ok|okay|fixed|test|testing|progress|update|note|misc|bad|ugh)$/.test(normalizedSummary)
+  ) {
+    issues.push("summary is too generic for a diagnostic record");
+  }
+  if (summary.length < 12 && !anchored) {
+    issues.push("summary is too short without a diagnostic anchor");
+  }
+  if (wordCount < 4 && !anchored) {
+    warnings.push(
+      "add evidence, expected/actual, tool, package, tag, or recurrenceKey before recording",
+    );
+  }
+  if (normalizeCategory(input?.category ?? record?.category) === "other" && !anchored) {
+    warnings.push(
+      "category defaults to other; add a specific category or local diagnostic facet if known",
+    );
+  }
+
+  return {
+    recordable: issues.length === 0,
+    issues,
+    warnings,
+    boundary:
+      "Quality check is local anti-junk guidance only; it does not create AK evidence, tasks, issues, incidents, telemetry, owner routing, or ASC/self state.",
+  };
+}
+
 export function createVentRecord(input, context = {}) {
   const summary = sanitizeOptionalText(input?.summary, 600);
   if (!summary.value) {
@@ -2588,13 +2667,13 @@ function assertNoEmptyReviewFilterValues(input = {}) {
 
 function normalizeReviewFilterCategory(value) {
   if (value === undefined) return undefined;
-  const normalized = String(value).trim().toLowerCase().replaceAll("-", "_");
-  if (!CATEGORIES.includes(normalized)) {
+  const category = resolveCategoryFilter(value);
+  if (!category) {
     throw new Error(
       `invalid agent_vent review filter category: ${value}; expected one of ${CATEGORIES.join(", ")}`,
     );
   }
-  return normalized;
+  return category;
 }
 
 function sanitizeReviewFilterTags(value) {