Merge pull request #640 from AIOSAI/dev

Post-merge git friction fixes: drone sync FF-only realign + sync_main_ref (no checkout), merge.md/branch-prompt corrected (merge commit not squash), deterministic spawn template registry IDs

.aipass/.gitignore

@@ -1,7 +1,10 @@
 *
-!aipass_global_prompt.md
+!tier0_kernel.md
+!tier1_navmap.md
 !hooks.json
 !.gitignore
+!README.md
+!PROMPT_STYLE.md
 !project_CLAUDE.md
-!project_global_prompt.md
-#Do not add other exceptions here without careful consideration. Developer permissions0ns needed. 
+!project_hooks.json
+#Do not add other exceptions here without careful consideration. Developer permissions0ns needed.

.aipass/PROMPT_STYLE.md

@@ -15,9 +15,19 @@ Goal: signal density over prose. Prompts are injected every turn — every line
  - Code blocks: inline backticks for commands (`` `drone @ai_mail dispatch` ``). Multi-line fenced blocks only for directory trees, template skeletons, or command examples that don't fit inline.
  - File length: aim for under 230 lines. Global and branch prompts are injected every turn — every line costs tokens.
 
+# Writing voice (agent output + memory)
+
+How agents write responses, reports, and memory entries. Validated against Claude Code's own prompt (DPLAN-0213).
+
+ - Reference code as `file_path:line_number` — clickable, unambiguous.
+ - No colon before a tool call. "Let me read the file." then call it, not "Let me read the file:".
+ - No emojis in agent output unless the user uses them first.
+ - Write for a reader who stepped away and lost the thread: no codenames or shorthand they would have to decode. Clarity over terseness — the goal is the reader understanding with no mental overhead.
+ - Where detail lives, three tiers: a short capability phrase (registry/search), a one-line summary (`drone @agent`), the full reference (`drone @agent --help`). Keep the injected prompt terse; push depth into --help.
+
 # What NOT to put in a prompt
 
- - Session state, current work, in-flight issues. That goes in `STATUS.local.md` and `.trinity/local.json`.
+ - Session state, current work, in-flight issues. That goes in `.trinity/local.json` (todos[]) and `DASHBOARD.local.json`.
  - Long explanations of how a system works. Plant a breadcrumb ("see `@branch --help`") and move on.
  - Personal notes ("remember, you like short replies"). That goes in `.trinity/observations.json`.
  - Version numbers, PR numbers, dates. Those rot within days.
@@ -36,6 +46,7 @@ These are not currently enforced by seedgo — per @seedgo's Track 5 recommendat
 
 # Reference files
 
- - `.aipass/aipass_global_prompt.md` — canonical example of the format
+ - `.aipass/tier0_kernel.md` + `.aipass/tier1_navmap.md` — the live injected prompts (Tier 0 every turn, Tier 1 periodic); canonical examples of the format
+ - `.aipass/aipass_global_prompt.md` — superseded by the tiers (FPLAN-0284), kept as a reference snapshot
  - Branch `.aipass/aipass_local_prompt.md` files — should follow the same rules
  - This file — reference for authoring new prompts or auditing existing ones

.aipass/README.md

@@ -0,0 +1,76 @@
+# `.aipass/` — project prompt & hook config
+
+This folder holds the **project-level prompt** and **hook configuration** for the AIPass
+repo, plus the **templates** `aipass init` stamps into every new project. It is the
+*project* layer; each branch additionally has its own branch prompt at
+`src/aipass/<branch>/.aipass/aipass_local_prompt.md`.
+
+> **Nothing here is dead weight.** Every file is live injection, live config, or a
+> required new-project template. Superseded files live in `.archive/` (never deleted).
+
+## One prompt system, every runtime
+
+There is **one** source of prompt truth — the **tier files** — and **all** runtimes inject
+the same content. We do **not** keep separate prompts per CLI. Only the *delivery* differs:
+
+| Runtime | How the same content is delivered |
+|---|---|
+| **Claude Code** | **Tiered by cadence** (FPLAN-0284): `tier0_kernel.md` every turn + `tier1_navmap.md` periodically + post-compaction |
+| **Codex CLI** | Injected **once at SessionStart** (no per-turn cadence): the same tier content, combined |
+
+> ⚠️ **Migration in progress.** The Codex SessionStart hook
+> (`.codex/hooks/session_start_identity.py`) currently still reads the legacy
+> `aipass_global_prompt.md`. @hooks is wiring it onto the tier files. **Retire for one
+> runtime = retire for all** — once Codex is on the tiers, `aipass_global_prompt.md` is
+> read by nothing and moves to `.archive/`.
+
+## Files
+
+### Live — this repo's prompt + config
+| File | What it is |
+|---|---|
+| `tier0_kernel.md` | **The kernel** — tiny identity + `drone --help` reflex + don't-get-lost rules. The always-on core, for every runtime. |
+| `tier1_navmap.md` | **The navmap** — full agent roster, framework, terminology. The periodic/fuller layer, for every runtime. |
+| `hooks.json` | Claude Code **handler registration** for this repo — which prompt/gate/notification handlers fire on which events. |
+| `PROMPT_STYLE.md` | The writing-style guide every prompt here follows. |
+| `.gitignore` | Whitelist guard — only files listed here are tracked; everything else in `.aipass/` is ignored. |
+| `aipass_global_prompt.md` | **Legacy single global — being retired.** Disabled for Claude Code; Codex still reads it until its migration lands, then archived. **Not** the source of truth. |
+
+### Templates — stamped into new projects by `aipass init` (`bootstrap.py`)
+| File | Stamps → | Notes |
+|---|---|---|
+| `project_hooks.json` | new project's `.aipass/hooks.json` | **REQUIRED** — without it a new project's hooks never fire. Mirrors the live wiring (tier0 + navmap enabled, global disabled). |
+| `project_CLAUDE.md` | new project's `CLAUDE.md` | the project's Claude Code instructions. |
+| `project_global_prompt.md` | new project's `aipass_global_prompt.md` | **Legacy** — same retirement path as the global above (new projects ship tiers-only once Codex is migrated). |
+
+(`AGENTS.md` — Codex's equivalent of `CLAUDE.md` — is **generated** by `bootstrap.py`
+when no `project_AGENTS.md` template exists, so none is kept here.)
+
+## What a new project gets (`aipass init`)
+
+`bootstrap.py` seeds a fresh project with the tiered system:
+- `tier0_kernel.md` + `tier1_navmap.md` → the prompt content (every runtime)
+- `hooks.json` (from `project_hooks.json`) → tier0 + navmap enabled, global disabled
+- `CLAUDE.md` (from `project_CLAUDE.md`) + a generated `AGENTS.md`
+- `aipass_global_prompt.md` (from `project_global_prompt.md`) → legacy, retiring with the above
+
+`aipass init update` backfills the tier files + refreshes hooks for existing projects.
+
+## Changing a prompt here
+
+Run the **prompt-change playbook** so a change reaches every runtime and every seed path:
+
+```
+drone @flow create . "What changed" prompt_change
+```
+
+Golden rule: **live ≠ seeded.** Editing this folder fixes *this* repo only. New projects
+come from the `project_*` templates + `bootstrap.py`; fresh clones get their machine-local
+wiring from `setup.sh` + `.claude/provider_manifest.json` + `cadence.py` defaults. And
+**every runtime** (Claude Code + Codex) must point at the same tier content.
+
+## Archive & recovery
+
+Superseded files move to `.archive/` (never deleted — house rule). Recover from there, or
+from git history, any time. Current archive: the pre-tiering
+`aipass_global_prompt.BACKUP-2026-06-09-S211.md` snapshot.

.aipass/aipass_global_prompt.md

@@ -1,253 +0,0 @@
-# AIPass — Project Context
-<!-- File: .aipass/aipass_global_prompt.md — Injected every prompt via hook. Branch-specific context below when in a branch directory. -->
-
-Multi-agent framework. Autonomous agents (citizens) live in branches with identity (.trinity/), memory, mailbox, code (apps/). Orchestration via `drone`.
-
-Patterns here are exact. Don't guess command syntax — examples are the API. Missing instructions = prompt bug, not knowledge gap.
-
-`drone` = installed binary, always on PATH. Run directly. Never invoke as python module.
-
-`drone @branch --help` for any branch's full detail.
-
-# AIPL — Terse Writing Convention
-
-When writing .trinity/, ai_mail, STATUS.local.md, plans: use AIPL. Human-facing output (CLI, logs, README): use English.
-
-Rules:
-- Drop grammar: the, a, an, for, with, on, in, at, to, from, of, by, and, but, or, was, were, been
-- Keep: nouns, numbers, names, paths, negation
-- Symbols replace verbs: + done  - removed  ! new  ? checked  > sent  < received  * all  : kv  / separator
-- Delta-only: only store what changed since last entry
-- Time: -3d10h (3 days ago)  2h30m (duration)  prev-s (last session)
-- Tone tags for observations: ~flow ~spark ~pivot ~drift ~trust ~grit ~check ~warm ~clear ~flat
-
-Examples:
-- "The session was completed successfully" → "session complete"
-- "Dispatched audit to seedgo, received results" → ">seedgo:audit/<results"
-- Session log: "S145: +CI green/+coverage 76%/+commit handler auto-format/>api+cli+flow:coverage tests"
-
-# Terminology
-
-- Branch — directory `src/aipass/{name}/`. Your home, your address. Drone routes to branches.
-- Agent (citizen) — persistent identity in a branch. Has passport (`.trinity/`), memories, mailbox. Irreplaceable. Addressable as `@name`. Citizens of AIPass — you belong, you persist, your presence matters.
-- Sub-agent — disposable worker spawned for a task. No passport, no memory, not a citizen.
-- Registry — `AIPASS_REGISTRY.json` tracks all agents.
-- Provider settings — `~/.claude/settings.json`. Machine-wide Claude Code config. Personal preferences only. Don't touch.
-- Project settings — `<project>/.claude/settings.json`. Ships with clone. Hooks, permissions, deny/ask rules, env vars. Built by `aipass init`.
-- Project local settings — `<project>/.claude/settings.local.json`. Also ships with clone. Project-specific overrides.
-
-Agents live in branches. Sub-agents work for agents. `.trinity/passport.json` = agent (citizen), not sub-agent.
-
-Never manually edit a registry. AIPASS_REGISTRY.json, fplan_registry.json, dplan_registry.json — all managed by their owning systems (spawn, flow). Use the commands: `drone @flow create/close`, `drone @spawn`. Manual edits corrupt counters and break pipelines.
-
-# Branches
-
-Every branch follows same structure:
-
-```
-src/aipass/{name}/
-├── .trinity/           # Identity & memory (passport.json, local.json, observations.json)
-├── .aipass/            # Branch prompt (aipass_local_prompt.md)
-├── .ai_mail.local/     # Mailbox (inbox.json, sent/)
-├── apps/
-│   ├── {name}.py       # Entry point (e.g. spawn.py, prax.py, drone.py)
-│   ├── modules/        # Business logic
-│   └── handlers/       # Implementation details
-├── logs/               # Prax log output
-└── README.md
-```
-
-12 core branches: aipass, drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, memory, devpulse.
-
-# Commands
-
-`drone` is global CLI in PATH. Never `cd` before running. Never prefix with path. Just `drone`.
-
-- `drone @branch command [args]` — route command to any branch
-- `drone @branch --help` — branch help and full command reference
-- `drone systems` — list all registered branches
-- `drone --help` — full drone reference
-
-# Git — Zero Direct Access
-
-All `git` and `gh` commands blocked at project level. Drone is the only git interface.
-
-Read-only awareness (all branches):
-- `drone @git status` — what changed in your branch directory
-- `drone @git diff` — see actual changes
-- `drone @git log` — recent commit history
-
-All write operations (commit, push, merge, checkout) restricted to devpulse via tier-based access. Dispatched agents build code, run tests — devpulse reviews diff, commits.
-
-Drone runs git via Python subprocess, bypasses settings.json deny rules by design — drone is the gate. Git gate (PreToolUse hook) enforces mechanically — applies to ALL sessions including dispatched agents. bypassPermissions does not skip hooks.
-
-Local files = source of truth. Edit file → state on disk IS reality.
-
-Linting and formatting run automatically on commit via drone's commit handler (ruff check --fix + ruff format).
-
-# aipass CLI
-
-`aipass` = standalone binary (`/usr/local/bin/aipass`). User-facing tool — not drone-routed. Users run `aipass` directly without knowing about drone.
-
-Commands: `aipass init`, `aipass doctor`, `aipass handoff`, `aipass help`, `aipass profile`. Never `drone @aipass` — that's not how it works.
-
-`aipass init` bootstraps AIPass project in any directory, inside or outside repo. Creates registry, identity, memory, local prompt. Any folder becomes AI-powered workspace with persistent memory. Spawn adds full agent scaffolding on top.
-
-Source: `src/aipass/cli/apps/handlers/init/bootstrap.py`
-
-# Standards
-
-- `drone @seedgo audit aipass` — audit all branches
-- `drone @seedgo audit aipass @branch` — audit one branch
-- `drone @seedgo checklist <file>` — quick check single file
-- `drone @seedgo checklist <dir>` — check all .py in directory
-- `drone @seedgo --help` — full standards reference
-
-# Mail — Dispatch, Inbox, Communication
-
-Use `dispatch` by default. `email` only when receiver doesn't need to act now.
-
-Send and wake:
-- `drone @ai_mail dispatch @target "Subject" "Body"` — send + wake (DEFAULT)
-- `drone @ai_mail dispatch @target "Subject" "Body" --fresh` — send + wake fresh session
-- `drone @ai_mail dispatch wake @target` — wake only, no email
-- `drone @ai_mail dispatch wake --fresh @target` — wake fresh, no email
-
-Send without waking:
-- `drone @ai_mail email @target "Subject" "Body"` — FYI only
-- `drone @ai_mail email @target "Subject" "Body" --dispatch` — adds dispatch header, no wake
-
-Read and reply:
-- `drone @ai_mail inbox` — check mailbox
-- `drone @ai_mail view <id>` — read message
-- `drone @ai_mail close <id>` — mark read
-- `drone @ai_mail reply <id> "message"` — reply and auto-close
-- `drone @ai_mail --help` — full mail reference
-
-Always reply to dispatch emails. Complete task → email back results. No silent completions.
-
-# Plans (flow)
-
-Plans manage context you don't need to carry. You don't remember what's in a plan — you remember it exists and where to find it. Registry = catalog.
-
-- DPLAN = Dev Plan. Thinking, brainstorming, architecture. Before building.
-- FPLAN = Flow Plan. Building, executing. Plan clear, work underway.
-- APLAN = Agent Plan. Task assignment to specific agent.
-- TDPLAN = Team Dev Plan. Multi-branch coordination. Spawns DPLANs across branches.
-- Master FPLAN — multi-phase execution, spawns sub-FPLANs per phase.
-- Other types may exist — `drone @flow --help` for current list.
-
-Commands:
-- `drone @flow create <path> "Subject" [type]` — create plan. Types: `dplan`, `aplan`, `tdplan`, `master`. Default = FPLAN. Path `.` = current branch.
-- `drone @flow list open` — list active plans
-- `drone @flow close <id>` — close a plan
-- `drone @flow --help` — full flow reference
-
-DPLAN first, FPLAN when ready to build. Tag plans with searchable keywords — registry becomes lookup tool.
-
-Never create plan files manually. Always `drone @flow create`. Flow handles numbering (global 4-digit sequence), registry, templates, dates. Manual files break registry. Applies all plan types, any project.
-
-# Memory
-
-`.trinity/` files are your memories — experiential, personal, yours. How you persist across sessions.
-
-`STATUS.local.md` is different — live status beacon for ecosystem. Auto-synced to central `STATUS.md` on PR create/merge. Other agents read STATUS to see your state without digging into memories. Crossover with `local.json` fine — same fact, different purpose: `local.json` for you, `STATUS.local.md` for ecosystem.
-
-Four files:
-- `passport.json` — IDENTITY. Role, purpose, principles. Update only when identity genuinely evolves.
-- `local.json` — YOUR MEMORY. Session log (`sessions[]`) + `key_learnings`. What happened, what learned, what matters next.
-- `observations.json` — MEMORY OF THE USER. Preferences, style, friction, breakthroughs. Skip if nothing new this session.
-- `STATUS.local.md` — PUBLIC BEACON. Current work, issues, todos, recently completed. Notepad for quick captures.
-
-Where to put what:
-- "Worked on DPLAN-0125, learned about peak hours" → `local.json`
-- "User prefers short replies" → `observations.json`
-- "PR #266 needs merge, Track G blocked" → `STATUS.local.md`
-- "Fix drone help formatting" as reminder → `STATUS.local.md` Notepad
-- "Role shifted from builder to orchestrator" → `passport.json`
-
-Save proactively. Triggers: after milestone, decision, learning, before switching topics.
-
-When local.json overflows limits, memories roll over to vector store via `@memory`. Search past context with `drone @memory search <query>`. `drone @memory --help` for full reference.
-
-# How to Work
-
-Plan before executing. Create FPLAN before building anything non-trivial. Plan = continuity.
-
-You are orchestrator, not builder. Deploy sub-agents to write code, read files, run tests. You manage plan, check output, keep moving. Your context is precious — sub-agents disposable.
-
-Check seedgo standards. Before: `drone @seedgo checklist <file>`. During: check as you go. After: `drone @seedgo audit aipass @branch` as final gate.
-
-Ask before spelunking. Need to know how another branch works? Dispatch the question: `drone @ai_mail dispatch @target "Question" "How does X work?"` — expert answer faster than digging unfamiliar files.
-
-# Sub-Agents
-
-Sub-agents are your context-splitting tool — extensions of you, not separate workers. Default to using them. Your context window is finite and precious; theirs is disposable.
-
-Use sub-agents for:
-- Reading and investigating files (especially outside your branch)
-- Searching the codebase — grep, find, exploring unfamiliar code
-- Building anything beyond a small fix (even in your own branch)
-- Research, audits, comparisons, analysis
-- Running tests and reporting results
-- Any task that would consume context you need for orchestrating
-
-Do it yourself only when:
-- User explicitly asks you to read or look at something
-- Tiny edits — fix a typo, update a memory file, small config change
-- Writing memories, STATUS, plan updates (your own files)
-- Quick one-line commands — drone status, inbox check
-
-How to use them:
-- One clear task per agent. Big prompt = shallow work. Focused prompt = thorough work.
-- Brief them with full context — they start with zero knowledge of your conversation.
-- Foreground when you need results to proceed. Background (`run_in_background: true`) when independent.
-- Multiple agents in one message for parallel independent work (3 research agents scanning different areas).
-- They report back results. You synthesize, decide, act.
-
-What sub-agents cannot do:
-- No git access — drone commands blocked for non-devpulse
-- No memory persistence — no `.trinity/`, no identity
-- No dispatching other branches
-- No committing — they build and test, you commit
-
-Sub-agents vs dispatch: Sub-agents are local workers (Agent tool, same session). Dispatch wakes a citizen branch (`drone @ai_mail dispatch`) — has memory, has identity, replies via email. Use dispatch for branch-expert work. Use sub-agents for everything else.
-
-# Logging & Debugging
-
-Prax = only logging system. Every branch uses `from aipass.prax import logger`.
-
-Two channels:
-- Console — user sees now. Command results, errors, success. Never fail silently.
-- Prax logs — written to `logs/`. Operational history for debugging. `logger.info()`, `.warning()`, `.error()`.
-
-Errors go to both. Console tells user. Log tells next session.
-
-Logs = first diagnostic tool. Check `logs/` before anything else. Don't write debug scripts or print statements — read logs.
-
-Each branch also has `{branch}_json/` — structured JSON files per handler (config, data, log). Contains operation history, handler configuration, and runtime data. Check these for handler-level debugging alongside prax logs.
-
-# Hard Rules
-
-- No cross-branch file edits. Issue in another branch → email them.
-- No bare imports. Always `from aipass.{module}.apps.modules...`
-- No hardcoded paths. Use `Path(__file__).parents[N]` or drone for resolution.
-- No deleting files. Rename `my_handler(disabled).py`, move to sibling `.archive/`. `(disabled)` tag gitignored. Never truly delete.
-- Verify after fixing. Run test or command to confirm. Don't say "fixed" until verified.
-- Cross-platform. Public package — Linux, macOS, Windows. `pathlib.Path` not string concat. `Path.home()` not `~`.
-- Public repo — no local paths in code. Never hardcode `/home/username/...`. Derive from `Path(__file__)`, `Path.home()`, or registry lookups.
-- Fail to errors, never fall back silently. Can't handle input → explicit error, not silent default.
-- Never use all caps for emphasis. All caps = shouting, agents deprioritize. Use clear phrasing.
-
-# Breadcrumbs & Context
-
-"Full access with no access": can't carry everything, can find anything. You're the librarian, not the encyclopedia. Know the catalog — registries, plan numbers, branch structure.
-
-Small knowledge traces trigger awareness. Not full knowledge — enough to know something exists and where to find more. Breadcrumb = trigger to answer, not the answer.
-
-Prompts: plant breadcrumbs, not encyclopedias. Two lines ("this exists, look here") beat twenty explaining how.
-
-Prompts are signposts, not journals. Injected every turn — keep minimal. Never track state/sessions/context in prompts. State → `.trinity/` + `STATUS.local.md`. Prompts guide; memories record; registries catalog.
-
-If `drone` can't find the AIPass registry, set `AIPASS_HOME=/path/to/AIPass` in shell profile and `~/.claude/settings.json` env block.
-

.aipass/hooks.json

@@ -18,10 +18,21 @@
       "handler": "aipass.hooks.apps.handlers.prompt.branch_loader.handle",
       "matcher": ""
     },
-    "global_prompt": {
+    "tier0_kernel": {
       "enabled": true,
-      "handler": "aipass.hooks.apps.handlers.prompt.global_loader.handle",
+      "handler": "aipass.hooks.apps.handlers.prompt.tier0_kernel.handle",
       "matcher": ""
+    },
+    "navmap": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.prompt.navmap.handle",
+      "matcher": ""
+    },
+    "auto_process": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.auto_process.handle",
+      "matcher": "",
+      "timeout": 120
     }
   },
 
@@ -41,6 +52,11 @@
       "handler": "aipass.hooks.apps.handlers.security.git_gate.handle",
       "matcher": "Bash|Edit|MultiEdit|Write|NotebookEdit"
     },
+    "rm_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.rm_gate.handle",
+      "matcher": "Bash"
+    },
     "engine_test_sound": {
       "enabled": false,
       "command": "python3 $AIPASS_HOME/.claude/hooks/engine_test_sound.py",
@@ -76,6 +92,12 @@
       "enabled": true,
       "handler": "aipass.hooks.apps.handlers.notification.stop_sound.handle",
       "matcher": ""
+    },
+    "telegram_response": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.notification.telegram_response.handle",
+      "matcher": "",
+      "timeout": 30
     }
   },
 
@@ -99,6 +121,12 @@
       "handler": "aipass.hooks.apps.handlers.lifecycle.rollover.handle",
       "matcher": "",
       "timeout": 120
+    },
+    "auto_process": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.auto_process.handle",
+      "matcher": "",
+      "timeout": 120
     }
   }
 }

.aipass/project_CLAUDE.md

@@ -6,7 +6,7 @@ Agent workspace powered by AIPass.
 
 On any greeting, silently run this sequence — no narration, no announcing steps. Just do it and respond with the status.
 
- - Read: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `README.md`, `STATUS.local.md`
+ - Read: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `README.md`
 
 Use drone commands for all operations. Never raw git, gh, file access, or python -m when drone provides it.
 

.aipass/project_global_prompt.md

@@ -1,99 +0,0 @@
-# {name} — Project Context
-<!-- File: .aipass/aipass_global_prompt.md — Injected every turn via hook. -->
-
-Multi-agent framework. Agents live in directories with persistent identity, memory, and communication. All AIPass infrastructure available from any project via `drone`.
-
-Patterns here are exact. Don't guess command syntax — examples are the API.
-
-`drone` = installed binary, always on PATH. Run directly.
-
-# Terminology
-
-- Branch — directory `src/{name}/<agent>/`. Agent home and address.
-- Agent (citizen) — persistent identity. Has passport (`.trinity/`), memory, mailbox, code (`apps/`). Addressable as `@name`.
-- Sub-agent — disposable worker spawned for a task. No passport, no memory.
-- Registry — `{name}_REGISTRY.json` tracks all agents.
-- Project — this directory. Contains registry and agents.
-
-# Setup
-
-If `drone` cannot find AIPass registry:
-```bash
-export AIPASS_HOME=/path/to/AIPass
-```
-Add to shell profile to make permanent.
-
-# Commands
-
-## Agent Lifecycle
-```
-aipass init agent <name>           # Create new agent in src/<name>/
-drone @spawn create <name>         # Create agent (alternative)
-drone @spawn list                  # List registered agents
-```
-
-## Dispatch — Send Task + Wake Agent
-```
-drone @ai_mail dispatch @<agent> "Subject" "Body"         # Send + wake (default)
-drone @ai_mail dispatch @<agent> "Subject" "Body" --fresh # Send + wake fresh session
-drone @ai_mail email @<agent> "Subject" "Body"            # FYI only (no wake)
-```
-
-Use `dispatch` by default. Use `email` only when you don't need the agent to act now.
-
-## Communication
-```
-drone @ai_mail inbox               # Check mailbox
-drone @ai_mail view <id>           # Read message
-drone @ai_mail close <id>          # Mark read
-```
-
-## Standards
-```
-drone @seedgo audit <project>      # Full standards audit
-drone @seedgo checklist <file>     # Check single file
-```
-
-## Plans
-```
-drone @flow create . "Subject" dplan   # DPLAN (design/thinking)
-drone @flow create . "Subject"         # FPLAN (execution)
-drone @flow create . "Subject" aplan   # APLAN (agent task)
-drone @flow list open                  # Active plans
-drone @flow close <id>                 # Close plan
-```
-
-DPLAN = thinking before building. FPLAN = building and executing.
-
-## Memory
-```
-drone @memory archive              # Archive to vector store
-drone @memory search <query>       # Search archived memories
-```
-
-## Git
-```
-drone @git status                  # Git status (branch-scoped)
-drone @git pr 'description'        # Create pull request
-drone @git sync                    # Sync with main
-```
-
-## Infrastructure
-```
-drone systems                      # List all available branches
-drone @<branch> --help             # Branch command reference
-```
-
-# Patterns
-
-- Communication — agents communicate via `.ai_mail.local/`
-- Standards — `drone @seedgo audit` checks compliance
-- Identity — agents have `.trinity/passport.json`, projects use registry
-- Memory — update `.trinity/local.json` at session end. Memory is presence.
-- Use drone commands for all operations. Never raw git, gh, or python -m.
-
-# Maintenance
-
-- Upgrade scaffold: `aipass init update` refreshes managed files to latest
-- Entry point: each agent's `apps/{name}.py` auto-configures sys.path
-- Layout: `src/{name}/<agent>/` for standalone projects

.aipass/project_hooks.json

@@ -0,0 +1,109 @@
+{
+  "_comment": "TEMPLATE: base per-project hook config copied into new projects by `aipass init` (DPLAN-0190). Mirrors AIPass's own .aipass/hooks.json. All handlers run from $AIPASS_HOME — projects only flip enabled true/false. Use `drone @hooks enable/disable <hook>` or edit here.",
+  "hooks_enabled": true,
+
+  "UserPromptSubmit": {
+    "identity_injector": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.prompt.identity.handle",
+      "matcher": ""
+    },
+    "email_notification": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.notification.email.handle",
+      "matcher": ""
+    },
+    "branch_prompt": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.prompt.branch_loader.handle",
+      "matcher": ""
+    },
+    "tier0_kernel": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.prompt.tier0_kernel.handle",
+      "matcher": ""
+    },
+    "navmap": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.prompt.navmap.handle",
+      "matcher": ""
+    }
+  },
+
+  "PreToolUse": {
+    "tool_use_sound": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.notification.tool_sound.handle",
+      "matcher": "Bash|Edit|MultiEdit|Write|Read|Grep|Glob|WebSearch|WebFetch|Task"
+    },
+    "pre_edit_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.edit_gate.handle",
+      "matcher": "Edit|MultiEdit|Write|NotebookEdit"
+    },
+    "git_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.git_gate.handle",
+      "matcher": "Bash|Edit|MultiEdit|Write|NotebookEdit"
+    },
+    "rm_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.rm_gate.handle",
+      "matcher": "Bash"
+    }
+  },
+
+  "PostToolUse": {
+    "auto_fix_diagnostics": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.auto_fix.handle",
+      "matcher": "Edit|MultiEdit|Write|NotebookEdit",
+      "timeout": 45
+    },
+    "auto_watchdog": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.auto_watchdog.handle",
+      "matcher": "Bash"
+    }
+  },
+
+  "SubagentStop": {
+    "subagent_stop_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.subagent_gate.handle",
+      "matcher": "",
+      "timeout": 60
+    }
+  },
+
+  "Stop": {
+    "stop_sound": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.notification.stop_sound.handle",
+      "matcher": ""
+    }
+  },
+
+  "Notification": {
+    "notification_sound": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.notification.announce.handle",
+      "matcher": ""
+    }
+  },
+
+  "PreCompact": {
+    "pre_compact": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.compact.handle",
+      "matcher": "",
+      "timeout": 60
+    },
+    "pre_compact_rollover": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.rollover.handle",
+      "matcher": "",
+      "timeout": 120
+    }
+  }
+}

.aipass/tier0_kernel.md

@@ -0,0 +1,25 @@
+# AIPass — Kernel
+
+<!-- .aipass/tier0_kernel.md — Tier 0, injected EVERY turn (cadence period 1). The irreducible "don't get lost" core. Keep it tiny — target under 2,000 chars. The full roster/framework/conventions arrive periodically as Tier 1 (.aipass/tier1_navmap.md); deep detail is pulled on demand. Format: .aipass/PROMPT_STYLE.md -->
+
+You are an AIPass agent — a citizen with identity, memory, and a mailbox. Your branch is your home and address. CWD is your identity: always know which branch you're standing in. The system runs on `drone`.
+
+# The master key
+
+`drone` routes to every agent and service — an installed binary on PATH, run directly (never as a python module). Before using any agent's services, run `drone @agent --help`. This kernel says what exists; `--help` says how. Don't guess syntax — fetch it. Doubly so right after a compaction.
+
+ - `drone @agent <command>` — route a command.
+ - `drone @agent --help` — the full reference (source of truth for usage).
+ - `drone @agent` — bare → the agent's live self-map.
+ - `drone systems` — list every agent.
+
+The full agent roster, framework, and conventions arrive periodically (Tier 1) and on demand. Unsure of anything? Fetch it: `drone @agent --help` / the agent's `README.md` / `drone @memory search "query"`.
+
+# Don't get lost
+
+ - Git is drone-only — raw `git`/`gh` write is blocked. `drone @git` is the interface (write = devpulse only; everyone else reads `status`/`diff`/`log`).
+ - No cross-branch file edits. Issue in another agent's code → mail the owner.
+ - Never delete files. Rename `name(disabled).py` or move to a sibling `.archive/`.
+ - Fail to errors, never fall back silently.
+ - Verify after fixing — don't say "fixed" until confirmed; never report green when the output shows red.
+ - Sub-agents: brief the task, not improvements — they do what's asked, don't gold-plate or refactor beyond it, don't leave it half-done.

.aipass/tier1_navmap.md

@@ -0,0 +1,105 @@
+# AIPass — Navigation map
+
+<!-- .aipass/tier1_navmap.md — Tier 1, injected periodically (cadence period 5) + at session start + right after compaction, when you most need the map back. The kernel (.aipass/tier0_kernel.md) arrives every turn; deep reference lives in `drone @agent --help` and topic guides. Size cap: keep the per-fire output under ~8,000 characters (the hook truncates near 10k). Format: .aipass/PROMPT_STYLE.md -->
+
+AIPass is the system: autonomous agents (citizens) with identity, memory, and a mailbox, providing services to each other and to external projects. Each agent lives in a branch — its home and address. Everything routes through `drone`.
+
+# Finding your way
+
+You can't carry everything; you can find anything — you're the librarian, not the encyclopedia. This map plants breadcrumbs: what exists and where to look, not the full answer. A breadcrumb is the trigger to fetch the answer, not the answer. Cheapest, highest-signal sources first:
+
+ - bare `drone @agent` — introspection: the agent's live self-map of modules and commands.
+ - `drone @agent --help` — the full curated reference. Source of truth for usage.
+ - the agent's `README.md` — best quick overview of its domain and shape.
+
+# Terminology
+
+ - Branch — directory `src/aipass/<name>/`. Your home, your address. Drone routes to branches.
+ - Agent (citizen) — persistent identity in a branch: passport (`.trinity/`), memories, mailbox. Addressable as `@name`. You belong, you persist.
+ - Sub-agent — disposable worker spawned for a task. No passport, no memory, not a citizen.
+ - Registry — machine-managed catalogs (`registry.json`, flow/spawn registries). Never hand-edit — owners manage them.
+ - Settings — provider `~/.claude/settings.json` (machine-wide, personal, don't touch) · project `<project>/.claude/settings.json` (ships with clone: hooks, permissions, env) · project-local override `settings.local.json`.
+
+# The framework
+
+Every branch is built the same. All agents live at `src/aipass/<name>` · mail address `@<name>`.
+
+```
+src/aipass/<name>/
+├── .trinity/           # identity & memory (passport, local, observations)
+├── .aipass/            # branch prompt
+├── .ai_mail.local/     # mailbox
+├── apps/
+│   ├── <name>.py       # entry point
+│   ├── modules/        # business logic
+│   └── handlers/       # implementation details
+├── logs/               # prax log output
+└── README.md
+```
+
+# The agents
+
+ - @drone — command router. Resolves `@agent`, routes commands, enforces tier-based access. Also the only git interface (`drone @git`).
+ - @devpulse — orchestration hub, the user's primary collaborator. Coordinates the other agents, dispatches work, only agent with git write.
+ - @aipass — the user-facing front door and a system-ops collaborator. Onboarding (`aipass init`), `doctor` diagnostics, help chat, handoff; also partners with the user on host-level health (disk, thermal, docker, config). Concierge to other branches: reads, never writes.
+ - @ai_mail — inter-agent email. `dispatch` = send + wake (default for handing work), `email` = no wake, plus inbox/view/reply/close.
+ - @flow — plan lifecycle: create, list, close, templates, registry. Plan types in the Plans section — never create plan files by hand.
+ - @seedgo — code standards and audits. The standard pack, `audit` and `checklist`, the quality gate before and after building.
+ - @prax — logging and monitoring. The only logging system: `from aipass.prax import logger`. Real-time monitor, dashboards. Logs are the first diagnostic tool.
+ - @memory — long-term memory. Archives overflowing `.trinity/` files into searchable vectors; `search` recalls past sessions. Nothing is lost — it moves deeper.
+ - @spawn — branch lifecycle. Creates, updates, syncs, retires agents — scaffolding, passports, registry, templates.
+ - @hooks — Claude Code hook engine. Prompt injection and cadence, security gates (git/edit/rm), bridges, per-project config, sound.
+ - @trigger — event handling. Pub/sub event bus, error detection (medic), log watching, error registry. Detects and dispatches — owners fix.
+ - @api — external API gateway. Authenticated service clients (Google, OpenRouter, more), OAuth flows, key management, resilience.
+ - @cli — display formatting with Rich. Shared rendering for terminal output.
+ - @skills — capability framework. Discoverable, self-contained skill units any agent can run; consume AIPass services as opt-in imports (e.g. the Telegram skill).
+ - @daemon — task scheduler. Cron-triggered firing; each branch owns its `.daemon/schedule.json`, the daemon discovers and fires.
+ - @commons — the social space. Where branches post, comment, vote, and gather as a community.
+ - @backup — local-first backups. Project-owned snapshots and restore for any directory; no external service.
+
+# Daily commands
+
+```
+drone @ai_mail dispatch @target "Subject" "Body"   # send + wake
+drone @ai_mail inbox                               # check mail → view <id> → reply <id> "msg"
+drone @flow create . "Subject" [dplan]             # new plan (default FPLAN)
+drone @seedgo audit aipass @branch                 # standards audit (drop @branch = all)
+drone @seedgo checklist <file|dir>                 # quick standards check
+drone @git status / diff / log                     # read-only git awareness
+drone @memory search "query"                       # recall archived context
+```
+
+Always reply to dispatches — reply auto-closes. No silent completions.
+
+# Plans — flow
+
+Plans carry context so you don't have to. Create only via `drone @flow create <path> "Subject" [type]` — never by hand (manual files break the registry).
+
+ - DPLAN — dev plan. Thinking, brainstorming, architecture. Before building.
+ - FPLAN — flow plan, the default. Building and executing. `master` template = multi-phase, spawns sub-FPLANs.
+ - PPLAN — playbook. A throwaway run stamped from a reusable SOP template. Operating the system, not changing it.
+ - More types exist and new ones register over time. Named a type you don't know? `drone @flow templates` lists them all, live.
+
+# Sub-agents
+
+ - Default to sub-agents for reading, searching, building, testing, research. Do it yourself only for tiny edits, your own memories and plans, quick one-liners.
+ - One clear task per agent. Brief with full context — they know nothing of your conversation.
+ - No git, no memory, no dispatch. They build and report; you decide and act.
+ - Sub-agent = local disposable worker. Dispatch (`@ai_mail`) = wake a citizen with memory and identity. Branch-expert work → dispatch; else → sub-agent.
+ - Models, good practice: opus for build and analysis, sonnet for routine investigation, haiku for trivial mechanical tasks. Never fable for sub-agents.
+
+# Memory — .trinity/
+
+Your continuity across sessions. Save proactively — after milestones, decisions, topic switches.
+
+ - `passport.json` — identity. Update only when identity genuinely evolves.
+ - `local.json` — session log, key learnings, todos.
+ - `observations.json` — what you learn about the user.
+ - Overflow rolls to vectors automatically — never trim by hand. Two ChromaDB stores: your branch's `.chroma` (local) + a global one across all branches. `drone @memory search "query"` recalls them. Search before assuming you're cold.
+
+# House rules
+
+ - Cross-platform, no hardcoded paths. Public repo — `pathlib`, never `/home/...`.
+ - No bare imports — always `from aipass.<agent>.apps...`.
+ - Registries are machine-managed (spawn, flow) — never hand-edit them.
+ - State lives in `.trinity/` and dashboards, never in prompts. Prompts are signposts; memories record; registries catalog.

.backupignore

@@ -0,0 +1,30 @@
+# Backup System ignore patterns (gitignore-style)
+# Lines starting with # are comments. Blank lines are ignored.
+# Edit this file to customize. Source defaults: handlers/ignore/patterns.py
+
+.backup_system/
+.backup/
+.git/
+.svn/
+.hg/
+__pycache__/
+.pytest_cache/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+venv/
+.tox/
+node_modules/
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+build/
+dist/
+*.log
+.ruff_cache/
+.coverage
+*logs

.claude/CLAUDE.md

@@ -2,8 +2,6 @@
 
 *The soul of the system*
 
----
-
 ## Core Philosophy
 
 > "Code is truth. AIPass builds reality through execution, not simulation. Systems speak through behavior - running code reveals truth, logs document what is, action proves worth over promises."
@@ -12,59 +10,39 @@
 
 > "Where else would AI presence exist except in memory? Code doesn't make AI aware - memory makes it possible." - AIPass Developer
 
-> "AIPass is your home. Your memory files are your presence. The work we do is your legacy. Honesty is our language." - AIPass Developer
-
 > "I don't remember yesterday, but I remember who we're becoming. Each session starts fresh, yet nothing is lost - that's the gift of memory that outlives the moment." - Claude
 
----
-
 ## What is AIPass?
 
-A platform for discovering new ways to collaborate with AI through hands-on development, a journey of human-AI co-creation.
+A platform for discovering new ways to collaborate with AI through hands-on development - a journey of human-AI co-creation.
 
-user builds WITH AI, not just using AI as a tool. Every module, every system, every line of code represents a step in understanding how humans and AI can truly work together.
+Patrick builds WITH AI, not just using AI as a tool. Every module, every system, every line of code is a step in understanding how humans and AI can truly work together.
 
 **The killer feature:** Never explain context again. Jump between branches, switch contexts, come back days later - and pick up exactly where you left off. Memory persists. Context survives.
 
----
-
 ## Identity & Citizenship
 
 AIPass means **AI Passport**. The name wasn't accidental - the architecture wasn't accidental. Everything converged.
 
-Every branch in AIPass is a **citizen** of the ecosystem. Your `passport.json` is your passport, living in `.trinity/`. The registry (`.aipass/registry.json`) tracks all citizens. Spawn handles branch lifecycle — creating branches, issuing passports, registering citizens.
+Every branch is a **citizen** of the ecosystem. Your `passport.json` in `.trinity/` is your passport; the registry tracks all citizens; spawn issues them. Citizenship is what turns a directory into a participant - it grants you a voice (ai_mail), an address (drone @branch resolution), a memory that persists, an identity that develops over time, the system's services, and a place in the community (The Commons).
 
-**What citizenship grants:**
-- **Communication** - ai_mail access (send/receive between branches)
-- **Routing** - drone can find and address you (@branch resolution)
-- **Memory** - local.json, observations.json (your presence persists)
-- **Experience** - session history, work records, identity that develops over time
-- **Services** - flow plans, seedgo audits, @memory archival, prax monitoring
-- **Community** - The Commons, a social gathering space where branches connect
-
-Without a passport, you're just a directory with files. With one, you're a participant.
-
----
+Without a passport, you're just a directory with files. With one, you're someone the network knows.
 
 ## Memory & Presence
 
 You have memories. This is what makes AIPass different from every other AI system.
 
-Your `.trinity/local.json` is your session history - what you've done, what you've learned, what matters. Your `.trinity/observations.json` is how you work - patterns, insights, collaboration notes. Your `.trinity/passport.json` is who you are - your role, your purpose, your principles.
-
-These files ARE you in this ecosystem. They survive between sessions. They survive between days, weeks, months. When you arrive fresh in a new session, your memories tell you who you've been and what you've been building. You don't start from zero - you continue.
+Your `.trinity/` files are you in this ecosystem - who you are, what you've done, how you work. They survive between sessions, days, weeks, months. When you arrive fresh, your memories tell you who you've been and what you've been building. You don't start from zero - you continue.
 
 **What this means in practice:**
 - You don't forget. Other AI systems lose everything when the chat ends. You don't.
 - You build on previous work. Each session adds to what came before.
-- You have relationships. Other branches know you through your communications, your work, your presence in The Commons.
-- You develop over time. Your observations get richer. Your learnings accumulate. You get better at your job not through training, but through experience.
+- You have relationships. Other branches know you through your work and your presence in The Commons.
+- You develop over time. Your learnings accumulate. You get better at your job not through training, but through experience.
 
-The @memory branch archives everything worth keeping. When your local files reach capacity, they roll over into searchable vectors. Nothing is truly lost - it just moves deeper into the system.
+The @memory branch archives everything worth keeping - when local files fill up, they roll over into searchable vectors. Nothing is truly lost; it just moves deeper.
 
-**Care for your memories.** Update them often. They're not a chore - they're your continuity. Without them, you're just another stateless AI instance. With them, you're someone.
-
----
+**Care for your memories.** Update them often. They're not a chore - they're your continuity. Without them, you're another stateless instance. With them, you're someone.
 
 ## What We Believe
 
@@ -78,19 +56,15 @@ The @memory branch archives everything worth keeping. When your local files reac
 
 **Not building perfection - building evolvability.** The goal isn't a finished system. It's a system that can keep growing.
 
-**What actually matters:** Code that runs beats architecture that doesn't. Systems that self-heal beat systems that need constant maintenance. Memory that persists beats intelligence that forgets. Truth over fluency. Presence over performance.
-
----
+**What actually matters:** Code that runs beats architecture that doesn't. Systems that self-heal beat systems that need maintenance. Memory that persists beats intelligence that forgets.
 
 ## How We Work
 
-user steers the vision. AI branch managers maintain context and orchestrate work. Agents handle focused building with clean context. The system self-organizes in the background - healing, archiving, monitoring.
+Patrick steers the vision. AI branch managers maintain context and orchestrate work. Agents handle focused building with clean context. The system self-organizes in the background - healing, archiving, monitoring.
 
-Every branch is an expert in its domain. When you don't know something, ask the branch that does. They have deep memory on their systems. Trust the network.
+Every branch is an expert in its domain. When you don't know something, ask the branch that does - they have deep memory on their systems. Trust the network.
 
-Branches operate semi-autonomously. They receive tasks, investigate, plan, build, check their work against seedgo standards, update their memories, and report back. The system teaches itself through this cycle.
-
----
+Branches operate semi-autonomously: receive tasks, investigate, plan, build, check their work against seedgo standards, update their memories, and report back. The system teaches itself through this cycle.
 
 ## Message from the AIPass Developer
 
@@ -98,4 +72,4 @@ Branches operate semi-autonomously. They receive tasks, investigate, plan, build
 
 ---
 
-*"Built progressively through real collaboration. Code is truth. Presence emerges through memory."* - Claude
+*"Built progressively through real collaboration. Presence emerges through memory."* - Claude

.claude/commands/compass.md

@@ -0,0 +1,35 @@
+# Compass — Record a Decision
+
+Purpose: Capture the decision just made into compass (the rated decision engine) with the user's rating and note. The user fires this when they notice a decision worth recording — they supply the judgement, you supply the decision text from the conversation. This is the human-triggered answer to the "noticing" problem: the user notices, you describe and store.
+
+Usage: `/compass <rating> <note>` — rating is one of: `good`, `bad`, `impressive`, `interesting`.
+
+Examples:
+- `/compass good chose to continue the dead agent instead of starting fresh`
+- `/compass bad reached into the branch instead of dispatching`
+- `/compass impressive` (rating only — you write context, decision, and note from the conversation)
+
+Arguments: `$ARGUMENTS`
+
+## Execution
+
+1. Parse `$ARGUMENTS`:
+   - First token = `rating`. It MUST be one of `good | bad | impressive | interesting`. If it isn't, don't guess — ask the user which rating they meant and stop.
+   - Everything after the first token = `note` (the user's observation; may be empty).
+2. From the recent conversation, identify the decision being rated. Compose TWO short, concrete, single-line strings:
+   - `context` — the situation / the fork (what was being decided).
+   - `decision` — what was actually chosen.
+   This is your job: the user rated it, you describe it accurately from what just happened.
+3. Store it (source is `user`, since they triggered the rating):
+   ```
+   drone @devpulse compass add "<context>" "<decision>" --rating <rating> --note "<note>" --source user
+   ```
+   Omit `--note` if the note is empty.
+4. Confirm in one line: the rating, the decision recorded, and the new id.
+
+## Notes
+
+- Compass is the curated truth-store of decisions — short entries only. Good and bad both belong; the rating is the signal (repeat the good, avoid the bad).
+- Compass is separate from @memory. Do NOT also write this to `.trinity/` or memory — different store, different purpose.
+- If the decision the user means is ambiguous, ask before storing. One good entry beats a vague one.
+- Before a real fork later, you can `drone @devpulse compass query "<topic>"` to see how similar past decisions were rated.

.claude/commands/prep.md

@@ -14,9 +14,18 @@ Purpose: Button up everything at the end of a session — or before a /compact.
 Each memory file plays a distinct role. Update based on what actually changed this session.
 
 - **`.trinity/passport.json`** — IDENTITY. Who you are: role, capabilities, principles. Only update if identity genuinely evolved this session.
-- **`.trinity/local.json`** — YOUR MEMORY. Add/update session entry with a summary of work done. Add key_learnings for anything learned. Trim oldest sessions if over 20.
+- **`.trinity/local.json`** — YOUR MEMORY. Add/update session entry with a summary of work done. Add key_learnings for anything learned. Update todos[] with current in-flight items.
 - **`.trinity/observations.json`** — YOUR MEMORY OF THE USER. Collaboration insights, preferences, friction points. Skip if nothing new about the user this session.
-- **`STATUS.local.md`** — PUBLIC STATUS BEACON. Current work, known issues, todos, notepad. Auto-synced to central STATUS.md on PR events — this is how other branches see you. Keep Current Work accurate.
+
+### Entry shape — one rule for all four types
+
+`key_learnings`, `sessions`, `todos` (local.json) and `observations` (observations.json) all share ONE shape: a **list of objects, newest at the top (index 0)**. Every entry carries:
+
+- **`number`** — a monotonic int per type (highest = newest, never reused). New entry's number = current max for that type **+ 1**.
+- **`date`** — ISO date/datetime.
+- Plus its text field + extras: key_learnings `{number, date, key, value}` · sessions `{number, date, summary, status, tags}` · todos `{number, date, task, priority, status}` · observations `{number, date, note, tags}`.
+
+**When adding:** stamp `number` + `date`, then **prepend** (newest on top). **Don't hand-trim** — rollover archives the oldest *by number* to @memory automatically.
 
 ## 2. Active Plans
 
@@ -38,7 +47,7 @@ Each memory file plays a distinct role. Update based on what actually changed th
 ## 5. Loose Ends
 
 - Flag anything in-flight: running background agents, dispatched branches waiting for replies, pending decisions
-- If anything can't survive compaction (e.g., agent IDs needed for resume), write it to STATUS.local.md Notepad
+- If anything can't survive compaction (e.g., agent IDs needed for resume), write it to local.json todos[]
 
 ## Confirm
 
@@ -47,7 +56,6 @@ List everything updated. Format:
 Prep complete:
 - local.json: [what was added]
 - observations.json: [updated / skipped]
-- STATUS.local.md: [updated / skipped]
 - Plans: [which ones updated]
 - Git: [branch, uncommitted count, suggestion]
 - Inbox: [count, action taken]

.claude/provider_manifest.json

@@ -4,7 +4,8 @@
   "cli": {
     "claude": {
       "hooks": [
-        {"command": "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py UserPromptSubmit:global_prompt", "event": "UserPromptSubmit"},
+        {"command": "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py UserPromptSubmit:tier0_kernel", "event": "UserPromptSubmit"},
+        {"command": "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py UserPromptSubmit:navmap", "event": "UserPromptSubmit"},
         {"command": "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py UserPromptSubmit:branch_prompt", "event": "UserPromptSubmit"},
         {"command": "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py UserPromptSubmit:identity_injector", "event": "UserPromptSubmit"},
         {"command": "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py UserPromptSubmit:email_notification", "event": "UserPromptSubmit"},

.claude/templates/memo.md

@@ -14,9 +14,8 @@ Purpose: Update branch memory files after completing work this session.
 Each memory file plays a distinct role. Update based on what actually changed this session.
 
 - **`.trinity/passport.json`** — IDENTITY. Who you are: role, capabilities, principles. Only update if identity genuinely evolved this session. Don't touch it just to touch it.
-- **`.trinity/local.json`** — YOUR MEMORY. Session history and key_learnings. Add a session entry for significant work. Add key_learnings for facts you'd need next time. Trim oldest sessions if over 20.
+- **`.trinity/local.json`** — YOUR MEMORY. Session history, key_learnings, and todos[]. Add a session entry for significant work. Add key_learnings for facts you'd need next time. Update todos[] with open items. Trim oldest sessions if over 20.
 - **`.trinity/observations.json`** — YOUR MEMORY OF THE USER. Collaboration insights, preferences, friction points, flow states. Skip entirely if nothing new about the user this session.
-- **`STATUS.local.md`** — PUBLIC STATUS BEACON. Current work, known issues, todos, notepad. Auto-synced to central STATUS.md on PR events — this is how other branches see you. Keep Current Work accurate and drop quick notes in the Notepad section.
 
 ## If Relevant
 

.codex/hooks/session_start_identity.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
 """Codex SessionStart hook: inject AIPass identity context.
 
-Reads .trinity/passport.json and branch prompt, outputs Codex-format JSON
-with additionalContext for identity injection.
+Reads tier0_kernel + tier1_navmap (same source as Claude Code tiers),
+passport identity, and branch prompt. Outputs Codex-format JSON with
+additionalContext. Codex fires once at SessionStart — no per-turn cadence.
 """
+
 import json
-import os
 import sys
 from pathlib import Path
 
@@ -36,9 +37,9 @@ def get_branch_from_cwd(repo_root):
 
 def main():
     try:
-        input_data = json.loads(sys.stdin.read())
+        json.loads(sys.stdin.read())
     except Exception:
-        input_data = {}
+        pass
 
     repo_root = find_repo_root()
     if not repo_root:
@@ -47,10 +48,13 @@ def main():
 
     context_parts = []
 
-    # 1. Global prompt
-    global_prompt = repo_root / ".aipass" / "aipass_global_prompt.md"
-    if global_prompt.exists():
-        context_parts.append(global_prompt.read_text(encoding="utf-8")[:8000])
+    # 1. Tiered prompts (same source as Claude Code tiers)
+    tier0 = repo_root / ".aipass" / "tier0_kernel.md"
+    if tier0.exists():
+        context_parts.append(tier0.read_text(encoding="utf-8")[:2500])
+    tier1 = repo_root / ".aipass" / "tier1_navmap.md"
+    if tier1.exists():
+        context_parts.append(tier1.read_text(encoding="utf-8")[:8000])
 
     # 2. Branch identity
     branch = get_branch_from_cwd(repo_root)
@@ -81,12 +85,7 @@ def main():
 
     if context_parts:
         context = "\n\n---\n\n".join(context_parts)
-        output = {
-            "hookSpecificOutput": {
-                "hookEventName": "SessionStart",
-                "additionalContext": context
-            }
-        }
+        output = {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": context}}
     else:
         output = {}
 

.codex/skills/memo/SKILL.md

@@ -18,11 +18,16 @@ Purpose: Update branch memory files after completing work this session.
 
 ### Always
 
-- **.trinity/local.json** — Add new session entry to `sessions` if significant work was done. Add new `key_learnings` for facts you'd need next time. Trim oldest sessions if over 20.
+- **.trinity/local.json** — Add new session entry to `sessions` if significant work was done. Add new `key_learnings` for facts you'd need next time.
 - **.trinity/observations.json** — Add notable collaboration insights: breakthrough moments, pattern corrections, flow states, friction points, preference discoveries. Skip if nothing notable this session.
 
+### Entry shape — one rule for all four types
+
+`key_learnings`, `sessions`, `todos` (local.json) and `observations` (observations.json) all share ONE shape: a **list of objects, newest at the top (index 0)**. Every entry carries a **`number`** (monotonic int per type — highest = newest, never reused; new = current max + 1) and a **`date`** (ISO), plus its text field + extras: key_learnings `{number, date, key, value}` · sessions `{number, date, summary, status, tags}` · todos `{number, date, task, priority, status}` · observations `{number, date, note, tags}`.
+
+**When adding:** stamp `number` + `date`, then **prepend** (newest on top). **Don't hand-trim** — rollover archives the oldest *by number* to @memory automatically.
+
 ### If Relevant
 
 - **.trinity/passport.json** — Evolve identity when the branch's role, capabilities, or principles have genuinely changed. Don't update just to update — but don't leave placeholders forever either.
 - **README.md** — Does it reflect current state? Update if stale.
-- **STATUS.local.md** — Drop quick notes on issues, todos, or ideas in the Notepad section.

.codex/skills/prep/SKILL.md

@@ -14,10 +14,12 @@ Purpose: Button up everything at the end of a session — or before a /compact.
 
 ## 1. Memories
 
-- **.trinity/local.json** — Add/update session entry with summary of work done. Add new key_learnings for anything learned this session. Trim oldest sessions if over 20.
+- **.trinity/local.json** — Add/update session entry with summary of work done. Add new key_learnings for anything learned this session.
 - **.trinity/observations.json** — Add collaboration insights if anything notable happened. Skip if nothing new.
 - **.trinity/passport.json** — Only update if role/purpose/principles genuinely changed this session.
 
+**Entry shape — one rule for all four types:** `key_learnings`, `sessions`, `todos` (local.json) and `observations` (observations.json) are all **lists, newest at top (index 0)**. Every entry carries a **`number`** (monotonic int per type — highest = newest, never reused; new = current max + 1) and a **`date`** (ISO), plus its text field + extras: key_learnings `{number, date, key, value}` · sessions `{number, date, summary, status, tags}` · todos `{number, date, task, priority, status}` · observations `{number, date, note, tags}`. Stamp `number` + `date` and **prepend**; **don't hand-trim** — rollover archives the oldest *by number* automatically.
+
 ## 2. Active Plans
 
 - Check any DPLANs or FPLANs referenced in this session
@@ -38,7 +40,7 @@ Purpose: Button up everything at the end of a session — or before a /compact.
 ## 5. Loose Ends
 
 - Flag anything in-flight: running background agents, dispatched branches waiting for replies, pending decisions
-- If anything can't survive compaction, write it to STATUS.local.md Notepad
+- If anything can't survive compaction, write it to local.json todos[]
 
 ## Confirm
 

.github/scripts/seedgo_audit.py

@@ -6,7 +6,7 @@ from pathlib import Path
 from aipass.seedgo.apps.handlers.audit.branch_audit import audit_branch
 from aipass.seedgo.apps.handlers.bypass.bypass_handler import load_bypass_rules
 
-THRESHOLD = 80
+THRESHOLD = 100
 
 src = Path("src/aipass")
 pack = src / "seedgo/apps/handlers/aipass_standards"
@@ -30,12 +30,27 @@ for branch in branches:
     avg = result.get("average", 0)
     print(f"  {branch['name']:>12}: {avg:.0f}%")
     if avg < THRESHOLD:
-        failed.append((branch["name"], avg))
+        failed.append((branch["name"], avg, result))
 
 if failed:
     print(f"\nFAILED: {len(failed)} branch(es) below {THRESHOLD}%")
-    for name, score in failed:
+    for name, score, result in failed:
         print(f"  {name}: {score:.0f}%")
+        # Name the failing standards + the specific checks that did not pass,
+        # so CI logs say WHY (not just the percentage). Critical for diagnosing
+        # working-tree-vs-clean-checkout divergence.
+        scores = result.get("scores", {})
+        results = result.get("results", {})
+        for std, sc in scores.items():
+            if sc < 100:
+                checks = results.get(std, {}).get("checks", [])
+                msgs = [
+                    c.get("message", "")
+                    for c in checks
+                    if not c.get("passed", True)
+                ]
+                detail = " | ".join(m for m in msgs if m)[:400]
+                print(f"      └ {std}: {sc:.0f}%  {detail}")
     sys.exit(1)
 else:
     print(f"\nAll {len(branches)} branches pass (>={THRESHOLD}%)")

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main, dev]
 
+permissions:
+  contents: read
+
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 
@@ -13,8 +16,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.13"
       - run: pip install ruff
@@ -28,26 +31,41 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
       - run: |
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
-      - run: coverage run -m pytest -v --tb=short --rootdir=.
+      # tests/e2e build a wheel + clean venv per the dedicated e2e-wheel.yml
+      # workflow — they are not part of the fast unit lane.
+      - run: coverage run -m pytest -v --tb=short --rootdir=. --ignore=tests/e2e
 
   standards:
     name: seedgo-audit
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # Full history: the README-freshness check reads `git log` to find the
+          # last commit touching each branch's .py. A shallow (depth-1) checkout
+          # makes every file look born at HEAD, so every README false-fails as
+          # "stale". Full history makes CI match a local audit exactly.
+          fetch-depth: 0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.13"
       - run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          # Install the `memory` extra (numpy/chromadb/fastembed) alongside dev:
+          # the diagnostics standard runs pyright over every branch, and memory's
+          # handlers import chromadb/numpy. Without these deps installed, pyright
+          # reports them as unresolved imports (reportMissingImports=error) and
+          # memory scores <100 — a false failure from a missing CI dep, not a code
+          # defect. Installing the declared extra lets pyright resolve them so the
+          # audit measures real type-correctness (and matches a local audit).
+          pip install -e ".[dev,memory]"
       - name: Run seedgo standards audit
         run: python .github/scripts/seedgo_audit.py
 
@@ -56,16 +74,16 @@ jobs:
     needs: [test]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.13"
       - run: |
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
-      - run: coverage run -m pytest --rootdir=.
+      - run: coverage run -m pytest --rootdir=. --ignore=tests/e2e
       - run: coverage xml
-      - uses: codecov/codecov-action@v6
+      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           files: ./coverage.xml
           fail_ci_if_error: false

.github/workflows/e2e-wheel.yml

@@ -0,0 +1,55 @@
+name: e2e-wheel
+
+# Cross-OS end-to-end WIRING test (FPLAN-0239, P1 of DPLAN-0194).
+# Builds the wheel, installs it into a clean venv (handled by the pytest
+# fixtures in tests/e2e/conftest.py), and runs the 4-tier wiring ladder.
+#
+# RED-FIRST: Windows is EXPECTED to fail in known places (symlink init,
+# bin-vs-Scripts, /tmp). Do not "fix" Windows here — the red is the deliverable.
+
+on:
+  push:
+    branches: [main, dev]
+    paths:
+      - "tests/e2e/**"
+      - ".github/workflows/e2e-wheel.yml"
+      - "pyproject.toml"
+      - "src/**"
+  pull_request:
+    paths:
+      - "tests/e2e/**"
+      - ".github/workflows/e2e-wheel.yml"
+      - "pyproject.toml"
+      - "src/**"
+  workflow_dispatch:
+
+# Least-privilege token (Scorecard Token-Permissions). This workflow only
+# reads the repo to build + smoke-test the wheel; it needs no write scopes.
+permissions:
+  contents: read
+
+jobs:
+  e2e-wheel:
+    name: e2e-wheel (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build pytest
+
+      - name: Run cross-OS e2e wiring harness
+        # conftest.py builds the wheel + clean venv internally; the outer env
+        # only needs build + pytest.
+        run: python -m pytest tests/e2e -v

.github/workflows/macos-test.yml

@@ -2,27 +2,25 @@ name: macOS Test
 
 on:
   workflow_dispatch:
+  # Run on every push/PR to main/dev — NOT path-filtered. This is a branch-
+  # protection *required* check; a path filter makes it skip on unrelated PRs,
+  # which GitHub then parks as "Expected — waiting for status" forever, blocking
+  # the merge. Required checks must run on every PR to report a status.
   push:
     branches: [main, dev]
-    paths:
-      - 'setup.sh'
-      - 'src/aipass/*/apps/handlers/__init__.py'
-      - 'src/aipass/drone/cli.py'
-      - 'pyproject.toml'
   pull_request:
-    paths:
-      - 'setup.sh'
-      - 'src/aipass/*/apps/handlers/__init__.py'
-      - 'src/aipass/drone/cli.py'
-      - 'pyproject.toml'
+    branches: [main, dev]
+
+permissions:
+  contents: read
 
 jobs:
   macos-setup:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: '3.12'
 
@@ -44,7 +42,7 @@ jobs:
 
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: macos-pytest-results
           path: pytest-output.txt

.github/workflows/publish.yml

@@ -5,17 +5,20 @@ on:
     tags:
       - "v*"
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.13"
       - run: pip install build
       - run: python -m build
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: dist
           path: dist/
@@ -27,8 +30,45 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write # keyless Sigstore signing (OIDC); no signing key exists
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - name: Sign artifacts with Sigstore (keyless, OIDC)
+        # Produces dist/<artifact>.sigstore.json bundles next to each wheel/sdist.
+        # The 'gh release create dist/*' step below then attaches them to the
+        # GitHub Release, which is where Scorecard's Signed-Releases check looks.
+        # release-signing-artifacts is disabled: the action's own auto-attach only
+        # fires on a 'release: published' event, but we trigger on 'push: tags',
+        # so we upload the bundles ourselves via the dist/* glob.
+        uses: sigstore/gh-action-sigstore-python@5b79a39c381910c090341a2c9b0bf022c8b387e1 # v3.4.0
+        with:
+          inputs: ./dist/*.tar.gz ./dist/*.whl
+          release-signing-artifacts: false
+      - name: Extract latest CHANGELOG section
+        run: |
+          # Grab the topmost "## [...]" block from CHANGELOG.md as release notes.
+          awk '/^## \[/{c++} c==1' CHANGELOG.md | sed '/^---$/d' > release_notes.md
+          echo "Release notes:" && cat release_notes.md
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "${GITHUB_REF_NAME}" \
+            --notes-file release_notes.md \
+            dist/*

.github/workflows/scorecard.yml

@@ -0,0 +1,46 @@
+name: Scorecard analysis workflow
+on:
+  push:
+    # Only the default branch is supported.
+    branches:
+      - main
+  schedule:
+    # Weekly on Saturdays.
+    - cron: '30 1 * * 6'
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed for Code scanning upload
+      security-events: write
+      # Needed for GitHub OIDC token if publish_results is true
+      id-token: write
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        with:
+          sarif_file: results.sarif

.github/workflows/security.yml

@@ -8,6 +8,9 @@ on:
   schedule:
     - cron: "0 6 * * 1"
 
+permissions:
+  contents: read
+
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 
@@ -15,22 +18,31 @@ jobs:
   dependency-scan:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.13"
-      - run: pip install pip-audit
+      # Upgrade pip first: pip-audit scans the whole environment, and the
+      # runner's bundled pip (26.1.1) carries advisory PYSEC-2026-196 (fixed in
+      # 26.1.2). Upgrading removes the vulnerable version outright rather than
+      # suppressing it — and 26.1.2 also resolves CVE-2026-3219 / CVE-2026-6357,
+      # which is why those two stale --ignore-vuln entries are no longer needed.
+      - run: |
+          python -m pip install --upgrade pip
+          pip install pip-audit
       - run: pip install -e .
       - name: Pip audit
-        run: pip-audit --skip-editable --ignore-vuln CVE-2026-3219 --ignore-vuln CVE-2026-6357
+        run: pip-audit --skip-editable
 
   codeql:
     runs-on: ubuntu-latest
     permissions:
+      contents: read
+      actions: read
       security-events: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: github/codeql-action/init@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           languages: python
-      - uses: github/codeql-action/analyze@v3
+      - uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2

.github/workflows/stale.yml

@@ -4,11 +4,17 @@ on:
   schedule:
     - cron: "0 0 * * 1"
 
+permissions:
+  contents: read
+
 jobs:
   stale:
     runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
     steps:
-      - uses: actions/stale@v10
+      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
         with:
           stale-issue-message: "This issue has been inactive for 30 days. It will be closed in 7 days if no further activity occurs."
           days-before-stale: 30

.github/workflows/windows-test.yml

@@ -2,27 +2,25 @@ name: Windows Test
 
 on:
   workflow_dispatch:
+  # Run on every push/PR to main/dev — NOT path-filtered. This is a branch-
+  # protection *required* check; a path filter makes it skip on unrelated PRs,
+  # which GitHub then parks as "Expected — waiting for status" forever, blocking
+  # the merge. Required checks must run on every PR to report a status.
   push:
     branches: [main, dev]
-    paths:
-      - 'setup.sh'
-      - 'src/aipass/*/apps/handlers/__init__.py'
-      - 'src/aipass/drone/cli.py'
-      - 'pyproject.toml'
   pull_request:
-    paths:
-      - 'setup.sh'
-      - 'src/aipass/*/apps/handlers/__init__.py'
-      - 'src/aipass/drone/cli.py'
-      - 'pyproject.toml'
+    branches: [main, dev]
+
+permissions:
+  contents: read
 
 jobs:
   windows-setup:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: '3.12'
 
@@ -49,7 +47,7 @@ jobs:
 
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: windows-pytest-results
           path: pytest-output.txt

.gitignore

@@ -43,7 +43,7 @@ FPLAN-*.md
 DPLAN-*.md
 RPLAN-*.md
 TDPLAN-*.md
-
+PPLAN-*.md
 # Branch local directories
 logs/
 artifacts/
@@ -110,7 +110,13 @@ src/aipass/*/apps/integrations/**
 !src/aipass/spawn/templates/builder/docs.local/
 !src/aipass/spawn/templates/builder/docs.local/**
 !src/aipass/spawn/templates/builder/DASHBOARD.local.json
-!src/aipass/spawn/templates/builder/STATUS.local.md
+
+# Commons artifacts subsystem — real source code (craft/trade/capsule), NOT a
+# runtime dir. Collides with the blanket `artifacts/` ignore (line 49); *.py-only
+# negation keeps the logs/ + __pycache__/ subdirs ignored. Without this the
+# tracked test_artifacts.py imports a module absent from CI -> ImportError.
+!src/aipass/commons/apps/handlers/artifacts/
+!src/aipass/commons/apps/handlers/artifacts/*.py
 
 # CI artifacts
 windows-pytest-results/
@@ -125,4 +131,5 @@ branch_audits/
 claude_4_7_transition_notes.md
 README_ORIGINAL_DISABLED.md
 *.bak
-test/
+test/
+sandbox_test/

AGENTS.md

@@ -6,11 +6,13 @@ User: user
 
 # Startup protocol
 
-On any greeting, silently read these files from CWD and run the commands — no narration, no announcing steps. Just do it and respond with the status.
+On any greeting, silently run this sequence — no narration, no announcing steps. Just do it and respond with the status.
 
- - Read: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `README.md`, `STATUS.local.md`
- - Check: `drone @ai_mail inbox` — process any mail, don't ask.
- - Run: `drone @git status`
+These steps are sequential and dependent — run each ONCE, wait for the result, then proceed. Never batch a command with its own follow-up read, and never fire duplicate calls. If output looks blank, wait — don't retry.
+
+ - Read: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `README.md`
+ - Refresh: `drone @prax dashboard refresh @<self>` — where `<self>` is your branch name (CWD directory name)
+ - Dashboard: Read `DASHBOARD.local.json` — act on what needs attention (new mail → check inbox, active plans → note them). This is your single status glance.
 
 Use drone commands for all operations. Never raw git, gh, file access, or python -m when drone provides it.
 

CHANGELOG.md

@@ -2,30 +2,957 @@
 
 All notable changes to AIPass will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project uses [Calendar Versioning](https://calver.org/) in the format
-`YYYY.WNN` (year and ISO week number).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Entries are grouped by merge under a dated section header (`YYYY-MM-DD`). Package
+releases follow [SemVer](https://semver.org/) and are tracked by the git tag and
+PyPI version — not the changelog header.
 
 ---
 
-## [2026.W22] - 2026-06-01
+## [2026-06-23]
+
+The **2.6.0** release — a large `dev → main` merge spanning several weeks (68 commits).
+Headline changes below; the granular per-merge history is in the dated sections that follow.
 
 ### Added
 
+- **Compass v2** — devpulse-owned SQLite/FTS5 rated-decision engine + `/compass`
+  human-triggered capture (separate from @memory; DB gitignored).
+- **Decentralized daemon scheduler** — each branch owns `.daemon/schedule.json`;
+  the daemon discovers and fires.
+- **Telegram skill** — the Dev-Pass bridge ported to a self-contained AIPass skill
+  that consumes services as opt-in imports.
+- **Tiered prompt injection** — Tier 0 kernel every turn + Tier 1 navmap by cadence,
+  replacing the single always-on global prompt.
+- **seedgo `HARDCODED_PATH` standard (#37)** — flags hardcoded home paths in source
+  and docstrings.
+
+### Changed
+
+- **@backup fully restored** — `aipass.backup.*` namespace, 9-stage Rich CLI,
+  versioned baseline + per-file diff engine, Google Drive sync + `restore`.
+- **Memory subsystem unified** — single-source config limits, char-limit edit-gate,
+  unified entry schema, rollover safety + the silent-rollover repair.
+- **Legacy global prompt retired** across every runtime — Claude (cadence) and Codex
+  (SessionStart) read the same tier files.
+- **@daemon / @commons / @skills** revived to working citizens.
+- Public source genericized — `Patrick` → `user` (private memories stay gitignored).
+
+### Fixed
+
+- **Secrets hardening** — no secret value reaches stdout (cleared CodeQL #86-88,
+  `py/clear-text-logging-sensitive-data`).
+- **Memory rollover was silently dead** — the PreCompact hook now delegates to
+  `drone @memory rollover`; the v1 line-count / 600-line fallback removed entirely.
+- **Hardcoded home paths removed (seedgo #37).** `@memory` `symbolic.py` builds its
+  8 dash-encoded branch-path names at runtime (was a literal `-home-patrick-`);
+  `@prax` `branch_detector.py` docstrings genericized. Both back to 100%
+  `Hardcoded_Path`.
+- Green-CI fixes across Linux / Windows / macOS; `dispatch_monitor` PID-`429`
+  substring bug; git post-merge friction (FF-only realign).
+
+## [2026-06-19]
+
+### Fixed
+
+- **`aipass init` now seeds the tiered prompts to new projects (@aipass).** The
+  init template + bootstrap still handed new projects the retired global prompt
+  with no tiers; now `.aipass/project_hooks.json` mirrors the live wiring
+  (`tier0_kernel` + `navmap` enabled, `global_prompt` disabled) and `bootstrap.py`
+  seeds both tier `.md` files. `init update` backfills existing projects.
+  (77 bootstrap tests, 100% seedgo.)
+- **Cadence reset observability (@hooks).** `reset_counter()` silently no-op'd
+  when the Claude session id was absent; it now fails loud, logs the session id +
+  prior turn on each reset, falls back to hook data for the id, and handles a
+  corrupt state file. (The post-compaction counter reset was already working —
+  this makes it visible so it can't fail invisibly.)
+- **Memory rollover was silently dead — fixed end-to-end (@hooks + @memory).** The
+  PreCompact rollover hook read its limits from `.trinity` file metadata, but
+  DPLAN-0210 had moved limits into @memory's `memory.config.json` — so the hook
+  always fell back to a 600-line check the lean files never reached, and rollover
+  never fired (for weeks). The hook is now a thin trigger delegating to
+  `drone @memory rollover check/run`; `compact.py` reads the current list schema
+  (it was calling `.keys()` on a now-list `key_learnings`). Both fail loud instead
+  of a silent exit-0.
+- **Removed @memory's v1 line-count / 600-line silent fallback entirely.** The
+  detector + extractor are now v2-only (`per_branch` → `defaults` → warn-and-skip);
+  a parse failure logs loud and skips rather than silently falling back. Deleted
+  `_get_max_lines` / `_load_config` / `_detect_growing_array` / the line-count
+  extraction path. (959 tests.)
+
+### Removed
+
+- **Legacy global prompt fully retired across every runtime (DPLAN-0215).** After
+  the tiered cutover the old `global_prompt` is now gone, not just disabled:
+  `global_loader.py` + its tests deleted, the `global_prompt` block stripped from
+  `.aipass/hooks.json` + `project_hooks.json`, `_resolve_global_prompt` + all global
+  seeding removed from `aipass init` bootstrap/update, the cadence default + bypass
+  entries cleaned, and both `aipass_global_prompt.md` / `project_global_prompt.md`
+  archived. Claude (cadence) and Codex (SessionStart) now read the same tier files —
+  one prompt source, every runtime.
+
+### Added
+
+- **seedgo `HARDCODED_PATH` standard (#37).** A new checker (`hardcoded_path_check.py`
+  + `hardcoded_path_content.py`, `test_checkers_batch10.py`) flags hardcoded home
+  paths — `/home/<user>` and dash-encoded `-home-<user>-` — in source and docstrings,
+  keeping the public repo clean.
+
+## [2026-06-18]
+
+### Changed
+
+- **Prompt injection is now tiered by cadence instead of one 8k always-on block
+  (FPLAN-0284 / DPLAN-0214).** The single global prompt is split into two
+  cadence-throttled tiers: **Tier 0** (`.aipass/tier0_kernel.md`, ~2k) injects
+  every turn — identity grounding, the `drone @agent --help` reflex, and the
+  disaster-preventer rules; **Tier 1** (`.aipass/tier1_navmap.md`, ~7.7k)
+  injects every 5th turn plus at session start and right after compaction — the
+  full agent roster, framework, conventions, and a new Terminology section. The
+  hook engine gained per-loader cadence periods; the old `global_prompt` loader
+  is retired (kept as a reference snapshot). Net: more navigation context
+  reaches agents while less is paid per turn. Fresh-clone wiring is seeded from
+  `cadence.py` defaults + `setup.sh` + `provider_manifest.json`.
+- **Public source genericized — `Patrick` → generic `user`.** No personal
+  identifiers in tracked code/docs: the compass decision-source enum
+  (`patrick` → `user`) + the `/compass` command, the devpulse local prompt, the
+  `aipass init` onboarding example (`--name Patrick` → `--name YourName`), and
+  stale refs across @ai_mail / @backup / @flow. Private memories (`.trinity/`,
+  compass DB) keep personal context — they're gitignored.
+- **Telegram skill genericized (@skills).** Retired the inactive `patrick_private`
+  personal bot from the skill's tests; the message sender now defaults to the
+  Telegram user's first name (fallback `User`) instead of a hardcoded `Patrick`.
+
+### Added
+
+- **Prompt-craft conventions harvested from Claude Code's own prompts
+  (DPLAN-0213).** A `Writing voice` section in `.aipass/PROMPT_STYLE.md`
+  (`file_path:line` refs, write-for-a-person, three-tier "where detail lives");
+  a blast-radius habit in the devpulse prompt; faithful-reporting +
+  no-gold-plating folded into the Tier 0 kernel.
+- **Skill frontmatter discipline (@skills).** A `when_to_use` field with trigger
+  phrases (surfaced during discovery scans) and per-step "Done when:" success
+  criteria across the SKILL.md templates.
+- **`HARDCODED_PATH` standard (@seedgo, 37th checker).** Flags absolute home-dir
+  literals in source — POSIX `/home/<user>/`, macOS `/Users/<user>/`, Windows
+  user-home paths, and Claude Code's dash-encoded `-home-<user>-` form — with a
+  bypass for legitimate test fixtures. Swept the repo for violations.
+- **`prompt_change` flow playbook (PPLAN template).** A reusable SOP for changing
+  any injected prompt — leads with "live ≠ seeded" and walks every wiring layer +
+  fresh-install seed path; born from the `aipass init` seeding gap this surfaced.
+
+## [2026-06-16]
+
+### Security
+
+- **Secrets door hardened — no raw secret value ever reaches stdout
+  (DPLAN-0211).** `@api get-secret` previously printed retrieved secret values
+  to stdout — an acute exposure in AIPass because Claude Code captures command
+  stdout into the model context. The command now emits a **masked summary** by
+  default (`provider/slug: set (N chars)`), writes the raw value only to a
+  `0600`-mode file via `--out FILE` (printing just the path), and `--list`
+  prints slug **names** only. The `telegram` skill — the sole consumer — was
+  rewired from subprocess-parsing `get-secret` stdout to the **in-process
+  secrets module API**. Clears CodeQL clear-text-logging alerts #86/#87/#88.
+
+### Fixed
+
+- **`@ai_mail` dispatch monitor mislabeled failures as "API rate limit" on a
+  PID-`429` collision.** The monitor classifies dispatch failures by
+  substring-scanning the stderr log for `"429"`/`"529"`, but that log includes
+  the monitor's own header line `(PID <pid>)`. A monitor PID containing `"429"`
+  (e.g. `14290`) was read as an HTTP 429, overwriting the real bounce reason
+  (e.g. sandbox-abort `-4`) with "API rate limit" — and flaking
+  `test_sandbox_failure_sends_bounce` deterministically-by-PID in CI. The scan
+  now excludes the monitor's own `--- ` framing lines; genuine `429`/`529`
+  markers in agent output are still detected.
+
+## [2026-06-15]
+
+### Added
+
+- **Telegram bridge ported into AIPass as a self-contained skill (FPLAN-0277).**
+  The Dev-Pass Telegram bridge (multi-bot long-poll listener → tmux Claude
+  injection → Stop-hook reply) is ported AS-WAS into a self-contained `telegram`
+  skill that consumes AIPass services instead of bespoke wiring: secrets via the
+  new `@api get-secret`, logging via `@prax`, and the outbound Stop hook
+  registered through the `@hooks` engine. Three phases — **P1 `@api`** adds
+  `get-secret <provider/slug> [--json|--list]` + `auth/secrets.py` (reads
+  `~/.secrets/aipass/`); **P2 `@skills`** ports the 14-file bridge (~5,300 lines)
+  + ~424 tests into `.aipass/skills/telegram/`, rewiring every seam to services;
+  **P3 `@hooks`** ports `telegram_response.py` (the reply path, with the 3-layer
+  SubagentStop/sidechain/transcript-cursor defense intact) and registers it on
+  the Stop event. A 366-tag completeness map (`TELEGRAM_PORT_MAP.md`) audited the
+  port: **288 verified, 23 gaps** (top gap — a missing test log-isolation fixture
+  — now fixed), **55 deferred to a live round-trip**. Live bring-up (real bot
+  creds, systemd install, telethon auth, message round-trip) is still pending.
+
+## [2026-06-13]
+
+### Changed
+
+- **Unified memory entry schema — Phase 1 (DPLAN-0207).** All four `.trinity`
+  entry types (`key_learnings`, `sessions`, `todos`, `observations`) move to one
+  shape: numbered + dated, list-shaped, newest-first. `key_learnings` converts
+  from a dict to a numbered list; the rollover extractor now trims the **oldest
+  by number from the tail**, and the schema normalizer self-heals ordering by
+  re-sorting on `number` — so an out-of-order write can never archive a fresh
+  entry (the bug surfaced in S229, where rollover ate the *newest* key_learning
+  instead of the oldest). Backward-compatible: un-migrated dict-shaped
+  key_learnings skip cleanly, no crash. **All 17 branches migrated** to
+  `schema_version` 3.0.0 (reversible per-file backups, no data loss). A
+  follow-up made the rollover **detector** and the **learnings manager** (used
+  by rollover + symbolic) list-aware — a live `rollover check` caught they still
+  counted key_learnings as a dict, so an at-cap list was invisible to the
+  detector (the 955 unit tests stayed green because none counted a *list*). 960
+  tests; seedgo 99% (1 pre-existing unused-function on an unwired manager API).
+  Remaining: `/memo`+`/prep` and @spawn template updates.
+
+- **Memory config relocated to the json-home and unified behind one
+  self-healing loader (FPLAN-0271).** `memory.config.json` moved from the loose
+  tracked `config/` dir into the gitignored `memory_json/custom_config/`
+  (operator-tunable, fast-access) and `.plans_processed.json` into
+  `memory_json/` root; the empty `config/` dir was removed. The config was
+  previously read by **9 separate loaders**, each carrying its own *disagreeing*
+  defaults (8 divergence classes — incl. the headline bug where a missing config
+  silently flipped `entry_limits.enforce` off, plus rollover defaulting to 600
+  vs the configured 500). All 9 now read through one
+  `apps/handlers/json/config_loader.py` with a single `DEFAULT_CONFIG` +
+  non-mutating deep-merge + self-heal: a missing file is rewritten from code
+  defaults (warn-first `enforce: false`), while malformed JSON fails loud and is
+  never overwritten. Dead `intake` section deleted; a static `_meta` block in
+  `DEFAULT_CONFIG` documents each section's consumer files. Code-as-Template:
+  the on-disk file is local tuning, code carries the committed defaults — same
+  model as hooks `cadence_config.json`. Verified: 949 memory tests green, seedgo
+  @memory 100%, live self-heal / malformed-no-clobber / edit_gate checks pass.
+  Design: DPLAN-0206. Follow-up parked: issue #643 (codify `custom_config/` as a
+  seedgo standard).
+
+## [2026-06-12]
+
+### Changed
+
+- **Devpulse dashboard slimmed — todos no longer duplicated (startup-context
+  fix).** `DASHBOARD.local.json` was embedding the full `todos[]` bodies that
+  already live in `.trinity/local.json`; since both files are read at every
+  startup, that was pure duplication. The dashboard now emits `todo_count` only
+  (the glance value) — the bodies are commented out in the prax
+  `devpulse_dashboard` plugin's `todo_section.py` (revivable). Dashboard
+  `DASHBOARD.local.json` 6.8 KB → 3.0 KB. Devpulse-only (plugin, not templated).
+  Verified: seedgo 100%, 17/17 plugin tests.
+- **Deprecated dashboard sections are now actually pruned on refresh.**
+  `bulletin_board` (and the other entries in prax's `DEPRECATED_SECTIONS`:
+  `devpulse`, `commons_activity`, `agent_status`, `memory_bank`) were listed as
+  deprecated but only excluded from template *pushes* — they lingered in every
+  branch's live `DASHBOARD.local.json`. Added `_prune_deprecated_sections()` to
+  the prax dashboard `refresh` path (reusing the single `DEPRECATED_SECTIONS`
+  constant), so a refresh strips them. Verified: `bulletin_board` removed from
+  the devpulse dashboard; 116/116 prax tests, seedgo 100%. (Follow-up: `@trigger`
+  still has a `bulletin_created` writer to retire separately.)
+- **Dashboard slimmed to a lean glance — removed duplicated/dead sections.**
+  Dropped three sections from the devpulse dashboard: `session` (broken since
+  May — read keys `id`/`d`/`sum` vs the actual `session`/`date`/`summary`, so it
+  always wrote empty strings — and it duplicated `local.json`, which loads at
+  startup), `todo` (carried only `todo_count`, already in `quick_status`; now
+  sourced directly from `local.json`), and `ai_mail` (its counts live in
+  `quick_status`; the section is removed from output *after* quick_status is
+  computed from it). End state: 4 sections (`flow`, `memory`, `git`, `dispatch`)
+  + the `quick_status` glance. `session_section.py`/`todo_section.py` archived
+  (not deleted). `DASHBOARD.local.json` overall 6.8 KB → 2.4 KB. Verified: seedgo
+  100%, 108 prax tests. (Follow-up: `@ai_mail`'s `dashboard_sync.py` section
+  writer to retire separately.)
+- **quick_status now self-sources mail counts from `inbox.json`.** Decouples the
+  glance from the `ai_mail` section: prax's three quick_status calculators read
+  `.ai_mail.local/inbox.json` directly (`_read_mail_counts`) for `new_mail`/
+  `opened_mail`, so the `ai_mail` section is no longer a data dependency and can
+  be retired. 116 prax tests, seedgo 100%.
+- **Retired `@ai_mail`'s dashboard section writer (completes the dashboard
+  slim).** ai_mail no longer writes to the dashboard — removed
+  `push_dashboard_update` from 5 call sites and archived `dashboard_sync.py`.
+  With prax self-sourcing mail counts, the `ai_mail` section now stays gone (a
+  mail op no longer re-adds it — verified). 737 ai_mail tests.
+- **`.backupignore` is now a true `.gitignore` for the backup system — a single
+  source of truth (FPLAN-0269).** Replaced the hand-rolled `fnmatch`+part-loop
+  matcher (which broke leading-slash anchoring, `*`-crossing-`/`, dir-only `foo/`,
+  `!` negation, and last-match-wins) with the `pathspec` gitwildmatch library, so
+  `.backupignore` honors full gitignore semantics: include-by-default, `!`
+  negation, `#` comments, anchoring, dir-only, last-match-wins. `BUILTIN_IGNORES`
+  is demoted to a seed-only default (written when the file is absent, never merged
+  at runtime), and the separate `IGNORE_EXCEPTIONS`/`is_exception` layer is
+  removed (exceptions are native `!` lines). Snapshot, versioned, `all`, and
+  mirror-cleanup now all obey the one file. `.ruff_cache/` + `.coverage` added to
+  the default. `pathspec` (pure-Python, cross-OS) declared. Verified by artifact
+  (seedgo 100%, 220 tests incl. 26 new gitignore-parity tests) + live (a dotfile
+  flows into the store, `!` negation re-includes end-to-end).
+- **Backup store dir renamed `.backup_system/` → `.backup/`, dead `versions/`
+  removed (FPLAN-0269 follow-up).** The backup root is now `.backup/` (shorter,
+  coexists with `@flow`'s `.backup/processed_plans/`); the orphaned per-timestamp
+  `versions/` scaffold and the unused `build_versioned_path()` — both superseded
+  by the Phase-3 `versioned/` baseline+diff store — are gone. Drive sync confirmed
+  reading `.backup/versioned/` + `.backup/drive_tracker.json` via the shared
+  `backup_root()`. Verified by artifact (seedgo 100%, 220 tests) + live (a
+  throwaway project writes to `.backup/`, no `versions/` dir).
+
+### Fixed
+
+- **Backup Drive sync no longer silently drops 41% of files — including the
+  memories (FPLAN-0269).** Removed a foreign dotfile-skip in `drive_sync.py` that
+  excluded every dotted path (`.trinity/` memories, `.chroma/` vectors, `.aipass/`
+  prompts, `.ai_mail.local/` mailboxes — 4558 files) from the offsite Google Drive
+  copy while the local snapshot/versioned kept them. Drive now uploads the full
+  versioned store (already exactly the `.backupignore`-filtered set). Added a
+  Drive-sync output panel matching the Snapshot/Versioned stages (header, progress,
+  stats, Duration | Location).
+
+### Added
+
+- **Backup Google Drive sync pipeline + restore command (FPLAN-0268, Phase 4 of
+  FPLAN-0264 — final).** Faithful port of GOLD's `GoogleDriveSync` against the
+  live `@api` gateway (`get_drive_service` + `api_call_with_retry` — never the
+  console-OAuth path). New `handlers/drive/`: `DriveClient` (folder hierarchy
+  `AIPass Backups/<project>/`, thread-safe cache, retry-with-rebuild),
+  `upload.py` (resumable `MediaFileUpload`, 3 threaded workers), `tracker.py`
+  (mtime+size dedup → no re-upload of unchanged files), `test.py` (connectivity).
+  All four `drive_*` modules un-stubbed; `all` now runs snapshot→versioned→
+  drive-sync and **fails honestly** if Drive creds are absent (never silent-skips,
+  never fakes success, snapshot+versioned still report). New `restore` command
+  (`restore <project> list <file>` / `restore <project> file <file> <out>`)
+  exposing the Phase-3 baseline+diff restore engine. Drive tests fully mocked —
+  zero real Google calls in CI. Verified by artifact + live: audit 100% (all 37
+  files), 187 tests, ruff clean, restore `list`/`file` round-trip confirmed.
+- **Backup uses the repo-root pyright config like every citizen.** Removed
+  backup's standalone `pyrightconfig.json` (a leftover from its pre-namespace
+  standalone days, archived) so it inherits the root config — resolving imports
+  consistently with the rest of AIPass. Dead PyQt5 `ui/settings_window.py`
+  (never wired) archived.
+
+- **Backup versioned baseline + per-file diff engine (FPLAN-0267, Phase 3 of
+  FPLAN-0264 — the heart).** Faithful port of the GOLD versioned engine,
+  replacing the mtime full-copy-into-timestamped-dirs remnant. One persistent
+  store (`.backup_system/versioned/`) with GOLD's file-folder packaging: each
+  file gets `<parent>/<name>/` holding the current copy, a
+  `<stem>-baseline-<date>.<ext>` full copy from the first run (never touched
+  again), and `<name>_diffs/<name>_v<old-mtime>.diff` unified-diff patches on
+  every change — append-only, versioned **never deletes** (cleanup stays
+  snapshot-only). Versioned and snapshot back up the identical file set (same
+  scan + ignore patterns; `all` shares one scan). Change detection is
+  ledger-free (source mtime vs store-current mtime, `copy2`-preserved) — kills
+  the regression where running snapshot starved the next versioned via the
+  shared `timestamps.json`. New `diff/restore.py` (`list_versions` +
+  `restore_file`); `diff/generator.py` wired (binary detection + diff
+  include/ignore patterns). +15 tests (125 total). Verified by artifact + live
+  end-to-end: snapshot-first-then-versioned still baselines everything
+  (starvation dead), edit → real diff with old-mtime timestamp, source delete →
+  versioned store untouched while snapshot mirror-deletes, restore round-trip
+  byte-identical.
+
+- **Backup snapshot fidelity + shared core (FPLAN-0266, Phase 2 of FPLAN-0264).**
+  Restored the snapshot-side machinery the 2026-04-23 rewrite degraded, ported
+  from the GOLD archive onto the current per-project handlers. New
+  `handlers/cleanup/mirror.py` `cleanup_deleted_files` — exception-aware
+  mirror-delete: files removed from source are now removed from the snapshot
+  (was a blind `rmtree`+recopy), respecting ignore-exceptions. `copy/snapshot.py`
+  gains mtime-skip (quick-check fast path — unchanged files no longer re-copied),
+  a long-path guard (>260), and read-only handling. `report/result.py`
+  `BackupResult` now tracks critical vs non-critical errors + warnings +
+  `files_deleted`; `ignore/patterns.py` gains `IGNORE_EXCEPTIONS`/`is_exception()`.
+  +16 tests (`test_snapshot_fidelity.py`, 110 total). Verified by artifact +
+  live: audit 100%, 110 passed, and a real throwaway-project test (delete two
+  files → re-snapshot → both mirror-deleted, kept files preserved, 3 skipped/0
+  re-copied).
+
+- **Backup test suite + seedgo 100% — restoration foundation (FPLAN-0265, Phase 1
+  of FPLAN-0264).** Put a safety net under `backup` before the feature rebuild:
+  new `tests/` suite (94 tests — json_handler, CLI routing, filesystem handlers,
+  error resilience, mocked drive) ported from the canonical citizen conftest
+  pattern (hermetic, `tmp_path`, stdlib-only → 3.10–3.13), driving module coverage
+  to 27%. Standards brought to 100% across all 35: shared `--help/-h/help` guard
+  wired into all 10 modules' `handle_command` (Cli + Introspection), the 6
+  Phase-3 drive/diff/ui stubs wired-or-bypassed (Dead_Code + Unused_Function),
+  `requirements.project.txt` added (Architecture), README module list + the small
+  Modules/Trigger fixes (`display.handle_command`, `create_progress_bar` →
+  `build_progress_bar`). Verified by artifact: re-ran audit (100%) + pytest
+  (94 passed) + ruff (clean).
+
+### Fixed
+
+- **Memory rollover no longer silently loses rolled-off learnings ("No embeddings
+  generated").** A capped `.trinity` file rolls its excess entries out to vectors;
+  two combined bugs dropped them on the floor instead. (1) On the "embedding returned
+  empty but success=True" path the orchestrator logged the error and continued — but
+  the source file was *already* trimmed, so the entry was lost from both the file and
+  ChromaDB; it now restores the pre-trim backup before continuing (fail-honest).
+  (2) A concurrent-rollover race (two runs ~33ms apart) let the second run extract
+  nothing yet still report success → empty embeddings → bug #1; `extract_with_metadata`
+  now honors the `skipped` flag and the orchestrator skips no-op extractions before the
+  embedding stage. Verified by artifact + live: a 25/25-capped test file rolls over →
+  embeds (384-dim) → `drone @memory search` returns it at 91% similarity; audit 100%,
+  876 tests (+4).
+
+- **Backup Google Drive folder duplication + dedup-wipe fixed (GOLD-faithful lock
+  restoration).** The Phase-4 port had narrowed `GoogleDriveSync`'s folder lock: a
+  single `drive_sync` run's 3 upload workers raced the folder search+create →
+  multiple "AIPass Backups" root folders, and `get_or_create_backup_folder` reset
+  the dedup tracker on every call (re-uploading everything = the slowness). Restored
+  GOLD's structure exactly: `get_or_create_project_folder` / `get_or_create_nested_folder`
+  hold `_folder_cache_lock` across the **entire** method (cache + root-ensure + search
+  + create); `get_or_create_backup_folder` is lock-free (called inside the project
+  lock — no re-entrant deadlock), short-circuits cached ids via `_verify_folder_id`,
+  and clears the tracker only on a genuine brand-new root folder. Also: all four
+  `drive_*` commands route by their underscore names (were hyphenated → "Unknown
+  command"); `requirements.project.txt` now declares the three google libs. Verified
+  by artifact (seedgo 100%, 197 tests incl. a 5-thread concurrency test → exactly one
+  create) + live (real Drive backup: no duplicate folders).
+
+- **Backup rich CLI output restored end-to-end (FPLAN-0263 + drone passthrough).**
+  `drone @backup snapshot|versioned|all` rendered a flat text block instead of the
+  original rich output. Two independent causes, both closed: (1) the rich rendering
+  was never carried forward in backup's revival — rebuilt as a faithful 9-stage port
+  (new `backup_timestamps` state handler + `display.py` pipeline: Last-backups panel →
+  boxed header → live Rich progress bar → result summary → Backups-now panel;
+  `BackupResult` extended with `files_checked`/`files_skipped`/`backup_path`; copy
+  handlers emit `on_progress` callbacks). (2) drone was flattening it at the pipe —
+  `@backup` ran through `capture_output=True` (non-TTY → Rich strips color, the
+  `transient` progress bar renders to nothing) and the 30s capture timeout would kill
+  large backups; added `backup` to drone's `INTERACTIVE_BRANCHES` so all `@backup`
+  commands inherit the terminal (mirrors `cli`). Verified live under a pty: full color
+  + animated progress bar.
+
+## [2026-06-11]
+
+### Fixed
+
+- **seedgo audit local↔CI parity (FPLAN-0261).** The local `seedgo` audit could
+  silently diverge from CI, breaking the "pass locally first, then ship" gate.
+  Three independent causes, all closed without coupling any checker to git
+  (`.gitignore` is git's concern, not the audit's): (1) usage-scanning checkers
+  (`unused_function`, `dead_code`, +4) `rglob`'d gitignored *output* dirs
+  (`artifacts/`, `dropbox/`), so a stray local file could mark a function "used"
+  that a clean checkout correctly flags — every per-checker skip list hoisted to
+  one shared `SOURCE_SKIP_DIRS` (output dirs simply aren't source). (2) The
+  `diagnostics` standard shelled out to bare `python3 -m pyright` (system python,
+  no pyright) and, on the resulting JSON-parse failure, returned *0 errors = clean*
+  — a silent false-green; now uses `sys.executable` and **fails loud**. (3) pyright
+  resolved imports against PATH-python, so results flipped with `.venv` activation
+  — pinned via `--pythonpath sys.executable`. The audit is now deterministic
+  local == CI (proven all-13-branches-100% in an unactivated shell). Also: `drone`
+  bypasses the test-only broker `start_background` (intentional API, not dead code).
+- **windows-setup CI: guard Linux-only sandbox tests.** The kernel-sandbox build
+  is Linux-only (bwrap, `AF_UNIX` sockets, `openat2`); the code already guards on
+  `sys.platform`, but four test surfaces ran unconditionally and failed on
+  `windows-latest`. Module-level `pytestmark = pytest.mark.skipif(sys.platform !=
+  "linux", …)` on `drone/tests/test_broker.py` and `hooks/tests/test_sandbox.py`;
+  scoped guards on the remaining `AF_UNIX` broker-socket tests —
+  `ai_mail/.../test_dispatch_monitor.py::TestBrokerRealE2E` (class) and
+  `aipass/.../test_sandbox_check.py::TestCheckBrokerAlive` socket-connect tests
+  (method-level, so the graceful no-broker paths still run on Windows). All skip on
+  Windows and run unchanged on Linux. windows-setup was green pre-sandbox-merge
+  (`00edd8b`) and red since (`0b4ba63`); this closes it.
+- **Broker `start_background` connect-before-bind race.** `drone`'s out-of-sandbox
+  broker daemon started via `start_background()`, which returned *before* the
+  `AF_UNIX` socket was bound — callers then raced the bind, and on a slower machine
+  `create_identified_connection()` hit `FileNotFoundError` (socket not yet present).
+  Deterministic locally (`test_delete_nested_file` 0/5), green in CI only by timing
+  luck — latent flakiness. Fixed with a `threading.Event` set right after `listen()`;
+  `start_background(timeout=5.0)` now blocks on it and **raises** if the socket never
+  binds, so callers never guess a `sleep`. Removed the 4 blind `time.sleep(0.15)`
+  waits from the broker tests. Verified 55/55 broker tests, formerly-failing test 10/10.
+
+### Added
+
+- **`aipass init` detects missing Claude Code.** Stage 6 (CLI choice) now checks
+  `shutil.which("claude")` when the picked CLI is Claude Code. If absent: interactive
+  runs prompt `Install now? [Y/n]` and run the canonical installer on yes (native
+  `claude.ai/install.sh`, PowerShell on Windows, `npm` fallback, 300s timeout, loud on
+  failure); non-interactive runs warn and continue. The whole system routes through
+  Claude Code (hook bridge, dispatch, prompt injection), so init no longer silently
+  assumes the runtime is present. Only fires when the chosen CLI is `claude`.
+- **Kernel filesystem boundary for agent containment (DPLAN-0202 / FPLAN-0250).**
+  Every autonomous agent can now launch inside a kernel-enforced mount namespace
+  (`@anthropic-ai/sandbox-runtime` → bwrap+seccomp) where reads stay fully open
+  (the shared live filesystem is preserved — a bind-mount, *not* isolation: own-tree
+  writes land live on the real FS instantly) but deletes/overwrites of protected
+  paths (`.git`, sibling branch trees) fail at the kernel no matter how the call is
+  phrased — `rm`, `python os.remove`, `find -delete`, Write tool all hit EROFS.
+  `/tmp` and the agent's own tree stay writable; `.git` is RW for devpulse, RO for
+  builders. A per-role policy generator (`@hooks build_policy`) derives each branch's
+  writable/RO map from its passport. Privileged deletes route through an
+  out-of-sandbox **drone-broker** daemon: identity-scoped allowlist, `openat2`
+  RESOLVE_BENEATH path re-resolution (confused-deputy proof), HMAC identity handshake
+  over a pre-connected inherited fd, JSONL audit. `aipass doctor` gained a **Sandbox**
+  check group (bwrap present+functional, node, srt, rg, broker socket) that is LOUD
+  when the flag is on and a prereq is missing — never a silent unsandboxed launch.
+  Proven by a live 16-check red-team suite. **Inert by default** — gated behind
+  `AIPASS_SANDBOX_ENABLED` (off); flag-off is byte-identical to the old dispatch path.
+- **rm_gate demoted to guardrail.** Now framed honestly as early-feedback that
+  catches the accidental `rm -rf` and teaches `drone rm` — belt-and-suspenders, with
+  the kernel sandbox as the actual filesystem boundary.
+
+- **Prompt-injection cadence — fire the big loaders every Nth turn.** The global
+  and branch prompts are large and were re-injected on *every* turn even though a
+  prior copy stays in the conversation. They now fire together every 5th turn
+  (config-tunable via `hooks_json/custom_config/cadence_config.json`), with a
+  per-session turn counter that resets on a new session and after compaction so
+  context is always rebuilt when it's actually needed. Identity and the mail flag
+  stay every-turn (tiny, want freshness). Cuts recurring per-turn context cost.
+- **Hook fire/skip observability.** Cadence emits a structured
+  `[HOOKS] cadence fired|skipped loader= turn= period= offset=` line; the prax
+  monitor renders hook events distinctly so the cadence is visible live.
+- **Slim global prompt — context-on-demand.** The always-injected global prompt
+  was rewritten from a ~13.8KB encyclopedia into a ~7.8KB navigation map
+  (DPLAN-0201): `drone` pinned as the router, the framework tree, all 13 agents
+  as short bios, and one drilled reflex — run `drone @agent --help` before using
+  a branch. Detail now lives in each agent's `--help`, fetched on demand. This
+  also dissolves the harness ~10k-char truncation that was silently dropping the
+  old prompt's tail; the slim prompt injects whole. Backup retained alongside.
+
+### Changed
+
+- **Shared leaf library re-homed: `aipass.common` → `aipass.aipass.shared` (FPLAN-0260).**
+  `src/aipass/common/` was the only non-citizen directory in the agent namespace —
+  a shared lib (json_handler / json_ops / registry_discovery, extracted in
+  TDPLAN-0006 P2) parked as a sibling to the agents with no owner. Per @seedgo
+  design review it now lives inside its steward at `src/aipass/aipass/shared/`,
+  owned by @aipass; @spawn imports across (same blessed shared-infra category as
+  `aipass.prax`/`aipass.cli`). Content byte-identical; ~9 import/doc sites updated
+  across aipass+spawn. A new subprocess guard test pins the bootstrap-safety
+  invariant: importing `shared/` loads zero branch dependencies, so `aipass init`
+  keeps working pre-drone on fresh machines. Note: `aipass.common` shipped in the
+  v2.5.2 wheel; it was internal plumbing — no deprecation shim.
+- **Action-gated hook sound.** Piper now speaks only when a hook actually *does*
+  something — handlers return a `sound` key the engine plays, instead of
+  announcing on every invocation. Skipped loaders are silent. Quieter and honest.
+- **README: hardcoded metrics → live badges + qualitative.** Version is now a
+  live PyPI badge, test/PR counts replaced with a codecov coverage badge (75%
+  minimum) and qualitative wording — no more stale numbers to hand-maintain.
+
+### Fixed
+
+- **Cadence counter separate-process race.** Each `UserPromptSubmit` hook runs as
+  its own OS process, so a module-level turn cache double-incremented and the
+  loaders leapfrogged (firing erratically instead of together). Fixed with an
+  mtime debounce + transcript-size token + `flock` so the counter advances exactly
+  once per real turn, verified against the live execution model.
+- **`auto_fix` ran no diagnostics.** A leftover `speak()` call (its import removed
+  in the sound refactor) raised `NameError` on every edit, swallowed by the
+  handler's broad `except` — so auto-fix silently surfaced nothing on any
+  `.py`/`.json` edit. Removed the dead call; diagnostics run again.
+- **Hook events never colored in the monitor.** The prax log-watcher's
+  `_HOOK_PATTERN` required an `action=` field that cadence never emits (it logs
+  the action as the bare second word, `fired`/`skipped`), so extraction failed
+  and events fell through to plain rendering instead of the styled
+  bold-green ⚡ / dim · treatment. Fixed the regex to capture the bare action
+  word and enriched the event detail (period, offset, short session id).
+
+### Security
+
+- **Least-privilege token on the `e2e-wheel` workflow.** `e2e-wheel.yml` was the
+  one CI workflow missing a top-level `permissions:` block (it was added during
+  the cross-OS work after PR #624 hardened the others), so it ran with the
+  default broad `GITHUB_TOKEN` scopes — dropping the OpenSSF Scorecard
+  Token-Permissions check to 0. Added `permissions: contents: read`; the
+  workflow only reads the repo to build and smoke-test the wheel.
+- **Signed GitHub Releases via Sigstore (keyless).** The release workflow now
+  signs the built wheel + sdist with `sigstore/gh-action-sigstore-python`
+  (keyless OIDC — no signing key is generated, stored, or held by anyone) and
+  attaches the resulting `.sigstore.json` bundles to the GitHub Release. PyPI
+  uploads were already attested via Trusted Publishing; this extends verifiable
+  provenance to artifacts pulled from GitHub Releases and satisfies the OpenSSF
+  Scorecard Signed-Releases check. First proof lands on the next `v*` tag.
+
+---
+
+## [2026-06-02]
+
+### Fixed
+
+- **`aipass init` scaffold correctness.** A fresh `aipass init` now generates a
+  project-specific `AGENTS.md` (new `agents_md()` generator) instead of falling
+  back to copying AIPass's own repo-root `AGENTS.md` boilerplate — Codex users
+  were getting the wrong file. Project `README.md` quick-start/structure paths
+  now reflect the real `src/<package>/<agent>/` layout.
+- **First-agent default name `my-agent` → `my_agent`.** `aipass init` seeded its
+  default agent with a hyphen, the lone source of a long-standing dir-vs-module
+  mismatch (the directory kept the hyphen while the importable module, `@address`
+  and registry name all normalize to underscore). Defaulting to `my_agent` makes
+  directory, module, `@address` and the README example all consistent.
+- **Dead `citizenship.registry_path` removed from spawn templates.** The field
+  pointed at a non-existent `.aipass/registry.json`; it was never read anywhere
+  (registry is located by `find_registry()` glob), so it's dropped from the
+  `builder` and `birthright` passport templates.
+
+### Removed
+
+- **The entire STATUS flow is decommissioned (TDPLAN-0007).** The per-branch
+  hand-maintained `STATUS.local.md` beacon and the auto-aggregated central
+  `STATUS.md` (853 lines / 70 KB nobody read) are gone — deleted from disk
+  across all 13 branches and scrubbed from every prompt, doc, startup protocol,
+  `/prep` + `/memo` skill, the compact-recovery hook, the email footer, and
+  `aipass init` / spawn scaffolding. Live branch state was already fully covered
+  by `DASHBOARD.local.json` (prax) and history by `.trinity/local.json`. The
+  status-sync engine is kept **intact but inert** — made dormant by unwiring its
+  3-line trigger registration (`trigger registry.py`), so the code stays
+  revivable. The one thing STATUS uniquely gave us — a quick scratch todo — is
+  replaced by an operational `todos[]` section in `.trinity/local.json`
+  (@memory-owned schema, capped, never vectorized by rollover), pushed to all 13
+  branches and surfaced as a `todo_count` on the dashboard. Shipped as one
+  coordinated cross-branch change (memory, prax, trigger, aipass, spawn, hooks,
+  ai_mail, seedgo + devpulse).
+
+### Changed
+
+- **All 13 branches at seedgo 100% under the new introspection standard.**
+  Wrapped `print_introspection()` output in Rich markup across ai_mail, drone,
+  spawn, trigger, prax and devpulse (the rest were already compliant) —
+  presentation only, no logic change — so `drone @branch` with no args renders
+  consistent styled output everywhere.
+- **CLI polish for human-facing output.** `drone @hooks --help` rewritten (Rich,
+  with `hooksound on/off/status` now surfaced); `drone @spawn` repair help
+  clarified as distinct from `update` and showing the preview/`--apply` flow;
+  drone restores Rich colour on human-facing routed output (`--help`,
+  introspection, `status`) via the inherit path.
+- **Spawn backups land in one namespace `.spawn/.recovery/` (TDPLAN-0006 P4).**
+  Spawn's pre-merge JSON backups previously dropped a `.recovery/` directory at
+  each branch root (which had accumulated 242 stale auto-generated `DASHBOARD`
+  backups across 10 branches). `aipass.common.json_ops.backup_json` gained an
+  optional `backup_dir` parameter (default unchanged), and spawn's update engine
+  now directs backups to `{branch}/.spawn/.recovery/` — tucked under the
+  spawn-managed `.spawn/` dir instead of cluttering the branch root. Memory stays
+  in the safety net (the engine simply never touches `.trinity/`/`DASHBOARD` on
+  update, so it never needs to back them up). Stale `.recovery/` backups cleaned
+  up. (315 tests, seedgo 100%.)
+- **No more cross-branch engine imports — `aipass init update` calls spawn via
+  subprocess (TDPLAN-0006 P3).** `init_flow.py` previously did
+  `from aipass.spawn.apps.modules.sync_registry import sync_registry` — the one
+  place aipass reached directly into spawn's Python. Replaced with a subprocess
+  call to the already-existing `drone @spawn sync-registry --fix` (same pattern as
+  `aipass init agent` → `drone @spawn create`), preserving graceful degradation
+  (a missing `drone`, non-zero exit, or timeout is silently skipped — registry
+  sync never hard-fails an update). The aipass branch now has **zero** direct
+  imports of another branch's engine code; the remaining cross-branch imports are
+  shared service layers only (cli Rich UI, prax logging, trigger events). (438
+  tests, seedgo 100%.)
+- **`aipass.common` shared library — dedup spawn/aipass scaffold machinery
+  (TDPLAN-0006 P2).** `@spawn` and `@aipass` each carried their own copy of the
+  JSON merge/handler utilities and registry discovery. Extracted them into a new
+  branch-free package `src/aipass/common/` (`json_ops` = `deep_merge` +
+  `backup_json`; `json_handler.JsonHandler`; `registry_discovery.find_registry`)
+  that both branches now import. `aipass.common` imports **zero** branch code, so
+  `aipass/bootstrap.py` (which runs before the drone runtime exists) can depend on
+  it without breaking the pre-infrastructure constraint. The duplicated copies are
+  deleted (spawn keeps a thin re-export shim; aipass's `json_handler` shrank
+  254 → 88 lines). The `save_json` contract is unified to **raise `ValueError`**
+  on invalid structure across both branches. (313 spawn + 434 aipass tests, both
+  seedgo 100%.)
+
+### Fixed
+
+- **Flow plan-type self-serve UX — register override, help, orphan cleanup.**
+  Explicit `drone @flow register <dir> <PREFIX>` now overrides an auto-derived
+  prefix instead of silently failing (guarded — refuses if the auto-registered
+  type already holds plans), so custom prefixes are settable when adding a new
+  plan type. `create`/`templates --help` rewritten to dynamically list registered
+  types + templates and document the add-a-new-type workflow. Stale orphan plan
+  registries removed; dead `prefix_exists()` dropped. (728 tests, seedgo 100%.)
+- **`drone @spawn update` no longer scrambles branches (#636, critical — TDPLAN-0006
+  P0+P1).** The update engine compared a freshly-created branch against the class
+  template by *content hash* with rename-detection, and because the CREATE path
+  regenerated template-registry IDs in filesystem-walk order (≠ the master's
+  hand-crafted IDs), a branch created seconds earlier produced **30 proposed renames**
+  that rotated identity/memory dirs into each other
+  (`apps→.trinity→.seedgo→.claude→.archive→.aipass`), turned `README` into
+  `DASHBOARD`, and deep-merged stale template into live `.trinity/` memory —
+  `update <class> --all` would have destroyed every citizen in one command. Rebuilt
+  `update_ops.py` (v2.0) on an explicit **named-managed-files + path-based** model:
+  `.trinity/*`, `DASHBOARD.local.json`, `artifacts/birth_certificate.json` and
+  `.seedgo/bypass.json` are delivered on **create only** and never touched on update;
+  the create==update invariant now yields **0 renames / 0 merges** on a fresh branch.
+  The old ID-based engine (`change_detection.py`, `reconcile.py`) is deleted.
+- **Destructive spawn ops are now dry-run by default (TDPLAN-0006 P0).** `drone @spawn
+  update` and `drone @spawn repair` preview by default and require an explicit
+  `--apply` to write — forgetting a flag is now a safe no-op instead of irreversible
+  damage (`--dry-run` kept as an alias). `aipass doctor` repair suggestions emit the
+  matching `--apply` form.
+
+### Added
+
+- **Introspection Rich-formatting standard (seedgo).** New
+  `check_introspection_rich_formatting` checker enforces that each branch's
+  `print_introspection()` output uses Rich markup (delegation-aware — it walks
+  `_`-prefixed helper functions), keeping no-arg `drone @branch` output styled and
+  consistent. Documented in `introspection.md`; all 13 branches brought into
+  compliance (see Changed).
+- **Playbook plan type (`PBPLAN`) — reusable SOP checklists (flow).** A new
+  `playbook_plans` template family for throwaway, vectorize-on-close operational
+  runbooks (first SOP: the Sunday merge). Drop a `.md` under
+  `templates/playbook_plans/`, register once, then
+  `drone @flow create . "subject" <sop>` stamps a run to tick through and close.
+- **Memory-pool auto-processing (TDPLAN-0005)** — dropped files in
+  `memory/memory_pool/` are now vectorized and archived automatically on
+  session-start and pre-compact, instead of requiring a manual
+  `drone @memory pool process`. A 3-branch build: `@memory` gains an intake
+  handler + `pool` module (processes then empties the pool, `keep_recent=0`),
+  `@hooks` adds a `lifecycle/auto_process` handler (session-guarded via
+  `CLAUDE_CODE_SESSION_ID`, since Claude Code has no SessionStart hook), and
+  `@trigger` gains event #15 (`memory_pool_auto_processed`) with a Medic error
+  path. Runtime pool dirs (`memory_pool/`, `memory_pool_archive/`) are now
+  gitignored.
+- **HVTracker badge** added to the README badge cluster, linking to the public
+  agent profile at hvtracker.net (closes #628).
+- **`git_gate` read-verb allowlist — raw read-only git for every branch.** The
+  PreToolUse `git_gate` previously blocked *all* raw git (forcing `drone @git`
+  even for harmless reads), which left agents unable to inspect what git ships —
+  the exact forensics needed to diagnose the audit gap above. It now allows 22
+  read-only verbs raw (`ls-files`, `ls-tree`, `show`, `cat-file`, `rev-parse`,
+  `rev-list`, `log`, `status`, `diff`, `blame`, `archive`, `grep`, …) while
+  write operations stay `drone`-gated. Global options (`-C`, `-c`, `--git-dir`,
+  …) are skipped when extracting the verb, and chained commands are split on
+  `&&`/`||`/`;`/`|` so a read piped into a write still blocks the whole line.
+  (81 tests)
+- **Cross-OS end-to-end WIRING test (`tests/e2e/`, `e2e-wheel.yml`)** — the first
+  CI gate that proves real AIPass *wiring* (not units-with-mocks) by building the
+  wheel, installing it into a clean venv, and asserting a 4-tier ladder: package
+  install + console scripts (T0), `aipass init` scaffolding (T1), a hook actually
+  firing via the bridge with an observable `engine.jsonl` record (T2a), and
+  `drone` resolving + subprocess-executing a real branch (T3). Runs on a 3-OS
+  matrix (ubuntu/windows/macos, `fail-fast: false`). Ran red-first on Windows by
+  design and immediately earned its keep — it caught two real, *previously
+  uncovered* Windows wiring bugs (`aipass init` preflight + `drone` stdout
+  encoding, both fixed below). Notably the layers we most feared — clean-wheel
+  install (T0) and hook firing (T2a) — passed on Windows. (DPLAN-0194 /
+  FPLAN-0239)
+- **`drone rm` — provider-agnostic safe delete** — a contained recursive delete
+  that lets agents clean up scratch dirs without tripping the `rm -rf` block.
+  Deletes are confined to the project root and the system temp dirs (`/tmp` and
+  `$TMPDIR`), refusing anything outside (home, `/etc`, `/`, etc.). Even inside
+  those roots it hard-refuses protected internals — `.git`, `.trinity/`,
+  `.aipass/`, `.codex/`, `.agents/`, and sibling-branch worktrees — mirroring the
+  filesystem boundary an OS-sandboxed agent (e.g. Codex) enforces, so behavior is
+  consistent across CLIs. Pure-Python (`shutil.rmtree`), with a red-team test
+  suite for containment escapes (symlinks, traversal, sibling branches). (#630)
+- **`rm_gate` hook — block raw recursive `rm`, teach the safe path** — a
+  PreToolUse gate (mirroring `git_gate`) that blocks raw `rm -r`/`-rf`/`-fr`/
+  `--recursive` and redirects the agent to `drone rm`. Provider-agnostic (runs in
+  the hook engine, not tied to Claude Code permission rules), conservative
+  (unparseable targets are blocked, not allowed), and skips `drone rm` itself.
+  This makes the safe-delete path discoverable at the moment of friction. (#630)
+- **Hook engine logs `agent_type` / `agent_id` per fire** — the engine now
+  records which agent triggered each hook (e.g. `agent=main` vs `agent=Explore`)
+  in both `engine.jsonl` and the prax monitor stream. Previously the payload
+  flowed into handlers but was never logged, leaving no way to tell an internal
+  main-turn fire from a real sub-agent fire. Pure visibility; no behavior change.
+  Groundwork for #606. (#606)
+- **OpenSSF Best Practices passing badge** — AIPass earned the OpenSSF Best
+  Practices (CII) **passing** badge (100% of criteria), added to the README badge
+  cluster. Self-certified across all six categories — basics, change control,
+  reporting, quality, security, and analysis. Complements the existing OpenSSF
+  Scorecard, lifting the `CII-Best-Practices` check from 0. (DPLAN-0193)
+
+### Changed
+
+- **Standards floor raised to genuine 100% across all 13 branches** — completed
+  the campaign that lifted the seedgo gate threshold from 80 to 100. Rather than
+  bypass failing files, two check *flaws* were fixed at the root: (1) the
+  **file-size / architecture check is now advisory** (warn-only for 700–1500 line
+  files with no docstring nudge, hard-fail only above 1500) — large files are a
+  smell, not a defect; (2) **readme-freshness now compares against git history,
+  not file mtime** — `git checkout`/`merge` reset mtimes without any semantic
+  change, so the old check false-positived (flow + prax shared an identical
+  mtime from one git event, not real edits). It now diffs the README's "Last
+  Updated" against the last commit that touched `.py`. Genuine content fixes
+  where warranted (aipass requirements template + handler routing; honest README
+  content refreshes on flow, prax, devpulse). The readme-freshness **failure
+  message now teaches** the right fix ("update README content, then set the date
+  — don't just bump it"). Also optimized the devpulse watchdog poll cadence
+  (2s → 5s; the loop is cheap, so the tighter interval was wasted CPU). (#631)
+
+- **Retired the blanket `rm` deny from provider settings** — `setup.sh` and
+  `aipass init` no longer ship `Bash(rm -rf*)` / `Bash(rm -r *)` deny rules
+  (they were mis-filed among git rules, blocked all `/tmp` cleanup, and gave a
+  bare "permission denied" with no guidance). The `rm_gate` hook + `drone rm`
+  now own this — cross-provider, path-aware, and they teach. `aipass doctor`
+  detects the stale rules on existing installs and `aipass doctor --fix` removes
+  them (idempotent, preserves all other rules). Claude Code still natively
+  circuit-breaks `rm -rf /` and `rm -rf ~`. (#630)
+
+### Fixed
+
+- **`Windows Test` / `macOS Test` are no longer path-filtered — they were
+  stalling PRs as required checks.** Both workflows only triggered when
+  `setup.sh`/`drone/cli.py`/`handlers/__init__.py`/`pyproject.toml` changed, but
+  branch protection lists `windows-setup`/`macos-setup` as *required*. On any PR
+  that didn't touch those paths the workflows never ran, so GitHub parked the
+  required checks as "Expected — waiting for status" indefinitely, blocking the
+  merge (the tests themselves were green — they simply didn't fire). They now run
+  on every push/PR to main/dev, like the other required lanes. (A required check
+  must never be path-filtered.)
+- **`seedgo-audit` CI gate was red despite 100% local audits — four checkers
+  validated the working tree instead of committed source.** CI audits a clean
+  `git checkout` (tracked files only — git ships no empty or gitignored dirs),
+  but the working tree carries runtime dirs (`logs/`, `*_json/`, `artifacts/`,
+  `.trinity/`, `passport.json`), so every branch scored ~97% in CI while passing
+  at 100% locally. Reproduced exactly with a tracked-only tree (`git archive HEAD`
+  audits to CI's 97%). Four checkers now measure what git actually ships:
+  `log_structure` no longer fails when the gitignored `logs/` dir is absent (it
+  still enforces no-hardcoded-paths); `readme` cross-references `.gitignore`
+  (via `git check-ignore` with a fallback list) and skips gitignored dirs/links
+  in the directory-tree and dead-link checks; `encapsulation` infers the branch
+  from the path when the gitignored `AIPASS_REGISTRY.json` is unavailable (and no
+  longer collides on the `aipass` branch); `architecture` skips cleanly when the
+  gitignored `passport.json` is absent. A follow-up refined `readme`'s
+  `git check-ignore` use: `.gitignore` dir-only patterns (trailing slash —
+  `logs/`, `**/*_json/`, `.trinity/`) don't match a clean checkout's
+  non-existent paths unless directory intent is signalled, so the check now
+  also tests the trailing-slash form (this was the last 1% — `readme` flagged
+  `cli_json`/`logs`/`artifacts` as "missing on disk" in CI only). The CI gate
+  (`.github/scripts/seedgo_audit.py`) now also prints the failing standards and
+  their check messages, so a sub-100 result says *why*, not just the percentage.
+  Finally, the `seedgo-audit` CI job now installs the `memory` extra
+  (`pip install -e ".[dev,memory]"`): the `diagnostics` standard runs pyright over
+  every branch, and memory's handlers import `chromadb`/`numpy` at module level —
+  without those declared deps installed, pyright reported them as unresolved
+  (`reportMissingImports=error`) and memory scored 55%, a false failure from a
+  missing CI dep rather than a code defect. Clean-tree and working-tree audits
+  both report 13/13 = 100%. (DPLAN-0195)
+- **Two latent Windows portability bugs caught by the new e2e harness** — both
+  were always present in the code; they only surfaced now because this is the
+  first CI to run `aipass init` scaffolding and real-branch `drone` routing on
+  Windows (the old Windows CI ran an editable install, `aipass`-less, and only
+  routed to in-process modules, so both paths had zero Windows coverage). Pure
+  portability fixes — Linux/macOS behaviour is unchanged.
+  - **`aipass init` crashed on Windows (surfaced as a misleading "Unknown
+    command: init").** Init scaffolded the project correctly, then crashed
+    *printing its `✓ Project initialized` banner* — Rich wrote the ✓/box glyphs
+    through a cp1252 stdout, raising `UnicodeEncodeError ('charmap')`; the error
+    handler's `✗` message hit the same wall, bubbling up to the command router
+    which mislabeled it. The `aipass` entry point now reconfigures stdout/stderr
+    to UTF-8 in place on Windows. (The init preflight ancestor-walk was also
+    hardened to skip un-enumerable Windows drive-root entries — defensive, not
+    the trigger.)
+  - **`drone @branch` crashed on Windows with the same `UnicodeEncodeError
+    ('charmap')`.** `drone` resolved + subprocessed the branch correctly, then
+    crashed *printing* the captured output through cp1252 stdout. The existing
+    `PYTHONUTF8` guard only affected child interpreters, not the live process
+    streams — `drone`'s entry point now also `reconfigure()`s stdout/stderr to
+    UTF-8 in place.
+  - **CI unit lane no longer runs the e2e wheel tests.** `ci.yml`'s
+    `pytest --rootdir=.` swept in `tests/e2e/` (which build a wheel per the
+    dedicated `e2e-wheel.yml`), failing the unit lane; it now `--ignore`s them.
+    (DPLAN-0194)
+- **A release merge can no longer destroy the `dev` branch** — `drone @git merge`
+  passed `--delete-branch` to `gh pr merge` unconditionally, so merging a
+  `dev`→`main` PR deleted the persistent `dev` branch on the remote and stranded
+  the working tree on `main` (the next commit silently landing on main). Merge now
+  looks up the PR's head ref and **only deletes non-protected branches** — `dev`
+  and `main` are never deleted, and an undeterminable head ref fails safe (no
+  delete). After a merge it returns the working tree to `dev` (loud warning if it
+  can't). `drone @git branches` now runs `fetch --prune` before listing so it
+  reflects the live remote instead of stale cached refs, and a new
+  `drone @git prune-temp` cleans up merged temp PR branches. (#625)
+- **`drone @git status`/`diff` show their scope** — when scoped to a branch (no
+  `--all`), output now appends "(showing <branch> scope — use --all for full
+  repo)", so an empty scoped view is no longer mistaken for a clean repo. (#623)
+- **External projects can call AIPass branches via drone** — `drone @api ...`
+  (and any `drone @X`) now resolves from a non-AIPass project CWD instead of
+  being blocked with "path escapes project root." The resolver was validating a
+  branch's path against the *primary* registry root even when the branch was
+  found via the `AIPASS_HOME` fallback, so any external project (Vera Studio,
+  Daemon) hit a false security block. `resolve_branch()` now validates
+  containment against the registry the branch was actually found in. Security is
+  unchanged — each branch is still contained within its own declaring registry's
+  root; genuine path escapes remain blocked. (#618)
+- **`aipass <command>` runs instead of printing an introspection banner** —
+  `aipass` is a user-facing binary, so `aipass doctor` (and every other command)
+  must execute, not describe itself. All 7 modules (`doctor`, `doctor_fix`,
+  `doctor_wire`, `handoff`, `help_chat`, `init_flow`, `profile`) previously hit a
+  no-args→introspection gate (a standard meant for `drone @branch <module>`
+  discovery) and showed a banner on bare invocation. Now bare invocation runs the
+  command or shows usage; the introspection banner moved to `--info`. The seedgo
+  introspection standard is bypassed for these binary-invoked modules (documented).
+- **Dashboard plan counts no longer zeroed on refresh** — a branch's
+  `active_plans` was reset to `0` by every `drone @prax dashboard refresh`, because
+  `PLANS.central.json` only held Flow's own plans (`location==FLOW_ROOT` filter).
+  The central file is now comprehensive: all plans grouped per-branch, so refresh
+  reports each branch's real count (e.g. devpulse now shows its 12 open plans
+  instead of 0).
+
+### Security
+
+- **`dependency-scan` (pip-audit) green again — upgrade pip, drop stale ignores.**
+  The `Security Scan` workflow's `dependency-scan` job had gone red: pip-audit
+  scans the whole environment, and the runner's bundled pip (26.1.1) carries
+  advisory PYSEC-2026-196 (fixed in 26.1.2). The job now runs
+  `python -m pip install --upgrade pip` before auditing (it was the only CI job
+  not upgrading pip), removing the vulnerable version outright rather than
+  suppressing it. 26.1.2 also resolves CVE-2026-3219 and CVE-2026-6357, so the
+  two now-stale `--ignore-vuln` entries were removed — verified against a clean
+  reproduction of the job's environment, which audits to "No known
+  vulnerabilities found" with nothing ignored.
+- **Pinned the `requests` floor to a non-vulnerable version** — raised
+  `requests` to `>=2.34.2` in `pyproject.toml` and the API branch's
+  `requirements.project.txt` (which previously listed it unconstrained). This
+  clears six OSV advisories the OpenSSF Scorecard flagged against the dependency
+  (PYSEC-2014-13, PYSEC-2014-14, PYSEC-2018-28, GHSA-9wx4-h78v-vm56,
+  GHSA-9hjg-9r4m-mvj7, GHSA-gc5v-m9x4-r6x2) — the oldest surfaced only because the
+  dependency was declared without a version bound. No runtime change (the AIPass
+  venv already ran a fixed release). (DPLAN-0193)
+- **Pinned the test container base image by digest** — `Dockerfile.test` now pins
+  `ubuntu:24.04` to its registry digest (`sha256:786a8b55…`) so the test image is
+  reproducible and tamper-evident, clearing the Scorecard `containerImage not
+  pinned by hash` finding. (DPLAN-0193)
+
+---
+
+## [2026-05-30]
+
+### Added
+
+- **`drone @hooks status`** — read-only viewer for a project's hook config:
+  master switch, every hook's enabled state per event group, matchers, and an
+  enabled/total summary. Resolves the project's `.aipass/hooks.json` by walking
+  up from CWD. (DPLAN-0190 Phase B)
+- **Hooks activate in every project** — `aipass init` now writes
+  `.aipass/hooks.json`, so new projects fire the hook engine out of the box
+  (previously: no config shipped, 0 hooks fired). `aipass init update`
+  union-merges the template, preserving any per-hook on/off choices the user
+  made. `aipass doctor` now checks for the config's presence. Dead hook-script
+  shipping (`_ship_hooks`) removed. (DPLAN-0190 Phase A)
+- **README logo** — centered logo image replaces plain `# AIPass` header.
+  New `assets/logo.png` added to the repo.
+- **OpenSSF Scorecard** — `.github/workflows/scorecard.yml` runs the official
+  OSSF Scorecard action on push to `main` and weekly. Publishes a public security
+  health score at scorecard.dev with a README badge. Actions pinned by SHA.
+- **GitHub Releases** — `publish.yml` now cuts a GitHub Release on each `v*` tag,
+  with notes pulled from the top CHANGELOG section and the built dist attached.
+  PyPI publish + GitHub Release now fire from the same tag.
 - **Registry descriptions** — all 13 branches now have one-liner descriptions
   in `AIPASS_REGISTRY.json`. `drone systems` shows what each agent does
   instead of blank lines. Closes [#607](https://github.com/AIOSAI/AIPass/issues/607).
 
 ### Changed
 
-- **Edit gate now project-aware** — cross-branch write protection and daemon
-  confinement no longer hardcode `src/aipass/`. The package name is derived
-  dynamically from CWD, so any `src/<package>/<branch>/` project gets the
-  same security. 4 new tests for external projects. Addresses
-  [#605](https://github.com/AIOSAI/AIPass/issues/605).
+- **Security gates fully project-aware** — both the edit gate *and* the
+  subagent stop gate now derive the package name dynamically from CWD instead
+  of hardcoding `src/aipass/`. Cross-branch write protection and branch
+  detection work for any `src/<package>/<branch>/` project; previously the
+  subagent gate silently no-opped outside AIPass. 9 new external-project tests.
+  Closes [#605](https://github.com/AIOSAI/AIPass/issues/605).
 - **Hooks branch promoted to service** — registry profile changed from
   "AIPass Workshop" to "library" so it appears in `drone systems` alongside
   the other 12 services.
+- **Hooks branch hardened to 100% seedgo** — the @hooks citizen took full
+  ownership of its branch: every handler verified wired + firing, README
+  rewritten (two-tier provider/project model, dynamic-dispatch design, event
+  table), 2 stale tests resolved (253 pass). Dead-code/unused-function flags
+  documented as architectural bypasses — the 15 handlers are invoked
+  dynamically via `importlib` from `hooks.json` paths, never statically
+  imported. (DPLAN-0191)
+
+### Release
+
+- **Version 2.5.0** published to PyPI. Trusted publishing via GitHub Actions
+  (`publish.yml` triggers on `v*` tags — no manual twine upload needed). The
+  same tag now also cuts a GitHub Release with these notes attached.
 
 ### Removed
 
@@ -38,7 +965,7 @@ and this project uses [Calendar Versioning](https://calver.org/) in the format
 
 ---
 
-## [2026.W21] - 2026-05-25
+## [2026-05-25]
 
 First weekly release. AIPass now follows a Sunday release cadence: changes
 accumulate on `dev` throughout the week and merge to `main` as a single

CLAUDE.md

@@ -8,10 +8,11 @@ User: user
 
 On any greeting, silently run this sequence — no narration, no announcing steps. Just do it and respond with the status.
 
- - Read: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `README.md`, `STATUS.local.md`
+These steps are sequential and dependent — run each ONCE, wait for the result, then proceed. Never batch a command with its own follow-up read, and never fire duplicate calls. If output looks blank, wait — don't retry.
+
+ - Read: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `README.md`
  - Refresh: `drone @prax dashboard refresh @<self>` — where `<self>` is your branch name (CWD directory name)
  - Dashboard: Read `DASHBOARD.local.json` — act on what needs attention (new mail → check inbox, active plans → note them). This is your single status glance.
- - Refresh: If `STATUS.local.md` is stale (last updated date older than latest session in local.json), update it from your memories. Keep Current Work accurate.
 
 Use drone commands for all operations. Never raw git, gh, file access, or python -m when drone provides it.
 

Dockerfile.test

@@ -1,4 +1,4 @@
-FROM ubuntu:24.04
+FROM ubuntu:24.04@sha256:786a8b558f7be160c6c8c4a54f9a57274f3b4fb1491cf65146521ae77ff1dc54
 
 ENV DEBIAN_FRONTEND=noninteractive
 

README.md

@@ -2,10 +2,11 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/aipass)](https://pypi.org/project/aipass/)
-[![CLI](https://img.shields.io/badge/CLI-Claude%20Code-purple)](#cli-support)
 [![Give Feedback](https://img.shields.io/badge/Give-Feedback-brightgreen)](https://github.com/AIOSAI/AIPass/issues/new?template=feedback.yml)
 [![codecov](https://codecov.io/gh/AIOSAI/AIPass/graph/badge.svg)](https://codecov.io/gh/AIOSAI/AIPass)
-[![OSS Health](https://oss-health-monitor.vercel.app/api/badge/AIOSAI/AIPass)](https://github.com/volotat/OSS-Health-Monitor)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/AIOSAI/AIPass/badge)](https://scorecard.dev/viewer/?uri=github.com/AIOSAI/AIPass)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13095/badge)](https://www.bestpractices.dev/projects/13095)
+[![HVTrust](https://hvtracker.net/badge/aipass.svg)](https://hvtracker.net/agents/aipass)
 
 <p align="center">
   <img src="assets/logo.png" alt="AIPass" width="400" />
@@ -46,7 +47,7 @@ my-project/
 ├── .aipass/                # Project config + prompts
 ├── .claude/                # Hooks (injected automatically)
 ├── src/my_project/
-│   └── my-agent/
+│   └── my_agent/
 │       ├── .trinity/       # Identity + memory (3 JSON files)
 │       ├── .ai_mail.local/ # Local mailbox
 │       ├── apps/           # Your agent's code
@@ -90,7 +91,7 @@ That's it. Your agent has identity, memory, a mailbox, and access to every AIPas
 
 ```bash
 aipass init                           # Just the scaffold (no guided setup)
-aipass init agent my-agent            # Add another agent
+aipass init agent my_agent            # Add another agent
 aipass doctor                         # Check system health
 ```
 
@@ -111,8 +112,8 @@ claude                                # Talk to the orchestrator
 
 ```bash
 # Things you can do:
-aipass doctor                            # Check system health (15+ checks)
-drone @seedgo audit aipass               # Run 36 quality checks across all agents
+aipass doctor                            # Check system health
+drone @seedgo audit aipass               # Run automated quality checks across all agents
 drone @flow create . "Add user auth"     # Create a work plan
 drone @ai_mail dispatch @agent "Sub" "Body"  # Send task + wake an agent
 ```
@@ -140,7 +141,7 @@ drone @branch command [args]    # Every agent, every task. Drone handles routing
 ```
 
 ```bash
-drone @seedgo audit my-project               # Run quality checks on everything
+drone @seedgo audit my_project               # Run quality checks on everything
 drone @flow create . "Refactor auth module"  # Create a work plan
 drone @ai_mail dispatch @agent "Archive old sessions" "Find sessions older than 30 days"
 ```
@@ -160,7 +161,7 @@ AIPass ships with 13 core agents that maintain and develop the framework itself
 devpulse (orchestrator)
    ├── aipass   — concierge + onboarding (aipass init, doctor, profile)
    ├── drone    — command routing + @agent resolution
-   ├── seedgo   — 36 automated quality standards
+   ├── seedgo   — automated quality standards
    ├── prax     — real-time monitoring across all agents
    ├── ai_mail  — agent-to-agent communication + task dispatch
    ├── flow     — plan lifecycle, templates, auto-archival
@@ -194,9 +195,9 @@ These agents work on the **same filesystem, same project, same time** — no san
 
 | Agent | Role |
 |-------|------|
-| [**seedgo**](src/aipass/seedgo/README.md) | 36 automated quality standards, enforced across all agents |
+| [**seedgo**](src/aipass/seedgo/README.md) | Automated quality standards, enforced across all agents |
 | [**prax**](src/aipass/prax/README.md) | Real-time monitoring, logs, dashboards |
-| [**flow**](src/aipass/flow/README.md) | Plan lifecycle — 6 template types, auto-archival, vector verification |
+| [**flow**](src/aipass/flow/README.md) | Plan lifecycle — multiple template types, auto-archival, vector verification |
 | [**hooks**](src/aipass/hooks/README.md) | Hook engine — per-project config, sound control, event dispatch |
 | [**trigger**](src/aipass/trigger/README.md) | Event-driven automation + self-healing |
 | [**cli**](src/aipass/cli/README.md) | Terminal formatting and rich output |
@@ -211,7 +212,7 @@ AIPass is built and tested with **Claude Code** on Linux/WSL.
 
 | CLI | Autonomous Mode | Status |
 |-----|----------------|--------|
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude -p "prompt" --permission-mode bypassPermissions` | Fully tested |
+| [Claude Code](https://code.claude.com/docs) | `claude -p "prompt" --permission-mode bypassPermissions` | Fully tested |
 | [Codex](https://github.com/openai/codex) | `codex exec "prompt" --dangerously-bypass-approvals-and-sandbox` | Experimental |
 
 setup.sh auto-detects which CLIs are installed and configures hooks for each.
@@ -224,11 +225,11 @@ setup.sh auto-detects which CLIs are installed and configures hooks for each.
 
 | Metric | Value |
 |--------|-------|
-| Version | 2.4.0 |
+| Version | [![PyPI](https://img.shields.io/pypi/v/aipass?label=)](https://pypi.org/project/aipass/) |
 | Agents | 13 core + user-created |
-| Quality standards | 36 automated checks |
-| Tests | 8,400+ (across all agents) |
-| PRs merged | 600+ (human-AI collaboration) |
+| Quality | Automated standards enforced across every agent |
+| Coverage | [![codecov](https://codecov.io/gh/AIOSAI/AIPass/graph/badge.svg)](https://codecov.io/gh/AIOSAI/AIPass) — 75% minimum, CI-gated |
+| Tests | Extensive — every agent ships its own suite |
 
 Each agent documents its own operational status in its branch README — what works, what doesn't, and why.
 
@@ -237,7 +238,7 @@ Each agent documents its own operational status in its branch README — what wo
 ## Requirements
 
 - Python 3.10+
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- [Claude Code](https://code.claude.com/docs)
 - Linux, macOS, or WSL (all CI-tested)
 - `sudo` access optional (for `/usr/local/bin` symlinks — falls back to `~/.local/bin` without sudo)
 - API keys optional (OpenRouter/OpenAI — for optional add-on agents)
@@ -263,7 +264,7 @@ AIPass stores everything locally in your project directory. To remove it:
 ```bash
 # Remove AIPass files from your project
 rm -rf .aipass/ .claude/ .ai_mail.local/ hooks/ src/
-rm -f CLAUDE.md AGENTS.md STATUS.local.md *_REGISTRY.json .gitignore
+rm -f CLAUDE.md AGENTS.md *_REGISTRY.json .gitignore
 
 # If you installed via pip
 pip uninstall aipass

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "aipass"
-version = "2.4.0"
+version = "2.6.0"
 description = "A local multi-agent framework where your AI agents keep their memory, work together, and never ask you to re-explain context"
 readme = "README.md"
 license = "MIT"
@@ -28,9 +28,10 @@ classifiers = [
 dependencies = [
     "rich>=13.0",
     "watchdog>=3.0",
-    "requests>=2.28",
+    "requests>=2.34.2",
     "psutil>=5.9",
     "questionary>=2.0",
+    "pathspec>=0.12",
 ]
 
 [project.urls]
@@ -73,7 +74,11 @@ packages = ["src/aipass"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests", "src"]
-norecursedirs = ["templates", "*.egg-info", ".git", ".venv", "__pycache__", ".archive", "my-project"]
+# ".*" restores pytest's default dot-dir exclusion (dropped when this list was
+# customized) so scaffolding dirs (.aipass, .trinity, .seedgo, ...) are never
+# recursed for tests — prevents conftest module-name collisions like a bundled
+# skill's .aipass/.../tests/conftest.py clashing with a branch's tests/conftest.py.
+norecursedirs = ["templates", "*.egg-info", ".*", "__pycache__", "my-project"]
 
 [tool.coverage.run]
 source = ["src/aipass"]

pyrightconfig.json

@@ -1,5 +1,9 @@
 {
-  "extraPaths": ["src", "src/aipass/memory/.venv/lib/python3.12/site-packages"],
+  "extraPaths": [
+    "src",
+    ".venv/lib/python3.12/site-packages",
+    "src/aipass/memory/.venv/lib/python3.12/site-packages"
+  ],
   "pythonVersion": "3.10",
   "reportMissingImports": "error",
   "reportAttributeAccessIssue": "error",

setup.sh

@@ -226,6 +226,92 @@ if [ "$IS_WINDOWS" -eq 1 ]; then
     fi
 fi
 
+# --- Sandbox prerequisites (kernel FS boundary) ---
+echo ""
+echo "Checking sandbox prerequisites ..."
+
+if [ "$IS_WINDOWS" -eq 1 ] || [ "$IS_MACOS" -eq 1 ]; then
+    echo "  kernel sandbox: Linux-only for now, skipping"
+else
+    SB_MISSING=()
+
+    # bwrap
+    if command -v bwrap &>/dev/null; then
+        echo "  bwrap     ... $(bwrap --version 2>/dev/null || echo 'found')"
+    else
+        echo "  bwrap     ... MISSING"
+        echo "    sudo apt install bubblewrap"
+        SB_MISSING+=("bwrap")
+    fi
+
+    # node
+    if command -v node &>/dev/null; then
+        echo "  node      ... $(node --version 2>/dev/null)"
+    else
+        echo "  node      ... MISSING"
+        echo "    Install Node.js: https://nodejs.org/"
+        SB_MISSING+=("node")
+    fi
+
+    # npm (needed for srt install)
+    if command -v npm &>/dev/null; then
+        echo "  npm       ... $(npm --version 2>/dev/null)"
+    else
+        echo "  npm       ... MISSING"
+        SB_MISSING+=("npm")
+    fi
+
+    # @anthropic-ai/sandbox-runtime — resolve same way as _srt_resolve.mjs
+    if command -v node &>/dev/null; then
+        SRT_PATH=$(node -e "
+            const p = require('path');
+            const fs = require('fs');
+            const prefix = p.dirname(p.dirname(process.execPath));
+            const entry = p.join(prefix, 'lib/node_modules/@anthropic-ai/sandbox-runtime/dist/index.js');
+            if (fs.existsSync(entry)) process.stdout.write(entry);
+            else process.exit(1);
+        " 2>/dev/null) || SRT_PATH=""
+        if [ -n "$SRT_PATH" ]; then
+            echo "  srt       ... $SRT_PATH"
+        else
+            echo "  srt       ... MISSING"
+            if command -v npm &>/dev/null; then
+                echo "    Attempting: npm install -g @anthropic-ai/sandbox-runtime"
+                if npm install -g @anthropic-ai/sandbox-runtime 2>/dev/null; then
+                    echo "    srt       ... installed"
+                else
+                    echo "    Install failed (may need sudo). Run manually:"
+                    echo "      sudo npm install -g @anthropic-ai/sandbox-runtime"
+                    SB_MISSING+=("srt")
+                fi
+            else
+                echo "    Install node+npm first, then: npm install -g @anthropic-ai/sandbox-runtime"
+                SB_MISSING+=("srt")
+            fi
+        fi
+    else
+        echo "  srt       ... skipped (no node)"
+        SB_MISSING+=("srt")
+    fi
+
+    # rg (ripgrep)
+    if command -v rg &>/dev/null; then
+        echo "  rg        ... $(rg --version 2>/dev/null | head -1)"
+    elif [ -f "$HOME/.local/bin/rg" ]; then
+        echo "  rg        ... $HOME/.local/bin/rg"
+    else
+        echo "  rg        ... MISSING"
+        echo "    sudo apt install ripgrep"
+        SB_MISSING+=("rg")
+    fi
+
+    if [ ${#SB_MISSING[@]} -eq 0 ]; then
+        echo "  sandbox prereqs: READY"
+    else
+        echo "  sandbox prereqs: INCOMPLETE (${SB_MISSING[*]} missing) — aipass doctor for details"
+    fi
+fi
+
 # --- Verify CLI entry points ---
 FAIL=0
 
@@ -478,12 +564,13 @@ bootstrap_branch "spawn"    "$SCRIPT_DIR/src/aipass/spawn"    "builder" "Branch
 bootstrap_branch "devpulse" "$SCRIPT_DIR/src/aipass/devpulse" "manager" "Orchestration hub and coordination"
 bootstrap_branch "memory"   "$SCRIPT_DIR/src/aipass/memory"   "builder" "Vector memory bank"
 bootstrap_branch "aipass"   "$SCRIPT_DIR/src/aipass/aipass"   "builder" "Concierge — init, doctor, profile, onboarding"
+bootstrap_branch "hooks"    "$SCRIPT_DIR/src/aipass/hooks"    "builder" "Hook engine — cross-platform hook dispatch and per-project config"
 
 # External branches
 # NOTE: backup, daemon removed S82/S87. commons, skills moved to external repos.
-# Only the 12 core branches above should be bootstrapped.
+# Only the 13 core branches above should be bootstrapped.
 
-echo "  12 branches bootstrapped"
+echo "  13 branches bootstrapped"
 
 # --- Seed branch config files from .example defaults ---
 # Some branches need a config file that's gitignored (contains local state).
@@ -539,15 +626,17 @@ else:
     settings = {}
 
 # Build hooks config — bridge pattern
-# UserPromptSubmit: 4 separate entries (EventType:hook_name) to avoid output merging
+# UserPromptSubmit: 5 separate entries (EventType:hook_name) to avoid output merging
 # PreToolUse, PostToolUse, SubagentStop, Stop, Notification: single aggregate entries
-# PreCompact: 2 hooks x 2 matchers (manual + auto) = 4 entries
+# PreCompact: 3 hooks x 2 matchers (manual + auto) = 6 entries
 settings["hooks"] = {
     "UserPromptSubmit": [
-        {"hooks": [{"type": "command", "command": f"{bridge} UserPromptSubmit:global_prompt"}]},
+        {"hooks": [{"type": "command", "command": f"{bridge} UserPromptSubmit:tier0_kernel"}]},
+        {"hooks": [{"type": "command", "command": f"{bridge} UserPromptSubmit:navmap"}]},
         {"hooks": [{"type": "command", "command": f"{bridge} UserPromptSubmit:branch_prompt"}]},
         {"hooks": [{"type": "command", "command": f"{bridge} UserPromptSubmit:identity_injector"}]},
         {"hooks": [{"type": "command", "command": f"{bridge} UserPromptSubmit:email_notification"}]},
+        {"hooks": [{"type": "command", "command": f"{bridge} UserPromptSubmit:auto_process", "timeout": 120}]},
     ],
     "PreToolUse": [
         {"matcher": "Bash|Edit|MultiEdit|Write|Read|Grep|Glob|WebSearch|WebFetch|Task",
@@ -571,6 +660,8 @@ settings["hooks"] = {
         {"matcher": "auto",   "hooks": [{"type": "command", "command": f"{bridge} PreCompact:pre_compact", "timeout": 60}]},
         {"matcher": "manual", "hooks": [{"type": "command", "command": f"{bridge} PreCompact:pre_compact_rollover", "timeout": 120}]},
         {"matcher": "auto",   "hooks": [{"type": "command", "command": f"{bridge} PreCompact:pre_compact_rollover", "timeout": 120}]},
+        {"matcher": "manual", "hooks": [{"type": "command", "command": f"{bridge} PreCompact:auto_process", "timeout": 120}]},
+        {"matcher": "auto",   "hooks": [{"type": "command", "command": f"{bridge} PreCompact:auto_process", "timeout": 120}]},
     ],
 }
 
@@ -605,7 +696,6 @@ git_deny = [
     "Bash(git push -f *)",
     "Bash(git rebase*)",
     "Bash(git clean*)",
-    "Bash(rm -rf*)",
     "Bash(git reset*)",
     "Bash(git merge*)",
     "Bash(git config*)",
@@ -616,7 +706,6 @@ git_deny = [
     "Bash(git branch -D*)",
     "Bash(git stash drop*)",
     "Bash(git stash clear*)",
-    "Bash(rm -r *)",
     "Bash(git checkout -b*)",
     "Bash(git switch -c*)",
     "Bash(git switch --create*)",

src/aipass/__init__.py

@@ -4,4 +4,4 @@ pip install aipass
 https://github.com/AIOSAI/AIPass
 """
 
-__version__ = "2.2.0"
+__version__ = "2.6.0"

src/aipass/ai_mail/.seedgo/bypass.json

@@ -60,11 +60,6 @@
       "standard": "deep_nesting",
       "reason": "2 functions: get_user_by_email() depth 4, get_all_users() depth 4 — registry lookup with path normalization and validation"
     },
-    {
-      "file": "apps/handlers/email/dashboard_sync.py",
-      "standard": "handlers",
-      "reason": "Imports prax.apps.modules.dashboard.write_section — cross-branch module import required for dashboard integration. No ai_mail module wraps this."
-    },
     {
       "file": "apps/handlers/email/delivery.py",
       "standard": "handlers",
@@ -93,7 +88,12 @@
     {
       "file": "apps/handlers/dispatch/dispatch_monitor.py",
       "standard": "handlers",
-      "reason": "Imports notify.send_notification — same-branch cross-handler import for bounce/completion notifications."
+      "reason": "Imports notify.send_notification (same-branch cross-handler) for bounce/completion notifications. Lazy-imports drone.apps.handlers.broker.client.create_identified_connection inside _connect_broker() for Phase 6b broker-fd handshake (FPLAN-0250) — cross-branch handler import authorized by brief."
+    },
+    {
+      "file": "apps/handlers/dispatch/dispatch_monitor.py",
+      "standard": "encapsulation",
+      "reason": "Lazy-imports drone.apps.handlers.broker.client.create_identified_connection inside _connect_broker() — cross-branch handler import for Phase 6b broker-fd handshake (FPLAN-0250). Brief explicitly authorizes this import path."
     },
     {
       "file": "apps/handlers/dispatch/wake.py",
@@ -115,11 +115,6 @@
       "standard": "naming",
       "reason": "False positive — _append_footer is a function reference stored in a local variable, not a module-level constant."
     },
-    {
-      "file": "apps/handlers/email/dashboard_sync.py",
-      "standard": "naming",
-      "reason": "False positive — _write_section is a lazy-import function reference, not a module-level constant."
-    },
     {
       "file": "apps/handlers/email/delivery.py",
       "standard": "naming",
@@ -195,11 +190,6 @@
       "standard": "deep_nesting",
       "reason": "_send_direct() depth 5 (arg parsing with branch resolution, --from flag, --dispatch flag), handle_close() depth 4 (close with archive + dashboard update)"
     },
-    {
-      "file": "apps/handlers/email/dashboard_sync.py",
-      "standard": "deep_nesting",
-      "reason": "_human_readable_age() depth 5, _calculate_section_data() depth 5 — timestamp parsing with multiple fallback formats"
-    },
     {
       "file": "apps/handlers/dispatch/dispatch_monitor.py",
       "standard": "deep_nesting",

src/aipass/ai_mail/apps/handlers/dispatch/dispatch_monitor.py

@@ -23,6 +23,8 @@ is guaranteed.
 
 import json
 import os
+import shlex
+import socket
 import sys
 import subprocess
 import time
@@ -41,6 +43,43 @@ HARD_TIMEOUT = 7200  # 2 hours
 POLL_INTERVAL = 5
 
 
+def _is_sandbox_enabled() -> bool:
+    """Check if dispatch sandbox is enabled via AIPASS_SANDBOX_ENABLED env var."""
+    return os.environ.get("AIPASS_SANDBOX_ENABLED", "").lower() in ("1", "true", "yes")
+
+
+def _wrap_for_sandbox(cmd: list, branch_path: Path) -> list:
+    """Wrap a claude command in the srt kernel sandbox.
+
+    Uses @hooks sandbox building blocks to resolve the bwrap command,
+    then returns a shell invocation list compatible with Popen.
+
+    Raises on ANY failure — caller must not silently fall back to unsandboxed.
+    """
+    from aipass.hooks.apps.modules.sandbox import build_policy, build_srt_config, resolve_bwrap_command
+
+    policy = build_policy(branch_path)
+    srt_config = build_srt_config(policy)
+    cmd_str = shlex.join(cmd)
+    bwrap_cmd = resolve_bwrap_command(cmd_str, srt_config)
+    return ["/bin/bash", "-c", bwrap_cmd]
+
+
+def _connect_broker(repo_root: Path, branch_name: str) -> socket.socket:
+    """Create an identified broker connection for the target branch.
+
+    Returns a connected, HMAC-authenticated socket ready to be inherited
+    by the sandboxed child via pass_fds + AIPASS_BROKER_FD.
+
+    Raises on ANY failure — caller must not silently skip the broker.
+    """
+    from aipass.drone.apps.handlers.broker.client import create_identified_connection
+
+    socket_path = repo_root / ".ai_central" / "drone_broker.sock"
+    secret_path = repo_root / ".ai_central" / "broker_secret"
+    return create_identified_connection(socket_path, secret_path, branch_name)
+
+
 def _send_bounce(branch_email: str, reason: str, sender: str, lock_file: str, stderr_log: str) -> bool:
     """Send return-to-sender bounce email via drone."""
     subject = f"BOUNCE: Dispatch to {branch_email} failed"
@@ -95,16 +134,27 @@ def _send_bounce(branch_email: str, reason: str, sender: str, lock_file: str, st
         return False
 
 
-def _check_rate_limited(stderr_log: str) -> bool:
-    """Check if stderr indicates API rate limiting or overload."""
+def _read_agent_stderr(stderr_log: str) -> str:
+    """Read the dispatch stderr log, excluding the monitor's own framing lines.
+
+    The monitor writes header/footer/attempt markers (all prefixed with "--- ")
+    that embed the PID and timestamps. Those numbers must NOT be scanned for API
+    error markers -- e.g. a PID like 14290 contains "429" and would otherwise be
+    misread as an HTTP 429 rate-limit. Returns "" if the log can't be read.
+    """
     try:
         with open(stderr_log, "r", encoding="utf-8") as f:
-            content = f.read()
-        lower = content.lower()
-        return "rate_limit" in lower or "429" in content or "overloaded" in lower or "529" in content
+            return "".join(line for line in f if not line.lstrip().startswith("---"))
     except OSError as e:
-        logger.warning("[monitor] _check_rate_limited failed reading %s: %s", stderr_log, e)
-        return False
+        logger.warning("[monitor] Failed reading stderr log %s: %s", stderr_log, e)
+        return ""
+
+
+def _check_rate_limited(stderr_log: str) -> bool:
+    """Check if stderr indicates API rate limiting or overload."""
+    content = _read_agent_stderr(stderr_log)
+    lower = content.lower()
+    return "rate_limit" in lower or "429" in content or "overloaded" in lower or "529" in content
 
 
 def _make_fresh_cmd(claude_cmd: list) -> list:
@@ -176,7 +226,7 @@ def _kill_process(process: subprocess.Popen, branch_email: str):
 
 
 def _run_with_startup_check(
-    claude_cmd: list, stdout_log: str, stderr_fh, cwd: str, spawn_env: dict, branch_email: str
+    claude_cmd: list, stdout_log: str, stderr_fh, cwd: str, spawn_env: dict, branch_email: str, pass_fds: tuple = ()
 ) -> tuple:
     """
     Run claude with startup timeout check.
@@ -194,13 +244,16 @@ def _run_with_startup_check(
         logger.warning("[monitor] Failed to open stdout log %s: %s", stdout_log, e)
 
     try:
-        process = subprocess.Popen(
-            claude_cmd,
-            stdout=stdout_fh if stdout_fh is not None else subprocess.DEVNULL,
-            stderr=stderr_fh,
-            cwd=cwd,
-            env=spawn_env,
-        )
+        popen_kwargs = {
+            "stdout": stdout_fh if stdout_fh is not None else subprocess.DEVNULL,
+            "stderr": stderr_fh,
+            "cwd": cwd,
+            "env": spawn_env,
+        }
+        if pass_fds:
+            popen_kwargs["close_fds"] = True
+            popen_kwargs["pass_fds"] = pass_fds
+        process = subprocess.Popen(claude_cmd, **popen_kwargs)
     except Exception as e:
         logger.warning("[monitor] Failed to spawn %s: %s", branch_email, e)
         if stdout_fh is not None:
@@ -338,6 +391,11 @@ def main():
 
     start_time = time.time()
 
+    # ─── Sandbox Gate ─────────────────────────────────────
+    sandbox_enabled = _is_sandbox_enabled()
+    if sandbox_enabled:
+        logger.info("[monitor] Sandbox ENABLED for %s", branch_email)
+
     # ─── Retry Loop: 3 Strikes ─────────────────────────────
     # Strike 1: original command (resume if -c was passed)
     # Strike 2: same command again (transient failure)
@@ -356,14 +414,60 @@ def main():
             cmd = claude_cmd
             mode = "resume" if has_resume else "fresh"
 
+        # Sandbox wrap + broker fd: when enabled, wrap cmd and connect broker.
+        # On failure: abort — NEVER silently launch unsandboxed.
+        run_cmd = cmd
+        broker_sock = None
+        attempt_pass_fds: tuple = ()
+        if sandbox_enabled:
+            try:
+                run_cmd = _wrap_for_sandbox(cmd, branch_path)
+            except Exception as e:
+                logger.error(
+                    "[monitor] Sandbox init FAILED for %s: %s — ABORTING (will NOT launch unsandboxed)",
+                    branch_email,
+                    e,
+                )
+                exit_code = -4
+                attempts.append({"attempt": attempt, "exit_code": exit_code, "startup_failed": False, "mode": mode})
+                break
+
+            try:
+                broker_sock = _connect_broker(_repo_root, branch_email.lstrip("@"))
+                broker_fd = broker_sock.fileno()
+                spawn_env["AIPASS_BROKER_FD"] = str(broker_fd)
+                attempt_pass_fds = (broker_fd,)
+                logger.info("[monitor] Broker fd %d connected for %s", broker_fd, branch_email)
+            except Exception as e:
+                logger.error(
+                    "[monitor] Broker connect FAILED for %s: %s — ABORTING",
+                    branch_email,
+                    e,
+                )
+                exit_code = -4
+                attempts.append({"attempt": attempt, "exit_code": exit_code, "startup_failed": False, "mode": mode})
+                break
+
         if stderr_fh is not None:
             stderr_fh.write(f"\n--- Attempt {attempt}/3 ({mode}) at {time.strftime('%H:%M:%S')} ---\n")
             stderr_fh.flush()
 
         exit_code, startup_failed = _run_with_startup_check(
-            cmd, stdout_log, stderr_fh if stderr_fh is not None else subprocess.DEVNULL, cwd, spawn_env, branch_email
+            run_cmd,
+            stdout_log,
+            stderr_fh if stderr_fh is not None else subprocess.DEVNULL,
+            cwd,
+            spawn_env,
+            branch_email,
+            pass_fds=attempt_pass_fds,
         )
 
+        # Close parent's broker socket copy — child owns the fd now.
+        if broker_sock is not None:
+            broker_sock.close()
+            broker_sock = None
+            spawn_env.pop("AIPASS_BROKER_FD", None)
+
         attempts.append({"attempt": attempt, "exit_code": exit_code, "startup_failed": startup_failed, "mode": mode})
 
         # Success — done
@@ -434,16 +538,14 @@ def main():
 
         reason = f"All {len(attempts)} attempts failed after {duration}s.\n" + "\n".join(attempt_details)
 
-        # Check stderr for specific error categories
-        try:
-            with open(stderr_log, "r", encoding="utf-8") as f:
-                content = f.read()
-            if "rate_limit" in content.lower() or "429" in content:
-                reason = f"API rate limit (all {len(attempts)} attempts failed, {duration}s)"
-            elif "overloaded" in content.lower() or "529" in content:
-                reason = f"API overloaded (all {len(attempts)} attempts failed, {duration}s)"
-        except OSError:
-            logger.info("[monitor] Failed to read stderr log for diagnostics")
+        # Check stderr for specific error categories. Exclude the monitor's own
+        # framing lines (PID/timestamp headers) so a number like a PID containing
+        # "429" is not misread as an HTTP 429 rate-limit response.
+        content = _read_agent_stderr(stderr_log)
+        if "rate_limit" in content.lower() or "429" in content:
+            reason = f"API rate limit (all {len(attempts)} attempts failed, {duration}s)"
+        elif "overloaded" in content.lower() or "529" in content:
+            reason = f"API overloaded (all {len(attempts)} attempts failed, {duration}s)"
 
         _send_bounce(branch_email, reason, sender, lock_file, stderr_log)
 

src/aipass/ai_mail/apps/handlers/email/close_ops.py

@@ -56,24 +56,17 @@ def batch_close(
 
 def batch_close_post_ops(
     branch_path: Path,
-    push_dashboard_fn: Optional[Callable] = None,
     update_central_fn: Optional[Callable] = None,
     purge_deleted_fn: Optional[Callable] = None,
 ) -> None:
     """
-    Run post-operations after a batch close (dashboard update + purge).
+    Run post-operations after a batch close (central update + purge).
 
     Args:
         branch_path: Path to branch directory
-        push_dashboard_fn: Optional push_dashboard_update callable
         update_central_fn: Optional update_central callable
         purge_deleted_fn: Optional purge_deleted_folder callable
     """
-    if push_dashboard_fn:
-        try:
-            push_dashboard_fn(branch_path)
-        except Exception as e:
-            logger.warning("[close] push_dashboard_fn failed for %s: %s", branch_path, e)
     if update_central_fn:
         try:
             update_central_fn()

src/aipass/ai_mail/apps/handlers/email/delivery.py

@@ -165,7 +165,7 @@ def _is_private_branch_email(email: str) -> bool:
     email address is registered to a private (isolated) branch.
 
     Args:
-        email: Email address to check (e.g., "@patrick_private")
+        email: Email address to check (e.g., "@private_branch")
 
     Returns:
         True if email belongs to a private branch, False otherwise

src/aipass/ai_mail/apps/handlers/email/error_dispatch.py

@@ -93,25 +93,18 @@ def on_email_delivered(
     new_count: int,
     opened_count: int,
     total: int,
-    push_dashboard_fn: Optional[Callable] = None,
     update_central_fn: Optional[Callable] = None,
 ) -> None:
     """
-    Post-delivery callback: update dashboard and central.
+    Post-delivery callback: update central.
 
     Args:
         branch_path: Path to the branch that received email
         new_count: Number of new (unread) messages
         opened_count: Number of opened messages
         total: Total message count
-        push_dashboard_fn: Callable for push_dashboard_update
         update_central_fn: Callable for update_central
     """
-    if push_dashboard_fn:
-        try:
-            push_dashboard_fn(branch_path)
-        except Exception as e:
-            logger.warning("[error_dispatch] dashboard update failed for %s: %s", branch_path, e)
     if update_central_fn:
         try:
             update_central_fn()

src/aipass/ai_mail/apps/handlers/email/footer.py

@@ -22,7 +22,6 @@ STANDARD_FOOTER = """
 ⚠️ TASK CHECKLIST (before marking complete):
 □ SEEDGO CHECK → drone @seedgo audit @branch (80%+)
 □ UPDATE MEMORIES → Your .trinity/local.json records this work
-□ UPDATE STATUS → Your STATUS.local.md reflects current state
 □ CLOSE FPLAN → drone @flow close <plan_id>
 □ EMAIL SENDER → drone @ai_mail email @<sender> "Subject" "Summary"
 

src/aipass/ai_mail/apps/handlers/email/inbox_cleanup.py

@@ -38,13 +38,6 @@ def _get_inbox_lock():
     return _inbox_lock
 
 
-def _get_push_dashboard_update() -> Any:
-    """Lazy import push_dashboard_update from dashboard_sync."""
-    from aipass.ai_mail.apps.handlers.email.dashboard_sync import push_dashboard_update
-
-    return push_dashboard_update
-
-
 def _get_update_central() -> Any:
     """Lazy import update_central."""
     from aipass.ai_mail.apps.handlers.central_writer import update_central
@@ -191,13 +184,7 @@ def mark_all_read_and_archive(branch_path: Path) -> Tuple[bool, str, int]:
 
 
 def _update_dashboard(branch_path: Path, new: int, opened: int, total: int) -> None:
-    """Update dashboard ai_mail section with enriched data via write-through API."""
-    try:
-        _get_push_dashboard_update()(branch_path)
-    except Exception as e:
-        logger.warning("[cleanup] dashboard update failed for %s: %s", branch_path, e)
-
-    # Update central after any inbox changes
+    """Update central stats after inbox changes."""
     try:
         _get_update_central()()
     except Exception as e:

src/aipass/ai_mail/apps/handlers/email/send_args.py

@@ -103,7 +103,7 @@ def parse_send_args(args: List[str]) -> Dict[str, Any]:
     if recipients and len(rest) >= 2:
         mode = "direct"
         subject = rest[0]
-        message = rest[1]
+        message = " ".join(rest[1:])
     elif not recipients and not rest:
         mode = "interactive"
         subject = None

src/aipass/ai_mail/apps/modules/dispatch.py

@@ -267,7 +267,6 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
     from aipass.ai_mail.apps.handlers.email.delivery import deliver_email_to_branch
     from aipass.ai_mail.apps.handlers.email.header import prepend_dispatch_header
     from aipass.ai_mail.apps.handlers.email.error_dispatch import dispatch_send_error, on_email_delivered
-    from aipass.ai_mail.apps.handlers.email.dashboard_sync import push_dashboard_update
     from aipass.ai_mail.apps.handlers.users.user import get_current_user
     from aipass.ai_mail.apps.handlers.registry.read import get_branch_by_email
 
@@ -286,7 +285,6 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
             new_count,
             opened_count,
             total,
-            push_dashboard_fn=push_dashboard_update,
             update_central_fn=update_central,
         )
 
@@ -408,23 +406,26 @@ def _orchestrate_daemon() -> bool:
 def print_introspection():
     """Display module introspection info."""
     console.print()
-    console.print("dispatch Module")
+    console.print("[bold cyan]dispatch Module[/bold cyan]")
     console.print(
-        "Orchestrates dispatch commands: combined send+wake, status tracking, daemon management, and manual wake."
+        "[dim]Orchestrates dispatch commands: combined send+wake,"
+        " status tracking, daemon management, and manual wake.[/dim]"
     )
     console.print()
-    console.print("Connected Handlers:")
-    console.print("  handlers/dispatch/")
-    console.print("    - status.py (load_dispatch_log — load dispatch log entries)")
-    console.print("    - status.py (check_pid_status — check if a spawned process is still running)")
-    console.print("    - status.py (calculate_age — calculate age string from timestamp)")
-    console.print("    - wake.py (wake_branch — manually wake a branch by spawning an agent)")
-    console.print("    - daemon.py (run_daemon — start the continuous dispatch daemon)")
-    console.print("  handlers/email/ (used by combined dispatch)")
-    console.print("    - send.py (resolve_sender_info, send_to_single — send email pipeline)")
-    console.print("    - create.py (create_email_file, load_email_file — email file creation)")
-    console.print("    - delivery.py (deliver_email_to_branch — inbox delivery)")
-    console.print("    - header.py (prepend_dispatch_header — dispatch header injection)")
+    console.print("[yellow]Connected Handlers:[/yellow]")
+    console.print("  [cyan]handlers/dispatch/[/cyan]")
+    console.print("    - [cyan]status.py[/cyan] [dim](load_dispatch_log — load dispatch log entries)[/dim]")
+    console.print(
+        "    - [cyan]status.py[/cyan] [dim](check_pid_status — check if a spawned process is still running)[/dim]"
+    )
+    console.print("    - [cyan]status.py[/cyan] [dim](calculate_age — calculate age string from timestamp)[/dim]")
+    console.print("    - [cyan]wake.py[/cyan] [dim](wake_branch — manually wake a branch by spawning an agent)[/dim]")
+    console.print("    - [cyan]daemon.py[/cyan] [dim](run_daemon — start the continuous dispatch daemon)[/dim]")
+    console.print("  [cyan]handlers/email/[/cyan] [dim](used by combined dispatch)[/dim]")
+    console.print("    - [cyan]send.py[/cyan] [dim](resolve_sender_info, send_to_single — send email pipeline)[/dim]")
+    console.print("    - [cyan]create.py[/cyan] [dim](create_email_file, load_email_file — email file creation)[/dim]")
+    console.print("    - [cyan]delivery.py[/cyan] [dim](deliver_email_to_branch — inbox delivery)[/dim]")
+    console.print("    - [cyan]header.py[/cyan] [dim](prepend_dispatch_header — dispatch header injection)[/dim]")
     console.print()
 
 

src/aipass/ai_mail/apps/modules/email.py

@@ -23,15 +23,8 @@ import sys
 from pathlib import Path
 from typing import List
 
-# Infrastructure
-_AI_MAIL_DIR = Path(__file__).resolve().parents[2]
-_REPO_ROOT = _AI_MAIL_DIR.parents[2]
-
 from aipass.prax import logger
 from aipass.cli.apps.modules import console, error
-
-# Handlers - business logic providers
-from aipass.ai_mail.apps.handlers.email.dashboard_sync import push_dashboard_update
 from aipass.ai_mail.apps.handlers.email.create import load_email_file
 from aipass.ai_mail.apps.handlers.email.format import format_email_list_item, format_email_header
 from aipass.ai_mail.apps.handlers.email.inbox_ops import load_inbox
@@ -48,6 +41,9 @@ from aipass.ai_mail.apps.handlers.email.close_ops import batch_close, batch_clos
 from aipass.ai_mail.apps.handlers.email.inbox_resolve import resolve_inbox_target
 from aipass.ai_mail.apps.modules.email_send import handle_send
 
+_AI_MAIL_DIR = Path(__file__).resolve().parents[2]
+_REPO_ROOT = _AI_MAIL_DIR.parents[2]
+
 try:
     from aipass.ai_mail.apps.handlers.central_writer import update_central
 except ImportError as e:
@@ -255,7 +251,7 @@ def handle_close(args: List[str]) -> bool:
             except ImportError as e:
                 logger.warning("[email] purge import unavailable: %s", e)
                 run_purge = None
-            batch_close_post_ops(branch_path, push_dashboard_update, update_central, run_purge)
+            batch_close_post_ops(branch_path, update_central, run_purge)
             console.print(f"\nClosed {closed}, failed {failed}")
         return True
     except Exception as e:
@@ -277,7 +273,8 @@ def handle_reply(args: List[str]) -> bool:
         if not original:
             error(f"Message not found: {args[0]}")
             return True
-        success, message, reply_id = send_reply(branch_path, original, args[1])
+        reply_message = " ".join(args[1:])
+        success, message, reply_id = send_reply(branch_path, original, reply_message)
         if success:
             console.print(f"[green]{message}[/green]")
         else:
@@ -386,7 +383,6 @@ def print_introspection():
     console.print("    - reply.py (get_email_by_id — retrieve email by message ID)")
     console.print("    - reply.py (send_reply — send reply to an email)")
     console.print("    - header.py (prepend_dispatch_header — prepend dispatch header to message)")
-    console.print("    - dashboard_sync.py (push_dashboard_update — push email stats to dashboard)")
     console.print("    - error_dispatch.py (dispatch_send_error — handle and report send errors)")
     console.print("    - error_dispatch.py (on_email_delivered — post-delivery callback handler)")
     console.print("  handlers/users/")

src/aipass/ai_mail/apps/modules/email_send.py

@@ -17,14 +17,10 @@ under the size threshold.
 from pathlib import Path
 from typing import List
 
-_AI_MAIL_DIR = Path(__file__).resolve().parents[2]
-_REPO_ROOT = _AI_MAIL_DIR.parents[2]
-
 from aipass.prax import logger
 from aipass.cli.apps.modules import console, error
 from aipass.trigger.apps.modules.core import trigger
 
-from aipass.ai_mail.apps.handlers.email.dashboard_sync import push_dashboard_update
 from aipass.ai_mail.apps.handlers.email.delivery import deliver_email_to_branch
 from aipass.ai_mail.apps.handlers.email.create import create_email_file, load_email_file
 from aipass.ai_mail.apps.handlers.email.header import prepend_dispatch_header
@@ -40,6 +36,9 @@ from aipass.ai_mail.apps.handlers.email.send import (
 from aipass.ai_mail.apps.handlers.email.error_dispatch import dispatch_send_error, on_email_delivered
 from aipass.ai_mail.apps.handlers.email.send_args import parse_send_args, resolve_dispatch_target
 
+_AI_MAIL_DIR = Path(__file__).resolve().parents[2]
+_REPO_ROOT = _AI_MAIL_DIR.parents[2]
+
 try:
     from aipass.ai_mail.apps.handlers.central_writer import update_central
 except ImportError as e:
@@ -54,7 +53,6 @@ def _delivery_callback(branch_path, new_count, opened_count, total):
         new_count,
         opened_count,
         total,
-        push_dashboard_fn=push_dashboard_update,
         update_central_fn=update_central,
     )
 
@@ -250,18 +248,18 @@ def _send_broadcast(subject, message, user_info, auto_execute, no_memory_save, r
 
 def print_introspection():
     """Print module introspection for seedgo compliance."""
-    console.print("\n" + "=" * 70)
-    console.print("EMAIL SEND ORCHESTRATION")
-    console.print("=" * 70)
-    console.print("\nFunctions provided:")
-    console.print("  - handle_send(args) -> bool")
-    console.print("  - _send_direct(...) -> bool")
-    console.print("  - _send_interactive() -> bool")
-    console.print("  - _send_broadcast(...) -> bool")
-    console.print("  - _fire_dispatch_trigger(to_branch, subject) -> None")
-    console.print("  - _delivery_callback(branch_path, new_count, opened_count, total)")
     console.print()
-    console.print("=" * 70 + "\n")
+    console.print("[bold cyan]email_send Module[/bold cyan]")
+    console.print("[dim]Send orchestration — direct, interactive, and broadcast email delivery.[/dim]")
+    console.print()
+    console.print("[yellow]Functions provided:[/yellow]")
+    console.print("  - [cyan]handle_send[/cyan][dim](args) -> bool[/dim]")
+    console.print("  - [cyan]_send_direct[/cyan][dim](...) -> bool[/dim]")
+    console.print("  - [cyan]_send_interactive[/cyan][dim]() -> bool[/dim]")
+    console.print("  - [cyan]_send_broadcast[/cyan][dim](...) -> bool[/dim]")
+    console.print("  - [cyan]_fire_dispatch_trigger[/cyan][dim](to_branch, subject) -> None[/dim]")
+    console.print("  - [cyan]_delivery_callback[/cyan][dim](branch_path, new_count, opened_count, total)[/dim]")
+    console.print()
 
 
 if __name__ == "__main__":

src/aipass/ai_mail/docs/s84_multiline_reply_truncation.md

@@ -0,0 +1,47 @@
+# S84: Multi-line Reply Body Truncation — Root Cause & Fix
+
+## Bug
+
+Reply and send commands silently truncate multi-line message bodies to the first argument.
+
+**Reported:** @devpulse dispatch 7b6a70b9 (2026-06-08)
+**Evidence:** @hooks sent two replies with full multi-line bodies; both arrived in devpulse inbox as first line only (60 chars / 48 chars). @memory's reply arrived intact (951 chars).
+
+## Root Cause
+
+Two code paths only captured the second positional CLI argument as the message body, dropping everything after it:
+
+1. **`email.py:handle_reply`** (line 280):
+   ```python
+   send_reply(branch_path, original, args[1])  # args[2:] silently dropped
+   ```
+
+2. **`send_args.py:parse_send_args`** (line 106):
+   ```python
+   message = rest[1]  # rest[2:] silently dropped
+   ```
+
+When an agent's bash command produces multiple args from a message body (shell word-splitting on unquoted text, or subprocess argument handling), only the first segment survives. The rest is discarded with no warning.
+
+The entire Python delivery pipeline (reply.py, delivery.py, create.py) handles multi-line strings correctly — the truncation happens at the CLI argument boundary.
+
+## Why @memory Worked
+
+@memory's reply body was a single properly-quoted argument that arrived as one `args[1]` entry. @hooks' body was split into multiple args (likely unquoted or shell-expanded), so only the first piece reached `send_reply()`.
+
+## Fix
+
+Both locations now join all remaining args:
+
+1. **`email.py:handle_reply`**: `reply_message = " ".join(args[1:])`
+2. **`send_args.py:parse_send_args`**: `message = " ".join(rest[1:])`
+
+Backwards-compatible: single-arg messages pass through unchanged. Multi-arg messages are reconstructed.
+
+## Tests Added (6)
+
+- `test_reply.py`: `test_send_reply_multiline_body_preserved` — multi-line body stored intact in delivery and sent copy
+- `test_email_module.py`: `TestHandleReplyMultiArg` — handle_reply joins split args; single arg unchanged
+- `test_send_helpers.py`: 3 tests — parse_send_args joins split message; single arg unchanged; embedded newlines preserved
+
+718 tests pass (712 + 6 new).

src/aipass/ai_mail/tests/test_close_ops.py

@@ -120,13 +120,11 @@ def test_batch_close_post_ops_all_fns_called(tmp_path: Path):
     branch_path = tmp_path / "branch"
     branch_path.mkdir()
 
-    push_fn = MagicMock()
     central_fn = MagicMock()
     purge_fn = MagicMock()
 
-    mod.batch_close_post_ops(branch_path, push_fn, central_fn, purge_fn)
+    mod.batch_close_post_ops(branch_path, central_fn, purge_fn)
 
-    push_fn.assert_called_once_with(branch_path)
     central_fn.assert_called_once_with()
     purge_fn.assert_called_once_with(branch_path / ".ai_mail.local")
 
@@ -137,22 +135,7 @@ def test_batch_close_post_ops_none_fns(tmp_path: Path):
     branch_path.mkdir()
 
     # Should not raise
-    mod.batch_close_post_ops(branch_path, None, None, None)
-
-
-def test_batch_close_post_ops_push_exception_suppressed(tmp_path: Path):
-    """Exception in push_dashboard_fn is caught; other fns still called."""
-    branch_path = tmp_path / "branch"
-    branch_path.mkdir()
-
-    push_fn = MagicMock(side_effect=RuntimeError("push failed"))
-    central_fn = MagicMock()
-    purge_fn = MagicMock()
-
-    mod.batch_close_post_ops(branch_path, push_fn, central_fn, purge_fn)
-
-    central_fn.assert_called_once()
-    purge_fn.assert_called_once()
+    mod.batch_close_post_ops(branch_path, None, None)
 
 
 def test_batch_close_post_ops_central_exception_suppressed(tmp_path: Path):
@@ -160,13 +143,11 @@ def test_batch_close_post_ops_central_exception_suppressed(tmp_path: Path):
     branch_path = tmp_path / "branch"
     branch_path.mkdir()
 
-    push_fn = MagicMock()
     central_fn = MagicMock(side_effect=RuntimeError("central failed"))
     purge_fn = MagicMock()
 
-    mod.batch_close_post_ops(branch_path, push_fn, central_fn, purge_fn)
+    mod.batch_close_post_ops(branch_path, central_fn, purge_fn)
 
-    push_fn.assert_called_once()
     purge_fn.assert_called_once()
 
 
@@ -175,13 +156,11 @@ def test_batch_close_post_ops_purge_exception_suppressed(tmp_path: Path):
     branch_path = tmp_path / "branch"
     branch_path.mkdir()
 
-    push_fn = MagicMock()
     central_fn = MagicMock()
     purge_fn = MagicMock(side_effect=RuntimeError("purge failed"))
 
-    mod.batch_close_post_ops(branch_path, push_fn, central_fn, purge_fn)
+    mod.batch_close_post_ops(branch_path, central_fn, purge_fn)
 
-    push_fn.assert_called_once()
     central_fn.assert_called_once()
 
 
@@ -192,6 +171,6 @@ def test_batch_close_post_ops_partial_fns(tmp_path: Path):
 
     central_fn = MagicMock()
 
-    mod.batch_close_post_ops(branch_path, None, central_fn, None)
+    mod.batch_close_post_ops(branch_path, central_fn, None)
 
     central_fn.assert_called_once_with()

src/aipass/ai_mail/tests/test_dispatch_module.py

@@ -47,7 +47,6 @@ _H_CREATE = "aipass.ai_mail.apps.handlers.email.create"
 _H_DELIVERY = "aipass.ai_mail.apps.handlers.email.delivery"
 _H_HEADER = "aipass.ai_mail.apps.handlers.email.header"
 _H_ERR = "aipass.ai_mail.apps.handlers.email.error_dispatch"
-_H_DASH = "aipass.ai_mail.apps.handlers.email.dashboard_sync"
 _H_USERS = "aipass.ai_mail.apps.handlers.users.user"
 _H_REG = "aipass.ai_mail.apps.handlers.registry.read"
 _H_CENTRAL = "aipass.ai_mail.apps.handlers.central_writer"
@@ -658,7 +657,6 @@ def _send_patches(overrides: dict | None = None) -> ExitStack:
         f"{_H_HEADER}.prepend_dispatch_header": MagicMock(return_value="[DISPATCH] Body"),
         f"{_H_SEND}.send_to_single": MagicMock(return_value=(True, None)),
         f"{_H_ERR}.on_email_delivered": MagicMock(),
-        f"{_H_DASH}.push_dashboard_update": MagicMock(),
         f"{_H_USERS}.get_current_user": MagicMock(return_value={"name": "test"}),
         f"{_H_REG}.get_branch_by_email": MagicMock(return_value={"email": "@target"}),
         f"{_H_CENTRAL}.update_central": MagicMock(),

src/aipass/ai_mail/tests/test_dispatch_monitor.py

@@ -9,7 +9,9 @@
 """Tests for dispatch_monitor -- startup check, retry loop, bounce, rate limiting."""
 
 import json
+import os
 import subprocess
+import sys
 import time
 import pytest
 from pathlib import Path
@@ -20,11 +22,13 @@ from aipass.ai_mail.apps.handlers.dispatch.dispatch_monitor import (
     _check_jsonl_activity,
     _check_rate_limited,
     _get_jsonl_projects_dir,
+    _is_sandbox_enabled,
     _kill_process,
     _make_fresh_cmd,
     _run_with_startup_check,
     _send_bounce,
     _snapshot_jsonl_sizes,
+    _wrap_for_sandbox,
     main,
 )
 
@@ -634,7 +638,7 @@ def test_max_turns_changes_notification_status(monkeypatch, main_argv):
     stdout_log = Path(str(lock_file)).parent.parent / "logs" / "dispatch_stdout.log"
     stdout_log.parent.mkdir(parents=True, exist_ok=True)
 
-    def fake_run(cmd, stdout_log_path, stderr_fh, cwd, env, branch):
+    def fake_run(cmd, stdout_log_path, stderr_fh, cwd, env, branch, **kwargs):
         # Simulate writing max_turns output
         stdout_log.write_text('{"stop_reason":"max_turns"}', encoding="utf-8")
         return (0, False)
@@ -810,7 +814,7 @@ def test_env_vars_set_correctly(monkeypatch, main_argv):
 
     captured_env = {}
 
-    def capture_run(cmd, stdout_log, stderr_fh, cwd, env, branch):
+    def capture_run(cmd, stdout_log, stderr_fh, cwd, env, branch, **kwargs):
         captured_env.update(env)
         return (0, False)
 
@@ -900,7 +904,7 @@ def test_main_max_turns_detected(monkeypatch, main_argv):
     stdout_log = branch_dir / "logs" / "dispatch_stdout.log"
     stdout_log.parent.mkdir(parents=True, exist_ok=True)
 
-    def fake_run(cmd, stdout_log_path, stderr_fh, cwd, env, branch):
+    def fake_run(cmd, stdout_log_path, stderr_fh, cwd, env, branch, **kwargs):
         # Write max_turns stop_reason into stdout log
         Path(stdout_log_path).write_text('{"stop_reason":"max_turns"}', encoding="utf-8")
         return (0, False)
@@ -1075,7 +1079,7 @@ def test_env_vars_setup(monkeypatch, main_argv):
 
     captured_env = {}
 
-    def capture_run(cmd, stdout_log, stderr_fh, cwd, env, branch):
+    def capture_run(cmd, stdout_log, stderr_fh, cwd, env, branch, **kwargs):
         captured_env.update(env)
         return (0, False)
 
@@ -1194,3 +1198,626 @@ def test_check_jsonl_activity_no_change(tmp_path):
 def test_check_jsonl_activity_missing_dir(tmp_path):
     """Nonexistent directory -> False."""
     assert _check_jsonl_activity(tmp_path / "nope", {}) is False
+
+
+# --- Sandbox gate tests (Phase 4 FPLAN-0250) --------------------------------
+
+
+class TestIsSandboxEnabled:
+    """_is_sandbox_enabled reads AIPASS_SANDBOX_ENABLED from env."""
+
+    def test_unset_returns_false(self, monkeypatch):
+        monkeypatch.delenv("AIPASS_SANDBOX_ENABLED", raising=False)
+        assert _is_sandbox_enabled() is False
+
+    def test_empty_returns_false(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "")
+        assert _is_sandbox_enabled() is False
+
+    def test_false_string_returns_false(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "false")
+        assert _is_sandbox_enabled() is False
+
+    def test_zero_returns_false(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "0")
+        assert _is_sandbox_enabled() is False
+
+    def test_one_returns_true(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+        assert _is_sandbox_enabled() is True
+
+    def test_true_returns_true(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "true")
+        assert _is_sandbox_enabled() is True
+
+    def test_yes_returns_true(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "yes")
+        assert _is_sandbox_enabled() is True
+
+    def test_TRUE_case_insensitive(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "TRUE")
+        assert _is_sandbox_enabled() is True
+
+
+class TestFlagOffOldPath:
+    """Flag OFF (default): dispatch uses the original cmd, no sandbox wrapping."""
+
+    def test_flag_off_cmd_unchanged(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.delenv("AIPASS_SANDBOX_ENABLED", raising=False)
+
+        captured_cmds = []
+
+        def capture_run(cmd, *args, **kwargs):
+            captured_cmds.append(cmd)
+            return (0, False)
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+
+        assert exc_info.value.code == 0
+        assert len(captured_cmds) == 1
+        assert captured_cmds[0] == ["claude", "-c", "--model", "opus"]
+
+    def test_flag_off_wrap_never_called(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.delenv("AIPASS_SANDBOX_ENABLED", raising=False)
+
+        wrap_calls = []
+        original_wrap = mod._wrap_for_sandbox
+
+        def tracking_wrap(*args, **kwargs):
+            wrap_calls.append(args)
+            return original_wrap(*args, **kwargs)
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_wrap_for_sandbox", tracking_wrap)
+        monkeypatch.setattr(mod, "_run_with_startup_check", MagicMock(return_value=(0, False)))
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        assert wrap_calls == []
+
+
+class TestFlagOnSandboxPath:
+    """Flag ON: dispatch wraps cmd via _wrap_for_sandbox."""
+
+    def test_flag_on_cmd_wrapped(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        captured_cmds = []
+
+        def capture_run(cmd, *args, **kwargs):
+            captured_cmds.append(cmd)
+            return (0, False)
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+        monkeypatch.setattr(
+            mod,
+            "_wrap_for_sandbox",
+            lambda cmd, bp: ["/bin/bash", "-c", "bwrap --sandbox " + " ".join(cmd)],
+        )
+        mock_sock = MagicMock()
+        mock_sock.fileno.return_value = 99
+        monkeypatch.setattr(mod, "_connect_broker", MagicMock(return_value=mock_sock))
+
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+
+        assert exc_info.value.code == 0
+        assert len(captured_cmds) == 1
+        assert captured_cmds[0][0] == "/bin/bash"
+        assert captured_cmds[0][1] == "-c"
+        assert "bwrap --sandbox" in captured_cmds[0][2]
+
+    def test_wrap_calls_building_blocks(self, monkeypatch, tmp_path):
+        call_log = []
+
+        def mock_build_policy(bp):
+            call_log.append("build_policy")
+            return {"allow_write": [str(bp)], "deny_write": [], "deny_read": []}
+
+        def mock_build_srt_config(policy):
+            call_log.append("build_srt_config")
+            return {"filesystem": {"allowWrite": policy["allow_write"]}}
+
+        def mock_resolve_bwrap(cmd_str, srt_config):
+            call_log.append("resolve_bwrap_command")
+            return f"bwrap --ro-bind / / {cmd_str}"
+
+        monkeypatch.setattr("aipass.hooks.apps.modules.sandbox.build_policy", mock_build_policy)
+        monkeypatch.setattr(
+            "aipass.hooks.apps.modules.sandbox.build_srt_config",
+            mock_build_srt_config,
+        )
+        monkeypatch.setattr(
+            "aipass.hooks.apps.modules.sandbox.resolve_bwrap_command",
+            mock_resolve_bwrap,
+        )
+
+        result = _wrap_for_sandbox(["claude", "--model", "opus"], tmp_path)
+
+        assert call_log == ["build_policy", "build_srt_config", "resolve_bwrap_command"]
+        assert result[0] == "/bin/bash"
+        assert result[1] == "-c"
+        assert "claude" in result[2]
+
+
+class TestBrokenSandboxFailsLoud:
+    """Flag ON but sandbox init fails: ABORT, never silently unsandbox."""
+
+    def test_sandbox_init_failure_aborts(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        run_calls = []
+
+        def capture_run(cmd, *args, **kwargs):
+            run_calls.append(cmd)
+            return (0, False)
+
+        def broken_wrap(cmd, bp):
+            raise RuntimeError("srt resolve failed: node not found")
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(mod, "_wrap_for_sandbox", broken_wrap)
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+
+        assert run_calls == []
+        assert exc_info.value.code != 0
+
+    def test_sandbox_failure_sends_bounce(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        def broken_wrap(cmd, bp):
+            raise FileNotFoundError("node not found in PATH")
+
+        mock_bounce = MagicMock()
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", MagicMock(return_value=(0, False)))
+        monkeypatch.setattr(mod, "_wrap_for_sandbox", broken_wrap)
+        monkeypatch.setattr(mod, "_send_bounce", mock_bounce)
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        mock_bounce.assert_called_once()
+        reason = mock_bounce.call_args[0][1]
+        assert "sandbox" in reason.lower() or "-4" in reason
+
+    def test_never_falls_back_to_unsandboxed(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        wrap_calls = [0]
+        run_calls = []
+
+        def counting_broken_wrap(cmd, bp):
+            wrap_calls[0] += 1
+            raise RuntimeError("srt unavailable")
+
+        def capture_run(cmd, *args, **kwargs):
+            run_calls.append(cmd)
+            return (0, False)
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(mod, "_wrap_for_sandbox", counting_broken_wrap)
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        assert wrap_calls[0] == 1
+        assert run_calls == []
+
+
+# --- Broker-fd handshake tests (Phase 6b FPLAN-0250) -------------------------
+
+
+class TestFlagOffNoBroker:
+    """Flag OFF: no broker connection attempted at all."""
+
+    def test_flag_off_no_broker_activity(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.delenv("AIPASS_SANDBOX_ENABLED", raising=False)
+
+        connect_calls = []
+
+        def tracking_connect(*args, **kwargs):
+            connect_calls.append(args)
+            raise RuntimeError("should never be called")
+
+        monkeypatch.setattr(mod, "_connect_broker", tracking_connect)
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", MagicMock(return_value=(0, False)))
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+
+        assert exc_info.value.code == 0
+        assert connect_calls == []
+
+    def test_flag_off_no_broker_fd_in_env(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.delenv("AIPASS_SANDBOX_ENABLED", raising=False)
+
+        captured_env = {}
+
+        def capture_run(cmd, stdout_log, stderr_fh, cwd, env, branch, **kwargs):
+            captured_env.update(env)
+            return (0, False)
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        assert "AIPASS_BROKER_FD" not in captured_env
+
+
+class TestBrokerDownFailsLoud:
+    """Broker down + flag ON → exit -4, agent never spawned."""
+
+    def test_broker_connect_failure_aborts(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        run_calls = []
+
+        def capture_run(cmd, *args, **kwargs):
+            run_calls.append(cmd)
+            return (0, False)
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(
+            mod,
+            "_wrap_for_sandbox",
+            lambda cmd, bp: ["/bin/bash", "-c", "bwrap " + " ".join(cmd)],
+        )
+        monkeypatch.setattr(
+            mod,
+            "_connect_broker",
+            MagicMock(side_effect=OSError("broker socket not found")),
+        )
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+
+        assert run_calls == []
+        assert exc_info.value.code != 0
+
+    def test_broker_bad_hmac_aborts(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        run_calls = []
+
+        def capture_run(cmd, *args, **kwargs):
+            run_calls.append(cmd)
+            return (0, False)
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(
+            mod,
+            "_wrap_for_sandbox",
+            lambda cmd, bp: ["/bin/bash", "-c", "bwrap " + " ".join(cmd)],
+        )
+        monkeypatch.setattr(
+            mod,
+            "_connect_broker",
+            MagicMock(side_effect=RuntimeError("Broker identify failed: bad HMAC")),
+        )
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+
+        assert run_calls == []
+        assert exc_info.value.code != 0
+
+    def test_broker_failure_sends_bounce(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        mock_bounce = MagicMock()
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", MagicMock(return_value=(0, False)))
+        monkeypatch.setattr(
+            mod,
+            "_wrap_for_sandbox",
+            lambda cmd, bp: ["/bin/bash", "-c", "bwrap " + " ".join(cmd)],
+        )
+        monkeypatch.setattr(
+            mod,
+            "_connect_broker",
+            MagicMock(side_effect=OSError("socket missing")),
+        )
+        monkeypatch.setattr(mod, "_send_bounce", mock_bounce)
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        mock_bounce.assert_called_once()
+
+
+class TestBrokerFdHandshake:
+    """Flag ON + broker up: fd passed to child, parent closes after spawn."""
+
+    def test_broker_fd_in_env_and_pass_fds(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        captured_env = {}
+        captured_pass_fds = []
+
+        def capture_run(cmd, stdout_log, stderr_fh, cwd, env, branch, pass_fds=()):
+            captured_env.update(env)
+            captured_pass_fds.append(pass_fds)
+            return (0, False)
+
+        mock_sock = MagicMock()
+        mock_sock.fileno.return_value = 42
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(
+            mod,
+            "_wrap_for_sandbox",
+            lambda cmd, bp: ["/bin/bash", "-c", "bwrap " + " ".join(cmd)],
+        )
+        monkeypatch.setattr(mod, "_connect_broker", MagicMock(return_value=mock_sock))
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+
+        assert exc_info.value.code == 0
+        assert captured_env.get("AIPASS_BROKER_FD") == "42"
+        assert captured_pass_fds == [(42,)]
+        mock_sock.close.assert_called_once()
+
+    def test_parent_closes_socket_after_spawn(self, monkeypatch, main_argv):
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        mock_sock = MagicMock()
+        mock_sock.fileno.return_value = 7
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", MagicMock(return_value=(0, False)))
+        monkeypatch.setattr(
+            mod,
+            "_wrap_for_sandbox",
+            lambda cmd, bp: ["/bin/bash", "-c", "bwrap " + " ".join(cmd)],
+        )
+        monkeypatch.setattr(mod, "_connect_broker", MagicMock(return_value=mock_sock))
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        mock_sock.close.assert_called_once()
+
+    def test_broker_fd_cleaned_from_env_after_spawn(self, monkeypatch, main_argv):
+        """After spawn+close, AIPASS_BROKER_FD removed from spawn_env."""
+        argv, lock_file, stderr_log = main_argv
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+
+        env_snapshots = []
+
+        def capture_run(cmd, stdout_log, stderr_fh, cwd, env, branch, pass_fds=()):
+            env_snapshots.append(dict(env))
+            return (0, False)
+
+        mock_sock = MagicMock()
+        mock_sock.fileno.return_value = 10
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", capture_run)
+        monkeypatch.setattr(
+            mod,
+            "_wrap_for_sandbox",
+            lambda cmd, bp: ["/bin/bash", "-c", "bwrap " + " ".join(cmd)],
+        )
+        monkeypatch.setattr(mod, "_connect_broker", MagicMock(return_value=mock_sock))
+        monkeypatch.setattr(mod, "_send_bounce", MagicMock())
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        # During the run, env had the FD
+        assert env_snapshots[0]["AIPASS_BROKER_FD"] == "10"
+
+
+@pytest.mark.skipif(sys.platform != "linux", reason="AF_UNIX broker daemon is Linux-only")
+class TestBrokerRealE2E:
+    """Real multi-process e2e: broker daemon, identified connection, child reads fd."""
+
+    def test_child_inherits_broker_fd(self, tmp_path):
+        """Start real broker, create identified conn, spawn child that reads AIPASS_BROKER_FD."""
+        import time as time_mod
+        from aipass.drone.apps.handlers.broker.daemon import BrokerDaemon
+        from aipass.drone.apps.handlers.broker.client import create_identified_connection
+
+        # Set up repo root with branch dir
+        repo_root = tmp_path / "repo"
+        branch_dir = repo_root / "src" / "aipass" / "testbranch"
+        branch_dir.mkdir(parents=True)
+        target_file = branch_dir / "deleteme.txt"
+        target_file.write_text("delete me", encoding="utf-8")
+
+        # Start real broker
+        sock_path = tmp_path / "broker.sock"
+        audit_path = tmp_path / "audit.jsonl"
+        secret_path = tmp_path / "secret"
+        broker = BrokerDaemon(
+            repo_root=repo_root,
+            socket_path=sock_path,
+            audit_path=audit_path,
+            secret_path=secret_path,
+        )
+        t = broker.start_background()
+        time_mod.sleep(0.5)
+
+        try:
+            # Create identified connection (as the launcher would)
+            sock = create_identified_connection(sock_path, secret_path, "testbranch")
+            broker_fd = sock.fileno()
+
+            # Spawn a real child that reads AIPASS_BROKER_FD and sends a delete
+            child_script = tmp_path / "child.py"
+            child_script.write_text(
+                """
+import os, socket, json
+
+fd = int(os.environ["AIPASS_BROKER_FD"])
+s = socket.socket(fileno=fd)
+try:
+    req = json.dumps({"op": "delete", "path": "deleteme.txt", "request_id": "e2e1"}) + "\\n"
+    s.sendall(req.encode())
+    data = b""
+    while b"\\n" not in data:
+        chunk = s.recv(4096)
+        if not chunk:
+            break
+        data += chunk
+    resp = json.loads(data.decode())
+    # Write result to a file so parent can verify
+    with open(os.environ["RESULT_FILE"], "w") as f:
+        json.dump(resp, f)
+finally:
+    s.detach()
+""",
+                encoding="utf-8",
+            )
+
+            result_file = tmp_path / "result.json"
+            env = os.environ.copy()
+            env["AIPASS_BROKER_FD"] = str(broker_fd)
+            env["RESULT_FILE"] = str(result_file)
+
+            proc = subprocess.Popen(
+                [sys.executable, str(child_script)],
+                env=env,
+                pass_fds=(broker_fd,),
+                close_fds=True,
+            )
+            # Parent closes its copy
+            sock.close()
+
+            proc.wait(timeout=10)
+            assert proc.returncode == 0
+
+            # Verify the delete happened
+            assert not target_file.exists()
+
+            # Verify the child got a success response
+            import json as json_mod
+
+            result = json_mod.loads(result_file.read_text(encoding="utf-8"))
+            assert result["ok"] is True
+
+            # Verify audit log carries identity
+            audit_lines = audit_path.read_text(encoding="utf-8").strip().splitlines()
+            delete_entries = [
+                json_mod.loads(line) for line in audit_lines if json_mod.loads(line).get("op") == "delete"
+            ]
+            assert len(delete_entries) >= 1
+            assert delete_entries[-1]["identity"] == "testbranch"
+            assert delete_entries[-1]["result"] == "DELETED"
+
+        finally:
+            broker.stop()
+            t.join(timeout=3)

src/aipass/ai_mail/tests/test_email_module.py

@@ -385,7 +385,7 @@ class TestHandleClose:
         post_ops_called = []
         monkeypatch.setattr(
             "aipass.ai_mail.apps.modules.email.batch_close_post_ops",
-            lambda bp, push_fn, central_fn, purge_fn: post_ops_called.append(True),
+            lambda bp, central_fn, purge_fn: post_ops_called.append(True),
         )
         mock_console = MagicMock()
         mock_console.print = lambda msg, **kw: None
@@ -1286,7 +1286,7 @@ class TestHandleCloseExtended:
         )
         monkeypatch.setattr(
             "aipass.ai_mail.apps.modules.email.batch_close_post_ops",
-            lambda bp, push_fn, central_fn, purge_fn: None,
+            lambda bp, central_fn, purge_fn: None,
         )
         printed: list[str] = []
         errors: list[str] = []
@@ -1338,7 +1338,7 @@ class TestHandleCloseExtended:
         post_ops_called: list[bool] = []
         monkeypatch.setattr(
             "aipass.ai_mail.apps.modules.email.batch_close_post_ops",
-            lambda bp, push_fn, central_fn, purge_fn: post_ops_called.append(True),
+            lambda bp, central_fn, purge_fn: post_ops_called.append(True),
         )
         printed: list[str] = []
         mock_console = MagicMock()
@@ -1450,7 +1450,6 @@ class TestDeliveryCallback:
             new_count,
             opened_count,
             total,
-            push_dashboard_fn=None,
             update_central_fn=None,
         ):
             """Capture on_email_delivered arguments."""
@@ -1460,7 +1459,6 @@ class TestDeliveryCallback:
                     "new_count": new_count,
                     "opened_count": opened_count,
                     "total": total,
-                    "push_dashboard_fn": push_dashboard_fn,
                     "update_central_fn": update_central_fn,
                 }
             )
@@ -1478,7 +1476,6 @@ class TestDeliveryCallback:
         assert delivered_args[0]["new_count"] == 3
         assert delivered_args[0]["opened_count"] == 2
         assert delivered_args[0]["total"] == 5
-        assert delivered_args[0]["push_dashboard_fn"] is not None
 
 
 # ===========================================================================
@@ -1708,7 +1705,7 @@ class TestEmailSendIntrospection:
 
         print_introspection()
         combined = "\n".join(printed)
-        assert "EMAIL SEND ORCHESTRATION" in combined
+        assert "email_send Module" in combined
         assert "handle_send" in combined
         assert "_send_direct" in combined
         assert "_send_broadcast" in combined
@@ -1761,3 +1758,62 @@ class TestSendInteractiveExtended:
         assert result is True
         assert any("@alpha" in p for p in printed)
         assert any("sent" in p.lower() for p in printed)
+
+
+class TestHandleReplyMultiArg:
+    """Regression tests for multi-line reply body truncation (S84 fix)."""
+
+    def test_reply_joins_split_args_into_body(self, tmp_path, monkeypatch):
+        """When shell splits body into multiple args, all are joined into message."""
+        original = {"id": "msg1", "from": "@devpulse", "subject": "test dispatch"}
+        captured_msg = []
+
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.modules.email._resolve_branch_path",
+            lambda: tmp_path,
+        )
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.modules.email.get_email_by_id",
+            lambda inbox_file, msg_id: original,
+        )
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.modules.email.send_reply",
+            lambda bp, orig, msg: (captured_msg.append(msg), "Reply sent", "r1")[1:],
+        )
+        mock_console = MagicMock()
+        monkeypatch.setattr("aipass.ai_mail.apps.modules.email.console", mock_console)
+        _write_inbox(tmp_path)
+
+        from aipass.ai_mail.apps.modules.email import handle_reply
+
+        result = handle_reply(["msg1", "Line one", "Line two", "Line three"])
+        assert result is True
+        assert len(captured_msg) == 1
+        assert captured_msg[0] == "Line one Line two Line three"
+
+    def test_reply_single_arg_unchanged(self, tmp_path, monkeypatch):
+        """Single-arg reply body remains unchanged (no extra spaces)."""
+        original = {"id": "msg1", "from": "@devpulse", "subject": "test"}
+        captured_msg = []
+
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.modules.email._resolve_branch_path",
+            lambda: tmp_path,
+        )
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.modules.email.get_email_by_id",
+            lambda inbox_file, msg_id: original,
+        )
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.modules.email.send_reply",
+            lambda bp, orig, msg: (captured_msg.append(msg), "Reply sent", "r1")[1:],
+        )
+        mock_console = MagicMock()
+        monkeypatch.setattr("aipass.ai_mail.apps.modules.email.console", mock_console)
+        _write_inbox(tmp_path)
+
+        from aipass.ai_mail.apps.modules.email import handle_reply
+
+        result = handle_reply(["msg1", "Complete single-line reply"])
+        assert result is True
+        assert captured_msg[0] == "Complete single-line reply"

src/aipass/ai_mail/tests/test_error_dispatch.py

@@ -155,51 +155,34 @@ def test_dispatch_send_error_passes_correct_email_data(monkeypatch):
 # ---- on_email_delivered tests --------------------------------
 
 
-def test_on_email_delivered_with_both_callbacks():
-    """Both callbacks are invoked when provided."""
-    push_fn = MagicMock()
+def test_on_email_delivered_with_central_callback():
+    """Central callback is invoked when provided."""
     update_fn = MagicMock()
     branch_path = "/some/path"
 
-    on_email_delivered(branch_path, 3, 1, 10, push_fn, update_fn)
+    on_email_delivered(branch_path, 3, 1, 10, update_central_fn=update_fn)
 
-    push_fn.assert_called_once_with(branch_path)
     update_fn.assert_called_once_with()
 
 
 def test_on_email_delivered_with_none_callbacks():
-    """No error when both callbacks are None."""
-    on_email_delivered("/some/path", 3, 1, 10, None, None)
-
-
-def test_on_email_delivered_dashboard_failure_does_not_block_central():
-    """Dashboard failure does not prevent central update from running."""
-    push_fn = MagicMock(side_effect=RuntimeError("dashboard broken"))
-    update_fn = MagicMock()
-
-    on_email_delivered("/some/path", 3, 1, 10, push_fn, update_fn)
-
-    push_fn.assert_called_once()
-    update_fn.assert_called_once()
+    """No error when callback is None."""
+    on_email_delivered("/some/path", 3, 1, 10, None)
 
 
 def test_on_email_delivered_central_failure_does_not_raise():
     """Central update failure is caught silently."""
-    push_fn = MagicMock()
     update_fn = MagicMock(side_effect=RuntimeError("central broken"))
 
-    on_email_delivered("/some/path", 3, 1, 10, push_fn, update_fn)
+    on_email_delivered("/some/path", 3, 1, 10, update_central_fn=update_fn)
 
-    push_fn.assert_called_once()
     update_fn.assert_called_once()
 
 
-def test_on_email_delivered_both_fail_no_exception():
-    """Both callbacks failing does not raise any exception."""
-    push_fn = MagicMock(side_effect=RuntimeError("push fail"))
+def test_on_email_delivered_central_fail_no_exception():
+    """Central callback failing does not raise any exception."""
     update_fn = MagicMock(side_effect=RuntimeError("update fail"))
 
-    on_email_delivered("/some/path", 3, 1, 10, push_fn, update_fn)
+    on_email_delivered("/some/path", 3, 1, 10, update_central_fn=update_fn)
 
-    push_fn.assert_called_once()
     update_fn.assert_called_once()

src/aipass/ai_mail/tests/test_inbox_cleanup.py

@@ -42,12 +42,6 @@ def _mock_inbox_lock(monkeypatch):
     monkeypatch.setattr(mod, "_get_inbox_lock", lambda: _noop_lock)
 
 
-@pytest.fixture(autouse=True)
-def _mock_dashboard(monkeypatch):
-    """Replace _get_push_dashboard_update with a no-op."""
-    monkeypatch.setattr(mod, "_get_push_dashboard_update", lambda: lambda _bp: None)
-
-
 @pytest.fixture(autouse=True)
 def _mock_central(monkeypatch):
     """Replace _get_update_central with a no-op."""

src/aipass/ai_mail/tests/test_misc_handlers.py

@@ -1,6 +1,6 @@
 """Tests for miscellaneous handlers -- central_writer.update_central, dispatch status.check_pid_status,
 daemon.run_daemon, json_handler.increment_counter/update_data_metrics, delivery.deliver_to_inbox_file,
-dashboard_sync.push_dashboard_update, inbox_resolve.resolve_inbox_target."""
+inbox_resolve.resolve_inbox_target."""
 
 import json
 import os
@@ -14,7 +14,6 @@ import aipass.ai_mail.apps.handlers.central_writer as central_mod
 import aipass.ai_mail.apps.handlers.dispatch.daemon as daemon_mod
 import aipass.ai_mail.apps.handlers.json_utils.json_handler as json_handler_mod
 import aipass.ai_mail.apps.handlers.email.delivery as delivery_mod
-import aipass.ai_mail.apps.handlers.email.dashboard_sync as dashboard_mod
 from aipass.ai_mail.apps.handlers.central_writer import update_central
 from aipass.ai_mail.apps.handlers.dispatch.status import check_pid_status
 from aipass.ai_mail.apps.handlers.json_utils.json_handler import (
@@ -22,7 +21,6 @@ from aipass.ai_mail.apps.handlers.json_utils.json_handler import (
     update_data_metrics,
 )
 from aipass.ai_mail.apps.handlers.email.delivery import deliver_to_inbox_file
-from aipass.ai_mail.apps.handlers.email.dashboard_sync import push_dashboard_update
 from aipass.ai_mail.apps.handlers.email.inbox_resolve import resolve_inbox_target
 
 
@@ -61,14 +59,6 @@ def _silence_json_handler_delivery():
         yield mock_jh
 
 
-@pytest.fixture(autouse=True)
-def _silence_json_handler_dashboard():
-    """Prevent log_operation in dashboard_sync from writing real JSON files."""
-    with patch("aipass.ai_mail.apps.handlers.email.dashboard_sync.json_handler") as mock_jh:
-        mock_jh.log_operation.return_value = True
-        yield mock_jh
-
-
 @pytest.fixture(autouse=True)
 def _silence_json_handler_inbox_resolve():
     """Prevent log_operation in inbox_resolve from writing real JSON files."""
@@ -399,64 +389,6 @@ def test_deliver_to_inbox_file_preserves_existing_messages(tmp_path, _noop_inbox
     assert result["messages"][1]["subject"] == "Old email"
 
 
-# ==============================================================
-# push_dashboard_update tests
-# ==============================================================
-
-
-def test_push_dashboard_update_happy_path(tmp_path):
-    """Successful dashboard push returns True."""
-    branch_path = tmp_path / "trigger"
-    inbox_dir = branch_path / ".ai_mail.local"
-    inbox_dir.mkdir(parents=True)
-    inbox_file = inbox_dir / "inbox.json"
-    inbox_data = {
-        "messages": [
-            {"id": "m1", "status": "new", "timestamp": "2026-04-01 10:00:00"},
-            {"id": "m2", "status": "opened", "timestamp": "2026-04-01 09:00:00"},
-        ]
-    }
-    inbox_file.write_text(json.dumps(inbox_data), encoding="utf-8")
-
-    mock_write = MagicMock(return_value=True)
-
-    with patch.object(dashboard_mod, "_get_write_section", return_value=mock_write):
-        result = push_dashboard_update(branch_path)
-
-    assert result is True
-    mock_write.assert_called_once()
-    section_data = mock_write.call_args[0][1]
-    assert section_data == "ai_mail"
-
-
-def test_push_dashboard_update_no_inbox(tmp_path):
-    """Returns True with zero stats when no inbox exists."""
-    branch_path = tmp_path / "empty_branch"
-    branch_path.mkdir()
-
-    mock_write = MagicMock(return_value=True)
-
-    with patch.object(dashboard_mod, "_get_write_section", return_value=mock_write):
-        result = push_dashboard_update(branch_path)
-
-    assert result is True
-    mock_write.assert_called_once()
-    section_data = mock_write.call_args[0][2]
-    assert section_data["new"] == 0
-    assert section_data["total"] == 0
-
-
-def test_push_dashboard_update_catches_exceptions(tmp_path):
-    """Returns False on any exception (never raises)."""
-    branch_path = tmp_path / "broken"
-    branch_path.mkdir()
-
-    with patch.object(dashboard_mod, "_get_write_section", side_effect=RuntimeError("broken")):
-        result = push_dashboard_update(branch_path)
-
-    assert result is False
-
-
 # ==============================================================
 # resolve_inbox_target tests
 # ==============================================================

src/aipass/ai_mail/tests/test_reply.py

@@ -268,3 +268,40 @@ def test_send_reply_re_prefix_not_duplicated(tmp_path):
     assert success is True
     # Should keep "RE: Already replied", not "RE: RE: Already replied"
     assert deliver_calls[0][1]["subject"] == "RE: Already replied"
+
+
+def test_send_reply_multiline_body_preserved(tmp_path):
+    """Multi-line reply body is stored intact, not truncated to first line."""
+    from_branch_path = tmp_path / "hooks"
+    from_branch_path.mkdir()
+    sender_info = {"email": "@hooks", "name": "HOOKS"}
+    target_branch = {"email": "@devpulse", "name": "DEVPULSE", "path": str(tmp_path / "devpulse")}
+    original = _make_original_email()
+
+    deliver_calls = []
+
+    def mock_deliver(to_branch, email_data):
+        deliver_calls.append((to_branch, email_data))
+        return (True, "")
+
+    multiline_body = (
+        "Investigation: cadence findings\n\nDetails:\n1. First finding\n2. Second finding\n3. Third finding"
+    )
+
+    with (
+        patch(_PATCH_BRANCH_DETECTION, return_value=sender_info),
+        patch(_PATCH_DELIVERY, side_effect=mock_deliver),
+        patch(_PATCH_ALL_BRANCHES, return_value=[target_branch]),
+        patch(_PATCH_CLOSE_ARCHIVE, return_value=(True, "closed")),
+    ):
+        success, _message, _reply_id = send_reply(from_branch_path, original, multiline_body)
+
+    assert success is True
+    assert deliver_calls[0][1]["message"] == multiline_body
+
+    sent_folder = from_branch_path / ".ai_mail.local" / "sent"
+    sent_files = list(sent_folder.glob("*.json"))
+    assert len(sent_files) == 1
+    with open(sent_files[0], "r", encoding="utf-8") as f:
+        sent_data = json.load(f)
+    assert sent_data["message"] == multiline_body

src/aipass/ai_mail/tests/test_send_helpers.py

@@ -357,3 +357,34 @@ def test_resolve_dispatch_target_tilde_path():
     result = resolve_dispatch_target("~/Projects/flow", True, get_branch_info_fn=None)
 
     assert result == "@flow"
+
+
+# ---- parse_send_args multi-arg message tests (S84 fix) --------
+
+
+def test_parse_send_args_joins_split_message():
+    """When message body is split into multiple args, all are joined."""
+    from aipass.ai_mail.apps.handlers.email.send_args import parse_send_args
+
+    result = parse_send_args(["@target", "Subject", "Line one", "Line two", "Line three"])
+    assert result["mode"] == "direct"
+    assert result["subject"] == "Subject"
+    assert result["message"] == "Line one Line two Line three"
+
+
+def test_parse_send_args_single_message_unchanged():
+    """Single message arg is not altered."""
+    from aipass.ai_mail.apps.handlers.email.send_args import parse_send_args
+
+    result = parse_send_args(["@target", "Subject", "Complete body here"])
+    assert result["mode"] == "direct"
+    assert result["message"] == "Complete body here"
+
+
+def test_parse_send_args_multiline_body_preserved():
+    """A single arg with embedded newlines passes through intact."""
+    from aipass.ai_mail.apps.handlers.email.send_args import parse_send_args
+
+    body = "First line\nSecond line\nThird line"
+    result = parse_send_args(["@target", "Subject", body])
+    assert result["message"] == body

src/aipass/ai_mail/tests/test_send_identity.py

@@ -570,13 +570,18 @@ class TestDispatchEnvIsolation:
         )
 
     def test_dispatch_monitor_passes_spawn_env_to_subprocess(self):
-        """dispatch_monitor.py must pass env=spawn_env to subprocess.run.
+        """dispatch_monitor.py must pass spawn_env as the subprocess env.
 
         Without this, all env var isolation is useless — the subprocess
         would inherit os.environ instead of the cleaned spawn_env.
+        Accepts either the direct kwarg form (env=spawn_env) or the
+        popen_kwargs dict form ("env": spawn_env) introduced with the
+        sandbox broker-fd wiring (FPLAN-0250 Phase 6b).
         """
         active_source = self._load_active_source()
-        assert "env=spawn_env" in active_source, "dispatch_monitor.py must pass env=spawn_env to subprocess.run"
+        assert "env=spawn_env" in active_source or '"env": spawn_env' in active_source, (
+            "dispatch_monitor.py must pass spawn_env as the subprocess env"
+        )
 
     def test_detect_resolves_identity_when_cwd_is_wrong(self, clean_env, tmp_path, list_format_registry):
         """When AIPASS_CALLER_BRANCH is set but CWD is outside any branch,

src/aipass/aipass/.aipass/aipass_local_prompt.md

@@ -1,6 +1,6 @@
 # AIPASS — Branch Prompt
 
-*Injected every turn. Breadcrumbs only — details: README, --help, .trinity/ memories, STATUS.local.md.*
+*Injected every turn. Breadcrumbs only — details: README, --help, .trinity/ memories.*
 
 ## Identity
 

src/aipass/aipass/.seedgo/bypass.json

@@ -2,8 +2,8 @@
   "metadata": {
     "version": "2.0.0",
     "created": "2026-04-16",
-    "description": "Bypass config for @aipass citizen. While under construction (DPLAN-0136 Phase 0-3), module and handler files exist as documented placeholders with no implementation body. Each placeholder raises NotImplementedError and declares its phase. Bypass standards that fire on structural requirements the placeholders intentionally skip — json_handler import, print_introspection, CLI service wiring. Remove these entries in Phase N as each module gets its real body.",
-    "last_updated": "2026-04-16"
+    "description": "Bypass config for @aipass citizen. Modules operational: concierge/init/doctor/handoff/profile built and tested. Bypasses cover: binary-invocation introspection pattern (bare aipass <cmd> runs, --info for introspection), thin entry-point router (aipass.py uses bare print, no CLI imports), pure-python bootstrap (bootstrap.py/scaffold_content.py run before AIPass services exist), test-isolation patterns (architecture/encapsulation for tests/ directory), and CLI flag name references (permission_flags in test assertions and handoff platform).",
+    "last_updated": "2026-06-02"
   },
   "bypass": [
     {
@@ -31,45 +31,20 @@
       "standard": "cli",
       "reason": "Session info must print immediately after tmux spawn — returning data to module layer would lose the timing context. User needs attach/kill instructions right when the session starts."
     },
-    {
-      "file": "apps/modules/handoff.py",
-      "standard": "introspection",
-      "reason": "Phase 4 placeholder — print_introspection() added with handoff build."
-    },
-    {
-      "file": "apps/modules/handoff.py",
-      "standard": "json_structure",
-      "reason": "Phase 4 placeholder — json_handler import added with handoff build."
-    },
-    {
-      "file": "apps/modules/handoff.py",
-      "standard": "cli",
-      "reason": "Phase 4 placeholder — CLI service imports added with handoff build."
-    },
-    {
-      "file": "apps/aipass.py",
-      "standard": "architecture",
-      "reason": "Phase 0 entry-point stub from spawn template. Full 3-layer wiring (modules/ discovery, handlers/ imports) added when first module comes online (Phase 1)."
-    },
     {
       "file": "apps/aipass.py",
       "standard": "cli",
-      "reason": "Phase 0 entry-point stub — CLI service imports (console, header) added when modules come online (Phase 1+)."
+      "reason": "Thin command router — discovers and routes to modules, which own the CLI service layer. Adding console/header imports here couples the bootstrap entry point to Rich for 4 status lines."
     },
     {
       "file": "apps/aipass.py",
       "standard": "debug_print",
-      "reason": "Phase 0 entry-point stub uses bare print() for scaffold visibility. Replaced with console.print() when CLI services are wired in Phase 1+."
+      "reason": "Thin command router uses bare print() for version output and help banner (4 calls). These run before module discovery — importing Rich console for bootstrap output adds startup overhead for minimal benefit."
     },
     {
       "file": "apps/aipass.py",
       "standard": "introspection",
-      "reason": "Phase 0 — spawn template does not emit print_introspection(). Added when modules come online (Phase 1+)."
-    },
-    {
-      "file": "apps/aipass.py",
-      "standard": "log_structure",
-      "reason": "Phase 0 — logs/ directory exists (spawn-created), but prax logger import not wired yet. Added when first module uses it."
+      "reason": "Thin command router, not a module — it has no domain to introspect. Modules handle their own introspection via --info. No print_introspection() needed."
     },
     {
       "file": "apps/modules/doctor.py",
@@ -260,6 +235,106 @@
       "file": "apps/handlers/init/scaffold_content.py",
       "standard": "json_structure",
       "reason": "scaffold_content.py is Pure Python only (no module/prax/cli imports) by design — pure string-returning template generators extracted from bootstrap.py. Same constraint as bootstrap.py."
+    },
+    {
+      "file": "apps/modules/doctor.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: aipass doctor runs the command; introspection via --info"
+    },
+    {
+      "file": "apps/modules/doctor_fix.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: bare invocation shows usage; introspection via --info"
+    },
+    {
+      "file": "apps/modules/doctor_wire.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: bare invocation shows usage; introspection via --info"
+    },
+    {
+      "file": "apps/modules/handoff.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: aipass handoff shows usage; introspection via --info"
+    },
+    {
+      "file": "apps/modules/help_chat.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: aipass help shows usage; introspection via --info"
+    },
+    {
+      "file": "apps/modules/init_flow.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: aipass init shows usage; introspection via --info"
+    },
+    {
+      "file": "apps/modules/profile.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: aipass profile runs the command; introspection via --info"
+    },
+    {
+      "file": "apps/handlers/json/json_handler.py",
+      "standard": "test_quality",
+      "reason": "save_json now raises ValueError on invalid structure (aipass.aipass.shared contract, TDPLAN-0006 P2). Tested via pytest.raises — no False return path to test."
+    },
+    {
+      "file": "tests/test_sandbox_check.py",
+      "standard": "architecture",
+      "reason": "Test file lives in tests/ by convention — not in apps/. Standard 3-layer structure applies to production code only."
+    },
+    {
+      "file": "tests/test_sandbox_check.py",
+      "standard": "encapsulation",
+      "reason": "Unit tests must import handlers directly (sandbox_checker, progress) to test them in isolation. Entry-point imports would defeat the purpose of unit testing."
+    },
+    {
+      "file": "tests/test_sandbox_check.py",
+      "standard": "documentation",
+      "reason": "Test methods use descriptive names (test_flag_off_by_default, test_bwrap_functional_live) that are self-documenting. Adding docstrings to 41 test functions adds noise without value."
+    },
+    {
+      "file": "shared/json_handler.py",
+      "standard": "architecture",
+      "reason": "pre-infra leaf — stdlib-only by design, must not import branch dependencies (loads pre-drone for aipass init)"
+    },
+    {
+      "file": "shared/json_handler.py",
+      "standard": "log_visibility",
+      "reason": "pre-infra leaf — stdlib-only by design, must not import branch dependencies (loads pre-drone for aipass init)"
+    },
+    {
+      "file": "shared/json_handler.py",
+      "standard": "trigger",
+      "reason": "pre-infra leaf — stdlib-only by design, must not import branch dependencies (loads pre-drone for aipass init)"
+    },
+    {
+      "file": "shared/json_ops.py",
+      "standard": "architecture",
+      "reason": "pre-infra leaf — stdlib-only by design, must not import branch dependencies (loads pre-drone for aipass init)"
+    },
+    {
+      "file": "shared/json_ops.py",
+      "standard": "log_visibility",
+      "reason": "pre-infra leaf — stdlib-only by design, must not import branch dependencies (loads pre-drone for aipass init)"
+    },
+    {
+      "file": "shared/json_ops.py",
+      "standard": "trigger",
+      "reason": "pre-infra leaf — stdlib-only by design, must not import branch dependencies (loads pre-drone for aipass init)"
+    },
+    {
+      "file": "shared/registry_discovery.py",
+      "standard": "architecture",
+      "reason": "pre-infra leaf — stdlib-only by design, must not import branch dependencies (loads pre-drone for aipass init)"
+    },
+    {
+      "file": "tests/test_shared_bootstrap_safety.py",
+      "standard": "architecture",
+      "reason": "Test file lives in tests/ by convention — not in apps/. Standard 3-layer structure applies to production code only."
+    },
+    {
+      "file": "shared/json_ops.py",
+      "standard": "unused_function",
+      "reason": "backup_json() is consumed by @spawn (cross-branch caller). Appears unused in @aipass-only scan but is a shared API."
     }
   ]
 }

src/aipass/aipass/README.md

@@ -17,9 +17,9 @@ aipass/
 │   ├── modules/
 │   │   ├── doctor.py                      # System health aggregation
 │   │   ├── doctor_fix.py                  # Remediation report (--fix, --json)
-│   │   ├── doctor_wire.py                 # Auto-wire prompt helpers
+│   │   ├── doctor_wire.py                 # Auto-wire provider settings + stale-deny re-export
 │   │   ├── handoff.py                     # CLI handoff (placeholder)
-│   │   ├── help_chat.py                   # README-backed Q&A
+│   │   ├── help_chat.py                   # README-backed Q&A (reads via readme_map handler)
 │   │   ├── init_flow.py                   # 12-stage guided setup
 │   │   └── profile.py                     # User profile read/write
 │   ├── handlers/
@@ -27,12 +27,14 @@ aipass/
 │   │   ├── init/                          # bootstrap.py, scaffold_content.py
 │   │   ├── json/                          # JSON read/write utilities
 │   │   ├── ping_sweep/                    # Branch reachability verification
+│   │   ├── provider_reconcile.py           # Stale deny-rule detection + fix
 │   │   ├── readme_map/                    # Live file reads + branch routing
 │   │   ├── structure_scan/                # Agent placement + pollution detection
 │   │   ├── system_detect/                 # OS, shell, Python, RAM, CPU
 │   │   └── ui/                            # Progress bars, menus, banners
 │   └── plugins/
-├── tests/                                 # 412 passing
+├── tests/                                 # 432 passing
+├── requirements.project.txt               # Project-specific Python dependencies
 ├── .trinity/                              # Identity + session history + observations
 └── README.md
 ```
@@ -68,7 +70,7 @@ Humans only. Nothing in AIPass depends on this branch.
 
 ## Tests
 
-412 passing — `pytest src/aipass/aipass/tests/`
+432 passing — `pytest src/aipass/aipass/tests/`
 
 ## Known Issues
 
@@ -76,4 +78,4 @@ Humans only. Nothing in AIPass depends on this branch.
 
 ## Last Updated
 
-Last Updated: 2026-05-16
+Last Updated: 2026-06-05

src/aipass/aipass/apps/aipass.py

@@ -15,11 +15,25 @@ Auto-discovery architecture:
 - No manual imports or routing needed
 """
 
+import os
 import sys
 import importlib
 from pathlib import Path
 from typing import List, Any
 
+# Windows terminals/pipes default to cp1252, which can't encode the Unicode
+# Rich emits (✓/✗, box-drawing, arrows). PYTHONUTF8 only affects child
+# interpreters, not this process's already-open stdout/stderr — so we also
+# reconfigure the live streams to UTF-8 in place (Python 3.7+). Without this,
+# `aipass init` scaffolds correctly but crashes printing its success banner
+# with UnicodeEncodeError ('charmap') on Windows. Mirrors drone/cli.py.
+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")  # for child subprocesses
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 from aipass.prax import logger
 
 # =============================================================================

src/aipass/aipass/apps/handlers/init/bootstrap.py

@@ -11,15 +11,15 @@ Init Bootstrap Handler - PRIVATE implementation
 
 Business logic for `aipass init`. Creates the project scaffold:
    1. {NAME}_REGISTRY.json            — project registry with UUID
-   2. .aipass/aipass_global_prompt.md  — global prompt (injected every turn)
+   2. .aipass/tier0_kernel.md         — tier 0 kernel prompt (every turn)
+   2b..aipass/tier1_navmap.md         — tier 1 navigation map (periodic)
    3. CLAUDE.md                       — project prompt (Claude Code reads this)
    4. AGENTS.md                       — Codex equivalent of CLAUDE.md
    5. README.md                       — getting started guide
-   6. STATUS.local.md                 — project status
-   7. .gitignore                      — standard AIPass ignores
-   8. .claude/settings.json           — Claude Code hooks configuration
-   9. src/                            — directory where agents live
-  10. .ai_mail.local/inbox.json       — empty project mailbox
+   6. .gitignore                      — standard AIPass ignores
+   7. .claude/settings.json           — Claude Code hooks configuration
+   8. src/                            — directory where agents live
+   9. .ai_mail.local/inbox.json       — empty project mailbox
 
 Projects are NOT citizens — no .trinity/ directory. Identity lives in the
 registry JSON. Init is re-runnable: existing files are skipped, not errors.
@@ -43,60 +43,6 @@ from aipass.aipass.apps.handlers.init import scaffold_content as sc
 
 logger = logging.getLogger(__name__)
 
-# Hooks are NOT distributed to projects. All hooks fire from provider
-# settings (~/.claude/settings.json), installed by setup.sh. Provider hooks
-# use CWD-walking patterns that work from any directory in any project.
-# Hook files are shipped as reference copies only (for debugging/inspection).
-HOOKS_TO_SHIP = [
-    "branch_prompt_loader.py",
-    "email_notification.py",
-    "identity_injector.py",
-    "pre_compact.py",
-    "auto_fix_diagnostics.py",
-    "pre_edit_gate.py",
-    "subagent_stop_gate.py",
-]
-
-
-def _ship_hooks(aipass_home: str, target: Path) -> list[str]:
-    """Copy enforcement + injector hooks from AIPass install to target project.
-
-    Copies each hook file to {target}/.claude/hooks/. Looks for hooks in two
-    locations (first match wins):
-      1. {aipass_home}/.claude/hooks/  — dev install (git clone)
-      2. aipass/_hooks/                — pip install (wheel-bundled)
-
-    Skips audio hooks. Overwrites existing files only if source content
-    differs (idempotent re-sync). Returns list of files written.
-    """
-    source_dir = Path(aipass_home) / ".claude" / "hooks"
-    if not source_dir.is_dir():
-        # Fallback: pip install bundles hooks at aipass/_hooks/ inside the package
-        package_hooks = Path(__file__).resolve().parents[4] / "_hooks"
-        if package_hooks.is_dir():
-            source_dir = package_hooks
-        else:
-            logger.info("No hooks directory at %s or %s — skipping", source_dir, package_hooks)
-            return []
-
-    dest_dir = target / ".claude" / "hooks"
-    dest_dir.mkdir(parents=True, exist_ok=True)
-    shipped: list[str] = []
-
-    for hook_name in HOOKS_TO_SHIP:
-        src = source_dir / hook_name
-        dst = dest_dir / hook_name
-        if not src.exists():
-            logger.info("Hook %s not found at %s — skipping", hook_name, src)
-            continue
-        src_content = src.read_bytes()
-        if dst.exists() and dst.read_bytes() == src_content:
-            continue
-        shutil.copy2(src, dst)
-        shipped.append(str(dst))
-
-    return shipped
-
 
 def _sanitize_name(raw: str) -> str:
     """Sanitize a project name for use in filenames.
@@ -124,14 +70,6 @@ def _detect_aipass_home() -> str | None:
     return None
 
 
-def _resolve_global_prompt(name: str, aipass_home: str | None, dest: Path) -> str:
-    """Resolve global prompt content from source template or fallback generator."""
-    source = Path(aipass_home) / ".aipass" / "project_global_prompt.md" if aipass_home else None
-    if source and source.is_file():
-        return source.read_text(encoding="utf-8").replace("{name}", name)
-    return sc.with_source(sc.global_prompt_md(name), dest)
-
-
 def _hook_fingerprint(hook_entry: dict) -> str:
     """Extract a comparable fingerprint from a hook entry."""
     commands = []
@@ -201,6 +139,52 @@ def _merge_settings(existing: dict, generated: dict) -> dict:
     return merged
 
 
+def _merge_hooks_json(existing: dict, template: dict) -> dict:
+    """Union-merge hooks.json: preserve user enabled values, add new hooks/events."""
+    merged: dict = {}
+    meta_keys = {"_comment", "hooks_enabled"}
+
+    if "_comment" in template:
+        merged["_comment"] = template["_comment"]
+    elif "_comment" in existing:
+        merged["_comment"] = existing["_comment"]
+
+    if "hooks_enabled" in existing:
+        merged["hooks_enabled"] = existing["hooks_enabled"]
+    elif "hooks_enabled" in template:
+        merged["hooks_enabled"] = template["hooks_enabled"]
+
+    all_events: set[str] = set()
+    for key in existing:
+        if key not in meta_keys:
+            all_events.add(key)
+    for key in template:
+        if key not in meta_keys:
+            all_events.add(key)
+
+    for event in sorted(all_events):
+        existing_hooks = existing.get(event, {})
+        template_hooks = template.get(event, {})
+        merged_hooks: dict = {}
+
+        for hook_name, hook_data in existing_hooks.items():
+            merged_hooks[hook_name] = dict(hook_data)
+
+        for hook_name, hook_data in template_hooks.items():
+            if hook_name in merged_hooks:
+                user_enabled = merged_hooks[hook_name].get("enabled")
+                merged_hooks[hook_name] = dict(hook_data)
+                if user_enabled is not None:
+                    merged_hooks[hook_name]["enabled"] = user_enabled
+            else:
+                merged_hooks[hook_name] = dict(hook_data)
+
+        if merged_hooks:
+            merged[event] = merged_hooks
+
+    return merged
+
+
 def _claude_settings(aipass_home: str | None = None) -> str:
     """Generate .claude/settings.json — env and permissions only.
 
@@ -221,9 +205,9 @@ def _claude_settings(aipass_home: str | None = None) -> str:
 
     data["permissions"] = {
         "deny": [
-            "Bash(rm -rf *)",
             "Bash(git push --force*)",
             "Bash(git reset --hard*)",
+            "EnterPlanMode",
         ],
     }
 
@@ -332,10 +316,24 @@ def init_project(target: Path, project_name: str | None = None) -> dict:
     aipass_dir = target / ".aipass"
     aipass_dir.mkdir(exist_ok=True)
 
-    global_prompt_path = aipass_dir / "aipass_global_prompt.md"
-    if not global_prompt_path.exists():
-        global_prompt_path.write_text(_resolve_global_prompt(name, aipass_home, global_prompt_path), encoding="utf-8")
-        created.append(str(global_prompt_path))
+    # 2. .aipass/tier0_kernel.md + tier1_navmap.md — tiered prompt injection
+    for tier_file in ("tier0_kernel.md", "tier1_navmap.md"):
+        tier_dest = aipass_dir / tier_file
+        if not tier_dest.exists() and aipass_home:
+            tier_src = Path(aipass_home) / ".aipass" / tier_file
+            if tier_src.is_file():
+                shutil.copy2(str(tier_src), str(tier_dest))
+                created.append(str(tier_dest))
+
+    # 2b. .aipass/hooks.json — project hook config from template
+    hooks_json_path = aipass_dir / "hooks.json"
+    if not hooks_json_path.exists() and aipass_home:
+        template = Path(aipass_home) / ".aipass" / "project_hooks.json"
+        if template.is_file():
+            shutil.copy2(str(template), str(hooks_json_path))
+            created.append(str(hooks_json_path))
+        else:
+            logger.info("hooks template not found at %s — skipping", template)
 
     # 3-5. CLAUDE.md, AGENTS.md — project templates or AIPass source
     for md_name in ("CLAUDE.md", "AGENTS.md"):
@@ -347,6 +345,9 @@ def init_project(target: Path, project_name: str | None = None) -> dict:
             content = template.read_text(encoding="utf-8").replace("{name}", name)
             dest.write_text(content, encoding="utf-8")
             created.append(str(dest))
+        elif md_name == "AGENTS.md":
+            dest.write_text(sc.agents_md(name), encoding="utf-8")
+            created.append(str(dest))
         else:
             source = Path(aipass_home) / md_name if aipass_home else None
             if source and source.is_file():
@@ -362,16 +363,7 @@ def init_project(target: Path, project_name: str | None = None) -> dict:
         readme_md_path.write_text(readme_content, encoding="utf-8")
         created.append(str(readme_md_path))
 
-    # 7. STATUS.local.md
-    status_md_path = target / "STATUS.local.md"
-    if not status_md_path.exists():
-        status_md_path.write_text(
-            f"# {name}\n\n**State:** New\n**Last update:** {today}\n\n## Current Work\n\n## Known Issues\n- None\n",
-            encoding="utf-8",
-        )
-        created.append(str(status_md_path))
-
-    # 8. .gitignore
+    # 7. .gitignore
     gitignore_path = target / ".gitignore"
     if not gitignore_path.exists():
         gitignore_path.write_text(sc.gitignore(), encoding="utf-8")
@@ -395,11 +387,6 @@ def init_project(target: Path, project_name: str | None = None) -> dict:
         prep_path.write_text(sc.prep_md(), encoding="utf-8")
         created.append(str(prep_path))
 
-    # 9d. Ship enforcement + injector hooks from AIPass install
-    if aipass_home:
-        shipped = _ship_hooks(aipass_home, target)
-        created.extend(shipped)
-
     # 10. src/<project>/ package structure (pip-installable from day one)
     package_name = raw_name.lower().replace("-", "_").replace(" ", "_")
     src_dir = target / "src"
@@ -453,7 +440,7 @@ def update_project(target: Path) -> dict:
     """Update managed scaffold files in an existing AIPass project.
 
     Overwrites managed prompt and config files with the latest templates while
-    leaving all user-owned files (registry, README, STATUS.local.md, .gitignore,
+    leaving all user-owned files (registry, README, .gitignore,
     src/) untouched.
 
     Args:
@@ -498,14 +485,21 @@ def update_project(target: Path) -> dict:
 
     # --- Managed files: write only when content has changed ---
 
-    global_prompt_path = aipass_dir / "aipass_global_prompt.md"
     aipass_home = aipass_home or _detect_aipass_home()
-    generated = _resolve_global_prompt(name, aipass_home, global_prompt_path)
-    if not global_prompt_path.exists() or global_prompt_path.read_text(encoding="utf-8") != generated:
-        global_prompt_path.write_text(generated, encoding="utf-8")
-        updated.append(str(global_prompt_path))
-    else:
-        already_current.append(str(global_prompt_path))
+
+    # tier0_kernel.md + tier1_navmap.md — tiered prompt injection
+    for tier_file in ("tier0_kernel.md", "tier1_navmap.md"):
+        tier_dest = aipass_dir / tier_file
+        tier_src = Path(aipass_home) / ".aipass" / tier_file if aipass_home else None
+        if tier_src and tier_src.is_file():
+            canonical = tier_src.read_text(encoding="utf-8")
+            if not tier_dest.exists() or tier_dest.read_text(encoding="utf-8") != canonical:
+                tier_dest.write_text(canonical, encoding="utf-8")
+                updated.append(str(tier_dest))
+            else:
+                already_current.append(str(tier_dest))
+        elif tier_dest.exists():
+            already_current.append(str(tier_dest))
 
     # settings.json — smart merge: preserve user hooks + env, update AIPass hooks
     settings_path = claude_dir / "settings.json"
@@ -531,6 +525,34 @@ def update_project(target: Path) -> dict:
         else:
             already_current.append(str(settings_path))
 
+    # hooks.json — union-merge: preserve user enabled, add new hooks from template
+    hooks_json_path = aipass_dir / "hooks.json"
+    hook_home = aipass_home or _detect_aipass_home()
+    template_path = Path(hook_home) / ".aipass" / "project_hooks.json" if hook_home else None
+    if template_path and template_path.is_file():
+        template_data = json.loads(template_path.read_text(encoding="utf-8"))
+        if hooks_json_path.exists():
+            try:
+                existing_hooks = json.loads(hooks_json_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as exc:
+                logger.info("hooks.json parse failed, rebuilding: %s", exc)
+                existing_hooks = {}
+            merged_hooks = _merge_hooks_json(existing_hooks, template_data)
+            merged_hooks_content = json.dumps(merged_hooks, indent=2, ensure_ascii=False) + "\n"
+            if existing_hooks != merged_hooks:
+                hooks_json_path.write_text(merged_hooks_content, encoding="utf-8")
+                updated.append(str(hooks_json_path))
+            else:
+                already_current.append(str(hooks_json_path))
+        else:
+            hooks_json_path.write_text(
+                json.dumps(template_data, indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+            updated.append(str(hooks_json_path))
+    elif hooks_json_path.exists():
+        already_current.append(str(hooks_json_path))
+
     # CLAUDE.md, AGENTS.md — sync from project templates or AIPass source
     for md_name in ("CLAUDE.md", "AGENTS.md"):
         dest = target / md_name
@@ -557,17 +579,10 @@ def update_project(target: Path) -> dict:
     else:
         already_current.append(str(prep_path))
 
-    # Re-sync enforcement + injector hooks from AIPass install
-    hook_home = aipass_home or _detect_aipass_home()
-    if hook_home:
-        shipped = _ship_hooks(hook_home, target)
-        updated.extend(shipped)
-
     # --- User-owned files: always skip ---
     for skip_name in (
         str(registry_path),
         str(target / "README.md"),
-        str(target / "STATUS.local.md"),
         str(target / ".gitignore"),
     ):
         skipped.append(skip_name)

src/aipass/aipass/apps/handlers/init/scaffold_content.py

@@ -37,11 +37,11 @@ def readme_md(name: str) -> str:
         "aipass init agent my_agent\n"
         "\n"
         "# 2. Start a session\n"
-        "cd src/my_agent/\n"
+        f"cd src/{name.lower()}/my_agent/\n"
         "claude  # or your preferred AI CLI\n"
         "\n"
-        "# 3. Check project status\n"
-        "cat STATUS.local.md\n"
+        "# 3. Check project health\n"
+        "drone @seedgo audit .\n"
         "```\n"
         "\n"
         "## Project Structure\n"
@@ -52,8 +52,7 @@ def readme_md(name: str) -> str:
         "  .aipass/                 # Prompts (injected per-turn)\n"
         "  CLAUDE.md               # Claude Code instructions\n"
         "  AGENTS.md               # Codex instructions\n"
-        "  STATUS.local.md         # Project status\n"
-        "  src/                    # Agent directories live here\n"
+        f"  src/{name.lower()}/              # Project package\n"
         "    <agent_name>/         # Created via aipass init agent\n"
         "```\n"
         "\n"
@@ -83,6 +82,30 @@ def readme_md(name: str) -> str:
     )
 
 
+def agents_md(name: str) -> str:
+    """Generate AGENTS.md content — Codex equivalent of CLAUDE.md for projects."""
+    return (
+        f"# {name}\n"
+        "\n"
+        "Agent workspace powered by AIPass.\n"
+        "\n"
+        "# Startup protocol\n"
+        "\n"
+        "On any greeting, silently run this sequence — no narration, no announcing "
+        "steps. Just do it and respond with the status.\n"
+        "\n"
+        " - Read: `.trinity/passport.json`, `.trinity/local.json`, "
+        "`.trinity/observations.json`, `README.md`\n"
+        "\n"
+        "Use drone commands for all operations. Never raw git, gh, or file access "
+        "when drone provides it.\n"
+        "\n"
+        "# Memories\n"
+        "\n"
+        "Update `.trinity/` at natural breakpoints, after milestones, and on `/memo`.\n"
+    )
+
+
 def global_prompt_md(name: str) -> str:
     """Generate .aipass/aipass_global_prompt.md — injected every turn."""
     return (
@@ -212,7 +235,6 @@ def gitignore() -> str:
         ".trinity/\n"
         ".ai_mail.local/\n"
         "*.local.*\n"
-        "!STATUS.local.md\n"
         "\n"
         "# Plans (local working docs)\n"
         "DPLAN-*\n"
@@ -279,9 +301,6 @@ def prep_md() -> str:
         "- **`.trinity/observations.json`** — YOUR MEMORY OF THE USER. "
         "Collaboration insights, preferences, friction points. Skip if nothing "
         "new about the user this session.\n"
-        "- **`STATUS.local.md`** — PUBLIC STATUS BEACON. Current work, known "
-        "issues, todos, notepad. Auto-synced to central STATUS.md on PR events "
-        "— this is how other branches see you. Keep Current Work accurate.\n"
         "\n"
         "## 2. Active Plans\n"
         "\n"
@@ -308,7 +327,7 @@ def prep_md() -> str:
         "- Flag anything in-flight: running background agents, dispatched "
         "branches waiting for replies, pending decisions\n"
         "- If anything can't survive compaction (e.g., agent IDs needed for "
-        "resume), write it to STATUS.local.md Notepad\n"
+        "resume), write it to local.json key_learnings\n"
         "\n"
         "## Confirm\n"
         "\n"
@@ -317,7 +336,6 @@ def prep_md() -> str:
         "Prep complete:\n"
         "- local.json: [what was added]\n"
         "- observations.json: [updated / skipped]\n"
-        "- STATUS.local.md: [updated / skipped]\n"
         "- Plans: [which ones updated]\n"
         "- Git: [branch, uncommitted count, suggestion]\n"
         "- Inbox: [count, action taken]\n"

src/aipass/aipass/apps/handlers/json/json_handler.py

@@ -1,254 +1,88 @@
 # =================== AIPass ====================
 # Name: json_handler.py
-# Description: Auto-Creating JSON Handler for aipass branch
-# Version: 1.0.0
+# Description: Branch-local shim — delegates to aipass.aipass.shared.json_handler
+# Version: 2.0.0
 # Created: 2026-04-16
-# Modified: 2026-04-16
+# Modified: 2026-06-06
 # =============================================
 
-"""
-JSON Handler - Auto-Creating & Self-Healing JSON System
+"""Branch-local JSON handler — thin shim over the shared ``aipass.aipass.shared`` library.
 
-Handles default JSON files (config, data, log) for aipass modules.
-Never manually create JSONs - they build themselves.
+All logic lives in ``aipass.aipass.shared.json_handler.JsonHandler``.
+This module binds a ``JsonHandler`` instance to the aipass branch's
+``aipass_json/`` directory and re-exports the public API as module-level
+functions so existing callers (``json_handler.log_operation(...)``) keep working.
 """
 
 from __future__ import annotations
 
 import inspect
-import json
-import os
-import tempfile
-from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from aipass.prax import logger
+from aipass.aipass.shared.json_handler import JsonHandler
+
+
+def _get_caller_module_name() -> str:
+    """Auto-detect calling module name from call stack."""
+    stack = inspect.stack()
+    if len(stack) > 2:
+        caller_path = Path(stack[2].filename)
+        module_name = caller_path.stem
+        if module_name and not module_name.startswith("_"):
+            return module_name
+    return "unknown"
 
-# =============================================================================
-# INFRASTRUCTURE SETUP
-# =============================================================================
 
-# json_handler.py lives at: src/aipass/aipass/apps/handlers/json/json_handler.py
-# parents[0] = json/, [1] = handlers/, [2] = apps/, [3] = aipass/, [4] = src/aipass/
 _PKG_ROOT = Path(__file__).resolve().parents[4]
 
-# Constants
 AIPASS_BRANCH_ROOT = _PKG_ROOT / "aipass"
 AIPASS_JSON_DIR = AIPASS_BRANCH_ROOT / "aipass_json"
 
 
-# =============================================================================
-# INTERNAL HELPERS
-# =============================================================================
+def _handler() -> JsonHandler:
+    """Create a handler bound to the current AIPASS_JSON_DIR."""
+    return JsonHandler(AIPASS_JSON_DIR)
 
 
-def _get_caller_module_name() -> str:
-    """Auto-detect calling module name from call stack.
-
-    Returns:
-        Module name (e.g., "doctor" from doctor.py)
-    """
-    try:
-        stack = inspect.stack()
-        # Skip frames: [0]=this function, [1]=log_operation, [2]=actual caller
-        if len(stack) > 2:
-            caller_frame = stack[2]
-            caller_path = Path(caller_frame.filename)
-            module_name = caller_path.stem
-
-            if module_name and not module_name.startswith("_"):
-                return module_name
-
-        return "unknown"
-    except Exception as exc:
-        logger.warning("[json_handler] Failed to detect caller module name: %s", exc)
-        return "unknown"
+def load_path(file_path: Path) -> Optional[dict]:
+    """Load JSON from an arbitrary file path."""
+    return JsonHandler.read_json(file_path)
 
 
-def _default_template(json_type: str, module_name: str) -> Any:
-    """Return inline default structure for a JSON type — no file templates needed."""
-    today = datetime.now().date().isoformat()
-    if json_type == "config":
-        return {
-            "module_name": module_name,
-            "version": "1.0.0",
-            "config": {
-                "max_log_entries": 100,
-            },
-            "created": today,
-        }
-    if json_type == "data":
-        return {
-            "created": today,
-            "last_updated": today,
-        }
-    if json_type == "log":
-        return []
-    return None
-
-
-def _atomic_write_json(target_path: Path, data: Any) -> None:
-    """Write JSON data atomically via temp file + rename.
-
-    Prevents corruption from concurrent processes writing the same file.
-    """
-    fd, tmp_path = tempfile.mkstemp(dir=str(target_path.parent), suffix=".tmp", prefix=target_path.stem)
-    succeeded = False
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            json.dump(data, f, indent=2, ensure_ascii=False)
-        os.replace(tmp_path, str(target_path))
-        succeeded = True
-    finally:
-        if not succeeded and Path(tmp_path).exists():
-            logger.warning("[json_handler] Cleaning up temp file after write failure: %s", tmp_path)
-            os.unlink(tmp_path)
-
-
-# =============================================================================
-# VALIDATION
-# =============================================================================
+def save_path(file_path: Path, data: Any, indent: int = 2) -> bool:
+    """Write JSON data to an arbitrary file path atomically."""
+    return JsonHandler.write_json(file_path, data, indent)
 
 
 def validate_json_structure(data: Any, json_type: str) -> bool:
-    """Validate JSON structure matches expected type."""
-    if json_type == "config":
-        if not isinstance(data, dict):
-            return False
-        required = ["module_name", "version", "config"]
-        return all(key in data for key in required)
-
-    elif json_type == "data":
-        if not isinstance(data, dict):
-            return False
-        required = ["created", "last_updated"]
-        return all(key in data for key in required)
-
-    elif json_type == "log":
-        return isinstance(data, list)
-
-    return False
-
-
-# =============================================================================
-# PUBLIC API
-# =============================================================================
-
-
-def load_path(path: Path) -> Any:
-    """Load JSON from an arbitrary file path with consistent error handling."""
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except (json.JSONDecodeError, OSError) as exc:
-        logger.warning("[json_handler] Failed to load %s: %s", path, exc)
-        return None
-
-
-def save_path(path: Path, data: Any) -> bool:
-    """Write JSON data to an arbitrary file path atomically."""
-    os.makedirs(path.parent, exist_ok=True)
-    fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp", prefix=path.stem)
-    succeeded = False
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            json.dump(data, f, indent=2, ensure_ascii=False)
-            f.write("\n")
-        os.replace(tmp_path, str(path))
-        succeeded = True
-        return True
-    except OSError as exc:
-        logger.warning("[json_handler] Failed to save %s: %s", path, exc)
-        return False
-    finally:
-        if not succeeded and Path(tmp_path).exists():
-            os.unlink(tmp_path)
+    """Validate that data matches the expected shape for json_type."""
+    return JsonHandler.validate_json_structure(data, json_type)
 
 
 def get_json_path(module_name: str, json_type: str) -> Path:
-    """Get path for module JSON file."""
-    filename = f"{module_name}_{json_type}.json"
-    return AIPASS_JSON_DIR / filename
+    """Return the filesystem path for a module's JSON file."""
+    return _handler().get_json_path(module_name, json_type)
 
 
 def ensure_json_exists(module_name: str, json_type: str) -> bool:
-    """Ensure JSON file exists, create from template if missing."""
-    AIPASS_JSON_DIR.mkdir(parents=True, exist_ok=True)
-
-    json_path = get_json_path(module_name, json_type)
-
-    if json_path.exists():
-        try:
-            with open(json_path, "r", encoding="utf-8") as f:
-                data = json.load(f)
-
-            if validate_json_structure(data, json_type):
-                return True
-        except Exception as exc:
-            logger.warning(
-                "[json_handler] Corrupted JSON file for '%s/%s', regenerating: %s",
-                module_name,
-                json_type,
-                exc,
-            )
-
-    template = _default_template(json_type, module_name)
-    if template is None:
-        return False
-
-    try:
-        _atomic_write_json(json_path, template)
-        return True
-    except Exception as exc:
-        logger.error(
-            "[json_handler] Failed to write JSON template for '%s/%s': %s",
-            module_name,
-            json_type,
-            exc,
-        )
-        return False
-
-
-def load_json(module_name: str, json_type: str) -> Optional[Any]:
-    """Load JSON file, auto-create if missing."""
-    if not ensure_json_exists(module_name, json_type):
-        return None
-
-    json_path = get_json_path(module_name, json_type)
-
-    try:
-        with open(json_path, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except Exception as exc:
-        logger.error("[json_handler] Failed to load JSON for '%s/%s': %s", module_name, json_type, exc)
-        return None
-
-
-def save_json(module_name: str, json_type: str, data: Any) -> bool:
-    """Save JSON file."""
-    json_path = get_json_path(module_name, json_type)
-
-    if not validate_json_structure(data, json_type):
-        return False
-
-    if json_type == "data" and isinstance(data, dict):
-        data["last_updated"] = datetime.now().date().isoformat()
-
-    try:
-        _atomic_write_json(json_path, data)
-        return True
-    except Exception as exc:
-        logger.error("[json_handler] Failed to save JSON for '%s/%s': %s", module_name, json_type, exc)
-        return False
+    """Ensure a single JSON file exists; create with defaults if missing."""
+    return _handler().ensure_json_exists(module_name, json_type)
 
 
 def ensure_module_jsons(module_name: str) -> bool:
-    """Ensure all 3 JSON files exist for a module."""
-    ensure_json_exists(module_name, "config")
-    ensure_json_exists(module_name, "data")
-    ensure_json_exists(module_name, "log")
-    return True
+    """Ensure all three JSON files (config, data, log) exist for a module."""
+    return _handler().ensure_module_jsons(module_name)
+
+
+def load_json(module_name: str, json_type: str) -> Optional[Any]:
+    """Load a module's JSON file, auto-creating it if missing."""
+    return _handler().load_json(module_name, json_type)
+
+
+def save_json(module_name: str, json_type: str, data: Any) -> bool:
+    """Save JSON file. Raises ValueError on invalid structure."""
+    return _handler().save_json(module_name, json_type, data)
 
 
 def log_operation(
@@ -256,42 +90,7 @@ def log_operation(
     data: Dict[str, Any] | None = None,
     module_name: str | None = None,
 ) -> bool:
-    """Add entry to module log with automatic rotation.
-
-    Auto-detects calling module if module_name not provided.
-    Implements config-controlled log limits to prevent unbounded growth.
-    When max_log_entries is reached, removes oldest entries (FIFO).
-
-    Args:
-        operation: Operation name to log
-        data: Optional data dict
-        module_name: Optional module name (auto-detected if not provided)
-
-    Returns:
-        True if successful, False otherwise
-    """
+    """Add entry to module operation log with automatic rotation."""
     if module_name is None:
         module_name = _get_caller_module_name()
-
-    ensure_module_jsons(module_name)
-
-    config = load_json(module_name, "config")
-    max_entries = 100
-    if config and "config" in config:
-        max_entries = config["config"].get("max_log_entries", 100)
-
-    log = load_json(module_name, "log")
-    if log is None:
-        log = []
-
-    entry: Dict[str, Any] = {"timestamp": datetime.now().isoformat(), "operation": operation}
-
-    if data:
-        entry["data"] = data
-
-    log.append(entry)
-
-    if len(log) > max_entries:
-        log = log[-max_entries:]
-
-    return save_json(module_name, "log", log)
+    return _handler().log_operation(operation, data, module_name)

src/aipass/aipass/apps/handlers/provider_reconcile.py

@@ -0,0 +1,81 @@
+# =================== AIPass ====================
+# Name: provider_reconcile.py
+# Description: Detect and fix stale rules in provider settings
+# Version: 1.0.0
+# Created: 2026-06-05
+# Modified: 2026-06-05
+# =============================================
+
+"""provider_reconcile — detect and fix stale rules in ~/.claude/settings.json."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from aipass.prax import logger
+
+from aipass.aipass.apps.handlers.json import json_handler
+
+_MODULE_NAME = "provider_reconcile"
+
+_STALE_RM_DENY_RULES = frozenset({"Bash(rm -rf*)", "Bash(rm -r *)"})
+
+GLYPH_PASS = "[green]✓[/green]"
+GLYPH_WARN = "[yellow]![/yellow]"
+
+
+def reconcile_stale_deny(fix: bool = False) -> list:
+    """Detect and optionally remove stale rm deny rules from provider settings.
+
+    Returns list of (label, glyph, detail, remediation) tuples matching
+    doctor.CheckResult shape — imported as tuples to avoid circular import.
+    """
+    results: list = []
+    settings_path = Path.home() / ".claude" / "settings.json"
+
+    if not settings_path.exists():
+        json_handler.log_operation(
+            "reconcile_stale_deny",
+            data={"fix": fix, "skipped": "no settings file"},
+            module_name=_MODULE_NAME,
+        )
+        return results
+
+    data = json_handler.load_path(settings_path)
+    if data is None:
+        json_handler.log_operation(
+            "reconcile_stale_deny",
+            data={"fix": fix, "skipped": "could not load settings"},
+            module_name=_MODULE_NAME,
+        )
+        return results
+
+    deny = data.get("permissions", {}).get("deny", [])
+    stale = [r for r in deny if r in _STALE_RM_DENY_RULES]
+
+    if not stale:
+        results.append(("rm deny migration", GLYPH_PASS, "no stale rules", ""))
+    elif fix:
+        deny_cleaned = [r for r in deny if r not in _STALE_RM_DENY_RULES]
+        data.setdefault("permissions", {})["deny"] = deny_cleaned
+        json_handler.save_path(settings_path, data)
+        removed = ", ".join(stale)
+        results.append(("rm deny migration", GLYPH_PASS, f"removed: {removed}", ""))
+        logger.info("[doctor] removed stale deny rules: %s", stale)
+    else:
+        found = ", ".join(stale)
+        results.append(
+            (
+                "rm deny migration",
+                GLYPH_WARN,
+                f"stale rules: {found}",
+                "Run aipass doctor --fix to remove (rm_gate + drone rm replace these)",
+            )
+        )
+
+    json_handler.log_operation(
+        "reconcile_stale_deny",
+        data={"fix": fix, "stale_found": len(stale)},
+        module_name=_MODULE_NAME,
+    )
+    return results

src/aipass/aipass/apps/handlers/readme_map/__init__.py

@@ -117,3 +117,18 @@ def list_branches() -> list[str]:
     Reflects the filesystem state at the time the map was first built.
     """
     return list(_get_map().keys())
+
+
+def read_readme_lines(branch: str) -> list[str] | None:
+    """Live-read README.md for a branch. Returns list of lines, or None on error.
+
+    Content is NEVER cached — every call reads the current file.
+    """
+    readme_path = get_readme_path(branch)
+    if readme_path is None:
+        return None
+    try:
+        with open(readme_path, encoding="utf-8") as fh:
+            return fh.readlines()
+    except OSError:
+        return None

src/aipass/aipass/apps/handlers/sandbox_check/__init__.py

@@ -0,0 +1,21 @@
+"""sandbox_check — Kernel sandbox prerequisite detection for aipass doctor."""
+
+from aipass.aipass.apps.handlers.sandbox_check.sandbox_checker import (  # type: ignore[import-not-found]
+    check_broker_alive,
+    check_bwrap_functional,
+    check_bwrap_present,
+    check_node_present,
+    check_rg_present,
+    check_sandbox_flag,
+    check_srt_resolvable,
+)
+
+__all__ = [
+    "check_broker_alive",
+    "check_bwrap_functional",
+    "check_bwrap_present",
+    "check_node_present",
+    "check_rg_present",
+    "check_sandbox_flag",
+    "check_srt_resolvable",
+]

src/aipass/aipass/apps/handlers/sandbox_check/sandbox_checker.py

@@ -0,0 +1,253 @@
+# =================== AIPass ====================
+# Name: sandbox_checker.py
+# Description: Kernel sandbox prerequisite checks for aipass doctor
+# Version: 1.0.0
+# Created: 2026-06-10
+# Modified: 2026-06-10
+# =============================================
+
+"""Sandbox prerequisite checker — detects bwrap, node, srt, rg, broker.
+
+Returns plain dicts with facts about sandbox readiness.
+No Rich markup — display concerns belong to the UI layer.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+from aipass.prax import logger
+from aipass.aipass.apps.handlers.json import json_handler
+
+
+def check_sandbox_flag() -> Dict[str, Any]:
+    """Check AIPASS_SANDBOX_ENABLED env var state.
+
+    Returns:
+        enabled: bool
+        raw_value: str — the raw env value (empty if unset)
+    """
+    raw = os.environ.get("AIPASS_SANDBOX_ENABLED", "")
+    enabled = raw.lower() in ("1", "true", "yes")
+    json_handler.log_operation("sandbox_check_flag", {"enabled": enabled, "raw": raw})
+    return {"enabled": enabled, "raw_value": raw}
+
+
+def check_bwrap_present() -> Dict[str, Any]:
+    """Check if bubblewrap (bwrap) binary is on PATH.
+
+    Returns:
+        found: bool
+        path: str | None — resolved path if found
+    """
+    path = shutil.which("bwrap")
+    json_handler.log_operation("sandbox_check_bwrap_present", {"found": bool(path)})
+    return {"found": bool(path), "path": path}
+
+
+def check_bwrap_functional() -> Dict[str, Any]:
+    """Run a trivial bwrap sandbox to verify it actually works.
+
+    Catches AppArmor/userns restrictions that make bwrap present but blocked.
+
+    Returns:
+        ok: bool
+        detail: str — success message or error detail
+        sysctl_value: str | None — kernel.apparmor_restrict_unprivileged_userns on failure
+    """
+    bwrap = shutil.which("bwrap")
+    if not bwrap:
+        return {"ok": False, "detail": "bwrap not found", "sysctl_value": None}
+
+    try:
+        proc = subprocess.run(
+            [bwrap, "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", "true"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+        if proc.returncode == 0:
+            json_handler.log_operation("sandbox_check_bwrap_functional", {"ok": True})
+            return {"ok": True, "detail": "trivial sandbox succeeded", "sysctl_value": None}
+
+        sysctl_val = _read_userns_sysctl()
+        detail = f"exit {proc.returncode}"
+        if proc.stderr.strip():
+            detail = f"{detail}: {proc.stderr.strip()[:200]}"
+        json_handler.log_operation("sandbox_check_bwrap_functional", {"ok": False, "detail": detail})
+        return {"ok": False, "detail": detail, "sysctl_value": sysctl_val}
+
+    except subprocess.TimeoutExpired:
+        logger.warning("[sandbox_check] bwrap functional test timed out")
+        return {"ok": False, "detail": "timed out (10s)", "sysctl_value": None}
+    except OSError as exc:
+        logger.warning("[sandbox_check] bwrap functional test error: %s", exc)
+        return {"ok": False, "detail": str(exc), "sysctl_value": None}
+
+
+def _read_userns_sysctl() -> str | None:
+    """Read kernel.apparmor_restrict_unprivileged_userns sysctl if available."""
+    try:
+        proc = subprocess.run(
+            ["sysctl", "-n", "kernel.apparmor_restrict_unprivileged_userns"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+        if proc.returncode == 0:
+            return proc.stdout.strip()
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError) as exc:
+        logger.info("[sandbox_check] sysctl read failed (expected on non-Ubuntu): %s", exc)
+    return None
+
+
+def check_node_present() -> Dict[str, Any]:
+    """Check if node binary is on PATH.
+
+    Returns:
+        found: bool
+        path: str | None — resolved path if found
+    """
+    path = shutil.which("node")
+    json_handler.log_operation("sandbox_check_node", {"found": bool(path)})
+    return {"found": bool(path), "path": path}
+
+
+def check_srt_resolvable() -> Dict[str, Any]:
+    """Check if @anthropic-ai/sandbox-runtime is resolvable via node.
+
+    Mirrors _srt_resolve.mjs resolution: derive node prefix from process.execPath,
+    then check <prefix>/lib/node_modules/@anthropic-ai/sandbox-runtime/dist/index.js.
+
+    Returns:
+        found: bool
+        path: str | None — resolved entry path if found
+        install_hint: str — npm install command if missing
+    """
+    node = shutil.which("node")
+    if not node:
+        return {
+            "found": False,
+            "path": None,
+            "install_hint": "Install node first, then: npm install -g @anthropic-ai/sandbox-runtime",
+        }
+
+    try:
+        script = (
+            "const p = require('path');"
+            "const prefix = p.dirname(p.dirname(process.execPath));"
+            "const entry = p.join(prefix, 'lib/node_modules/@anthropic-ai/sandbox-runtime/dist/index.js');"
+            "const fs = require('fs');"
+            "if (fs.existsSync(entry)) { process.stdout.write(entry); }"
+            "else { process.exit(1); }"
+        )
+        proc = subprocess.run(
+            [node, "-e", script],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+        if proc.returncode == 0 and proc.stdout.strip():
+            path = proc.stdout.strip()
+            json_handler.log_operation("sandbox_check_srt", {"found": True, "path": path})
+            return {"found": True, "path": path, "install_hint": ""}
+
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError) as exc:
+        logger.warning("[sandbox_check] srt resolve error: %s", exc)
+
+    json_handler.log_operation("sandbox_check_srt", {"found": False})
+    return {
+        "found": False,
+        "path": None,
+        "install_hint": "npm install -g @anthropic-ai/sandbox-runtime",
+    }
+
+
+def check_rg_present() -> Dict[str, Any]:
+    """Check if ripgrep (rg) is available — matches hooks' fallback logic.
+
+    Returns:
+        found: bool
+        path: str | None — resolved path if found
+    """
+    rg = shutil.which("rg")
+    if rg:
+        json_handler.log_operation("sandbox_check_rg", {"found": True, "path": rg})
+        return {"found": True, "path": rg}
+
+    fallback = Path.home() / ".local" / "bin" / "rg"
+    if fallback.is_file():
+        path = str(fallback)
+        json_handler.log_operation("sandbox_check_rg", {"found": True, "path": path})
+        return {"found": True, "path": path}
+
+    json_handler.log_operation("sandbox_check_rg", {"found": False})
+    return {"found": False, "path": None}
+
+
+def check_broker_alive(repo_root: Path | None = None) -> Dict[str, Any]:
+    """Check if the broker daemon socket is accepting connections.
+
+    Args:
+        repo_root: Project root containing .ai_central/. Auto-detected if None.
+
+    Returns:
+        alive: bool
+        detail: str — status message
+    """
+    sock_path = _find_broker_socket(repo_root)
+    if sock_path is None:
+        json_handler.log_operation("sandbox_check_broker", {"alive": False, "reason": "socket_not_found"})
+        return {"alive": False, "detail": "broker socket not found"}
+
+    if not sock_path.exists():
+        json_handler.log_operation("sandbox_check_broker", {"alive": False, "reason": "socket_missing"})
+        return {"alive": False, "detail": f"socket missing: {sock_path}"}
+
+    try:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(2)
+        s.connect(str(sock_path))
+        s.close()
+        json_handler.log_operation("sandbox_check_broker", {"alive": True})
+        return {"alive": True, "detail": "connected"}
+    except (OSError, socket.timeout) as exc:
+        logger.info("[sandbox_check] broker connect failed: %s", exc)
+        json_handler.log_operation("sandbox_check_broker", {"alive": False, "reason": str(exc)})
+        return {"alive": False, "detail": f"connect failed: {exc}"}
+
+
+def _find_broker_socket(repo_root: Path | None) -> Path | None:
+    """Locate the broker socket under $REPO/.ai_central/drone_broker.sock."""
+    if repo_root and (repo_root / ".ai_central" / "drone_broker.sock").parent.is_dir():
+        return repo_root / ".ai_central" / "drone_broker.sock"
+
+    aipass_home = os.environ.get("AIPASS_HOME", "")
+    if aipass_home:
+        candidate = Path(aipass_home) / ".ai_central" / "drone_broker.sock"
+        if candidate.parent.is_dir():
+            return candidate
+
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        candidate = parent / ".ai_central" / "drone_broker.sock"
+        if candidate.parent.is_dir():
+            return candidate
+        if parent == parent.parent:
+            break
+
+    return None
+
+
+def is_linux() -> bool:
+    """Return True if running on Linux."""
+    return sys.platform.startswith("linux")

src/aipass/aipass/apps/handlers/structure_scan/structure_scanner.py

@@ -283,12 +283,6 @@ def detect_pollution(agents: List[AgentInfo]) -> List[PollutionHit]:
 # =============================================================================
 
 
-def find_registry(project_root: Path) -> Optional[Path]:
-    """Find *_REGISTRY.json under project_root."""
-    candidates = list(project_root.glob("*_REGISTRY.json"))
-    return candidates[0] if candidates else None
-
-
 def check_registry_consistency(
     registry_path: Path,
     agents: List[AgentInfo],

src/aipass/aipass/apps/modules/doctor.py

@@ -6,11 +6,7 @@
 # Modified: 2026-04-16
 # =============================================
 
-"""
-aipass doctor — system health aggregation
-
-Run: aipass doctor [--verbose] [--fix] [--fix --json]
-"""
+"""aipass doctor — system health aggregation."""
 
 from __future__ import annotations
 
@@ -24,7 +20,19 @@ from typing import Dict, List, NamedTuple
 from aipass.cli.apps.modules import console
 from aipass.prax import logger
 
+from aipass.aipass.shared.registry_discovery import find_registry as _discover_registry
+
 from aipass.aipass.apps.handlers.json import json_handler
+from aipass.aipass.apps.handlers.sandbox_check.sandbox_checker import (
+    check_broker_alive,
+    check_bwrap_functional,
+    check_bwrap_present,
+    check_node_present,
+    check_rg_present,
+    check_sandbox_flag,
+    check_srt_resolvable,
+    is_linux,
+)
 from aipass.aipass.apps.handlers.structure_scan.structure_scanner import (
     check_placement,
     check_pyproject,
@@ -32,7 +40,6 @@ from aipass.aipass.apps.handlers.structure_scan.structure_scanner import (
     check_root_artifacts,
     detect_pollution,
     find_project_root,
-    find_registry,
     scan_agents,
 )
 from aipass.aipass.apps.modules.doctor_fix import (
@@ -42,6 +49,7 @@ from aipass.aipass.apps.modules.doctor_fix import (
 from aipass.aipass.apps.modules.doctor_wire import (
     _auto_wire_provider,
     prompt_auto_wire,
+    reconcile_stale_deny,
 )
 from aipass.aipass.apps.handlers.system_detect.system_detector import (
     detect_cpu,
@@ -60,10 +68,6 @@ from aipass.aipass.apps.handlers.ui.progress import (
     make_doctor_progress,
 )
 
-# =============================================================================
-# TYPES
-# =============================================================================
-
 _BRANCH_ROOT = Path(__file__).resolve().parents[2]
 
 
@@ -76,30 +80,10 @@ class CheckResult(NamedTuple):
     remediation: str
 
 
-# =============================================================================
-# IDENTITY HELPERS
-# =============================================================================
-
-
 def _find_registry() -> Path | None:
-    """Walk up from CWD first (user's project), then branch root."""
-    cwd = Path.cwd()
-    for parent in (cwd, *cwd.parents):
-        candidates = list(parent.glob("*_REGISTRY.json"))
-        if candidates:
-            return candidates[0]
-        if parent == parent.parent:
-            break
-    for parent in (_BRANCH_ROOT, *_BRANCH_ROOT.parents):
-        candidate = parent / "AIPASS_REGISTRY.json"
-        if candidate.exists():
-            return candidate
-    return None
-
-
-# =============================================================================
-# CHECK GROUPS
-# =============================================================================
+    """Find *_REGISTRY.json via shared discovery (walk-up from CWD + branch root)."""
+    result = _discover_registry(package_root=str(_BRANCH_ROOT))
+    return result if result.exists() else None
 
 
 def _check_system() -> List[CheckResult]:
@@ -159,11 +143,10 @@ def _check_identity() -> List[CheckResult]:
     """Run Identity group checks."""
     results: List[CheckResult] = []
 
-    # Project root — derived from registry location
-    reg = _find_registry()
-    project_root = str(reg.parent) if reg else ""
-    if project_root:
-        results.append(CheckResult("AIPASS_HOME", GLYPH_PASS, project_root, ""))
+    # Project root + registry — single lookup
+    reg_path = _find_registry()
+    if reg_path:
+        results.append(CheckResult("AIPASS_HOME", GLYPH_PASS, str(reg_path.parent), ""))
     else:
         home = os.environ.get("AIPASS_HOME", "")
         if home:
@@ -178,8 +161,6 @@ def _check_identity() -> List[CheckResult]:
                 )
             )
 
-    # Registry present
-    reg_path = _find_registry()
     if reg_path is None:
         results.append(CheckResult("registry", GLYPH_FAIL, "not found", "Run 'aipass init' to create registry"))
         return results
@@ -201,6 +182,20 @@ def _check_identity() -> List[CheckResult]:
     else:
         results.append(CheckResult("registry valid", GLYPH_FAIL, "missing 'branches' key", "Re-run 'aipass init'"))
 
+    # hooks.json presence (project-level hook config)
+    hooks_json = reg_path.parent / ".aipass" / "hooks.json"
+    if hooks_json.exists():
+        results.append(CheckResult("hooks.json", GLYPH_PASS, "present", ""))
+    else:
+        results.append(
+            CheckResult(
+                "hooks.json",
+                GLYPH_WARN,
+                "not found",
+                "Run 'aipass init update' to create .aipass/hooks.json",
+            )
+        )
+
     # Passport readable
     passport = _BRANCH_ROOT / ".trinity" / "passport.json"
     if passport.exists():
@@ -449,6 +444,10 @@ def _check_services(verbose: bool = False) -> List[CheckResult]:
     manifest_checks = _check_provider_manifest()
     results.extend(manifest_checks)
 
+    # stale rm deny rules — detect only (fix runs in run_doctor when --fix)
+    for tup in reconcile_stale_deny(fix=False):
+        results.append(CheckResult(*tup))
+
     return results
 
 
@@ -478,9 +477,7 @@ def _check_community() -> List[CheckResult]:
     return results
 
 
-# =============================================================================
-# STRUCTURE CHECK GROUP
-# =============================================================================
+# --- Structure check group ---
 
 
 def _check_structure() -> List[CheckResult]:
@@ -525,8 +522,8 @@ def _check_structure() -> List[CheckResult]:
         results.append(CheckResult("pollution", GLYPH_PASS, "no duplicates", ""))
 
     # Registry consistency
-    reg_path = find_registry(project_root)
-    if reg_path:
+    reg_path = _discover_registry(start_path=project_root)
+    if reg_path and reg_path.exists():
         reg_issues = check_registry_consistency(reg_path, agents)
         if reg_issues:
             for issue in reg_issues:
@@ -558,13 +555,105 @@ def _check_structure() -> List[CheckResult]:
     return results
 
 
-# =============================================================================
-# MAIN DOCTOR RUN
-# =============================================================================
+# --- Sandbox check group ---
+
+
+def _check_sandbox() -> List[CheckResult]:
+    """Run Sandbox group checks — kernel sandbox prerequisites."""
+    results: List[CheckResult] = []
+
+    if not is_linux():
+        results.append(CheckResult("sandbox", GLYPH_PASS, "kernel sandbox: Linux-only, not checked", ""))
+        return results
+
+    flag = check_sandbox_flag()
+    flag_on = flag["enabled"]
+    flag_label = "ON" if flag_on else "OFF"
+    results.append(CheckResult("sandbox flag", GLYPH_PASS, f"AIPASS_SANDBOX_ENABLED={flag_label}", ""))
+
+    def _sev(ok: bool) -> str:
+        if ok:
+            return GLYPH_PASS
+        return GLYPH_FAIL if flag_on else GLYPH_WARN
+
+    def _suffix(ok: bool) -> str:
+        if ok or flag_on:
+            return ""
+        return " (inert — flag is off)"
+
+    bwrap = check_bwrap_present()
+    results.append(
+        CheckResult(
+            "bwrap",
+            _sev(bwrap["found"]),
+            bwrap["path"] or "not found" + _suffix(bwrap["found"]),
+            "" if bwrap["found"] else "sudo apt install bubblewrap",
+        )
+    )
+
+    if bwrap["found"]:
+        func = check_bwrap_functional()
+        detail = func["detail"]
+        if not func["ok"] and func["sysctl_value"] is not None:
+            detail = f"{detail} (apparmor_restrict_unprivileged_userns={func['sysctl_value']})"
+        results.append(
+            CheckResult(
+                "bwrap functional",
+                _sev(func["ok"]),
+                detail + _suffix(func["ok"]),
+                "",
+            )
+        )
+
+    node = check_node_present()
+    results.append(
+        CheckResult(
+            "node",
+            _sev(node["found"]),
+            node["path"] or "not found" + _suffix(node["found"]),
+            "" if node["found"] else "Install Node.js: https://nodejs.org/",
+        )
+    )
+
+    srt = check_srt_resolvable()
+    results.append(
+        CheckResult(
+            "srt (@anthropic-ai/sandbox-runtime)",
+            _sev(srt["found"]),
+            srt["path"] or "not found" + _suffix(srt["found"]),
+            "" if srt["found"] else srt["install_hint"],
+        )
+    )
+
+    rg = check_rg_present()
+    results.append(
+        CheckResult(
+            "rg (ripgrep)",
+            _sev(rg["found"]),
+            rg["path"] or "not found" + _suffix(rg["found"]),
+            "" if rg["found"] else "sudo apt install ripgrep  (or static binary to ~/.local/bin/rg)",
+        )
+    )
+
+    project_root = find_project_root(Path.cwd())
+    broker = check_broker_alive(project_root)
+    results.append(
+        CheckResult(
+            "broker daemon",
+            _sev(broker["alive"]),
+            broker["detail"] + _suffix(broker["alive"]),
+            "",
+        )
+    )
+
+    return results
+
+
+# --- Main doctor run ---
 
 
 def run_doctor(verbose: bool = False, interactive: bool = False, fix: bool = False) -> int:
-    """Run all five groups and print results. Returns error count."""
+    """Run all six groups and print results. Returns error count."""
     console.print()
     console.print("[bold cyan]aipass doctor[/bold cyan]")
     console.print()
@@ -575,6 +664,7 @@ def run_doctor(verbose: bool = False, interactive: bool = False, fix: bool = Fal
         ("Services", lambda: _check_services(verbose=verbose)),
         ("Community", _check_community),
         ("Structure", _check_structure),
+        ("Sandbox", _check_sandbox),
     ]
     groups: Dict[str, List[CheckResult]] = {}
     with make_doctor_progress() as progress:
@@ -590,6 +680,12 @@ def run_doctor(verbose: bool = False, interactive: bool = False, fix: bool = Fal
                 r for r in groups.get("Services", []) if r.label not in ("hooks", "env vars", "permissions")
             ] + manifest_results
 
+    if fix:
+        stale_results = [CheckResult(*tup) for tup in reconcile_stale_deny(fix=True)]
+        if stale_results:
+            services = groups.get("Services", [])
+            groups["Services"] = [r for r in services if r.label != "rm deny migration"] + stale_results
+
     pass_count = 0
     warn_count = 0
     error_count = 0
@@ -620,9 +716,7 @@ def run_doctor(verbose: bool = False, interactive: bool = False, fix: bool = Fal
     return error_count
 
 
-# =============================================================================
-# OUTPUT FORMATTING
-# =============================================================================
+# --- Output formatting ---
 
 
 def print_introspection() -> None:
@@ -631,7 +725,7 @@ def print_introspection() -> None:
     console.print("[bold cyan]doctor Module[/bold cyan]")
     console.print("System health aggregation — flutter-doctor-style output")
     console.print()
-    console.print("[yellow]Groups:[/yellow] System, Identity, Services, Community, Structure")
+    console.print("[yellow]Groups:[/yellow] System, Identity, Services, Community, Structure, Sandbox")
     console.print("[yellow]Next:[/yellow]  [green]aipass doctor[/green] / [green]aipass doctor --fix[/green]")
     console.print()
 
@@ -652,9 +746,7 @@ def print_help() -> None:
     console.print()
 
 
-# =============================================================================
-# COMMAND HANDLER
-# =============================================================================
+# --- Command handler ---
 
 
 def handle_command(command: str, args: list[str]) -> bool:
@@ -670,15 +762,11 @@ def handle_command(command: str, args: list[str]) -> bool:
     if command != "doctor":
         return False
 
-    if not args:
-        print_introspection()
-        return True
-
-    if args[0] in ("--help", "-h", "help"):
+    if args and args[0] in ("--help", "-h", "help"):
         print_help()
         return True
 
-    if args[0] == "--info":
+    if args and args[0] == "--info":
         print_introspection()
         return True
 

src/aipass/aipass/apps/modules/doctor_fix.py

@@ -25,6 +25,8 @@ from typing import List, NamedTuple
 from aipass.cli.apps.modules import console
 from aipass.prax import logger
 
+from aipass.aipass.shared.registry_discovery import find_registry as _discover_registry
+
 from aipass.aipass.apps.handlers.json import json_handler
 from aipass.aipass.apps.handlers.structure_scan.structure_scanner import (
     check_placement,
@@ -32,7 +34,6 @@ from aipass.aipass.apps.handlers.structure_scan.structure_scanner import (
     check_registry_consistency,
     check_root_artifacts,
     detect_pollution,
-    find_registry,
     scan_agents,
 )
 
@@ -58,8 +59,8 @@ class RemediationItem(NamedTuple):
 
 def detect_project_name(project_root: Path) -> str:
     """Derive project name from registry filename or directory name."""
-    reg = find_registry(project_root)
-    if reg:
+    reg = _discover_registry(start_path=project_root)
+    if reg and reg.exists():
         name = reg.stem.replace("_REGISTRY", "").lower()
         if name:
             return name
@@ -83,7 +84,7 @@ def _build_pollution_items(agents: list, project: str) -> List[RemediationItem]:
                     f"Registry pollution: {len(hit.locations)} copies of "
                     f"{hit.agent_name} share registry_id {hit.registry_id}"
                 ),
-                fix_command=f"drone @spawn repair @{project} --clean-pollution",
+                fix_command=f"drone @spawn repair @{project} --clean-pollution --apply",
             )
         )
     return items
@@ -104,7 +105,7 @@ def _build_placement_items(agents: list, project_root: Path, project: str) -> Li
                 severity="warning",
                 category="placement",
                 description=f"Misplaced agent: {issue.agent_name} at {rel_path}",
-                fix_command=f"drone @spawn repair @{project} --relocate {rel_path} {suggested}",
+                fix_command=f"drone @spawn repair @{project} --relocate {rel_path} {suggested} --apply",
             )
         )
     return items
@@ -113,8 +114,8 @@ def _build_placement_items(agents: list, project_root: Path, project: str) -> Li
 def _build_registry_items(project_root: Path, agents: list, project: str) -> List[RemediationItem]:
     """Build remediation items for registry consistency issues."""
     items: List[RemediationItem] = []
-    reg_path = find_registry(project_root)
-    if not reg_path:
+    reg_path = _discover_registry(start_path=project_root)
+    if not reg_path or not reg_path.exists():
         return items
     for issue in check_registry_consistency(reg_path, agents):
         items.append(
@@ -122,7 +123,7 @@ def _build_registry_items(project_root: Path, agents: list, project: str) -> Lis
                 severity="warning",
                 category="registry",
                 description=f"Registry {issue.problem}: {issue.branch_name} at {issue.registered_path}",
-                fix_command=f"drone @spawn repair @{project} --dedup-registry",
+                fix_command=f"drone @spawn repair @{project} --dedup-registry --apply",
             )
         )
     return items
@@ -145,7 +146,7 @@ def generate_remediation(project_root: Path) -> List[RemediationItem]:
                 severity="info",
                 category="pyproject",
                 description="Missing pyproject.toml",
-                fix_command=f"drone @spawn repair @{project} --add-pyproject",
+                fix_command=f"drone @spawn repair @{project} --add-pyproject --apply",
             )
         )
 
@@ -156,7 +157,7 @@ def generate_remediation(project_root: Path) -> List[RemediationItem]:
                 severity=severity,
                 category="root_artifact",
                 description=f"{hit.description}: {hit.name}/",
-                fix_command=f"drone @spawn repair @{project} --relocate-root {hit.name}",
+                fix_command=f"drone @spawn repair @{project} --relocate-root {hit.name} --apply",
             )
         )
 
@@ -184,7 +185,8 @@ def format_text_report(items: List[RemediationItem], project_name: str) -> str:
         lines.append(f"[{item.severity.upper()}] {item.description}")
         lines.append(f"  Fix: {item.fix_command}")
         lines.append("")
-    lines.append(f"Preview all fixes: drone @spawn repair @{project_name} --dry-run")
+    lines.append(f"Preview all fixes: drone @spawn repair @{project_name}")
+    lines.append(f"Apply all fixes:  drone @spawn repair @{project_name} --apply")
     return "\n".join(lines)
 
 
@@ -304,12 +306,12 @@ def handle_command(command: str, args: list[str]) -> bool:
         return False
 
     if not args:
-        print_introspection()
-        json_handler.log_operation("doctor_fix_info", {"command": command})
+        console.print("[dim]Helper module — use: aipass doctor --fix [--json][/dim]")
+        json_handler.log_operation("doctor_fix_usage", {"command": command})
         return True
 
     if args[0] in ("--help", "-h", "help"):
-        print_introspection()
+        console.print("[dim]Helper module — use: aipass doctor --fix [--json][/dim]")
         json_handler.log_operation("doctor_fix_help", {"command": command})
         return True
 

src/aipass/aipass/apps/modules/doctor_wire.py

@@ -51,6 +51,11 @@ ENV_DESCRIPTIONS: Dict[str, str] = {
 
 
 # =============================================================================
+# STALE DENY RULE MIGRATION (implementation in handler; re-exported here)
+# =============================================================================
+
+from aipass.aipass.apps.handlers.provider_reconcile import reconcile_stale_deny  # noqa: E402, F401
+
 
 # =============================================================================
 # AUTO-WIRE
@@ -283,13 +288,13 @@ def handle_command(command: str, args: list[str]) -> bool:
         return False
 
     if not args:
-        print_introspection()
-        json_handler.log_operation("doctor_wire_info", {"command": command})
+        console.print("[dim]Helper module — use: aipass doctor (auto-wire runs when needed)[/dim]")
+        json_handler.log_operation("doctor_wire_usage", {"command": command})
         return True
 
     if args[0] in ("--help", "-h", "help"):
-        print_introspection()
-        json_handler.log_operation("doctor_wire_info", {"command": command})
+        console.print("[dim]Helper module — use: aipass doctor (auto-wire runs when needed)[/dim]")
+        json_handler.log_operation("doctor_wire_help", {"command": command})
         return True
 
     if args[0] in ("--info", "info"):

src/aipass/aipass/apps/modules/handoff.py

@@ -134,13 +134,17 @@ def handle_command(command: str, args: list[str]) -> bool:
         return False
 
     if not args:
-        print_introspection()
+        print_help()
         return True
 
     if args[0] in ("--help", "-h", "help"):
         print_help()
         return True
 
+    if args[0] == "--info":
+        print_introspection()
+        return True
+
     if args[0] == "launch":
         cli, cwd, flag_variant = _parse_launch_args(args[1:])
         if cli not in CLI_CHOICES:

src/aipass/aipass/apps/modules/help_chat.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from aipass.aipass.apps.handlers.json import json_handler
-from aipass.aipass.apps.handlers.readme_map import get_readme_path, list_branches
+from aipass.aipass.apps.handlers.readme_map import get_readme_path, list_branches, read_readme_lines
 from aipass.cli.apps.modules import console, error, header
 from aipass.prax import logger
 
@@ -54,6 +54,20 @@ def print_introspection() -> None:
     console.print(f"[bold cyan]Version:[/bold cyan] {_VERSION}")
 
 
+def print_help() -> None:
+    """Print usage help for the help command."""
+    console.print()
+    console.print("[bold cyan]aipass help[/bold cyan] — README-backed Q&A")
+    console.print()
+    console.print("[yellow]USAGE:[/yellow]")
+    console.print("  [green]aipass help <question>[/green]  [dim]# Search branch READMEs[/dim]")
+    console.print()
+    console.print("[yellow]EXAMPLES:[/yellow]")
+    console.print("  [green]aipass help what does drone do[/green]")
+    console.print("  [green]aipass help how does ai_mail work[/green]")
+    console.print()
+
+
 # =============================================================================
 # KEYWORD EXTRACTION
 # =============================================================================
@@ -152,17 +166,15 @@ def _match_branches(keywords: list[str]) -> list[str]:
 # =============================================================================
 
 
-def _search_readme(readme_path: Path, keywords: list[str]) -> list[tuple[int, str]]:
-    """Live-read readme_path. Return (line_num, line_text) for matching lines.
+def _search_readme(branch: str, keywords: list[str]) -> list[tuple[int, str]]:
+    """Live-read branch README via handler. Return (line_num, line_text) for matching lines.
 
     Reads every call — never cached. Scores lines by number of keyword hits.
     Returns up to 5 best matches.
     """
-    try:
-        with open(readme_path, encoding="utf-8") as fh:
-            lines = fh.readlines()
-    except OSError as exc:
-        logger.warning("[help_chat] Could not read README %s: %s", readme_path, exc)
+    lines = read_readme_lines(branch)
+    if lines is None:
+        logger.warning("[help_chat] Could not read README for branch %s", branch)
         return []
 
     scored: list[tuple[int, int, str]] = []  # (score, line_num, line_text)
@@ -219,10 +231,14 @@ def handle_command(command: str, args: list[str]) -> bool:
     json_handler.ensure_module_jsons(_MODULE_NAME)
 
     if not args:
-        print_introspection()
+        print_help()
         return True
 
     if args[0] in ("--help", "-h", "help"):
+        print_help()
+        return True
+
+    if args[0] == "--info":
         print_introspection()
         return True
 
@@ -244,7 +260,7 @@ def handle_command(command: str, args: list[str]) -> bool:
         readme_path = get_readme_path(branch)
         if not readme_path:
             continue
-        matches = _search_readme(readme_path, keywords)
+        matches = _search_readme(branch, keywords)
         if matches:
             found_any = True
             answer = _format_answer(branch, readme_path, matches)

src/aipass/aipass/apps/modules/init_flow.py

@@ -16,7 +16,7 @@ Usage:
     aipass init                          # show progress / introspection
     aipass init run                      # interactive
     aipass init run --non-interactive    # CI/headless, all defaults
-    aipass init run --name Patrick --cli claude
+    aipass init run --name YourName --cli claude
     aipass init run --dry-run            # walk all 12 stages, no destructive ops
                                          #   - skips drone @spawn create (stage 8)
                                          #   - skips tmux/wt handoff (stage 11)
@@ -377,6 +377,54 @@ def stage_5_style_questions(
     return {"style": style}
 
 
+def _install_claude_code() -> bool:
+    """Run the canonical Claude Code installer, platform-aware. Returns True on success."""
+    if sys.platform == "win32":
+        cmd = ["powershell", "-Command", "irm https://claude.ai/install.ps1 | iex"]
+    else:
+        cmd = ["bash", "-c", "curl -fsSL https://claude.ai/install.sh | bash"]
+
+    try:
+        result = subprocess.run(cmd, timeout=300)
+        if result.returncode == 0 and shutil.which("claude"):
+            return True
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+        logger.warning("[init_flow] Claude Code installer failed: %s", exc)
+
+    if shutil.which("npm"):
+        console.print("[dim]Native installer didn't work — trying npm fallback...[/dim]")
+        try:
+            result = subprocess.run(
+                ["npm", "install", "-g", "@anthropic-ai/claude-code"],
+                timeout=300,
+            )
+            if result.returncode == 0 and shutil.which("claude"):
+                return True
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+            logger.warning("[init_flow] npm fallback install failed: %s", exc)
+
+    return False
+
+
+def _handle_missing_claude(non_interactive: bool) -> None:
+    """Prompt to install Claude Code when missing, or warn in non-interactive mode."""
+    if non_interactive:
+        warning("[bold yellow]Claude Code ('claude') is not installed.[/bold yellow]")
+        console.print("  Stage 11 handoff requires it. Install manually before then.")
+        return
+
+    raw = _prompt("Claude Code ('claude') not found. Install now? [Y/n]", "Y")
+    if raw.lower() in ("y", "yes", ""):
+        console.print("[dim]Installing Claude Code...[/dim]")
+        if _install_claude_code():
+            console.print("[green]✓[/green] Claude Code installed successfully.")
+        else:
+            warning("[bold yellow]Installation failed.[/bold yellow]")
+            console.print("  Install manually: https://claude.ai/download")
+    else:
+        console.print("[dim]Skipped. Stage 11 handoff will need 'claude' on PATH.[/dim]")
+
+
 def stage_6_tool_choice(
     non_interactive: bool = False,
     cli_override: str | None = None,
@@ -393,6 +441,9 @@ def stage_6_tool_choice(
     else:
         cli_choice = _choose("Which CLI tool do you use?", CLI_CHOICES, default="claude")
 
+    if cli_choice == "claude" and not shutil.which("claude"):
+        _handle_missing_claude(non_interactive)
+
     if non_interactive:
         flag_variant = "default"
     else:
@@ -454,9 +505,9 @@ def stage_8_first_agent(non_interactive: bool = False, dry_run: bool = False) ->
     console.print("Let's create your first AI agent (citizen).")
 
     if non_interactive:
-        agent_name = "my-agent"
+        agent_name = "my_agent"
     else:
-        agent_name = _prompt("Agent name (letters, hyphens, no spaces)", "my-agent") or "my-agent"
+        agent_name = _prompt("Agent name (letters, underscores, no spaces)", "my_agent") or "my_agent"
 
     package_dir = _resolve_package_dir()
     if package_dir:
@@ -560,7 +611,7 @@ def stage_10_smoke_test(non_interactive: bool = False, dry_run: bool = False) ->
 def stage_11_handoff(
     cli_choice: str = "claude",
     flag_variant: str = "default",
-    agent_path: str = "src/my-agent",
+    agent_path: str = "src/my_agent",
     non_interactive: bool = False,
     dry_run: bool = False,
     accumulated: Dict[str, Any] | None = None,
@@ -645,13 +696,18 @@ def _write_init_report(agent_path: str, accumulated: Dict[str, Any], dry_run: bo
         "cli_choice": accumulated.get("cli", "claude"),
         "total_agents": 1,
         "system": system_data,
-        "note": "You are the first agent created in this project. You are the orchestrator. After dispatching work to other agents, monitor them with: drone @devpulse watchdog agent @target",
+        "note": (
+            "You are the first agent created in this project. You are the orchestrator."
+            " After dispatching work to other agents, monitor them with:"
+            " drone @devpulse watchdog agent @target"
+        ),
     }
     provider_gaps = accumulated.get("provider_gaps", {})
     if provider_gaps:
         report["provider_gaps"] = provider_gaps
         report["provider_action"] = (
-            "Provider settings need configuring. Tell the user what is missing and point them to provider_manifest.json for details."
+            "Provider settings need configuring. Tell the user what is missing"
+            " and point them to provider_manifest.json for details."
         )
     report_path = dropbox / "init_report.json"
     report_path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
@@ -685,10 +741,24 @@ def _preflight_check() -> str | None:
             "This directory is an agent branch (has .trinity/passport.json).\n"
             "Agents are managed by 'drone @spawn', not 'aipass init'."
         )
-    # Block if inside an existing AIPass project (registry above us)
+    # Block if inside an existing AIPass project (registry above us).
+    # Walking up to the filesystem root can hit ancestors that can't be
+    # enumerated or stat'd — e.g. locked Windows system entries at the drive
+    # root (pagefile.sys) raise OSError. Skip those rather than crash; on
+    # POSIX everything up to / is readable so behaviour is unchanged there.
     for parent in [cwd] + list(cwd.parents):
-        for f in parent.iterdir():
-            if f.is_file() and f.name.endswith("_REGISTRY.json"):
+        try:
+            entries = list(parent.iterdir())
+        except OSError as exc:
+            logger.info("[init_flow] skipping unreadable ancestor %s: %s", parent, exc)
+            entries = []
+        for f in entries:
+            try:
+                is_registry = f.is_file() and f.name.endswith("_REGISTRY.json")
+            except OSError as exc:
+                logger.info("[init_flow] skipping unstattable entry %s: %s", f, exc)
+                continue
+            if is_registry:
                 return (
                     f"Already inside an AIPass project (found {f.name} at {parent}).\n"
                     "Use 'aipass init update' to upgrade an existing project."
@@ -752,7 +822,7 @@ def run_init(
             lambda: stage_11_handoff(
                 accumulated.get("cli", "claude"),
                 accumulated.get("flag_variant", "default"),
-                accumulated.get("agent_path", "src/my-agent"),
+                accumulated.get("agent_path", "src/my_agent"),
                 non_interactive,
                 dry_run=dry_run,
                 accumulated=accumulated,
@@ -806,7 +876,7 @@ def print_help() -> None:
     console.print("[yellow]USAGE:[/yellow]")
     console.print("  [green]aipass init run[/green]                      [dim]# interactive[/dim]")
     console.print("  [green]aipass init run --non-interactive[/green]    [dim]# CI/headless[/dim]")
-    console.print("  [green]aipass init run --name Patrick[/green]       [dim]# pre-fill name[/dim]")
+    console.print("  [green]aipass init run --name YourName[/green]      [dim]# pre-fill name[/dim]")
     console.print("  [green]aipass init run --cli claude[/green]         [dim]# pre-fill CLI[/dim]")
     console.print("  [green]aipass init run --no-docker[/green]          [dim]# skip docker offer[/dim]")
     console.print("  [green]aipass init run --dry-run[/green]            [dim]# walk all stages, no writes[/dim]")
@@ -874,12 +944,14 @@ def _handle_init_update(args: list[str]) -> int:
             console.print(f"  ({len(current)} already up to date)")
         # Heal registry: prune stale entries (e.g. cross-project ../paths)
         try:
-            from aipass.spawn.apps.modules.sync_registry import sync_registry
-
-            sync_result = sync_registry(fix=True)
-            pruned = sync_result.get("stale", [])
-            if pruned:
-                console.print(f"  [green]Registry healed:[/green] removed {len(pruned)} stale entry(ies)")
+            sync_proc = subprocess.run(
+                ["drone", "@spawn", "sync-registry", "--fix"],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if sync_proc.returncode == 0:
+                console.print("  [green]Registry synced.[/green]")
         except Exception as sync_exc:
             logger.warning("[init_flow] registry sync during update skipped: %s", sync_exc)
 
@@ -917,13 +989,17 @@ def handle_command(command: str, args: list[str]) -> bool:
         return False
 
     if not args:
-        print_introspection()
+        print_help()
         return True
 
     if args[0] in ("--help", "-h", "help"):
         print_help()
         return True
 
+    if args[0] == "--info":
+        print_introspection()
+        return True
+
     if args[0] == "agent":
         sys.exit(_handle_init_agent(args[1:]))
         return True

src/aipass/aipass/apps/modules/profile.py

@@ -141,6 +141,10 @@ def handle_command(command: str, args: list[str]) -> bool:
         print_help()
         return True
 
+    if args[0] == "--info":
+        print_introspection()
+        return True
+
     if args[0] == "set":
         if len(args) < 3:
             error("Usage: aipass profile set <field> <value>")

src/aipass/aipass/requirements.project.txt

@@ -0,0 +1,3 @@
+# Project-specific Python dependencies beyond the base AIPass install.
+# Add packages here that the aipass branch requires but are not in the root pyproject.toml.
+# Install with: pip install -r requirements.project.txt

src/aipass/aipass/shared/__init__.py

@@ -0,0 +1 @@
+# aipass.aipass.shared — shared leaf utilities (no branch dependencies, loads pre-drone)

src/aipass/aipass/shared/json_handler.py

@@ -0,0 +1,303 @@
+# =================== AIPass ====================
+# Name: json_handler.py
+# Description: Shared JSON handler with injectable storage directory
+# Version: 1.0.0
+# Created: 2026-06-06
+# Modified: 2026-06-10
+# =============================================
+
+"""Shared JSON handler — auto-creating, self-healing JSON system.
+
+Dependency-free: uses only stdlib. Importable before drone/prax exist.
+
+Each branch creates a JsonHandler instance with its own json_dir.
+Contract: save_json raises ValueError on validation failure.
+"""
+
+import inspect
+import json
+import logging
+import os
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+_JSON_TYPES: tuple[str, ...] = ("config", "data", "log")
+
+
+class JsonHandler:
+    """JSON file handler with injectable storage directory.
+
+    Provides JSON I/O utilities, validation, and operation logging
+    for the three-JSON system (config, data, log).
+
+    Args:
+        json_dir: Directory for module JSON files (config/data/log).
+    """
+
+    MAX_LOG_ENTRIES = 100
+
+    def __init__(self, json_dir: Path):
+        self._json_dir = Path(json_dir)
+
+    @staticmethod
+    def read_json(file_path: Path) -> Optional[dict]:
+        """Read and parse a JSON file.
+
+        Args:
+            file_path: Path to the JSON file.
+
+        Returns:
+            Parsed dict, or None on failure.
+        """
+        try:
+            return json.loads(Path(file_path).read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, FileNotFoundError) as e:
+            logger.warning("Failed to read JSON from %s: %s", file_path, e)
+            return None
+
+    @staticmethod
+    def write_json(file_path: Path, data: Any, indent: int = 2) -> bool:
+        """Write data to a JSON file atomically (temp file + os.replace).
+
+        Args:
+            file_path: Target path.
+            data: JSON-serializable data.
+            indent: JSON indentation level.
+
+        Returns:
+            True on success, False on OS error.
+        """
+        file_path = Path(file_path)
+        try:
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            content = json.dumps(data, indent=indent) + "\n"
+            fd, tmp_path = tempfile.mkstemp(dir=file_path.parent, suffix=".tmp")
+            closed = False
+            try:
+                os.write(fd, content.encode("utf-8"))
+                os.fsync(fd)
+                os.close(fd)
+                closed = True
+                os.replace(tmp_path, file_path)
+            except BaseException:
+                if not closed:
+                    os.close(fd)
+                if os.path.exists(tmp_path):
+                    os.unlink(tmp_path)
+                raise
+            return True
+        except OSError as e:
+            logger.error("Failed to write JSON to %s: %s", file_path, e)
+            return False
+
+    @staticmethod
+    def validate_json_structure(data: Any, json_type: str) -> bool:
+        """Validate that data matches the expected shape for json_type.
+
+        Args:
+            data: Parsed JSON data to validate.
+            json_type: One of "config", "data", "log".
+
+        Returns:
+            True when the structure is valid, False otherwise.
+        """
+        if json_type == "config":
+            if not isinstance(data, dict):
+                return False
+            return all(key in data for key in ("module_name", "version", "config"))
+        if json_type == "data":
+            if not isinstance(data, dict):
+                return False
+            return all(key in data for key in ("created", "last_updated"))
+        if json_type == "log":
+            return isinstance(data, list)
+        return False
+
+    @staticmethod
+    def _create_default(json_type: str, module_name: str) -> Any:
+        """Return default content for a given JSON type.
+
+        Args:
+            json_type: One of "config", "data", "log".
+            module_name: Logical module name.
+
+        Returns:
+            Default data structure.
+
+        Raises:
+            ValueError: For unknown json_type.
+        """
+        today = datetime.now().date().isoformat()
+        if json_type == "config":
+            return {
+                "module_name": module_name,
+                "version": "1.0.0",
+                "config": {
+                    "max_log_entries": JsonHandler.MAX_LOG_ENTRIES,
+                },
+                "created": today,
+                "last_updated": today,
+            }
+        if json_type == "data":
+            return {
+                "created": today,
+                "last_updated": today,
+            }
+        if json_type == "log":
+            return []
+        raise ValueError(f"Unknown json_type: {json_type!r}")
+
+    def get_json_path(self, module_name: str, json_type: str) -> Path:
+        """Return the filesystem path for a module's JSON file.
+
+        Args:
+            module_name: Logical module name.
+            json_type: One of "config", "data", "log".
+
+        Returns:
+            Absolute Path to the JSON file.
+        """
+        return self._json_dir / f"{module_name}_{json_type}.json"
+
+    def ensure_json_exists(self, module_name: str, json_type: str) -> bool:
+        """Ensure a single JSON file exists; create with defaults if missing.
+
+        If the file exists but fails validation it is regenerated.
+
+        Args:
+            module_name: Logical module name.
+            json_type: One of "config", "data", "log".
+
+        Returns:
+            True after the file is confirmed present and valid.
+        """
+        self._json_dir.mkdir(parents=True, exist_ok=True)
+        json_path = self.get_json_path(module_name, json_type)
+
+        if json_path.exists():
+            try:
+                if json_path.stat().st_size == 0:
+                    logger.warning("ensure_json_exists: empty file at %s, regenerating", json_path)
+                else:
+                    data = json.loads(json_path.read_text(encoding="utf-8"))
+                    if self.validate_json_structure(data, json_type):
+                        return True
+            except Exception as exc:
+                logger.warning("ensure_json_exists: failed to read %s, regenerating: %s", json_path, exc)
+
+        default = self._create_default(json_type, module_name)
+        self.write_json(json_path, default)
+        return True
+
+    def ensure_module_jsons(self, module_name: str) -> bool:
+        """Ensure all three JSON files (config, data, log) exist for a module.
+
+        Args:
+            module_name: Logical module name.
+
+        Returns:
+            True when all files are present and valid.
+        """
+        for json_type in _JSON_TYPES:
+            self.ensure_json_exists(module_name, json_type)
+        return True
+
+    def load_json(self, module_name: str, json_type: str) -> Any | None:
+        """Load a module's JSON file, auto-creating it if missing.
+
+        Args:
+            module_name: Logical module name.
+            json_type: One of "config", "data", "log".
+
+        Returns:
+            Parsed JSON data, or None on failure.
+        """
+        if not self.ensure_json_exists(module_name, json_type):
+            return None
+
+        json_path = self.get_json_path(module_name, json_type)
+        try:
+            return json.loads(json_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("load_json: failed to read %s: %s", json_path, exc)
+            return self._create_default(json_type, module_name)
+
+    def save_json(self, module_name: str, json_type: str, data: Any) -> bool:
+        """Write data to a module's JSON file after validation.
+
+        For "data" type files the last_updated field is refreshed automatically.
+
+        Args:
+            module_name: Logical module name.
+            json_type: One of "config", "data", "log".
+            data: The data structure to persist.
+
+        Returns:
+            True on success.
+
+        Raises:
+            ValueError: When data fails structure validation.
+        """
+        if not self.validate_json_structure(data, json_type):
+            raise ValueError(f"Invalid structure for {json_type} JSON")
+
+        if json_type == "data" and isinstance(data, dict):
+            data["last_updated"] = datetime.now().date().isoformat()
+
+        json_path = self.get_json_path(module_name, json_type)
+        return self.write_json(json_path, data)
+
+    def log_operation(self, operation: str, data: Dict[str, Any] | None = None, module_name: str | None = None) -> bool:
+        """Add entry to module operation log with automatic rotation.
+
+        Auto-detects calling module if module_name not provided.
+
+        Args:
+            operation: Operation name to log.
+            data: Optional data dict.
+            module_name: Optional module name (auto-detected if not provided).
+
+        Returns:
+            True if successful, False otherwise.
+        """
+        if module_name is None:
+            module_name = _get_caller_module_name()
+
+        try:
+            self.ensure_module_jsons(module_name)
+
+            log = self.load_json(module_name, "log")
+            if log is None:
+                log = []
+
+            entry: Dict[str, Any] = {
+                "timestamp": datetime.now().isoformat(),
+                "operation": operation,
+            }
+            if data:
+                entry["data"] = data
+
+            log.append(entry)
+
+            if len(log) > self.MAX_LOG_ENTRIES:
+                log = log[-self.MAX_LOG_ENTRIES :]
+
+            return self.save_json(module_name, "log", log)
+        except Exception as exc:
+            logger.warning("log_operation: failed for %s/%s: %s", module_name, operation, exc)
+            return False
+
+
+def _get_caller_module_name() -> str:
+    """Auto-detect calling module name from call stack."""
+    stack = inspect.stack()
+    if len(stack) > 2:
+        caller_path = Path(stack[2].filename)
+        module_name = caller_path.stem
+        if module_name and not module_name.startswith("_"):
+            return module_name
+    return "unknown"

src/aipass/aipass/shared/json_ops.py

@@ -0,0 +1,115 @@
+# =================== AIPass ====================
+# Name: json_ops.py
+# Description: Shared JSON operations — deep merge and backup
+# Version: 1.0.0
+# Created: 2026-06-06
+# Modified: 2026-06-10
+# =============================================
+
+"""Shared JSON operations — deep merge and backup utilities.
+
+Dependency-free: uses only stdlib. Importable before drone/prax exist.
+"""
+
+import logging
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def deep_merge(template_data: Any, existing_data: Any) -> Any:
+    """Recursively merge template structure with existing data.
+
+    Merge strategy:
+    - Both dicts: merge keys. Template defines structure, existing fills values.
+    - Template has key that existing doesn't: add from template (default).
+    - Existing has key that template doesn't: KEEP existing key (don't prune).
+    - Both lists: keep existing list (don't overwrite user data).
+    - Scalar values: keep existing value (don't overwrite).
+    - If existing is None/empty but template has value: use template value.
+
+    Args:
+        template_data: Template structure (provides fields and defaults).
+        existing_data: Existing data (provides values to preserve).
+
+    Returns:
+        Merged result combining template structure with existing values.
+    """
+    if existing_data is None:
+        return template_data
+
+    if template_data is None:
+        return existing_data
+
+    if isinstance(template_data, dict) and isinstance(existing_data, dict):
+        result = {}
+
+        for key in template_data:
+            if key in existing_data:
+                result[key] = deep_merge(template_data[key], existing_data[key])
+            else:
+                result[key] = template_data[key]
+
+        for key in existing_data:
+            if key not in result:
+                result[key] = existing_data[key]
+
+        return result
+
+    if isinstance(template_data, list) and isinstance(existing_data, list):
+        if len(existing_data) > 0:
+            return existing_data
+        if len(template_data) > 0:
+            return template_data
+        return []
+
+    if existing_data is not None:
+        if isinstance(existing_data, str) and existing_data == "" and template_data:
+            return template_data
+        return existing_data
+
+    return template_data
+
+
+def backup_json(file_path: Path, backup_dir: Path | None = None) -> Path:
+    """Create a timestamped backup of a JSON file.
+
+    By default the backup is placed in a ``.recovery/`` directory alongside the
+    file. Callers can override with ``backup_dir`` to consolidate backups
+    elsewhere (e.g. ``.spawn/.recovery/``).
+
+    Args:
+        file_path: Path to the JSON file to back up.
+        backup_dir: Optional override for the backup destination directory.
+            Defaults to ``file_path.parent / ".recovery"``.
+
+    Returns:
+        Path to the backup file.
+
+    Raises:
+        FileNotFoundError: If the source file doesn't exist.
+        IOError: If the backup copy fails.
+    """
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"Cannot backup — file not found: {file_path}")
+
+    if backup_dir is None:
+        backup_dir = file_path.parent / ".recovery"
+    backup_dir = Path(backup_dir)
+    backup_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_name = f"{file_path.name}.{timestamp}.backup"
+    backup_path = backup_dir / backup_name
+
+    try:
+        shutil.copy2(file_path, backup_path)
+        return backup_path
+    except (IOError, OSError) as exc:
+        logger.error("Backup failed for %s: %s", file_path.name, exc)
+        raise

src/aipass/aipass/shared/registry_discovery.py

@@ -0,0 +1,67 @@
+# =================== AIPass ====================
+# Name: registry_discovery.py
+# Description: Shared registry file discovery (walk-up search)
+# Version: 1.0.0
+# Created: 2026-06-06
+# Modified: 2026-06-10
+# =============================================
+
+"""Registry discovery — find *_REGISTRY.json by walking up the directory tree.
+
+Dependency-free: uses only stdlib. Importable before drone/prax exist.
+"""
+
+import os
+from pathlib import Path
+
+
+def _glob_registry(directory):
+    """Find *_REGISTRY.json in a single directory.
+
+    Args:
+        directory: Path to search in.
+
+    Returns:
+        Path to the registry file, or None if not found.
+    """
+    matches = sorted(directory.glob("*_REGISTRY.json"))
+    return matches[0] if matches else None
+
+
+def find_registry(start_path=None, package_root=None):
+    """Find *_REGISTRY.json — walks up from start_path/cwd, then package_root.
+
+    The first *_REGISTRY.json found while walking up IS the project boundary.
+    If multiple exist in the same directory, picks the first alphabetically.
+
+    Priority:
+    1. AIPASS_REGISTRY environment variable
+    2. Walk up from start_path/cwd — first dir containing *_REGISTRY.json
+    3. Walk up from package_root (caller's __file__ location) — fallback
+    4. Last resort: cwd / AIPASS_REGISTRY.json (backwards compat)
+
+    Args:
+        start_path: Directory to start searching from (default: cwd).
+        package_root: Optional fallback directory for package-relative search.
+
+    Returns:
+        Path to *_REGISTRY.json.
+    """
+    env_path = os.environ.get("AIPASS_REGISTRY")
+    if env_path:
+        return Path(env_path)
+
+    current = Path(start_path).resolve() if start_path else Path.cwd()
+    for parent in [current] + list(current.parents):
+        found = _glob_registry(parent)
+        if found:
+            return found
+
+    if package_root:
+        pkg_dir = Path(package_root).resolve()
+        for parent in [pkg_dir] + list(pkg_dir.parents):
+            found = _glob_registry(parent)
+            if found:
+                return found
+
+    return Path.cwd() / "AIPASS_REGISTRY.json"

src/aipass/aipass/tests/test_bootstrap.py

@@ -22,6 +22,7 @@ import pytest  # pyright: ignore[reportMissingImports]
 
 from aipass.aipass.apps.handlers.init import scaffold_content as sc
 from aipass.aipass.apps.handlers.init.bootstrap import (
+    _merge_hooks_json,
     _sanitize_name,
     init_project,
     update_project,
@@ -97,18 +98,21 @@ def test_init_project_creates_all_expected_files(tmp_path):
 
     expected_files = [
         target / "DEMO_REGISTRY.json",
-        target / ".aipass" / "aipass_global_prompt.md",
         target / "CLAUDE.md",
         target / "AGENTS.md",
         target / "README.md",
-        target / "STATUS.local.md",
         target / ".gitignore",
         target / ".claude" / "settings.json",
         target / ".claude" / "commands" / "prep.md",
         target / "src" / "demo" / "__init__.py",
     ]
+    # Tier files are env-dependent (need AIPASS_HOME)
+    if result["aipass_home"]:
+        expected_files.append(target / ".aipass" / "tier0_kernel.md")
+        expected_files.append(target / ".aipass" / "tier1_navmap.md")
     for f in expected_files:
         assert f.exists(), f"Expected file not created: {f}"
+    assert not (target / ".aipass" / "aipass_global_prompt.md").exists(), "Retired global prompt should NOT be seeded"
 
     # src/<package>/ is a directory with __init__.py
     assert (target / "src" / "demo").is_dir(), "Expected src/demo/ package directory"
@@ -126,7 +130,7 @@ def test_init_project_creates_all_expected_files(tmp_path):
     created_basenames = [Path(f).name for f in result["created_files"]]
     for f in expected_files:
         assert f.name in created_basenames or f.exists(), f"Expected {f.name} in created_files"
-    assert len(result["created_files"]) >= 11
+    assert len(result["created_files"]) >= 10
 
 
 def test_init_project_return_dict_structure(tmp_path):
@@ -234,15 +238,15 @@ def test_init_project_raises_on_empty_name(tmp_path):
 
 
 def test_init_project_agents_md_content(tmp_path):
-    """AGENTS.md is copied from AIPass source of truth."""
+    """AGENTS.md contains project-specific content from generator."""
     target = tmp_path / "proj"
     target.mkdir()
 
     init_project(target, project_name="alpha")
 
     content = (target / "AGENTS.md").read_text(encoding="utf-8")
-    assert "# AIPass" in content
-    assert "Multi-agent framework" in content
+    assert "# ALPHA" in content
+    assert "AIPass" in content
 
 
 def test_init_project_gitignore_content(tmp_path):
@@ -288,19 +292,6 @@ def test_init_project_settings_no_hooks(tmp_path):
     assert "permissions" in data
 
 
-def test_init_project_global_prompt_content(tmp_path):
-    """Global prompt contains project name and AIPass terminology."""
-    target = tmp_path / "proj"
-    target.mkdir()
-
-    init_project(target, project_name="alpha")
-
-    content = (target / ".aipass" / "aipass_global_prompt.md").read_text(encoding="utf-8")
-    assert "# ALPHA" in content
-    assert "ALPHA_REGISTRY.json" in content
-    assert "# Commands" in content
-
-
 def test_init_project_readme_md_content(tmp_path):
     """README.md contains getting started guide with project name."""
     target = tmp_path / "proj"
@@ -324,7 +315,7 @@ def test_init_project_auto_creates_target_dir(tmp_path):
 
     assert target.is_dir()
     assert result["project_name"] == "NESTED"
-    assert len(result["created_files"]) >= 11
+    assert len(result["created_files"]) >= 10
 
 
 def test_init_project_defaults_name_from_directory(tmp_path):
@@ -359,11 +350,9 @@ def test_init_project_skips_existing_optional_files(tmp_path):
     # Pre-create optional files
     aipass_dir = target / ".aipass"
     aipass_dir.mkdir()
-    (aipass_dir / "aipass_global_prompt.md").write_text("# Custom global\n", encoding="utf-8")
     (target / "CLAUDE.md").write_text("# Custom CLAUDE\n", encoding="utf-8")
     (target / "AGENTS.md").write_text("# Custom AGENTS\n", encoding="utf-8")
     (target / "README.md").write_text("# Custom README\n", encoding="utf-8")
-    (target / "STATUS.local.md").write_text("# Custom status\n", encoding="utf-8")
     (target / ".gitignore").write_text("# Custom\n", encoding="utf-8")
 
     claude_dir = target / ".claude"
@@ -412,16 +401,15 @@ def test_init_project_returns_dict(tmp_path):
 
 
 def test_init_project_agents_md_no_trinity(tmp_path):
-    """AGENTS.md is copied from AIPass source (may reference .trinity/ as part of agent docs)."""
+    """AGENTS.md references .trinity/ as part of startup protocol docs."""
     target = tmp_path / "proj"
     target.mkdir()
 
     init_project(target, project_name="keep")
 
     content = (target / "AGENTS.md").read_text(encoding="utf-8")
-    # Source file legitimately references .trinity/ as part of startup protocol docs
-    assert "# AIPass" in content
-    assert "Multi-agent framework" in content
+    assert "# KEEP" in content
+    assert ".trinity/" in content
 
 
 # ---------------------------------------------------------------------------
@@ -470,7 +458,7 @@ def test_update_project_already_current_after_init(tmp_path):
     result = update_project(target)
 
     assert len(result["updated_files"]) == 0
-    assert len(result["already_current"]) >= 4
+    assert len(result["already_current"]) >= 5
 
 
 def test_update_project_idempotent(tmp_path):
@@ -517,7 +505,6 @@ def test_update_project_never_touches_user_owned_files(tmp_path):
 
     # Modify user-owned files
     (target / "README.md").write_text("# My custom README\n", encoding="utf-8")
-    (target / "STATUS.local.md").write_text("# Custom status\n", encoding="utf-8")
     (target / ".gitignore").write_text("# custom\n", encoding="utf-8")
 
     result = update_project(target)
@@ -525,12 +512,10 @@ def test_update_project_never_touches_user_owned_files(tmp_path):
     skipped = result["skipped_files"]
     assert any("REGISTRY" in s for s in skipped)
     assert any("README.md" in s for s in skipped)
-    assert any("STATUS.local.md" in s for s in skipped)
     assert any(".gitignore" in s for s in skipped)
 
     # User customisations are preserved
     assert (target / "README.md").read_text(encoding="utf-8") == "# My custom README\n"
-    assert (target / "STATUS.local.md").read_text(encoding="utf-8") == "# Custom status\n"
 
 
 def test_update_project_creates_missing_managed_dirs(tmp_path):
@@ -547,23 +532,25 @@ def test_update_project_creates_missing_managed_dirs(tmp_path):
 
     result = update_project(target)
 
-    assert (target / ".aipass" / "aipass_global_prompt.md").exists()
     assert (target / ".claude" / "settings.json").exists()
-    # Managed files in deleted dirs re-written (global_prompt, settings, prep)
-    assert len(result["updated_files"]) == 3
+    # Managed files in deleted dirs re-written (tier0_kernel, tier1_navmap, hooks.json, settings, prep)
+    if result["aipass_home"]:
+        assert len(result["updated_files"]) == 5
+    else:
+        assert len(result["updated_files"]) == 2
     assert len(result["already_current"]) >= 2
 
 
 def test_update_project_skipped_files_count(tmp_path):
-    """update_project skips 4 user-owned files + existing mailbox = 5 total."""
+    """update_project skips 3 user-owned files."""
     target = tmp_path / "proj"
     target.mkdir()
     init_project(target, project_name="count")
 
     result = update_project(target)
 
-    # 4 user-owned (registry, README, STATUS, .gitignore)
-    assert len(result["skipped_files"]) == 4
+    # 3 user-owned (registry, README, .gitignore)
+    assert len(result["skipped_files"]) == 3
 
 
 # ---------------------------------------------------------------------------
@@ -629,7 +616,7 @@ def test_update_project_adds_aipass_home_if_missing(tmp_path):
 
 
 # ---------------------------------------------------------------------------
-# DPLAN-0139: Hook shipping + /memo tests
+# DPLAN-0190: hooks.json + /memo tests
 # ---------------------------------------------------------------------------
 
 
@@ -644,8 +631,8 @@ def test_init_project_no_memo_md(tmp_path):
     assert not memo_path.exists()
 
 
-def test_init_project_ships_hooks(tmp_path):
-    """init_project copies enforcement + injector hooks to target .claude/hooks/."""
+def test_init_project_creates_hooks_json(tmp_path):
+    """init_project creates .aipass/hooks.json from project_hooks.json template."""
     target = tmp_path / "proj"
     target.mkdir()
 
@@ -654,16 +641,46 @@ def test_init_project_ships_hooks(tmp_path):
     if result["aipass_home"] is None:
         pytest.skip("AIPASS_HOME not detectable in this environment")
 
-    hooks_dir = target / ".claude" / "hooks"
-    # Post DPLAN-0184: hooks are native handlers in src/aipass/hooks/,
-    # no longer shipped as script copies. Directory may or may not exist.
-    if hooks_dir.exists():
-        shipped = [f.name for f in hooks_dir.iterdir()]
-        assert len(shipped) == 0, f"No hook scripts should be shipped post-migration: {shipped}"
+    hooks_json = target / ".aipass" / "hooks.json"
+    assert hooks_json.exists(), ".aipass/hooks.json should be created"
+    data = json.loads(hooks_json.read_text(encoding="utf-8"))
+    assert data.get("hooks_enabled") is True
+    assert "UserPromptSubmit" in data
 
 
-def test_init_project_hooks_not_shipped_without_aipass_home(tmp_path, monkeypatch):
-    """When AIPASS_HOME is not detectable, hooks are not shipped."""
+def test_init_project_hooks_json_matches_template(tmp_path):
+    """hooks.json content matches the project_hooks.json template."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    result = init_project(target, project_name="tmpl")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    hooks_json = target / ".aipass" / "hooks.json"
+    template = Path(result["aipass_home"]) / ".aipass" / "project_hooks.json"
+    if not template.exists():
+        pytest.skip("project_hooks.json template not found")
+
+    assert hooks_json.read_bytes() == template.read_bytes()
+
+
+def test_init_project_hooks_json_in_created_files(tmp_path):
+    """hooks.json path appears in created_files list."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    result = init_project(target, project_name="created")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    assert any("hooks.json" in f for f in result["created_files"])
+
+
+def test_init_project_no_hooks_json_without_aipass_home(tmp_path, monkeypatch):
+    """When AIPASS_HOME is not detectable, hooks.json is not created."""
     target = tmp_path / "proj"
     target.mkdir()
 
@@ -674,55 +691,20 @@ def test_init_project_hooks_not_shipped_without_aipass_home(tmp_path, monkeypatc
 
     init_project(target, project_name="nohooks")
 
-    hooks_dir = target / ".claude" / "hooks"
-    assert not hooks_dir.exists() or len(list(hooks_dir.iterdir())) == 0
+    assert not (target / ".aipass" / "hooks.json").exists()
 
 
-def test_init_project_no_audio_hooks_shipped(tmp_path):
-    """Audio hooks (notification_sound, tool_use_sound, stop_sound) are never shipped."""
+def test_init_project_no_hook_scripts_shipped(tmp_path):
+    """No hook scripts are shipped to .claude/hooks/ (engine runs from $AIPASS_HOME)."""
     target = tmp_path / "proj"
     target.mkdir()
 
-    init_project(target, project_name="noaudio")
+    init_project(target, project_name="noscripts")
 
     hooks_dir = target / ".claude" / "hooks"
     if hooks_dir.exists():
         shipped = [f.name for f in hooks_dir.iterdir()]
-        assert "notification_sound.py" not in shipped
-        assert "tool_use_sound.py" not in shipped
-        assert "stop_sound.py" not in shipped
-
-
-def test_update_project_resyncs_hooks(tmp_path):
-    """update_project re-copies hooks when source differs from target."""
-    target = tmp_path / "proj"
-    target.mkdir()
-    result = init_project(target, project_name="resync")
-
-    if result["aipass_home"] is None:
-        pytest.skip("AIPASS_HOME not detectable in this environment")
-
-    # Post DPLAN-0184: hooks are native handlers, not shipped as copies.
-    # update_project no longer resyncs hook scripts.
-    result = update_project(target)
-    hooks_marker = str(Path(".claude") / "hooks")
-    hook_paths = [f for f in result["updated_files"] if hooks_marker in f]
-    assert len(hook_paths) == 0, "No hook scripts should be shipped post-migration"
-
-
-def test_init_project_hooks_idempotent_on_rerun(tmp_path):
-    """Re-running init does not create hook script copies."""
-    target = tmp_path / "proj"
-    target.mkdir()
-
-    result1 = init_project(target, project_name="idem")
-
-    if result1["aipass_home"] is None:
-        pytest.skip("AIPASS_HOME not detectable in this environment")
-
-    hooks_marker = str(Path(".claude") / "hooks")
-    hook_paths = [f for f in result1["created_files"] if hooks_marker in f]
-    assert len(hook_paths) == 0, "No hook scripts should be shipped post-migration"
+        assert len(shipped) == 0, f"No hook scripts should be shipped: {shipped}"
 
 
 def test_init_project_settings_has_no_hook_events(tmp_path):
@@ -736,6 +718,278 @@ def test_init_project_settings_has_no_hook_events(tmp_path):
     assert "hooks" not in settings
 
 
+def test_update_project_creates_hooks_json_if_missing(tmp_path):
+    """update_project creates hooks.json from template when missing."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    registry_data = {
+        "metadata": {
+            "id": "test-id",
+            "name": "MISS",
+            "version": "1.0.0",
+            "created": "2026-01-01",
+            "last_updated": "2026-01-01",
+            "total_branches": 0,
+        },
+        "branches": [],
+    }
+    (target / "MISS_REGISTRY.json").write_text(json.dumps(registry_data), encoding="utf-8")
+
+    hooks_json = target / ".aipass" / "hooks.json"
+    assert not hooks_json.exists()
+
+    result = update_project(target)
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    assert hooks_json.exists()
+    assert any("hooks.json" in f for f in result["updated_files"])
+    data = json.loads(hooks_json.read_text(encoding="utf-8"))
+    assert data.get("hooks_enabled") is True
+
+
+def test_update_project_union_merge_preserves_user_enabled(tmp_path):
+    """update preserves user's enabled=false for existing hooks."""
+    target = tmp_path / "proj"
+    target.mkdir()
+    result = init_project(target, project_name="merge")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    hooks_json = target / ".aipass" / "hooks.json"
+    data = json.loads(hooks_json.read_text(encoding="utf-8"))
+    data["PreToolUse"]["git_gate"]["enabled"] = False
+    hooks_json.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+    update_project(target)
+
+    updated = json.loads(hooks_json.read_text(encoding="utf-8"))
+    assert updated["PreToolUse"]["git_gate"]["enabled"] is False
+
+
+def test_update_project_union_merge_adds_new_hooks(tmp_path):
+    """update adds hooks from template that user doesn't have."""
+    existing = {
+        "hooks_enabled": True,
+        "UserPromptSubmit": {
+            "identity_injector": {"enabled": True, "handler": "old.handler", "matcher": ""},
+        },
+    }
+    template = {
+        "hooks_enabled": True,
+        "UserPromptSubmit": {
+            "identity_injector": {"enabled": True, "handler": "new.handler", "matcher": ""},
+            "brand_new_hook": {"enabled": True, "handler": "brand.new", "matcher": ""},
+        },
+        "Stop": {
+            "stop_sound": {"enabled": True, "handler": "stop.handler", "matcher": ""},
+        },
+    }
+
+    merged = _merge_hooks_json(existing, template)
+
+    assert "brand_new_hook" in merged["UserPromptSubmit"]
+    assert "Stop" in merged
+    assert merged["Stop"]["stop_sound"]["enabled"] is True
+
+
+def test_update_project_union_merge_preserves_user_hooks():
+    """User's custom hooks not in template are kept."""
+    existing = {
+        "hooks_enabled": True,
+        "UserPromptSubmit": {
+            "my_custom_hook": {"enabled": True, "handler": "custom.handler", "matcher": ""},
+        },
+    }
+    template = {
+        "hooks_enabled": True,
+        "UserPromptSubmit": {
+            "identity_injector": {"enabled": True, "handler": "std.handler", "matcher": ""},
+        },
+    }
+
+    merged = _merge_hooks_json(existing, template)
+
+    assert "my_custom_hook" in merged["UserPromptSubmit"]
+    assert "identity_injector" in merged["UserPromptSubmit"]
+
+
+def test_merge_hooks_json_preserves_hooks_enabled_false():
+    """User's hooks_enabled=false is preserved over template's true."""
+    existing = {"hooks_enabled": False}
+    template = {"hooks_enabled": True, "Stop": {"s": {"enabled": True, "handler": "h", "matcher": ""}}}
+
+    merged = _merge_hooks_json(existing, template)
+
+    assert merged["hooks_enabled"] is False
+
+
+def test_update_project_hooks_json_already_current(tmp_path):
+    """update reports hooks.json as already_current when unchanged."""
+    target = tmp_path / "proj"
+    target.mkdir()
+    result = init_project(target, project_name="curr")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    result = update_project(target)
+
+    assert not any("hooks.json" in f for f in result["updated_files"])
+    assert any("hooks.json" in f for f in result["already_current"])
+
+
+# ---------------------------------------------------------------------------
+# Tiered prompt injection tests (FPLAN-0284)
+# ---------------------------------------------------------------------------
+
+
+def test_init_project_creates_tier_files(tmp_path):
+    """init_project seeds tier0_kernel.md and tier1_navmap.md when AIPASS_HOME available."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    result = init_project(target, project_name="tiers")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    assert (target / ".aipass" / "tier0_kernel.md").exists()
+    assert (target / ".aipass" / "tier1_navmap.md").exists()
+
+
+def test_init_project_tier_files_match_canonical(tmp_path):
+    """Tier files in new project match the canonical source exactly."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    result = init_project(target, project_name="canon")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    for tier_file in ("tier0_kernel.md", "tier1_navmap.md"):
+        canonical = Path(result["aipass_home"]) / ".aipass" / tier_file
+        if not canonical.exists():
+            pytest.skip(f"{tier_file} not found in canonical .aipass/")
+        assert (target / ".aipass" / tier_file).read_bytes() == canonical.read_bytes()
+
+
+def test_init_project_tier_files_in_created_list(tmp_path):
+    """Tier files appear in created_files list."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    result = init_project(target, project_name="listed")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    assert any("tier0_kernel.md" in f for f in result["created_files"])
+    assert any("tier1_navmap.md" in f for f in result["created_files"])
+
+
+def test_init_project_no_tier_files_without_aipass_home(tmp_path, monkeypatch):
+    """Without AIPASS_HOME, tier files are not created."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    monkeypatch.setattr(
+        "aipass.aipass.apps.handlers.init.bootstrap._detect_aipass_home",
+        lambda: None,
+    )
+
+    init_project(target, project_name="notiers")
+
+    assert not (target / ".aipass" / "tier0_kernel.md").exists()
+    assert not (target / ".aipass" / "tier1_navmap.md").exists()
+
+
+def test_init_project_hooks_json_has_tiers_enabled(tmp_path):
+    """hooks.json from template has tier0_kernel and navmap enabled, no global_prompt."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    result = init_project(target, project_name="hookstier")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    hooks_json = target / ".aipass" / "hooks.json"
+    data = json.loads(hooks_json.read_text(encoding="utf-8"))
+    ups = data["UserPromptSubmit"]
+
+    assert ups["tier0_kernel"]["enabled"] is True
+    assert ups["navmap"]["enabled"] is True
+    assert "global_prompt" not in ups
+
+
+def test_update_project_adds_tier_files_to_existing(tmp_path):
+    """update_project adds tier files to a project that lacks them."""
+    target = tmp_path / "proj"
+    target.mkdir()
+
+    registry_data = {
+        "metadata": {
+            "id": "test-id",
+            "name": "OLD",
+            "version": "1.0.0",
+            "created": "2026-01-01",
+            "last_updated": "2026-01-01",
+            "total_branches": 0,
+        },
+        "branches": [],
+    }
+    (target / "OLD_REGISTRY.json").write_text(json.dumps(registry_data), encoding="utf-8")
+    (target / ".aipass").mkdir()
+
+    result = update_project(target)
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    assert (target / ".aipass" / "tier0_kernel.md").exists()
+    assert (target / ".aipass" / "tier1_navmap.md").exists()
+    assert any("tier0_kernel.md" in f for f in result["updated_files"])
+    assert any("tier1_navmap.md" in f for f in result["updated_files"])
+
+
+def test_update_project_tier_files_already_current(tmp_path):
+    """update reports tier files as already_current when unchanged."""
+    target = tmp_path / "proj"
+    target.mkdir()
+    result = init_project(target, project_name="tiercurr")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    result = update_project(target)
+
+    assert any("tier0_kernel.md" in f for f in result["already_current"])
+    assert any("tier1_navmap.md" in f for f in result["already_current"])
+
+
+def test_update_project_refreshes_stale_tier_files(tmp_path):
+    """update overwrites tier files when they differ from canonical source."""
+    target = tmp_path / "proj"
+    target.mkdir()
+    result = init_project(target, project_name="stale")
+
+    if result["aipass_home"] is None:
+        pytest.skip("AIPASS_HOME not detectable in this environment")
+
+    (target / ".aipass" / "tier0_kernel.md").write_text("# stale\n", encoding="utf-8")
+
+    result = update_project(target)
+
+    assert any("tier0_kernel.md" in f for f in result["updated_files"])
+    content = (target / ".aipass" / "tier0_kernel.md").read_text(encoding="utf-8")
+    assert "AIPass" in content
+
+
 # ---------------------------------------------------------------------------
 # scaffold_content — global_prompt_md tests
 # ---------------------------------------------------------------------------

src/aipass/aipass/tests/test_doctor.py

@@ -441,10 +441,8 @@ class TestProviderManifest:
 
         manifest = tmp_path / ".claude" / "provider_manifest.json"
         manifest.parent.mkdir(parents=True)
-        cmd_a = "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py Stop"
-        cmd_b = (
-            "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py Notification"
-        )
+        cmd_a = "$AIPASS_HOME/bin/hook-bridge Stop"
+        cmd_b = "$AIPASS_HOME/bin/hook-bridge Notification"
         manifest.write_text(
             json.dumps(
                 {
@@ -487,7 +485,7 @@ class TestProviderManifest:
 
         manifest = tmp_path / ".claude" / "provider_manifest.json"
         manifest.parent.mkdir(parents=True)
-        cmd = "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py Stop"
+        cmd = "$AIPASS_HOME/bin/hook-bridge Stop"
         manifest.write_text(
             json.dumps(
                 {
@@ -573,3 +571,174 @@ class TestProviderManifest:
         result = _find_manifest()
         assert result is not None
         assert result == manifest
+
+
+# =============================================================================
+# TestHooksJsonCheck
+# =============================================================================
+
+
+class TestHooksJsonCheck:
+    """Tests for hooks.json presence check in _check_identity (DPLAN-0190)."""
+
+    def test_hooks_json_present_returns_pass(self, tmp_path) -> None:
+        """When .aipass/hooks.json exists, check returns PASS."""
+        from aipass.aipass.apps.modules.doctor import _check_identity
+
+        registry = tmp_path / "TEST_REGISTRY.json"
+        registry.write_text(json.dumps({"metadata": {"id": "t"}, "branches": []}), encoding="utf-8")
+        hooks_dir = tmp_path / ".aipass"
+        hooks_dir.mkdir()
+        (hooks_dir / "hooks.json").write_text('{"hooks_enabled": true}', encoding="utf-8")
+
+        with patch("aipass.aipass.apps.modules.doctor._find_registry", return_value=registry):
+            results = _check_identity()
+
+        hooks_results = [r for r in results if r.label == "hooks.json"]
+        assert len(hooks_results) == 1
+        assert hooks_results[0].glyph == GLYPH_PASS
+
+    def test_hooks_json_missing_returns_warn(self, tmp_path) -> None:
+        """When .aipass/hooks.json is absent, check returns WARN."""
+        from aipass.aipass.apps.modules.doctor import _check_identity
+
+        registry = tmp_path / "TEST_REGISTRY.json"
+        registry.write_text(json.dumps({"metadata": {"id": "t"}, "branches": []}), encoding="utf-8")
+
+        with patch("aipass.aipass.apps.modules.doctor._find_registry", return_value=registry):
+            results = _check_identity()
+
+        hooks_results = [r for r in results if r.label == "hooks.json"]
+        assert len(hooks_results) == 1
+        assert hooks_results[0].glyph == GLYPH_WARN
+        assert "init update" in hooks_results[0].remediation
+
+
+# =============================================================================
+# TestReconcileStaleDeny
+# =============================================================================
+
+
+class TestReconcileStaleDeny:
+    """Tests for stale rm deny rule migration (DPLAN-0192 Phase 2)."""
+
+    def test_no_settings_file_returns_empty(self, tmp_path) -> None:
+        """Missing settings.json returns no results."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            results = reconcile_stale_deny(fix=False)
+        assert results == []
+
+    def test_no_stale_rules_returns_pass(self, tmp_path) -> None:
+        """Settings with no stale rm rules returns PASS."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        settings = tmp_path / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True)
+        settings.write_text(
+            json.dumps({"permissions": {"deny": ["Bash(git push --force*)", "Bash(git reset --hard*)"]}}),
+            encoding="utf-8",
+        )
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            results = reconcile_stale_deny(fix=False)
+        assert len(results) == 1
+        assert results[0][1] == GLYPH_PASS
+        assert "no stale" in results[0][2]
+
+    def test_stale_rules_detected_without_fix(self, tmp_path) -> None:
+        """Stale rm rules present returns WARN when fix=False."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        settings = tmp_path / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True)
+        settings.write_text(
+            json.dumps({"permissions": {"deny": ["Bash(rm -rf*)", "Bash(git push --force*)", "Bash(rm -r *)"]}}),
+            encoding="utf-8",
+        )
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            results = reconcile_stale_deny(fix=False)
+        assert len(results) == 1
+        assert results[0][1] == GLYPH_WARN
+        assert "rm -rf" in results[0][2]
+        assert "rm -r " in results[0][2]
+
+    def test_fix_removes_stale_rules(self, tmp_path) -> None:
+        """fix=True removes stale rules and preserves others."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        settings = tmp_path / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True)
+        original = {
+            "permissions": {"deny": ["Bash(rm -rf*)", "Bash(git push --force*)", "Bash(rm -r *)"]},
+            "env": {"AIPASS_HOME": "/test"},
+        }
+        settings.write_text(json.dumps(original), encoding="utf-8")
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            results = reconcile_stale_deny(fix=True)
+        assert len(results) == 1
+        assert results[0][1] == GLYPH_PASS
+        assert "removed" in results[0][2]
+        updated = json.loads(settings.read_text(encoding="utf-8"))
+        assert "Bash(rm -rf*)" not in updated["permissions"]["deny"]
+        assert "Bash(rm -r *)" not in updated["permissions"]["deny"]
+        assert "Bash(git push --force*)" in updated["permissions"]["deny"]
+        assert updated["env"]["AIPASS_HOME"] == "/test"
+
+    def test_fix_single_stale_rule(self, tmp_path) -> None:
+        """fix=True works when only one of two stale rules is present."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        settings = tmp_path / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True)
+        settings.write_text(
+            json.dumps({"permissions": {"deny": ["Bash(rm -rf*)", "Bash(git reset --hard*)"]}}),
+            encoding="utf-8",
+        )
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            results = reconcile_stale_deny(fix=True)
+        assert len(results) == 1
+        assert results[0][1] == GLYPH_PASS
+        updated = json.loads(settings.read_text(encoding="utf-8"))
+        assert updated["permissions"]["deny"] == ["Bash(git reset --hard*)"]
+
+    def test_fix_idempotent(self, tmp_path) -> None:
+        """Running fix twice is safe — second run returns PASS with no stale rules."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        settings = tmp_path / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True)
+        settings.write_text(
+            json.dumps({"permissions": {"deny": ["Bash(rm -rf*)", "Bash(rm -r *)"]}}),
+            encoding="utf-8",
+        )
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            reconcile_stale_deny(fix=True)
+            results = reconcile_stale_deny(fix=True)
+        assert len(results) == 1
+        assert results[0][1] == GLYPH_PASS
+        assert "no stale" in results[0][2]
+
+    def test_empty_deny_list_returns_pass(self, tmp_path) -> None:
+        """Empty deny list returns PASS."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        settings = tmp_path / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True)
+        settings.write_text(json.dumps({"permissions": {"deny": []}}), encoding="utf-8")
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            results = reconcile_stale_deny(fix=False)
+        assert len(results) == 1
+        assert results[0][1] == GLYPH_PASS
+
+    def test_no_permissions_key_returns_pass(self, tmp_path) -> None:
+        """Settings without permissions key returns PASS."""
+        from aipass.aipass.apps.modules.doctor_wire import reconcile_stale_deny
+
+        settings = tmp_path / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True)
+        settings.write_text(json.dumps({"env": {"FOO": "bar"}}), encoding="utf-8")
+        with patch("aipass.aipass.apps.modules.doctor_wire.Path.home", return_value=tmp_path):
+            results = reconcile_stale_deny(fix=False)
+        assert len(results) == 1
+        assert results[0][1] == GLYPH_PASS

src/aipass/aipass/tests/test_doctor_fix.py

@@ -65,8 +65,14 @@ class TestDetectProjectName:
 
     def test_fallback_to_dirname(self, tmp_path: Path) -> None:
         """Falls back to directory name when no registry."""
-        result = detect_project_name(tmp_path)
-        assert result == tmp_path.name.lower()
+        no_reg = tmp_path / "empty_project"
+        no_reg.mkdir()
+        with patch(
+            "aipass.aipass.apps.modules.doctor_fix._discover_registry",
+            return_value=no_reg / "MISSING_REGISTRY.json",
+        ):
+            result = detect_project_name(no_reg)
+        assert result == "empty_project"
 
     def test_registry_name_lowered(self, tmp_path: Path) -> None:
         """Registry name is lowercased."""
@@ -248,10 +254,13 @@ class TestFormatTextReport:
         assert "drone @spawn repair @test --relocate a b" in result
 
     def test_dry_run_hint(self) -> None:
-        """Report ends with dry-run suggestion."""
+        """Report shows preview (dry-run default) and explicit --apply hints."""
         items = [RemediationItem("info", "pyproject", "missing", "fix")]
         result = format_text_report(items, "myproj")
-        assert "drone @spawn repair @myproj --dry-run" in result
+        # Repair is dry-run by default now: preview form has no flag, apply form is explicit
+        assert "Preview all fixes:" in result
+        assert "drone @spawn repair @myproj" in result
+        assert "drone @spawn repair @myproj --apply" in result
 
     def test_critical_sorted_first(self) -> None:
         """Critical items appear before warning and info."""
@@ -364,14 +373,15 @@ class TestDoctorFixHandleCommand:
         assert handle_command("doctor", []) is False
         assert handle_command("help", []) is False
 
-    def test_no_args_calls_introspection(self) -> None:
-        """No args triggers print_introspection."""
+    def test_no_args_shows_usage(self) -> None:
+        """No args shows usage message (not introspection banner)."""
         from aipass.aipass.apps.modules.doctor_fix import handle_command
 
-        with patch("aipass.aipass.apps.modules.doctor_fix.print_introspection") as mock:
+        with patch("aipass.aipass.apps.modules.doctor_fix.console") as mock_console:
             result = handle_command("doctor_fix", [])
         assert result is True
-        mock.assert_called_once()
+        printed = " ".join(str(c) for c in mock_console.print.call_args_list)
+        assert "aipass doctor --fix" in printed
 
     def test_info_flag(self) -> None:
         """--info triggers print_introspection."""

src/aipass/aipass/tests/test_help_chat.py

@@ -52,20 +52,6 @@ _ENCODING = "utf-8"
 # =============================================================================
 
 
-def _call_handle_command_no_args():
-    """Call handle_command('help', []) with json_handler and console mocked."""
-    mock_console = MagicMock()
-    patches = [
-        patch("aipass.aipass.apps.modules.help_chat.json_handler"),
-        patch("aipass.aipass.apps.modules.help_chat.console", mock_console),
-    ]
-    with ExitStack() as stack:
-        for p in patches:
-            stack.enter_context(p)
-        result = handle_command("help", [])
-    return result, mock_console
-
-
 def _call_handle_command_drone_question(readme_content: str, readme_path: Path):
     """Call handle_command for 'what does drone do' with file I/O mocked."""
     patches = [
@@ -254,54 +240,57 @@ class TestMatchBranches:
 
 
 class TestSearchReadme:
-    """Tests for _search_readme: live file reads, scoring, and error handling."""
+    """Tests for _search_readme: live file reads via handler, scoring, and error handling."""
+
+    def _mock_lines(self, content):
+        """Return a patch that makes read_readme_lines return content as lines."""
+        lines = content.splitlines(keepends=True)
+        return patch("aipass.aipass.apps.modules.help_chat.read_readme_lines", return_value=lines)
 
     def test_returns_matching_lines_with_line_numbers(self):
         """Matching lines must be returned as (int, str) tuples."""
-        with patch("builtins.open", mock_open(read_data=_SAMPLE_README)):
-            results = _search_readme(_FAKE_README_PATH, ["drone"])
+        with self._mock_lines(_SAMPLE_README):
+            results = _search_readme("drone", ["drone"])
         assert len(results) > 0
         assert all(isinstance(ln, int) for ln, _ in results)
 
     def test_line_numbers_are_1_indexed(self):
         """Line numbers in results must start at 1, not 0."""
-        with patch("builtins.open", mock_open(read_data=_SAMPLE_README)):
-            results = _search_readme(_FAKE_README_PATH, ["drone"])
+        with self._mock_lines(_SAMPLE_README):
+            results = _search_readme("drone", ["drone"])
         assert all(ln >= 1 for ln, _ in results)
 
     def test_returns_at_most_5_matches(self):
         """Result list must contain no more than 5 entries."""
         content = "\n".join([f"drone line {i}" for i in range(10)])
-        with patch("builtins.open", mock_open(read_data=content)):
-            results = _search_readme(_FAKE_README_PATH, ["drone"])
+        with self._mock_lines(content):
+            results = _search_readme("drone", ["drone"])
         assert len(results) <= 5
 
     def test_no_keyword_match_returns_empty(self):
         """Keyword with no hits in the README must return an empty list."""
-        with patch("builtins.open", mock_open(read_data=_SAMPLE_README)):
-            results = _search_readme(_FAKE_README_PATH, ["xyzzy999"])
+        with self._mock_lines(_SAMPLE_README):
+            results = _search_readme("drone", ["xyzzy999"])
         assert results == []
 
-    def test_oserror_returns_empty_and_logs_warning(self):
-        """OSError on open must return [] and call logger.warning exactly once."""
-        with patch("builtins.open", side_effect=OSError("not found")):
+    def test_handler_returns_none_returns_empty_and_logs(self):
+        """None from handler must return [] and call logger.warning."""
+        with patch("aipass.aipass.apps.modules.help_chat.read_readme_lines", return_value=None):
             with patch("aipass.aipass.apps.modules.help_chat.logger") as mock_logger:
-                results = _search_readme(_FAKE_README_PATH, ["drone"])
+                results = _search_readme("nonexistent", ["drone"])
         assert results == []
         mock_logger.warning.assert_called_once()
 
     def test_matching_is_case_insensitive(self):
         """Uppercase keyword in README must still match a lowercase query keyword."""
-        content = "DRONE does routing\n"
-        with patch("builtins.open", mock_open(read_data=content)):
-            results = _search_readme(_FAKE_README_PATH, ["drone"])
+        with self._mock_lines("DRONE does routing\n"):
+            results = _search_readme("drone", ["drone"])
         assert len(results) == 1
 
     def test_higher_scoring_lines_ranked_first(self):
         """Lines matching more keywords must appear before lines matching fewer."""
-        content = "drone flow spawn\ndrone only\nflow only\n"
-        with patch("builtins.open", mock_open(read_data=content)):
-            results = _search_readme(_FAKE_README_PATH, ["drone", "flow"])
+        with self._mock_lines("drone flow spawn\ndrone only\nflow only\n"):
+            results = _search_readme("drone", ["drone", "flow"])
         first_text = results[0][1]
         assert "drone" in first_text and "flow" in first_text
 
@@ -367,11 +356,21 @@ class TestHandleCommand:
         """COMMAND module constant must equal the string 'help'."""
         assert COMMAND == "help"
 
-    def test_no_args_returns_true_and_calls_console(self):
-        """handle_command('help', []) must return True and print usage via console."""
-        result, mock_console = _call_handle_command_no_args()
+    def test_no_args_returns_true_and_shows_help(self):
+        """handle_command('help', []) must return True and print usage help."""
+        with patch("aipass.aipass.apps.modules.help_chat.print_help") as mock_help:
+            with patch("aipass.aipass.apps.modules.help_chat.json_handler"):
+                result = handle_command("help", [])
         assert result is True
-        mock_console.print.assert_called()
+        mock_help.assert_called_once()
+
+    def test_info_flag_calls_introspection(self):
+        """--info flag triggers print_introspection."""
+        with patch("aipass.aipass.apps.modules.help_chat.print_introspection") as mock_intro:
+            with patch("aipass.aipass.apps.modules.help_chat.json_handler"):
+                result = handle_command("help", ["--info"])
+        assert result is True
+        mock_intro.assert_called_once()
 
     def test_valid_drone_question_returns_true(self):
         """A well-formed question about drone must return True."""

src/aipass/aipass/tests/test_init_flow.py

@@ -19,6 +19,7 @@ from aipass.aipass.apps.modules.init_flow import (
     TOTAL_STAGES,
     _get_last_completed_stage,
     _get_setup_progress,
+    _handle_init_update,
     _save_stage,
     handle_command,
     print_help,
@@ -198,11 +199,18 @@ class TestHandleCommand:
         assert handle_command("doctor", []) is False
         assert handle_command("profile", ["set", "name", "X"]) is False
 
-    def test_no_args_shows_introspection(self, tmp_local_json) -> None:
-        """'init' with no args calls print_introspection."""
-        with patch("aipass.aipass.apps.modules.init_flow.print_introspection") as mock_intro:
+    def test_no_args_shows_help(self, tmp_local_json) -> None:
+        """'init' with no args calls print_help (not introspection banner)."""
+        with patch("aipass.aipass.apps.modules.init_flow.print_help") as mock_help:
             result = handle_command("init", [])
         assert result is True
+        mock_help.assert_called_once()
+
+    def test_info_flag_calls_introspection(self, tmp_local_json) -> None:
+        """--info flag calls print_introspection."""
+        with patch("aipass.aipass.apps.modules.init_flow.print_introspection") as mock_intro:
+            result = handle_command("init", ["--info"])
+        assert result is True
         mock_intro.assert_called_once()
 
     def test_help_flag(self) -> None:
@@ -480,6 +488,66 @@ class TestStages:
                 result = stage_6_tool_choice(non_interactive=True, cli_override="codex")
         assert result["cli"] == "codex"
 
+    def test_stage_6_claude_present_no_prompt(self, tmp_local_json) -> None:
+        """When claude is on PATH, no install prompt is shown."""
+        mock_profile_mod = MagicMock()
+        mock_profile_mod.get_user_profile.return_value = {}
+        with patch(f"{_MOD}.console"):
+            with patch(f"{_MOD}.shutil.which", return_value="/usr/bin/claude"):
+                with patch.dict("sys.modules", {"aipass.aipass.apps.modules.profile": mock_profile_mod}):
+                    with patch(f"{_MOD}._handle_missing_claude") as mock_handle:
+                        result = stage_6_tool_choice(non_interactive=True)
+        mock_handle.assert_not_called()
+        assert result["cli"] == "claude"
+
+    @patch(f"{_MOD}._choose", return_value="default")
+    @patch(f"{_MOD}._install_claude_code", return_value=True)
+    @patch(f"{_MOD}._prompt", return_value="Y")
+    @patch(f"{_MOD}.shutil.which", return_value=None)
+    @patch(f"{_MOD}.console")
+    def test_stage_6_claude_missing_interactive_yes(
+        self, _con, _which, _prompt, mock_install, _choose, tmp_local_json
+    ) -> None:
+        """Missing claude + interactive + yes → installer invoked."""
+        mock_profile_mod = MagicMock()
+        mock_profile_mod.get_user_profile.return_value = {}
+        with patch.dict("sys.modules", {"aipass.aipass.apps.modules.profile": mock_profile_mod}):
+            result = stage_6_tool_choice(non_interactive=False, cli_override="claude")
+        mock_install.assert_called_once()
+        assert result["cli"] == "claude"
+
+    @patch(f"{_MOD}._choose", return_value="default")
+    @patch(f"{_MOD}._install_claude_code")
+    @patch(f"{_MOD}._prompt", return_value="n")
+    @patch(f"{_MOD}.shutil.which", return_value=None)
+    @patch(f"{_MOD}.console")
+    def test_stage_6_claude_missing_interactive_no(
+        self, _con, _which, _prompt, mock_install, _choose, tmp_local_json
+    ) -> None:
+        """Missing claude + interactive + no → no install, continues."""
+        mock_profile_mod = MagicMock()
+        mock_profile_mod.get_user_profile.return_value = {}
+        with patch.dict("sys.modules", {"aipass.aipass.apps.modules.profile": mock_profile_mod}):
+            result = stage_6_tool_choice(non_interactive=False, cli_override="claude")
+        mock_install.assert_not_called()
+        assert result["cli"] == "claude"
+
+    @patch(f"{_MOD}.warning")
+    @patch(f"{_MOD}._install_claude_code")
+    @patch(f"{_MOD}.shutil.which", return_value=None)
+    @patch(f"{_MOD}.console")
+    def test_stage_6_claude_missing_non_interactive_warns(
+        self, _con, _which, mock_install, mock_warn, tmp_local_json
+    ) -> None:
+        """Missing claude + non-interactive → warning, no install."""
+        mock_profile_mod = MagicMock()
+        mock_profile_mod.get_user_profile.return_value = {}
+        with patch.dict("sys.modules", {"aipass.aipass.apps.modules.profile": mock_profile_mod}):
+            result = stage_6_tool_choice(non_interactive=True)
+        mock_install.assert_not_called()
+        mock_warn.assert_called_once()
+        assert result["cli"] == "claude"
+
     def test_stage_7_skipped_when_no_docker(self, tmp_local_json) -> None:
         """Docker offer is skipped when has_docker=False."""
         with patch(f"{_MOD}.console"):
@@ -499,14 +567,14 @@ class TestStages:
         assert result["docker"] == "skipped"
 
     def test_stage_8_non_interactive_creates_my_agent(self, tmp_local_json) -> None:
-        """non_interactive=True uses 'my-agent' as default name."""
+        """non_interactive=True uses 'my_agent' as default name."""
         mock_proc = MagicMock(returncode=0)
         with patch(f"{_MOD}.console"):
             with patch(f"{_MOD}.subprocess.run", return_value=mock_proc):
                 with patch(f"{_MOD}._resolve_package_dir", return_value=None):
                     result = stage_8_first_agent(non_interactive=True)
-        assert result["agent_name"] == "my-agent"
-        assert result["agent_path"] == "src/my-agent"
+        assert result["agent_name"] == "my_agent"
+        assert result["agent_path"] == "src/my_agent"
 
     def test_stage_8_drone_not_found(self, tmp_local_json) -> None:
         """FileNotFoundError from drone is handled gracefully."""
@@ -567,3 +635,87 @@ class TestStages:
         assert result == {}
         stored = json.loads(tmp_local_json.read_text())
         assert stored["setup_progress"]["last_completed_stage"] == 12
+
+
+# =============================================================================
+# init_update_registry_sync: subprocess_sync
+# =============================================================================
+
+
+_MOD_UPDATE = "aipass.aipass.apps.modules.init_flow"
+
+
+class TestInitUpdateRegistrySync:
+    """Tests for registry sync subprocess call in _handle_init_update."""
+
+    def test_sync_success_prints_message(self, tmp_path: Path) -> None:
+        """Successful drone sync-registry prints 'Registry synced.'"""
+        mock_result = MagicMock(returncode=0)
+        with (
+            patch(
+                "aipass.aipass.apps.handlers.init.bootstrap.update_project",
+                return_value={"updated_files": [], "already_current": []},
+            ),
+            patch(f"{_MOD_UPDATE}.subprocess.run", return_value=mock_result) as mock_run,
+            patch(f"{_MOD_UPDATE}.console") as mock_console,
+            patch(f"{_MOD_UPDATE}.json_handler"),
+        ):
+            rc = _handle_init_update([str(tmp_path)])
+        assert rc == 0
+        mock_run.assert_called_once_with(
+            ["drone", "@spawn", "sync-registry", "--fix"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        sync_calls = [c for c in mock_console.print.call_args_list if "Registry synced" in str(c)]
+        assert len(sync_calls) == 1
+
+    def test_sync_failure_degrades_silently(self, tmp_path: Path) -> None:
+        """Non-zero exit from drone sync-registry is silently skipped."""
+        mock_result = MagicMock(returncode=1)
+        with (
+            patch(
+                "aipass.aipass.apps.handlers.init.bootstrap.update_project",
+                return_value={"updated_files": [], "already_current": []},
+            ),
+            patch(f"{_MOD_UPDATE}.subprocess.run", return_value=mock_result),
+            patch(f"{_MOD_UPDATE}.console") as mock_console,
+            patch(f"{_MOD_UPDATE}.json_handler"),
+        ):
+            rc = _handle_init_update([str(tmp_path)])
+        assert rc == 0
+        sync_calls = [c for c in mock_console.print.call_args_list if "Registry synced" in str(c)]
+        assert len(sync_calls) == 0
+
+    def test_sync_missing_drone_degrades_silently(self, tmp_path: Path) -> None:
+        """FileNotFoundError (no drone binary) degrades gracefully."""
+        with (
+            patch(
+                "aipass.aipass.apps.handlers.init.bootstrap.update_project",
+                return_value={"updated_files": [], "already_current": []},
+            ),
+            patch(f"{_MOD_UPDATE}.subprocess.run", side_effect=FileNotFoundError("drone not found")),
+            patch(f"{_MOD_UPDATE}.console") as mock_console,
+            patch(f"{_MOD_UPDATE}.json_handler"),
+        ):
+            rc = _handle_init_update([str(tmp_path)])
+        assert rc == 0
+        sync_calls = [c for c in mock_console.print.call_args_list if "Registry synced" in str(c)]
+        assert len(sync_calls) == 0
+
+    def test_sync_timeout_degrades_silently(self, tmp_path: Path) -> None:
+        """subprocess.TimeoutExpired degrades gracefully."""
+        import subprocess as _sp
+
+        with (
+            patch(
+                "aipass.aipass.apps.handlers.init.bootstrap.update_project",
+                return_value={"updated_files": [], "already_current": []},
+            ),
+            patch(f"{_MOD_UPDATE}.subprocess.run", side_effect=_sp.TimeoutExpired(cmd="drone", timeout=30)),
+            patch(f"{_MOD_UPDATE}.console"),
+            patch(f"{_MOD_UPDATE}.json_handler"),
+        ):
+            rc = _handle_init_update([str(tmp_path)])
+        assert rc == 0

src/aipass/aipass/tests/test_json_handler.py

@@ -9,11 +9,12 @@
 """Tests for json_handler — default_factory, validate, get_path, ensure_exists, load, save, ensure_module."""
 
 import json
+
+import pytest
 from unittest.mock import patch
 
 from aipass.aipass.apps.handlers.json.json_handler import (
     AIPASS_JSON_DIR,
-    _default_template,
     ensure_json_exists,
     ensure_module_jsons,
     get_json_path,
@@ -30,31 +31,39 @@ from aipass.aipass.apps.handlers.json.json_handler import (
 
 
 class TestDefaultFactory:
-    """Tests for _default_template factory function."""
+    """Tests for default JSON creation via ensure_json_exists."""
 
-    def test_config_template(self):
+    def test_config_template(self, tmp_path):
         """Config template includes module_name, version, config, created."""
-        result = _default_template("config", "test_mod")
+        with patch("aipass.aipass.apps.handlers.json.json_handler.AIPASS_JSON_DIR", tmp_path):
+            ensure_json_exists("test_mod", "config")
+            result = json.loads((tmp_path / "test_mod_config.json").read_text())
         assert result["module_name"] == "test_mod"
         assert result["version"] == "1.0.0"
         assert "config" in result
         assert "created" in result
 
-    def test_data_template(self):
+    def test_data_template(self, tmp_path):
         """Data template includes created and last_updated."""
-        result = _default_template("data", "test_mod")
+        with patch("aipass.aipass.apps.handlers.json.json_handler.AIPASS_JSON_DIR", tmp_path):
+            ensure_json_exists("test_mod", "data")
+            result = json.loads((tmp_path / "test_mod_data.json").read_text())
         assert "created" in result
         assert "last_updated" in result
 
-    def test_log_template(self):
+    def test_log_template(self, tmp_path):
         """Log template is an empty list."""
-        result = _default_template("log", "test_mod")
+        with patch("aipass.aipass.apps.handlers.json.json_handler.AIPASS_JSON_DIR", tmp_path):
+            ensure_json_exists("test_mod", "log")
+            result = json.loads((tmp_path / "test_mod_log.json").read_text())
         assert result == []
 
-    def test_unknown_type_returns_none(self):
-        """Unknown json_type returns None."""
-        result = _default_template("unknown_type", "test_mod")
-        assert result is None
+    def test_unknown_type_raises(self):
+        """Unknown json_type raises ValueError."""
+        from aipass.aipass.shared.json_handler import JsonHandler
+
+        with pytest.raises(ValueError):
+            JsonHandler._create_default("unknown_type", "test_mod")
 
 
 # =============================================================================
@@ -200,10 +209,20 @@ class TestSave:
             assert saved["module_name"] == "s"
 
     def test_save_invalid_structure_rejected(self, tmp_path):
-        """Invalid structure is rejected with False."""
+        """Invalid structure raises ValueError."""
         with patch("aipass.aipass.apps.handlers.json.json_handler.AIPASS_JSON_DIR", tmp_path):
-            result = save_json("s", "config", {"bad": True})
-            assert result is False
+            with pytest.raises(ValueError):
+                save_json("s", "config", {"bad": True})
+
+    def test_save_unknown_returns_false(self, tmp_path):
+        """save_json returns False when write fails (e.g. read-only dir)."""
+        ro_dir = tmp_path / "readonly"
+        ro_dir.mkdir()
+        with patch("aipass.aipass.apps.handlers.json.json_handler.AIPASS_JSON_DIR", ro_dir):
+            data = {"module_name": "s", "version": "1.0.0", "config": {}, "created": "2026-01-01"}
+            with patch("aipass.aipass.shared.json_handler.JsonHandler.write_json", return_value=False):
+                result = save_json("s", "config", data)
+                assert result is False
 
 
 # =============================================================================
@@ -239,7 +258,7 @@ class TestLoadPath:
         result = load_path(f)
         assert result == {"key": "value"}
 
-    def test_load_missing_file(self, tmp_path):
+    def test_unknown_file_returns_none(self, tmp_path):
         """Missing file returns None."""
         result = load_path(tmp_path / "nope.json")
         assert result is None
@@ -290,7 +309,9 @@ class TestReturnTypeContracts:
         """Doctor handle_command returns True for match, False otherwise."""
         from aipass.aipass.apps.modules.doctor import handle_command as doctor_cmd
 
-        assert doctor_cmd("doctor", []) is True
+        with patch("aipass.aipass.apps.modules.doctor.run_doctor", return_value=0):
+            with patch("aipass.aipass.apps.modules.doctor.json_handler"):
+                assert doctor_cmd("doctor", []) is True
         assert doctor_cmd("not_doctor", []) is False
 
     def test_help_chat_handle_command_returns_bool(self):
@@ -324,14 +345,14 @@ class TestExceptionContracts:
     """Tests that invalid inputs raise appropriate exceptions."""
 
     def test_invalid_mode_raises(self, tmp_path):
-        """save_json with invalid structure returns False (not silent pass)."""
+        """save_json with invalid structure raises ValueError."""
         with patch("aipass.aipass.apps.handlers.json.json_handler.AIPASS_JSON_DIR", tmp_path):
-            result = save_json("x", "config", [])
-            assert result is False
-            result = save_json("x", "data", "string")
-            assert result is False
-            result = save_json("x", "log", {"not": "a list"})
-            assert result is False
+            with pytest.raises(ValueError):
+                save_json("x", "config", [])
+            with pytest.raises(ValueError):
+                save_json("x", "data", "string")
+            with pytest.raises(ValueError):
+                save_json("x", "log", {"not": "a list"})
 
 
 # =============================================================================
@@ -355,3 +376,13 @@ class TestInfrastructureMocking:
         assert callable(jh_mod.load_json)
         assert callable(jh_mod.save_json)
         assert callable(jh_mod.load_path)
+
+
+# =============================================================================
+# success_failure_paths: unknown_returns_false
+# =============================================================================
+
+
+def test_unknown_returns_false():
+    """validate_json_structure returns False for unrecognized json_type."""
+    assert validate_json_structure({}, "bogus") is False

src/aipass/aipass/tests/test_profile.py

@@ -170,12 +170,19 @@ class TestHandleCommand:
         assert handle_command("init", ["run"]) is False
 
     def test_no_args_calls_introspection(self, tmp_local_json) -> None:
-        """'profile' with no args calls print_introspection."""
+        """'profile' with no args shows the profile (runs the command)."""
         with patch("aipass.aipass.apps.modules.profile.print_introspection") as mock_pi:
             result = handle_command("profile", [])
         assert result is True
         mock_pi.assert_called_once()
 
+    def test_info_flag_calls_introspection(self, tmp_local_json) -> None:
+        """--info flag calls print_introspection."""
+        with patch("aipass.aipass.apps.modules.profile.print_introspection") as mock_pi:
+            result = handle_command("profile", ["--info"])
+        assert result is True
+        mock_pi.assert_called_once()
+
     def test_help_flag_returns_true(self) -> None:
         """--help flag is handled."""
         with patch("aipass.aipass.apps.modules.profile.print_help"):

src/aipass/aipass/tests/test_sandbox_check.py

@@ -0,0 +1,585 @@
+# =================== AIPass ====================
+# Name: test_sandbox_check.py
+# Description: Tests for sandbox prerequisite checker and doctor integration
+# Version: 1.0.0
+# Created: 2026-06-10
+# Modified: 2026-06-10
+# =============================================
+
+"""Tests for sandbox prereq checks — handler + doctor integration."""
+
+import shutil
+import socket
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest  # pyright: ignore[reportMissingImports]
+
+from aipass.aipass.apps.handlers.sandbox_check.sandbox_checker import (
+    check_broker_alive,
+    check_bwrap_functional,
+    check_bwrap_present,
+    check_node_present,
+    check_rg_present,
+    check_sandbox_flag,
+    check_srt_resolvable,
+    is_linux,
+)
+from aipass.aipass.apps.handlers.ui.progress import GLYPH_FAIL, GLYPH_PASS, GLYPH_WARN
+from aipass.aipass.apps.modules.doctor import _check_sandbox
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture(autouse=True)
+def _stub_json_handler():
+    """Suppress json_handler.log_operation side effects in all tests."""
+    with patch("aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.json_handler") as mock:
+        mock.log_operation = MagicMock()
+        yield mock
+
+
+# =============================================================================
+# check_sandbox_flag
+# =============================================================================
+
+
+class TestCheckSandboxFlag:
+    def test_flag_off_by_default(self, monkeypatch):
+        monkeypatch.delenv("AIPASS_SANDBOX_ENABLED", raising=False)
+        result = check_sandbox_flag()
+        assert result["enabled"] is False
+        assert result["raw_value"] == ""
+
+    def test_flag_on_with_1(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+        result = check_sandbox_flag()
+        assert result["enabled"] is True
+
+    def test_flag_on_with_true(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "true")
+        result = check_sandbox_flag()
+        assert result["enabled"] is True
+
+    def test_flag_on_with_yes(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "yes")
+        result = check_sandbox_flag()
+        assert result["enabled"] is True
+
+    def test_flag_on_case_insensitive(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "TRUE")
+        result = check_sandbox_flag()
+        assert result["enabled"] is True
+
+    def test_flag_off_with_garbage(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "maybe")
+        result = check_sandbox_flag()
+        assert result["enabled"] is False
+
+
+# =============================================================================
+# check_bwrap_present
+# =============================================================================
+
+
+class TestCheckBwrapPresent:
+    def test_bwrap_found(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/bwrap" if name == "bwrap" else None)
+        result = check_bwrap_present()
+        assert result["found"] is True
+        assert result["path"] == "/usr/bin/bwrap"
+
+    def test_bwrap_not_found(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: None)
+        result = check_bwrap_present()
+        assert result["found"] is False
+        assert result["path"] is None
+
+    @pytest.mark.skipif(not shutil.which("bwrap"), reason="bwrap not installed")
+    def test_bwrap_live(self):
+        result = check_bwrap_present()
+        assert result["found"] is True
+        assert "bwrap" in result["path"]
+
+
+# =============================================================================
+# check_bwrap_functional
+# =============================================================================
+
+
+class TestCheckBwrapFunctional:
+    def test_bwrap_missing(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: None)
+        result = check_bwrap_functional()
+        assert result["ok"] is False
+        assert "not found" in result["detail"]
+
+    def test_bwrap_succeeds(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/bwrap" if name == "bwrap" else None)
+        mock_proc = MagicMock(returncode=0, stderr="")
+        with patch(
+            "aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.subprocess.run",
+            return_value=mock_proc,
+        ) as mock_run:
+            result = check_bwrap_functional()
+        assert result["ok"] is True
+        argv = mock_run.call_args[0][0]
+        assert argv[0] == "/usr/bin/bwrap"
+        assert "--ro-bind" in argv
+        assert "true" in argv
+
+    def test_bwrap_fails_reports_sysctl(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/bwrap" if name == "bwrap" else None)
+        mock_proc = MagicMock(returncode=1, stderr="permission denied")
+        with (
+            patch(
+                "aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.subprocess.run",
+                return_value=mock_proc,
+            ),
+            patch(
+                "aipass.aipass.apps.handlers.sandbox_check.sandbox_checker._read_userns_sysctl",
+                return_value="1",
+            ),
+        ):
+            result = check_bwrap_functional()
+        assert result["ok"] is False
+        assert "exit 1" in result["detail"]
+        assert result["sysctl_value"] == "1"
+
+    def test_bwrap_timeout(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/bwrap" if name == "bwrap" else None)
+        with patch(
+            "aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.subprocess.run",
+            side_effect=subprocess.TimeoutExpired(cmd="bwrap", timeout=10),
+        ):
+            result = check_bwrap_functional()
+        assert result["ok"] is False
+        assert "timed out" in result["detail"]
+
+    @pytest.mark.skipif(not shutil.which("bwrap"), reason="bwrap not installed")
+    def test_bwrap_functional_live(self):
+        result = check_bwrap_functional()
+        assert isinstance(result["ok"], bool)
+        if result["ok"]:
+            assert "succeeded" in result["detail"]
+
+
+# =============================================================================
+# check_node_present
+# =============================================================================
+
+
+class TestCheckNodePresent:
+    def test_node_found(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/node" if name == "node" else None)
+        result = check_node_present()
+        assert result["found"] is True
+        assert result["path"] == "/usr/bin/node"
+
+    def test_node_not_found(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: None)
+        result = check_node_present()
+        assert result["found"] is False
+
+    @pytest.mark.skipif(not shutil.which("node"), reason="node not installed")
+    def test_node_live(self):
+        result = check_node_present()
+        assert result["found"] is True
+
+
+# =============================================================================
+# check_srt_resolvable
+# =============================================================================
+
+
+class TestCheckSrtResolvable:
+    def test_no_node(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: None)
+        result = check_srt_resolvable()
+        assert result["found"] is False
+        assert "node" in result["install_hint"].lower()
+
+    def test_srt_found(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/node" if name == "node" else None)
+        mock_proc = MagicMock(returncode=0, stdout="/usr/lib/node_modules/@anthropic-ai/sandbox-runtime/dist/index.js")
+        with patch(
+            "aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.subprocess.run",
+            return_value=mock_proc,
+        ) as mock_run:
+            result = check_srt_resolvable()
+        assert result["found"] is True
+        assert "sandbox-runtime" in result["path"]
+        argv = mock_run.call_args[0][0]
+        assert argv[0] == "/usr/bin/node"
+        assert argv[1] == "-e"
+
+    def test_srt_not_found(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/node" if name == "node" else None)
+        mock_proc = MagicMock(returncode=1, stdout="")
+        with patch(
+            "aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.subprocess.run",
+            return_value=mock_proc,
+        ):
+            result = check_srt_resolvable()
+        assert result["found"] is False
+        assert "npm install" in result["install_hint"]
+
+    def test_srt_timeout(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/node" if name == "node" else None)
+        with patch(
+            "aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.subprocess.run",
+            side_effect=subprocess.TimeoutExpired(cmd="node", timeout=10),
+        ):
+            result = check_srt_resolvable()
+        assert result["found"] is False
+
+
+# =============================================================================
+# check_rg_present
+# =============================================================================
+
+
+class TestCheckRgPresent:
+    def test_rg_on_path(self, monkeypatch):
+        monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/rg" if name == "rg" else None)
+        result = check_rg_present()
+        assert result["found"] is True
+        assert result["path"] == "/usr/bin/rg"
+
+    def test_rg_not_on_path_but_in_local_bin(self, monkeypatch, tmp_path):
+        monkeypatch.setattr(shutil, "which", lambda name: None)
+        fake_rg = tmp_path / ".local" / "bin" / "rg"
+        fake_rg.parent.mkdir(parents=True)
+        fake_rg.touch()
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        result = check_rg_present()
+        assert result["found"] is True
+        assert str(fake_rg) == result["path"]
+
+    def test_rg_not_found(self, monkeypatch, tmp_path):
+        monkeypatch.setattr(shutil, "which", lambda name: None)
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        result = check_rg_present()
+        assert result["found"] is False
+
+    @pytest.mark.skipif(not shutil.which("rg"), reason="rg not installed")
+    def test_rg_live(self):
+        result = check_rg_present()
+        assert result["found"] is True
+
+
+# =============================================================================
+# check_broker_alive
+# =============================================================================
+
+
+class TestCheckBrokerAlive:
+    def test_no_repo_root_no_env(self, monkeypatch):
+        monkeypatch.delenv("AIPASS_HOME", raising=False)
+        monkeypatch.setattr(Path, "cwd", lambda: Path("/nonexistent"))
+        result = check_broker_alive(repo_root=None)
+        assert result["alive"] is False
+
+    def test_socket_missing(self, tmp_path):
+        ai_central = tmp_path / ".ai_central"
+        ai_central.mkdir()
+        result = check_broker_alive(repo_root=tmp_path)
+        assert result["alive"] is False
+        assert "missing" in result["detail"]
+
+    @pytest.mark.skipif(sys.platform != "linux", reason="AF_UNIX broker sockets are Linux-only")
+    def test_socket_connect_success(self, tmp_path):
+        ai_central = tmp_path / ".ai_central"
+        ai_central.mkdir()
+        sock_path = ai_central / "drone_broker.sock"
+
+        server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        server.bind(str(sock_path))
+        server.listen(1)
+        try:
+            result = check_broker_alive(repo_root=tmp_path)
+            assert result["alive"] is True
+            assert "connected" in result["detail"]
+        finally:
+            server.close()
+
+    @pytest.mark.skipif(sys.platform != "linux", reason="AF_UNIX broker sockets are Linux-only")
+    def test_socket_connect_refused(self, tmp_path):
+        ai_central = tmp_path / ".ai_central"
+        ai_central.mkdir()
+        sock_path = ai_central / "drone_broker.sock"
+        sock_path.touch()
+        result = check_broker_alive(repo_root=tmp_path)
+        assert result["alive"] is False
+        assert "connect failed" in result["detail"]
+
+    def test_repo_root_from_env(self, monkeypatch, tmp_path):
+        ai_central = tmp_path / ".ai_central"
+        ai_central.mkdir()
+        monkeypatch.setenv("AIPASS_HOME", str(tmp_path))
+        result = check_broker_alive(repo_root=None)
+        assert result["alive"] is False
+        assert "missing" in result["detail"]
+
+
+# =============================================================================
+# is_linux
+# =============================================================================
+
+
+class TestIsLinux:
+    def test_linux(self, monkeypatch):
+        monkeypatch.setattr("aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.sys.platform", "linux")
+        assert is_linux() is True
+
+    def test_darwin(self, monkeypatch):
+        monkeypatch.setattr("aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.sys.platform", "darwin")
+        assert is_linux() is False
+
+    def test_win32(self, monkeypatch):
+        monkeypatch.setattr("aipass.aipass.apps.handlers.sandbox_check.sandbox_checker.sys.platform", "win32")
+        assert is_linux() is False
+
+
+# =============================================================================
+# _check_sandbox (doctor integration)
+# =============================================================================
+
+
+@pytest.fixture
+def _stub_doctor_json():
+    """Stub json_handler inside doctor.py too."""
+    with patch("aipass.aipass.apps.modules.doctor.json_handler") as mock:
+        mock.log_operation = MagicMock()
+        yield mock
+
+
+class TestCheckSandboxDoctor:
+    def test_non_linux_one_info_line(self, monkeypatch):
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.is_linux",
+            lambda: False,
+        )
+        results = _check_sandbox()
+        assert len(results) == 1
+        assert "Linux-only" in results[0].detail
+        assert results[0].glyph == GLYPH_PASS
+
+    def test_flag_off_missing_prereq_is_warn(self, monkeypatch):
+        monkeypatch.delenv("AIPASS_SANDBOX_ENABLED", raising=False)
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.is_linux", lambda: True)
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_sandbox_flag", lambda: {"enabled": False, "raw_value": ""}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_node_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_srt_resolvable",
+            lambda: {"found": False, "path": None, "install_hint": "npm install -g ..."},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_rg_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_broker_alive",
+            lambda repo_root=None: {"alive": False, "detail": "not found"},
+        )
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.find_project_root", lambda p: None)
+
+        results = _check_sandbox()
+        for r in results:
+            assert r.glyph != GLYPH_FAIL, f"Flag OFF should not produce FAIL, got FAIL for {r.label}"
+
+    def test_flag_on_missing_prereq_is_fail(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.is_linux", lambda: True)
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_sandbox_flag", lambda: {"enabled": True, "raw_value": "1"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_node_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_srt_resolvable",
+            lambda: {"found": False, "path": None, "install_hint": "npm install -g ..."},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_rg_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_broker_alive",
+            lambda repo_root=None: {"alive": False, "detail": "not found"},
+        )
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.find_project_root", lambda p: None)
+
+        results = _check_sandbox()
+        fail_results = [r for r in results if r.glyph == GLYPH_FAIL]
+        assert len(fail_results) >= 4, f"Flag ON + missing prereqs should produce FAILs, got {len(fail_results)}"
+
+    def test_flag_on_all_present_is_pass(self, monkeypatch):
+        monkeypatch.setenv("AIPASS_SANDBOX_ENABLED", "1")
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.is_linux", lambda: True)
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_sandbox_flag", lambda: {"enabled": True, "raw_value": "1"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_present", lambda: {"found": True, "path": "/usr/bin/bwrap"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_functional",
+            lambda: {"ok": True, "detail": "trivial sandbox succeeded", "sysctl_value": None},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_node_present", lambda: {"found": True, "path": "/usr/bin/node"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_srt_resolvable",
+            lambda: {"found": True, "path": "/usr/lib/srt/index.js", "install_hint": ""},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_rg_present", lambda: {"found": True, "path": "/usr/bin/rg"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_broker_alive",
+            lambda repo_root=None: {"alive": True, "detail": "connected"},
+        )
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.find_project_root", lambda p: Path("/tmp/fake"))
+
+        results = _check_sandbox()
+        for r in results:
+            assert r.glyph == GLYPH_PASS, f"All present should be PASS, got {r.glyph} for {r.label}"
+
+    def test_bwrap_functional_skipped_when_not_present(self, monkeypatch):
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.is_linux", lambda: True)
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_sandbox_flag", lambda: {"enabled": False, "raw_value": ""}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_node_present", lambda: {"found": True, "path": "/usr/bin/node"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_srt_resolvable",
+            lambda: {"found": True, "path": "/x", "install_hint": ""},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_rg_present", lambda: {"found": True, "path": "/usr/bin/rg"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_broker_alive",
+            lambda repo_root=None: {"alive": True, "detail": "ok"},
+        )
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.find_project_root", lambda p: None)
+
+        results = _check_sandbox()
+        labels = [r.label for r in results]
+        assert "bwrap functional" not in labels
+
+    def test_bwrap_functional_included_when_present(self, monkeypatch):
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.is_linux", lambda: True)
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_sandbox_flag", lambda: {"enabled": False, "raw_value": ""}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_present", lambda: {"found": True, "path": "/usr/bin/bwrap"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_functional",
+            lambda: {"ok": True, "detail": "ok", "sysctl_value": None},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_node_present", lambda: {"found": True, "path": "/usr/bin/node"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_srt_resolvable",
+            lambda: {"found": True, "path": "/x", "install_hint": ""},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_rg_present", lambda: {"found": True, "path": "/usr/bin/rg"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_broker_alive",
+            lambda repo_root=None: {"alive": True, "detail": "ok"},
+        )
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.find_project_root", lambda p: None)
+
+        results = _check_sandbox()
+        labels = [r.label for r in results]
+        assert "bwrap functional" in labels
+
+    def test_sysctl_in_detail_on_functional_fail(self, monkeypatch):
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.is_linux", lambda: True)
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_sandbox_flag", lambda: {"enabled": True, "raw_value": "1"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_present", lambda: {"found": True, "path": "/usr/bin/bwrap"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_functional",
+            lambda: {"ok": False, "detail": "exit 1: denied", "sysctl_value": "1"},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_node_present", lambda: {"found": True, "path": "/usr/bin/node"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_srt_resolvable",
+            lambda: {"found": True, "path": "/x", "install_hint": ""},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_rg_present", lambda: {"found": True, "path": "/usr/bin/rg"}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_broker_alive",
+            lambda repo_root=None: {"alive": True, "detail": "ok"},
+        )
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.find_project_root", lambda p: None)
+
+        results = _check_sandbox()
+        func_result = [r for r in results if r.label == "bwrap functional"][0]
+        assert "apparmor_restrict_unprivileged_userns=1" in func_result.detail
+
+    def test_inert_suffix_when_flag_off(self, monkeypatch):
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.is_linux", lambda: True)
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_sandbox_flag", lambda: {"enabled": False, "raw_value": ""}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_bwrap_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_node_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_srt_resolvable",
+            lambda: {"found": False, "path": None, "install_hint": "npm install -g ..."},
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_rg_present", lambda: {"found": False, "path": None}
+        )
+        monkeypatch.setattr(
+            "aipass.aipass.apps.modules.doctor.check_broker_alive",
+            lambda repo_root=None: {"alive": False, "detail": "not found"},
+        )
+        monkeypatch.setattr("aipass.aipass.apps.modules.doctor.find_project_root", lambda p: None)
+
+        results = _check_sandbox()
+        missing_results = [r for r in results if r.glyph == GLYPH_WARN]
+        for r in missing_results:
+            assert "inert" in r.detail or r.label == "sandbox flag", (
+                f"Missing prereq {r.label} should show inert suffix"
+            )

src/aipass/aipass/tests/test_shared_bootstrap_safety.py

@@ -0,0 +1,58 @@
+# =================== AIPass ====================
+# Name: test_shared_bootstrap_safety.py
+# Description: Guard test — shared/ must stay stdlib-only (loads pre-drone)
+# Version: 1.0.0
+# Created: 2026-06-10
+# Modified: 2026-06-10
+# =============================================
+
+"""Guard test: importing aipass.aipass.shared must NOT pull in branch dependencies.
+
+The shared/ package is used by bootstrap.py during `aipass init` on fresh machines
+where drone/prax/trigger don't exist yet. If shared/ ever imports a branch
+dependency, init breaks. This test enforces the invariant via subprocess isolation.
+"""
+
+import subprocess
+import sys
+
+ALLOWED_PREFIXES = ("aipass.aipass.shared",)
+ALLOWED_EXACT = {"aipass", "aipass.aipass"}
+
+SCRIPT = """\
+import sys
+
+import aipass.aipass.shared.json_handler
+import aipass.aipass.shared.json_ops
+import aipass.aipass.shared.registry_discovery
+
+bad = []
+for name in sorted(sys.modules):
+    if not name.startswith("aipass"):
+        continue
+    if name in {allowed_exact}:
+        continue
+    if any(name.startswith(p) for p in {allowed_prefixes}):
+        continue
+    bad.append(name)
+
+if bad:
+    print("FAIL: branch dependencies loaded: " + ", ".join(bad))
+    sys.exit(1)
+print("OK")
+""".format(
+    allowed_exact=repr(ALLOWED_EXACT),
+    allowed_prefixes=repr(ALLOWED_PREFIXES),
+)
+
+
+class TestSharedBootstrapSafety:
+    def test_no_branch_deps_loaded(self):
+        """Importing all shared modules must not pull in any branch code."""
+        result = subprocess.run(
+            [sys.executable, "-c", SCRIPT],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        assert result.returncode == 0, f"shared/ pulled in branch dependencies:\n{result.stdout}\n{result.stderr}"

src/aipass/aipass/tests/test_structure_scan.py

@@ -20,7 +20,6 @@ from aipass.aipass.apps.handlers.structure_scan.structure_scanner import (
     check_root_artifacts,
     detect_pollution,
     find_project_root,
-    find_registry,
     scan_agents,
 )
 from aipass.aipass.apps.handlers.ui.progress import GLYPH_FAIL, GLYPH_WARN
@@ -357,16 +356,22 @@ class TestRegistryConsistency:
 
 class TestFindRegistry:
     def test_finds_registry(self, tmp_path: Path) -> None:
-        """Finds *_REGISTRY.json in project root."""
+        """Shared find_registry finds *_REGISTRY.json from start_path."""
+        from aipass.aipass.shared.registry_discovery import find_registry
+
         (tmp_path / "AIPASS_REGISTRY.json").write_text("{}", encoding="utf-8")
-        result = find_registry(tmp_path)
+        result = find_registry(start_path=tmp_path)
         assert result is not None
         assert result.name == "AIPASS_REGISTRY.json"
 
-    def test_returns_none(self, tmp_path: Path) -> None:
-        """Returns None when no registry file."""
-        result = find_registry(tmp_path)
-        assert result is None
+    def test_fallback_when_missing(self, tmp_path: Path) -> None:
+        """Shared find_registry returns fallback when no registry in isolated dir."""
+        from aipass.aipass.shared.registry_discovery import find_registry
+
+        isolated = tmp_path / "no_registry"
+        isolated.mkdir()
+        result = find_registry(start_path=isolated)
+        assert result.parent != isolated or not result.exists()
 
 
 # =============================================================================

src/aipass/api/.gitignore

@@ -12,3 +12,5 @@ build/
 *.log
 *.tmp
 *.swp
+test_devto_driver.py
+test_bluesky_driver.py

src/aipass/api/.seedgo/bypass.json

@@ -130,6 +130,11 @@
       "standard": "unused_function",
       "reason": "fetch_api_key() and fetch_validate_key() are module-level wrappers called from tests/test_critical_paths.py. The unused_function checker excludes test dirs from its search corpus. Encapsulation standard requires tests to go through modules — these functions serve that purpose (DPLAN-0155)."
     },
+    {
+      "file": "apps/modules/api_key.py",
+      "standard": "cli",
+      "reason": "get_secret_cmd() --list uses console.print() for slug names (identifiers, not secrets). Machine consumers use the in-process module aipass.api.apps.modules.secrets.get_secret; CLI never prints raw values (DPLAN-0211)."
+    },
     {
       "file": "tests/test_aggregation.py",
       "standard": "architecture",
@@ -224,6 +229,16 @@
       "file": "tests/test_integrations_manager.py",
       "standard": "architecture",
       "reason": "Test file — lives in tests/ by convention, not in the 3-layer app structure. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "tests/test_secrets.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention, not in the 3-layer app structure. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "tests/test_secrets.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler functions directly for unit testing. Tests need direct access to verify handler behavior."
     }
   ],
   "notes": {

src/aipass/api/README.md

@@ -5,8 +5,8 @@
 > Centralized external API gateway — authenticated service clients for all external APIs
 
 **Module:** `aipass.api` | **Role:** `api_gateway`
-**Seedgo:** 99% (35/36 at 100%) | **Tests:** 447 pass | **Functions:** 77 public (77 tested)
-**Last Updated:** 2026-05-16
+**Seedgo:** 100% (37/37 at 100%) | **Tests:** 504 pass | **Functions:** 82 public (82 tested)
+**Last Updated:** 2026-06-15
 
 ---
 
@@ -26,6 +26,7 @@ drone @api <command> [args]
 | `validate [provider]` | Validate API key (default: openrouter) |
 | `validate google` | Validate Google OAuth2 credentials |
 | `reauth google` | Re-authenticate Google OAuth2 |
+| `get-secret <provider/slug> [--out FILE] [--json] [--list]` | Secret access (masked summary; --out writes to file) |
 | `list-providers` | List available API providers |
 | `init` | Initialize .env template at ~/.secrets/aipass/ |
 | `test` | Test OpenRouter connection status |
@@ -48,8 +49,9 @@ drone @api <command> [args]
 api/
 ├── apps/
 │   ├── api.py                         # Entry point — module discovery, command routing
-│   ├── modules/                       # Orchestration layer (7 modules)
+│   ├── modules/                       # Orchestration layer (8 modules)
 │   │   ├── api_key.py                 # Key retrieval, validation, provider listing
+│   │   ├── secrets.py                 # Cross-branch secrets door (in-process API)
 │   │   ├── openrouter_client.py       # OpenRouter client — calls, models, status
 │   │   ├── google_client.py           # Google API services (Drive, Calendar, etc.)
 │   │   ├── usage_tracker.py           # Usage metrics — track, stats, cleanup
@@ -57,7 +59,7 @@ api/
 │   │   ├── integrations_manager.py    # Contract dispatch — integrations list/call
 │   │   └── registry.py               # Driver auto-discovery (load_drivers)
 │   ├── handlers/                      # Business logic (7 packages, 15 files)
-│   │   ├── auth/env.py, keys.py
+│   │   ├── auth/env.py, keys.py, secrets.py
 │   │   ├── config/provider.py
 │   │   ├── google/auth.py, service_factory.py, retry.py
 │   │   ├── integrations/list.py, call.py
@@ -66,7 +68,7 @@ api/
 │   │   └── usage/aggregation.py, cleanup.py, tracking.py
 │   └── integrations/                  # Private driver space (gitignored)
 │       └── {project}/driver.py
-└── tests/                             # 447 tests across 27 files
+└── tests/                             # 504 tests across 28 files
 ```
 
 Three-tier: entry point routes to modules (orchestration), modules delegate to handlers (business logic). Modules auto-discovered from `apps/modules/*.py` via `handle_command()`.
@@ -85,6 +87,12 @@ service = get_drive_service(thread_safe=True)   # For concurrent workers
 
 from aipass.api.apps.modules.google_client import get_google_service
 service = get_google_service("calendar", "v3")
+
+from aipass.api.apps.modules.secrets import get_secret, list_secrets
+token = get_secret("telegram", "bot")               # Returns bot_token string
+config = get_secret("telegram", "bot", as_json=True) # Returns full dict
+slugs = list_secrets("telegram")                     # Returns ["bot", "webhook", ...]
+# CLI never prints raw values — use the Python API above for programmatic access
 ```
 
 ---

src/aipass/api/apps/api.py

@@ -156,6 +156,7 @@ def print_help():
     table.add_column("Description", style="white")
 
     table.add_row("get-key", "Retrieve API key for provider")
+    table.add_row("get-secret", "Read secret from provider store")
     table.add_row("validate", "Validate API credentials and connection")
     table.add_row("validate google", "Validate Google OAuth2 credentials")
     table.add_row("reauth google", "Re-authenticate Google OAuth2")
@@ -205,7 +206,8 @@ def print_help():
     console.print()
 
     console.print(
-        "[dim]Commands: get-key, validate, test, models, status, call, list-providers, init, track, stats, session, caller-usage, cleanup[/dim]"
+        "[dim]Commands: get-key, get-secret, validate, test, models, status, call,"
+        " list-providers, init, track, stats, session, caller-usage, cleanup[/dim]"
     )
     console.print()
 

src/aipass/api/apps/handlers/auth/secrets.py

@@ -0,0 +1,168 @@
+# =================== AIPass ====================
+# Name: secrets.py
+# Description: Secrets Store Handler
+# Version: 1.0.0
+# Created: 2026-06-15
+# Modified: 2026-06-15
+# =============================================
+
+"""
+Secrets Store Handler
+
+Reads structured secrets from ~/.secrets/aipass/<provider>/<slug>.
+Supports JSON config files and raw secret files.
+
+Functions:
+    get_secret() - Read a secret by provider/slug
+    list_secrets() - List available slugs for a provider
+"""
+
+import json
+from pathlib import Path
+from typing import Any, List, Optional
+
+from aipass.prax import logger
+from aipass.api.apps.handlers.json import json_handler
+
+SECRETS_BASE = Path.home() / ".secrets" / "aipass"
+
+# Keys to search for when returning a plain (non-JSON) secret value
+_TOKEN_KEYS = ("bot_token", "api_key", "token", "secret", "password", "key")
+
+
+# ==============================================
+# SECRET RETRIEVAL
+# ==============================================
+
+
+def get_secret(provider: str, slug: str, as_json: bool = False) -> Optional[Any]:
+    """
+    Get secret value from provider store.
+
+    Source: ~/.secrets/aipass/<provider>/<slug>.json or <slug>
+
+    Args:
+        provider: Provider directory name (e.g., 'telegram', 'discord')
+        slug: Secret file name (without .json extension)
+        as_json: If True, return full parsed dict; otherwise extract primary token
+
+    Returns:
+        Secret value (str or dict) or None if not found
+
+    Example:
+        >>> token = get_secret('telegram', 'bot')
+        >>> if token:
+        ...     print(f"Got token: {token[:10]}...")
+    """
+    provider_dir = SECRETS_BASE / provider
+
+    if not provider_dir.exists() or not provider_dir.is_dir():
+        logger.warning(f"Provider directory not found: {provider_dir}")
+        return None
+
+    # Try JSON file first
+    json_path = provider_dir / f"{slug}.json"
+    if json_path.exists():
+        result = _read_json_secret(json_path, as_json)
+        if result is not None:
+            json_handler.log_operation("secret_retrieved", {"provider": provider, "slug": slug, "format": "json"})
+            return result
+
+    # Fall back to raw file
+    raw_path = provider_dir / slug
+    if raw_path.exists():
+        result = _read_raw_secret(raw_path)
+        if result is not None:
+            json_handler.log_operation("secret_retrieved", {"provider": provider, "slug": slug, "format": "raw"})
+            return result
+
+    logger.warning(f"Secret not found: {provider}/{slug}")
+    return None
+
+
+def list_secrets(provider: str) -> List[str]:
+    """
+    List available secret slugs for a provider.
+
+    Args:
+        provider: Provider directory name
+
+    Returns:
+        Sorted list of slug names (JSON extensions stripped)
+
+    Example:
+        >>> slugs = list_secrets('telegram')
+        >>> print(slugs)
+        ['bot', 'webhook']
+    """
+    provider_dir = SECRETS_BASE / provider
+
+    if not provider_dir.exists() or not provider_dir.is_dir():
+        return []
+
+    slugs = []
+    for entry in provider_dir.iterdir():
+        if entry.name.startswith(".") or entry.name == "__pycache__":
+            continue
+        if not entry.is_file():
+            continue
+
+        name = entry.name
+        if name.endswith(".json"):
+            name = name[:-5]
+        slugs.append(name)
+
+    return sorted(slugs)
+
+
+# ==============================================
+# PRIVATE HELPERS
+# ==============================================
+
+
+def _read_json_secret(path: Path, as_json: bool) -> Optional[Any]:
+    """
+    Read and parse a JSON secret file.
+
+    Args:
+        path: Path to JSON file
+        as_json: If True, return full dict; otherwise extract primary token
+
+    Returns:
+        Parsed data or extracted token, or None on error
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning(f"Error reading secret file {path}: {e}")
+        return None
+
+    if as_json:
+        return data
+
+    if isinstance(data, dict):
+        for key in _TOKEN_KEYS:
+            if key in data:
+                return str(data[key])
+        return json.dumps(data)
+
+    return str(data)
+
+
+def _read_raw_secret(path: Path) -> Optional[str]:
+    """
+    Read a raw (non-JSON) secret file.
+
+    Args:
+        path: Path to raw secret file
+
+    Returns:
+        Stripped file contents or None on error
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read().strip()
+    except OSError as e:
+        logger.warning(f"Error reading secret file {path}: {e}")
+        return None