---
name: oh-my-pi-foundation
description: "Use when building or hardening an LLM agent harness: steering, compaction and context reduction; memory, patch editing, telemetry; plan handoff, durable workers, fanout, experiments, or advisor delivery."
disable-model-invocation: true
---
# Oh My Pi: Agent Harness Foundation

## Use this for
Agent-harness work: provider loops, queue-owning facades, compaction, replay, plan handoff, durable workers, task fanout, experiments, advisor delivery. Code and tests are ground truth; references carry decisive excerpts plus live Codebase Memory retrieval calls.

## Load the matching source dump
- `references/agent-loop.md` — non-consuming steering, tool-result coercion, completed-pair retention.
- `references/agent-loop-tool-batch.md` — synthetic pairing for never-executed calls, transient-turn recovery, batch skip/concurrency gates.
- `references/agent-wrapper.md` — queue ownership and empty-transcript continuation.
- `references/compaction-suite.md` — legal cuts, cache-aware prune/shake, protected output.
- `references/replay-and-occupancy.md` — honest occupancy and portable fallback for native replay.
- `references/prewalk-and-plan-handoff.md` — plan-to-implementation handoff gated on a durable write boundary.
- `references/durable-workers.md` — parent-scoped worker session persistence and teardown-safe records.
- `references/fanout-and-budgets.md` — ordered fanout, cancellation-safe concurrency, soft-to-hard execution budgets.
- `references/isolation-and-provider-permits.md` — worktree isolation and narrow provider concurrency permits.
- `references/experiment-control.md` — baseline branch isolation, branch-bound resume, durable run ledgers.
- `references/hashline.md` — line-anchored patch language and applier; pure materialize-then-syntax-veto apply pipeline.
- `references/mnemopi.md` — bank/session-scoped persistent memory facade and linear-vs-polyphonic recall orchestration.
- `references/stats.md` — honest usage windows and pure user-metric extraction that degrade instead of failing.
- `references/hashline-fs-stream.md` — pluggable Filesystem seam, numbered-line streaming, fs-mediated snapshot/recovery keys.
- `references/mnemonic-beam.md` — recall signal fusion, tier fallbacks, and consolidate/sleep compaction.
- `references/stats-sync-worker.md` — single-writer ingestion lock, worker grabs, embedded dashboard archive magic.
- `references/hashline-parser-seams.md` — lexical section splitter, lenient ranges, strict anchors, snapshot cache.
- `references/mnemonic-embeddings.md` — four-stage provider chain, guarded model heal, runtime install, host LLM bridge.
- `references/stats-db.md` — WAL init + idempotent migrations, per-file offsets, bucketed series, usage windows.
- `references/hashline-normalize-prefixes.md` — text-shape round-trip (CRLF/BOM) and echoed-prefix stripping before tokenizing.
- `references/mnemonic-binary-vectors.md` — int8/bit binary store, Hamming+cosine, triples-split migration guard.
- `references/stats-gain-dashboard.md` — savings ledger aggregation with worktree-root folding and zero-record tolerance.
- `references/hashline-clipboard-syntax.md` — clipboard register resolution and parser-backed structural proof boundaries.
- `references/mnemonic-query-cache.md` — tiered recall cache thresholds, SQLite persistence, and zero-safe cost logging.
- `references/stats-server-port.md` — dashboard route behavior, embedded client selection, and safe port reuse/reclamation.
- `references/hashline-format-recovery.md` — format grammar, content-derived identity, and anchor-proved recovery.
- `references/mnemonic-temporal-gates.md` — deterministic temporal parser and host/env recall feature gates.
- `references/stats-provider-client.md` — bounded abortable dashboard data client over typed API endpoints.
- `references/advice-delivery.md` — severity-based steer/aside/preserve routing to a live agent.
- `references/hashline-executor.md` — token-to-edit state machine: deferred flush, lenient repair warnings, ordered indices.
- `references/hashline-mismatch.md` — stale-read rejection taxonomy: drifted vs fabricated snapshot tags as actionable recovery.
- `references/hashline-stream.md` — bounded-chunk numbered-line streaming over byte inputs without materializing files.
- `references/hashline-patcher.md` — prepare/commit orchestrator: preflight-everything batches, disk-truth snapshot tags, seen-line guard, landed-prefix failure reports.
- `references/hashline-diff-preview.md` — signed numbered-diff renumbered into a post-edit preview a follow-up edit can anchor on.
- `references/hashline-noop-loop-guard.md` — byte-identical no-op edit loop breaker: soft hint first, then a thrown tool error.
- `references/edit-snapshot-budget.md` — shared-budget pruning of edit-tool oldText/newText snapshots with strip-and-mark semantics.
- `references/snapcompact-archive.md` — vision-compaction orchestration: re-render-from-kept-source, foveated HQ/LQ/HQ imaged middle, oldest-slice drop.
- `references/snapcompact-shape-billing.md` — provider-aware frame shape + per-frame token billing (billing by API, geometry by model id).
- `references/snapcompact-serialization.md` — `¶user/think/ai/call:` transcript with tool-result-into-call-scope merging and intent-as-comment.
- `references/snapcompact-normalization.md` — font-aware folding, whitespace collapse, word-wrap, and cell-grid pagination for bitmap rendering.
- `references/collab-wire-protocol.md` — dependency-free live-session collab wire contract: message/entry/event/frame shapes, envelope+link split, version-reject-at-hello.
- `references/bench-run-store.md` — SQLite mirror of filesystem-truth runs: WAL recovery-lock retry, phantom-trial pruning, freshness-based orphan inference.
- `references/bench-experiment-projection.md` — decided-population arm stats and sibling-calibrated (Rasch) final-pass projection; re-run trial merge precedence.
- `references/bench-live-cost-probe.md` — incremental JSONL cost probe over appending transcripts: byte cursor, partial-line carry, oversized-line discard.
- `references/bench-resume-recovery.md` — rebuild an exact job invocation from disk: config snapshot → launch-record ladder, recorded-backend override, default-filter union.
- `references/bench-managed-children.md` — manager child lifecycle: detached spawn, TERM→KILL cancel ladder, pid-probe liveness, dual-layer delete, hot-reload retirement.
- `references/bench-adapter-normalization.md` — one uniform snapshot schema over heterogeneous benchmark artifacts via declared metric definitions + per-kind readers.
- `references/bench-arm-inheritance.md` — comparable-arm launches that inherit dataset/sample/scale from the best-recorded sibling and diff only treatment knobs.
- `references/bench-best-of-n.md` — best-run selection ordering (success > non-ghost > cheaper > earlier) with ghost/transport-failure denominator exclusion.
- `references/bench-retry-ladder.md` — timeout/no-op/provider-failure retries that don't consume attempt slots, with telemetry-stuffed follow-up context.
- `references/bench-token-accounting.md` — cross-provider comparable token metrics: sum cache buckets into prompt cost, subtract per-call system overhead, clamp deltas.
- `references/bench-early-stop.md` — abort-on-verified-match machinery: serialized verification chain, single-settle guards, abort-inside-prompt tolerance.
- `references/bench-source-deps-cache.md` — manifest-hash-stamped linux deps tree for containerized TS workspaces: zero rebuild on TS edits, arch-matched installs, shadow mounts.
- `references/bench-gateway-isolation.md` — provider credentials never enter containers: gateway baseUrl rewrite, prefix-allowlisted env forwarding, vmnet bridge forward.
- `references/bench-sse-broadcast.md` — SSE push-on-change dashboards: serialize-compare ticks, immediate initial frame, enqueue-failure eviction, retire-before-replace.
- `references/bench-trace-tail.md` — bounded trace tail reads: fixed-byte window with torn-line drop, locator containment under the job root, per-format normalization.
- `references/bench-guided-synthesis.md` — guided-mode patch synthesis: compile expected-vs-actual into the agent's edit grammar with BOF/EOF anchors and complexity guards.
- `references/bench-edit-taxonomy.md` — edit-failure classification ladder with payload-shape fallback, autocorrect accounting, and attempted-op telemetry.
- `references/bench-docker-cleanup.md` — targeted Docker reclamation after crashes: two-signal project targeting, state filtering, active-project network protection.
- `references/bench-trial-parsing.md` — native result-file parsing contract: usage/reward fallback chains, epsilon reward compare, exception-beats-reward precedence.
- `references/bench-live-dashboard.md` — TTY monitor around a long child: signal-forward-not-die, adaptive render cadence, total finally restoration.
- `references/bench-edit-agent-loop.md` — fixture-isolated benchmarked turn-loop: one client facade over in-process/RPC, env save/restore, JSONL evidence logs.
- `references/bench-edit-verification.md` — format-normalized output equivalence: whitespace-restore-before-format, blank-line-sensitive compare, indent score.
- `references/bench-unique-hunk-rendering.md` — prompt blocks that admit exactly one byte-exact answer: placements-from-diff, merge-nearby, re-solve-as-proof.
- `references/bench-ast-mutation-framework.md` — AST-collect → mutate-node → byte-range source splice with dual-parser fallback and re-parse validity gate.
- `references/bench-in-process-client.md` — warm-pool shared infra (auth/model) with per-client registry isolation for concurrent in-process sessions.
- `references/catalog-family-predicates.md` — namespace-agnostic family predicates: version floors over allowlists, name-substring matching, coarse family tokens.
- `references/catalog-id-classifier.md` — id → family/kind/version parsing with null-memoizing parsers and precompute-plus-dynamic SemVer.
- `references/catalog-variant-collapse.md` — per-effort sibling wire ids collapsed into one logical model: purity/idempotence, price-homogeneity gate, retired-id reconciliation.
- `references/catalog-thinking-derivation.md` — derive-once thinking ladders (per-host dialects, mandatory-reasoning floors) + field-read runtime clamps.
- `references/catalog-host-classification.md` — provider-or-URL host classes with substring-default/strict-opt-in split and bounded verdict cache.
- `references/catalog-provider-priority.md` — config-first provider rank map for same-model tie-breaks.
- `references/catalog-display-name-cleaning.md` — gateway author prefixes and extrinsic tags stripped while variant tags survive.
- `references/catalog-tokenizer-resolution.md` — id-only tokenizer ladder baked at build time with oldest-generation fallback.
- `references/catalog-proxy-reference.md` — reseller id → bundled upstream metadata inheritance via bracket/marker candidate ladders.
- `references/catalog-canonical-coalescing.md` — canonical-id coalescing provenance ladder with poisoning-proof resolution caches.
- `references/catalog-anthropic-compat.md` — signing-endpoint detection, exact-origin OAuth gate, unsigned-thinking replay policy.
- `references/catalog-openai-compat.md` — detect-once wire-quirk flag records with conditional whenThinking variant views.
- `references/catalog-bedrock-compat.md` — model-card-sourced checkpoint presets and reasoning-tiered idle watchdog floors.
- `references/catalog-resolution-merge.md` — static→fallback→cache→dynamic merge ladders, authority-vs-retry split, 4096 sentinel.
- `references/catalog-model-cache.md` — SQLite catalog cache: versioned invalidation-by-delete, header-omission ledgers, quarantine healing, secure_delete.
- `references/catalog-cache-namespacing.md` — credential/endpoint-scoped cache namespaces as the migration mechanism.
- `references/catalog-openai-discovery.md` — bounded /models probes: default deadline, envelope recursion, null-vs-empty contract.
- `references/catalog-codex-wire.md` — ChatGPT-OAuth JWT claim extraction and token-derived residency headers.
- `references/catalog-copilot-wire.md` — Copilot key envelopes, plan-endpoint discovery, version-header host split.
- `references/catalog-client-version-discovery.md` — client-impersonation version tracking: env → silent manifest probe → pinned fallback.
- `references/catalog-image-fetcher-attribution.md` — provider-side image fetcher registry with corroboration flags; attribution-not-auth.
- `references/catalog-fireworks-wire-ids.md` — digit-guarded dot↔p wire codec across models/routers namespaces + Fast serving-path suffix.
- `references/catalog-cursor-proto-discovery.md` — capability truth recovered via signal ladders when a protobuf RPC under-reports.
- `references/catalog-token-costing.md` — threshold-tier pricing and TTL-component cache-write billing with residual fallback.
- `references/auth-resolution-cascade.md` — seven-leg credential precedence and the sticky side effects at each leg boundary.
- `references/auth-oauth-refresh-lease.md` — cross-process refresh: lease acquire/renew, CAS persist, peer-rotation adoption.
- `references/auth-oauth-identity-dedupe.md` — JWT-claim identity keys, org-scoped Anthropic/Codex rows, duplicate pruning on reload.
- `references/auth-usage-ranked-selection.md` — drain-urgency comparator ladder over blocked/plan/boost/hot/measured candidates.
- `references/auth-session-stickiness.md` — durable sticky pins, index re-derivation on restore, warm-window ranking skip.
- `references/auth-scoped-blocks.md` — memory+SQLite backoff blocks with MAX merge, scope keys, corruption latch.
- `references/auth-usage-cache.md` — report cache identity, ±25% TTL jitter, single-flight epoch, last-good vs purge failure contract.
- `references/auth-codex-plan-gating.md` — tri-state plan eligibility, confirm-before-enforce, three-pass degradation.
- `references/auth-definitive-failure-taxonomy.md` — definitive vs transient refresh failures: CAS-disable+tomestone vs 5-min block.
- `references/auth-broker-sentinel.md` — redacted snapshots, `__remote__` sentinel semantics, authoritative-null store hooks.
- `references/auth-bearer-attribution.md` — SHA-256 bearer fingerprint ledgers attributing delayed usage-limit errors to durable rows.
- `references/session-streaming-edit-guard.md` — dual-epoch + promise-identity staleness defense for queued streamed-edit validations, time-sliced scans, reset-before-fan-out ordering.
- `references/session-loop-guards-gemini.md` — Gemini header-runaway abort + two-phase generation-guarded post-idle recovery (discard by timestamp, remind, continue).
- `references/session-title-index.md` — history.db `session_titles` read-through-with-backfill ladder replacing content scans; never-version-someone-else's-db ownership rule.
- `references/session-pins-stable-partition.md` — id-keyed pins file, degrade-to-empty corruption handling, stable pinned-first partition preserving recency.
- `references/bash-user-shell-pty.md` — six-clause PTY eligibility ladder, dual output planes (raw renderer vs sanitized capture), color-restoring env surgery.
- `references/session-payload-413-arbitration.md` — payload-vs-token-overflow flag taxonomy, trusted-gate occupancy arithmetic, dual-flag fallback-chain routing, honest usage-backed dead ends.
- `references/session-unexpected-stop-modes.md` — boolean→enum settings migration with off-preserving semantics; mechanical vs smart detection modes.
- `references/builtins-host-contract.md` — owned Host snapshot, spawn_blocking adapter, help/usage exit split, panic containment at the builtin boundary.
- `references/builtins-stdout-buffering.md` — destination-classified StreamWriter (block for files, line otherwise) and shared-writer `2>&1` ordering.
- `references/builtins-child-env.md` — children inherit shell cwd/env/duplicated stderr and never the TUI's stdio; run_captured ordering.
- `references/builtins-registration-sets.md` — default vs utility vs process builtin sets; shadowing utilities opt-in, destructive rm/mv/ln withholdable.
- `references/builtins-rewrite-argv.md` — pre-clap argv rewrites for GNU/BSD syntax clap cannot model (`head -5`, `cut -d=`, `yes --help me`).
- `references/builtins-duration-quote.md` — GNU interval parsing (inf, zero, saturation) and safe single-quote rebuilding of child command lines.
- `references/builtins-proc-snapshot.md` — one ProcInfo contract over /proc / proc_pidinfo / Toolhelp with start-time identity and pidfd delivery.
- `references/builtins-host-processes.md` — ancestor-immunity chain: presence+age walk, late refusal, inline storage, single-snapshot resolution.
- `references/builtins-proc-match-engine.md` — pgrep/pkill/pidwait shared engine: mode-gated flags, pidfile flock, exit taxonomy, newest/oldest arbitration.
- `references/builtins-kill-semantics.md` — signal grammar incl. SIG-prefix rules, `kill -l 137` round-trip, kill(2) target classification with refusal.
- `references/builtins-timeout-spawn-recorder.md` — configured-signal delivery via SpawnObserver pid/pgid capture, `-k` escalation, 124/125/126/127/137 ladder.
- `references/builtins-nohup-detach.md` — transparent background wrapper: persistence is a background concern handled by session reparenting, not the builtin.
- `references/builtins-sort-external.md` — two-thread chunk/recycle pipeline, compressor probe on shell PATH, join-before-return panic surfacing.
- `references/builtins-xargs-limiters.md` — composable command-size limiters over ARG_MAX−2048−env, six-way exit taxonomy.
- `references/builtins-sponge-soak.md` — soak-before-open delayed destination, sibling-temp permission-preserving atomic rename.
- `references/builtins-wc-fastpaths.md` — stat/splice/read byte-count ladder with partial-count handoff and all-or-nothing SIMD gating.
- `references/builtins-tail-follow.md` — notify backend ladder with ENFILE polling degradation and tailable/orphan/parent watch trichotomy.
- `references/builtins-fd-fastpath.md` — conservative const gate for the buffered fast path; WalkDecision pruning ladder with root suppression.
- `references/builtins-rg-defaults.md` — Host-view stdin-vs-cwd default and root-stripping display paths; dual binary-mode searchers.
- `references/builtins-grep-resolution.md` — resolver-function decomposition over grep-searcher with latest-wins index tracking and JIT probe.
- `references/builtins-ps-parser.md` — one argv walker classifying BSD clusters, long options, bare-word groups, and pid lists.
- `references/builtins-top-sampling.md` — start-time-keyed CPU delta map (PID-recycling guard), zero first sample, BrokenPipe-as-success.
- `references/builtins-stat-bsd-rewrite.md` — detect-then-rewrite BSD invocations to GNU argv before clap parsing.
- `references/builtins-date-gnu-plane.md` — modifier pre-scan, depth-counted comment stripping, military-timezone DayDelta rollovers.
- `references/builtins-rm-guards.md` — guard order before resolve: empty operand cwd hazard, canonicalize-based preserve-root, `.`/`..` refusal.
- `references/builtins-mv-crossfs.md` — host-env backup defaults, hardlink/xattr-aware cross-device copy tree.
- `references/builtins-ls-sort-resolution.md` — argv-index last-wins arbitration among mutually exclusive sort flags, command-line-source gated.
- `references/builtins-tr-set-grammar.md` — context-sensitive octal parsing with GNU ambiguous-escape warning; ranges/star/equivalence classes.
- `references/builtins-cut-matchers.md` — memchr ExactMatcher + run-collapsing WhitespaceMatcher behind a one-method trait.
- `references/builtins-small-faithfulness.md` — uniq positional-flag merge, jq thread-local RuntimeGuard shim, tee never-touch-signals policy.
- `references/builtins-panic-containment.md` — PANIC_SCOPE_DEPTH Cell protocol cooperating with the native crash hook.
- `references/builtins-stdin-cancellation.md` — 200 ms poll-sliced stdin reads returning EOF on abort; await-completion-before-return.
- `references/builtins-procsub-materialize.md` — `/dev/fd/<shell-fd>` args dup'd to real process fds with task-lifetime ownership, pre-parse.
- `references/builtins-head-headers.md` — output-latch header rule: failures print no separator and must not flip `first`.
- `references/builtins-find-cancellation.md` — walker-level Interrupted sentinel as the abort channel; per-entry flag polling, silent-abort mapping.

## Capsule map
Each capsule pairs a decisive excerpt, invariants, a live `mcp.codebase_memory.search_graph` call, and a probe at a real test. The map records seams, not history.

- **Patch language** — grammar, parsing, addressing, replay, fs seams: `hashline`, `hashline-fs-stream`, `hashline-parser-seams`, `hashline-normalize-prefixes`, `hashline-clipboard-syntax`, `hashline-format-recovery`.
- **Patch parsing & rejection** — token-to-edit execution and stale-tag refusal: `hashline-executor`, `hashline-mismatch`.
- **Patch orchestration & feedback** — all-or-nothing apply, preview renumbering, noop-loop escalation, snapshot budgets: `hashline-patcher`, `hashline-diff-preview`, `hashline-noop-loop-guard`, `edit-snapshot-budget`.
- **Memory** — facade, recall, embeddings, binary vectors, cache, temporal gates: `mnemopi`, `mnemonic-beam`, `mnemonic-embeddings`, `mnemonic-binary-vectors`, `mnemonic-query-cache`, `mnemonic-temporal-gates`.
- **Telemetry** — usage windows, sync worker, WAL series, gain dashboard, server/port, provider/client: `stats`, `stats-sync-worker`, `stats-db`, `stats-gain-dashboard`, `stats-server-port`, `stats-provider-client`.
- **Harness seams** — steering, wrapper, compaction, replay, navigator, workers, fan-out, experiments, isolation: `agent-loop`, `agent-loop-tool-batch`, `agent-wrapper`, `compaction-suite`, `replay-and-occupancy`, `prewalk-and-plan-handoff`, `durable-workers`, `fanout-and-budgets`, `isolation-and-provider-permits`, `experiment-control`, `advice-delivery`.
- **Streaming** — numbered-line output over byte inputs: `hashline-stream`.
- **Vision compaction** — bitmap-frame context compression for vision LLMs: archive orchestration, shape/billing, serialization, normalization: `snapcompact-archive`, `snapcompact-shape-billing`, `snapcompact-serialization`, `snapcompact-normalization`.
- **Collab wire protocol** — live-session host/guest/relay contract: `collab-wire-protocol`.
- **Benchmark harness (metaharness)** — run store, experiment math, adapters, and manager lifecycle: `bench-run-store`, `bench-experiment-projection`, `bench-arm-inheritance`, `bench-best-of-n`, `bench-trial-parsing`, `bench-adapter-normalization`, `bench-token-accounting`.
- **Benchmark manager ops** — live monitoring, launching, resuming, and cleanup: `bench-live-cost-probe`, `bench-managed-children`, `bench-resume-recovery`, `bench-sse-broadcast`, `bench-trace-tail`, `bench-live-dashboard`, `bench-docker-cleanup`.
- **Benchmarked agent runs** — driving and scoring agent attempts: `bench-edit-agent-loop`, `bench-edit-verification`, `bench-in-process-client`, `bench-retry-ladder`, `bench-early-stop`, `bench-guided-synthesis`, `bench-edit-taxonomy`, plus container/auth infra: `bench-source-deps-cache`, `bench-gateway-isolation`.
- **Benchmark fixture generation (typescript-edit-benchmark)** — the engine behind the edit adapter: uniqueness-provable prompt hunks, AST source-edit mutations, and the re-solve proof: `bench-unique-hunk-rendering`, `bench-ast-mutation-framework`.
- **Model catalog: identity & policy** — namespace-agnostic family predicates, id classification, effort-ladder derivation, host classes: `catalog-family-predicates`, `catalog-id-classifier`, `catalog-thinking-derivation`, `catalog-host-classification`, `catalog-provider-priority`, `catalog-display-name-cleaning`, `catalog-tokenizer-resolution`.
- **Model catalog: variant collapsing** — per-effort sibling ids → one logical model with routing + alias migration: `catalog-variant-collapse`.
- **Model catalog: compat detection** — build-once per-API wire-quirk records: `catalog-anthropic-compat`, `catalog-openai-compat`, `catalog-bedrock-compat`.
- **Model catalog: resolution & caching** — source merge ladders, SQLite cache healing, credential-scoped namespaces: `catalog-resolution-merge`, `catalog-model-cache`, `catalog-cache-namespacing`.
- **Model catalog: discovery & wire** — bounded /models probes, JWT claims, impersonation versioning, image-fetcher attribution, wire-id codecs, protobuf RPC recovery: `catalog-openai-discovery`, `catalog-codex-wire`, `catalog-copilot-wire`, `catalog-client-version-discovery`, `catalog-image-fetcher-attribution`, `catalog-fireworks-wire-ids`, `catalog-cursor-proto-discovery`.
- **Model catalog: proxy & canonical identity** — reseller reference inheritance and canonical-id coalescing: `catalog-proxy-reference`, `catalog-canonical-coalescing`; token pricing: `catalog-token-costing`.
- **Credential storage kernel (packages/ai/src/auth-storage.ts)** — resolution cascade, refresh leases, identity dedupe, usage ranking, stickiness, scoped blocks, report cache, plan gating, failure taxonomy, broker sentinels, bearer attribution: `auth-resolution-cascade`, `auth-oauth-refresh-lease`, `auth-oauth-identity-dedupe`, `auth-usage-ranked-selection`, `auth-session-stickiness`, `auth-scoped-blocks`, `auth-usage-cache`, `auth-codex-plan-gating`, `auth-definitive-failure-taxonomy`, `auth-broker-sentinel`, `auth-bearer-attribution`.
- **Session runtime plane (drift wave @4854db85)** — streamed-edit staleness defense, Gemini runaway recovery, title index, session pins, user-shell PTY, payload-413 arbitration, unexpected-stop modes: `session-streaming-edit-guard`, `session-loop-guards-gemini`, `session-title-index`, `session-pins-stable-partition`, `bash-user-shell-pty`, `session-payload-413-arbitration`, `session-unexpected-stop-modes`.
- **In-process CLI utilities (crates/pi-builtins)** — the host kernel and its ~60 ported tools as portable contracts. Kernel: `builtins-host-contract`, `builtins-stdout-buffering`, `builtins-child-env`, `builtins-registration-sets`, `builtins-rewrite-argv`, `builtins-duration-quote`, `builtins-panic-containment`, `builtins-stdin-cancellation`, `builtins-procsub-materialize`. Process plane: `builtins-proc-snapshot`, `builtins-host-processes`, `builtins-proc-match-engine`, `builtins-kill-semantics`, `builtins-timeout-spawn-recorder`, `builtins-nohup-detach`, `builtins-ps-parser`, `builtins-top-sampling`. Text/file plane: `builtins-sort-external`, `builtins-xargs-limiters`, `builtins-sponge-soak`, `builtins-wc-fastpaths`, `builtins-tail-follow`, `builtins-fd-fastpath`, `builtins-find-cancellation`, `builtins-rg-defaults`, `builtins-grep-resolution`, `builtins-stat-bsd-rewrite`, `builtins-date-gnu-plane`, `builtins-rm-guards`, `builtins-mv-crossfs`, `builtins-ls-sort-resolution`, `builtins-tr-set-grammar`, `builtins-cut-matchers`, `builtins-head-headers`, `builtins-small-faithfulness`.

## Extending the foundation
Add one `references/*.md` capsule per new seam: a catalog line, a decisive excerpt, an invariant, a `Probe`, a `search_graph` call. Reuse the pattern. Pass 11 added the 24 `catalog-*` capsules from `packages/catalog`; pass 12 added the 11 `auth-*` capsules from `packages/ai/src/auth-storage.ts` + its sqlite store twin; new seams still start from a mechanical citation-vs-inventory grep.

## Provenance
oh-my-pi (MIT), `main@4854db856`; Codebase Memory project `oh-my-pi` (111,148 nodes / 592,586 edges, `full` index re-pinned 2026-08-24 after a +545-commit upstream drift wave — tests graph-covered; only `parse_partial` ranges read directly). Pass 13 mined the drift wave's session-runtime plane (+7 capsule-v2, 101→108); live symlink root `/mnt/hdd/utopia/inspo/oh-my-pi` → `coding-agents/oh-my-pi`, refreshed in place per the [DONE:366] live-symlink precedent; content freshness proven by resolving drift-introduced symbol `canUseInteractiveBashPty`. Pass 14 (2026-08-24) entered `crates/pi-builtins` at the SAME pin (zero upstream drift: `git rev-list HEAD..origin/main` = 0 after fetch) and added 34 capsule-v2 (108→142); graph state re-verified this pass (`index_status` ready at identical counts).

## Full view (memory graph)
Revalidate `oh-my-pi` before porting: run `index_status`, `check_index_coverage`, `search_graph`, `trace_path`, and `get_code_snippet`. Live at this squeeze: root `/mnt/hdd/utopia/inspo/oh-my-pi` (live symlink into `coding-agents/oh-my-pi`), branch `main@4854db85`, mode `full`, 111,148 nodes / 592,586 edges; parse_partial limited (vendor `.proto` trees plus single-line TS gaps); assets/vendor excluded by design. Source and direct tests decide shipped claims. Pass-14 note on the pi-builtins retrieval plane: BM25 resolves Function/Method/Struct nodes line-exact for the kernel symbols (`HostProcesses.walk` :1167-1198, `SpawnRecorder.signal` :107-123, `soak_stdin` :106-121, `is_regular_file` :393-398, `CommandSizeLimiter` :82-89, `pidfile_is_locked` :899-913); small-faithfulness seams (uniq/jq/tee internals, tail watcher config) rank below generic noise — their capsules cite anchor greps instead of ranked hits, which is a plane property, not dead metadata.

## Boundaries
Pass 14 (2026-08-24, THIS pass, crates/pi-builtins @ zero-drift pin 4854db8): whole-file read `host.rs` (1,292L — Utility trait/Host/StreamWriter/ChildEnv/Stdin/panic-scope/duration+quote helpers) and `proc_snapshot.rs` (1,399L incl. its synthetic-tree test suite), plus `factory.rs`, `proc_match.rs` (970L), `sponge.rs` (280L), `builder.rs`, `unimp.rs`, and targeted deep reads of sort/tail/xargs/wc/fd/rg/grep/ps/top/stat/date/rm/mv/ls/tr/cut/head/uniq/jq/kill/timeout/nohup → 34 capsule-v2 in the new "In-process CLI utilities" map group (kernel 9 / process plane 8 / text-file plane 17). Omitted-with-reason this pass: `sed.rs` 9,635L command grammar (the sed script language is a standalone spec; its I/O runs on the captured host contract — mine only if a sed-language porting question emerges); remaining per-tool bodies beyond their distinctive seams (`find.rs` expression evaluator internals, `ls.rs` column renderer, `date.rs` full word-tokenizer table, `jq.rs` jaq binding breadth) — each tool's PORTABLE contract is its host integration + the specific seam captured, not a line-by-line algorithm re-derivation available upstream; `Cargo.toml` dependency pins (declarative); `complete.rs`/`bind.rs`/readline-facing bash builtins (interactive-TUI surface). Runner: cargo test BLOCKED honestly — stable rustc 1.97.1 without rustup/nightly; workspace dep `xutf` needs `#![feature(portable_simd)]` → E0554 (extends the standing pi-natives E0554 block to any crate pulling xutf). Deterministic gate-5 instead: every capsule's Probe anchor executed byte-exact from repo root pre- and post-write (24/24 GREEN: per-file `grep -c` anchors + direct-test name pins verified present at cited lines); Retrieve liveness live-executed for kernel/process-plane queries with wrong-project adversarial check (graphiti same-terms total:0 relevant). Prior pass 13: mined the drift wave's session-runtime plane into 7 capsule-v2 — `stream-guards.ts` whole (498L), `title-index.ts` whole (112L), `session-pins.ts` whole (44L), `bash-pty-selection.ts` whole (14L), `bash-executor.ts` PTY plane, `flags.ts`/`session-maintenance.ts` payload-413 arbitration funnel, settings boolean→enum migration. Omitted-with-reason pass 13: `history-storage.ts` churn, extensions inspector #9311 (TUI product surface), unexpected-stop classifier body. Prior pass 12: mined the credential-storage kernel — `packages/ai/src/auth-storage.ts` (6,886L whole) + `sqlite-credential-store.ts` identity plane — into 11 `auth-*` capsules. Omitted-with-reason pass 12: SqliteAuthCredentialStore SQL body, usage/* fetcher SPI adapters, providers/** wire adapters (~59k LOC — still next-pass target), coding-agent session/controllers/config mass. | All Oh My Pi material lives under this single foundation; prewalk, vibe workers, task orchestration, experiment control, and advisor delivery are all `references/` capsules here, not sibling leaves. Adopt pure contracts; adapt provider dialects, storage, and token estimators; omit OMP-specific telemetry and transports. Edit family (2026-08-23 sweep): every `packages/hashline` module plus `execute`/`patcher`/`snapshot-details` is mapped to a capsule above or an omit-with-reason in the work record; `messages.ts` stays un-capsuled deliberately. Vision-compaction family (pass 7): whole `packages/snapcompact` mapped to four capsules; native PNG rasterizer omitted by design. Collab wire family (pass 8): `packages/wire/src/index.ts` → `collab-wire-protocol`; live-session collab runtime omitted. Benchmark-harness family (pass 9): whole `packages/metaharness` → 21 `bench-*` capsules. Pass 10: fixture-generation engine `packages/typescript-edit-benchmark` → 4 capsules; trace-report/live-progress/prompts omitted with reason. Pass 11: mined `packages/catalog` (~52k lines whole-file) into 24 capsules — identity/variant-collapse/thinking/hosts/cache/manager/compat/wire/discovery/equivalence; omitted with reason: provider-models/openai-compat.ts option builders, generated proto IR, types.ts/models.json.