@tryinget/pi-agent-vent 0.1.2 → 0.2.1

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,69 @@
+---
+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.
+- `self.diagnostic_candidate.v1` exposes separate `agentVentSuggestionAllowed` and `agentVentRecordAllowed` permissions. Plain `no agent_vent` / `no-agent_vent` constraints suppress activation, preview, and record guidance. Record-only `no agent_vent record` / `no-agent_vent-record` constraints preserve non-mutating preview guidance while marking durable recording forbidden.
+- ASC category `context_alignment` is accepted by `agent_vent` as a compatibility alias and normalized to canonical category `other`; the alias does not add a new canonical category.
+- The toolbox bundle currently exposes only its `default` diagnostic profile. Keep a call read-only by choosing `agent_vent` actions such as `preview`, `review`, or `stats`; do not invent `profile=read`.
+- 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,11 @@
+// ---
+// summary: registers the agent_vent tool and command for local diagnostic review workflows
+// read_when:
+//   - changing agent vent actions, command parsing, tool schemas, or authority boundaries
+// ---
+
 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 +13,7 @@ import {
   appendVentRecord,
   archiveRecurrenceGroup,
   assertCanCurateRecurrence,
+  assessVentRecordQuality,
   buildEscalationDraft,
   buildFacetSummary,
   buildLifecycleSnapshot,
@@ -49,6 +56,7 @@ import {
   normalizeReviewState,
   RETENTION_ACTIONS,
   readRetentionEvents,
+  resolveCategoryFilter,
   resolveRecurrenceGroup,
   restoreRetentionBackup,
   SEVERITIES,
@@ -59,6 +67,7 @@ import {
 
 const ACTIONS = [
   "record",
+  "preview",
   "summary",
   "list",
   "path",
@@ -79,6 +88,20 @@ 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",
+  "context_alignment",
+  "tooling_friction",
+] as const;
+const CATEGORY_INPUTS = [...CATEGORIES, ...CATEGORY_ALIAS_INPUTS] as const;
 
 const AgentVentParams = Type.Object({
   action: Type.Optional(
@@ -92,9 +115,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 +259,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 +278,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 +301,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 +373,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
         });
       }
 
+      throwIfCancelled(signal);
       const state = loadDiagnosticState({
         storePath,
         reviewPath,
@@ -367,6 +410,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 +444,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 +655,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
           });
         }
         if (retentionAction === "archive") {
+          throwIfCancelled(signal);
           const result = archiveRecurrenceGroup({
             storePath,
             reviewPath,
@@ -632,6 +678,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
             retention: result,
           });
         }
+        throwIfCancelled(signal);
         const result = restoreRetentionBackup({
           storePath,
           retentionPath,
@@ -737,15 +784,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 +822,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 +1148,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 +1438,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.1",
   "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.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0"
   },
   "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": "1.3.7"
   }
 }

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/docs-list.sh

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+# ---
+# summary: locates and invokes documentation listing support for pi-agent-vent
+# read_when:
+#   - enumerating package docs or overriding the docs-list implementation
+# ---
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

package/scripts/quality-gate.sh

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+# ---
+# summary: runs pi-agent-vent quality stages through the root gate or package fallback
+# read_when:
+#   - checking lint, types, tests, or scaffold structure in varied checkout layouts
+# ---
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"