pi-jarvis Agent Notes

# pi-jarvis Agent Notes

## Project Scope
- `pi-jarvis` is a Pi extension that opens a `/jarvis` side-conversation overlay.
- Core runtime files: `index.ts`, `side-session.ts`, `native-mcp.ts`, `overlay.ts`, `overlay-layout.ts`, `draft-editor.ts`, `transcript-viewport.ts`, `jarvis-branding.ts`, `model-picker.ts`, `jarvis-config.ts`, `session-ref.ts`, `memory-{types,config,content,store,service,extension,editor-types,editor,editor-controller}.ts`, and `archive-{types,config,store,service,extension,import,crypto,sqlite,keychain,unlock,secret-input,vault-files,vault,migration}.ts`.
- Current baseline: Pi 1.0.0 (`@earendil-works` packages), Node.js >=22.19.0. Older Pi hosts are not supported.

## Current `/jarvis-model` and `/jarvis-thinking` Behavior
- `/jarvis` requires `ctx.mode === "tui"`; other modes must not boot or prompt a hidden side session.
- `/jarvis-model` with no request opens a searchable host-registry model picker in TUI mode; other modes report status.
- `/jarvis-model <provider/model>` writes a project-scoped override to `.pi/jarvis.json`.
- `/jarvis-model --global <provider/model>` writes the default global override to the active Pi agent directory's `extensions/pi-jarvis.json` (by default `~/.pi/agent/extensions/pi-jarvis.json`).
- `/jarvis-model [--project|--global] follow-main` stores a scoped `follow-main` override.
- `/jarvis-model [--project|--global] clear` removes that scope's override so fallback applies.
- `/jarvis-thinking [--project|--global] auto|follow-main|off|minimal|low|medium|high|xhigh|max` stores a scoped thinking override without changing the main session thinking level.
- `/jarvis-thinking [--project|--global] clear` removes that scope's thinking override so fallback applies.
- Resolution order is: project config, then global config, then built-in defaults (`follow-main` for model, `auto` for thinking). Global writes never override an active project setting.
- Config writes use atomic same-directory replacement. Malformed shared JSON requires manual repair: model/thinking set/clear must never replace/delete it and reset unknown memory privacy controls. Keep I/O errors distinct and parser input snippets out of UI errors. Legacy model/thinking cross-process writes remain unlocked.
- `auto` thinking follows main only when `/jarvis` follows the main model; pinned `/jarvis` models default to thinking `off`.
- `follow-main` thinking follows the main thinking level regardless of model selection, except xAI `/jarvis` models force thinking `off`.
- `/compact`, `/tree`, and `/new` entered inside `/jarvis` operate on the isolated `/jarvis` side-session, not the main Pi session.
- `Note main` and `Redirect` stay disabled when the active `/jarvis` model is incompatible with bridge tools.
- Published packages keep Pi runtime packages as optional peers, not bundled dependencies. Never load the legacy MCP adapter. Version 1.6.0 adds native MCP to Repo tools opt-in alongside read/bash/edit/write.
- Physical models delegate to the host's public registry for auth and dispatch. Virtual/router models explicitly reject; do not access the registry's private backing runtime.
- Side resources/settings honor `ctx.isProjectTrusted()`. Local tool execution and bridge delivery recheck live permissions. Ordinary overlay close hides presentation without stopping assigned work or clearing its three grants; cancel pending confirmations and refuse new invisible reviews. Grants are in-memory, scoped to the current main/side owner, not saved across restart/reload. Explicit access-off, observed trust denial, side `/new`, reference/main replacement and teardown revoke them. Archive private-input preparation explicitly revokes transient grants before closing/yielding.
- Use `agent_settled`, not `agent_end`, for final idle state. Main context must honor Pi context-edit/compaction projection.
- Runtime disposal must not detach the overlay's bridge subscription. Queue ownership must survive side `/new` but not main-session replacement; failed/uncertain sends are not auto-retried.

## Overlay UX
- Closing presentation is distinct from stopping work. Keep background activity and enabled grants visible in main Pi; local `/jarvis status`, `/jarvis stop` and `/jarvis access off` require no hidden side boot/model work. Stop cancels active work and clears waiting input, without replay/rollback promises. Main/side replacement and reload/quit still end background work; this is not a detached daemon.
- Compact header by default; Ctrl+O expands verbose focus/settings/diagnostics, PageUp/PageDown scroll transcript, Ctrl+End follows live, Ctrl+L dismisses notices. Keep permission states and focused controls visible while giving the conversation a distinct padded reading panel, bounded column width and quiet contextual hints. Use public theme APIs with readable light/dark/256-color fallbacks; never change user theme/renderer settings. Summarize informational notices without hiding warnings/errors. Regular-mode mouse scrolling belongs to the terminal, while supported fullscreen wheel events use the public component API.
- Model/thinking pickers stay inside the overlay, use the public physical-model registry and existing scoped config rules, and preserve draft state. Reject changes during active work before persistence; do not silently stop a turn or change the main model/thinking. Async picker results and configuration completions must be owner-bound and private-input-safe.
- Use Pi's public multiline Editor. Enter sends; Shift+Enter/Ctrl+J inserts newline. Preserve indentation and reject unsafe/oversized drafts (64 KiB) explicitly.
- Bridge-owned in-memory drafts survive close/reopen. Bridge reset clears draft/recall on side `/new` or main/side-reference replacement; side-tree navigation only resets scroll.
- Consume bracketed paste before global shortcuts and confirmation keys; pasted content must not toggle permissions or approve a redirect.
- Queue count excludes active work; processing includes boot and complete queue settlement. Keep activity separate from scrollback and never replay uncertain sends.
- Bound overlay history (500 entries, 512K UTF-16 units total, 64K per entry) with explicit omission notices; never truncate persisted history.

## Branding intro (1.6.1)
- The first overlay for each main-session ID in the loaded extension shows a 1.8-second neon/chrome ASCII sweep, then returns to the compact UI. Reopen, side `/new`, tree navigation, and returning to an already-seen main session must not replay it. Reload/restart resets this in-memory bookkeeping.
- The intro is decoration, never a boot/queue gate. Keep editor, permissions, and activity available. Input dismisses it without being consumed; paste framing still precedes shortcuts. Confirmations and warnings/errors preempt it.
- Use a bounded, unreferenced, lazily started timer; stop on dismissal, expiry, or disposal. No blinking, flashing, terminal-clearing commands, transcript entries, or persisted session changes.
- Suppress with `PI_JARVIS_NO_ANIMATION=1`, non-empty `NO_COLOR`, or `TERM=dumb`. Use compact/no intro on small terminals and readable palettes for light themes and 256-color output.
- `jarvis-branding.ts` owns the original wordmark. `npm run render:branding` regenerates README SVGs with local renderer fixtures, not live provider/session data. Label fixture previews honestly.
- `npm run render:showcase` generates self-contained conceptual workspace/history/access SVGs; `npm run check:showcase` optionally uses an existing Playwright installation for loopback-only desktop/narrow/light/dark screenshots and text-bound checks. Keep browser dependencies out of the runtime package, distinguish conceptual diagrams from live UI, and preserve truthful defaults/privacy/close-versus-stop labels.

## Native MCP (1.6.0)
- Use Pi's root-exported native factories, not private registry/runtime/transport internals. Jarvis owns separate configured-server connections; main-only extension registrations are not inherited.
- No native startup/credential expansion while initially off. Respect project trust, enabled states, native tool exposures, and live Repo tools permission for direct/deferred/codemode/resource execution.
- Revocation invalidates permission generations, hides owned tools, aborts calls and invokes owned native shutdown. Stale prepared tools and late registrations cannot regain access after re-enable.
- Pi cancellation is best effort: already-started handshake/authentication/remote work may finish or time out after shutdown is requested. Do not promise immediate child teardown, rollback, or sandboxing.
- Keep server administration in main Pi. Disable codemode model helpers (`models: false`); preserve independent Note main/Redirect gates and the overlay-owned bridge subscription.
- Tests use temporary agent/workspace directories and local fixture servers only; never start real user MCP servers or resolve real credentials during validation.

## Shared memory (1.7.0)
- Main Pi and the isolated Jarvis SDK session explicitly mount one shared local service. Memory is enabled by default in trusted projects, independently of Repo tools, Note main, Redirect, and overlay open/close. It can share historical facts even when bridge delivery is off; it never steers or queues work.
- `/jarvis-memory` reports status; `help` documents controls. `[--global|--project] on|off|capture on|off|recall on|off|clear` controls default to GLOBAL (unlike model/thinking). Per-field project > global > defaults, except global enabled=false is a master kill switch. Untrusted projects and config errors pause all memory. Full off means no memory-record reads/capture/injection/tool execution; retain data. Explicit admin inspection still requires enabled memory; capture/recall-only pauses do not block manual commands.
- Inside the overlay, `/memory …` and `/jarvis-memory …` execute immediately without model/boot/queue work. `clear` removes settings, never data; `forget-all --confirm [--global|--all]` defaults to only the current project's records. Data scope flags follow the action.
- Disclose capture/recall before first use and only then persist the global disclosure marker. No silent historical import, background providers, embeddings, real user credential access, or real MCP servers during tests. Isolate every test's agent/workspace directories.
- Capture only new finalized user/assistant text, not thinking/tool/custom/system/attachment data or aborted/error output. Stage only event metadata (max 256 anchors); resolve at turn/settlement boundaries from at most 1,024 newly persisted parent-chain entries, stopping before the old leaf. Never archive intermediate message_end payloads before later redaction hooks. Discard pending anchors on revocation, session/tree change or disposal; never backfill. Secret filtering is best-effort, not a guarantee; reject suspected secrets in curated notes. Cap text at 16 KiB UTF-8; omit oversized archive captures, reject oversized notes. Archive retains newest 10,000 records; curated notes cap at 1,000 without automatic deletion.
- Keep auto recall scoped to global + canonical current cwd; explicit all-project search is supported. Request-local context injection is bounded to 6,000 bytes of untrusted record JSON plus notice; search results 12,000 bytes with excerpt/omission markers. Never persist automatically injected context via appendEntry/sendMessage or treat stored instructions as authority. Explicit tool calls/results still follow normal Pi persistence; don't promise that disabling/forgetting erases earlier tool results or already-viewed output.
- Store is lazy local SQLite under the active agent directory (`extensions/pi-jarvis-memory/memory.sqlite`), not a project-selected path. SQLite coordinates record writers; memory settings use atomic cooperative locking that legacy model/thinking writes do not participate in. Fail closed on malformed settings; never repair automatically.
- Memory guidance is also request-local: use a custom advisory so Pi's later forced-prompt projection cannot discard it. Preserve other prompt/tool state; a mid-turn disable removes both advisory and recalled records from future requests.
- Model tools recheck live trust/settings/cancellation and permission generations at execution, including captured definitions. Broadcast observed policy changes across mounted lanes and revoke per-binding generations at session/tree boundaries; don't promise live push delivery across processes. Model forget requires cancellable human review and transactionally compares the reviewed version. Tombstones prevent identical event/title resurrection, not every semantic mention; Pi transcripts, backups and already-sent context remain. Do not promise encryption, a sandbox, or forensic erasure.

## Curated memory editor
- `/jarvis-memory editor` opens a human-only TUI overlay; `/memory editor` inside Jarvis is intercepted locally before boot/provider/queue work. It manages only curated `kind=note` memories, including manual notes, not bounded conversation captures or the separate archive.
- Browse/search/filter/sort with bounded summary pages; inspect full text/provenance; create, duplicate, edit title/body/category/scope, and explicitly review saves and single/selected deletion. Full-off/untrusted/config errors deny reads and writes. Human administration remains available when only capture or recall is paused; never change those controls automatically.
- Create must not overwrite an existing scoped title. Renames/scope changes and reviewed deletions compare exact snapshots transactionally, retain tombstone/FTS/identity-budget semantics, and never replay uncertain writes. Forgotten titles require the existing explicit remember command rather than silent editor resurrection. Separate note-data notifications from policy invalidation so edits do not discard pending captures.
- Reserve editor modal ownership before closing/yielding Jarvis. Coordinate with private archive input, model pickers and main memory-forget reviews; use live owner/cancellation checks at operation/transaction boundaries. Dispose/revocation rejects stale callbacks and clears local editor references; no auto-reopen or hidden model boot. Preserve ordinary close-versus-stop and archive finalization boundaries.
- Use public multiline editing, explicit size validation, paste-first shortcut/review handling, fresh visible confirmation and bounded small-screen layouts. Memory-editor Escape retains a possible split paste opener; Escape then Enter performs back/close, while another Escape only re-arms. Do not restore immediate lone-Escape exit or weaken all-page save/delete/discard review. Notes remain local plaintext, untrusted historical data; this is not a password vault or forensic erasure. No real memories, archives, credentials or providers in tests.

## Optional full-session archive (1.8.0)
- `archive-{types,config,store,service,extension}.ts` implement an independent OFF-by-default archive, explicitly mounted in main and Jarvis. Defaults enabled=false/capture=true/modelAccess=false; per-field project > global > defaults except explicit global enabled=false is master-off. Untrusted/config errors pause everything. Never enable/import real user data in tests.
- Separate settings: `<agentDir>/extensions/pi-jarvis-archive.json` and `.pi/jarvis-archive.json`, top-level `archive`. Controls default global. Settings writers may retry only a raced inode/unlink preflight read once under the existing cooperative lock; policy readers and locked-read races remain fail-closed, with no uncertain write replay. on/model-access on/model-search on/clear require `--confirm-sensitive`; clear removes settings, not data, and fallback can re-enable. Archive tools are read-only and need modelAccess; humans can inspect with only capture/modelAccess off, but not full off.
- Model-tool reach: `jarvis_archive_search/read/session` default to the current session (scope "session", mapped to project + current session ID; store read gains a session filter so entry IDs cannot bypass the reach). Wider reaches (scope "current"/"all" or a foreign session ID) require one approval per request via Pi's normal confirmation (the Jarvis lane bridges it through the overlay like `confirmForget`), or the standing `modelWideSearch` setting (`/jarvis-archive model-search on --confirm-sensitive`, off by default, layered like model-access). A declined/unavailable approval returns one refusal sentence and executes nothing. Flipping the setting revokes prepared tool definitions. Session reach follows the current Pi session ID; pre-fork/pre-tree history is outside it (documented follow-up). Human CLI commands keep defaulting to this project.
- `/jarvis-archive` and overlay `/archive` commands are local, immediate, no provider/boot/queue work. Search/read/session default current-project; all-project access is explicit. Model tools cannot change controls, import, or delete. No auto context injection.
- Archive accepted finalized journal entries unredacted, including exposed thinking/tool/system/custom/error/inline-image data. Never capture intermediate message_end/tool_result/raw-provider payloads before later redactors. Baseline existing entry IDs on activation, never auto-backfill; parent/header provenance retained. Snapshots are not crash-safe audit logging and cannot recover unpersisted events, earlier truncation or external referenced files. Warn on storage/observation failures, not silent replay.
- Lazy private SQLite FTS5, plaintext by default at `<agentDir>/extensions/pi-jarvis-archive/archive.sqlite`; optional encryption selects a managed generation at `vaults/<UUID>/archive.sqlite` under that fixed root. No automatic retention eviction. 64 MiB raw-entry/index budgets and 64K UTF-16 normalization-context hard rejection, no truncation of accepted raw JSON or silent partial indexing. Identical serialized payloads deduplicate across lanes; conflicting payloads for one identity fail without replacement. Search/read output max 24,000 JSON bytes plus notice; raw read offsets count Unicode codepoints and preserve pagination through output shrinking. Oversized display provenance is explicitly abbreviated; read(part=metadata) / read --metadata pages exact original metadata so every accepted entry stays accessible. Images/signatures are raw-retained, not text-indexed. Never load full payloads for search or scan all raw bodies on open. Inspection uses read-only schema snapshots and bounded observation of a version-zero, truly empty database while a concurrent creator initializes it; release each empty snapshot before waiting. Never let readers initialize/reset storage or retry record writes; unknown nonempty schemas reject.
- Explicit human single-file import streams one selected regular v3 JSONL file, honors its header's project/session provenance, checks live capture/epoch/cancellation at chunk/record boundaries, reports partial commits, never mutates source. No automatic directory scans or legacy auto-migration. Scoped forget-session/prune require --confirm; tombstones stop identical entry resurrection, not all copies. Plaintext remains the default; optional archive-only encryption protects the active database/index/journals, not original transcripts/shared memory/retained plaintext backups. No sandbox, forensic erase, or hard total-disk-quota claims.
- Keep live trust/settings and per-binding stale-definition guards independent of Repo tools. Reader permission changes must not discard pending recording. Main owner closes storage after final archive snapshot; the side owner snapshots finalized entries before revoking its lifetime/context, without closing the shared service. Preserve archive finalization before main boot-generation invalidation. Settings observations propagate between mounted lanes, not by a cross-process watcher.

## Bulk archive import (1.9.0)
- `archive-import.ts` owns bounded discovery and the shared streaming reader. `/jarvis-archive import-all [absolute-directory]` is an explicit metadata-only recursive preview, defaulting to `<agentDir>/sessions` (older Jarvis side history lives under `<agentDir>/jarvis-sessions` and needs an explicit root). Require enabled recording/trust before scanning; never read transcript bodies or open archive records for preview. No startup scan, model import tool, or implicit history backfill.
- Confirmation requires `import-all --confirm-sensitive --preview <id>` and consumes the 10-minute preview once. Pin the exact reviewed set, root/directory/file identities and metadata; do not rescan or add newly discovered files. Bind to cwd/session and live permission/import generations; new previews replace old ones. Cancellation/revocation/session change stops remaining work, without replay or rollback promises.
- Bounded sequential discovery/import: 10,000 candidates, 50,000 entries visited, depth 64, approximately 8 MiB manifest. Skip nested symlinks, hardlinks and nonregular files. Fail incomplete/over-limit previews explicitly. Recheck opened FDs and directory identities, cap bulk reads at reviewed size, check mutation at streaming boundaries; do not claim a filesystem snapshot/sandbox.
- Preserve single-file import compatibility, v3/header provenance, dedup/conflict/tombstone semantics and partial counts. Per-file source failures continue; cancellation/permission/storage-wide failure stops the batch. Sources are never intentionally written. Tests use temporary synthetic session directories only.
- `import-report <id> [offset]` pages the latest ephemeral per-file report under the same project/session owner, with enabled archive but no model-access/capture requirement. Bound JSON output to 24,000 bytes, explicitly abbreviate oversized paths and preserve pagination progress. `import-cancel` cancels local imports/previews without changing settings and works while off. No persisted report or automatic context injection.

## Optional archive encryption (1.10.0)
- Password-based archive encryption ships OPTIONAL/OFF by default, agent-wide and independent of archive enablement/capture/modelAccess, shared memory, Repo tools and bridge permissions. No automatic migration, history import, backfill or user-setting changes. Public/private-key support is deferred. `docs/archive-encryption-design.md` documents the shipped operating/security contract, not independent cryptographic certification.
- Safe setup is human-directed: review configured/effective status, trust and global/project overrides; if avoiding new plaintext archive captures, pause CAPTURE at the effective scope BEFORE enabling/migrating. Global capture off does not override project capture on; explicit global enabled=false blocks project on. Stop all other Pi instances, enable only the intended scope in a trusted project with capture still off, migrate/unlock, verify active storage and chosen plaintext cleanup, unlock again after cleanup, then resume capture explicitly. Never recommend or perform automatic user-control/renderer changes. This does not pause original Pi transcripts or shared memory.
- Human-only agent-wide syntax (no scope/password/key/path arguments): `/jarvis-archive encryption [status]`; `encryption on|off|cleanup --confirm-sensitive --confirm-stopped`; `encryption recover --rollback --confirm-sensitive --confirm-stopped`; `encryption break-lock --confirm-sensitive --confirm-stopped`; `unlock [session|process|remember|for MINUTES|idle MINUTES]`; `lock`; `password`; `startup manual|prompt|remember`. Overlay `/archive` interception is local, without provider/boot/queue work; password entry closes Jarvis and revokes its transient permissions. Enabled/trusted archive policy is required for unlock/migration/cleanup/data operations; capture/modelAccess may remain off. Status and explicit lock are available while access is paused.
- `encryption on` migrates to encrypted storage; `encryption off` converts to plaintext without disabling recording. Ordinary `/jarvis-archive off` pauses archive reads/capture and revokes local access without decrypting/deleting files. Password change requires unlock, asks twice, rewraps the SAME data key and ends the local grant: it is not key rotation; old key/envelope backups may still unlock that key's data.
- Use a random 256-bit data key with authenticated password wrapping (fixed asynchronous scrypt and AES-256-GCM); encrypt the SQLite database and its FTS/journal/WAL content, not just message bodies. Ordinary encrypted operation has no temporary plaintext database; temp_store must be MEMORY. Passwords are valid Unicode, 1–4096 UTF-8 bytes, without controls/line breaks, with no trimming/normalization. Never fall back to plaintext, ordinary password input, unprotected key files or another credential backend after encryption/remembered-unlock failure.
- Native dependencies are exact-pinned optional packages, lazy loaded: `better-sqlite3-multiple-ciphers@13.0.3` and `@napi-rs/keyring@2.1.0`. Plaintext stays on node:sqlite. Linux glibc prebuilds require >=2.35; upstream advertises musl/macOS/Windows binaries, but local runtime validation is Linux-only. Remember uses the OS store (Linux explicitly Secret Service, no kernel-keyring downgrade); service/platform authorization applies. Missing/omitted/incompatible dependencies fail closed. Do not execute install scripts or auto-build/download fallback binaries at runtime. Tests use disposable native databases and fake keychains only, never real OS credentials/user archives; preserve host optional peers.
- Password entry supports ONLY public Pi regular TUI (`pi --tui-mode regular`); fullscreen/unknown/missing/non-TUI refuse. Never change user settings. EVERY submit/cancel, including typed-only Enter/Escape/Ctrl+C, requires a fresh displayed 12-symbol/60-bit code typed + Enter; paste cannot authorize completion. Passwords never enter arguments, environment variables, ordinary editors/history, tools, session entries, notifications or logs.
- Reserve private-input ownership synchronously before closing Jarvis/yielding. Jarvis/model-picker/main-memory-review admission must use the same gate through preparation, deferred mount, custom lifecycle and cancellation sink. Abort revokes backend work immediately but retains a cancel-only sink until fresh verified exit; never release merely because the backend promise resolves. Cancellable main switch/fork/tree navigation retains the sink and is refused until verified exit. Forced reload/quit/trusted external focus replacement cannot preserve quarantine: abandon without stale done or waiting; disclose this unsupported boundary. Bytes after verified release/host teardown and trusted screen/input/process code are outside protection; hostile input can deny service.
- Session leases belong to MAIN and are shared with Jarvis; side /new and overlay close preserve them. Default unlock is session. Process/timed/persistent-local grants hand off only across supported main new/resume/fork, preserving fixed/idle deadlines; reload/quit/restart end local grants. Minutes are integers 1–10080. Timed grants check monotonic/wall clocks and access-boundary expiry; idle refreshes only on successful archive data operations, never status/policy checks. No immediate erasure during OS sleep.
- `unlock remember` authorizes a unique OS account containing the random key, not password, and selects startup remember; `startup remember` requires a live encrypted unlock. Default startup manual and startup prompt clear remembered authorization and lock locally; prompt requests session unlock only on permitted MAIN startup. Explicit nonremember unlock clears prior remembered authorization (remember startup becomes manual). Explicit lock revokes locally first, then durably clears/rotates remembered authorization before best-effort native deletion; report potentially remaining credentials or failed durable revocation honestly. Full-off/untrusted/config errors/restart-required state suppress startup prompts/credentials/authentication; trust restoration does not silently revive revoked grants. Jarvis boot never restores credentials.
- Locked, transitional, invalid or restart-required vaults block record reads/capture/import/ordinary deletion. Rebaseline capture, cancel imports/previews and reject stale tools; never queue plaintext/backfill after unlock. Observe trust denials through shared policy to revoke keys/pending grants, not just hide tools. Observed durable revisions revoke at operation boundaries, not instant cross-process key erasure/push notification. Final side/main snapshots and side disposal precede boot-generation invalidation, so retiring-side cleanup cannot falsely revoke the main grant.
- Fixed root `<agentDir>/extensions/pi-jarvis-archive`, strict bounded Ready/Transition metadata `archive.vault.json` (64 KiB), cooperative `archive.vault.lock`, UUID generations `vaults/<UUID>/archive.sqlite`, max EIGHT distinct retired generations. Metadata/wrapping parameters/filesystem identities are not concealed. Canonicalize the selected root only; appended paths remain strict no-follow. Serialize managed operations; stop all other Pi instances, including older versions, before migration/recovery/cleanup. Never auto-steal locks, repair metadata, replay uncertain writes or treat confirm-stopped as stopping processes. Break-lock requires a demonstrably dead local PID on the same host plus identity/token rechecks.
- Source/active-file observation is stat-only: NEVER open/close another SQLite database/SHM descriptor to inspect a live file, since POSIX close can release the process's native transaction locks. Keep private owner/type/mode/nlink/ancestry and operation-local identity/presence checks. This is not an immutable filesystem snapshot.
- Throwing trust observations are denial and revoke keys/pending work, including direct policy/status paths. Mid-operation denial revokes immediately; restoring permission cannot reuse that grant. Recheck permits after lease.touch(), which may itself expire/revoke. Import counts retain acknowledged append outcomes despite later guard/release failure; never infer an uncertain COMMIT or retry a write.
- Stream/verify exact raw JSON spelling/index/provenance/rowids/tombstones to a DISTINCT target, checkpoint/close/fsync before publication, and retain sources until explicit cleanup (including plaintext). Check disk space for both copies; no hard disk-quota guarantee. Record initial legacy-source presence; missing/empty/unsafe/changed known sources require manual inspection/restoration and preservation of unpublished target/Transition, never empty publication or deletion of the only potential copy. An originally absent legacy source is distinct from loss; unknown prototype presence is handled conservatively.
- Cleanup deletes only recognized retired SQLite files, not active storage or outside backups. Preflight all candidates, auxiliaries before main, live authorization/source checks between deletions; failed cleanup can leave a PARTIAL retained backup, with metadata retained and no automatic uncertain-deletion replay. Encrypted cleanup requires a live lease and existing-active-DB authentication; never recreate a missing active database. Cleanup ends the local grant. Explicit recover --rollback is separate, source-checked, target-only recovery, not migration resume. Timed/idle grants cannot convert to plaintext; explicitly select session/process BEFORE key copying or Transition publication.
- Preserve native close uncertainty even before a factory returns its handle. Restart-required canonical-root poison survives new facades, aliases, main changes and logical reload/quit, with no unsafe eviction; ONLY ACTUAL PROCESS RESTART resets it. No startup credential/auth work or rollback/cleanup under poison. Grant only after successful lock release and fresh ownership checks. Uncertain publication may already have succeeded; require status/manual inspection/restart, never claim guaranteed Transition or retry automatically. Restart does not repair durable metadata, missing sources or pending transitions.
- Best-effort buffer wiping/file deletion is NOT forensic erasure. Encryption protects only active archive database/index/journals: original Pi transcripts, shared memory, attachments/exports, retained plaintext sources/backups, previously retrieved/provider context, swap/core dumps and same-user code remain outside the boundary. No sandbox, independently audited cryptography, official/vendor-audited SQLCipher, FIPS or independent certification claims.

## Git and Release Policy
- Every new commit MUST have an annotated **stable version tag `vX.Y.Z`**. No `dev`, alpha, beta, release-candidate, build-metadata, or SHA-only tags. This is a released extension, not a prerelease channel.
- Before committing, choose the next unused stable version and update package metadata, lockfile, README, and a dated changelog entry together. Tag every commit, including intermediate and merge commits; never leave a new commit untagged. Run `npm run check:tags`, then push the commit and version tag atomically. Do not move or replace existing tags or rewrite shared history.
- Prefer fast-forwarding the exact validated commits to `main`; a new merge commit also requires its own version bump and tag. Every pushed `vX.Y.Z` tag triggers validated GitHub release packaging; npm publication remains manual.
- Stable-only CI enforcement starts after historical baseline `4b6b4e6`, preserving already-pushed history. Branch/PR jobs validate on Node 22.19.0 and 24 and reject missing, lightweight, prerelease, or SHA-only version coverage. Each new tag must match that commit's package metadata, lockfile, README, and changelog.
- Existing release assets must not be overwritten with differing bytes. See `RELEASING.md` for branch/tag protection and merge/fork constraints; CI alone cannot prevent administrator bypass.

## Validation
- Run `npm test` for full validation.
- Run `npm run build` before release packaging.
- Run `npm run verify:release` to validate npm pack payload and release metadata expectations.
- Run `npm run check:tags` after tagging commits to validate annotated-tag policy.

## Docs To Keep In Sync
- `README.md`
- `CHANGELOG.md`
- `package.json` version
- this `AGENTS.md` when command/config behavior changes