@tryinget/pi-agent-vent 0.1.2 → 0.2.0

package/README.md

@@ -45,11 +45,12 @@ Then in Pi:
 
 ## Tool behavior
 
-`agent_vent` supports fourteen actions:
+`agent_vent` supports fifteen actions:
 
 | Action | Purpose |
 |---|---|
-| `record` | Append a minimized vent record. Requires `summary`. |
+| `record` | Append a minimized vent record. Requires `summary` and must pass the local anti-junk quality check. |
+| `preview` | Build the sanitized would-be record and anti-junk quality result without writing the local store. |
 | `summary` | Show recurrence groups and advisory candidate incidents. |
 | `list` | Show recent local records. |
 | `path` | Show the store path and boundary contract. |
@@ -99,11 +100,14 @@ The runtime-facing name is intentionally singular: use `agent_vent` for the LLM
 
 `pi-agent-vent` is a companion to `pi-autonomous-session-control`, not part of it. ASC/`self` remains the execution and operational-mirror owner; this package owns only local vent diagnostics.
 
+For the cross-package handoff between ASC `self` diagnostic candidates, toolbox activation, and `agent_vent` preview/record writes, see [Self, toolbox, and agent_vent diagnostic boundary](docs/project/2026-06-05-self-toolbox-agent-vent-diagnostic-boundary.md).
+
 When `pi-toolbox-discovery` is installed, it exposes the `agent_vent` bundle so agents can discover or activate the same-named `agent_vent` tool on demand:
 
 ```ts
 toolbox({ action: "search", query: "vent" })
 toolbox({ action: "activate", bundle: "agent_vent" })
+agent_vent({ action: "preview", summary: "...", category: "workflow", tool: "..." })
 ```
 
 The owner extension must still be installed/reloaded so the `agent_vent` tool is registered before toolbox can activate it.
@@ -157,6 +161,7 @@ Product docs:
 - [Vision](docs/project/vision.md)
 - [Product posture](docs/project/product-posture.md)
 - [Agent vent design](docs/project/2026-05-21-agent-vent-design.md)
+- [Self/toolbox/agent_vent diagnostic boundary](docs/project/2026-06-05-self-toolbox-agent-vent-diagnostic-boundary.md)
 - [Implementation plan](docs/project/2026-05-21-agent-vent-implementation-plan.md)
 
 ## Package checks
@@ -168,7 +173,9 @@ npm install
 npm run check
 ```
 
-For release confidence, `npm run release:check` packs the package, verifies packaged docs/scripts, runs the packaged fallback gate, installs the tarball into an isolated npm prefix for a no-auth shadow registered-tool `agent_vent path` smoke, then installs the tarball with isolated Pi settings and npm prefix/cache, validates that local `npm:<tarball>` is being used only as the install source, and smokes the installed artifact through local-path Pi package discovery with `/agent_vent path`. Use `npm run release:check:quick` for artifact-only checks when live Pi smoke is not available; quick checks still include the no-auth installed shadow registered-tool smoke. These smokes prove artifact/package-loading behavior only, not npm/GitHub publication or provenance.
+For release confidence, `npm run release:check` packs the package, verifies packaged docs/scripts, runs the packaged fallback gate, installs the tarball into an isolated npm prefix for a no-auth shadow registered-tool `agent_vent path` smoke, then installs the tarball with isolated Pi settings and npm prefix/cache, validates that local `npm:<tarball>` is being used only as the install source, and smokes the installed artifact through local-path Pi package discovery with `/agent_vent path`. Use `npm run release:check:quick` for artifact-only checks when live Pi smoke is not available; quick checks still include the no-auth installed shadow registered-tool smoke.
+
+Release probes pin `pi-ai` and `pi-coding-agent` to one exact version and fail before installation if that contract diverges from the selected/installed Pi host. Only the isolated artifact/probe installs set `min-release-age=0`, allowing a newly selected exact host contract to be tested while ordinary installs continue to obey the workstation supply-chain cutoff. These smokes prove artifact/package-loading behavior only, not npm/GitHub publication or provenance.
 
 Run from monorepo root through the canonical package gate:
 

package/docs/engineering.local.md

@@ -55,3 +55,16 @@ Not selected by default:
 - Authority: candidate incidents are recommendations only; do not create or imply AK/GitHub/incident mutations.
 - Validation: `npm run check` from this package, or root `bash ./scripts/package-quality-gate.sh ci packages/pi-agent-vent`.
 - Optional companions are intentionally not adopted for v0.1: no `fast-check`, Cucumber, Nunjucks, or ts-quality rollout.
+
+## Repo loop validation
+
+`@tryinget/pi-agent-vent` adopts `repo-loop-validation-v1` for package-local loop prompt dogfooding. The policy declaration is in `policy/engineering-lane.json`.
+
+- `loop-doctor`: `npm run loop-doctor` (non-failing Node/npm/package/git diagnostics)
+- `loop-verify-fast`: `npm run loop-verify-fast` (maps to `quality:pre-commit`)
+- `loop-impact-plan`: `npm run loop-impact-plan` (coarse package impact note plus changed-file listing)
+- `loop-impact-run`: `npm run loop-impact-run` (maps to `npm run check`)
+- `loop-impact-wide`: `npm run loop-impact-wide` (explicit full package gate, also `npm run check`)
+- `loop-landing-check`: `npm run loop-landing-check` (maps to `npm run check`)
+
+These commands produce package-local evidence for orchestration prompts. They do not replace Pi runtime install/reload proof, release approval, or monorepo owner authority.

package/docs/project/2026-05-21-agent-vent-design.md

@@ -95,7 +95,8 @@ The tool prompt and runtime validation both bias toward minimal summaries:
 
 Actions:
 
-- `record` — append a vent record.
+- `record` — append a vent record after the local anti-junk quality check accepts it.
+- `preview` — build the sanitized would-be record and anti-junk quality result without writing the local store.
 - `summary` — summarize recurrence groups and candidate incidents.
 - `list` — show recent records.
 - `path` — show local store path and data contract.
@@ -112,7 +113,8 @@ Actions:
 
 Important behavior:
 
-- `record` requires `summary`.
+- `record` requires `summary` and rejects low-signal generic payloads such as `done`.
+- `preview` returns `recordPreview`, `quality`, and `wouldRecord` without appending JSONL; use it before `record` when the candidate came from `self`, another tool, or a generic/friction-heavy moment.
 - `severity` defaults to `medium`.
 - `category` defaults to `other`.
 - `recurrenceKey` may be supplied by the agent; otherwise it is derived from category + summary.
@@ -164,11 +166,11 @@ This heuristic intentionally errs toward surfacing review candidates, not assert
 
 ## Cross-package integration
 
-`pi-agent-vent` remains separate from `pi-autonomous-session-control` by design:
+`pi-agent-vent` remains separate from `pi-autonomous-session-control` by design. The detailed handoff is documented in [Self, toolbox, and agent_vent diagnostic boundary](2026-06-05-self-toolbox-agent-vent-diagnostic-boundary.md):
 
-- ASC/`self` owns operational introspection, subagent/runtime control, and mirror-only handoff/progress summaries.
-- `pi-agent-vent` owns local diagnostic vent records, redaction, recurrence grouping, and advisory candidate-incident heuristics.
+- ASC/`self` owns operational introspection, subagent/runtime control, mirror-only handoff/progress summaries, and typed `self.diagnostic_candidate.v1` suggestions.
 - `pi-toolbox-discovery` owns discovery/activation of the already-registered `agent_vent` tool through the same-named `agent_vent` bundle; `agent-vent` is not a runtime alias.
+- `pi-agent-vent` owns local diagnostic vent records, preview quality checks, redaction, recurrence grouping, and advisory candidate-incident heuristics.
 
 This keeps vent persistence from becoming hidden ASC state while still making the capability discoverable during autonomous work.
 

package/docs/project/2026-06-05-self-toolbox-agent-vent-diagnostic-boundary.md

@@ -0,0 +1,66 @@
+---
+summary: "Boundary contract for self diagnostic candidates, toolbox activation, and agent_vent local diagnostic records."
+read_when:
+  - "Changing ASC self diagnostic-review output."
+  - "Changing toolbox agent_vent bundle discovery or activation guidance."
+  - "Changing agent_vent preview/record behavior or diagnostic authority wording."
+system4d:
+  container: "Cross-package diagnostic handoff boundary."
+  compass: "Make recurring friction visible without turning diagnostics into authority."
+  engine: "self mirrors candidate -> toolbox activates bundle -> agent_vent previews/records local diagnostics -> human decides owner escalation."
+  fog: "Diagnostic candidates and local records can be mistaken for tasks, evidence, incidents, telemetry, or ASC state."
+---
+
+# Self, toolbox, and agent_vent diagnostic boundary
+
+## Purpose
+
+This note documents the intended handoff between three Pi extension surfaces:
+
+1. `self` from `pi-autonomous-session-control` notices current-session friction and can return a typed `self.diagnostic_candidate.v1` payload.
+2. `toolbox` from `pi-toolbox-discovery` can discover or activate the already-registered `agent_vent` tool on demand.
+3. `agent_vent` from `pi-agent-vent` can preview or record minimized local diagnostic records in its append-only local store.
+
+The chain is deliberately not an escalation pipeline. It is a low-cost local diagnostic path for repeated bugs, tool failures, workflow friction, context loss, missing affordances, and similar agent-experience problems.
+
+## Ownership contract
+
+| Surface | Owns | Does not own |
+|---|---|---|
+| `self` | Moment-level mirror of the current session; candidate diagnostic payloads; suggested next local actions. | Durable vent records, recurrence truth, AK evidence/tasks, GitHub issues, incidents, telemetry, or owner routing. |
+| `toolbox` | Bundle discovery, risk posture, and active-tool-set changes for already-registered tools. | Registering missing owner tools, validating vent quality, storing diagnostics, or deciding escalation. |
+| `agent_vent` | Local JSONL diagnostic records, preview quality checks, redaction, recurrence grouping, review state, curation, draft-only text, export, and retention lifecycle. | AK evidence/tasks, GitHub issues, real incidents, external telemetry, ASC/self state, publication, or owner-system lifecycle. |
+
+## Safe handoff sequence
+
+Use this sequence when a session notices recurring or high-friction behavior worth possible local memory:
+
+```ts
+self({ query: "What friction just happened?" })
+toolbox({ action: "activate", bundle: "agent_vent" })
+agent_vent({ action: "preview", summary: "...", category: "...", tool: "...", packageName: "..." })
+agent_vent({ action: "record", summary: "...", category: "...", tool: "...", packageName: "..." })
+```
+
+Rules:
+
+- `self` may prefill or suggest an `agent_vent` payload, but it must not write the record internally.
+- `toolbox` activation only makes the `agent_vent` tool callable; it does not create or preview a diagnostic record.
+- `agent_vent action=preview` sanitizes the would-be record and runs the anti-junk quality check without writing the store.
+- `agent_vent action=record` writes only if the local quality check accepts the payload.
+- Generic low-signal summaries such as `done` are rejected for `record`; use `preview` to inspect issues and warnings before writing.
+- Human/operator judgment still decides whether any recurrence should become an AK task, GitHub issue, incident review, evidence record, publication, or owner-surface handoff.
+
+## Copy wording for boundaries
+
+Recommended short wording:
+
+> Diagnostic review is mirror/local only: `self` can propose a candidate, `toolbox` can activate the `agent_vent` capability, and `agent_vent` can preview or write local diagnostic memory. None of these actions create AK evidence/tasks, GitHub issues, incidents, external telemetry, publication, owner routing, or ASC/self state.
+
+Use stronger wording when a durable local write happened:
+
+> A local `agent_vent` record was written to the operator's Pi diagnostic store. This is recurrence memory for review, not canonical evidence, task truth, issue state, incident declaration, telemetry, publication, or owner-system mutation.
+
+## Review and escalation posture
+
+`agent_vent` recurrence groups and candidate incidents mean “worth human review,” not “incident declared.” Draft outputs are paste-ready text only. Exports are diagnostic projections only. If a human decides a local recurrence deserves owner action, use the owning surface directly and record evidence there according to that owner’s rules.

package/docs/project/product-posture.md

@@ -114,6 +114,8 @@ The highest-leverage product line is:
 local vent capture -> operator review queue -> draft-only owner routing -> human-approved escalation
 ```
 
+For visible self-evolution work, keep `agent_vent` as recurrence memory and review queue only. The DRY routing map lives in the root `docs/project/visible-self-evolution-spine.md` spine; orchestrator may project verified evidence, while AK/society owner surfaces retain durable authority.
+
 Do not add automatic GitHub/AK/incident writers. The local facet summary, fail-closed facet-filtered local review queue, per-state review outcome follow-up, read-only cross-state review comparison, explicit local decision posture, filter-preserving supported follow-up commands, record/state-scoped facet export, export-local-follow-up guidance, read-only retention-candidate planning, read-only retention-history receipt projection, advisory human-review hints, quoted state-aware next-action guidance, bounded review-detail samples, curation-aware recurrence resolution, facet-aware draft-only routing, retention archive/restore, and privacy membrane now have package validation; remaining product depth should refine operator comprehension only where it does not broaden authority. Hard-delete beyond backup-backed archive is decided out of v0.1: permanent removal remains operator-owned filesystem/data-lifecycle control unless a future decision accepts a narrower purge design.
 
 Current proof: `npm run check` passes with 80 package tests plus release dry-run, packaged Markdown link checks, an unpacked-tarball `npm install && npm run check` contract smoke that runs the packaged fallback gate from inside the artifact, an artifact-only no-auth installed shadow registered-tool `agent_vent path` no-store-read smoke, and a full installed-tarball local-path package-discovery `/agent_vent path` smoke using isolated `PI_CODING_AGENT_DIR`, isolated npm prefix/cache, and `PI_AGENT_VENT_DIR`; docs strict check passes, `git diff --check` passes, and historical dogfood covered curation resolution, export posture, and live `pi install` reload behavior. Validation now covers quoted rollback commands, complete retention token inputs, stale-token/stale-restore failures, path-escape/symlink backup failures, receipt-failure rollback, retention-history restore-candidate reconstruction without active-store reads, export follow-up command quoting without archive/restore tokens or owner-routing claims, review decision-posture projection without resolution/assignment/evidence/incident claims, curation-aware recurrence resolution for review state and record feedback, stale lock cleanup, backup restore, duplicate-id-safe retention archive selection, retention-candidate planning without archive tokens, retention-candidate and compare tool-schema/command-contract parity, filter-preserving supported compare follow-ups, record/state-scoped facet export without owner-routing claims, mixed-group export non-broadening, empty export filters failing closed before store reads, tag/facet privacy metadata recomputation, hostile legacy JSONL privacy recomputation, fail-closed review/outcome/compare/export/retention-candidate/history syntax before store reads including empty filters, invalid review category/state handling, explicit per-state outcome/compare limits, quoted legacy recurrence-key command round trips, tool-only maintainer-note hints, reference-style packaged Markdown links, fail-closed `files[]` wildcard handling, public artifact script viability, release metadata alignment with `.copier-answers.yml`, local `npm:<tarball>` install-source validation, isolated installed-command smoke output, local-path package-discovery loading from the installed artifact, shadow registered-tool execution from the installed artifact, and registered-tool `path` no-store-read/no-store-write behavior with symlinked active stores.

package/docs/project/vision.md

@@ -44,6 +44,10 @@ agent notices recurring friction
 -> owner system receives a human-approved draft only when appropriate
 ```
 
+For self-evolution loops, `agent_vent` is the recurrence-memory surface after ASC/self has produced a diagnostic candidate.
+It is not the loop executor, evaluator, or escalation authority.
+Use the root `docs/project/visible-self-evolution-spine.md` spine and the cross-package [self/toolbox/agent_vent diagnostic boundary](./2026-06-05-self-toolbox-agent-vent-diagnostic-boundary.md) for the DRY owner map.
+
 Near-term product work should make the review step better rather than broadening authority. Useful next surfaces include:
 
 - `/agent_vent review` for an operator-facing review queue;

package/extensions/agent-vent.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
   appendCurationEvent,
@@ -7,6 +7,7 @@ import {
   appendVentRecord,
   archiveRecurrenceGroup,
   assertCanCurateRecurrence,
+  assessVentRecordQuality,
   buildEscalationDraft,
   buildFacetSummary,
   buildLifecycleSnapshot,
@@ -49,6 +50,7 @@ import {
   normalizeReviewState,
   RETENTION_ACTIONS,
   readRetentionEvents,
+  resolveCategoryFilter,
   resolveRecurrenceGroup,
   restoreRetentionBackup,
   SEVERITIES,
@@ -59,6 +61,7 @@ import {
 
 const ACTIONS = [
   "record",
+  "preview",
   "summary",
   "list",
   "path",
@@ -79,6 +82,19 @@ const REVIEW_STATES = Array.isArray(STORE_REVIEW_STATES)
   ? STORE_REVIEW_STATES
   : FALLBACK_REVIEW_STATES;
 const RETENTION_CANDIDATE_STATES = ["reviewed", "all", ...REVIEW_STATES] as const;
+const CATEGORY_ALIAS_INPUTS = [
+  "workflow_friction",
+  "operator_friction",
+  "process_friction",
+  "missing_affordance",
+  "missing_feature",
+  "documentation_gap",
+  "docs_gap",
+  "context_window",
+  "context_friction",
+  "tooling_friction",
+] as const;
+const CATEGORY_INPUTS = [...CATEGORIES, ...CATEGORY_ALIAS_INPUTS] as const;
 
 const AgentVentParams = Type.Object({
   action: Type.Optional(
@@ -92,9 +108,10 @@ const AgentVentParams = Type.Object({
   ),
   category: Type.Optional(
     Type.Union(
-      CATEGORIES.map((category) => Type.Literal(category)),
+      CATEGORY_INPUTS.map((category) => Type.Literal(category)),
       {
-        description: "Local category for the frustration pattern.",
+        description:
+          "Local category for the frustration pattern. Common aliases are accepted and normalized to canonical categories.",
       },
     ),
   ),
@@ -235,11 +252,12 @@ export default function agentVentExtension(pi: ExtensionAPI) {
     name: "agent_vent",
     label: "Agent Vent",
     description:
-      "Record, review, and inspect local agent frustration events so recurring bugs, workflow friction, and missing affordances become visible.",
+      "Record, preview, review, and inspect local agent frustration events so recurring bugs, workflow friction, and missing affordances become visible.",
     promptSnippet:
-      "Record minimized local frustration events and review recurring patterns without creating incidents, tasks, issues, evidence records, or telemetry.",
+      "Preview or record minimized local frustration events and review recurring patterns without creating incidents, tasks, issues, evidence records, or telemetry.",
     promptGuidelines: [
       "Use agent_vent when you encounter recurring agent frustration, long-lived bugs, repeated tool/runtime failures, context-loss patterns, or missing affordances worth later human review.",
+      "Use action=preview before action=record when the diagnostic may be generic, low-signal, or copied from another tool; previews run the anti-junk quality check without writing the local store.",
       "Use action=review to inspect the local recurrence review queue; include recurrenceKey to inspect bounded representative samples for one local group; optionally filter review by local category, tag, tool, or package facets; use action=set_review to mark a recurrence group as new, acknowledged, dismissed, or escalation_drafted.",
       "Use action=outcomes for read-only post-review follow-up across local review-state buckets; outcome guidance is local diagnostic UX only, not owner routing or external completion.",
       "Use action=compare for a read-only cross-state review comparison before export, retention planning, or draft-only handoff; comparison output emits no archive/restore tokens and mutates nothing.",
@@ -253,7 +271,8 @@ export default function agentVentExtension(pi: ExtensionAPI) {
       "When calling agent_vent, summarize minimally and never include secrets, credentials, private user payloads, or long raw logs.",
     ],
     parameters: AgentVentParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      throwIfCancelled(signal);
       const storePath = defaultStorePath();
       const reviewPath = defaultReviewPath();
       const curationPath = defaultCurationPath();
@@ -275,13 +294,29 @@ export default function agentVentExtension(pi: ExtensionAPI) {
         );
       }
 
-      if (action === "record") {
+      if (action === "preview" || action === "record") {
         const sessionFile = ctx.sessionManager.getSessionFile();
         const record = createVentRecord(params, {
           cwd: ctx.cwd,
           sessionFile: sessionFile ? path.basename(sessionFile) : undefined,
-          source: "agent_vent_tool",
+          source: action === "preview" ? "agent_vent_preview" : "agent_vent_tool",
         });
+        const quality = assessVentRecordQuality(params, record);
+        if (action === "preview") {
+          return textResult(formatRecordPreview(record, quality), {
+            action,
+            storePath,
+            recordPreview: record,
+            quality,
+            wouldRecord: quality.recordable,
+          });
+        }
+        if (!quality.recordable) {
+          throw new Error(
+            `agent_vent record rejected by anti-junk quality check: ${quality.issues.join("; ")}`,
+          );
+        }
+        throwIfCancelled(signal);
         appendVentRecord(storePath, record);
         const state = loadDiagnosticState({
           storePath,
@@ -331,6 +366,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
         });
       }
 
+      throwIfCancelled(signal);
       const state = loadDiagnosticState({
         storePath,
         reviewPath,
@@ -367,6 +403,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
         };
         assertCanCurateRecurrence(records, curationEvents, input);
         const event = createCurationEvent(input, { source: "agent_vent_tool" });
+        throwIfCancelled(signal);
         appendCurationEvent(curationPath, event);
         const targetText = event.targetRecurrenceKey ? ` -> ${event.targetRecurrenceKey}` : "";
         const text = [
@@ -400,6 +437,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
           },
           { source: "agent_vent_tool" },
         );
+        throwIfCancelled(signal);
         appendReviewEvent(reviewPath, event);
         const text = [
           `Set local review state for ${event.recurrenceKey} to ${event.state}.`,
@@ -610,6 +648,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
           });
         }
         if (retentionAction === "archive") {
+          throwIfCancelled(signal);
           const result = archiveRecurrenceGroup({
             storePath,
             reviewPath,
@@ -632,6 +671,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
             retention: result,
           });
         }
+        throwIfCancelled(signal);
         const result = restoreRetentionBackup({
           storePath,
           retentionPath,
@@ -737,15 +777,31 @@ function registerAgentVentCommand(pi: ExtensionAPI, name: string, description: s
     description,
     handler: async (args, ctx) => {
       const output = handleCommand(args);
-      if (ctx.hasUI) {
-        ctx.ui.notify(output, "info");
-      } else {
+      if (!ctx.hasUI) {
         console.log(output);
+      } else if (isLongCommandOutput(output)) {
+        pi.sendMessage({
+          customType: "agent-vent-command",
+          content: output,
+          display: true,
+          details: { command: name },
+        });
+        ctx.ui.notify("agent_vent output added to the session transcript", "info");
+      } else {
+        ctx.ui.notify(output, "info");
       }
     },
   });
 }
 
+function isLongCommandOutput(output: string): boolean {
+  return output.length > 500 || output.split("\n").length > 8;
+}
+
+function throwIfCancelled(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new Error("agent_vent cancelled");
+}
+
 function handleCommand(args: string) {
   const tokens = splitCommandArgs(args);
   const action = tokens[0] || "summary";
@@ -759,6 +815,7 @@ function handleCommand(args: string) {
     return [
       "agent_vent commands:",
       "  /agent_vent summary                                  Show recurrence groups and candidate incidents.",
+      "  LLM tool action=preview                              Preview a local diagnostic record and anti-junk quality check without writing the store.",
       "  /agent_vent list [limit]                             Show recent local vent records.",
       "  /agent_vent facets [limit]                           Show read-only local category/tag/tool/package facets.",
       "  /agent_vent review [state|all] [limit] [category=bug] [tag=reload] [tool=pi-reload] [package=tryinget-pi-agent-vent]",
@@ -1084,8 +1141,8 @@ function parseReviewListTokens(tokens: string[], options: { allowReviewedState?:
           invalidFilters.push("category=");
           continue;
         }
-        const normalizedCategory = value.toLowerCase().replaceAll("-", "_");
-        if (CATEGORIES.includes(normalizedCategory)) filters.category = normalizedCategory;
+        const category = resolveCategoryFilter(value);
+        if (category) filters.category = category;
         else invalidFilters.push(`category=${value}`);
       } else if (key === "tool") {
         if (!value) {
@@ -1374,6 +1431,24 @@ function formatDiagnosticWarnings(state: Record<string, unknown>) {
     : "";
 }
 
+function formatRecordPreview(
+  record: Record<string, unknown>,
+  quality: { recordable?: boolean; issues?: string[]; warnings?: string[]; boundary?: string },
+) {
+  const issues = quality.issues || [];
+  const warnings = quality.warnings || [];
+  return [
+    `Agent vent preview: ${quality.recordable ? "recordable" : "not recordable"} (${record.severity || "medium"}/${record.category || "other"}) under ${record.recurrenceKey || "unknown"}.`,
+    `Summary: ${record.summary || "(no summary)"}`,
+    issues.length ? `Issues: ${issues.join("; ")}` : "Issues: none",
+    warnings.length ? `Warnings: ${warnings.join("; ")}` : "Warnings: none",
+    "No local diagnostic record was written. Use action=record only if this is a recurring or review-worthy diagnostic, not an ordinary progress update.",
+    `Boundary: ${quality.boundary || "local diagnostic preview only"}`,
+  ].join("\n");
+}
+
+export const _test = { isLongCommandOutput, throwIfCancelled };
+
 function textResult(text: string, details: Record<string, unknown>) {
   return {
     content: [{ type: "text" as const, text }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryinget/pi-agent-vent",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Local pi tool for agents to record recurring frustrations, bugs, and workflow friction without creating incidents or external telemetry",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "fix": "bash ./scripts/quality-gate.sh fix",
@@ -43,7 +43,13 @@
     "docs:list:workspace": "bash ./scripts/docs-list.sh --workspace --discover",
     "docs:list:json": "bash ./scripts/docs-list.sh --json",
     "release:check": "bash ./scripts/release-check.sh",
-    "release:check:quick": "SKIP_PI_SMOKE=1 bash ./scripts/release-check.sh"
+    "release:check:quick": "SKIP_PI_SMOKE=1 bash ./scripts/release-check.sh",
+    "loop-doctor": "bash -lc 'node --version; npm --version; npm pkg get name version >/dev/null; git status --short -- . || true; exit 0'",
+    "loop-verify-fast": "npm run quality:pre-commit",
+    "loop-impact-plan": "bash -lc 'echo \"loop-impact-plan: package-local impact planner is coarse; run npm run loop-impact-run for the full package gate.\"; git status --short -- . || true'",
+    "loop-impact-run": "npm run check",
+    "loop-impact-wide": "npm run check",
+    "loop-landing-check": "npm run check"
   },
   "files": [
     "extensions/agent-vent.ts",
@@ -60,6 +66,7 @@
     "docs/project/product-posture.md",
     "docs/project/2026-05-21-agent-vent-design.md",
     "docs/project/2026-05-21-agent-vent-implementation-plan.md",
+    "docs/project/2026-06-05-self-toolbox-agent-vent-diagnostic-boundary.md",
     "docs/project/extension-sop.md",
     "docs/project/trusted-publishing.md",
     "docs/adr/2026-05-22-agent-vent-retention-delete-policy.md"
@@ -79,17 +86,19 @@
     "releaseConfigMode": "component"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.14"
+    "@biomejs/biome": "2.3.14",
+    "@earendil-works/pi-ai": "0.80.6",
+    "@earendil-works/pi-coding-agent": "0.80.6"
   },
   "overrides": {
     "fast-xml-parser": "5.3.6"
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
   "dependencies": {
-    "typebox": "^1.0.0"
+    "typebox": "*"
   }
 }

package/policy/engineering-lane.json

@@ -17,6 +17,18 @@
       "dependency-governance",
       "specification-and-dsls",
       "engineering-reasoning"
-    ]
+    ],
+    "loop_validation": {
+      "version": "repo-loop-validation-v1",
+      "contract_doc": "docs/engineering.local.md#repo-loop-validation",
+      "commands": {
+        "loop-doctor": "npm run loop-doctor",
+        "loop-verify-fast": "npm run loop-verify-fast",
+        "loop-impact-plan": "npm run loop-impact-plan",
+        "loop-impact-run": "npm run loop-impact-run",
+        "loop-impact-wide": "npm run loop-impact-wide",
+        "loop-landing-check": "npm run loop-landing-check"
+      }
+    }
   }
 }

package/prompts/{implementation-planning.md → pi-agent-vent-implementation-planning.md}

@@ -1,8 +1,8 @@
 ---
-summary: "Monorepo package implementation planning prompt template."
+summary: "pi-agent-vent implementation planning prompt template."
 read_when:
   - "Using or updating the monorepo package implementation-planning prompt template."
-description: Draft an implementation plan for a requested change
+description: Draft an implementation plan for a requested pi-agent-vent change
 system4d:
   container: "Prompt template for implementation planning."
   compass: "Turn requests into actionable, risk-aware plans."
@@ -10,7 +10,7 @@ system4d:
   fog: "Hidden constraints unless assumptions are surfaced."
 ---
 
-Create an implementation plan for this request: $@
+Create a pi-agent-vent implementation plan for this request: $@
 
 Include:
 - Scope and non-goals

package/prompts/{security-review.md → pi-agent-vent-security-review.md}

@@ -1,8 +1,8 @@
 ---
-summary: "Monorepo package security review prompt template."
+summary: "pi-agent-vent security review prompt template."
 read_when:
   - "Using or updating the monorepo package security-review prompt template."
-description: Review a change for security risks and mitigations
+description: Review a pi-agent-vent change for security risks and mitigations
 system4d:
   container: "Prompt template for security-focused review."
   compass: "Identify practical vulnerabilities before release."
@@ -10,7 +10,7 @@ system4d:
   fog: "Partial context can hide exploit paths."
 ---
 
-Review this change for security concerns: $@
+Review this pi-agent-vent change for security concerns: $@
 
 Focus on:
 - Input validation and injection risk

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);

package/tests/release-smoke-check.test.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import test from "node:test";
 import {
   assertAgentVentPathSmokeOutput,
+  assertExactHostContract,
   assertInstalledArtifactPackage,
   assertLocalTarballInstallSource,
   assertPackageSpecInstalled,
@@ -13,6 +14,24 @@ import {
   packageSourcesFromSettings,
 } from "../scripts/release-smoke-check.mjs";
 
+test("release smoke release-age bypass is gated by one exact host contract", () => {
+  const packageJson = {
+    devDependencies: {
+      "@earendil-works/pi-ai": "0.80.6",
+      "@earendil-works/pi-coding-agent": "0.80.6",
+    },
+  };
+  assert.equal(assertExactHostContract({ packageJson, hostVersion: "0.80.6" }), "0.80.6");
+  assert.throws(
+    () => assertExactHostContract({ packageJson, hostVersion: "^0.80.6" }),
+    /requires an exact Pi host version/,
+  );
+  assert.throws(
+    () => assertExactHostContract({ packageJson, hostVersion: "0.80.7" }),
+    /host contract mismatch/,
+  );
+});
+
 test("release smoke settings check accepts only unfiltered string package entries", () => {
   const settings = {
     packages: [

package/tests/vent-store.test.js

@@ -111,6 +111,30 @@ test("createVentRecord minimizes, redacts, and derives recurrence key", () => {
   assert.deepEqual(tagOnlySecret.privacy.redactionPatterns, ["assigned_secret"]);
 });
 
+test("category aliases normalize at record and review-filter boundaries", () => {
+  const workflow = createVentRecord({
+    summary: "Workflow alias should not degrade",
+    category: "workflow_friction",
+    recurrenceKey: "workflow alias",
+  });
+  const missing = createVentRecord({
+    summary: "Missing affordance alias should preserve meaning",
+    category: "missing_affordance",
+  });
+
+  assert.equal(workflow.category, "workflow");
+  assert.equal(workflow.recurrenceKey, "workflow:workflow-alias");
+  assert.equal(missing.category, "missing_capability");
+  assert.match(missing.recurrenceKey, /^missing_capability:/);
+
+  const queue = summarizeReviewQueue([workflow, missing], [], {
+    filters: { category: "workflow_friction" },
+  });
+  assert.equal(queue.filters.category, "workflow");
+  assert.equal(queue.matchingGroupCount, 1);
+  assert.equal(queue.items[0].recurrenceKey, workflow.recurrenceKey);
+});
+
 test("explicit recurrence keys are redacted before slugging", () => {
   const record = createVentRecord({
     summary: "Explicit key should not leak",