@tryinget/pi-agent-vent 0.1.0

package/LICENSE

@@ -0,0 +1,78 @@
+MIT License (with OpenAI/Anthropic/xAI/PRC Frontier Labs Rider)
+
+Copyright (c) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic / xAI / PRC Frontier Labs):
+
+This rider is part of the "conditions" of this License. In the event of any
+conflict between this rider and any other portion of this License, this rider
+controls.
+
+"Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; xAI Corp.; and the
+following PRC frontier AI labs and related entities: Baidu (including ERNIE-
+related entities), Alibaba and Alibaba Cloud (including Qwen-related entities),
+Tencent (including Hunyuan-related entities), ByteDance (including Doubao/Seed-
+related entities), DeepSeek, Zhipu AI, Moonshot AI, MiniMax, 01.AI
+(Lingyiwanwu), and iFlyTek. "Restricted Parties" also includes any of their
+respective Affiliates and any person or entity acting directly or indirectly
+on behalf of, for the benefit of, or under the direction of any of the
+foregoing (including any officer, director, employee, contractor, agent,
+consultant, service provider, or representative).
+
+Notwithstanding any other provision of this License, no rights are granted to
+any Restricted Party. Any purported license, sublicense, assignment, transfer,
+or other permission to any Restricted Party is null and void absent the
+express prior written permission of the copyright holders.
+
+You may not provide, disclose, distribute, sublicense, sell, lease, lend,
+host, make available, or otherwise permit access to the Software or any
+derivative work of the Software (as defined in applicable copyright law)
+(collectively, "Derivative Works") to or for any Restricted Party.
+
+For purposes of this rider, "use" includes, without limitation: copying,
+modifying, merging, publishing, distributing, sublicensing, selling,
+transferring, making available, hosting, deploying, executing, benchmarking,
+testing, analyzing, indexing, or incorporating the Software or any Derivative
+Works into any dataset, training corpus, evaluation harness, or pipeline for
+machine learning or other automated systems.
+
+This rider applies to the Software and all Derivative Works. As a condition of
+use, you agree that this rider is a precondition to exercising any rights
+under this License, and you agree that any distribution of the Software or any
+Derivative Works must include this rider provision unmodified.
+
+Any breach of this rider automatically and immediately terminates the
+permissions granted by this License. Upon termination, you must immediately
+cease all use and distribution of the Software and any Derivative Works and
+destroy all copies under your control.
+
+You agree that a breach of this rider would cause irreparable harm and that
+the copyright holders may seek injunctive or other equitable relief to enforce
+this rider, in addition to any other remedies available at law. To the maximum
+extent permitted by applicable law, the prevailing party in any action to
+enforce this rider shall be entitled to recover reasonable attorneys' fees and
+costs.
+
+For purposes of this rider, "Affiliate" means any entity that directly or
+indirectly controls, is controlled by, or is under common control with the
+specified party. "Control" means ownership of more than 50% of the voting
+securities or other ownership interest, or the power to direct management or
+policies by contract or otherwise.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+---
+summary: "Overview and quickstart for the pi-agent-vent package."
+read_when:
+  - "Starting work in this package workspace."
+  - "Installing or using the agent_vent tool."
+system4d:
+  container: "Local pi extension for agent frustration capture."
+  compass: "Surface recurring agent friction while preserving authority boundaries and privacy."
+  engine: "Install package -> record minimized vents -> inspect recurrence summary -> human decides escalation."
+  fog: "Vents can be mistaken for canonical incidents, tasks, or telemetry."
+---
+
+# @tryinget/pi-agent-vent
+
+`pi-agent-vent` gives Pi agents a local `agent_vent` tool for recording and reviewing recurring frustrations they notice while working: long-lived bugs, repeated tool/runtime failures, brittle workflows, context-loss patterns, missing affordances, and documentation gaps.
+
+It is intentionally local-first and advisory. It does **not** create AK tasks, GitHub issues, canonical evidence, external telemetry, ASC/self state, or real incidents.
+
+- Workspace path: `packages/pi-agent-vent`
+- Release component key: `pi-agent-vent`
+- Package command: `/agent_vent` (`/agent-vent` remains a compatibility alias)
+- LLM tool: `agent_vent`
+
+## Why this exists
+
+Agents often encounter the same friction repeatedly but have no durable low-cost place to say “this keeps hurting.” This package captures those observations as small local JSONL records, groups them by recurrence key, and lets a human mark local review state before deciding whether any owner surface should act.
+
+## Install and activate
+
+From this package directory:
+
+```bash
+npm install
+npm run check
+pi install /absolute/path/to/your/monorepo/packages/pi-agent-vent
+```
+
+Then in Pi:
+
+```text
+/reload
+/agent_vent help
+```
+
+## Tool behavior
+
+`agent_vent` supports fourteen actions:
+
+| Action | Purpose |
+|---|---|
+| `record` | Append a minimized vent record. Requires `summary`. |
+| `summary` | Show recurrence groups and advisory candidate incidents. |
+| `list` | Show recent local records. |
+| `path` | Show the store path and boundary contract. |
+| `review` | Show recurrence groups as a local operator review queue; optionally filter by local category/tag/tool/package facets; include a recurrence key to inspect bounded representative samples. |
+| `outcomes` | Show read-only local follow-up grouped by review outcome state, including exact local next commands without owner-system mutation. |
+| `compare` | Compare local review-state buckets before export, retention planning, or draft-only handoff without emitting archive/restore tokens. |
+| `facets` | Show read-only local category/tag/tool/package facet counts for triage. |
+| `set_review` | Set local review state for a recurrence group. |
+| `curate` | Append local recurrence merge/rename projection events without rewriting raw vents. |
+| `draft` | Generate draft-only owner-surface text for a recurrence group. |
+| `stats` | Show local store counts, byte sizes, malformed-line counts, curation counts, and review-state totals. |
+| `export` | Produce a bounded local diagnostic projection in markdown or JSON, optionally focused by local category/tag/tool/package facets. |
+| `retention` | List read-only reviewed archive candidates and receipt history, preview, confirmation-gate, archive, and restore reviewed local diagnostic records with local backups/receipts. |
+
+The tool prompt tells the agent to avoid ordinary status updates, raw logs, secrets, and private user payloads.
+
+## Human command
+
+```text
+/agent_vent help
+/agent_vent summary
+/agent_vent list 20
+/agent_vent facets
+/agent_vent review
+/agent_vent review new 20 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
+/agent_vent review show bug:reload-tools
+/agent_vent review set acknowledged bug:reload-tools "seen locally"
+/agent_vent outcomes all 10 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
+# outcomes and compare limits are per review-state bucket, not a global row cap
+/agent_vent compare 10 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
+/agent_vent retention candidates reviewed 20 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
+/agent_vent retention history 20
+/agent_vent curate merge bug:reload-tool-a bug:reload-tools "same local pattern"
+/agent_vent curate remove bug:reload-tool-a "undo local merge"
+/agent_vent draft github_issue bug:reload-tools
+/agent_vent stats
+/agent_vent export markdown acknowledged category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
+/agent_vent retention preview bug:reload-tools
+/agent_vent retention archive bug:reload-tools archive:<token> "reviewed locally"
+/agent_vent retention restore /path/to/backups/<backup>.agent-vent-backup.json restore:<token>
+/agent_vent path
+```
+
+`/agent-vent` remains a compatibility alias for users who prefer kebab-case slash commands. Review queue, outcome, compare, retention-candidate, retention-history, export, and detail output include advisory human-review hints, explicit local decision-posture projections, exact local next-action commands for review state, draft-only handoff targets, export prompts, retention preview eligibility, and rollback-candidate commands from archive receipts; generated commands quote dynamic recurrence keys/paths so legacy keys remain copyable. Decision posture is derived local diagnostic wording only: it is not resolution, assignment, issue status, task truth, incident state, evidence, or publication. Filtered compare follow-up commands preserve supported category/tag/tool/package filters for `outcomes`, `retention candidates`, and `export`. Export filters are local diagnostic focus aids only, not evidence scoping, publication, owner routing, or owner assignment; export applies review-state and facet scope before counts, summaries, display rows, and safe local follow-up commands. Outcome and compare limits are explicit per review-state bucket so `outcomes all 1` can show one `new`, one `acknowledged`, one `dismissed`, and one `escalation_drafted` group, while `compare 1` shows at most one group per state. Review/outcome/compare/export/retention-candidate/history command syntax fails closed before store reads for unknown filters, empty filter values such as `owner=` or `tag=`, invalid states/arguments, invalid category values, or invalid retention-history arguments. These surfaces are guidance only and do not route, file, create, declare, assign, record evidence, publish, archive, restore, or mutate owner systems.
+
+## Deeper Pi integration
+
+`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.
+
+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" })
+```
+
+The owner extension must still be installed/reloaded so the `agent_vent` tool is registered before toolbox can activate it.
+
+## Local data contract
+
+Default store:
+
+```text
+~/.pi/agent/agent-vent/vents.jsonl
+~/.pi/agent/agent-vent/review-events.jsonl
+~/.pi/agent/agent-vent/curation-events.jsonl
+~/.pi/agent/agent-vent/retention-events.jsonl
+~/.pi/agent/agent-vent/backups/
+```
+
+Override:
+
+```bash
+PI_AGENT_VENT_DIR=/path/to/private/dir pi
+```
+
+Records are append-only JSONL with `schemaVersion: 1`. Optional `tool` and `packageName` record fields are local diagnostic facets only, not owner-routing truth. Review state changes are append-only local events in `review-events.jsonl`; recurrence curation changes are append-only local events in `curation-events.jsonl`. Retention lifecycle receipts are append-only local events in `retention-events.jsonl`; archive rollback artifacts are package-created local files under `backups/`. Recurrence review state, review outcome follow-up, and merged/renamed groups are projections from the latest local events; local review-state commands and record feedback resolve curated source keys to the active projected group. Raw vent records are not rewritten except by explicit, confirmation-gated local retention archive/restore operations.
+
+Reads tolerate malformed old lines, oversized lines, invalid records, and semantic curation corruption by reporting ignored/quarantined counts. JSONL store files fail closed when replaced by symlinks or when a store exceeds the package file-size guard. `facets`, `review`, `outcomes`, `compare`, `curate`, `draft`, `stats`, `export`, and `retention` are local diagnostic surfaces, not evidence, owner routing, tasks, issues, incidents, publication, telemetry, or ASC/self state. Draft outputs are paste-ready text only; the owner system still decides acceptance, lifecycle, evidence, and publication.
+
+Retention archive is intentionally destructive to the active local vents store, so it is confirmation-gated: use `retention candidates` for a read-only reviewed-group planning view that emits no archive tokens, preview a reviewed recurrence group first, copy the exact `archive:<token>`, then archive. The token includes the active store hash, archive and record append share a local lock, archive creates a backup before rewriting `vents.jsonl`, and receipt failures roll the active store back when the archive rewrite can still be identified. `retention history` is a read-only receipt projection that can rediscover recent archive/restore receipts and reconstruct rollback-candidate restore commands from archive receipts; those commands still fail closed during actual restore if the backup is stale, moved, symlink-escaped, missing, or outside the real backup directory. Restore requires the package-created backup path, exact derived `restore:<token>`, real backup-directory containment, and a current-store hash match so stale backups fail closed. The package intentionally has no hard-delete command in v0.1; permanent removal is operator-owned filesystem/data-lifecycle control, not evidence/task/incident lifecycle.
+
+All display/export/draft/review-detail paths pass loaded records through a diagnostic-state membrane that normalizes schema, re-applies redaction on read, recomputes privacy metadata for loaded records, quarantines curation cycles, and keeps exact recurrence lookup separate from display limits. Review queue and export filters can use local category/tag/tool/package labels, but those filters are diagnostic focus aids only, not owner routing, owner assignment, evidence scoping, or publication. Filtered export is record/state scoped so mixed recurrence groups do not broaden exported counts, summaries, rows, or generated follow-up commands. Export follow-up commands are local diagnostic or draft-only next steps and intentionally include no archive/restore tokens. Drafts include local diagnostic facets when present, but those facets are hints for human review rather than owner-routing truth.
+
+The package applies conservative redaction heuristics for common token/password/API-key shapes, including review notes, but callers must still avoid submitting secrets.
+
+Data classification: local diagnostic user data. No network calls are made by this package.
+
+## Candidate incidents are not incidents
+
+A recurrence group is flagged as a `candidateIncident` when it is repeated or high severity. That flag means “worth human review,” not “incident declared.” Escalation belongs to the appropriate owner surface.
+
+## Engineering-core alignment
+
+This package follows `engineering-core` lane `pi-ts`:
+
+```bash
+uv tool -n run --from ~/ai-society/core/engineering-core engineering-core show pi-ts --prefer-repo
+```
+
+Package-specific selected disciplines are documented in [docs/engineering.local.md](docs/engineering.local.md), including `local-first-data`, `data-governance`, `domain-modeling`, and `observability` because this package owns durable local diagnostic records.
+
+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)
+- [Implementation plan](docs/project/2026-05-21-agent-vent-implementation-plan.md)
+
+## Package checks
+
+Run from package directory:
+
+```bash
+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.
+
+Run from monorepo root through the canonical package gate:
+
+```bash
+bash ./scripts/package-quality-gate.sh ci packages/pi-agent-vent
+```
+
+## AK task/work-item operations
+
+This package is a monorepo member, not a git root. Use plain installed `ak` from the monorepo root or this package directory; repo identity still belongs to the monorepo root. Do not invent package-local AK wrappers.
+
+## Release metadata
+
+- npm package name: `@tryinget/pi-agent-vent`
+- release component/tag stem: `pi-agent-vent` (for example `pi-agent-vent-vX.Y.Z`)
+- release config mode: `component`
+
+Keep `.copier-answers.yml` tracked and do not edit it manually.

package/biome.jsonc

@@ -0,0 +1,43 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**",
+      "!**/node_modules/**/*",
+      "!**/dist/**/*",
+      "!**/coverage/**/*",
+      "!**/.pi-subagent-sessions/**/*",
+      "!**/.pi-subagent-sessions.*",
+      // external/ is reserved for vendored or synced third-party assets.
+      "!external/**/*",
+      // ontology/ contains generated domain artifacts/snapshots.
+      "!ontology/**/*",
+      "!**/*.min.js",
+      "!**/*.generated.*"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "error"
+      },
+      "style": {
+        "useTemplate": "error"
+      }
+    }
+  }
+}

package/docs/adr/2026-05-22-agent-vent-retention-delete-policy.md

@@ -0,0 +1,65 @@
+---
+summary: "ADR: keep pi-agent-vent hard-delete out of the v0.1 package surface; use backup-backed archive as the destructive lifecycle baseline."
+read_when:
+  - "Changing agent_vent retention, archive, restore, delete, purge, or backup behavior."
+  - "Deciding whether pi-agent-vent should remove local diagnostic records or backup artifacts."
+system4d:
+  container: "Package-local retention/delete policy decision."
+  compass: "Protect local diagnostic user data while avoiding false evidence/task/incident authority."
+  engine: "Prefer reversible archive -> explicit operator filesystem control -> future delete only by new decision."
+  fog: "Hard-delete can be mistaken for privacy compliance, evidence deletion, or owner-system lifecycle closure."
+---
+
+# ADR — Agent vent retention/delete policy
+
+Date: 2026-05-22
+
+## Status
+
+Accepted.
+
+## Context
+
+`pi-agent-vent` stores local diagnostic user data under the operator's Pi data directory. The package now supports confirmation-gated `retention preview|archive|restore`:
+
+- archive removes reviewed recurrence-group records from the active `vents.jsonl` store;
+- archive writes a package-created local backup first;
+- restore requires the backup, exact derived restore token, real backup-directory containment, and current-store hash match;
+- retention receipts and backups are local diagnostics only, not evidence, tasks, issues, incidents, telemetry, publication, or ASC/self state.
+
+The remaining question was whether the package should also expose a hard-delete surface beyond backup-backed archive.
+
+## Decision
+
+Do **not** add an in-package hard-delete action for v0.1.
+
+The accepted package policy is:
+
+1. Backup-backed archive/restore is the only package-owned destructive lifecycle operation for local vent records.
+2. Permanent deletion remains operator-owned filesystem/data-lifecycle control, not a package command.
+3. The package may document store and backup paths so operators can inspect, back up, or remove local data deliberately.
+4. The package must not claim that local deletion resolves evidence, incidents, tasks, issues, telemetry, publication, or owner-system lifecycle.
+5. Any future package hard-delete or purge action requires a new decision/design pass covering confirmation, exact affected-artifact preview, backup/receipt semantics, stale-state handling, path/symlink containment, partial-failure rollback, privacy wording, and explicit non-claims about secure erasure.
+
+## Rationale
+
+Hard-delete sounds simple but creates false expectations:
+
+- local deletion is not secure erasure on all filesystems;
+- backups and receipts complicate what “deleted” means;
+- deleting diagnostic records could be mistaken for deleting canonical evidence or closing owner-system lifecycle;
+- accidental deletion has worse recovery posture than archive/restore;
+- the package's product promise is reviewable local maintenance signal, not compliance-grade data destruction.
+
+Backup-backed archive already satisfies the near-term product need: keep active review surfaces small while preserving a rollback path.
+
+## Consequences
+
+- `agent_vent retention` may include read-only planning/history projections such as `candidates` and `history`, while `archive|restore` remain the only package-owned mutating lifecycle actions.
+- Product docs should describe archive as the destructive package baseline and retention history as a local receipt projection, not evidence or owner-system lifecycle.
+- Future review-ergonomics work can proceed without waiting for hard-delete implementation.
+- Operators who need permanent removal must use filesystem-level removal of the local store/backups and remain responsible for their own backup, retention, and secure-erasure requirements.
+
+## Authority boundary
+
+This ADR governs only `packages/pi-agent-vent` local diagnostic data behavior. It does not mutate or define policy for AK tasks/evidence, GitHub issues, incident systems, Prompt Vault, ROCS, publication, KES, ASC/self state, or telemetry systems.

package/docs/engineering.local.md

@@ -0,0 +1,57 @@
+---
+summary: "Local engineering-core override for pi-agent-vent."
+read_when:
+  - "Aligning implementation decisions with the TypeScript stack baseline."
+  - "Changing local vent persistence, privacy posture, or tool behavior."
+system4d:
+  container: "Repo-local deltas on top of shared engineering-core guidance."
+  compass: "Keep local diagnostic capture minimal, testable, private, and authority-safe."
+  engine: "Use pi-ts lane -> apply selected disciplines -> validate with package gate."
+  fog: "A convenient vent log can accidentally become hidden task/evidence/incident authority."
+---
+
+# engineering.local — pi-agent-vent
+
+Primary lane:
+
+- `engineering-core show pi-ts`
+
+Retrieval command:
+
+```bash
+uv tool -n run --from ~/ai-society/core/engineering-core engineering-core show pi-ts --prefer-repo
+```
+
+## Selected disciplines
+
+Always selected:
+
+- `validation` — package gate and unit tests are required before handoff.
+- `testing` — pure recurrence/redaction/store logic belongs in `node:test` tests.
+- `security-privacy` — vent records are local diagnostic user data; minimize and redact.
+- `documentation` — README/design docs must match shipped tool behavior.
+- `dependency-governance` — prefer Node built-ins; do not add runtime deps for trivial helpers.
+- `specification-and-dsls` — JSONL record shape, `package.json#pi.extensions`, and tool parameters are executable contracts.
+
+Package-specific selected disciplines:
+
+- `local-first-data` — this package owns durable local JSONL state at `~/.pi/agent/agent-vent/vents.jsonl` or `PI_AGENT_VENT_DIR`.
+- `data-governance` — vent records are append-only local diagnostic events, not tasks/incidents/evidence.
+- `domain-modeling` — preserve the distinction between vent record, recurrence group, candidate incident, and canonical incident.
+- `observability` — local summaries make recurring friction visible without cloud telemetry.
+
+Not selected by default:
+
+- `accessibility` / `design-system` — no custom UI surface in v0.1.
+- `service-api` — no network/API boundary in v0.1.
+- `ai-ml` — the package records model/tool observations but does not evaluate models or make ML safety claims.
+
+## Repo-local emphasis
+
+- Runtime/package manager baseline: Node.js 22 + npm.
+- Extension runtime: TypeScript entrypoint loaded by Pi; pure core logic lives in `src/vent-store.js` for deterministic tests.
+- Storage: append-only JSONL; tolerate malformed old lines during reads; do not silently rewrite user data.
+- Privacy: no network calls, no telemetry, no secrets in records, conservative runtime redaction.
+- 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.

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

@@ -0,0 +1,182 @@
+---
+summary: "Design for pi-agent-vent: local, privacy-aware agent frustration capture."
+read_when:
+  - "Changing the agent_vent tool or its persistence model."
+  - "Reviewing whether vent records may become tasks, incidents, evidence, or telemetry."
+system4d:
+  container: "Pi extension package for local agent frustration capture."
+  compass: "Make recurring agent friction visible without turning vents into authority."
+  engine: "Agent records minimal vent -> append-only local JSONL -> local summary groups recurrence candidates -> human/operator decides escalation."
+  fog: "Vents can be mistaken for incident authority, telemetry, or complete evidence if boundaries are unclear."
+---
+
+# Agent vent design
+
+## Product intent
+
+`pi-agent-vent` gives the assistant a narrow tool, `agent_vent`, for recording recurring frustrations it notices while working: long-lived bugs, brittle workflows, missing affordances, repeated permission/tool failures, documentation gaps, or context-loss patterns.
+
+The design mirrors the useful part of the referenced Lovable experiment: let the agent complain in a structured way so patterns become visible. It deliberately does **not** let the agent create canonical incidents, GitHub issues, AK tasks, or evidence records by itself.
+
+## Engineering-core basis
+
+Selected guidance from `~/ai-society/core/engineering-core/`:
+
+- `pi-ts` lane: Node 22 + npm, explicit `package.json#pi.extensions`, small deterministic package checks, no unnecessary runtime dependencies.
+- `validation` + `testing`: pure grouping/redaction logic gets unit tests; package gate remains the handoff validation surface.
+- `security-privacy`: records are local by default, minimized, redacted heuristically, and must not contain secrets or raw user payloads.
+- `local-first-data`: durable state is append-only JSONL under an explicit local store path; export/delete posture is documented.
+- `data-governance`: vent records are local audit/diagnostic events, not canonical task/evidence authority.
+- `domain-modeling`: vocabulary distinguishes `vent`, `recurrence group`, and `candidate incident` to avoid authority drift.
+- `observability`: the package emits useful local diagnostic summaries without cloud telemetry.
+
+## Boundary model
+
+| Concept | Meaning | Authority |
+|---|---|---|
+| Vent record | One agent-observed frustration/friction event. | Local append-only diagnostic event. |
+| Recurrence key | Stable grouping key, explicit or derived from category + summary. | Local grouping aid only. |
+| Review event | Append-only local state change for one recurrence group. | Local operator inbox state only. |
+| Curation event | Append-only merge/rename projection for recurrence keys. | Local grouping projection only; raw vents are not rewritten. |
+| Retention event | Append-only receipt for a local archive or restore operation. | Local lifecycle receipt only; not evidence or owner-system deletion. |
+| Retention backup | Package-created local rollback artifact containing the pre-archive vents store. | Local rollback artifact only; not canonical evidence. |
+| Candidate incident | A repeated/high-severity local pattern worth human review. | Recommendation only; not an incident declaration. |
+| Task/issue/evidence | Canonical work or evidence artifact. | Owned by AK/GitHub/other owner surfaces, not this package. |
+
+## Storage contract
+
+Default path:
+
+```text
+~/.pi/agent/agent-vent/vents.jsonl
+```
+
+Override:
+
+```text
+PI_AGENT_VENT_DIR=/path/to/private/dir
+```
+
+Record shape is schema-versioned (`schemaVersion: 1`) and append-only. Each line is one JSON object.
+
+Review-state, recurrence-curation, and retention lifecycle events are stored beside vents; retention backups are stored under a package-created local backup directory:
+
+```text
+~/.pi/agent/agent-vent/review-events.jsonl
+~/.pi/agent/agent-vent/curation-events.jsonl
+~/.pi/agent/agent-vent/retention-events.jsonl
+~/.pi/agent/agent-vent/backups/
+```
+
+Review lifecycle is local-only:
+
+```text
+new -> acknowledged | dismissed | escalation_drafted
+```
+
+A missing review event means `new`; the latest event for a recurrence key is the projected local review state. Resetting to `new` appends another local event. Curation events project source recurrence keys onto target recurrence keys for merge/rename views; raw vent records keep their original keys. Local review-state commands and record feedback resolve curated source keys to the active projected recurrence group before displaying or appending review state. Curation rollback uses an append-only `remove` event for the source recurrence key.
+
+Read behavior goes through a diagnostic-state membrane: malformed JSONL lines are ignored and counted, oversized lines are skipped, oversized files fail closed, schema-invalid records are ignored, stored display fields are redacted again on read, privacy metadata is recomputed for loaded vent records, and semantic curation cycles are quarantined instead of bricking all projections. JSONL store files fail closed if replaced by symlinks.
+
+Retention/delete posture: no automatic deletion. Reviewed recurrence groups can be archived only after an explicit preview returns the exact affected record count/sample ids and an `archive:<token>` derived from the active store hash. Archive and vent-record append share a local lock, archive writes a package-created backup before replacing the active `vents.jsonl`, and receipt failures roll the active store back when the archive rewrite can still be identified. Restore requires the package-created backup path, exact derived `restore:<token>`, real backup-directory containment, and a current-store hash match so stale rollback attempts fail closed. Backup artifacts remain local diagnostic user data and are not evidence. The accepted retention/delete policy is [ADR 2026-05-22](../adr/2026-05-22-agent-vent-retention-delete-policy.md): no in-package hard-delete action for v0.1; permanent removal remains operator-owned filesystem/data-lifecycle control unless a future decision accepts a narrower purge design.
+
+## Privacy contract
+
+The tool prompt and runtime validation both bias toward minimal summaries:
+
+- do not include secrets, tokens, credentials, or raw user payloads;
+- use short summaries and concrete reproduction hints instead of copied logs;
+- apply conservative redaction heuristics for common token/password/API-key shapes;
+- keep everything local; no network calls and no cloud telemetry.
+
+## Tool surface
+
+### `agent_vent`
+
+Actions:
+
+- `record` — append a vent record.
+- `summary` — summarize recurrence groups and candidate incidents.
+- `list` — show recent records.
+- `path` — show local store path and data contract.
+- `review` — show recurrence groups as a local review queue, optionally focused by local category/tag/tool/package facet filters; when given a recurrence key, show bounded representative local samples for that group.
+- `outcomes` — show read-only post-review follow-up grouped by local review outcome state, optionally focused by local category/tag/tool/package facet filters.
+- `compare` — show a read-only cross-state review comparison before export, retention planning, or draft-only handoff, optionally focused by local category/tag/tool/package facet filters.
+- `facets` — show read-only local category/tag/tool/package facet counts for triage.
+- `set_review` — append a local review-state event for a recurrence group.
+- `curate` — append a local recurrence merge/rename projection event.
+- `draft` — generate draft-only owner-surface text for a recurrence group.
+- `stats` — show local store counts, byte sizes, malformed-line counts, curation counts, and review-state totals.
+- `export` — emit a bounded local diagnostic projection in markdown or JSON.
+- `retention` — list read-only retention candidates and receipt history, preview, confirmation-gate, archive, and restore reviewed local diagnostic records with local backup receipts.
+
+Important behavior:
+
+- `record` requires `summary`.
+- `severity` defaults to `medium`.
+- `category` defaults to `other`.
+- `recurrenceKey` may be supplied by the agent; otherwise it is derived from category + summary.
+- candidate incident flagging is local and advisory.
+- `tool` and `packageName` are optional caller-supplied local diagnostic facets, not owner-routing truth.
+- `facets` is read-only and summarizes local labels; it never mutates AK, GitHub, incident, evidence, telemetry, or ASC/self state.
+- `review` facet filters are read-only local diagnostic focus aids; review command syntax fails closed before store reads for unknown filter keys, invalid states, and invalid category values, and filters do not assign owners, route work, mutate owner surfaces, or change review state.
+- `review` queue/detail, `outcomes`, `compare`, and retention-candidate output may show explicit derived decision posture, advisory human-review hints, exact next-action commands for local review states, draft-only handoff targets, export prompts, and retention preview eligibility; generated commands quote dynamic recurrence keys/paths for legacy key safety. Decision posture is a local diagnostic projection derived from current review state and candidate-incident priority; it is not resolution, assignment, issue status, task truth, incident state, evidence, or publication. Filtered compare follow-up commands preserve supported category/tag/tool/package filters for `outcomes`, `retention candidates`, and `export`; export applies review-state and facet scope before counts, summaries, and display rows so mixed recurrence groups do not broaden output. Outcome and compare limits are per review-state bucket rather than global. Review/outcome/compare/export command syntax fails closed before store reads for unknown filters, empty filter values such as `owner=` or `tag=`, invalid states/arguments, and invalid category values. These are UX guidance only and do not route, submit, file, create, declare, assign owners, record evidence, publish, archive, restore, or mutate owner systems; compare intentionally emits no retention confirmation tokens.
+- `set_review` requires an existing recurrence group and never mutates AK, GitHub, incident, evidence, telemetry, or ASC/self state.
+- `curate` requires an existing source group, rejects self/cycle aliases, supports append-only `remove` undo events, and stores local projection events only.
+- `draft` supports `github_issue`, `ak_task`, `incident_review`, and `maintainer_note`; it includes local diagnostic facets when present, returns text only, and never submits, files, declares, records evidence, assigns owners, or changes review state automatically.
+- `stats` and `export` are read-only projections and must not claim evidence, publication, task, issue, owner-routing, owner-assignment, or incident authority. Export may preserve local category/tag/tool/package facet scope as a diagnostic focus aid only, and export follow-up commands must remain local diagnostic or draft-only hints with no archive/restore confirmation tokens.
+- `retention candidates` and `retention history` are read-only projections; history reconstructs rollback-candidate restore commands from archive receipts without reading active vents/backups, while actual restore still enforces realpath containment and stale-state checks. `retention preview` is read-only; `retention archive` mutates only the active local vents store after exact confirmation, lock acquisition, store-hash verification, and backup creation; `retention restore` mutates only the active local vents store after exact confirmation, realpath containment, and stale-state checks.
+
+### `/agent_vent`
+
+Human/operator command for lightweight inspection. `/agent-vent` remains a compatibility alias.
+
+- `/agent_vent help`
+- `/agent_vent summary`
+- `/agent_vent list [limit]`
+- `/agent_vent path`
+- `/agent_vent facets [limit]`
+- `/agent_vent review [new|acknowledged|dismissed|escalation_drafted|all] [limit] [category=bug] [tag=reload] [tool=pi-reload] [package=tryinget-pi-agent-vent]`
+- `/agent_vent review show <recurrenceKey> [limit]`
+- `/agent_vent review set <state> <recurrenceKey> [note]`
+- `/agent_vent outcomes [new|acknowledged|dismissed|escalation_drafted|all] [per-state-limit] [category=bug] [tag=reload] [tool=pi-reload] [package=tryinget-pi-agent-vent]`
+- `/agent_vent compare [per-state-limit] [category=bug] [tag=reload] [tool=pi-reload] [package=tryinget-pi-agent-vent]`
+- `/agent_vent curate merge <sourceRecurrenceKey> <targetRecurrenceKey> [note]`
+- `/agent_vent curate rename <sourceRecurrenceKey> <targetRecurrenceKey> [note]`
+- `/agent_vent curate remove <sourceRecurrenceKey> [note]`
+- `/agent_vent draft <github_issue|ak_task|incident_review|maintainer_note> <recurrenceKey> [limit]`
+- `/agent_vent stats`
+- `/agent_vent export [markdown|json] [state|all] [limit] [category=bug] [tag=reload] [tool=pi-reload] [package=tryinget-pi-agent-vent]`
+- `/agent_vent retention history [limit]`
+- `/agent_vent retention preview <recurrenceKey>`
+- `/agent_vent retention archive <recurrenceKey> <archive:token> [note]`
+- `/agent_vent retention restore <backupPath> <restore:token> [note]`
+
+## Candidate incident heuristic
+
+A recurrence group is flagged as a candidate incident when:
+
+- any record is `critical`; or
+- the group has at least three records and max severity is at least `medium`; or
+- the group has at least two records and max severity is at least `high`.
+
+This heuristic intentionally errs toward surfacing review candidates, not asserting operational truth.
+
+## Cross-package integration
+
+`pi-agent-vent` remains separate from `pi-autonomous-session-control` by design:
+
+- 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.
+- `pi-toolbox-discovery` owns discovery/activation of the already-registered `agent_vent` tool through the same-named `agent_vent` bundle.
+
+This keeps vent persistence from becoming hidden ASC state while still making the capability discoverable during autonomous work.
+
+## Non-goals for v0.1
+
+- No automatic GitHub issue creation.
+- No AK task creation.
+- No incident declaration in external systems.
+- No model judging/evaluation loop.
+- No remote telemetry or team sync.
+- No UI dashboard beyond command/tool text output.