@tryinget/pi-agent-vent 0.1.1 → 0.2.0

package/scripts/release-check.sh

@@ -8,7 +8,81 @@ NAME="$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf
 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/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/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 \
+    --ignore-scripts --no-audit --fund=false "$@"
+}
+
+CONTROL_NPM_CACHE="$(mktemp -d /tmp/pi-agent-vent-control-npm-cache-XXXXXX)"
+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 +95,14 @@ 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"
 
 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,55 +115,20 @@ 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_NPM_CACHE="$(mktemp -d /tmp/pi-agent-vent-tarball-npm-cache-XXXXXX)"
 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
 )
 
@@ -107,8 +146,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 +163,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="$(mktemp -d /tmp/pi-agent-vent-pi-agent-dir-XXXXXX)"
+  TEST_NPM_PREFIX="$(mktemp -d /tmp/pi-agent-vent-pi-npm-prefix-XXXXXX)"
+  TEST_NPM_CACHE="$(mktemp -d /tmp/pi-agent-vent-pi-npm-cache-XXXXXX)"
 
   cp "$HOME/.pi/agent/auth.json" "$TEST_AGENT_DIR/auth.json"
 
@@ -153,8 +196,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 +221,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

@@ -5,6 +5,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 +308,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 +378,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

@@ -14,6 +14,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 +43,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

@@ -92,7 +92,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 +129,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

@@ -33,8 +33,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

@@ -22,6 +22,18 @@ 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",
+  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 +83,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 +249,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 +2660,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) {

package/tests/agent-vent-extension.test.js

@@ -3,15 +3,17 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
-import agentVentExtension from "../extensions/agent-vent.ts";
+import agentVentExtension, { _test } from "../extensions/agent-vent.ts";
 import { createCurationEvent, createVentRecord, readReviewEvents } from "../src/vent-store.js";
 
 function createMockPi() {
   const tools = new Map();
   const commands = new Map();
+  const messages = [];
   return {
     tools,
     commands,
+    messages,
     api: {
       registerTool(tool) {
         tools.set(tool.name, tool);
@@ -19,6 +21,9 @@ function createMockPi() {
       registerCommand(name, command) {
         commands.set(name, command);
       },
+      sendMessage(message) {
+        messages.push(message);
+      },
     },
   };
 }
@@ -39,6 +44,8 @@ test("agent_vent tool schema stays aligned with retention candidate and compare
   const schemaText = JSON.stringify(pi.tools.get("agent_vent").parameters);
 
   assert.match(schemaText, /"compare"/);
+  assert.match(schemaText, /"preview"/);
+  assert.match(schemaText, /"workflow_friction"/);
   assert.match(schemaText, /"candidates"/);
   assert.match(schemaText, /"history"/);
   assert.match(schemaText, /retentionCandidateState/);
@@ -48,6 +55,41 @@ test("agent_vent tool schema stays aligned with retention candidate and compare
   assert.match(schemaText, /outcomes, compare, export, or retention planning/);
 });
 
+test("agent_vent keeps long command output persistent while short statuses stay notifications", async () => {
+  const pi = createMockPi();
+  agentVentExtension(pi.api);
+  const notifications = [];
+  const ctx = { hasUI: true, ui: { notify: (message) => notifications.push(message) } };
+
+  await pi.commands.get("agent_vent").handler("help", ctx);
+  assert.equal(pi.messages.length, 1);
+  assert.equal(pi.messages[0].customType, "agent-vent-command");
+  assert.match(pi.messages[0].content, /agent_vent commands/);
+  assert.match(notifications[0], /added to the session transcript/);
+
+  await pi.commands.get("agent_vent").handler("unknown", ctx);
+  assert.equal(pi.messages.length, 1);
+  assert.match(notifications[1], /Unknown \/agent_vent action/);
+  assert.equal(_test.isLongCommandOutput("short"), false);
+});
+
+test("agent_vent cancellation fails before expensive store work", async () => {
+  const pi = createMockPi();
+  agentVentExtension(pi.api);
+  const controller = new AbortController();
+  controller.abort();
+  await assert.rejects(
+    () =>
+      pi.tools
+        .get("agent_vent")
+        .execute("cancelled", { action: "summary" }, controller.signal, undefined, {
+          cwd: "/repo",
+          sessionManager: { getSessionFile: () => undefined },
+        }),
+    /cancelled/,
+  );
+});
+
 test("agent_vent records minimized local diagnostics without external authority claims", async () => {
   const pi = createMockPi();
   agentVentExtension(pi.api);
@@ -474,6 +516,129 @@ test("agent_vent records minimized local diagnostics without external authority
   }
 });
 
+test("agent_vent accepts category aliases for tool records and command filters", async () => {
+  const pi = createMockPi();
+  agentVentExtension(pi.api);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-alias-"));
+  const oldDir = process.env.PI_AGENT_VENT_DIR;
+  const oldLog = console.log;
+  const messages = [];
+  process.env.PI_AGENT_VENT_DIR = dir;
+  console.log = (message) => messages.push(String(message));
+  try {
+    const tool = pi.tools.get("agent_vent");
+    const result = await tool.execute(
+      "tool-call-category-alias",
+      {
+        action: "record",
+        summary: "Workflow friction alias should normalize",
+        category: "workflow_friction",
+        severity: "medium",
+      },
+      undefined,
+      undefined,
+      {
+        cwd: "/repo",
+        sessionManager: { getSessionFile: () => undefined },
+      },
+    );
+
+    assert.equal(result.details.record.category, "workflow");
+    assert.equal(
+      result.details.record.recurrenceKey,
+      "workflow:workflow-friction-alias-should-normalize",
+    );
+
+    const reviewResult = await tool.execute(
+      "tool-call-category-alias-review",
+      { action: "review", category: "workflow_friction" },
+      undefined,
+      undefined,
+      {
+        cwd: "/repo",
+        sessionManager: { getSessionFile: () => undefined },
+      },
+    );
+    assert.equal(reviewResult.details.reviewQueue.filters.category, "workflow");
+    assert.equal(reviewResult.details.reviewQueue.matchingGroupCount, 1);
+
+    await pi.commands.get("agent_vent").handler("review category=workflow_friction", {
+      hasUI: false,
+    });
+    assert.match(messages[0], /Filters: category=workflow/);
+    assert.doesNotMatch(messages[0], /category=workflow_friction/);
+  } finally {
+    console.log = oldLog;
+    if (oldDir === undefined) delete process.env.PI_AGENT_VENT_DIR;
+    else process.env.PI_AGENT_VENT_DIR = oldDir;
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("agent_vent preview runs anti-junk checks without writing records", async () => {
+  const pi = createMockPi();
+  agentVentExtension(pi.api);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-preview-"));
+  const oldDir = process.env.PI_AGENT_VENT_DIR;
+  process.env.PI_AGENT_VENT_DIR = dir;
+  try {
+    const tool = pi.tools.get("agent_vent");
+    const preview = await tool.execute(
+      "tool-call-preview",
+      {
+        action: "preview",
+        summary: "Workflow friction alias should normalize before recording",
+        category: "workflow_friction",
+        tool: "self",
+      },
+      undefined,
+      undefined,
+      {
+        cwd: "/repo",
+        sessionManager: { getSessionFile: () => undefined },
+      },
+    );
+
+    assert.equal(preview.details.wouldRecord, true);
+    assert.equal(preview.details.recordPreview.category, "workflow");
+    assert.match(preview.content[0].text, /No local diagnostic record was written/);
+    assert.equal(fs.existsSync(path.join(dir, "vents.jsonl")), false);
+
+    const junkPreview = await tool.execute(
+      "tool-call-preview-junk",
+      { action: "preview", summary: "done" },
+      undefined,
+      undefined,
+      {
+        cwd: "/repo",
+        sessionManager: { getSessionFile: () => undefined },
+      },
+    );
+    assert.equal(junkPreview.details.wouldRecord, false);
+    assert.match(junkPreview.content[0].text, /not recordable/);
+
+    await assert.rejects(
+      () =>
+        tool.execute(
+          "tool-call-record-junk",
+          { action: "record", summary: "done" },
+          undefined,
+          undefined,
+          {
+            cwd: "/repo",
+            sessionManager: { getSessionFile: () => undefined },
+          },
+        ),
+      /anti-junk quality check/,
+    );
+    assert.equal(fs.existsSync(path.join(dir, "vents.jsonl")), false);
+  } finally {
+    if (oldDir === undefined) delete process.env.PI_AGENT_VENT_DIR;
+    else process.env.PI_AGENT_VENT_DIR = oldDir;
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("agent_vent command rejects unknown review filter keys without creating stores", async () => {
   const pi = createMockPi();
   agentVentExtension(pi.api);