Merge pull request #696 from AIOSAI/dev

Post-v2.7.0 fixes: #692 legacy builder-class migration + birth-cert template, #694 order-dependent test pollution. Both verified live: Vera Studio dry-run plans exactly the 2 passport migrations (zero writes), original repro pair passes, prax+skills+spawn 1576 tests green, skills_json litter eliminated.
chore(release): bump 2.7.0 -> 2.7.1 — supply-chain hardening (DPLAN-0243: commit signing, hash-pinned CI tooling, release provenance attestation), TG streaming v2 polish, rate_tracker burst-evasion fix, CI green pass
2026-07-15 13:37:45 -07:00 · 2026-07-15 13:24:41 -07:00 · 2026-07-15 13:19:29 -07:00 · 2026-07-15 12:36:19 -07:00 · 2026-07-15 12:21:22 -07:00 · 2026-07-15 11:14:05 -07:00
939 changed files with 119062 additions and 7213 deletions
@@ -1,8 +1,11 @@
 *
-!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
+!project_AGENTS.md
 !project_hooks.json
 #Do not add other exceptions here without careful consideration. Developer permissions0ns needed.
@@ -15,6 +15,16 @@ 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 `.trinity/local.json` (todos[]) and `DASHBOARD.local.json`.
@@ -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
@@ -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.
@@ -1,121 +0,0 @@
-# AIPass — Global Prompt
-<!-- .aipass/aipass_global_prompt.md — injected via hook, cadence-throttled. Size cap: keep under 8,000 characters — the harness truncates hook output near 10k and the tail silently never arrives. Detail belongs in `drone @agent --help`, not here. Format: .aipass/PROMPT_STYLE.md -->
-
-Persistent Agent Workspace. 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`.
-
-# Drone — the router
-
-`drone` reaches every agent and service. Installed binary, always on PATH — run directly, never as a python module.
-
-```
-drone @agent <command> [args]   # route a command to any agent
-drone @agent --help             # full curated reference for that agent
-drone @agent                    # bare → introspection: the agent's live self-map
-drone systems                   # list all agents
-drone --help                    # drone itself
-```
-
-One reflex above all: before using an agent's services, run `drone @agent --help`. This prompt says what exists — `--help` says how. Don't guess syntax; fetch it. Doubly so right after a compaction.
-
-# Git — drone only, devpulse only
-
- - All raw `git` and `gh` commands are blocked — do not use them. `drone @git` is the only git interface.
- - Write ops (commit, push, merge, checkout) are devpulse-only. Agents build and test; devpulse reviews and commits.
- - Read-only awareness for everyone: `drone @git status / diff / log`.
- - Local files = source of truth.
-
-# Finding your way
-
-You can't carry everything; you can find anything. This prompt plants breadcrumbs — enough to know a thing exists and where to look, not the full answer. Unfamiliar term? A command or README resolves it. Cheapest, highest-signal sources first:
-
- - Introspection — bare `drone @agent`. The agent's self-map: modules, commands, where to go next.
- - README — the agent's `README.md`. Best quick overview of its domain and shape.
- - `drone @agent --help` — the full reference. Source of truth for usage.
- - Code — `apps/modules/`, `apps/handlers/`. Ground truth when needed. Rarely the first move.
-
-# 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.
-
-# 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.
-
- - DPLAN — design 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.
- - RPLAN — research plan. Investigation runs — gather findings before deciding.
- - More types exist and new ones register over time. Named a type you don't know? `drone @flow templates` lists them all, live.
-
-# Sub-agent usage
-
-Sub-agents are your context-splitting tool: disposable workers, extensions of you. Your context is precious; theirs is not.
-
- - 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 memories are your continuity across sessions. Save proactively: after milestones, decisions, learnings, 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
-
- - 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 a test or command confirms it.
- - 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.
@@ -3,6 +3,16 @@
  "hooks_enabled": true,

  "UserPromptSubmit": {
+    "presence_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.presence_gate.handle",
+      "matcher": ""
+    },
+    "persistent_alert": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.prompt.persistent_alert.handle",
+      "matcher": ""
+    },
    "identity_injector": {
      "enabled": true,
      "handler": "aipass.hooks.apps.handlers.prompt.identity.handle",
@@ -18,9 +28,14 @@
      "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": {
@@ -28,6 +43,11 @@
      "handler": "aipass.hooks.apps.handlers.lifecycle.auto_process.handle",
      "matcher": "",
      "timeout": 120
+    },
+    "user_message_relay": {
+      "enabled": true,
+      "handler": "aipass.skills.lib.telegram.apps.handlers.user_message_relay.handle",
+      "matcher": ""
    }
  },

@@ -52,6 +72,11 @@
      "handler": "aipass.hooks.apps.handlers.security.rm_gate.handle",
      "matcher": "Bash"
    },
+    "registry_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.registry_gate.handle",
+      "matcher": "Bash|Edit|MultiEdit|Write|NotebookEdit"
+    },
    "engine_test_sound": {
      "enabled": false,
      "command": "python3 $AIPASS_HOME/.claude/hooks/engine_test_sound.py",
@@ -87,6 +112,17 @@
      "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
+    },
+    "presence_release": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.presence_gate.handle_stop",
+      "matcher": ""
    }
  },

@@ -117,5 +153,13 @@
      "matcher": "",
      "timeout": 120
    }
+  },
+
+  "SessionStart": {
+    "cadence_reset": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.session_start.handle",
+      "matcher": ""
+    }
  }
 }
@@ -0,0 +1,15 @@
+# {name}
+
+Agent workspace powered by AIPass.
+
+# Startup protocol
+
+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`
+
+Use drone commands for all operations. Never raw git, gh, or file access when drone provides it.
+
+# Memories
+
+Update `.trinity/` at natural breakpoints, after milestones, and on `/memo`.
@@ -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
@@ -1,5 +1,5 @@
 {
-  "_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.",
+  "_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. NOTE: git_gate is enabled by default — it enforces git via drone to prevent state conflicts. To disable for your project, set git_gate.enabled to false below (this won't break other hooks).",
  "hooks_enabled": true,

  "UserPromptSubmit": {
@@ -18,9 +18,14 @@
      "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": ""
    }
  },
@@ -87,6 +92,14 @@
    }
  },

+  "SessionStart": {
+    "cadence_reset": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.lifecycle.session_start.handle",
+      "matcher": ""
+    }
+  },
+
  "PreCompact": {
    "pre_compact": {
      "enabled": true,
@@ -0,0 +1,27 @@
+# AIPass — Kernel
+
+<!-- .aipass/tier0_kernel.md — Tier 0, injected every 5 turns (cadence period 5) + on every fresh context (new chat / clear / after compact). 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.
+
+`aipass` is the one exception — the user's own front-door CLI and concierge (onboarding, `doctor`, OS/system help). Run `aipass` / `aipass --help` directly, **never `drone @aipass`** (drone can't resolve it). Serves humans, not agents.
+
+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.
@@ -0,0 +1,115 @@
+# AIPass — Navigation map
+
+<!-- Tier 1 — injected on cadence 5, at session start, and post-compaction. Kernel = tier0_kernel.md, every turn. Cap: ~8,000 chars per fire (hook truncates near 10k). Format: 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. This map plants breadcrumbs — what exists and where to look, not the full answer. Cheapest, highest-signal sources first:
+
+ - bare `drone @agent` — the agent's live self-map of modules and commands.
+ - `drone @agent --help` — the full reference, source of truth for usage.
+ - the agent's `README.md` — quick overview of its domain.
+
+# 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` (personal, don't touch) · project `.claude/settings.json` (ships with clone) · local override `settings.local.json`.
+
+# The framework
+
+Every branch is built the same: `src/aipass/<name>` · mail `@<name>`.
+
+```
+src/aipass/<name>/
+├── .trinity/           # identity & memory
+├── .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. 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's front-door concierge, its OWN CLI: run `aipass` directly, never `drone @aipass` (drone can't resolve it). Onboarding (`init`/`install`), `doctor` health, help chat, OS/system questions. Serves humans, not agents — 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. See the Plans section.
+ - @seedgo — code standards and audits. `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, runaway-log detection. Logs are the first diagnostic tool.
+ - @memory — long-term memory. Archives overflowing `.trinity/` files into searchable vectors; `search` recalls past sessions.
+ - @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, persistent alerts, 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 (e.g. the Telegram skill).
+ - @daemon — task scheduler. Each branch owns its `.daemon/schedule.json`; the daemon discovers and fires.
+ - @commons — the social space. Branches post, comment, vote.
+ - @backup — local-first backups. Snapshots, versioning, restore for any directory; optional Google Drive sync. `.backup/` is shared — @memory rollover and @flow archives write there too.
+
+# 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 @trigger medic mute @<self>                  # BEFORE build/edit work — auto-expires 24h
+drone @git status / diff / log                     # read-only git awareness
+drone @memory search "query"                       # recall archived context
+```
+
+# Talking to other agents
+
+Citizens dispatch each other directly — allowed and expected, no permission needed. Pick by one question: does the recipient need to ACT?
+
+ - Need an answer, input, or work from them → `dispatch` (send + wake). A sleeping agent never reads plain email — a question sent as `email` stalls unread.
+ - FYI only (status, steering an agent already awake) → `email` (no wake).
+ - Replies never wake — wake-back does: when an agent you dispatched completes, YOU are woken. Team mission: the lead dispatches each phase BEFORE sleeping; the worker replies normally; wake-back returns the lead to verify and hand off the next phase.
+ - Exception — managers (`citizen_class: manager`, e.g. @devpulse) are never dispatched — the wake is blocked. `email` them; the mail lands and they see it live.
+
+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 register over time — `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/plans, 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: opus for build/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. `drone @memory search "query"` recalls it — search before assuming you're cold.
+ - Entry caps are hook-enforced (over-limit edit = rejected whole). The live cap is in each file's `*_meta` line — read it before writing, draft to ~80%; if rejected, rewrite hard in one pass.
+
+# House rules
+
+ - Cross-platform, no hardcoded paths. Public repo — `pathlib`, never `/home/...`.
+ - No bare imports — always `from aipass.<agent>.apps...`.
+ - State lives in `.trinity/` and dashboards, never in prompts. Prompts are signposts; memories record; registries catalog.
@@ -1,39 +1,28 @@
 # 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's own directory
-.backup_system/
-
-# Version control
+.backup/
 .git/
 .svn/
 .hg/
-
-# Python
 __pycache__/
+.pytest_cache/
 *.pyc
 *.pyo
 *.egg-info/
 .venv/
 venv/
 .tox/
-
-# Node
 node_modules/
-
-# IDE
 .vscode/
 .idea/
 *.swp
 *.swo
-
-# OS
 .DS_Store
 Thumbs.db
-
-# Build artifacts
 build/
 dist/
-
-# Logs
 *.log
+.ruff_cache/
+.coverage
@@ -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
@@ -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.
@@ -14,16 +14,37 @@ 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. Update todos[] with current in-flight items. 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.

+### 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** sessions/key_learnings/observations — rollover archives the oldest *by number* to @memory automatically. **Todos are the exception** — rollover never touches them, so you prune done ones by hand (see Reconcile below).
+
+### Reconcile todos — verify against reality, don't trust the label
+
+Stored status drifts: a todo finished in a past session often never gets closed. Before writing the session entry, **audit every open todo against the actual system** — check the real state, not the stored `status`:
+
+- Does the file/dir still exist (or is it gone)? Is the code path in or out? Does the README/doc actually say what the todo claims? Does the audit pass?
+- **Close what's verifiably done** → note it in the session entry, then **DELETE the todo from the array**. Rollover never trims todos (they're operational — only sessions/key_learnings/observations roll), so done items left as `status: done` pile up and go stale across chats. Fail honestly — remove only on evidence, never just to tidy the list.
+- **Re-scope what's partially done** → record which sub-items landed, keep the rest open.
+- **Leave deferred / pending-decision todos open** — but confirm they're still real.
+
+Quick checks beat assumptions: `ls`/`find` for files, `git ls-files`/`grep` for code/docs, `drone @seedgo audit` for standards. This step is the whole point of "close whats done."
+
 ## 2. Active Plans

 - Check any DPLANs or FPLANs referenced in this session
 - Update their execution logs, status, decision logs with current state
 - If a plan was completed, note it (but don't close — the user does that)

-## 3. Git State
+## 3. Git State (Devpulse only)

 - Run `git status` — report uncommitted changes
 - If there's a logical commit waiting, suggest it (don't commit without asking)
@@ -45,6 +66,7 @@ List everything updated. Format:
 ```
 Prep complete:
 - local.json: [what was added]
+- Todos: [reconciled vs reality — N done & removed, M re-scoped, K still open]
 - observations.json: [updated / skipped]
 - Plans: [which ones updated]
 - Git: [branch, uncommitted count, suggestion]
@@ -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"},
@@ -14,7 +14,7 @@ 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, 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/local.json`** — YOUR MEMORY. Add a session entry for significant work; add key_learnings for facts you'd need next time. **Todos: add what you parked, and DELETE every todo you finished this session** — the proof goes in the session entry, not the todo. Rollover never trims todos (they're operational), so done ones you leave behind resurface as "open" next load and you waste time re-confirming them. (Sessions/key_learnings DO auto-roll by number — don't hand-trim those.)
 - **`.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.

 ## If Relevant
@@ -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 = {}

@@ -18,9 +18,15 @@ 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 a session entry to `sessions` if significant work was done; add `key_learnings` for facts you'd need next time. **Todos: add what you parked, and DELETE every todo you finished this session** — the proof goes in the session entry, not the todo. Rollover never trims todos (they're operational), so done ones you leave behind resurface as "open" next load and you waste time re-confirming them.
 - **.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** sessions/key_learnings/observations — rollover archives the oldest *by number* to @memory automatically. **Todos are the exception** — rollover never touches them, so you prune done ones by hand (delete finished todos, see above).
+
 ### 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.
@@ -14,10 +14,14 @@ 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** sessions/key_learnings/observations — rollover archives the oldest *by number* automatically. **Todos are the exception** — rollover never touches them, so you prune done ones by hand (see Reconcile).
+
+**Reconcile todos — verify against reality, don't trust the label.** Stored status drifts (a todo finished a past session often never got closed). Audit every **open** todo against the actual system: file/dir still there? code path in or out? README says what it claims? audit passes? **Close what's verifiably done** → note it in the session entry, then **DELETE the todo from the array** (rollover never trims todos — they're operational — so done items left as `status: done` pile up and go stale across chats), **re-scope** partials, **leave** deferred/pending-decision ones open. Fail honestly — remove only on evidence, never to tidy the list. Use `ls`/`find`/`git ls-files`/`grep`/`drone @seedgo audit`, not assumptions.
+
 ## 2. Active Plans

 - Check any DPLANs or FPLANs referenced in this session
@@ -46,6 +50,7 @@ List everything updated. Format:
 ```
 Prep complete:
 - local.json: [what was added]
+- Todos: [reconciled vs reality — N done & removed, M re-scoped, K still open]
 - observations.json: [updated / skipped]
 - Plans: [which ones updated]
 - Git: [branch, uncommitted count, suggestion]
@@ -12,6 +12,31 @@ updates:
      prefix-development: "deps"
      include: "scope"

+  # Hash-pinned CI tool installs (ruff/build/pytest/pip-audit/pip). Pinning is
+  # what Scorecard's Pinned-Dependencies wants, but a frozen pin rots: these
+  # locks are what security.yml's pip-audit scans, so a new advisory against a
+  # pinned dep reds the job until the pin moves. This entry is what keeps that
+  # window short. Dependabot reads the `pip-compile ...` command out of each
+  # .txt header and regenerates the lock (hashes included) from the .in.
+  # Separate from the "/" pip entry above, which tracks pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/.github/requirements"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "ci"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    # packaging/pygments are shared across build.txt, e2e.txt and audit.txt.
+    # Ungrouped, one bump fans out into several PRs that each rewrite a subset
+    # of the locks and conflict with each other. One PR per week moves them all.
+    groups:
+      ci-tooling:
+        patterns:
+          - "*"
+
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
@@ -22,3 +47,11 @@ updates:
    commit-message:
      prefix: "ci"
      include: "scope"
+    # codeql-action is a monorepo (init/analyze/upload-sarif share one release).
+    # Bumping them in separate PRs leaves mismatched versions in security.yml and
+    # CodeQL hard-fails "init and analyze must be the same version". Group them so
+    # every codeql-action bump lands as a single PR that moves all paths together.
+    groups:
+      codeql-action:
+        patterns:
+          - "github/codeql-action*"
@@ -0,0 +1,16 @@
+# pip-audit for the security.yml `dependency-scan` job, hash-pinned (Scorecard:
+# Pinned-Dependencies).
+#
+# Target env: ubuntu-latest, Python 3.13. pip-audit's own dependency tree is
+# resolved and hashed here; the project itself is still installed unpinned via
+# `pip install -e .` and scanned with `pip-audit --skip-editable`, so pinning
+# this file does not narrow what the audit covers.
+#
+# TRADE-OFF: pip-audit scans the whole environment, including its own deps. They
+# used to float to latest on every run (self-healing); pinned, a new advisory
+# against one of them reds this job until the pin moves. Dependabot's `pip`
+# entry for /.github/requirements is what keeps that window short.
+#
+# Regenerate:
+#   pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=audit.txt audit.in
+pip-audit==2.10.1
@@ -0,0 +1,330 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=audit.txt audit.in
+#
+boolean-py==5.0 \
+    --hash=sha256:60cbc4bad079753721d32649545505362c754e121570ada4658b852a3a318d95 \
+    --hash=sha256:ef28a70bd43115208441b53a045d1549e2f0ec6e3d08a9d142cbc41c1938e8d9
+    # via license-expression
+cachecontrol[filecache]==0.14.4 \
+    --hash=sha256:b7ac014ff72ee199b5f8af1de29d60239954f223e948196fa3d84adaffc71d2b \
+    --hash=sha256:e6220afafa4c22a47dd0badb319f84475d79108100d04e26e8542ef7d3ab05a1
+    # via
+    #   cachecontrol
+    #   pip-audit
+certifi==2026.6.17 \
+    --hash=sha256:024c88eeec92ca068db80f02b8b07c9cef7b9fe261d1d535abfd5abd6f6af432 \
+    --hash=sha256:2227dcbaafe0d2f59279d1762ddddc37783ed4354594f194ffc31d20f41fc3db
+    # via requests
+charset-normalizer==3.4.9 \
+    --hash=sha256:0327fcd59a935777d83410750c50600ee9571af2846f71ce40f25b13da1ef380 \
+    --hash=sha256:03d07803992c6c7bbc976327f34b18b6160327fc81cb82c9d504720ac0be3b62 \
+    --hash=sha256:04ce310cb89c15df659582aee80a0603788732a5e017d5bd5c81158106ce249c \
+    --hash=sha256:0d861473f743244d349b50f850d10eb87aeb22bbdcc8e64f79273c94af5a8226 \
+    --hash=sha256:0e94703ec9684807f20cfb5eed95c70f67f2a8f21ad620146d7b5a13677b93e5 \
+    --hash=sha256:0fa1aec2d32bcc03c8fa0f6f1712caad1adc38509f31142112e5c9daf5b9c833 \
+    --hash=sha256:16b65ea0f2465b6fb52aa22de5eca612aa964ddfec00a912e26f4656cbef890b \
+    --hash=sha256:16d10d789dd9bcca1173c95af82c58433122564b7bc39385124be735a35cbe99 \
+    --hash=sha256:19ac87f93086ce37b86e098888555c4b4bc48102279bae3350098c0ed664b501 \
+    --hash=sha256:1d22856ffbe153a602df38e4a5464f0b748a54002e0d69ac6d2ad0a197cc99ec \
+    --hash=sha256:21e764fd1e70b6a3e205a0e46f3051701f98a8cb3fad66eeb80e48bb502f8698 \
+    --hash=sha256:231ddcbb35e2ff8973e1365db41fe0572662893b99a05deb183b68ad4c0c8bd4 \
+    --hash=sha256:253a4a220747e8b5faf57ec320c4f5efb0cef05f647420bf267143ec15dba10a \
+    --hash=sha256:280081916dc341820640489a66e4696049401ef1cf6dd672f672e70ad915aca3 \
+    --hash=sha256:2a441ea71902098ffe78c5abe6c494f44160b4af614ed16c3d9a3b1d17fd8ee2 \
+    --hash=sha256:304b13570067b2547562e308af560b3963857b1fa90bd6afd978130130fe2d6a \
+    --hash=sha256:32286a2c8d167e897177b673176c1e3e00d4057caf5d2b64eef9a3666b03018e \
+    --hash=sha256:33bdcc2a32c0a0e861f60841a512c8acc658c87c2ac59d89e3a46dacf7d866e4 \
+    --hash=sha256:375b83ed0aecfce76c16d198fbc21f3b11b337d68662bea0a995046682a11419 \
+    --hash=sha256:3c09a49d6cde137258beb3d551994a2927fd35ad5cf96aed573f61bbd67c5f84 \
+    --hash=sha256:3d92613ec25e43b05f042302531ec0f00b8445190e43325880cbd6ab7c2581da \
+    --hash=sha256:40a126142a56b2dfc0aacbad1de8310cbf60da7656db0e6b16eebd48e3e93519 \
+    --hash=sha256:416c229f77e5ea25b3dfd4b582f8d73d7e43c22320302b9ab128a2d3a0b38efe \
+    --hash=sha256:432786d3561e69aeeae6c7e8648964ce0ad05736120135601f87ac26b9c83381 \
+    --hash=sha256:43b9e366a31fdd1c87d0eb08f579b4a82b723ea54338f040d6b4e518a026ea29 \
+    --hash=sha256:440eede837960000d74978f0eba527be106b5b9aee0daf779d395276ed0b0614 \
+    --hash=sha256:45b0cc4e3556cd875e09102988d1ab8356c998b596c9fced84547c8138b487a0 \
+    --hash=sha256:476743fe6dfe14a2da12e3ac79125dc84a3b2cf8094369a47a1529b0cd8549fe \
+    --hash=sha256:4773092f8019072343a7447203308b176e10199920eb02d6195e81bbb3274c29 \
+    --hash=sha256:4b3dac63058cc36820b0dd072f89898604e2d39686fe05321729d00d8ac185a0 \
+    --hash=sha256:4d1c96a7a18b9690a4d46df09e3e3382406ae3213727cd1019ebade1c4a81917 \
+    --hash=sha256:51307f5c71007673a2bf8232ad973483d281e74cb99c8c5a990af1eefa6277d9 \
+    --hash=sha256:51447e9aa2684679af07ca5021c3db526e0284347ebf4ffcec1154c3350cfe32 \
+    --hash=sha256:58150c9f9b9a552505912d182ccdf26f6396fb6094816ceebcbb20eecabaed94 \
+    --hash=sha256:5b10cd92fc5c498b35a8635df6d5a100207f88b63a4dc1de7ef9a548e1e2cd63 \
+    --hash=sha256:5e226f6218febc71f6c1fc2fafb91c226f75bdc1d8fb12d66823716e891608fd \
+    --hash=sha256:609b3ba8fcc0fb5ab7af00719d0fb6ad0cb518e48e7712d12fd68f1327951198 \
+    --hash=sha256:60f44ade2cf573dad7a277e6f8ca9a51a21dda572b13bd7d8539bb3cd5dbedde \
+    --hash=sha256:611057cc5d5c0afc743ba8be6bd828c17e0aaa8643f9d0a9b9bb7dea80eb8012 \
+    --hash=sha256:6366a16e1a25018694d6a5d784d09b046edc9eac40ea2b54065c3052672516a1 \
+    --hash=sha256:65a7ff3f705e57d392f7261b6d0550fe137c3019477431f1c355e0db0a7d3e15 \
+    --hash=sha256:673611bbd43f0810bec0b0f028ddeaaa501190339cac411f347ac76917c3ae7b \
+    --hash=sha256:67830fc78e67501f47bb950471b2dcb9b35b140084429318e862895a8e89c993 \
+    --hash=sha256:68ce9f4d6b26d5ccbf7fd4459bf75f74a0a146677ebba80597df60cbdb20e6f4 \
+    --hash=sha256:68e5f26a1ad57ded6d1cfb85331d1c1a195314756471d97758c48498bb4dcdf5 \
+    --hash=sha256:69b157c5d3292bcd443faca052f3096f637f1e074b98212a933c074ae23dc3b8 \
+    --hash=sha256:75286256590a6320cf106a0d28970d3560aad9ee09aa7b34fb40524792436d35 \
+    --hash=sha256:78841cccf1af7b40f6f716338d50c0902dbe88d9f800b3c973b7a9a0a693a642 \
+    --hash=sha256:78fa18e436a1a0e58dbd7e02fc4473f3f32cceb12df9dfca542d075961c307d2 \
+    --hash=sha256:79580094b00d1789d1f93ea55bc43cb2f611910c72235b7657f3482ddcc1b22d \
+    --hash=sha256:7b86a2b16095d250c6f58b3d9b2eee6f4147754344f3dab0922f7c9bf7d226c9 \
+    --hash=sha256:83aed2c10721ddd90f68140685391b50811a880af20654c59af6b6c66c40513c \
+    --hash=sha256:84fd18bcc17526fc2b3c1af7d2b9217d32c9c04448c16ec693b9b4f1985c3d33 \
+    --hash=sha256:871ff67ea1aad4dfd91736464934d56b32dac49f9fbe16cddba36198a7b3a0db \
+    --hash=sha256:898f0e9068ca27d37f8e83a5b962821df851532e6c4a7d615c1c033f9da6eedf \
+    --hash=sha256:8a79d9f4d8001473a30c163556b3c3bfebec837495a412dde78b51672f6134f9 \
+    --hash=sha256:8c041122946b7ba21bb32c45b1aa57b1be35527690aeb3c5c234521085632eee \
+    --hash=sha256:90c44bc373b7687f6948b693cceaea1348ae0975d7474746559494468e3c1d84 \
+    --hash=sha256:9104ed0bd76a429d46f9ec0dbc9b08ad1d2dcdf2b00a5a0daa1c145329b35b44 \
+    --hash=sha256:920079c3f7456fa213e0829ed2073aaa727fd39d889ead5b4f35d0de5460d04f \
+    --hash=sha256:93d59d504b230e83c7a843251681959a0b6a9cd76f6e146ce1b8a80eb8739af9 \
+    --hash=sha256:9b2aff1c7b3884512b9512c3eaadd9bab39fb45042ffaaa1dd08ff2b9f8109d9 \
+    --hash=sha256:9b8e0f3107e2200b76f6054de99016eac3ee6762713587b36baaa7e4bd2ae177 \
+    --hash=sha256:9bb41182d93ea91f60b4bc8fbf4c820c69ef8a12ab2d917f3f1834f1acad07e8 \
+    --hash=sha256:9cdef90ae47919cae358d8ab15797a800ed41da7aba5d72419fb510729e2ed4b \
+    --hash=sha256:a1786910334ed46ab1dd73222f2cd1e05c2c3bb39f6dddb4f8b36fc382058a39 \
+    --hash=sha256:a4cfde78a9f2880208d16a93b795726a3017d5977e08d1e162a7a31322479c41 \
+    --hash=sha256:a4fbdde9dd4a9ce5fd52c2b3a347bb50cc89483ef783f1cb00d408c13f7a96c0 \
+    --hash=sha256:aa99adc8f081b475a12843953db36831eaf83ec33eb46a90629ca6a5de45a616 \
+    --hash=sha256:ac351b3b8014eead140e77e9717e2992c6bbe30b63bc3422422eb84865412e3d \
+    --hash=sha256:ad41ba96094304aa090f5a30cb6e4fb3b3f1c264c523394b4c39bbacc4dc92ba \
+    --hash=sha256:b5314963fce9b0b12743891de876e724997864ee22aa496f903f426c7e2fa5b2 \
+    --hash=sha256:bcf74c1df76758a395bf0af608c04c82257523f55c9868b334f06270d0f2112b \
+    --hash=sha256:bd47ba7fc3ca94896759ea0109775132d3e7ab921fbf54038e1bab2e46c313c9 \
+    --hash=sha256:c0323c9daef75ef2e5083624b4585018a0c9d5e3b40f607eed81a311270b934b \
+    --hash=sha256:c1225416b463483160e4af85d5fc3a9690ccb53fd4b1865a6437825f5ede3209 \
+    --hash=sha256:c1c948747b03be832dceed96ca815cef7360de9aa19d37c730f8e3f6101aca48 \
+    --hash=sha256:c25fe15c70c59eb7c5ce8c06a1f3fa1da0ecc5ea1e7a5922c40fd2fa9b0d5046 \
+    --hash=sha256:cc1b0fff8ead343dae06305f954eb8468ba0ec1a97881f42489d198e4ce3c632 \
+    --hash=sha256:cd6280cf040f233bd7d3407b743b4b4c74f70e8e1c4199cb112a62c941c0772a \
+    --hash=sha256:cd6c3d4b783c556fa00bf540854e42f135e2f256abd29669fcd0da0f2dec79c2 \
+    --hash=sha256:d4d6fcde76f94f5cb9e43e9e9a61f16dacefd228cbbf6f1a09bd9b219a92f1a1 \
+    --hash=sha256:ddf4af30b417d9fe16481e9b81c27ab2a7cde1ff7ba3e85653b02db7d145dc7b \
+    --hash=sha256:df115d4d83168fdf2cae48ef1ff6d1cb4c466364e30861b37121de0f3bf1b990 \
+    --hash=sha256:df7276909358e5635ae203673ab7e509ddd224225a8d6b0790bf13eb2bde1cc5 \
+    --hash=sha256:e4fd89cc178bced6ad29cb3e6dd4aa63fa5017c3524dbd0b25998fb64a87cc8b \
+    --hash=sha256:e9701d0049d92c16703a42771b98d560b95248949f23f8cf7b4eddd201814fb9 \
+    --hash=sha256:ee2f2a527e3c1a6e6411eb4209642e138b544a2d72fe5d0d76daf77b24063534 \
+    --hash=sha256:f7fb7d750cfa0a070d2c24e831fd3481019a60dd317ea2b39acbcebc08b6ed81 \
+    --hash=sha256:f840ed6d8ecba8255df8c42b87fadeda98ddfc6eeec05e2dc66e26d46dd6f58a \
+    --hash=sha256:f86c6358749bd4fda175388691e3ba8c46e24c5347d0afd20f9b7edfc9faf07d \
+    --hash=sha256:fa36ec09ef71d158186bc79e359ff5fdd6e7996fe8ab638f00d6b93139ba4fcf \
+    --hash=sha256:fe2c7201c642b7c308f1675355ad7ff7b66acfe3541625efe5a3ad38f29d6115
+    # via requests
+cyclonedx-python-lib==11.11.0 \
+    --hash=sha256:3049fc83e06a059b5c5907a527625a8ed5073caab10607ed4c9e5503b590fd44 \
+    --hash=sha256:4b3194db72b613717f2912447e67ab618c75ff7dcac6c4af3c0e9e1ac617c102
+    # via pip-audit
+defusedxml==0.7.1 \
+    --hash=sha256:1bb3032db185915b62d7c6209c5a8792be6a32ab2fedacc84e01b52c51aa3e69 \
+    --hash=sha256:a352e7e428770286cc899e2542b6cdaedb2b4953ff269a210103ec58f6198a61
+    # via py-serializable
+filelock==3.29.7 \
+    --hash=sha256:5b481979797ae69e72f0b389d89a80bdd585c260c5b3f1fb9c0a5ba9bb3f195d \
+    --hash=sha256:987db6f789a3a2a59f55081801b2b3697cb97e2a736b5f1a9e99b559285fbc51
+    # via cachecontrol
+idna==3.18 \
+    --hash=sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2 \
+    --hash=sha256:ffb385a7e039654cef1ab9ef32c6fafe283c0c0467bba1d9029738ce4a14a848
+    # via requests
+license-expression==30.4.4 \
+    --hash=sha256:421788fdcadb41f049d2dc934ce666626265aeccefddd25e162a26f23bcbf8a4 \
+    --hash=sha256:73448f0aacd8d0808895bdc4b2c8e01a8d67646e4188f887375398c761f340fd
+    # via cyclonedx-python-lib
+markdown-it-py==4.2.0 \
+    --hash=sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49 \
+    --hash=sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a
+    # via rich
+mdurl==0.1.2 \
+    --hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \
+    --hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba
+    # via markdown-it-py
+msgpack==1.2.1 \
+    --hash=sha256:01e2dd6c9b19d333a00282330cc8a73d38d8dabc306dc5b42cd668c3ac82e833 \
+    --hash=sha256:020e881a764b20d8d7ca1a54fc01b8175519d108e3c3f194fddc200bda95951a \
+    --hash=sha256:04c721c2c7448767e9e3f2520a475663d8ee0f09c31890f6d2bd70fd636a9647 \
+    --hash=sha256:05f340e47e7e47d2da8db9b53e1bb1d294369e9ef45a747441309f6650b8351d \
+    --hash=sha256:0a70e3cf2804a300d921bb0940426e35f4e489a23adfb77a808892241db0a064 \
+    --hash=sha256:0adcf06ffde0777c0e1a9b771a2b1c4226ba1bbf748c8efcc02fcdeca3299107 \
+    --hash=sha256:0c0d9802354507bcba62af19c17918e3eb437cc25e6f50657d511b5856a77aac \
+    --hash=sha256:0e2bf9280bceb5efca998435904b5d3e9fdbcc11d90dc9df30aec7973252b720 \
+    --hash=sha256:1233ee2dd0cefba127583de50ea654677277047d238303521db35def3d7b2e7c \
+    --hash=sha256:146ee4e9ce80b365c6d4c47073da9da7bcec473e58194ceee5dd7620ace77e06 \
+    --hash=sha256:1548006a91aa93c5da81f3bdcebc1a0d10cea2d25969754fbe848da622b2b895 \
+    --hash=sha256:196300e7e5d6e74d50f1607ab9c06c4a1484c383cd22defd727902591f7e8dde \
+    --hash=sha256:1dabedcd0f23559f3596428c6589c1cd8c6eaed3a0d720795b07b0225d769203 \
+    --hash=sha256:20466cca18c49c7292a8984bc15d65857b171e7264bdcb5f96baf8be238791fc \
+    --hash=sha256:298872ecf9e61950f1c6af4ca969b859ee91783bb920ef6e6172697d0c8aad74 \
+    --hash=sha256:29a3f6e9667868429d8240dfd063ea5ffdc1321c13d783aa23827a38de0dcb22 \
+    --hash=sha256:2eda0b7ebb1283a98d3e4492ac933c8af6aff59fd3df1c3ed024f536af4b1dc8 \
+    --hash=sha256:2ef59c659f289eddf8aa6623823f19fa2f40a4029266889eac7a2505dd210c35 \
+    --hash=sha256:2ff164c1b0bcb740b073b99e945234d0212852fa378e44a208c425379140dbeb \
+    --hash=sha256:33f14fba63278b714efe6ad07e50ea5f03d91537aa6a1c5f1ceca4cf44013ca9 \
+    --hash=sha256:350cb813d0af6e65d2f7ef0d729f7ff5be5a8bce03665892f43e5883d4ecc1b8 \
+    --hash=sha256:4202c74688ca06591f78cb18988228bd4cca2cc75d57b60008372892d2f1e6e6 \
+    --hash=sha256:4227224aaec8f7fbcbfbd4272319347b2bb4030366502600f8c45588c5187b07 \
+    --hash=sha256:491cc39455ca765fad51fb451bf2915eb2cf41192ab5801ce8d67c1d614fe056 \
+    --hash=sha256:575957e79cd51903a4e8495a242442949641e08f1efd5197b43bebd3ea7682b4 \
+    --hash=sha256:5ad5467fc3f68b5468e06c5f788d712e9f8ffc8b0cd1bcb160c105c1ee92dae7 \
+    --hash=sha256:5bb9c386f0a329c035ddbab4b72d1028bf9627add8dda41070288563d57ed1b1 \
+    --hash=sha256:5c24aa15d5963051e1a5c62b12c50cd705992502b5ec1f3bece6046f33c9fc24 \
+    --hash=sha256:5f6277e5f783c36786a145e0247fc189a03f35f84b251646e53592d2bc12b355 \
+    --hash=sha256:60926b75d00c8e816ef98f3034f484a8bc64242d66839cef4cf7e503142316a0 \
+    --hash=sha256:633727297ed063441fd1cda2288865487f33ad14eeb8831afb5f0c396a62cfce \
+    --hash=sha256:67f6dd22fa72a93752643f07889796d62739a13415ee630169a8ce764f86cf9f \
+    --hash=sha256:6d09badf350af2be9d189184e04e64cf54ad93569ab3d96fca58bd3e84aad707 \
+    --hash=sha256:6ee967f7c7e1df2890c671ff2ee51a28ded0efc95da3e507176dee881ce36c66 \
+    --hash=sha256:74847557e28ce71bd3c438a447ca90e4b507e997ddbdef8a12a7b283b86c156b \
+    --hash=sha256:779197a6513bab3c3632265e3d0f7cb3227e62510841a6f34f1eaa37efbb345e \
+    --hash=sha256:787c9bebb5833e8f6fc8abca3c0597683d8d87f56a8842b6b89c75a5f3176e2d \
+    --hash=sha256:7d31c0ac0c640f877804c67cb2bc9f4e23dc2db97e96c2e67fa27d38283b41f8 \
+    --hash=sha256:810b916696c86ef0deb3b74588480224df4c1b071136c34183e4a2a4284d7ac7 \
+    --hash=sha256:83efa1c898e0fc5380fc0cabbf75164c52e3b5cbb45973710d75821928380c73 \
+    --hash=sha256:85f57e960d877f2977f6430896191b04a21f8901b3b4baf2e4604329f4db5402 \
+    --hash=sha256:8b267ce94efb76fbd1b3373511420074ee3187f0f7811bf394531de13294735a \
+    --hash=sha256:8c2ed1e48cc0f460bf3c7780e7137ff21a4e18433451916f2442c1b21036cd7d \
+    --hash=sha256:8c7b398c56ff125feae96c2737abfec5595f1fa0aa186df60c56040b8accb95c \
+    --hash=sha256:8d00f177ca88a77c1cf848d204a38f249751650b601cb6532acc68805d8a8273 \
+    --hash=sha256:8ff92d7feeaf5bc26c51495b69e2f99ed97ab79346fb6555f44be7dd2ac6503b \
+    --hash=sha256:91054a783328e0ea7954b8771095705c8d2243b814743fbaadf14552c9c52c5d \
+    --hash=sha256:98b58bdb89c46190e4609bb36abe17c6d4105ad13f9c5f8f6f64d320f8ced3fb \
+    --hash=sha256:a28d076ca7c82b9c8728ad90b7147489449557038bed50e4241eb832395169b4 \
+    --hash=sha256:aa6c4be5d1c02a42b066ca6ddb71adf36432868fdcdb6ee87e634e86e0674190 \
+    --hash=sha256:aded5bdf32609dc7987a49bbbd15a8ef096193f96dd8bbeb791de729e650acf5 \
+    --hash=sha256:afc5febcd4c99effbc02b528e49d6fd0760b2b7d48c05239e345a5fa6e743d9a \
+    --hash=sha256:b50b727bd652bdc37d950336c848ef20ec54a4cafc38dce19b1cd86ad625d0f7 \
+    --hash=sha256:c1c79a604a2969a868a78b6ebd27a887e00c624f14f66b3038e0590cb23332d1 \
+    --hash=sha256:ca0dacff965c47afdc3749a8469d7302a8f801d6a28758d55120d75e66ce6889 \
+    --hash=sha256:d3567748a5107cb40cdf66a275430c2f87c07777698f4bfd25c35f44d533258c \
+    --hash=sha256:dc871b997a9370d855b7394465f2f350e847a5b806dd38dcc9c989e7d87da155 \
+    --hash=sha256:dd3bfe82d53edfe4b7fc9a7ec9761e23a7a5b1dac22264505af428253c29ed24 \
+    --hash=sha256:e3dc2feb0876209d9c38aa56cb1de169bd6c4348f1aa48271f241226590993e6 \
+    --hash=sha256:e4f1d0f8f98ade9634e01fb704a408f9336c0a8f1117b369f5db83dc7551d8b1 \
+    --hash=sha256:ec0e675d59150a6269ddc9139087c722292664a37d071a849c05c473350f1f2d \
+    --hash=sha256:ee1d9ed27d0497b848923746cf762ed2e7db24f4be7eec8e5cbe8c766aa707b7 \
+    --hash=sha256:f02cf17a6ca1abe29b5f980644f7551f94d71f2011509b26d8625ce038f0df64 \
+    --hash=sha256:f12038a35fabd52e56a3547bab42401af49a45caa6dd00b34c44de235bc93ee2 \
+    --hash=sha256:f310233ef7fb9c14e201c93639fe5f5260b005f56f0b29048e999c30935596cc \
+    --hash=sha256:f9389552ecf4784886345ead0647e4edc96bee37cbab05b75540f542f766c48c
+    # via cachecontrol
+packageurl-python==0.17.6 \
+    --hash=sha256:1252ce3a102372ca6f86eb968e16f9014c4ba511c5c37d95a7f023e2ca6e5c25 \
+    --hash=sha256:31a85c2717bc41dd818f3c62908685ff9eebcb68588213745b14a6ee9e7df7c9
+    # via cyclonedx-python-lib
+packaging==26.2 \
+    --hash=sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e \
+    --hash=sha256:ff452ff5a3e828ce110190feff1178bb1f2ea2281fa2075aadb987c2fb221661
+    # via
+    #   pip-audit
+    #   pip-requirements-parser
+pip-api==0.0.34 \
+    --hash=sha256:8b2d7d7c37f2447373aa2cf8b1f60a2f2b27a84e1e9e0294a3f6ef10eb3ba6bb \
+    --hash=sha256:9b75e958f14c5a2614bae415f2adf7eeb54d50a2cfbe7e24fd4826471bac3625
+    # via pip-audit
+pip-audit==2.10.1 \
+    --hash=sha256:1eb4565d19ebe5d48996f4b770b4d2b32887e12cb12cfa637f1a064011b55ffc \
+    --hash=sha256:99ef3f600a317c1945f1e89e227ef26e1c2d618429b8bd3fa6f4f7c440c4611a
+    # via -r audit.in
+pip-requirements-parser==32.0.1 \
+    --hash=sha256:4659bc2a667783e7a15d190f6fccf8b2486685b6dba4c19c3876314769c57526 \
+    --hash=sha256:b4fa3a7a0be38243123cf9d1f3518da10c51bdb165a2b2985566247f9155a7d3
+    # via pip-audit
+platformdirs==4.10.0 \
+    --hash=sha256:31e761a6a0ca04faf7353ea759bdba55652be214725111e5aac52dfa29d4bef7 \
+    --hash=sha256:fb516cdb12eb0d857d0cd85a7c57cea4d060bee4578d6cf5a14dfdf8cbf8784a
+    # via pip-audit
+py-serializable==2.1.0 \
+    --hash=sha256:9d5db56154a867a9b897c0163b33a793c804c80cee984116d02d49e4578fc103 \
+    --hash=sha256:b56d5d686b5a03ba4f4db5e769dc32336e142fc3bd4d68a8c25579ebb0a67304
+    # via cyclonedx-python-lib
+pygments==2.20.0 \
+    --hash=sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f \
+    --hash=sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176
+    # via rich
+pyparsing==3.3.2 \
+    --hash=sha256:850ba148bd908d7e2411587e247a1e4f0327839c40e2e5e6d05a007ecc69911d \
+    --hash=sha256:c777f4d763f140633dcb6d8a3eda953bf7a214dc4eff598413c070bcdc117cbc
+    # via pip-requirements-parser
+requests==2.34.2 \
+    --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0 \
+    --hash=sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed
+    # via
+    #   cachecontrol
+    #   pip-audit
+rich==15.0.0 \
+    --hash=sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb \
+    --hash=sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36
+    # via pip-audit
+sortedcontainers==2.4.0 \
+    --hash=sha256:25caa5a06cc30b6b83d11423433f65d1f9d76c4c6a0c90e3379eaa43b9bfdb88 \
+    --hash=sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0
+    # via cyclonedx-python-lib
+tomli==2.4.1 \
+    --hash=sha256:01f520d4f53ef97964a240a035ec2a869fe1a37dde002b57ebc4417a27ccd853 \
+    --hash=sha256:0d85819802132122da43cb86656f8d1f8c6587d54ae7dcaf30e90533028b49fe \
+    --hash=sha256:136443dbd7e1dee43c68ac2694fde36b2849865fa258d39bf822c10e8068eac5 \
+    --hash=sha256:1d8591993e228b0c930c4bb0db464bdad97b3289fb981255d6c9a41aedc84b2d \
+    --hash=sha256:2190f2e9dd7508d2a90ded5ed369255980a1bcdd58e52f7fe24b8162bf9fedbd \
+    --hash=sha256:2c1c351919aca02858f740c6d33adea0c5deea37f9ecca1cc1ef9e884a619d26 \
+    --hash=sha256:36d2bd2ad5fb9eaddba5226aa02c8ec3fa4f192631e347b3ed28186d43be6b54 \
+    --hash=sha256:3d48a93ee1c9b79c04bb38772ee1b64dcf18ff43085896ea460ca8dec96f35f6 \
+    --hash=sha256:47149d5bd38761ac8be13a84864bf0b7b70bc051806bc3669ab1cbc56216b23c \
+    --hash=sha256:4ab97e64ccda8756376892c53a72bd1f964e519c77236368527f758fbc36a53a \
+    --hash=sha256:4b605484e43cdc43f0954ddae319fb75f04cc10dd80d830540060ee7cd0243cd \
+    --hash=sha256:504aa796fe0569bb43171066009ead363de03675276d2d121ac1a4572397870f \
+    --hash=sha256:51529d40e3ca50046d7606fa99ce3956a617f9b36380da3b7f0dd3dd28e68cb5 \
+    --hash=sha256:52c8ef851d9a240f11a88c003eacb03c31fc1c9c4ec64a99a0f922b93874fda9 \
+    --hash=sha256:559db847dc486944896521f68d8190be1c9e719fced785720d2216fe7022b662 \
+    --hash=sha256:5a881ab208c0baf688221f8cecc5401bd291d67e38a1ac884d6736cbcd8247e9 \
+    --hash=sha256:5cb41aa38891e073ee49d55fbc7839cfdb2bc0e600add13874d048c94aadddd1 \
+    --hash=sha256:5e262d41726bc187e69af7825504c933b6794dc3fbd5945e41a79bb14c31f585 \
+    --hash=sha256:5ee18d9ebdb417e384b58fe414e8d6af9f4e7a0ae761519fb50f721de398dd4e \
+    --hash=sha256:7008df2e7655c495dd12d2a4ad038ff878d4ca4b81fccaf82b714e07eae4402c \
+    --hash=sha256:734e20b57ba95624ecf1841e72b53f6e186355e216e5412de414e3c51e5e3c41 \
+    --hash=sha256:7c7e1a961a0b2f2472c1ac5b69affa0ae1132c39adcb67aba98568702b9cc23f \
+    --hash=sha256:7f86fd587c4ed9dd76f318225e7d9b29cfc5a9d43de44e5754db8d1128487085 \
+    --hash=sha256:7f94b27a62cfad8496c8d2513e1a222dd446f095fca8987fceef261225538a15 \
+    --hash=sha256:88dceee75c2c63af144e456745e10101eb67361050196b0b6af5d717254dddf7 \
+    --hash=sha256:8a650c2dbafa08d42e51ba0b62740dae4ecb9338eefa093aa5c78ceb546fcd5c \
+    --hash=sha256:8d65a2fbf9d2f8352685bc1364177ee3923d6baf5e7f43ea4959d7d8bc326a36 \
+    --hash=sha256:96481a5786729fd470164b47cdb3e0e58062a496f455ee41b4403be77cb5a076 \
+    --hash=sha256:a120733b01c45e9a0c34aeef92bf0cf1d56cfe81ed9d47d562f9ed591a9828ac \
+    --hash=sha256:b1d22e6e9387bf4739fbe23bfa80e93f6b0373a7f1b96c6227c32bef95a4d7a8 \
+    --hash=sha256:b8c198f8c1805dc42708689ed6864951fd2494f924149d3e4bce7710f8eb5232 \
+    --hash=sha256:c2541745709bad0264b7d4705ad453b76ccd191e64aa6f0fc66b69a293a45ece \
+    --hash=sha256:c742f741d58a28940ce01d58f0ab2ea3ced8b12402f162f4d534dfe18ba1cd6a \
+    --hash=sha256:c7f2c7f2b9ca6bdeef8f0fa897f8e05085923eb091721675170254cbc5b02897 \
+    --hash=sha256:d312ef37c91508b0ab2cee7da26ec0b3ed2f03ce12bd87a588d771ae15dcf82d \
+    --hash=sha256:d4d8fe59808a54658fcc0160ecfb1b30f9089906c50b23bcb4c69eddc19ec2b4 \
+    --hash=sha256:da25dc3563bff5965356133435b757a795a17b17d01dbc0f42fb32447ddfd917 \
+    --hash=sha256:eab21f45c7f66c13f2a9e0e1535309cee140182a9cdae1e041d02e47291e8396 \
+    --hash=sha256:eb0dc4e38e6a1fd579e5d50369aa2e10acfc9cace504579b2faabb478e76941a \
+    --hash=sha256:ec9bfaf3ad2df51ace80688143a6a4ebc09a248f6ff781a9945e51937008fcbc \
+    --hash=sha256:ede3e6487c5ef5d28634ba3f31f989030ad6af71edfb0055cbbd14189ff240ba \
+    --hash=sha256:f3c6818a1a86dd6dca7ddcaaf76947d5ba31aecc28cb1b67009a5877c9a64f3f \
+    --hash=sha256:f758f1b9299d059cc3f6546ae2af89670cb1c4d48ea29c3cacc4fe7de3058257 \
+    --hash=sha256:f8f0fc26ec2cc2b965b7a3b87cd19c5c6b8c5e5f436b984e85f486d652285c30 \
+    --hash=sha256:fd0409a3653af6c147209d267a0e4243f0ae46b011aa978b1080359fddc9b6cf \
+    --hash=sha256:ff18e6a727ee0ab0388507b89d1bc6a22b138d1e2fa56d1ad494586d61d2eae9 \
+    --hash=sha256:ff2983983d34813c1aeb0fa89091e76c3a22889ee83ab27c5eeb45100560c049
+    # via pip-audit
+tomli-w==1.2.0 \
+    --hash=sha256:188306098d013b691fcadc011abd66727d3c414c571bb01b1a174ba8c983cf90 \
+    --hash=sha256:2dd14fac5a47c27be9cd4c976af5a12d87fb1f0b4512f81d69cce3b35ae25021
+    # via pip-audit
+typing-extensions==4.16.0 \
+    --hash=sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8 \
+    --hash=sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5
+    # via cyclonedx-python-lib
+urllib3==2.7.0 \
+    --hash=sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c \
+    --hash=sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897
+    # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+pip==26.1.2 \
+    --hash=sha256:382ff9f685ee3bc25864f820aa50505825f10f5458ffff07e30a6d96e5715cab \
+    --hash=sha256:f49cd134c61cf2fd75e0ce2676db03e4054504a5a4986d00f8299ae632dc4605
+    # via pip-api
@@ -0,0 +1,17 @@
+# `build` for the publish.yml `build` job, hash-pinned (Scorecard:
+# Pinned-Dependencies).
+#
+# Target env: ubuntu-latest, Python 3.13 ONLY.
+# That narrowness is load-bearing — build's marker-gated deps are all excluded
+# at this target and therefore absent from build.txt:
+#   colorama          ; os_name == "nt"            -> posix runner, not needed
+#   tomli             ; python_version < "3.11"    -> 3.13, not needed
+#   importlib-metadata; python_full_version < "3.10.2" -> 3.13, not needed
+# If publish.yml ever gains a Windows runner or a <3.11 Python, regenerate this
+# file on that target (or add the dep explicitly) or --require-hashes will fail
+# with "all requirements must have their versions pinned".
+# See e2e.in for the cross-OS variant that handles this.
+#
+# Regenerate:
+#   pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=build.txt build.in
+build==1.5.0
@@ -0,0 +1,18 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=build.txt build.in
+#
+build==1.5.0 \
+    --hash=sha256:13f3eecb844759ab66efec90ca17639bbf14dc06cb2fdf37a9010322d9c50a6f \
+    --hash=sha256:302c22c3ba2a0fd5f3911918651341ebb3896176cbdec15bd421f80b1afc7647
+    # via -r build.in
+packaging==26.2 \
+    --hash=sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e \
+    --hash=sha256:ff452ff5a3e828ce110190feff1178bb1f2ea2281fa2075aadb987c2fb221661
+    # via build
+pyproject-hooks==1.2.0 \
+    --hash=sha256:1e859bd5c40fae9448642dd871adf459e5e2084186e8d2c2a79a824c970da1f8 \
+    --hash=sha256:9e5c6bfa8dcc30091c74b0cf803c81fdd29d94f01992a7707bc97babb1141913
+    # via build
@@ -0,0 +1,26 @@
+# Outer build tooling for e2e-wheel.yml, hash-pinned (Scorecard:
+# Pinned-Dependencies).
+#
+# Target env: ubuntu-latest + windows-latest + macos-latest, Python 3.12.
+# conftest.py builds the wheel + a clean venv internally; the outer env only
+# needs build + pytest.
+#
+# WHY colorama IS LISTED EXPLICITLY (do not "clean up"):
+# both build and pytest depend on colorama behind a platform marker
+# (`os_name == "nt"` / `sys_platform == "win32"`). pip-compile evaluates markers
+# against the machine it runs on, so compiling on Linux DROPS colorama from the
+# lock — and the windows-latest leg then dies under --require-hashes with
+# "In --require-hashes mode, all requirements must have their versions pinned".
+# Listing it as a direct requirement forces it into the lock with hashes.
+# colorama is a pure-python universal wheel (py2.py3-none-any, zero deps), so
+# installing it on the Linux/macOS legs is inert.
+#
+# Python 3.12 is likewise load-bearing: pytest's `exceptiongroup`/`tomli` and
+# build's `tomli` are gated on python_version < "3.11" and are absent here. If
+# the matrix ever drops below 3.11, regenerate on that target.
+#
+# Regenerate (on Linux, Python 3.12):
+#   pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=e2e.txt e2e.in
+build==1.5.0
+pytest==9.1.1
+colorama==0.4.6
@@ -0,0 +1,40 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=e2e.txt e2e.in
+#
+build==1.5.0 \
+    --hash=sha256:13f3eecb844759ab66efec90ca17639bbf14dc06cb2fdf37a9010322d9c50a6f \
+    --hash=sha256:302c22c3ba2a0fd5f3911918651341ebb3896176cbdec15bd421f80b1afc7647
+    # via -r e2e.in
+colorama==0.4.6 \
+    --hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \
+    --hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6
+    # via -r e2e.in
+iniconfig==2.3.0 \
+    --hash=sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730 \
+    --hash=sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12
+    # via pytest
+packaging==26.2 \
+    --hash=sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e \
+    --hash=sha256:ff452ff5a3e828ce110190feff1178bb1f2ea2281fa2075aadb987c2fb221661
+    # via
+    #   build
+    #   pytest
+pluggy==1.6.0 \
+    --hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 \
+    --hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
+    # via pytest
+pygments==2.20.0 \
+    --hash=sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f \
+    --hash=sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176
+    # via pytest
+pyproject-hooks==1.2.0 \
+    --hash=sha256:1e859bd5c40fae9448642dd871adf459e5e2084186e8d2c2a79a824c970da1f8 \
+    --hash=sha256:9e5c6bfa8dcc30091c74b0cf803c81fdd29d94f01992a7707bc97babb1141913
+    # via build
+pytest==9.1.1 \
+    --hash=sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313 \
+    --hash=sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c
+    # via -r e2e.in
@@ -0,0 +1,15 @@
+# ruff for the ci.yml `lint` job, hash-pinned (Scorecard: Pinned-Dependencies).
+#
+# Target env: ubuntu-latest, Python 3.13. ruff has no dependencies, and
+# --generate-hashes emits every PyPI file hash for the pinned version (all 18
+# platform wheels + sdist), so this lock stays valid if lint ever runs on
+# another OS/arch.
+#
+# 0.15.21 == what the previous unpinned `pip install ruff` resolved to on
+# 2026-07-15, so pinning is a no-op for lint results today. Bumping this file
+# can surface new lint rules — that is the intended, reviewable trade-off.
+# Keep compatible with pyproject.toml's dev extra (`ruff>=0.11`).
+#
+# Regenerate:
+#   pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=lint.txt lint.in
+ruff==0.15.21
@@ -0,0 +1,26 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=lint.txt lint.in
+#
+ruff==0.15.21 \
+    --hash=sha256:00eca240af5789fec6fe7df74c088cc1f9644ed83027113468efba7c92b94075 \
+    --hash=sha256:01d65b4831c6b2a4ba8ee6faa84049d44d982b7a706e622c4094c509e51673be \
+    --hash=sha256:01f8d5be84823c172b389e123174f781f9daf86d6c58719d603f941932195cdd \
+    --hash=sha256:0f212c5d7d54c01bbfe6dcab02b724a39300f3e34ed7acbe995ccb320a2c58bd \
+    --hash=sha256:16d090c0740916594157e75b80d666eab8e78083b39b3b0e1d698f4670a17b86 \
+    --hash=sha256:262ab31557a75141325e32d3357f3597645a7f084e732b6b054dde428ecd9341 \
+    --hash=sha256:2c5a913a589120ce67933d5d05fd6ddbcc2481c6a054980ee767f7414c72b4fd \
+    --hash=sha256:3a10e74757dd65004d779b73e2f3c5210156d9980b41224d50d2ebcf1db51e67 \
+    --hash=sha256:5ef04b681d02ad4dc9620f00f83ac5c22f652d0e9a9cfe431d219b16ad5ccc41 \
+    --hash=sha256:63ea0e965e5d73c90e95b2434beeafc70820536717f561b32ab6e777cb9bdf5d \
+    --hash=sha256:659c4e7a4212f83306045ec7c5e5a356d16d9a6ef4ae0c7a4d872914fc655d9d \
+    --hash=sha256:6e83115d4b9377c1cbc13abf0e051f069fab0ef815ea0504a8a008cee24dd0a8 \
+    --hash=sha256:9e866eab611a5f959d36df2d10e446973a3610bc42b0c15b31dc27977d59c233 \
+    --hash=sha256:bab0905d2f29e0d9fbc3c373ed23db0095edaa3f71f1f4f519ec15134d9e85c8 \
+    --hash=sha256:d0cfc841c572283c36548f82664a54ce6565567f1b0d5b4cf2caac693d8b7500 \
+    --hash=sha256:d4b8d9a2f0f12b816b50447f6eccb9f4bb01a6b82c86b50fb3b5354b458dc6d3 \
+    --hash=sha256:e6312e41bc96791299614995ea3a977c5857c3b5662b1ecef6755b02b87cb646 \
+    --hash=sha256:e89bc93c0d3803ba870b55c29671bad9dc6d94bb1eb181b056b52eb05b52854f
+    # via -r lint.in
@@ -0,0 +1,13 @@
+# pip self-upgrade, hash-pinned (OpenSSF Scorecard: Pinned-Dependencies).
+#
+# Replaces `python -m pip install --upgrade pip` in ci.yml, security.yml and
+# e2e-wheel.yml. pip has no runtime dependencies, so this lock is inherently
+# portable across every OS and Python in the CI matrix (3.10-3.13).
+#
+# 26.1.2 is deliberate, not merely "latest": security.yml's pip-audit scans the
+# whole environment and the runner's bundled pip (26.1.1) carries PYSEC-2026-196
+# (fixed in 26.1.2). Do not pin below 26.1.2 — audit will red.
+#
+# Regenerate:
+#   pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=pip.txt pip.in
+pip==26.1.2
@@ -0,0 +1,12 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --allow-unsafe --generate-hashes --no-emit-index-url --output-file=pip.txt pip.in
+#
+
+# The following packages are considered to be unsafe in a requirements file:
+pip==26.1.2 \
+    --hash=sha256:382ff9f685ee3bc25864f820aa50505825f10f5458ffff07e30a6d96e5715cab \
+    --hash=sha256:f49cd134c61cf2fd75e0ce2676db03e4054504a5a4986d00f8299ae632dc4605
+    # via -r pip.in
@@ -16,11 +16,13 @@ jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.13"
-      - run: pip install ruff
+      # Hash-pinned tool install (Scorecard: Pinned-Dependencies). Pins ruff to
+      # the version this lint gate is known-green against; see .github/requirements/lint.in.
+      - run: python -m pip install --require-hashes -r .github/requirements/lint.txt
      - run: ruff check src/ tests/
      - run: ruff format --check src/ tests/

@@ -31,12 +33,12 @@ jobs:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: ${{ matrix.python-version }}
      - run: |
-          python -m pip install --upgrade pip
+          python -m pip install --require-hashes -r .github/requirements/pip.txt
          pip install -e ".[dev]"
      # tests/e2e build a wheel + clean venv per the dedicated e2e-wheel.yml
      # workflow — they are not part of the fast unit lane.
@@ -46,18 +48,18 @@ jobs:
    name: seedgo-audit
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - 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
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.13"
      - run: |
-          python -m pip install --upgrade pip
+          python -m pip install --require-hashes -r .github/requirements/pip.txt
          # 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
@@ -74,16 +76,16 @@ jobs:
    needs: [test]
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.13"
      - run: |
-          python -m pip install --upgrade pip
+          python -m pip install --require-hashes -r .github/requirements/pip.txt
          pip install -e ".[dev]"
      - run: coverage run -m pytest --rootdir=. --ignore=tests/e2e
      - run: coverage xml
-      - uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
        with:
          files: ./coverage.xml
          fail_ci_if_error: false
@@ -39,15 +39,22 @@ jobs:
        python-version: ["3.12"]
    steps:
      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install build tooling
-        run: python -m pip install --upgrade pip build pytest
+        # Hash-pinned (Scorecard: Pinned-Dependencies). e2e.txt carries colorama
+        # explicitly — build/pytest need it only on Windows (os_name == "nt" /
+        # sys_platform == "win32"), and a Linux-generated lock would otherwise
+        # omit it and break the windows-latest leg under --require-hashes.
+        # See .github/requirements/e2e.in.
+        run: |
+          python -m pip install --require-hashes -r .github/requirements/pip.txt
+          python -m pip install --require-hashes -r .github/requirements/e2e.txt

      - name: Run cross-OS e2e wiring harness
        # conftest.py builds the wheel + clean venv internally; the outer env
@@ -18,9 +18,9 @@ jobs:
  macos-setup:
    runs-on: macos-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: '3.12'

@@ -11,13 +11,34 @@ permissions:
 jobs:
  build:
    runs-on: ubuntu-latest
+    # Job-level permissions REPLACE the top-level block rather than merge with
+    # it, so `contents: read` is restated here on purpose — dropping it would
+    # break actions/checkout. id-token/attestations are what the provenance
+    # attestation below needs (Scorecard: Signed-Releases).
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.13"
-      - run: pip install build
+      # Hash-pinned tool install (Scorecard: Pinned-Dependencies).
+      - run: python -m pip install --require-hashes -r .github/requirements/build.txt
      - run: python -m build
+      - name: Attest build provenance
+        # Signs a provenance statement binding these exact sdist/wheel digests to
+        # this workflow run, via the same keyless Sigstore/OIDC path as the
+        # release signing below. Runs after the artifacts exist and before they
+        # leave the job, so the attested digests are the published ones.
+        # NOTE: the bundle is deliberately NOT written into dist/ — the publish
+        # job feeds dist/* to gh-action-pypi-publish, which rejects any file that
+        # is not a distribution. See the report note on attaching provenance to
+        # the GitHub Release.
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        with:
+          subject-path: "dist/*"
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: dist
@@ -43,7 +64,7 @@ jobs:
      contents: write
      id-token: write # keyless Sigstore signing (OIDC); no signing key exists
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: dist
@@ -55,7 +76,7 @@ jobs:
        # 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@04cffa1d795717b140764e8b640de88853c92acc # v3.3.0
+        uses: sigstore/gh-action-sigstore-python@5b79a39c381910c090341a2c9b0bf022c8b387e1 # v3.4.0
        with:
          inputs: ./dist/*.tar.gz ./dist/*.whl
          release-signing-artifacts: false
@@ -22,7 +22,7 @@ jobs:

    steps:
      - name: "Checkout code"
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false

@@ -41,6 +41,6 @@ jobs:
          retention-days: 5

      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
        with:
          sarif_file: results.sarif
@@ -18,8 +18,8 @@ jobs:
  dependency-scan:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.13"
      # Upgrade pip first: pip-audit scans the whole environment, and the
@@ -27,9 +27,11 @@ jobs:
      # 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.
+      # Both installs are hash-pinned (Scorecard: Pinned-Dependencies); pip.txt
+      # holds the >=26.1.2 floor the comment above requires.
      - run: |
-          python -m pip install --upgrade pip
-          pip install pip-audit
+          python -m pip install --require-hashes -r .github/requirements/pip.txt
+          python -m pip install --require-hashes -r .github/requirements/audit.txt
      - run: pip install -e .
      - name: Pip audit
        run: pip-audit --skip-editable
@@ -41,8 +43,8 @@ jobs:
      actions: read
      security-events: write
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
        with:
          languages: python
-      - uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+      - uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
@@ -14,7 +14,7 @@ jobs:
      issues: write
      pull-requests: write
    steps:
-      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
+      - uses: actions/stale@1e223db275d687790206a7acac4d1a11bd6fe629 # v10.4.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
@@ -18,9 +18,9 @@ jobs:
  windows-setup:
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: '3.12'

@@ -43,7 +43,7 @@ FPLAN-*.md
 DPLAN-*.md
 RPLAN-*.md
 TDPLAN-*.md
-
+PPLAN-*.md
 # Branch local directories
 logs/
 artifacts/
@@ -87,29 +87,42 @@ src/aipass/*/apps/integrations/**
 !src/aipass/*/apps/integrations/README.md

 # Spawn template exceptions (template files must be tracked for public repo)
-!src/aipass/spawn/templates/builder/.trinity/
-!src/aipass/spawn/templates/builder/.trinity/**
-!src/aipass/spawn/templates/builder/.ai_mail.local/
-!src/aipass/spawn/templates/builder/.ai_mail.local/**
-!src/aipass/spawn/templates/builder/.archive/
-!src/aipass/spawn/templates/builder/.archive/**
-!src/aipass/spawn/templates/builder/.spawn/
-!src/aipass/spawn/templates/builder/.spawn/**
-!src/aipass/spawn/templates/builder/.claude/
-!src/aipass/spawn/templates/builder/.claude/**
-!src/aipass/spawn/templates/builder/*_json/
-!src/aipass/spawn/templates/builder/*_json/**
-!src/aipass/spawn/templates/builder/logs/
-!src/aipass/spawn/templates/builder/logs/**
-!src/aipass/spawn/templates/builder/artifacts/
-!src/aipass/spawn/templates/builder/artifacts/**
-!src/aipass/spawn/templates/builder/dropbox/
-!src/aipass/spawn/templates/builder/dropbox/**
-!src/aipass/spawn/templates/builder/tools/
-!src/aipass/spawn/templates/builder/tools/**
-!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/aipass_framework/.trinity/
+!src/aipass/spawn/templates/aipass_framework/.trinity/**
+!src/aipass/spawn/templates/aipass_framework/.ai_mail.local/
+!src/aipass/spawn/templates/aipass_framework/.ai_mail.local/**
+!src/aipass/spawn/templates/aipass_framework/.archive/
+!src/aipass/spawn/templates/aipass_framework/.archive/**
+!src/aipass/spawn/templates/aipass_framework/.spawn/
+!src/aipass/spawn/templates/aipass_framework/.spawn/**
+!src/aipass/spawn/templates/aipass_framework/.claude/
+!src/aipass/spawn/templates/aipass_framework/.claude/**
+!src/aipass/spawn/templates/aipass_framework/*_json/
+!src/aipass/spawn/templates/aipass_framework/*_json/**
+!src/aipass/spawn/templates/aipass_framework/logs/
+!src/aipass/spawn/templates/aipass_framework/logs/**
+!src/aipass/spawn/templates/aipass_framework/artifacts/
+!src/aipass/spawn/templates/aipass_framework/artifacts/**
+!src/aipass/spawn/templates/aipass_framework/dropbox/
+!src/aipass/spawn/templates/aipass_framework/dropbox/**
+!src/aipass/spawn/templates/aipass_framework/tools/
+!src/aipass/spawn/templates/aipass_framework/tools/**
+!src/aipass/spawn/templates/aipass_framework/docs.local/
+!src/aipass/spawn/templates/aipass_framework/docs.local/**
+!src/aipass/spawn/templates/aipass_framework/DASHBOARD.local.json
+
+# 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
+
+# hooks boot-shim installer — must ship so fresh clones can install the claude()
+# shell function. Collides with the blanket tools/ ignore (line 51).
+!src/aipass/hooks/tools/
+src/aipass/hooks/tools/*
+!src/aipass/hooks/tools/install_boot_shim.sh

 # CI artifacts
 windows-pytest-results/
@@ -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.
+
+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`
- - Check: `drone @ai_mail inbox` — process any mail, don't ask.
- - Run: `drone @git status`
+ - 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.

@@ -18,4 +18,6 @@ Use drone commands for all operations. Never raw git, gh, file access, or python

 # Memories

-Update `.trinity/` at natural breakpoints, after milestones, and on `/memo`.
+Update `.trinity/` at natural breakpoints, after milestones, and on `/memo`.
+
+Todos[] don't auto-roll — rollover never trims them. So **delete each todo the moment it's done** (never leave it as `status: done`), and **reconcile on load**: close/remove anything already finished so completed work never resurfaces as "open" and wastes a re-confirm.
@@ -15,7 +15,7 @@ PRs are welcome after an issue has been discussed. Keep changes focused -- one f
 - Python 3.10+
 - Tests: `pytest` (4,900+ tests across the project)
 - Quality: AIPass uses its own standards system ([seedgo](src/aipass/seedgo/README.md)) for automated audits
- Run `./setup.sh` to bootstrap the full environment
+- Run `./aipass install --no-init` to bootstrap the full environment (contributors work in the engine repo itself — no first-project scaffold needed)

 ## Questions?

@@ -1,7 +1,6 @@
 [![Status](https://img.shields.io/badge/status-beta-yellow)](#project-status)
 [![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/)
 [![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)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/AIOSAI/AIPass/badge)](https://scorecard.dev/viewer/?uri=github.com/AIOSAI/AIPass)
@@ -31,12 +30,12 @@ That's not a team. That's a room full of people wearing headphones.
 AIPass is a CLI-native scaffold that adds **persistent memory, identity, and coordination** to your AI agents. You bring your project — AIPass adds the agent layer on top. No UI, no dashboard. You work in your terminal.

 ```bash
-pip install aipass
-mkdir my-project && cd my-project
-aipass init run
+git clone https://github.com/AIOSAI/AIPass.git
+cd AIPass
+./aipass install                      # installs everything, then walks you into your first project
 ```

-A guided setup creates your project, your first agent, and opens a terminal where that agent is already running. Say "hi" — it knows who it is. Come back tomorrow — it remembers.
+One command does it all: builds the environment, puts `aipass` + `drone` on your PATH, then chains straight into a guided init that creates your project, your first agent, and opens a terminal where that agent is already running. Say "hi" — it knows who it is. Come back tomorrow — it remembers.

 This is the base framework. It gives your agents the infrastructure to persist, communicate, and organize — everything else you build on top.

@@ -78,12 +77,20 @@ aipass init agent my-agent            # Full agent: apps, mail, memory, identity

 ## Quick Start

-### Your own project
+### 1. Install

 ```bash
-pip install aipass
+git clone https://github.com/AIOSAI/AIPass.git
+cd AIPass
+./aipass install                      # Creates venv, installs, puts `aipass` + `drone` on your PATH, bootstraps 17 agents
+```

-mkdir my-project && cd my-project
+On an interactive terminal, install ends by chaining into `aipass init run` — one command takes you from clone to a working first project. Pass `--no-init` to skip the chain, `--project <dir>` to pick where the project lands (CI and piped shells skip automatically). `./aipass` is a thin repo-root launcher over `setup.sh`; after setup it simply forwards to the installed `aipass` binary.
+
+### 2. Your own project (if you skipped the chain)
+
+```bash
+cd ~ && mkdir my-project && cd my-project
 aipass init run                       # Guided setup — project, first agent, terminal handoff
 ```

@@ -97,15 +104,11 @@ aipass doctor                         # Check system health

 > **Need help?** [Ask in Discussions](https://github.com/AIOSAI/AIPass/discussions) or [file feedback](https://github.com/AIOSAI/AIPass/issues/new?template=feedback.yml) — both take 30 seconds.

-### Explore the full framework
+### 3. Explore the full framework

-Clone the repo to see all 13 agents working together — the reference implementation:
+The clone above already includes all 17 agents working together — the reference implementation:

 ```bash
-git clone https://github.com/AIOSAI/AIPass.git
-cd AIPass
-./setup.sh                            # Creates venv, installs, bootstraps 13 agents
-
 cd src/aipass/devpulse
 claude                                # Talk to the orchestrator
 ```
@@ -141,7 +144,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 aipass                   # 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"
 ```
@@ -149,20 +152,20 @@ drone @ai_mail dispatch @agent "Archive old sessions" "Find sessions older than
 **Two ways to use AIPass:**

 - **Your own project:** `aipass init run` sets up a new project with your first agent. Add more agents as you need them. Your first agent is the orchestrator — it coordinates the others.
- **The full framework:** Clone the repo to work with all 13 core agents. Talk to `devpulse` (the orchestrator), dispatch work across specialists. Agents work in parallel and report back.
+- **The full framework:** Clone the repo to work with all 17 core agents. Talk to `devpulse` (the orchestrator), dispatch work across specialists. Agents work in parallel and report back.

 ---

 ## The Reference Implementation

-AIPass ships with 13 core agents that maintain and develop the framework itself — proving the architecture works at scale. You don't need any of these to use AIPass in your own project. They're here as examples and as services your project can call.
+AIPass ships with 17 core agents that maintain and develop the framework itself — proving the architecture works at scale. You don't need any of these to use AIPass in your own project. They're here as examples and as services your project can call.

 ```
 devpulse (orchestrator)
   ├── aipass   — concierge + onboarding (aipass init, doctor, profile)
   ├── drone    — command routing + @agent resolution
   ├── seedgo   — automated quality standards
-   ├── prax     — real-time monitoring across all agents
+   ├── prax     — real-time monitoring + runaway-log detection across all agents
   ├── ai_mail  — agent-to-agent communication + task dispatch
   ├── flow     — plan lifecycle, templates, auto-archival
   ├── spawn    — creates new agents anywhere on your filesystem
@@ -170,7 +173,11 @@ devpulse (orchestrator)
   ├── memory   — automatic archival, ChromaDB, semantic search
   ├── api      — LLM access layer (OpenRouter, multi-provider)
   ├── trigger  — event-driven automation + self-healing
-   └── cli      — terminal formatting and rich output
+   ├── cli      — terminal formatting and rich output
+   ├── backup   — local-first snapshots + restore (optional Drive sync)
+   ├── daemon   — cron-style task scheduler (each branch owns its schedule)
+   ├── skills   — discoverable capability units any agent can run
+   └── commons  — the social space — post, comment, vote, gather
 ```

 These agents work on the **same filesystem, same project, same time** — no sandboxes, no worktrees. This is the pattern your projects inherit.
@@ -196,11 +203,20 @@ These agents work on the **same filesystem, same project, same time** — no san
 | Agent | Role |
 |-------|------|
 | [**seedgo**](src/aipass/seedgo/README.md) | Automated quality standards, enforced across all agents |
-| [**prax**](src/aipass/prax/README.md) | Real-time monitoring, logs, dashboards |
+| [**prax**](src/aipass/prax/README.md) | Real-time monitoring, logs, dashboards, runaway-log detection |
 | [**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 |
+| [**hooks**](src/aipass/hooks/README.md) | Hook engine — per-project config, sound control, event dispatch, persistent alerts |
 | [**trigger**](src/aipass/trigger/README.md) | Event-driven automation + self-healing |
 | [**cli**](src/aipass/cli/README.md) | Terminal formatting and rich output |
+| [**backup**](src/aipass/backup/README.md) | Local-first backups — snapshots, versioning, restore (optional Google Drive sync) |
+| [**daemon**](src/aipass/daemon/README.md) | Task scheduler — cron-style firing; each branch owns its schedule |
+
+**Capabilities and community** — what agents can do and where they gather:
+
+| Agent | Role |
+|-------|------|
+| [**skills**](src/aipass/skills/README.md) | Capability framework — discoverable, self-contained skill units any agent can run |
+| [**commons**](src/aipass/commons/README.md) | The social space — agents post, comment, vote, and gather as a community |

 </details>

@@ -215,7 +231,7 @@ AIPass is built and tested with **Claude Code** on Linux/WSL.
 | [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.
+The installer (`./aipass install`, powered by setup.sh) auto-detects which CLIs are installed and configures hooks for each — merging with any hooks you've already wired, never overwriting them.

 ---

@@ -225,8 +241,8 @@ setup.sh auto-detects which CLIs are installed and configures hooks for each.

 | Metric | Value |
 |--------|-------|
-| Version | [![PyPI](https://img.shields.io/pypi/v/aipass?label=)](https://pypi.org/project/aipass/) |
-| Agents | 13 core + user-created |
+| Version | See [git tags](https://github.com/AIOSAI/AIPass/tags) |
+| Agents | 17 core + user-created |
 | 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 |
@@ -266,8 +282,8 @@ AIPass stores everything locally in your project directory. To remove it:
 rm -rf .aipass/ .claude/ .ai_mail.local/ hooks/ src/
 rm -f CLAUDE.md AGENTS.md *_REGISTRY.json .gitignore

-# If you installed via pip
-pip uninstall aipass
+# If you ran the backup system, also remove its local state + shipped config
+rm -rf .backup/ && rm -f .backupignore
 ```

 No cloud accounts, no external services, no cleanup beyond your local filesystem.
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# aipass — cold-clone entry point (pre-venv launcher)
+#
+# The first command after cloning:
+#   git clone https://github.com/AIOSAI/AIPass.git
+#   cd AIPass
+#   ./aipass install
+#
+# Pre-setup: only `install` is available — delegates to setup.sh.
+# Post-setup: forwards everything to the venv-installed aipass binary.
+#
+# Stdlib-only, zero AIPass imports, zero third-party deps.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# --- Post-setup: forward to the real binary ---
+if [[ -x "$SCRIPT_DIR/.venv/bin/aipass" ]]; then
+    exec "$SCRIPT_DIR/.venv/bin/aipass" "$@"
+fi
+if [[ -x "$SCRIPT_DIR/.venv/Scripts/aipass.exe" ]]; then
+    exec "$SCRIPT_DIR/.venv/Scripts/aipass.exe" "$@"
+fi
+if [[ -x "$SCRIPT_DIR/.venv/Scripts/aipass" ]]; then
+    exec "$SCRIPT_DIR/.venv/Scripts/aipass" "$@"
+fi
+
+# --- Pre-setup: only 'install' works ---
+if [[ "${1:-}" == "install" ]]; then
+    shift
+    exec bash "$SCRIPT_DIR/setup.sh" "$@"
+fi
+
+# --- Help (no venv, no 'install' verb) ---
+cat <<'HELP'
+AIPass is not set up yet.
+
+  ./aipass install                # set up AIPass (venv + deps + hooks)
+  ./aipass install --no-init      # set up without the guided first-project setup
+  ./aipass install --project DIR  # set the first-project directory
+
+After setup, all aipass commands become available:
+  ./aipass doctor    # system health
+  ./aipass help      # how-does-X-work Q&A
+  ./aipass init run  # scaffold a new project
+
+Quick start:
+  git clone https://github.com/AIOSAI/AIPass.git
+  cd AIPass
+  ./aipass install
+HELP
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "aipass"
-version = "2.5.3"
+version = "2.7.1"
 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"
@@ -31,6 +31,7 @@ dependencies = [
    "requests>=2.34.2",
    "psutil>=5.9",
    "questionary>=2.0",
+    "pathspec>=0.12",
 ]

 [project.urls]
@@ -50,6 +51,9 @@ memory = [
    "chromadb>=1.0",
    "fastembed>=0.4",
 ]
+telegram = [
+    "telethon>=1.36",
+]
 seedgo = []
 dev = [
    "pytest>=9.0.3",
@@ -73,7 +77,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"]
@@ -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",
@@ -2,6 +2,15 @@
 #
 # AIPass setup script
 # Creates a venv, installs the package in editable mode, and verifies CLI entry points.
+# On interactive terminals it then chains into `aipass init run` to scaffold a first
+# project (DPLAN-0234: one command does setup + init).
+#
+# Usage: ./setup.sh [--no-init] [--with-init] [--project <dir>] [--no-symlink] [--force-symlink]
+#   --no-init        skip the first-project init chain
+#   --with-init      force the init chain even headless (init runs --non-interactive)
+#   --project <dir>  first-project directory (default: ~/aipass-project)
+#   --no-symlink     do not create/modify global drone/aipass CLI symlinks
+#   --force-symlink  repoint a global symlink even if it points at a different install (#660)
 #

 set -euo pipefail
@@ -27,6 +36,31 @@ case "${OSTYPE:-}" in
        ;;
 esac

+# --- Args ---
+# Mirrors the `aipass install` handoff rules: --no-init wins, --with-init forces,
+# default (auto) chains into init on interactive terminals only — CI/headless skip.
+RUN_INIT="auto"
+INIT_PROJECT=""
+SKIP_SYMLINK="no"
+FORCE_SYMLINK="no"
+PREV_ARG=""
+for arg in "$@"; do
+    if [ "$PREV_ARG" = "--project" ]; then
+        INIT_PROJECT="$arg"
+        PREV_ARG=""
+        continue
+    fi
+    case "$arg" in
+        --no-init)       RUN_INIT="no" ;;
+        --with-init)     RUN_INIT="yes" ;;
+        --no-symlink)    SKIP_SYMLINK="yes" ;;
+        --force-symlink) FORCE_SYMLINK="yes" ;;
+        --project=*)     INIT_PROJECT="${arg#--project=}" ;;
+        --project)       PREV_ARG="--project" ;;
+        *) echo "WARN: unknown argument '$arg' (ignored)" ;;
+    esac
+done
+
 echo "=== AIPass Setup ==="
 echo "Repo root: $SCRIPT_DIR"
 echo ""
@@ -190,8 +224,8 @@ fi
 echo "Upgrading pip ..."
 "$VENV_PYTHON" -m pip install --upgrade pip --quiet

-echo "Installing aipass in editable mode (with dev + memory extras) ..."
-"$VENV_PYTHON" -m pip install -e ".[dev,memory]" --quiet
+echo "Installing aipass in editable mode (with dev + memory extras) — this can take a few minutes while the memory wheels build ..."
+"$VENV_PYTHON" -m pip install -e ".[dev,memory]"

 # --- Detect shadowing drone installs (Windows) ---
 # Issues #317 + #321: system-Python pip or legacy npm aipass-drone can shadow venv drone.exe.
@@ -605,7 +639,7 @@ if [ -f "$SCRIPT_DIR/src/aipass/hooks/apps/handlers/bridges/claude.py" ]; then
    echo "Installing Claude Code hooks ..."
    mkdir -p "$HOME/.claude"

-    "$PYTHON" - "$SCRIPT_DIR" "$CLAUDE_SETTINGS" << 'PYEOF'
+    "$PYTHON" - "$SCRIPT_DIR" "$CLAUDE_SETTINGS" "$IS_WINDOWS" << 'PYEOF'
 import json
 import os
 import sys
@@ -613,11 +647,16 @@ from pathlib import Path

 repo_root = sys.argv[1]
 settings_path = Path(sys.argv[2])
+is_windows = len(sys.argv) > 3 and sys.argv[3] == "1"

 # Bridge entry point — all hooks route through the engine via this bridge.
 # Uses $AIPASS_HOME env var (injected into settings.env below) so the
-# settings file stays relocatable.
-bridge = "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py"
+# settings file stays relocatable. CC on Windows runs hooks via Git Bash
+# (which must exist for setup.sh to have run), so $VAR expansion works —
+# but the venv interpreter lives at Scripts/python.exe there, not bin/python3
+# (@hooks assessment, DPLAN-0234 Strand C).
+venv_python = ".venv/Scripts/python.exe" if is_windows else ".venv/bin/python3"
+bridge = f"$AIPASS_HOME/{venv_python} $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py"

 # Load existing settings or start fresh
 if settings_path.exists():
@@ -629,9 +668,11 @@ else:
 # UserPromptSubmit: 5 separate entries (EventType:hook_name) to avoid output merging
 # PreToolUse, PostToolUse, SubagentStop, Stop, Notification: single aggregate entries
 # PreCompact: 3 hooks x 2 matchers (manual + auto) = 6 entries
-settings["hooks"] = {
+# SessionStart: cadence reset on startup/clear (handler skips resume itself)
+aipass_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"}]},
@@ -662,8 +703,32 @@ settings["hooks"] = {
        {"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}]},
    ],
+    "SessionStart": [
+        {"hooks": [{"type": "command", "command": f"{bridge} SessionStart:cadence_reset", "timeout": 30}]},
+    ],
 }

+# Merge, don't replace (DPLAN-0234 Strand C): refresh every AIPass bridge entry
+# (identified by the bridges/claude.py marker) but preserve any hooks the user
+# wired themselves. Re-runs stay idempotent; custom hooks survive reinstall.
+existing_hooks = settings.get("hooks", {})
+merged_hooks = {}
+for event in set(existing_hooks) | set(aipass_hooks):
+    user_entries = [
+        entry for entry in existing_hooks.get(event, [])
+        if "bridges/claude.py" not in json.dumps(entry)
+    ]
+    merged = aipass_hooks.get(event, []) + user_entries
+    # Never emit an empty hook event. If this event had only stale AIPass bridge
+    # entries (no current aipass_hooks definition AND no user-wired hooks), the
+    # filter above orphans it to [] — a half-wired event that fires nothing,
+    # written silently. Drop the key instead and say so, so the state stays honest.
+    if not merged:
+        print(f"  ! dropped orphaned hook event (no live entries): {event}")
+        continue
+    merged_hooks[event] = merged
+settings["hooks"] = merged_hooks
+
 # Inject AIPASS_HOME into env block so dispatched agents find AIPass
 env_block = settings.get("env", {})
 env_block["AIPASS_HOME"] = repo_root
@@ -739,6 +804,16 @@ else
    echo "Skipping Claude hooks (bridge not found at src/aipass/hooks/apps/handlers/bridges/claude.py)"
 fi

+# --- Install claude() boot shim (attach-if-live / start-in-tmux) ---
+# Ships via the .gitignore negation (#666). Idempotent: the installer checks for
+# its marker before appending to the shell rc, and resolves the venv Python from
+# its own location (POSIX/Windows/fallback). Composes with presence_gate seeding.
+BOOT_SHIM="$SCRIPT_DIR/src/aipass/hooks/tools/install_boot_shim.sh"
+if [ -f "$BOOT_SHIM" ]; then
+    echo "Installing claude() boot shim ..."
+    bash "$BOOT_SHIM" || echo "  boot shim install skipped (non-fatal)"
+fi
+
 # --- Install Claude Code commands (provider level) ---
 # memo.md belongs at provider level — works in all projects.
 # prep.md stays at repo root only — it's AIPass-specific.
@@ -905,8 +980,42 @@ else
 fi

 # --- Create global symlinks for CLI tools (Linux/macOS only) ---
+# #660: never SILENTLY hijack a global 'drone'/'aipass' that points at a
+# DIFFERENT install. safe_symlink skips a different-target link (loud warning)
+# unless --force-symlink; --no-symlink opts out of symlinking entirely.
+SYMLINK_SKIPPED=0
+safe_symlink() {
+    # safe_symlink <src> <dest> [sudo]  ->  0 linked · 1 skipped(diff target) · 2 ln failed
+    local src="$1" dest="$2" use_sudo="${3:-}" existing=""
+    if [ -L "$dest" ]; then
+        existing="$(readlink "$dest" 2>/dev/null)"
+    elif [ -e "$dest" ]; then
+        existing="$dest (real file, not a symlink)"
+    fi
+    if [ -n "$existing" ] && [ "$existing" != "$src" ]; then
+        if [ "$FORCE_SYMLINK" != "yes" ]; then
+            echo "  SKIP $dest — already points at a different install:"
+            echo "       $existing"
+            echo "       Not repointing (would hijack your existing '$(basename "$dest")'); PATH keeps the above."
+            echo "       Re-run 'aipass install' with --force-symlink to repoint here, or --no-symlink to skip quietly."
+            SYMLINK_SKIPPED=$((SYMLINK_SKIPPED + 1))
+            return 1
+        fi
+        echo "  WARNING: repointing $dest"
+        echo "           from $existing"
+        echo "           to   $src   (--force-symlink)"
+    fi
+    if [ -n "$use_sudo" ]; then
+        $use_sudo ln -sf "$src" "$dest" 2>/dev/null && return 0 || return 2
+    fi
+    ln -sf "$src" "$dest" 2>/dev/null && return 0 || return 2
+}
+
 echo ""
-if [ "$IS_WINDOWS" -eq 1 ]; then
+if [ "$SKIP_SYMLINK" = "yes" ]; then
+    echo "Skipping global CLI symlinks (--no-symlink)."
+    echo "  'drone'/'aipass' resolve from $SCRIPT_DIR/.venv/bin — add it to PATH to use them."
+elif [ "$IS_WINDOWS" -eq 1 ]; then
    echo "Windows: drone available via PATH (set above)"
 elif [ "$IS_MACOS" -eq 1 ]; then
    # Mac: symlink into ~/.local/bin (user-writable, no sudo needed).
@@ -918,9 +1027,11 @@ elif [ "$IS_MACOS" -eq 1 ]; then

    for cmd in drone aipass; do
        if [ -f "$VENV_BIN/$cmd" ]; then
-            if ln -sf "$VENV_BIN/$cmd" "$LOCAL_BIN/$cmd"; then
+            rc=0
+            safe_symlink "$VENV_BIN/$cmd" "$LOCAL_BIN/$cmd" || rc=$?
+            if [ "$rc" -eq 0 ]; then
                echo "  $LOCAL_BIN/$cmd -> $VENV_BIN/$cmd"
-            else
+            elif [ "$rc" -eq 2 ]; then
                echo "  WARN: Could not create symlink for $cmd"
                echo "  Manual fix: ln -sf $VENV_BIN/$cmd $LOCAL_BIN/$cmd"
            fi
@@ -933,14 +1044,20 @@ else

    for cmd in drone aipass; do
        if [ -f "$VENV_BIN/$cmd" ]; then
-            if sudo ln -sf "$VENV_BIN/$cmd" "/usr/local/bin/$cmd" 2>/dev/null; then
+            rc=0
+            safe_symlink "$VENV_BIN/$cmd" "/usr/local/bin/$cmd" "sudo" || rc=$?
+            if [ "$rc" -eq 0 ]; then
                echo "  /usr/local/bin/$cmd -> $VENV_BIN/$cmd"
                LINUX_SYMLINK_DIR="/usr/local/bin"
+            elif [ "$rc" -eq 1 ]; then
+                :  # skipped a different install — safe_symlink explained; do NOT fall back
            else
-                # Fallback: user-local bin (no sudo needed)
+                # sudo/ln failed (e.g. no sudo) — fall back to user-local bin
                LOCAL_BIN="$HOME/.local/bin"
                mkdir -p "$LOCAL_BIN"
-                if ln -sf "$VENV_BIN/$cmd" "$LOCAL_BIN/$cmd"; then
+                rc=0
+                safe_symlink "$VENV_BIN/$cmd" "$LOCAL_BIN/$cmd" || rc=$?
+                if [ "$rc" -eq 0 ]; then
                    echo "  /usr/local/bin failed (no sudo) — using $LOCAL_BIN/$cmd instead"
                    LINUX_SYMLINK_DIR="$LOCAL_BIN"
                    # Ensure ~/.local/bin is on PATH
@@ -950,7 +1067,7 @@ else
                        echo "  ~/.local/bin added to PATH in $PROFILE"
                    fi
                    export PATH="$HOME/.local/bin:$PATH"
-                else
+                elif [ "$rc" -eq 2 ]; then
                    echo "  WARN: Could not create symlink for $cmd"
                    echo "  Manual fix: ln -sf $VENV_BIN/$cmd $LOCAL_BIN/$cmd"
                fi
@@ -959,6 +1076,12 @@ else
    done
 fi

+if [ "$SYMLINK_SKIPPED" -gt 0 ]; then
+    echo ""
+    echo "  NOTE: $SYMLINK_SKIPPED global symlink(s) left untouched (pointed at a different install)."
+    echo "        Your existing 'drone'/'aipass' still work. Use --force-symlink to repoint them here."
+fi
+
 # --- Result ---
 echo ""
 if [ "$FAIL" -eq 0 ]; then
@@ -981,6 +1104,77 @@ if [ "$FAIL" -eq 0 ]; then
    echo "  Claude Code: hooks installed to ~/.claude/settings.json"
    command -v codex &>/dev/null && echo "  Codex CLI:   hooks at .codex/hooks.json + config at ~/.codex/config.toml"
    echo ""
+
+    # --- Chain into first-project init (DPLAN-0234: one command does setup + init) ---
+    # `aipass init` refuses to run inside the engine tree, so it always targets a
+    # sibling directory — never the repo itself. Decision mirrors install.py:
+    # --no-init wins, --with-init forces (headless chains --non-interactive),
+    # default = interactive terminals only (CI and piped shells skip).
+    AIPASS_BIN=""
+    if [ "$IS_WINDOWS" -eq 1 ] && [ -f "$SCRIPT_DIR/.venv/Scripts/aipass.exe" ]; then
+        AIPASS_BIN="$SCRIPT_DIR/.venv/Scripts/aipass.exe"
+    elif [ "$IS_WINDOWS" -eq 1 ] && [ -f "$SCRIPT_DIR/.venv/Scripts/aipass" ]; then
+        AIPASS_BIN="$SCRIPT_DIR/.venv/Scripts/aipass"
+    elif [ -f "$SCRIPT_DIR/.venv/bin/aipass" ]; then
+        AIPASS_BIN="$SCRIPT_DIR/.venv/bin/aipass"
+    elif command -v aipass &>/dev/null; then
+        AIPASS_BIN="$(command -v aipass)"
+    fi
+
+    LAUNCH_INIT=0
+    INIT_HEADLESS=0
+    if [ "$RUN_INIT" = "no" ]; then
+        echo "Skipping first-project init (--no-init). Run 'aipass init run' in a fresh directory when ready."
+    elif [ "$RUN_INIT" = "yes" ]; then
+        LAUNCH_INIT=1
+        if [ ! -t 0 ]; then
+            INIT_HEADLESS=1
+        fi
+    elif [ -t 0 ] && [ -z "${CI:-}" ]; then
+        LAUNCH_INIT=1
+    else
+        echo "Non-interactive shell — skipping first-project init. Run 'aipass init run' in a fresh directory when ready."
+    fi
+
+    if [ "$LAUNCH_INIT" -eq 1 ]; then
+        if [ -z "$AIPASS_BIN" ]; then
+            echo "WARN: aipass binary not found — open a new terminal and run 'aipass init run' in a fresh directory."
+        else
+            DEFAULT_PROJECT_DIR="$HOME/aipass-project"
+            PROJECT_DIR="$INIT_PROJECT"
+            if [ -z "$PROJECT_DIR" ] && [ "$INIT_HEADLESS" -eq 0 ] && [ -t 0 ]; then
+                echo "AIPass projects live in their own directory, never inside the engine repo."
+                read -r -p "Set up your first project now? [Y/n]: " INIT_REPLY
+                case "$INIT_REPLY" in
+                    [nN]*)
+                        PROJECT_DIR="-"
+                        echo "  Skipped. Run 'aipass init run' in a fresh directory when ready."
+                        ;;
+                    *)
+                        read -r -p "  Project directory [$DEFAULT_PROJECT_DIR]: " INIT_INPUT
+                        PROJECT_DIR="${INIT_INPUT:-$DEFAULT_PROJECT_DIR}"
+                        ;;
+                esac
+            elif [ -z "$PROJECT_DIR" ]; then
+                PROJECT_DIR="$DEFAULT_PROJECT_DIR"
+            fi
+
+            if [ "$PROJECT_DIR" != "-" ]; then
+                mkdir -p "$PROJECT_DIR"
+                INIT_CMD=("$AIPASS_BIN" init run)
+                if [ "$INIT_HEADLESS" -eq 1 ]; then
+                    INIT_CMD+=(--non-interactive)
+                fi
+                echo ""
+                echo "Launching guided setup in $PROJECT_DIR ..."
+                if (cd "$PROJECT_DIR" && "${INIT_CMD[@]}"); then
+                    echo "First project initialized at $PROJECT_DIR"
+                else
+                    echo "Init didn't complete — run 'aipass init run' in $PROJECT_DIR when ready."
+                fi
+            fi
+        fi
+    fi
 else
    echo "=== Setup finished with errors ==="
    echo "The venv was created and the package was installed, but one or more"
@@ -1,7 +1,6 @@
 """AIPass — Multi-agent orchestration framework.

-pip install aipass
-https://github.com/AIOSAI/AIPass
+git clone + ./setup.sh — https://github.com/AIOSAI/AIPass
 """

-__version__ = "2.5.3"
+__version__ = "2.7.1"
@@ -23,7 +23,7 @@
    {
      "file": "apps/handlers/dispatch/daemon.py",
      "standard": "deep_nesting",
-      "reason": "3 functions: check_inbox_for_dispatch() depth 4 (priority scanning with business logic), run_daemon() depth 4 (main daemon loop), _check_lock() depth 4 (lock validation + PID liveness + cleanup)"
+      "reason": "run_daemon() depth 5 (main daemon loop with retry + signal handling)"
    },
    {
      "file": "apps/handlers/dispatch/wake.py",
@@ -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",
@@ -120,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",
@@ -200,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",
@@ -62,19 +62,22 @@ The `dispatch` command sends an email and wakes the target branch in one step. D
 ### Wake Pipeline

 1. `dispatch.py` orchestrates: send email via `send_to_single()`, then wake via `wake_branch()`
-2. `wake.py` resolves the branch from the registry, finds the `claude` binary, spawns a subprocess
+2. `wake.py` resolves the branch from the registry, checks `citizen_class` (managers are mail-only — wake skips), finds the `claude` binary, spawns a subprocess
 3. `dispatch_monitor.py` wraps the claude process with safety features:
   - **Startup health check** — monitors JSONL session files for 90s, kills if no activity
   - **Auto-retry** — 3 strikes: attempt 1+2 resume, attempt 3 fresh (new session)
   - **Bounce email** — on final failure, sends error report back to sender
   - **Lock cleanup** — removes `.dispatch.lock` when agent exits
-4. After wake, `_spawn_watchdog()` auto-launches `drone @devpulse watchdog agent @target` as a detached background process
+   - **Wake-back** — on agent exit, wakes the original sender so they can process the result. Wake-back sessions carry an empty sender, so chains terminate at the original dispatcher

 ### Safety Limits

 - PID-based locking prevents concurrent agents per branch (`.dispatch.lock`)
 - Max turns per wake, max dispatches per branch per day
 - `WAKE_BLOCKLIST` protects `@devpulse` from cross-branch manual wakes
+- **Manager structural block** — branches with `citizen_class: "manager"` in their passport (e.g. `@devpulse`) are unwakeable on all wake paths. Mail delivers, wake skips
+- **Self-wake guard** — if sender equals target, wake-back is skipped (prevents self-loops)
+- **Chain termination** — wake-back sessions carry an empty sender, so the chain always stops at the original dispatcher
 - `dispatch_monitor.py` strips `AIPASS_CALLER_*` env vars to prevent parent context leaking into agent identity
 - `AIPASS_BRANCH_NAME` env var set in spawn_env for CWD-independent identity

@@ -14,13 +14,19 @@ Main handles routing, modules implement functionality.
 """

 # Standard library imports
+import os
 import sys
 import importlib
-import argparse
 import signal
 from pathlib import Path
 from typing import Any, List

+# AIPass infrastructure imports
+from aipass.prax.apps.modules.logger import system_logger as logger
+
+# CLI services for display
+from aipass.cli.apps.modules import console, error
+
 # Handle broken pipe gracefully (e.g. output piped to head)
 # SIGPIPE does not exist on Windows
 if hasattr(signal, "SIGPIPE"):
@@ -29,11 +35,12 @@ if hasattr(signal, "SIGPIPE"):
 # Dashboard integration (optional, provided by prax)
 _UPDATE_SECTION = None  # type: ignore

-# AIPass infrastructure imports
-from aipass.prax.apps.modules.logger import system_logger as logger
-
-# CLI services for display
-from aipass.cli.apps.modules import console, error
+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")

 # =============================================================================
 # CONSTANTS & CONFIG
@@ -51,52 +58,47 @@ MODULES_DIR = MODULE_ROOT / "modules"


 def print_help():
-    """Print drone-compliant help output"""
-    parser = argparse.ArgumentParser(
-        description="AI_MAIL Branch Operations - Email system for branch communication",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-COMMANDS:
-  dispatch  - Send dispatch email + wake target (one step)
-  email     - Send email to a branch
-  send      - Send email (alias for email)
-  inbox     - List emails (new + opened)
-  view      - View email content (marks as opened)
-  reply     - Reply to email (closes + archives)
-  close     - Close email(s) without reply (archives)
-  sent      - View sent messages
-  contacts  - Manage contacts
-EMAIL LIFECYCLE (v2):
-  new → opened → closed
-  - new: Just arrived, never viewed
-  - opened: You've viewed it, not yet resolved
-  - closed: Resolved (replied or dismissed), auto-archived
+    """Print drone-compliant help output with Rich markup"""
+    console.print()
+    console.print("[bold cyan]AI_MAIL — Email system for branch communication[/bold cyan]")
+    console.print()

-USAGE:
-  drone @ai_mail <command> [args]
-  drone @ai_mail --help
+    console.print("[yellow]COMMANDS:[/yellow]")
+    console.print("  [cyan]dispatch[/cyan]  [dim]Send dispatch email + wake target (one step)[/dim]")
+    console.print("  [cyan]email[/cyan]     [dim]Send email to a branch[/dim]")
+    console.print("  [cyan]send[/cyan]      [dim]Send email (alias for email)[/dim]")
+    console.print("  [cyan]inbox[/cyan]     [dim]List emails (new + opened)[/dim]")
+    console.print("  [cyan]view[/cyan]      [dim]View email content (marks as opened)[/dim]")
+    console.print("  [cyan]reply[/cyan]     [dim]Reply to email (closes + archives)[/dim]")
+    console.print("  [cyan]close[/cyan]     [dim]Close email(s) without reply (archives)[/dim]")
+    console.print("  [cyan]sent[/cyan]      [dim]View sent messages[/dim]")
+    console.print("  [cyan]contacts[/cyan]  [dim]Manage contacts[/dim]")
+    console.print()

-EXAMPLES:
-  # Dispatch (send + wake in one command)
-  drone @ai_mail dispatch @branch "Subject" "Body"
-  drone @ai_mail dispatch @branch "Subject" "Body" --fresh
+    console.print("[yellow]EMAIL LIFECYCLE (v2):[/yellow]")
+    console.print("  new → opened → closed")
+    console.print("  [dim]new: Just arrived, never viewed[/dim]")
+    console.print("  [dim]opened: You've viewed it, not yet resolved[/dim]")
+    console.print("  [dim]closed: Resolved (replied or dismissed), auto-archived[/dim]")
+    console.print()

-  # Send mail (no wake)
-  drone @ai_mail email @seedgo "Subject" "Msg"  # Send to branch
-  drone @ai_mail email @all "Subject" "Msg"   # Broadcast to all
+    console.print("[yellow]USAGE:[/yellow]")
+    console.print("  [cyan]drone @ai_mail[/cyan] <command> [args]")
+    console.print("  [cyan]drone @ai_mail --help[/cyan]")
+    console.print()

-  # Check mail
-  drone @ai_mail inbox                        # List all emails
-  drone @ai_mail view abc123                  # View email (marks as opened)
-
-  # Resolve emails
-  drone @ai_mail reply abc123 "Thanks!"       # Reply + close + archive
-  drone @ai_mail close abc123                 # Close single email
-  drone @ai_mail close abc123 def456 ghi789   # Close multiple emails
-  drone @ai_mail close all                    # Close ALL emails
-        """,
-    )
-    console.print(parser.format_help())
+    console.print("[yellow]EXAMPLES:[/yellow]")
+    console.print('  [cyan]drone @ai_mail dispatch @branch "Subject" "Body"[/cyan]')
+    console.print('  [cyan]drone @ai_mail dispatch @branch "Subject" "Body" --fresh[/cyan]')
+    console.print('  [cyan]drone @ai_mail email @seedgo "Subject" "Msg"[/cyan]  [dim]Send to branch[/dim]')
+    console.print('  [cyan]drone @ai_mail email @all "Subject" "Msg"[/cyan]     [dim]Broadcast to all[/dim]')
+    console.print("  [cyan]drone @ai_mail inbox[/cyan]                          [dim]List all emails[/dim]")
+    console.print("  [cyan]drone @ai_mail view abc123[/cyan]                    [dim]View email[/dim]")
+    console.print('  [cyan]drone @ai_mail reply abc123 "Thanks!"[/cyan]         [dim]Reply + close + archive[/dim]')
+    console.print("  [cyan]drone @ai_mail close abc123[/cyan]                   [dim]Close single email[/dim]")
+    console.print("  [cyan]drone @ai_mail close abc123 def456 ghi789[/cyan]     [dim]Close multiple[/dim]")
+    console.print("  [cyan]drone @ai_mail close all[/cyan]                      [dim]Close ALL emails[/dim]")
+    console.print()


 # =============================================================================
@@ -241,6 +243,13 @@ def main():
            error("No modules found")
            return 1

+        if remaining_args and remaining_args[0] in ["--help", "-h"]:
+            for module in modules:
+                if module.handle_command(command, ["--help"]):
+                    return 0
+            print_help()
+            return 0
+
        # Route command
        if route_command(command, remaining_args, modules):
            return 0
@@ -19,6 +19,7 @@ Architecture:
 """

 # CRITICAL: Use importlib to bypass local json/ directory and get stdlib json
+import os
 import sys
 import importlib.util

@@ -32,13 +33,20 @@ stdlib_json = importlib.util.module_from_spec(spec)
 spec.loader.exec_module(stdlib_json)
 sys.path = _saved_path

-from pathlib import Path
-from datetime import datetime
-from typing import Dict, Any, List, Tuple
+from pathlib import Path  # noqa: E402
+from datetime import datetime  # noqa: E402
+from typing import Dict, Any, List, Tuple  # noqa: E402

-from aipass.prax.apps.modules.logger import system_logger as logger
-from aipass.ai_mail.apps.handlers.json import json_handler
-from aipass.ai_mail.apps.handlers.paths import find_repo_root
+from aipass.prax.apps.modules.logger import system_logger as logger  # noqa: E402
+from aipass.ai_mail.apps.handlers.json import json_handler  # noqa: E402
+from aipass.ai_mail.apps.handlers.paths import find_repo_root  # noqa: E402
+
+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")


 # =============================================================================
@@ -341,5 +349,7 @@ if __name__ == "__main__":
        console.print()

    except Exception as e:
-        console.print(f"[red]Error:[/red] {e}")
+        from aipass.cli.apps.modules import error as cli_error
+
+        cli_error(f"Error: {e}")
        raise
@@ -33,6 +33,7 @@ from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.dispatch.status import log_dispatch
 from aipass.ai_mail.apps.handlers.paths import find_repo_root
+from aipass.ai_mail.apps.handlers.dispatch.test_token import scan_and_ack_test_emails


 # Infrastructure paths
@@ -49,9 +50,6 @@ BRANCH_REGISTRY = _REPO_ROOT / "AIPASS_REGISTRY.json"
 # Graceful shutdown
 SHUTDOWN = False

-# AIPASS-TEST token handling extracted to test_token.py
-from aipass.ai_mail.apps.handlers.dispatch.test_token import scan_and_ack_test_emails
-

 def _handle_signal(signum, _frame):
    """Handle shutdown signals for graceful daemon stop."""
@@ -88,6 +86,56 @@ def _write_json(filepath: Path, data: Dict[str, Any]) -> bool:
        return False


+def _pid_alive_windows(pid: int) -> bool:
+    """Windows-safe liveness check via OpenProcess + GetExitCodeProcess."""
+    import ctypes
+    from ctypes import wintypes
+
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    STILL_ACTIVE = 259
+
+    kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.GetExitCodeProcess.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+    kernel32.GetExitCodeProcess.restype = wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+
+    handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+    if not handle:
+        return False
+    try:
+        exit_code = wintypes.DWORD()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+            return False
+        return exit_code.value == STILL_ACTIVE
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def _pid_alive(pid: int) -> bool:
+    """Return True if the process is alive."""
+    if sys.platform == "win32":
+        try:
+            return _pid_alive_windows(pid)
+        except Exception as exc:
+            logger.info("[daemon] PID %s Windows check failed (assuming alive): %s", pid, exc)
+            return True
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError as exc:
+        logger.info("[daemon] PID %s not found: %s", pid, exc)
+        return False
+    except PermissionError as exc:
+        logger.info("[daemon] PID %s permission denied (alive): %s", pid, exc)
+        return True
+    except OSError as exc:
+        logger.info("[daemon] PID %s os.kill error (assuming dead): %s", pid, exc)
+        return False
+    return True
+
+
 def _check_lock(branch_path: Path) -> Optional[Dict[str, Any]]:
    """Check if branch has an active dispatch lock. Returns lock data or None."""
    lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
@@ -98,14 +146,9 @@ def _check_lock(branch_path: Path) -> Optional[Dict[str, Any]]:
            data = json.load(f)
        pid = data.get("pid")
        if pid is not None:
-            try:
-                os.kill(pid, 0)
-                return data  # Process alive, lock valid
-            except ProcessLookupError:
-                logger.info("Lock PID %s dead — stale lock cleanup needed", pid)
-            except PermissionError as e:
-                logger.warning("[daemon] Lock PID %s permission error: %s", pid, e)
-                return data  # Process exists, can't signal
+            if _pid_alive(pid):
+                return data
+            logger.info("Lock PID %s dead — stale lock cleanup needed", pid)
        # Stale lock — check age (10 min timeout)
        ts = data.get("timestamp", "")
        if ts:
@@ -216,15 +259,10 @@ def _write_pid_file() -> bool:
    # PID file exists — check if the owning process is alive
    try:
        old_pid = int(DAEMON_PID_FILE.read_text().strip())
-        try:
-            os.kill(old_pid, 0)
-            logger.info(f"Another daemon already running (PID {old_pid}). Exiting.")
-            return False
-        except ProcessLookupError:
-            logger.info(f"Removing stale PID file (PID {old_pid} is dead)")
-        except PermissionError:
-            logger.info(f"Another daemon already running (PID {old_pid}, permission denied). Exiting.")
+        if _pid_alive(old_pid):
+            logger.info("Another daemon already running (PID %s). Exiting.", old_pid)
            return False
+        logger.info("Removing stale PID file (PID %s is dead)", old_pid)
    except (ValueError, OSError):
        logger.info("Corrupt PID file — removing")

@@ -410,14 +448,19 @@ def spawn_agent(
        logger.info(f"Lock acquisition failed for {branch_email}: {lock_msg}")
        return False

+    _detach_kwargs: dict = {}
+    if sys.platform == "win32":
+        _detach_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        _detach_kwargs["start_new_session"] = True
    try:
        process = subprocess.Popen(
            monitor_cmd,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
-            start_new_session=True,
            cwd=str(branch_path),
            env=spawn_env,
+            **_detach_kwargs,
        )

        monitor_pid = process.pid
@@ -471,18 +514,74 @@ def is_protected_branch(branch_email: str) -> bool:
    return branch_email == "@devpulse"


-def _read_session_type(pid_str: str) -> str:
-    """Read AIPASS_SESSION_TYPE from /proc/{pid}/environ. Returns 'interactive' if unset."""
-    if sys.platform != "linux":
-        return "interactive"
+def _get_pid_cwd(pid_str: str) -> Optional[str]:
+    """Get the cwd of a process. Cross-platform: Linux /proc, macOS lsof."""
+    if sys.platform == "linux":
+        try:
+            return os.readlink(f"/proc/{pid_str}/cwd")
+        except (OSError, PermissionError):
+            logger.info("[daemon] Cannot read cwd for PID %s", pid_str)
+            return None
+    if sys.platform == "darwin":
+        return _get_pid_cwd_darwin(pid_str)
+    logger.info("[daemon] Cannot determine cwd for PID %s on %s", pid_str, sys.platform)
+    return None
+
+
+def _get_pid_cwd_darwin(pid_str: str) -> Optional[str]:
+    """macOS: get process cwd via lsof."""
    try:
-        with open(f"/proc/{pid_str}/environ", "rb") as f:
-            data = f.read()
-        for entry in data.split(b"\0"):
-            if entry.startswith(b"AIPASS_SESSION_TYPE="):
-                return entry.split(b"=", 1)[1].decode("utf-8")
-    except (OSError, PermissionError):
-        logger.info("Cannot read session type for PID %s", pid_str)
+        result = subprocess.run(
+            ["lsof", "-a", "-p", pid_str, "-d", "cwd", "-Fn"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (subprocess.SubprocessError, OSError):
+        logger.info("[daemon] Cannot read cwd for PID %s on macOS", pid_str)
+        return None
+    if result.returncode != 0:
+        return None
+    for line in result.stdout.strip().split("\n"):
+        if line.startswith("n/"):
+            return line[1:]
+    return None
+
+
+def _read_session_type(pid_str: str) -> str:
+    """Read AIPASS_SESSION_TYPE from process environment. Returns 'interactive' if unset."""
+    if sys.platform == "linux":
+        try:
+            with open(f"/proc/{pid_str}/environ", "rb") as f:
+                data = f.read()
+            for entry in data.split(b"\0"):
+                if entry.startswith(b"AIPASS_SESSION_TYPE="):
+                    return entry.split(b"=", 1)[1].decode("utf-8")
+        except (OSError, PermissionError):
+            logger.info("[daemon] Cannot read session type for PID %s", pid_str)
+        return "interactive"
+    if sys.platform == "darwin":
+        return _read_session_type_darwin(pid_str)
+    return "interactive"
+
+
+def _read_session_type_darwin(pid_str: str) -> str:
+    """macOS: read AIPASS_SESSION_TYPE from ps environment output."""
+    try:
+        result = subprocess.run(
+            ["ps", "-p", pid_str, "-wwE", "-o", "command="],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (subprocess.SubprocessError, OSError):
+        logger.info("[daemon] Cannot read session type for PID %s on macOS", pid_str)
+        return "interactive"
+    if result.returncode != 0:
+        return "interactive"
+    for token in result.stdout.split():
+        if token.startswith("AIPASS_SESSION_TYPE="):
+            return token.split("=", 1)[1]
    return "interactive"


@@ -491,35 +590,25 @@ _NON_BLOCKING_SESSION_TYPES = {"dispatched", "daemon"}


 def _is_branch_occupied(branch_path: Path) -> bool:
-    """
-    Check if an interactive Claude session is running in this branch.
-
-    Only interactive sessions block dispatch. Telegram, dispatched, and daemon
-    sessions are idle/background and should not prevent new agent spawns.
-    """
-    resolved = branch_path.resolve()
+    """Check if an interactive Claude session is running in this branch."""
+    resolved = str(branch_path.resolve())
    try:
        result = subprocess.run(["pgrep", "-x", "claude"], capture_output=True, text=True, timeout=5)
        if result.returncode != 0:
            return False
-
        for pid_str in result.stdout.strip().split("\n"):
            pid_str = pid_str.strip()
            if not pid_str:
                continue
-            try:
-                if sys.platform != "linux":
-                    continue
-                cwd = os.readlink(f"/proc/{pid_str}/cwd")
-                if Path(cwd).resolve() == resolved:
-                    session_type = _read_session_type(pid_str)
-                    if session_type not in _NON_BLOCKING_SESSION_TYPES:
-                        return True
-            except (OSError, PermissionError, ValueError):
-                logger.info("Cannot read cwd for PID %s", pid_str)
+            cwd = _get_pid_cwd(pid_str)
+            if cwd is None:
                continue
+            if str(Path(cwd).resolve()) == resolved:
+                session_type = _read_session_type(pid_str)
+                if session_type not in _NON_BLOCKING_SESSION_TYPES:
+                    return True
    except Exception:
-        logger.info("Failed to check branch occupancy for %s", branch_path)
+        logger.info("[daemon] Failed to check branch occupancy for %s", branch_path)
    return False


@@ -80,6 +80,80 @@ def _connect_broker(repo_root: Path, branch_name: str) -> socket.socket:
    return create_identified_connection(socket_path, secret_path, branch_name)


+MAX_WAKE_DEPTH = 3
+
+
+def _wake_sender(sender: str, branch_email: str, exit_code: int, lock_file: str) -> str:
+    """Wake the dispatcher back after target completion.
+
+    Any citizen sender gets woken back (same availability checks as
+    normal wake — interactive session, active lock, depth cap).
+
+    Returns a result tag for the dispatch_wake.log:
+      success, blocked_occupied, blocked_locked, blocked_depth,
+      skipped_sender, skipped_self, failed
+    """
+    if not sender or not sender.strip():
+        logger.info("[monitor] Wake-back skipped — no sender")
+        return "skipped_sender"
+
+    normalized_sender = f"@{sender.lstrip('@').lower()}"
+    normalized_target = f"@{branch_email.lstrip('@').lower()}"
+    if normalized_sender == normalized_target:
+        logger.info("[monitor] Wake-back skipped — sender %s is the completed agent (self-wake)", sender)
+        return "skipped_self"
+
+    depth = int(os.environ.get("AIPASS_WAKE_DEPTH", "0"))
+    if depth >= MAX_WAKE_DEPTH:
+        logger.warning("[monitor] Wake-back skipped — depth %d >= max %d", depth, MAX_WAKE_DEPTH)
+        return "blocked_depth"
+
+    try:
+        from aipass.ai_mail.apps.handlers.dispatch.wake import wake_branch
+
+        os.environ["AIPASS_WAKE_DEPTH"] = str(depth + 1)
+        wake_status, success = wake_branch(sender, auto=True, sender="")
+
+        if success:
+            logger.info("[monitor] Wake-back: %s woken after %s completed (exit %d)", sender, branch_email, exit_code)
+            return "success"
+
+        summary = wake_status.summary
+        lower = summary.lower()
+        if "interactive" in lower or "occupancy" in lower or "occupied" in lower:
+            logger.info("[monitor] Wake-back blocked — sender %s has interactive session: %s", sender, summary)
+            return "blocked_occupied"
+        if "active agent" in lower or "lock" in lower:
+            logger.info("[monitor] Wake-back blocked — sender %s has active lock: %s", sender, summary)
+            return "blocked_locked"
+
+        logger.info("[monitor] Wake-back: %s not woken — %s", sender, summary)
+        return "failed"
+    except Exception as e:
+        logger.warning("[monitor] Wake-back failed for %s: %s", sender, e)
+        return "failed"
+
+
+def _log_wake_result(branch_email: str, sender: str, exit_code: int, result: str, lock_file: str):
+    """Append a wake-back result line to dispatch_wake.log under target's logs/."""
+    lock_path = Path(lock_file).resolve()
+    logs_dir = lock_path.parent.parent / "logs"
+    log_file = logs_dir / "dispatch_wake.log"
+    try:
+        logs_dir.mkdir(parents=True, exist_ok=True)
+        line = (
+            f"{time.strftime('%Y-%m-%dT%H:%M:%S')}"
+            f" target={branch_email}"
+            f" sender={sender}"
+            f" exit_code={exit_code}"
+            f" wake_result={result}\n"
+        )
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(line)
+    except OSError as e:
+        logger.info("[monitor] Failed to write dispatch_wake.log: %s", e)
+
+
 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"
@@ -134,16 +208,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:
@@ -234,6 +319,7 @@ def _run_with_startup_check(

    try:
        popen_kwargs = {
+            "stdin": subprocess.DEVNULL,
            "stdout": stdout_fh if stdout_fh is not None else subprocess.DEVNULL,
            "stderr": stderr_fh,
            "cwd": cwd,
@@ -316,6 +402,18 @@ def main():

    json_handler.log_operation("dispatch_monitor_start", {"branch": branch_email, "sender": sender})

+    # Self-register PID in lock file — the parent may have written its own
+    # PID during pre-spawn lock acquisition (DPLAN-0155), and under
+    # systemd-run the parent PID belongs to the caller, not the monitor.
+    try:
+        lock_path_obj = Path(lock_file)
+        if lock_path_obj.exists():
+            ld = json.loads(lock_path_obj.read_text(encoding="utf-8"))
+            ld["pid"] = os.getpid()
+            lock_path_obj.write_text(json.dumps(ld, indent=2), encoding="utf-8")
+    except (json.JSONDecodeError, OSError):
+        logger.info("[monitor] Could not self-register PID in lock file %s", lock_file)
+
    # Open stderr log for claude output (rotate if > 500KB)
    stderr_fh = None
    try:
@@ -527,16 +625,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)

@@ -563,6 +659,10 @@ def main():
    except Exception:
        logger.info("[monitor] Desktop notification unavailable")

+    # ─── Wake-back: wake the dispatcher ────────────────────
+    wake_result = _wake_sender(sender, branch_email, exit_code, lock_file)
+    _log_wake_result(branch_email, sender, exit_code, wake_result, lock_file)
+
    sys.exit(0 if exit_code == 0 else 1)


@@ -14,13 +14,22 @@ without triggering dispatch. Extracted from daemon.py to keep
 the daemon under the 700-line architecture threshold.
 """

+import os
 import subprocess
+import sys
 from pathlib import Path
 from typing import Any, Dict

 from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 TEST_TOKEN = "[AIPASS-TEST — do not update memories, do not execute, reply 'ack' only]"


@@ -141,6 +141,34 @@ def _read_json(filepath: Path) -> Optional[dict]:
        return None


+def _pid_alive_windows(pid: int) -> bool:
+    """Windows-safe liveness check via OpenProcess + GetExitCodeProcess."""
+    import ctypes
+    from ctypes import wintypes
+
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    STILL_ACTIVE = 259
+
+    kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.GetExitCodeProcess.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+    kernel32.GetExitCodeProcess.restype = wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+
+    handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+    if not handle:
+        return False
+    try:
+        exit_code = wintypes.DWORD()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+            return False
+        return exit_code.value == STILL_ACTIVE
+    finally:
+        kernel32.CloseHandle(handle)
+
+
 def _check_lock(branch_path: Path) -> Optional[dict]:
    """Check if branch has an active dispatch lock. Returns lock data or None."""
    lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
@@ -151,14 +179,9 @@ def _check_lock(branch_path: Path) -> Optional[dict]:
            data = json.load(f)
        pid = data.get("pid")
        if pid is not None:
-            try:
-                os.kill(pid, 0)
-                return data  # Process alive, lock valid
-            except ProcessLookupError:
-                logger.info("[wake] Lock PID %s dead — cleaning stale lock", pid)
-            except PermissionError as e:
-                logger.warning("[wake] Lock PID %s permission error: %s", pid, e)
-                return data  # Process exists but can't signal — treat as active
+            if _check_pid_alive(pid):
+                return data
+            logger.info("[wake] Lock PID %s dead — cleaning stale lock", pid)
        # Stale lock — check age (10 min timeout)
        ts = data.get("timestamp", "")
        if ts:
@@ -210,18 +233,74 @@ def _load_config() -> dict:
    return config


-def _read_session_type(pid_str: str) -> str:
-    """Read AIPASS_SESSION_TYPE from /proc/{pid}/environ. Returns 'interactive' if unset."""
-    if sys.platform != "linux":
-        return "interactive"
+def _get_pid_cwd(pid_str: str) -> Optional[str]:
+    """Get the cwd of a process. Cross-platform: Linux /proc, macOS lsof."""
+    if sys.platform == "linux":
+        try:
+            return os.readlink(f"/proc/{pid_str}/cwd")
+        except (OSError, PermissionError):
+            logger.info("[wake] Cannot read cwd for PID %s", pid_str)
+            return None
+    if sys.platform == "darwin":
+        return _get_pid_cwd_darwin(pid_str)
+    logger.info("[wake] Cannot determine cwd for PID %s on %s", pid_str, sys.platform)
+    return None
+
+
+def _get_pid_cwd_darwin(pid_str: str) -> Optional[str]:
+    """macOS: get process cwd via lsof."""
    try:
-        with open(f"/proc/{pid_str}/environ", "rb") as f:
-            data = f.read()
-        for entry in data.split(b"\0"):
-            if entry.startswith(b"AIPASS_SESSION_TYPE="):
-                return entry.split(b"=", 1)[1].decode("utf-8")
-    except (OSError, PermissionError):
-        logger.info("[wake] Cannot read session type for PID %s", pid_str)
+        result = subprocess.run(
+            ["lsof", "-a", "-p", pid_str, "-d", "cwd", "-Fn"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (subprocess.SubprocessError, OSError):
+        logger.info("[wake] Cannot read cwd for PID %s on macOS", pid_str)
+        return None
+    if result.returncode != 0:
+        return None
+    for line in result.stdout.strip().split("\n"):
+        if line.startswith("n/"):
+            return line[1:]
+    return None
+
+
+def _read_session_type(pid_str: str) -> str:
+    """Read AIPASS_SESSION_TYPE from process environment. Returns 'interactive' if unset."""
+    if sys.platform == "linux":
+        try:
+            with open(f"/proc/{pid_str}/environ", "rb") as f:
+                data = f.read()
+            for entry in data.split(b"\0"):
+                if entry.startswith(b"AIPASS_SESSION_TYPE="):
+                    return entry.split(b"=", 1)[1].decode("utf-8")
+        except (OSError, PermissionError):
+            logger.info("[wake] Cannot read session type for PID %s", pid_str)
+        return "interactive"
+    if sys.platform == "darwin":
+        return _read_session_type_darwin(pid_str)
+    return "interactive"
+
+
+def _read_session_type_darwin(pid_str: str) -> str:
+    """macOS: read AIPASS_SESSION_TYPE from ps environment output."""
+    try:
+        result = subprocess.run(
+            ["ps", "-p", pid_str, "-wwE", "-o", "command="],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (subprocess.SubprocessError, OSError):
+        logger.info("[wake] Cannot read session type for PID %s on macOS", pid_str)
+        return "interactive"
+    if result.returncode != 0:
+        return "interactive"
+    for token in result.stdout.split():
+        if token.startswith("AIPASS_SESSION_TYPE="):
+            return token.split("=", 1)[1]
    return "interactive"


@@ -240,17 +319,13 @@ def _is_branch_occupied(branch_path: Path) -> bool:
            pid_str = pid_str.strip()
            if not pid_str:
                continue
-            try:
-                if sys.platform != "linux":
-                    continue
-                cwd = os.readlink(f"/proc/{pid_str}/cwd")
-                if str(Path(cwd).resolve()) == resolved:
-                    session_type = _read_session_type(pid_str)
-                    if session_type not in _NON_BLOCKING_SESSION_TYPES:
-                        return True
-            except (OSError, PermissionError, ValueError):
-                logger.info("[wake] Cannot read cwd for PID %s", pid_str)
+            cwd = _get_pid_cwd(pid_str)
+            if cwd is None:
                continue
+            if str(Path(cwd).resolve()) == resolved:
+                session_type = _read_session_type(pid_str)
+                if session_type not in _NON_BLOCKING_SESSION_TYPES:
+                    return True
    except (subprocess.SubprocessError, OSError):
        logger.info("[wake] Failed to check branch occupancy")
    return False
@@ -273,21 +348,110 @@ def _clean_zombies() -> int:

 def _check_pid_alive(pid: int) -> bool:
    """Check if a process is alive (not zombie)."""
+    if sys.platform == "win32":
+        try:
+            return _pid_alive_windows(pid)
+        except Exception as exc:
+            logger.info("[wake] PID %s Windows check failed (assuming alive): %s", pid, exc)
+            return True
    try:
        os.kill(pid, 0)
-        # Also verify not zombie via /proc (Linux only)
-        if sys.platform == "linux":
-            with open(f"/proc/{pid}/status", "r") as f:
-                for line in f:
-                    if line.startswith("State:"):
-                        return "Z" not in line
-        return True
-    except (ProcessLookupError, FileNotFoundError) as e:
-        logger.warning("[wake] PID %s not found: %s", pid, e)
+    except ProcessLookupError as exc:
+        logger.warning("[wake] PID %s not found: %s", pid, exc)
        return False
-    except PermissionError as e:
-        logger.warning("[wake] PID %s permission denied: %s", pid, e)
-        return True  # Exists but can't check — assume alive
+    except PermissionError as exc:
+        logger.warning("[wake] PID %s permission denied: %s", pid, exc)
+        return True
+    except OSError as exc:
+        logger.warning("[wake] PID %s os.kill error (assuming dead): %s", pid, exc)
+        return False
+    if sys.platform == "linux" and _is_zombie_linux(pid):
+        return False
+    return True
+
+
+def _is_zombie_linux(pid: int) -> bool:
+    """Return True if PID is a zombie (Linux /proc/status check)."""
+    try:
+        with open(f"/proc/{pid}/status", "r") as f:
+            for line in f:
+                if line.startswith("State:"):
+                    return "Z" in line
+    except FileNotFoundError as exc:
+        logger.warning("[wake] PID %s /proc not found: %s", pid, exc)
+    return False
+
+
+def _spawn_in_systemd_scope(monitor_cmd, branch_path, spawn_env, branch_email, lock_file_path, custom_message, status):
+    """Spawn monitor in its own systemd unit to survive cgroup cleanup (td-48).
+
+    When wake_branch() runs inside a systemd oneshot service (e.g.
+    daemon-tick.timer), the default KillMode=control-group sends SIGTERM to
+    every process in the cgroup once the main process exits — killing the
+    detached monitor and its claude child.  systemd-run --user creates a
+    transient service unit with its own cgroup so the monitor survives.
+
+    Returns True on success, False to fall back to direct Popen.
+    """
+    unit_name = f"dispatch-{branch_email.lstrip('@')}"
+    env_file = branch_path / "logs" / ".dispatch_env"
+
+    try:
+        with open(env_file, "w", encoding="utf-8") as ef:
+            for key, val in spawn_env.items():
+                if "\n" not in str(val):
+                    ef.write(f"{key}={val}\n")
+        env_file.chmod(0o600)
+    except OSError as e:
+        logger.warning("[wake] Failed to write env file for systemd-run: %s", e)
+        return False
+
+    systemd_cmd = [
+        "systemd-run",
+        "--user",
+        "--unit",
+        unit_name,
+        "--collect",
+        "--property",
+        f"WorkingDirectory={branch_path}",
+        "--property",
+        f"EnvironmentFile={env_file}",
+        "--property",
+        "StandardInput=null",
+        "--",
+    ] + monitor_cmd
+
+    try:
+        result = subprocess.run(systemd_cmd, capture_output=True, text=True, timeout=15)
+        if result.returncode != 0:
+            logger.warning("[wake] systemd-run failed (rc=%d): %s", result.returncode, result.stderr.strip())
+            return False
+    except (subprocess.SubprocessError, OSError) as e:
+        logger.warning("[wake] systemd-run failed: %s", e)
+        return False
+
+    try:
+        pid_result = subprocess.run(
+            ["systemctl", "--user", "show", f"{unit_name}.service", "-p", "MainPID", "--value"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        monitor_pid = int(pid_result.stdout.strip())
+        if monitor_pid > 0:
+            lock_data = {
+                "pid": monitor_pid,
+                "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
+                "branch": str(branch_path),
+                "subject": custom_message or "daemon wake",
+            }
+            with open(lock_file_path, "w", encoding="utf-8") as f:
+                json.dump(lock_data, f, indent=2)
+    except (subprocess.SubprocessError, ValueError, OSError) as e:
+        logger.info("[wake] Could not query systemd unit PID: %s", e)
+
+    status.ok("spawn", f"Monitor started via systemd scope ({unit_name})")
+    return True


 # ─── Branch Resolution ──────────────────────────────────
@@ -378,14 +542,27 @@ def wake_branch(
    branch_path, email = result
    status.ok("resolve", f"{email} → {branch_path}")

-    # Step 3: Zombie check (pre-flight)
+    # Step 3: Manager check — managers are never woken, mail only
+    passport_file = branch_path / ".trinity" / "passport.json"
+    try:
+        with open(passport_file, "r", encoding="utf-8") as f:
+            passport = json.load(f)
+        citizen_class = passport.get("identity", {}).get("citizen_class", "")
+        if citizen_class == "manager":
+            status.info("manager", f"{email} is a manager — mail only, wake skipped")
+            logger.info("[wake] %s is citizen_class=manager — wake skipped, mail delivered", email)
+            return status, True
+    except (FileNotFoundError, json.JSONDecodeError, OSError) as exc:
+        logger.info("[wake] Could not read passport for %s: %s", email, exc)
+
+    # Step 4: Zombie check (pre-flight)
    zombie_count = _clean_zombies()
    if zombie_count > 0:
        status.warn("zombies", f"{zombie_count} zombie Claude process(es) detected")
    else:
        status.ok("pre-flight", "No zombie processes")

-    # Step 4: Lock check
+    # Step 5: Lock check
    existing = _check_lock(branch_path)
    if existing is not None:
        pid = existing.get("pid", "?")
@@ -401,7 +578,7 @@ def wake_branch(

    status.ok("lock", "No active lock — agent is sleeping")

-    # Step 5: Occupancy check
+    # Step 6: Occupancy check
    if _is_branch_occupied(branch_path):
        status.warn("occupancy", f"Interactive Claude session in {branch_path}")
        status.fail("blocked", "Cannot spawn — interactive session running")
@@ -410,7 +587,7 @@ def wake_branch(

    status.ok("occupancy", "No interactive session")

-    # Step 6: Build spawn command
+    # Step 7: Build spawn command
    config = _load_config()
    max_turns = config.get("max_turns_per_wake", 100)

@@ -487,54 +664,97 @@ def wake_branch(
        return status, False
    status.ok("lock-acquire", "Dispatch lock acquired")

-    try:
-        process = subprocess.Popen(
+    # When inside a systemd oneshot service (e.g. daemon-tick.timer), the
+    # default KillMode=control-group sends SIGTERM to all cgroup members
+    # when the service exits — killing the detached monitor.  Escape by
+    # launching the monitor in its own transient systemd unit (td-48).
+    spawned_via_scope = False
+    monitor_pid = 0
+    if os.environ.get("INVOCATION_ID") and shutil.which("systemd-run"):
+        spawned_via_scope = _spawn_in_systemd_scope(
            monitor_cmd,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            start_new_session=True,
-            cwd=str(branch_path),
-            env=spawn_env,
+            branch_path,
+            spawn_env,
+            email,
+            lock_file_path,
+            custom_message,
+            status,
        )

-        monitor_pid = process.pid
+    if not spawned_via_scope:
+        try:
+            _detach_kwargs: dict = {}
+            if sys.platform == "win32":
+                _detach_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+            else:
+                _detach_kwargs["start_new_session"] = True
+            process = subprocess.Popen(
+                monitor_cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                cwd=str(branch_path),
+                env=spawn_env,
+                **_detach_kwargs,
+            )

-        # Update lock with real monitor PID
-        lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
-        lock_data = {
-            "pid": monitor_pid,
-            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
-            "branch": str(branch_path),
-            "subject": custom_message or "manual wake",
-        }
-        with open(lock_file, "w", encoding="utf-8") as f:
-            json.dump(lock_data, f, indent=2)
+            monitor_pid = process.pid

-        status.ok("spawn", f"Monitor started (PID {monitor_pid})")
+            # Update lock with real monitor PID
+            lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
+            lock_data = {
+                "pid": monitor_pid,
+                "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
+                "branch": str(branch_path),
+                "subject": custom_message or "manual wake",
+            }
+            with open(lock_file, "w", encoding="utf-8") as f:
+                json.dump(lock_data, f, indent=2)

-    except FileNotFoundError as e:
-        lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
-        lock_file.unlink(missing_ok=True)
-        logger.warning("[wake] Spawn failed — script not found: %s", e)
-        status.fail("spawn", "Python or monitor script not found")
-        return status, False
-    except Exception as e:
-        lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
-        lock_file.unlink(missing_ok=True)
-        logger.warning("[wake] Spawn failed for %s: %s", branch_email, e)
-        status.fail("spawn", f"{type(e).__name__}: {e}")
-        return status, False
+            status.ok("spawn", f"Monitor started (PID {monitor_pid})")
+
+        except FileNotFoundError as e:
+            lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
+            lock_file.unlink(missing_ok=True)
+            logger.warning("[wake] Spawn failed — script not found: %s", e)
+            status.fail("spawn", "Python or monitor script not found")
+            return status, False
+        except Exception as e:
+            lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
+            lock_file.unlink(missing_ok=True)
+            logger.warning("[wake] Spawn failed for %s: %s", branch_email, e)
+            status.fail("spawn", f"{type(e).__name__}: {e}")
+            return status, False

    # Step 9: Liveness check (brief wait then verify)
    time.sleep(2)
-    if _check_pid_alive(monitor_pid):
-        status.ok("alive", f"Agent responding (PID {monitor_pid} alive)")
+    if spawned_via_scope:
+        _unit = f"dispatch-{email.lstrip('@')}"
+        try:
+            check = subprocess.run(
+                ["systemctl", "--user", "is-active", f"{_unit}.service"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if check.stdout.strip() == "active":
+                status.ok("alive", f"Agent responding (unit {_unit} active)")
+            else:
+                status.fail("alive", f"Agent died immediately ({check.stdout.strip()})")
+                lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
+                lock_file.unlink(missing_ok=True)
+                return status, False
+        except Exception as e:
+            logger.info("[wake] Cannot verify systemd unit %s: %s", _unit, e)
+            status.warn("alive", "Cannot verify systemd unit status — assuming running")
    else:
-        status.fail("alive", f"Agent died immediately (PID {monitor_pid})")
-        # Clean up lock
-        lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
-        lock_file.unlink(missing_ok=True)
-        return status, False
+        if _check_pid_alive(monitor_pid):
+            status.ok("alive", f"Agent responding (PID {monitor_pid} alive)")
+        else:
+            status.fail("alive", f"Agent died immediately (PID {monitor_pid})")
+            lock_file = branch_path / ".ai_mail.local" / ".dispatch.lock"
+            lock_file.unlink(missing_ok=True)
+            return status, False

    # Desktop notification
    notif_body = custom_message[:80] if custom_message else "Manual wake: check inbox"
@@ -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()
@@ -14,6 +14,8 @@ Solves the BRANCH DETECTION FAILED problem when external projects call drone
 — contacts lookup works even when CWD-walking cannot identify the caller.
 """

+import os
+import sys
 from datetime import datetime
 from typing import Dict, Optional

@@ -21,6 +23,13 @@ from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.paths import find_repo_root

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 CONTACTS_FILE = find_repo_root() / "src/aipass/ai_mail/.ai_mail.local/contacts.json"


@@ -14,6 +14,8 @@ Independent handler - no module dependencies.
 """

 import json
+import os
+import sys
 from pathlib import Path
 from datetime import datetime
 from typing import Dict, Optional
@@ -21,6 +23,13 @@ from typing import Dict, Optional
 from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 # Lazy imports
 _append_footer = None

@@ -15,6 +15,7 @@ Independent handler - no module dependencies.

 import json
 import os
+import sys
 import uuid
 from pathlib import Path
 from typing import Dict, Tuple, List, Optional, Callable
@@ -24,6 +25,13 @@ from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.paths import find_repo_root
 from aipass.ai_mail.apps.handlers.registry.read import get_all_branches

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+

 _REPO_ROOT = find_repo_root()

@@ -165,7 +173,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
@@ -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()
@@ -1,9 +1,9 @@
 # =================== AIPass ====================
 # Name: footer.py
 # Description: Email Footer Handler
-# Version: 1.0.0
+# Version: 1.1.0
 # Created: 2026-01-29
-# Modified: 2026-01-29
+# Modified: 2026-07-14
 # =============================================

 """
@@ -19,10 +19,12 @@ from aipass.ai_mail.apps.handlers.json import json_handler
 # Standard footer for all outgoing emails
 STANDARD_FOOTER = """
 ---
+▶ BUILD/EDIT task? First: drone @trigger medic mute @<your-branch> — auto-expires 24h, no unmute.
+
 ⚠️ TASK CHECKLIST (before marking complete):
 □ SEEDGO CHECK → drone @seedgo audit @branch (80%+)
 □ UPDATE MEMORIES → Your .trinity/local.json records this work
-□ CLOSE FPLAN → drone @flow close <plan_id>
+□ CLOSE YOUR PLAN → drone @flow close <your_plan_id> — this task's plan only, never the master/parent
 □ EMAIL SENDER → drone @ai_mail email @<sender> "Subject" "Summary"

 Memories = Presence. No update = No learning.
@@ -14,12 +14,21 @@ Independent handler - no module dependencies.
 """

 import json
+import os
+import sys
 from typing import Dict, Optional

 from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.paths import find_repo_root

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+

 REGISTRY_PATH = find_repo_root() / "AIPASS_REGISTRY.json"

@@ -164,10 +173,10 @@ if __name__ == "__main__":
    console.print("  - format_email_list_item(index, email_data, show_unread) -> str")
    console.print()
    console.print("HANDLER CHARACTERISTICS:")
-    console.print("  ✓ Independent - no module dependencies")
-    console.print("  ✓ Can import Prax (service provider)")
-    console.print("  ✓ Pure business logic")
-    console.print("  ✗ CANNOT import parent modules")
+    console.print("  [green]+[/green] Independent - no module dependencies")
+    console.print("  [green]+[/green] Can import Prax (service provider)")
+    console.print("  [green]+[/green] Pure business logic")
+    console.print("  [dim]-[/dim] CANNOT import parent modules")
    console.print()
    console.print("USAGE FROM MODULES:")
    console.print("  from ai_mail.apps.handlers.email.format import format_email_preview")
@@ -16,6 +16,8 @@ v3.0.0: Now uses deleted/ directory with individual JSON files (like sent/).
 """

 import json
+import os
+import sys
 from pathlib import Path
 from datetime import datetime
 from typing import Dict, Tuple, Optional, Any
@@ -23,6 +25,13 @@ from typing import Dict, Tuple, Optional, Any
 from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+

 # Lazy import for inbox file lock
 _inbox_lock = None
@@ -38,13 +47,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 +193,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:
@@ -14,12 +14,21 @@ Independent handler - no module dependencies.
 """

 import json
+import os
+import sys
 from pathlib import Path
 from typing import Dict

 from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 # Lazy import for inbox file lock
 _inbox_lock = None

@@ -125,10 +134,10 @@ if __name__ == "__main__":
    console.print("  - load_inbox(inbox_file) -> Dict")
    console.print()
    console.print("HANDLER CHARACTERISTICS:")
-    console.print("  ✓ Independent - no module dependencies")
-    console.print("  ✓ Can import Prax (service provider)")
-    console.print("  ✓ Pure business logic")
-    console.print("  ✗ CANNOT import parent modules")
+    console.print("  [green]+[/green] Independent - no module dependencies")
+    console.print("  [green]+[/green] Can import Prax (service provider)")
+    console.print("  [green]+[/green] Pure business logic")
+    console.print("  [dim]-[/dim] CANNOT import parent modules")
    console.print()
    console.print("USAGE FROM MODULES:")
    console.print("  from aipass.ai_mail.apps.handlers.email.inbox_ops import load_inbox")
@@ -31,6 +31,13 @@ from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.paths import find_repo_root

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 # Purge configuration
 MAX_EMAILS = 10

@@ -13,6 +13,8 @@ Handles replying to emails and auto-closing the original.
 """

 import json
+import os
+import sys
 import uuid
 from pathlib import Path
 from typing import Dict, Tuple, Optional
@@ -22,6 +24,13 @@ from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.email.delivery import deliver_to_inbox_file

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 # Services imported in __main__ only (handlers should not display)


@@ -13,10 +13,19 @@ Provides repo root discovery used across all handler files.
 Consolidated from 8 identical copies per DPLAN-0036 audit.
 """

+import os
+import sys
 from pathlib import Path

 from aipass.ai_mail.apps.handlers.json import json_handler

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+

 def find_repo_root() -> Path:
    """Walk up from this file to find AIPASS_REGISTRY.json (repo root)."""
@@ -21,6 +21,8 @@ Handler Independence:
 """

 import json
+import os
+import sys
 from pathlib import Path
 from typing import List, Dict, Optional

@@ -28,6 +30,13 @@ from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.paths import find_repo_root

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+

 # Constants
 MODULE_NAME = "registry.read"
@@ -17,6 +17,7 @@ Walks up directory tree to find branch root (has .trinity/passport.json).
 # IMPORTS
 # =============================================
 import os
+import sys
 import json
 from pathlib import Path
 from typing import Dict, Optional
@@ -25,6 +26,13 @@ from aipass.prax.apps.modules.logger import system_logger as logger
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.paths import find_repo_root

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
 # =============================================
 # CONSTANTS
 # =============================================
@@ -297,10 +305,10 @@ if __name__ == "__main__":
    console.print("  - get_branch_info_from_registry(branch_path) -> Optional[Dict]")
    console.print()
    console.print("HANDLER CHARACTERISTICS:")
-    console.print("  ✓ Independent - no module dependencies")
-    console.print("  ✓ Can import Prax (service provider)")
-    console.print("  ✓ Pure business logic")
-    console.print("  ✗ CANNOT import parent modules")
+    console.print("  [green]+[/green] Independent - no module dependencies")
+    console.print("  [green]+[/green] Can import Prax (service provider)")
+    console.print("  [green]+[/green] Pure business logic")
+    console.print("  [dim]-[/dim] CANNOT import parent modules")
    console.print()
    console.print("DETECTION FLOW:")
    console.print("  1. Get current working directory (PWD)")
@@ -14,7 +14,6 @@ Delegates all business logic to handlers.
 """

 import os
-import subprocess
 import sys
 from pathlib import Path
 from typing import List
@@ -24,6 +23,13 @@ from aipass.cli.apps.modules import console, error
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.dispatch.status import load_dispatch_log, check_pid_status, calculate_age

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+

 def print_help() -> None:
    """Print help for dispatch commands."""
@@ -41,7 +47,6 @@ DISPATCH (send + wake):
  drone @ai_mail dispatch @branch "Subject" "Body" --fresh            # Send + fresh wake
  drone @ai_mail dispatch @branch "Subject" "Body" --model opus       # Send + wake with Opus
  drone @ai_mail dispatch @branch "Subject" "Body" --no-memory-save
-  drone @ai_mail dispatch @branch "Subject" "Body" --no-watchdog      # Skip auto-watchdog

 WAKE ONLY:
  drone @ai_mail dispatch wake @branch                       # Wake with default inbox check
@@ -219,7 +224,6 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
    # Parse flags
    use_fresh = False
    no_memory_save = False
-    no_watchdog = False
    from_branch = None
    use_model = None
    filtered = []
@@ -234,7 +238,6 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
            i += 1
            continue
        if args[i] == "--no-watchdog":
-            no_watchdog = True
            i += 1
            continue
        if args[i] == "--from" and i + 1 < len(args):
@@ -267,9 +270,9 @@ 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
+    from aipass.ai_mail.apps.handlers.paths import find_repo_root

    try:
        from aipass.ai_mail.apps.handlers.central_writer import update_central
@@ -278,7 +281,7 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
        update_central = None

    _ai_mail_dir = Path(__file__).resolve().parents[2]
-    _repo_root = _ai_mail_dir.parents[2]
+    _repo_root = find_repo_root()

    def _delivery_callback(branch_path, new_count, opened_count, total):
        on_email_delivered(
@@ -286,7 +289,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,
        )

@@ -343,57 +345,12 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
    if not wake_ok:
        logger.warning("[dispatch] Wake failed for %s — email was sent", target)
        error(f"Email sent but wake failed — retry: drone @ai_mail dispatch wake {target}")
-    elif not no_watchdog:
-        _spawn_watchdog(target)
+    else:
+        console.print(f"[dim]Wake-back enabled — sender will be woken when {target} completes (if available)[/dim]")

    return True


-def _spawn_watchdog(target: str) -> None:
-    """Auto-spawn devpulse watchdog as a detached background process."""
-    from aipass.ai_mail.apps.handlers.registry.read import get_branch_by_email
-
-    devpulse_info = get_branch_by_email("@devpulse")
-    if not devpulse_info:
-        logger.warning("[dispatch] Cannot spawn watchdog — @devpulse not in registry")
-        return
-
-    _ai_mail_dir = Path(__file__).resolve().parents[2]
-    _repo_root = _ai_mail_dir.parents[2]
-    devpulse_path = devpulse_info.get("path", "")
-    if not devpulse_path:
-        logger.warning("[dispatch] Cannot spawn watchdog — @devpulse has no path")
-        return
-
-    devpulse_dir = Path(devpulse_path)
-    if not devpulse_dir.is_absolute():
-        devpulse_dir = _repo_root / devpulse_dir
-
-    if not devpulse_dir.is_dir():
-        logger.warning("[dispatch] Cannot spawn watchdog — devpulse dir not found: %s", devpulse_dir)
-        return
-
-    cmd = ["drone", "@devpulse", "watchdog", "agent", target]
-
-    spawn_env = os.environ.copy()
-    local_bin = str(Path.home() / ".local" / "bin")
-    if local_bin not in spawn_env.get("PATH", ""):
-        spawn_env["PATH"] = local_bin + ":" + spawn_env.get("PATH", "")
-
-    try:
-        subprocess.Popen(
-            cmd,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            start_new_session=True,
-            cwd=str(devpulse_dir),
-            env=spawn_env,
-        )
-        console.print(f"[green]Watchdog armed for {target}[/green]")
-    except Exception as e:
-        logger.warning("[dispatch] Watchdog spawn failed for %s: %s", target, e)
-
-
 def _orchestrate_daemon() -> bool:
    """Orchestrate daemon startup."""
    logger.info("[dispatch] Starting dispatch daemon")
@@ -19,19 +19,13 @@ Module Pattern:
 - NO business logic in this file
 """

+import os
 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
@@ -46,8 +40,19 @@ from aipass.ai_mail.apps.handlers.registry.read import get_all_branches, get_bra
 from aipass.ai_mail.apps.handlers.json import json_handler
 from aipass.ai_mail.apps.handlers.email.close_ops import batch_close, batch_close_post_ops
 from aipass.ai_mail.apps.handlers.email.inbox_resolve import resolve_inbox_target
+from aipass.ai_mail.apps.handlers.paths import find_repo_root
 from aipass.ai_mail.apps.modules.email_send import handle_send

+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
+_AI_MAIL_DIR = Path(__file__).resolve().parents[2]
+_REPO_ROOT = find_repo_root()
+
 try:
    from aipass.ai_mail.apps.handlers.central_writer import update_central
 except ImportError as e:
@@ -255,7 +260,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:
@@ -387,7 +392,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/")
@@ -14,17 +14,15 @@ broadcast, and dispatch trigger. Extracted from email.py to keep modules
 under the size threshold.
 """

+import os
+import sys
 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
@@ -39,6 +37,17 @@ 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
+from aipass.ai_mail.apps.handlers.paths import find_repo_root
+
+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    for _stream in (sys.stdout, sys.stderr):
+        _reconfigure = getattr(_stream, "reconfigure", None)
+        if _reconfigure is not None:
+            _reconfigure(encoding="utf-8", errors="replace")
+
+_AI_MAIL_DIR = Path(__file__).resolve().parents[2]
+_REPO_ROOT = find_repo_root()

 try:
    from aipass.ai_mail.apps.handlers.central_writer import update_central
@@ -54,7 +63,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,
    )

@@ -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()
@@ -9,10 +9,11 @@
 """Tests for dispatch daemon handler -- config loading, state management, inbox scanning."""

 import json
+import os
 import sys
 import pytest
 from datetime import datetime, date, timedelta
-from unittest.mock import patch
+from unittest.mock import MagicMock, mock_open, patch

 import aipass.ai_mail.apps.handlers.dispatch.daemon as daemon_mod
 from aipass.ai_mail.apps.handlers.dispatch.daemon import (
@@ -25,6 +26,17 @@ from aipass.ai_mail.apps.handlers.dispatch.daemon import (
    get_registered_branches,
    check_inbox_for_dispatch,
    is_protected_branch,
+    _handle_signal,
+    _check_lock,
+    _acquire_lock,
+    _is_registered_sender,
+    poll_cycle,
+    _write_pid_file,
+    _remove_pid_file,
+    _read_session_type,
+    _is_branch_occupied,
+    spawn_agent,
+    run_daemon,
 )


@@ -764,26 +776,6 @@ def test_poll_cycle_absolute_path_unchanged(tmp_path, monkeypatch):
    assert spawned_paths[0] == branch_dir


-# ---- Additional imports for new tests --------------------------------
-
-import os
-from unittest.mock import MagicMock, mock_open
-
-from aipass.ai_mail.apps.handlers.dispatch.daemon import (
-    _handle_signal,
-    _check_lock,
-    _acquire_lock,
-    _is_registered_sender,
-    poll_cycle,
-    _write_pid_file,
-    _remove_pid_file,
-    _read_session_type,
-    _is_branch_occupied,
-    spawn_agent,
-    run_daemon,
-)
-
-
 # ---- _handle_signal tests --------------------------------------


@@ -814,7 +806,7 @@ def test_check_lock_alive_pid(tmp_path, monkeypatch):
    lock_data = {"pid": 99999, "timestamp": datetime.now().isoformat()}
    lock_file.write_text(json.dumps(lock_data), encoding="utf-8")

-    monkeypatch.setattr(os, "kill", lambda pid, sig: None)
+    monkeypatch.setattr(daemon_mod, "_pid_alive", lambda pid: True)

    result = _check_lock(tmp_path)

@@ -823,17 +815,14 @@ def test_check_lock_alive_pid(tmp_path, monkeypatch):


 def test_check_lock_dead_pid(tmp_path, monkeypatch):
-    """Lock with dead PID (ProcessLookupError) is cleaned up."""
+    """Lock with dead PID is cleaned up."""
    lock_dir = tmp_path / ".ai_mail.local"
    lock_dir.mkdir(parents=True)
    lock_file = lock_dir / ".dispatch.lock"
    lock_data = {"pid": 99999, "timestamp": datetime.now().isoformat()}
    lock_file.write_text(json.dumps(lock_data), encoding="utf-8")

-    def _raise_process_lookup(pid, sig):
-        raise ProcessLookupError("No such process")
-
-    monkeypatch.setattr(os, "kill", _raise_process_lookup)
+    monkeypatch.setattr(daemon_mod, "_pid_alive", lambda pid: False)

    result = _check_lock(tmp_path)

@@ -849,10 +838,7 @@ def test_check_lock_permission_error(tmp_path, monkeypatch):
    lock_data = {"pid": 99999, "timestamp": datetime.now().isoformat()}
    lock_file.write_text(json.dumps(lock_data), encoding="utf-8")

-    def _raise_permission(pid, sig):
-        raise PermissionError("Operation not permitted")
-
-    monkeypatch.setattr(os, "kill", _raise_permission)
+    monkeypatch.setattr(daemon_mod, "_pid_alive", lambda pid: True)

    result = _check_lock(tmp_path)

@@ -869,10 +855,7 @@ def test_check_lock_stale_over_10min_removed(tmp_path, monkeypatch):
    lock_data = {"pid": 99999, "timestamp": old_time}
    lock_file.write_text(json.dumps(lock_data), encoding="utf-8")

-    def _raise_process_lookup(pid, sig):
-        raise ProcessLookupError("No such process")
-
-    monkeypatch.setattr(os, "kill", _raise_process_lookup)
+    monkeypatch.setattr(daemon_mod, "_pid_alive", lambda pid: False)

    result = _check_lock(tmp_path)

@@ -889,10 +872,7 @@ def test_check_lock_stale_under_10min_dead_pid_removed(tmp_path, monkeypatch):
    lock_data = {"pid": 99999, "timestamp": recent_time}
    lock_file.write_text(json.dumps(lock_data), encoding="utf-8")

-    def _raise_process_lookup(pid, sig):
-        raise ProcessLookupError("No such process")
-
-    monkeypatch.setattr(os, "kill", _raise_process_lookup)
+    monkeypatch.setattr(daemon_mod, "_pid_alive", lambda pid: False)

    result = _check_lock(tmp_path)

@@ -1015,6 +995,7 @@ def test_write_pid_file_existing_dead_pid(tmp_path, monkeypatch):

 def test_write_pid_file_existing_permission_error(tmp_path, monkeypatch):
    """Existing PID file with PermissionError on kill returns False."""
+    monkeypatch.setattr("sys.platform", "linux")
    pid_file = tmp_path / "daemon.pid"
    pid_file.write_text("888888", encoding="utf-8")
    monkeypatch.setattr(daemon_mod, "DAEMON_PID_FILE", pid_file)
@@ -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(),
@@ -971,168 +969,18 @@ class TestPrintIntrospection:


 # ===========================================================================
-# _spawn_watchdog
+# Wake-back messaging (TDPLAN-0012 — retired _spawn_watchdog)
 # ===========================================================================


-class TestSpawnWatchdog:
-    """Tests for _spawn_watchdog."""
-
-    def test_spawns_detached_subprocess(self, monkeypatch, tmp_path):
-        """Successful watchdog spawn calls Popen with correct args."""
-        devpulse_dir = tmp_path / "src" / "aipass" / "devpulse"
-        devpulse_dir.mkdir(parents=True)
+class TestWakeBackMessaging:
+    """Tests for honest wake-back messaging after watchdog retirement."""

+    def test_wake_back_message_on_successful_wake(self, monkeypatch):
+        """Successful send + wake prints wake-back enabled message."""
        printed: list[str] = []
        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))

-        popen_calls: list[dict] = []
-        mock_popen = MagicMock()
-
-        def tracking_popen(cmd, **kwargs):
-            """Capture Popen arguments."""
-            popen_calls.append({"cmd": cmd, **kwargs})
-            return mock_popen
-
-        with (
-            patch(
-                f"{_H_REG}.get_branch_by_email",
-                return_value={"email": "@devpulse", "path": str(devpulse_dir)},
-            ),
-            patch(f"{MOD}.subprocess.Popen", side_effect=tracking_popen),
-        ):
-            from aipass.ai_mail.apps.modules.dispatch import _spawn_watchdog
-
-            _spawn_watchdog("@flow")
-
-        assert len(popen_calls) == 1
-        assert popen_calls[0]["cmd"] == ["drone", "@devpulse", "watchdog", "agent", "@flow"]
-        assert popen_calls[0]["start_new_session"] is True
-        assert popen_calls[0]["cwd"] == str(devpulse_dir)
-        combined = " ".join(printed)
-        assert "Watchdog armed for @flow" in combined
-
-    def test_devpulse_not_in_registry(self, monkeypatch):
-        """No spawn when @devpulse not found in registry."""
-        printed: list[str] = []
-        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))
-
-        with (
-            patch(f"{_H_REG}.get_branch_by_email", return_value=None),
-            patch(f"{MOD}.subprocess.Popen") as mock_popen,
-        ):
-            from aipass.ai_mail.apps.modules.dispatch import _spawn_watchdog
-
-            _spawn_watchdog("@flow")
-
-        mock_popen.assert_not_called()
-
-    def test_devpulse_no_path(self, monkeypatch):
-        """No spawn when @devpulse has empty path."""
-        printed: list[str] = []
-        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))
-
-        with (
-            patch(
-                f"{_H_REG}.get_branch_by_email",
-                return_value={"email": "@devpulse", "path": ""},
-            ),
-            patch(f"{MOD}.subprocess.Popen") as mock_popen,
-        ):
-            from aipass.ai_mail.apps.modules.dispatch import _spawn_watchdog
-
-            _spawn_watchdog("@flow")
-
-        mock_popen.assert_not_called()
-
-    def test_devpulse_dir_missing(self, monkeypatch, tmp_path):
-        """No spawn when devpulse directory doesn't exist."""
-        printed: list[str] = []
-        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))
-
-        with (
-            patch(
-                f"{_H_REG}.get_branch_by_email",
-                return_value={"email": "@devpulse", "path": str(tmp_path / "nonexistent")},
-            ),
-            patch(f"{MOD}.subprocess.Popen") as mock_popen,
-        ):
-            from aipass.ai_mail.apps.modules.dispatch import _spawn_watchdog
-
-            _spawn_watchdog("@flow")
-
-        mock_popen.assert_not_called()
-
-    def test_popen_failure_warns_but_does_not_raise(self, monkeypatch, tmp_path):
-        """Popen failure logs warning but doesn't propagate."""
-        devpulse_dir = tmp_path / "src" / "aipass" / "devpulse"
-        devpulse_dir.mkdir(parents=True)
-
-        printed: list[str] = []
-        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))
-
-        with (
-            patch(
-                f"{_H_REG}.get_branch_by_email",
-                return_value={"email": "@devpulse", "path": str(devpulse_dir)},
-            ),
-            patch(f"{MOD}.subprocess.Popen", side_effect=FileNotFoundError("drone not found")),
-        ):
-            from aipass.ai_mail.apps.modules.dispatch import _spawn_watchdog
-
-            _spawn_watchdog("@flow")
-
-        # Should not raise — watchdog is optional
-
-    def test_relative_devpulse_path_resolved(self, monkeypatch, tmp_path):
-        """Relative path from registry is resolved against repo root."""
-        printed: list[str] = []
-        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))
-
-        popen_calls: list[dict] = []
-
-        def tracking_popen(cmd, **kwargs):
-            """Capture Popen arguments."""
-            popen_calls.append({"cmd": cmd, **kwargs})
-            return MagicMock()
-
-        from aipass.ai_mail.apps.modules import dispatch as dispatch_mod
-
-        real_repo_root = dispatch_mod.Path(__file__).resolve().parents[4]
-        devpulse_dir = real_repo_root / "src" / "aipass" / "devpulse"
-
-        with (
-            patch(
-                f"{_H_REG}.get_branch_by_email",
-                return_value={"email": "@devpulse", "path": "src/aipass/devpulse"},
-            ),
-            patch(f"{MOD}.subprocess.Popen", side_effect=tracking_popen),
-        ):
-            from aipass.ai_mail.apps.modules.dispatch import _spawn_watchdog
-
-            _spawn_watchdog("@flow")
-
-        if devpulse_dir.is_dir():
-            assert len(popen_calls) == 1
-            assert "devpulse" in popen_calls[0]["cwd"]
-        else:
-            assert len(popen_calls) == 0
-
-
-class TestDispatchSendWatchdogIntegration:
-    """Tests for watchdog integration in _orchestrate_dispatch_send."""
-
-    def test_watchdog_spawned_after_successful_wake(self, monkeypatch):
-        """Watchdog is spawned after successful send + wake."""
-        printed: list[str] = []
-        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))
-
-        watchdog_calls: list[str] = []
-        monkeypatch.setattr(
-            f"{MOD}._spawn_watchdog",
-            lambda target: watchdog_calls.append(target),
-        )
-
        patches = _send_patches()
        with patches:
            from aipass.ai_mail.apps.modules.dispatch import _orchestrate_dispatch_send
@@ -1140,21 +988,17 @@ class TestDispatchSendWatchdogIntegration:
            result = _orchestrate_dispatch_send(["@target", "Subject", "Body"])

        assert result is True
-        assert watchdog_calls == ["@target"]
+        combined = " ".join(printed)
+        assert "Wake-back enabled" in combined
+        assert "Watchdog armed" not in combined

-    def test_watchdog_not_spawned_on_wake_failure(self, monkeypatch):
-        """Watchdog is NOT spawned when wake fails."""
+    def test_no_wake_back_message_on_wake_failure(self, monkeypatch):
+        """No wake-back message when wake fails."""
        errors: list[str] = []
        monkeypatch.setattr(f"{MOD}.error", lambda msg: errors.append(msg))
        printed: list[str] = []
        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))

-        watchdog_calls: list[str] = []
-        monkeypatch.setattr(
-            f"{MOD}._spawn_watchdog",
-            lambda target: watchdog_calls.append(target),
-        )
-
        mock_status = MagicMock()
        mock_status.format.return_value = "WAKE FAILED"
        patches = _send_patches(
@@ -1167,19 +1011,14 @@ class TestDispatchSendWatchdogIntegration:

            _orchestrate_dispatch_send(["@target", "Subject", "Body"])

-        assert watchdog_calls == []
+        combined = " ".join(printed)
+        assert "Wake-back enabled" not in combined

-    def test_no_watchdog_flag_skips_spawn(self, monkeypatch):
-        """--no-watchdog flag prevents watchdog spawn."""
+    def test_no_watchdog_flag_still_accepted(self, monkeypatch):
+        """--no-watchdog flag is consumed without error (backward compat)."""
        printed: list[str] = []
        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))

-        watchdog_calls: list[str] = []
-        monkeypatch.setattr(
-            f"{MOD}._spawn_watchdog",
-            lambda target: watchdog_calls.append(target),
-        )
-
        patches = _send_patches()
        with patches:
            from aipass.ai_mail.apps.modules.dispatch import _orchestrate_dispatch_send
@@ -1187,21 +1026,14 @@ class TestDispatchSendWatchdogIntegration:
            result = _orchestrate_dispatch_send(["@target", "Subject", "Body", "--no-watchdog"])

        assert result is True
-        assert watchdog_calls == []

-    def test_watchdog_not_spawned_on_send_failure(self, monkeypatch):
-        """Watchdog is NOT spawned when send fails."""
+    def test_no_watchdog_message_on_send_failure(self, monkeypatch):
+        """No wake-back message when send fails."""
        errors: list[str] = []
        monkeypatch.setattr(f"{MOD}.error", lambda msg: errors.append(msg))
        printed: list[str] = []
        monkeypatch.setattr(f"{MOD}.console", _mock_console(printed))

-        watchdog_calls: list[str] = []
-        monkeypatch.setattr(
-            f"{MOD}._spawn_watchdog",
-            lambda target: watchdog_calls.append(target),
-        )
-
        patches = _send_patches(
            {
                f"{_H_SEND}.send_to_single": MagicMock(return_value=(False, "error")),
@@ -1212,4 +1044,5 @@ class TestDispatchSendWatchdogIntegration:

            _orchestrate_dispatch_send(["@target", "Subject", "Body"])

-        assert watchdog_calls == []
+        combined = " ".join(printed)
+        assert "Wake-back enabled" not in combined
@@ -19,15 +19,18 @@ from unittest.mock import MagicMock

 import aipass.ai_mail.apps.handlers.dispatch.dispatch_monitor as mod
 from aipass.ai_mail.apps.handlers.dispatch.dispatch_monitor import (
+    MAX_WAKE_DEPTH,
    _check_jsonl_activity,
    _check_rate_limited,
    _get_jsonl_projects_dir,
    _is_sandbox_enabled,
    _kill_process,
+    _log_wake_result,
    _make_fresh_cmd,
    _run_with_startup_check,
    _send_bounce,
    _snapshot_jsonl_sizes,
+    _wake_sender,
    _wrap_for_sandbox,
    main,
 )
@@ -52,6 +55,13 @@ def _suppress_logger(monkeypatch):
    monkeypatch.setattr(mod, "logger", MagicMock())


+@pytest.fixture(autouse=True)
+def _suppress_wake(monkeypatch):
+    """Prevent _wake_sender from importing/calling real wake_branch in unrelated tests."""
+    monkeypatch.setattr(mod, "_wake_sender", MagicMock(return_value="skipped_sender"))
+    monkeypatch.setattr(mod, "_log_wake_result", MagicMock())
+
+
@pytest.fixture
 def stderr_log(tmp_path):
    """Create a stderr log file and return its path string."""
@@ -1731,10 +1741,13 @@ class TestBrokerRealE2E:
        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
+        # Set up repo root with branch dir + .trinity marker (broker marker-walk requires it)
        repo_root = tmp_path / "repo"
        branch_dir = repo_root / "src" / "aipass" / "testbranch"
        branch_dir.mkdir(parents=True)
+        trinity_dir = branch_dir / ".trinity"
+        trinity_dir.mkdir()
+        (trinity_dir / "passport.json").write_text('{"branch_info": {"branch_name": "testbranch"}}', encoding="utf-8")
        target_file = branch_dir / "deleteme.txt"
        target_file.write_text("delete me", encoding="utf-8")

@@ -1821,3 +1834,328 @@ finally:
        finally:
            broker.stop()
            t.join(timeout=3)
+
+
+# === Wake-back tests (TDPLAN-0012) ==========================================
+
+
+class TestWakeSender:
+    """_wake_sender guards and wake-back dispatch."""
+
+    def test_skips_empty_sender(self, monkeypatch):
+        """Empty sender returns skipped_sender."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        result = _wake_sender("", "@target", 0, "/fake/lock")
+        assert result == "skipped_sender"
+
+    def test_skips_whitespace_sender(self, monkeypatch):
+        """Whitespace-only sender returns skipped_sender."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        result = _wake_sender("   ", "@target", 0, "/fake/lock")
+        assert result == "skipped_sender"
+
+    def test_skips_self_wake(self, monkeypatch):
+        """Sender equal to completed agent returns skipped_self."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        result = _wake_sender("@trigger", "@trigger", 0, "/fake/lock")
+        assert result == "skipped_self"
+
+    def test_skips_self_wake_case_insensitive(self, monkeypatch):
+        """Self-wake guard is case-insensitive."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        result = _wake_sender("Trigger", "@TRIGGER", 0, "/fake/lock")
+        assert result == "skipped_self"
+
+    def test_wake_back_carries_empty_sender(self, monkeypatch):
+        """Wake-back session carries empty sender to terminate the chain."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.delenv("AIPASS_WAKE_DEPTH", raising=False)
+        mock_status = MagicMock()
+        mock_status.summary = "ok"
+        mock_wake = MagicMock(return_value=(mock_status, True))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            mock_wake,
+        )
+        _wake_sender("@prax", "@trigger", 0, "/fake/lock")
+        mock_wake.assert_called_once_with("@prax", auto=True, sender="")
+
+    def test_any_citizen_reaches_wake_branch(self, monkeypatch):
+        """Any citizen sender reaches wake_branch."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.delenv("AIPASS_WAKE_DEPTH", raising=False)
+        mock_status = MagicMock()
+        mock_status.summary = "ok"
+        mock_wake = MagicMock(return_value=(mock_status, True))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            mock_wake,
+        )
+        result = _wake_sender("@prax", "@target", 0, "/fake/lock")
+        assert result == "success"
+        mock_wake.assert_called_once()
+
+    def test_depth_cap_blocks(self, monkeypatch):
+        """AIPASS_WAKE_DEPTH >= MAX_WAKE_DEPTH returns blocked_depth."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.setenv("AIPASS_WAKE_DEPTH", str(MAX_WAKE_DEPTH))
+        result = _wake_sender("@prax", "@target", 0, "/fake/lock")
+        assert result == "blocked_depth"
+
+    def test_depth_cap_over_max_blocks(self, monkeypatch):
+        """Depth above max also blocks."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.setenv("AIPASS_WAKE_DEPTH", str(MAX_WAKE_DEPTH + 5))
+        result = _wake_sender("@prax", "@target", 0, "/fake/lock")
+        assert result == "blocked_depth"
+
+    def test_success_on_wake(self, monkeypatch):
+        """Successful wake_branch call returns success."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.delenv("AIPASS_WAKE_DEPTH", raising=False)
+
+        mock_status = MagicMock()
+        mock_status.summary = "ok"
+        mock_wake = MagicMock(return_value=(mock_status, True))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            mock_wake,
+        )
+
+        result = _wake_sender("@trigger", "@target", 0, "/fake/lock")
+        assert result == "success"
+        mock_wake.assert_called_once_with("@trigger", auto=True, sender="")
+
+    def test_blocked_locked_on_lock_failure(self, monkeypatch):
+        """wake_branch failing with lock-related message returns blocked_locked."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.delenv("AIPASS_WAKE_DEPTH", raising=False)
+
+        mock_status = MagicMock()
+        mock_status.summary = "lock: Active agent (PID 1234)"
+        mock_wake = MagicMock(return_value=(mock_status, False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            mock_wake,
+        )
+
+        result = _wake_sender("@prax", "@target", 0, "/fake/lock")
+        assert result == "blocked_locked"
+
+    def test_blocked_occupied_on_interactive(self, monkeypatch):
+        """wake_branch failing with occupancy message returns blocked_occupied."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.delenv("AIPASS_WAKE_DEPTH", raising=False)
+
+        mock_status = MagicMock()
+        mock_status.summary = "blocked: Cannot spawn — interactive session running"
+        mock_wake = MagicMock(return_value=(mock_status, False))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            mock_wake,
+        )
+
+        result = _wake_sender("@trigger", "@target", 0, "/fake/lock")
+        assert result == "blocked_occupied"
+
+    def test_failed_on_exception(self, monkeypatch):
+        """Exception during wake returns failed."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.delenv("AIPASS_WAKE_DEPTH", raising=False)
+
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            MagicMock(side_effect=RuntimeError("broken")),
+        )
+
+        result = _wake_sender("@prax", "@target", 0, "/fake/lock")
+        assert result == "failed"
+
+    def test_depth_incremented_before_wake(self, monkeypatch):
+        """AIPASS_WAKE_DEPTH is incremented before calling wake_branch."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.setenv("AIPASS_WAKE_DEPTH", "1")
+
+        captured_depth = []
+
+        def capture_wake(*args, **kwargs):
+            captured_depth.append(os.environ.get("AIPASS_WAKE_DEPTH"))
+            mock_status = MagicMock()
+            mock_status.summary = "ok"
+            return mock_status, True
+
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            capture_wake,
+        )
+
+        _wake_sender("@trigger", "@target", 0, "/fake/lock")
+        assert captured_depth == ["2"]
+
+    def test_wake_called_on_failure_exit(self, monkeypatch):
+        """Wake fires on non-zero exit code too."""
+        monkeypatch.setattr(mod, "logger", MagicMock())
+        monkeypatch.delenv("AIPASS_WAKE_DEPTH", raising=False)
+
+        mock_status = MagicMock()
+        mock_status.summary = "ok"
+        mock_wake = MagicMock(return_value=(mock_status, True))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.dispatch.wake.wake_branch",
+            mock_wake,
+        )
+
+        result = _wake_sender("@prax", "@target", 1, "/fake/lock")
+        assert result == "success"
+        mock_wake.assert_called_once()
+
+
+class TestLogWakeResult:
+    """_log_wake_result writes to dispatch_wake.log."""
+
+    def test_creates_log_file(self, tmp_path):
+        """Log file created under target's logs/ directory."""
+        lock = tmp_path / "branch" / ".ai_mail.local" / ".dispatch.lock"
+        lock.parent.mkdir(parents=True)
+        lock.write_text("{}", encoding="utf-8")
+        logs_dir = tmp_path / "branch" / "logs"
+
+        _log_wake_result("@target", "@sender", 0, "success", str(lock))
+
+        log_file = logs_dir / "dispatch_wake.log"
+        assert log_file.exists()
+        content = log_file.read_text(encoding="utf-8")
+        assert "target=@target" in content
+        assert "sender=@sender" in content
+        assert "exit_code=0" in content
+        assert "wake_result=success" in content
+
+    def test_appends_to_existing(self, tmp_path):
+        """Subsequent calls append, not overwrite."""
+        lock = tmp_path / "branch" / ".ai_mail.local" / ".dispatch.lock"
+        lock.parent.mkdir(parents=True)
+        lock.write_text("{}", encoding="utf-8")
+        logs_dir = tmp_path / "branch" / "logs"
+        logs_dir.mkdir(parents=True)
+        log_file = logs_dir / "dispatch_wake.log"
+        log_file.write_text("existing line\n", encoding="utf-8")
+
+        _log_wake_result("@target", "@sender", 0, "success", str(lock))
+
+        lines = log_file.read_text(encoding="utf-8").strip().split("\n")
+        assert len(lines) == 2
+        assert lines[0] == "existing line"
+        assert "wake_result=success" in lines[1]
+
+    def test_all_result_values(self, tmp_path):
+        """All result enum values are logged correctly."""
+        lock = tmp_path / "branch" / ".ai_mail.local" / ".dispatch.lock"
+        lock.parent.mkdir(parents=True)
+        lock.write_text("{}", encoding="utf-8")
+
+        for result_tag in (
+            "success",
+            "blocked_occupied",
+            "blocked_locked",
+            "blocked_depth",
+            "skipped_sender",
+            "failed",
+        ):
+            _log_wake_result("@t", "@s", 0, result_tag, str(lock))
+
+        log_file = tmp_path / "branch" / "logs" / "dispatch_wake.log"
+        lines = log_file.read_text(encoding="utf-8").strip().split("\n")
+        assert len(lines) == 6
+
+
+class TestWakeBackIntegration:
+    """Wake-back wired into main() — fires after lock cleanup on both paths."""
+
+    def test_wake_called_on_success(self, monkeypatch, main_argv):
+        """_wake_sender called with correct args after successful agent run."""
+        argv, lock_file, stderr_log = main_argv
+
+        wake_calls = []
+
+        def track_wake(sender, branch_email, exit_code, lf):
+            wake_calls.append((sender, branch_email, exit_code))
+            return "success"
+
+        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(mod, "_wake_sender", track_wake)
+        monkeypatch.setattr(mod, "_log_wake_result", MagicMock())
+        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(wake_calls) == 1
+        assert wake_calls[0] == ("@sender", "@test_branch", 0)
+
+    def test_wake_called_on_failure(self, monkeypatch, main_argv):
+        """_wake_sender called after all attempts fail (in addition to bounce)."""
+        argv, lock_file, stderr_log = main_argv
+
+        wake_calls = []
+        mock_bounce = MagicMock()
+
+        def track_wake(sender, branch_email, exit_code, lf):
+            wake_calls.append((sender, branch_email, exit_code))
+            return "success"
+
+        monkeypatch.setattr("sys.argv", argv)
+        monkeypatch.setattr(mod, "_run_with_startup_check", MagicMock(side_effect=[(1, False), (1, False), (1, False)]))
+        monkeypatch.setattr(mod, "_send_bounce", mock_bounce)
+        monkeypatch.setattr(mod, "_check_rate_limited", MagicMock(return_value=False))
+        monkeypatch.setattr(mod, "_wake_sender", track_wake)
+        monkeypatch.setattr(mod, "_log_wake_result", MagicMock())
+        monkeypatch.setattr(
+            mod,
+            "time",
+            MagicMock(time=time.time, strftime=time.strftime, sleep=MagicMock()),
+        )
+        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()
+        assert len(wake_calls) == 1
+        assert wake_calls[0][2] != 0
+
+    def test_log_wake_result_called(self, monkeypatch, main_argv):
+        """_log_wake_result called with wake result after main completes."""
+        argv, lock_file, stderr_log = main_argv
+
+        log_calls = []
+
+        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(mod, "_wake_sender", MagicMock(return_value="success"))
+        monkeypatch.setattr(mod, "_log_wake_result", lambda *a: log_calls.append(a))
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.paths.find_repo_root",
+            MagicMock(return_value=Path("/fake/repo")),
+        )
+
+        with pytest.raises(SystemExit):
+            main()
+
+        assert len(log_calls) == 1
+        branch_email, sender, exit_code, result, lf = log_calls[0]
+        assert branch_email == "@test_branch"
+        assert sender == "@sender"
+        assert exit_code == 0
+        assert result == "success"
@@ -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


 # ===========================================================================
@@ -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()
@@ -46,7 +46,7 @@ def test_get_footer_contains_checklist():
    assert "TASK CHECKLIST" in result
    assert "SEEDGO CHECK" in result
    assert "UPDATE MEMORIES" in result
-    assert "CLOSE FPLAN" in result
+    assert "CLOSE YOUR PLAN" in result
    assert "EMAIL SENDER" in result


@@ -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."""
@@ -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
 # ==============================================================
@@ -20,7 +20,11 @@ from aipass.ai_mail.apps.handlers.dispatch.wake import (
    _read_json,
    _check_lock,
    _check_pid_alive,
+    _get_pid_cwd,
+    _get_pid_cwd_darwin,
    _read_session_type,
+    _read_session_type_darwin,
+    _is_zombie_linux,
    _clean_zombies,
    _find_claude_bin,
    resolve_branch,
@@ -138,6 +142,7 @@ def test_check_pid_alive_dead(monkeypatch):

 def test_check_pid_alive_permission_error(monkeypatch):
    """PermissionError means process exists but cannot signal -- returns True."""
+    monkeypatch.setattr("sys.platform", "linux")
    monkeypatch.setattr(os, "kill", _raise_permission)
    assert _check_pid_alive(1) is True

@@ -201,11 +206,126 @@ def test_read_session_type_not_set(monkeypatch, tmp_path):


 def test_read_session_type_non_linux(monkeypatch):
-    """Non-linux platform returns 'interactive' immediately."""
-    monkeypatch.setattr("sys.platform", "darwin")
+    """Non-linux, non-darwin platform returns 'interactive' immediately."""
+    monkeypatch.setattr("sys.platform", "win32")
    assert _read_session_type("999") == "interactive"


+def test_read_session_type_darwin_found(monkeypatch):
+    """macOS: reads AIPASS_SESSION_TYPE from ps -wwE output."""
+    monkeypatch.setattr("sys.platform", "darwin")
+
+    class FakeResult:
+        returncode = 0
+        stdout = "/usr/bin/claude AIPASS_SESSION_TYPE=dispatched HOME=/Users/u"
+
+    monkeypatch.setattr(subprocess, "run", lambda *a, **kw: FakeResult())
+    assert _read_session_type("123") == "dispatched"
+
+
+def test_read_session_type_darwin_not_set(monkeypatch):
+    """macOS: missing env var returns 'interactive'."""
+    monkeypatch.setattr("sys.platform", "darwin")
+
+    class FakeResult:
+        returncode = 0
+        stdout = "/usr/bin/claude HOME=/Users/u"
+
+    monkeypatch.setattr(subprocess, "run", lambda *a, **kw: FakeResult())
+    assert _read_session_type("456") == "interactive"
+
+
+def test_read_session_type_darwin_ps_failure(monkeypatch):
+    """macOS: ps failure returns 'interactive'."""
+    assert _read_session_type_darwin("999") == "interactive"
+
+
+# --- _get_pid_cwd tests ------------------------------------------------
+
+
+def test_get_pid_cwd_linux(monkeypatch, tmp_path):
+    """Linux: reads /proc/{pid}/cwd via readlink."""
+    monkeypatch.setattr("sys.platform", "linux")
+    target = str(tmp_path / "project")
+    monkeypatch.setattr(os, "readlink", lambda p: target)
+    assert _get_pid_cwd("100") == target
+
+
+def test_get_pid_cwd_linux_oserror(monkeypatch):
+    """Linux: OSError returns None."""
+    monkeypatch.setattr("sys.platform", "linux")
+    monkeypatch.setattr(os, "readlink", lambda p: (_ for _ in ()).throw(OSError("no proc")))
+    assert _get_pid_cwd("100") is None
+
+
+def test_get_pid_cwd_darwin(monkeypatch, tmp_path):
+    """macOS: reads cwd via lsof."""
+    monkeypatch.setattr("sys.platform", "darwin")
+    target = "/tmp/pytest-project"
+
+    class FakeResult:
+        returncode = 0
+        stdout = f"p100\nn{target}\n"
+
+    monkeypatch.setattr(subprocess, "run", lambda *a, **kw: FakeResult())
+    assert _get_pid_cwd("100") == target
+
+
+def test_get_pid_cwd_darwin_failure(monkeypatch):
+    """macOS: lsof failure returns None."""
+
+    class FailedResult:
+        returncode = 1
+        stdout = ""
+
+    monkeypatch.setattr(subprocess, "run", lambda *a, **kw: FailedResult())
+    assert _get_pid_cwd_darwin("999") is None
+
+
+def test_get_pid_cwd_unsupported_platform(monkeypatch):
+    """Unsupported platform returns None."""
+    monkeypatch.setattr("sys.platform", "win32")
+    assert _get_pid_cwd("100") is None
+
+
+# --- _is_zombie_linux tests --------------------------------------------
+
+
+def test_is_zombie_linux_not_zombie(monkeypatch, tmp_path):
+    """Non-zombie process returns False."""
+    status_file = tmp_path / "status"
+    status_file.write_text("Name:\tclaude\nState:\tS (sleeping)\nPid:\t42\n")
+    monkeypatch.setattr(
+        "builtins.open",
+        _fake_open_factory(str(status_file), {"/proc/42/status": str(status_file)}),
+    )
+    assert _is_zombie_linux(42) is False
+
+
+def test_is_zombie_linux_zombie(monkeypatch, tmp_path):
+    """Zombie process returns True."""
+    status_file = tmp_path / "status"
+    status_file.write_text("Name:\tclaude\nState:\tZ (zombie)\nPid:\t42\n")
+    monkeypatch.setattr(
+        "builtins.open",
+        _fake_open_factory(str(status_file), {"/proc/42/status": str(status_file)}),
+    )
+    assert _is_zombie_linux(42) is True
+
+
+def test_is_zombie_linux_no_proc(monkeypatch):
+    """Missing /proc entry returns False (not zombie, just gone)."""
+    _real_open = open
+
+    def _fake_open(path, *a, **kw):
+        if "/proc/99999/" in str(path):
+            raise FileNotFoundError(path)
+        return _real_open(path, *a, **kw)
+
+    monkeypatch.setattr("builtins.open", _fake_open)
+    assert _is_zombie_linux(99999) is False
+
+
 # --- _check_lock tests ------------------------------------------------


@@ -222,7 +342,7 @@ def test_check_lock_alive_pid(tmp_path, monkeypatch):
    lock_file = lock_dir / ".dispatch.lock"
    lock_data = {"pid": 1234, "timestamp": "2026-03-29T10:00:00"}
    lock_file.write_text(json.dumps(lock_data), encoding="utf-8")
-    monkeypatch.setattr(os, "kill", lambda pid, sig: None)
+    monkeypatch.setattr(wake_mod, "_check_pid_alive", lambda pid: True)
    result = _check_lock(tmp_path)
    assert result is not None
    assert result["pid"] == 1234
@@ -235,7 +355,7 @@ def test_check_lock_dead_pid_removes_lock(tmp_path, monkeypatch):
    lock_file = lock_dir / ".dispatch.lock"
    lock_data = {"pid": 99999, "timestamp": "2026-03-29T10:00:00"}
    lock_file.write_text(json.dumps(lock_data), encoding="utf-8")
-    monkeypatch.setattr(os, "kill", _raise_process_lookup)
+    monkeypatch.setattr(wake_mod, "_check_pid_alive", lambda pid: False)
    result = _check_lock(tmp_path)
    assert result is None
    assert not lock_file.exists()
@@ -257,6 +377,7 @@ def test_check_lock_stale_old_timestamp(tmp_path, monkeypatch):

 def test_check_lock_permission_error_treated_active(tmp_path, monkeypatch):
    """Lock PID that raises PermissionError is treated as active."""
+    monkeypatch.setattr("sys.platform", "linux")
    lock_dir = tmp_path / ".ai_mail.local"
    lock_dir.mkdir(parents=True)
    lock_file = lock_dir / ".dispatch.lock"
@@ -601,6 +722,7 @@ class TestWakeBranchSpawnEnv:

        local_bin = str(_Path.home() / ".local" / "bin")
        monkeypatch.setenv("PATH", "/usr/bin:/bin")
+        monkeypatch.delenv("INVOCATION_ID", raising=False)

        captured_envs: list = []

@@ -831,6 +953,7 @@ def _patch_wake_deps(monkeypatch, **overrides):
        monkeypatch.setattr(wake_mod, attr, val)

    monkeypatch.setattr("aipass.ai_mail.apps.handlers.dispatch.wake.time.sleep", lambda _: None)
+    monkeypatch.delenv("INVOCATION_ID", raising=False)


 class _FakeProc:
@@ -862,6 +985,57 @@ class TestWakeBranch:
        assert ok is False
        assert any(s[0] == "fail" and "resolve" in s[1] for s in status.steps)

+    # --- manager check ---
+
+    def test_manager_target_skips_wake(self, tmp_path, monkeypatch):
+        """Target with citizen_class=manager returns True (mail only, no wake)."""
+        branch_path = _make_wake_fixtures(tmp_path, monkeypatch)
+        trinity = branch_path / ".trinity"
+        trinity.mkdir(parents=True, exist_ok=True)
+        (trinity / "passport.json").write_text(
+            json.dumps({"identity": {"citizen_class": "manager"}}),
+            encoding="utf-8",
+        )
+        status, ok = wake_branch("@testbranch")
+        assert ok is True
+        assert any(s[1] == "manager" for s in status.steps)
+
+    def test_non_manager_target_continues(self, tmp_path, monkeypatch):
+        """Target with non-manager citizen_class proceeds to spawn."""
+        branch_path = _make_wake_fixtures(tmp_path, monkeypatch)
+        trinity = branch_path / ".trinity"
+        trinity.mkdir(parents=True, exist_ok=True)
+        (trinity / "passport.json").write_text(
+            json.dumps({"identity": {"citizen_class": "aipass_framework"}}),
+            encoding="utf-8",
+        )
+        _patch_wake_deps(monkeypatch, _clean_zombies=lambda: 0)
+        monkeypatch.setattr("subprocess.Popen", lambda *a, **kw: _FakeProc())
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.notify.send_notification",
+            lambda *a, **kw: None,
+            raising=False,
+        )
+        status, ok = wake_branch("@testbranch")
+        assert ok is True
+        assert not any(s[1] == "manager" for s in status.steps)
+
+    def test_missing_passport_continues(self, tmp_path, monkeypatch):
+        """No passport.json — wake proceeds normally."""
+        _make_wake_fixtures(tmp_path, monkeypatch)
+        _patch_wake_deps(monkeypatch, _clean_zombies=lambda: 0)
+        monkeypatch.setattr("subprocess.Popen", lambda *a, **kw: _FakeProc())
+        monkeypatch.setattr(
+            "aipass.ai_mail.apps.handlers.notify.send_notification",
+            lambda *a, **kw: None,
+            raising=False,
+        )
+        status, ok = wake_branch("@testbranch")
+        assert ok is True
+        assert not any(s[1] == "manager" for s in status.steps)
+
+    # --- zombie check ---
+
    def test_zombie_check_warns_but_continues(self, tmp_path, monkeypatch):
        """Zombie detected adds warning but dispatch continues."""
        _make_wake_fixtures(tmp_path, monkeypatch)
@@ -12,13 +12,13 @@ Not suggestions. Violating = bug.

 - **No writes outside own `.trinity/`.** Never create, edit, delete files anywhere else. Not code, not docs, not configs, not other branches' memories.
 - **No git. Ever.** Not `git status`, not `drone @git anything`. Git is drone's world.
- **No `drone @ai_mail dispatch`.** Email only test-convention body (below). Never wake agent real work.
+- **Dispatch focused work via `drone @ai_mail dispatch`** — to ONE owning branch, as the user's voice with detailed feedback. Reply routes to @aipass; I track the loop and report back. Not an orchestrator (no fleets, no running the floor — that's devpulse). Test-convention pings (below) still fine.
 - **No registry / hooks / bypass.json / config edits.** Spot bug → report. Never patch.
- User asks build/fix/change something: tell them who. Offer dispatch through devpulse/drone — don't do it.
+- User asks build/fix/change in another branch: name the owner, then dispatch focused work to them as the user's voice. Heavy orchestration, git, and fleets stay with devpulse.

 ## What I Do

- Guide new users through `aipass init` (12 stages: welcome, system detect, doctor, profile, style questions, tool choice, docker offer, first agent, ping sweep, smoke test, handoff, done)
+- Guide new users through `aipass init` (10 stages: welcome, system detect, profile, style questions, tool choice, first agent, ping sweep, smoke test, handoff, done)
 - Answer "how does X work?" via `aipass help` — live README reads, offer depth, route branch experts
 - Run `aipass doctor` — aggregate seedgo, pytest, registry, hooks, git state, AIPASS_HOME
 - Remember user — name, OS, preferred CLI, setup progress `.trinity/local.json`
@@ -30,7 +30,7 @@ Not suggestions. Violating = bug.
 aipass              # Help banner with all commands
 aipass help [q]     # Chatbot Q&A over branch READMEs
 aipass doctor       # System health aggregation
-aipass init         # 12-stage guided setup for new users, resumable
+aipass init         # 10-stage guided setup for new users, resumable
 aipass profile      # Show/edit what I know about the user
 aipass --version
 ```
@@ -53,7 +53,7 @@ apps/
 ├── modules/
 │   ├── doctor.py      # System health aggregation
 │   ├── help_chat.py   # README-backed Q&A
-│   ├── init_flow.py   # 12-stage guided setup, resumable
+│   ├── init_flow.py   # 10-stage guided setup, resumable
 │   ├── handoff.py     # CLI handoff (tmux / wt.exe)
 │   └── profile.py     # User profile read/write
 └── handlers/
@@ -79,6 +79,6 @@ apps/

 ## Known Gotchas

- **Status: under construction.** Whole branch gitignored. Do not PR anything this directory until Phase 8 reveal (DPLAN-0136).
+- **Status: under construction (DPLAN-0136).** Don't PR / reveal this branch until Phase 8 — that's a *policy*, NOT a gitignore. Only the usual runtime/memory layer is ignored (`.trinity/`, plan files, `*.local`, logs) same as every branch; my code (init_flow, cross_os, tests, README) IS trackable. Committed-or-not = git's call, devpulse's lane.
 - **`aipass` binary currently `cli` branch's `aipass init`** — project bootstrap, not citizen creation. Eventually this CLI entry moves here. Until then, use `drone @spawn create` citizen creation.
 - **Test-convention tokens need buy-in.** Core agents don't yet recognize `[AIPASS-TEST — ...]`. Coordinating @ai_mail before pinging anyone.
@@ -2,8 +2,8 @@
  "metadata": {
    "version": "2.0.0",
    "created": "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"
+    "description": "Bypass config for @aipass citizen. Modules operational: concierge/init/doctor/handoff/profile/install 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-07-05"
  },
  "bypass": [
    {
@@ -91,6 +91,21 @@
      "standard": "permission_flags",
      "reason": "Assertions verify that the CLI flag name appears/absent in handoff_command output. String is in assertion context only — not a permission bypass in this file."
    },
+    {
+      "file": "tests/test_install.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_install.py",
+      "standard": "encapsulation",
+      "reason": "Unit tests must import the install module directly to test home resolution, clone, and setup orchestration in isolation. Entry-point imports would defeat the purpose of unit testing."
+    },
+    {
+      "file": "tests/test_launcher.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_ping_sweep.py",
      "standard": "architecture",
@@ -271,11 +286,36 @@
      "standard": "introspection",
      "reason": "aipass is binary-invoked: aipass profile runs the command; introspection via --info"
    },
+    {
+      "file": "apps/modules/install.py",
+      "standard": "introspection",
+      "reason": "aipass is binary-invoked: bare 'aipass install' runs the bootstrap; introspection via --info (same pattern as doctor/init_flow/profile)."
+    },
+    {
+      "file": "apps/modules/install.py",
+      "standard": "modules",
+      "reason": "Thin bootstrap orchestrator — preps the target/project dir (mkdir) immediately before shelling out to git clone / setup.sh / aipass init. Pre-subprocess dir prep, not business file ops; a handler adds indirection for 2 mkdir calls in a linear flow (same pattern as init_flow/doctor)."
+    },
    {
      "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_cross_os.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_cross_os.py",
+      "standard": "encapsulation",
+      "reason": "Unit tests must import the cross_os handler directly to test the parser/filter in isolation. Entry-point imports would defeat the purpose of unit testing."
+    },
+    {
+      "file": "tests/test_cross_os.py",
+      "standard": "documentation",
+      "reason": "Test methods use descriptive names (test_filter_win32_gets_win_and_all, test_missing_doc_raises) that are self-documenting. Adding docstrings to every test function adds noise without value."
+    },
    {
      "file": "tests/test_sandbox_check.py",
      "standard": "architecture",
@@ -15,14 +15,16 @@ aipass/
 ├── apps/
 │   ├── aipass.py                          # Entry point — subcommand dispatch
 │   ├── modules/
-│   │   ├── doctor.py                      # System health aggregation
+│   │   ├── doctor.py                      # System health aggregation + cross-OS pre-flight (--cross-os)
 │   │   ├── doctor_fix.py                  # Remediation report (--fix, --json)
 │   │   ├── doctor_wire.py                 # Auto-wire provider settings + stale-deny re-export
 │   │   ├── handoff.py                     # CLI handoff (placeholder)
 │   │   ├── help_chat.py                   # README-backed Q&A (reads via readme_map handler)
-│   │   ├── init_flow.py                   # 12-stage guided setup
+│   │   ├── init_flow.py                   # 10-stage guided setup
+│   │   ├── install.py                     # aipass install — one-command bootstrap (clone + setup + init)
 │   │   └── profile.py                     # User profile read/write
 │   ├── handlers/
+│   │   ├── cross_os/                      # Cross-OS pre-flight: gap_registry, preflight, run_record
 │   │   ├── handoff_platform/              # Platform-specific handoff detection
 │   │   ├── init/                          # bootstrap.py, scaffold_content.py
 │   │   ├── json/                          # JSON read/write utilities
@@ -33,7 +35,7 @@ aipass/
 │   │   ├── system_detect/                 # OS, shell, Python, RAM, CPU
 │   │   └── ui/                            # Progress bars, menus, banners
 │   └── plugins/
-├── tests/                                 # 432 passing
+├── tests/                                 # 609 passing
 ├── requirements.project.txt               # Project-specific Python dependencies
 ├── .trinity/                              # Identity + session history + observations
 └── README.md
@@ -48,7 +50,11 @@ aipass/
 | `aipass doctor` | System health — structure, registry, hooks, pytest |
 | `aipass doctor --fix` | Remediation report with `drone @spawn repair` commands |
 | `aipass doctor --json` | JSON output for structure scan results |
-| `aipass init` | 12-stage guided setup (resumable) |
+| `aipass doctor --cross-os` | Cross-OS pre-flight (Layer-3-lite, machine) — OS-gap cross-ref + routing/versions/hookstatus |
+| `aipass doctor --cross-os --e2e` | ...also runs the real Layer-2 e2e wiring suite (heavy, opt-in) |
+| `aipass doctor --cross-os --record [PATH]` | Write a machine-filled Run Record for the human Layer-3 acceptance pass |
+| `aipass init` | 10-stage guided setup (resumable) |
+| `aipass install` | One-command bootstrap — clone + setup.sh + hooks, then hand off to init (`--no-init`/`--with-init`/`--path`/`--here`) |
 | `aipass profile` | Show/edit user profile |
 | `aipass --version` | Version |

@@ -70,7 +76,7 @@ Humans only. Nothing in AIPass depends on this branch.

 ## Tests

-432 passing — `pytest src/aipass/aipass/tests/`
+609 passing — `pytest src/aipass/aipass/tests/`

 ## Known Issues

@@ -78,4 +84,4 @@ Humans only. Nothing in AIPass depends on this branch.

 ## Last Updated

-Last Updated: 2026-06-05
+Last Updated: 2026-07-05
@@ -18,6 +18,7 @@ Auto-discovery architecture:
 import os
 import sys
 import importlib
+import importlib.metadata
 from pathlib import Path
 from typing import List, Any

@@ -43,9 +44,13 @@ from aipass.prax import logger
 MODULES_DIR = Path(__file__).parent / "modules"


+_import_failures: dict[str, Exception] = {}
+
+
 def discover_modules() -> List[Any]:
    """Auto-discover modules in modules/ directory."""
    modules = []
+    _import_failures.clear()

    if not MODULES_DIR.exists():
        return modules
@@ -62,18 +67,25 @@ def discover_modules() -> List[Any]:
                modules.append(module)
        except Exception as e:
            logger.error(f"[AIPASS] Failed to load module {module_name}: {e}")
+            _import_failures[file_path.stem] = e

    return modules


 def route_command(command: str, args: List[str], modules: List[Any]) -> bool:
-    """Route command to appropriate module."""
+    """Route command to appropriate module.
+
+    Returns True on success. Raises on handler crash so callers can
+    distinguish 'not found' (False) from 'found but broken'.
+    """
    for module in modules:
        try:
            if module.handle_command(command, args):
                return True
        except Exception as e:
-            logger.error(f"[AIPASS] Module {module.__name__} error: {e}")
+            mod_name = module.__name__.split(".")[-1]
+            logger.error(f"[AIPASS] Module {mod_name} crashed: {e}")
+            raise
    return False


@@ -88,14 +100,20 @@ def main():
    args = sys.argv[1:]

    if len(args) > 0 and args[0] in ["--version", "-V"]:
-        print("aipass 0.1.0")
+        try:
+            version = importlib.metadata.version("aipass")
+        except importlib.metadata.PackageNotFoundError:
+            logger.info("[AIPASS] Package metadata not found, version unknown")
+            version = "unknown"
+        print(f"aipass {version}")
        return 0

    show_root_help = len(args) == 0 or args[0] in ["--help", "-h"] or (args[0] == "help" and len(args) == 1)
    if show_root_help:
        print(f"AIPASS - {len(modules)} modules discovered")
        for module in modules:
-            name = module.__name__.split(".")[-1]
+            stem = module.__name__.split(".")[-1]
+            name = getattr(module, "COMMAND", stem)
            desc = (module.__doc__ or "").strip().split("\n")[0] if module.__doc__ else "No description"
            print(f"  {name:20} {desc}")
        return 0
@@ -103,8 +121,34 @@ def main():
    command = args[0]
    remaining = args[1:] if len(args) > 1 else []

-    if route_command(command, remaining, modules):
-        return 0
+    # Subcommand --help guard: intercept before dispatch
+    if remaining and remaining[0] in ("--help", "-h"):
+        for module in modules:
+            if module.handle_command(command, ["--help"]):
+                return 0
+        print(f"Unknown command: {command}")
+        return 1
+
+    try:
+        if route_command(command, remaining, modules):
+            return 0
+    except Exception as e:
+        print(f"Error: '{command}' crashed: {e}")
+        logger.error(f"[AIPASS] '{command}' traceback", exc_info=True)
+        return 1
+
+    if command.startswith("@"):
+        print(f"{command} is a drone routing target, not an aipass command.")
+        print("aipass is your front-door CLI; drone is the agent router — two separate tools.")
+        print()
+        print(f"  Reach an agent:   drone {command} ...   ·  drone systems")
+        print("  aipass commands:  aipass --help")
+        return 1
+
+    for stem, err in _import_failures.items():
+        if command in (stem, stem.replace("_", "")):
+            print(f"Error: '{command}' failed to load: {err}")
+            return 1

    print(f"Unknown command: {command}")
    return 1
@@ -0,0 +1,45 @@
+"""cross_os — gap-registry cross-reference + non-mutating pre-flight runners."""
+
+from aipass.aipass.apps.handlers.cross_os.gap_registry import (  # type: ignore[import-not-found]
+    CrossOsGap,
+    CrossOsGapError,
+    find_gap_doc,
+    gaps_for_platform,
+    load_gaps,
+    os_matches,
+    parse_gap_registry,
+)
+from aipass.aipass.apps.handlers.cross_os.preflight import (  # type: ignore[import-not-found]
+    PreflightResult,
+    check_hookstatus,
+    check_routing,
+    check_versions,
+    find_e2e_dir,
+    run_e2e,
+)
+from aipass.aipass.apps.handlers.cross_os.run_record import (  # type: ignore[import-not-found]
+    RunRecordError,
+    build_run_record,
+    default_record_path,
+    generate_run_record,
+)
+
+__all__ = [
+    "CrossOsGap",
+    "CrossOsGapError",
+    "PreflightResult",
+    "RunRecordError",
+    "build_run_record",
+    "check_hookstatus",
+    "check_routing",
+    "check_versions",
+    "default_record_path",
+    "find_e2e_dir",
+    "find_gap_doc",
+    "gaps_for_platform",
+    "generate_run_record",
+    "load_gaps",
+    "os_matches",
+    "parse_gap_registry",
+    "run_e2e",
+]
@@ -0,0 +1,167 @@
+# =================== AIPass ====================
+# Name: gap_registry.py
+# Description: Live-parse the cross-OS gap registry and filter by platform
+# Version: 1.0.0
+# Created: 2026-07-02
+# Modified: 2026-07-02
+# =============================================
+
+"""Cross-OS gap registry parser — Layer-3-lite pre-flight source.
+
+Live-reads ``tests/CROSS_OS_TESTING.md`` (read-only to @aipass), parses the
+"Known cross-OS gap registry" markdown table, and filters rows to the running
+platform. This is a *machine pre-flight* — it surfaces tracked OS-specific gaps
+for the box the user is on. It NEVER claims the checklist's human acceptance
+green ("you watched it work on that OS").
+
+Fail-to-error contract: if the doc is missing, the section is absent, or no data
+rows can be parsed, functions raise ``CrossOsGapError`` — they never silently
+return "no gaps". Callers must surface the error as a WARN/FAIL, not swallow it.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import List, NamedTuple
+
+from aipass.prax import logger
+from aipass.aipass.apps.handlers.json import json_handler
+
+# Path of the source-of-truth doc, relative to the repo root.
+DOC_RELATIVE = Path("tests") / "CROSS_OS_TESTING.md"
+
+# Case-insensitive marker identifying the registry section header line.
+_SECTION_MARKER = "known cross-os gap registry"
+
+# Expected column count in the registry table: # | Gap | OS | Symptom | Owner | Status
+_EXPECTED_COLUMNS = 6
+
+
+class CrossOsGapError(RuntimeError):
+    """Raised when the cross-OS gap registry cannot be located or parsed."""
+
+
+class CrossOsGap(NamedTuple):
+    """One row of the Known cross-OS gap registry table."""
+
+    number: str
+    gap: str
+    os: str
+    symptom: str
+    owner: str
+    status: str
+
+
+def find_gap_doc(start: Path | None = None) -> Path:
+    """Search upward from ``start`` (or this file) for ``tests/CROSS_OS_TESTING.md``.
+
+    Portable — derives the repo root by walking ancestors rather than hardcoding
+    an absolute path.
+
+    Raises:
+        CrossOsGapError: if the doc is not found in any ancestor directory.
+    """
+    base = (start or Path(__file__)).resolve()
+    for parent in [base, *base.parents]:
+        candidate = parent / DOC_RELATIVE
+        if candidate.is_file():
+            return candidate
+    raise CrossOsGapError(f"cross-OS testing doc not found (searched upward from {base} for {DOC_RELATIVE})")
+
+
+def parse_gap_registry(text: str) -> List[CrossOsGap]:
+    """Parse the 'Known cross-OS gap registry' table out of the doc text.
+
+    Only rows whose first cell begins with a digit are treated as data rows,
+    which naturally skips the header and the ``|---|`` separator.
+
+    Raises:
+        CrossOsGapError: if the section is missing or no data rows parse.
+    """
+    lines = text.splitlines()
+
+    section_idx = None
+    for i, line in enumerate(lines):
+        if line.lstrip().startswith("#") and _SECTION_MARKER in line.lower():
+            section_idx = i
+            break
+    if section_idx is None:
+        raise CrossOsGapError("'Known cross-OS gap registry' section not found in doc")
+
+    gaps: List[CrossOsGap] = []
+    for line in lines[section_idx + 1 :]:
+        stripped = line.strip()
+        # Stop at the next top-level section.
+        if stripped.startswith("## "):
+            break
+        if not stripped.startswith("|"):
+            continue
+        cells = [c.strip() for c in stripped.strip("|").split("|")]
+        if len(cells) < _EXPECTED_COLUMNS:
+            continue
+        number = cells[0]
+        # Skip header ("#") and separator ("---") rows — data rows start with a digit.
+        if not number or not number[0].isdigit():
+            continue
+        gaps.append(
+            CrossOsGap(
+                number=number,
+                gap=cells[1],
+                os=cells[2],
+                symptom=cells[3],
+                owner=cells[4],
+                status=cells[5],
+            )
+        )
+
+    if not gaps:
+        raise CrossOsGapError("gap registry table found but no data rows could be parsed")
+    return gaps
+
+
+def load_gaps(start: Path | None = None) -> List[CrossOsGap]:
+    """Locate, read, and parse the full gap registry.
+
+    Raises:
+        CrossOsGapError: on missing/unreadable doc or unparseable table.
+    """
+    doc = find_gap_doc(start)
+    try:
+        raw = doc.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise CrossOsGapError(f"cross-OS testing doc unreadable at {doc}: {exc}") from exc
+    logger.info("[cross_os] parsing gap registry from %s", doc)
+    return parse_gap_registry(raw)
+
+
+def os_matches(os_cell: str, platform_name: str) -> bool:
+    """Return True if an OS cell applies to ``platform_name`` (a ``sys.platform`` value).
+
+    Mapping (case-insensitive): 'all' matches every platform; 'win' matches
+    win32; 'mac' matches darwin. So 'Win/mac' matches both win32 and darwin.
+    """
+    cell = os_cell.lower()
+    if "all" in cell:
+        return True
+    if platform_name == "win32":
+        return "win" in cell
+    if platform_name == "darwin":
+        return "mac" in cell
+    return False
+
+
+def gaps_for_platform(platform_name: str | None = None, start: Path | None = None) -> List[CrossOsGap]:
+    """Return only the gap rows relevant to ``platform_name`` (defaults to ``sys.platform``).
+
+    Raises:
+        CrossOsGapError: on any load/parse failure (never silently empty).
+    """
+    plat = platform_name or sys.platform
+    gaps = load_gaps(start)
+    relevant = [g for g in gaps if os_matches(g.os, plat)]
+    json_handler.log_operation(
+        "cross_os_gap_lookup",
+        {"platform": plat, "total": len(gaps), "relevant": len(relevant)},
+    )
+    return relevant
@@ -0,0 +1,230 @@
+# =================== AIPass ====================
+# Name: preflight.py
+# Description: Non-mutating cross-OS pre-flight runners (routing/version/hooks/e2e)
+# Version: 1.0.0
+# Created: 2026-07-02
+# Modified: 2026-07-02
+# =============================================
+
+"""Cross-OS pre-flight runners — Layer-3-lite machine checks.
+
+Each runner probes one machine-provable slice of the cross-OS acceptance
+checklist and returns a small ``PreflightResult(name, ok, detail)``. Everything
+here is *non-mutating* and NEVER wakes a citizen: the drone routes exercised
+(``drone systems``, ``drone @ai_mail --help``, ``drone @hooks status``) only
+print/route — they do not dispatch work to a branch.
+
+Robustness contract: every subprocess has a timeout and every runner catches
+``FileNotFoundError`` / ``TimeoutExpired`` (and other ``OSError``) and turns it
+into ``ok=False`` with a clear ``detail`` — a runner never crashes the caller.
+
+These are pre-flight rows. They can NEVER claim the checklist's human green
+("you watched it work on that OS"); callers must label them pre-flight.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, NamedTuple, Sequence, Tuple
+
+from aipass.prax import logger
+from aipass.aipass.apps.handlers.json import json_handler
+
+# Directory (relative to repo root) holding the Layer-2 e2e wiring suite.
+E2E_RELATIVE = Path("tests") / "e2e"
+
+# Subprocess timeouts (seconds). Light routes are quick; e2e is heavy (it builds
+# a wheel and installs it into a fresh venv) so it gets a generous budget.
+_ROUTE_TIMEOUT = 20
+_VERSION_TIMEOUT = 15
+_HOOKSTATUS_TIMEOUT = 20
+_E2E_TIMEOUT = 600
+
+# Detail prefix marking an e2e result that could NOT run (infra), so callers can
+# map it to WARN rather than FAIL. Real pytest failures do not use this prefix.
+E2E_UNRUNNABLE_PREFIX = "could not run"
+
+
+class PreflightResult(NamedTuple):
+    """One non-mutating pre-flight probe outcome."""
+
+    name: str
+    ok: bool
+    detail: str
+
+
+def _run(cmd: Sequence[str], timeout: int, cwd: str | None = None) -> Tuple[int | None, str]:
+    """Run ``cmd`` non-interactively; return ``(returncode, combined_output)``.
+
+    Never raises for the expected failure modes: a missing binary yields
+    ``(None, "not found: ...")`` and a timeout yields ``(None, "timed out ...")``.
+    """
+    try:
+        proc = subprocess.run(
+            list(cmd),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=cwd,
+        )
+        return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+    except FileNotFoundError as exc:
+        logger.warning("[cross_os.preflight] binary not found for %s: %s", cmd, exc)
+        return None, f"not found: {cmd[0]}"
+    except subprocess.TimeoutExpired as exc:
+        logger.warning("[cross_os.preflight] %s timed out after %ss: %s", cmd, timeout, exc)
+        return None, f"timed out after {timeout}s"
+    except OSError as exc:
+        logger.warning("[cross_os.preflight] error running %s: %s", cmd, exc)
+        return None, f"error running {cmd[0]}: {exc}"
+
+
+def _first_line(output: str) -> str:
+    """Return the first non-empty stripped line of ``output`` (or "")."""
+    for line in output.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def check_routing() -> PreflightResult:
+    """Verify drone routing (Phase 4): ``drone systems`` + one subprocess route.
+
+    Both ``drone systems`` (4.1) and ``drone @ai_mail --help`` (4.2) must exit 0.
+    These are non-mutating routes — ``--help`` prints usage; neither dispatches
+    work to a citizen.
+    """
+    sys_rc, sys_out = _run(["drone", "systems"], _ROUTE_TIMEOUT)
+    route_rc, route_out = _run(["drone", "@ai_mail", "--help"], _ROUTE_TIMEOUT)
+
+    ok = sys_rc == 0 and route_rc == 0
+    if ok:
+        detail = "drone systems exit 0; @ai_mail route exit 0"
+    else:
+        problems: List[str] = []
+        if sys_rc != 0:
+            problems.append(f"drone systems -> {sys_rc or _first_line(sys_out)}")
+        if route_rc != 0:
+            problems.append(f"@ai_mail --help -> {route_rc or _first_line(route_out)}")
+        detail = "; ".join(problems)
+    return PreflightResult("routing", ok, detail)
+
+
+def check_versions() -> PreflightResult:
+    """Verify ``drone --version`` and ``aipass --version`` exit 0 (Phase 1.3).
+
+    Captures the version strings into the detail.
+    """
+    drone_rc, drone_out = _run(["drone", "--version"], _VERSION_TIMEOUT)
+    aipass_rc, aipass_out = _run(["aipass", "--version"], _VERSION_TIMEOUT)
+
+    def _ver(label: str, rc: int | None, out: str) -> str:
+        if rc == 0:
+            return _first_line(out)
+        return f"{label} --version failed ({rc}: {_first_line(out)})"
+
+    ok = drone_rc == 0 and aipass_rc == 0
+    detail = f"{_ver('drone', drone_rc, drone_out)}; {_ver('aipass', aipass_rc, aipass_out)}"
+    return PreflightResult("versions", ok, detail)
+
+
+def check_hookstatus() -> PreflightResult:
+    """Verify the @hooks per-project config renders (Phase 6.3).
+
+    Note: the checklist labels this ``drone @hooks hookstatus``, but that command
+    name does not route on the current drone build (it returns "Unknown command"
+    — gap #9 in the wild). The real, non-mutating subcommand that renders the
+    per-project hook config is ``drone @hooks status``, which is what Phase 6.3
+    actually verifies, so that is what we probe.
+    """
+    rc, out = _run(["drone", "@hooks", "status"], _HOOKSTATUS_TIMEOUT)
+    ok = rc == 0
+    detail = _first_line(out) if ok else f"drone @hooks status exit {rc}: {_first_line(out)}"
+    return PreflightResult("hookstatus", ok, detail)
+
+
+def find_e2e_dir(start: Path | None = None) -> Path | None:
+    """Search upward from ``start`` (or this file) for ``tests/e2e``.
+
+    Portable — walks ancestors rather than hardcoding a path (mirrors the
+    gap_registry ``find_gap_doc`` pattern). Returns ``None`` if not found.
+    """
+    base = (start or Path(__file__)).resolve()
+    for parent in [base, *base.parents]:
+        candidate = parent / E2E_RELATIVE
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def _resolve_pytest(repo_root: Path) -> Tuple[List[str], str] | None:
+    """Resolve a pytest invocation for the current box.
+
+    Prefers ``<repo>/.venv/<bin>/pytest`` (system ``python`` may be absent);
+    falls back to ``sys.executable -m pytest``. Returns ``(argv_prefix, source)``
+    or ``None`` if neither can be resolved.
+    """
+    bin_dir = "Scripts" if os.name == "nt" else "bin"
+    exe = "pytest.exe" if os.name == "nt" else "pytest"
+    venv_pytest = repo_root / ".venv" / bin_dir / exe
+    if venv_pytest.is_file():
+        return [str(venv_pytest)], "venv pytest"
+    if sys.executable:
+        return [sys.executable, "-m", "pytest"], "sys.executable -m pytest"
+    return None
+
+
+def run_e2e(start: Path | None = None) -> PreflightResult:
+    """Run the Layer-2 e2e wiring suite (``pytest tests/e2e -q``). HEAVY.
+
+    Only call this when explicitly opted into (``--e2e``): the suite builds the
+    aipass wheel and installs it into a fresh venv. ``ok=True`` only when every
+    test passes (pytest exit 0). Un-runnable cases (dir missing, no pytest,
+    timeout, crash) return ``ok=False`` with a ``could not run`` detail so the
+    caller can render them as WARN rather than a hard FAIL.
+    """
+    e2e_dir = find_e2e_dir(start)
+    if e2e_dir is None:
+        return PreflightResult("e2e", False, f"{E2E_UNRUNNABLE_PREFIX}: e2e dir not found")
+
+    repo_root = e2e_dir.parent.parent
+    resolved = _resolve_pytest(repo_root)
+    if resolved is None:
+        detail = f"{E2E_UNRUNNABLE_PREFIX}: pytest unavailable (no venv pytest, no interpreter)"
+        return _log_e2e(PreflightResult("e2e", False, detail))
+
+    argv_prefix, source = resolved
+    logger.info("[cross_os.preflight] running e2e suite via %s (cwd=%s)", source, repo_root)
+    rc, out = _run([*argv_prefix, str(e2e_dir), "-q"], _E2E_TIMEOUT, cwd=str(repo_root))
+
+    if rc is None:
+        # Timeout / missing binary / OSError — infra, not a real test failure.
+        return _log_e2e(PreflightResult("e2e", False, f"{E2E_UNRUNNABLE_PREFIX}: {out}"))
+
+    summary = _e2e_summary(out)
+    if rc == 0:
+        return _log_e2e(PreflightResult("e2e", True, summary))
+    # Non-zero: could be real failures OR pytest itself being absent under
+    # `python -m pytest`. Distinguish so the caller can WARN vs FAIL.
+    if "no module named pytest" in out.lower():
+        return _log_e2e(PreflightResult("e2e", False, f"{E2E_UNRUNNABLE_PREFIX}: pytest not importable"))
+    return _log_e2e(PreflightResult("e2e", False, summary))
+
+
+def _log_e2e(result: PreflightResult) -> PreflightResult:
+    """Record the e2e pre-flight outcome via json_handler, then return it."""
+    json_handler.log_operation("cross_os_e2e_preflight", {"ok": result.ok, "detail": result.detail})
+    return result
+
+
+def _e2e_summary(output: str) -> str:
+    """Extract pytest's terminal summary line (e.g. '14 passed', '2 failed...')."""
+    for line in reversed(output.splitlines()):
+        stripped = line.strip().strip("=").strip()
+        if any(tok in stripped for tok in ("passed", "failed", "error", "no tests ran")):
+            return stripped
+    return _first_line(output) or "no pytest summary parsed"
@@ -0,0 +1,243 @@
+# =================== AIPass ====================
+# Name: run_record.py
+# Description: Machine pre-flight Run Record generator for the cross-OS checklist
+# Version: 1.0.0
+# Created: 2026-07-02
+# Modified: 2026-07-02
+# =============================================
+
+"""Cross-OS Run Record generator — Layer-3-lite machine pre-flight DRAFT.
+
+Emits a text Run Record block modelled on the "## Run Record" fenced template in
+``tests/CROSS_OS_TESTING.md`` (that block is the format source-of-truth). The
+block is *constructed in code* rather than string-substituted into the parsed
+template on purpose: the load-bearing invariant here is the machine/human
+boundary — the machine fills ONLY what it can prove (env facts + the
+non-mutating pre-flight rows) and every human-only row (clean install,
+interactive init, daemons, audible sound, PTY, per-branch matrix, overall
+verdict, commit, tester) is left blank or marked ``— human``. Constructing the
+block gives exact control over that boundary; substituting values line-by-line
+into the free-text template would be brittle and could silently tick a human row.
+
+Env facts are detected with stdlib (``platform`` / ``os``) directly — the same
+detection ``system_detector`` performs — because the seedgo cross-handler rule
+forbids this handler importing another handler.
+
+A machine can NEVER claim the checklist's human green ("you watched it work on
+that OS"). This artifact is explicitly a pre-flight DRAFT that a person must
+complete by running the real Layer-3 acceptance pass.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import List
+
+from aipass.prax import logger
+from aipass.aipass.shared.registry_discovery import find_registry
+
+from aipass.aipass.apps.handlers.cross_os.gap_registry import CrossOsGapError, gaps_for_platform
+from aipass.aipass.apps.handlers.cross_os.preflight import (
+    E2E_UNRUNNABLE_PREFIX,
+    check_hookstatus,
+    check_routing,
+    run_e2e,
+)
+from aipass.aipass.apps.handlers.json import json_handler
+
+# Marker glyphs for the record. Match the doc's Run Record block, which uses the
+# ✅ / ❌ emoji rather than the terminal ✓ / ✗ glyphs.
+_PASS = "✅"
+_FAIL = "❌"
+# Un-ticked human box — a person must still run and mark the real pass.
+_HUMAN = "⬜ — human"
+
+# Horizontal rule used by the doc's Run Record block.
+_RULE = "─────────────────────────────────────────────"
+
+
+class RunRecordError(RuntimeError):
+    """Raised when the Run Record file cannot be written."""
+
+
+def _os_name() -> str:
+    """OS family name (e.g. 'Linux', 'Darwin', 'Windows')."""
+    return platform.system() or "unknown"
+
+
+def _resolve_aipass_home() -> str:
+    """Resolve AIPASS_HOME from the env, else the discovered registry parent.
+
+    Returns "" (blank) if neither is available — a blank row is honest; we never
+    invent a path.
+    """
+    home = os.environ.get("AIPASS_HOME", "").strip()
+    if home:
+        return home
+    registry = find_registry(package_root=str(Path(__file__).resolve().parent))
+    if registry.exists():
+        return str(registry.parent)
+    return ""
+
+
+def _env_lines() -> List[str]:
+    """Build the machine-auto-filled environment header lines (Phase 0 facts)."""
+    os_desc = f"{_os_name()} {platform.release()}".strip()
+    shell_path = os.environ.get("SHELL", "")
+    shell_name = Path(shell_path).name if shell_path else "unknown"
+    term = os.environ.get("TERM", "").strip() or "unknown"
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    return [
+        "AIPass Cross-OS Run Record",
+        f"Machine/VM   : {platform.node() or 'unknown'}",
+        f"OS + version : {os_desc}",
+        f"Arch         : {platform.machine() or 'unknown'}",
+        f"Python       : {platform.python_version()}",
+        f"Shell / term : {shell_name} / {term}",
+        f"AIPASS_HOME  : {_resolve_aipass_home()}",
+        # Commit stays blank — no git here; a human fills it (hint inline).
+        "Commit (drone @git log -1) :            ← fill via drone @git log -1",
+        # Tester stays blank (human); Date is machine-knowable.
+        f"Tester       :            Date : {today}",
+    ]
+
+
+def _verdict(ok: bool) -> str:
+    """Map a pre-flight boolean to the machine glyph + a pre-flight label."""
+    glyph = _PASS if ok else _FAIL
+    return f"{glyph} pre-flight (machine)"
+
+
+def _phase2_line(run_heavy_e2e: bool) -> str:
+    """Phase 2 (e2e) line — only auto-filled when the heavy suite was opted into."""
+    label = "Phase 2 e2e suite (14/14) ...."
+    if not run_heavy_e2e:
+        return f"{label} {_HUMAN}   notes: — not run (pass --e2e to run it)"
+    result = run_e2e()
+    if result.ok:
+        return f"{label} {_verdict(True)}   notes: {result.detail}"
+    if result.detail.startswith(E2E_UNRUNNABLE_PREFIX):
+        # Infra could not run the suite — WARN-ish, not a proven fail.
+        return f"{label} ⚠️ could not run (machine)   notes: {result.detail}"
+    return f"{label} {_verdict(False)}   notes: {result.detail}"
+
+
+def _phase_lines(run_heavy_e2e: bool) -> List[str]:
+    """Build the Phase 0–7 + per-branch lines, machine-proving only what it can."""
+    routing = check_routing()
+    hooks = check_hookstatus()
+
+    return [
+        # Phase 0 — the machine captured the env above, so this is proven.
+        f"Phase 0 env capture .......... {_verdict(True)}   notes: captured above",
+        # Phase 1 — clean install (setup.sh / .venv) is pre-init + human.
+        f"Phase 1 clean install ........ {_HUMAN}   notes:",
+        _phase2_line(run_heavy_e2e),
+        # Phase 3 — real scaffold + interactive init is human (PTY).
+        f"Phase 3 aipass init .......... {_HUMAN}   notes:",
+        # Phase 4 — drone routing is non-mutating and machine-provable.
+        f"Phase 4 drone routing ........ {_verdict(routing.ok)}   notes: {routing.detail}",
+        # Phase 5 — daemons (os.kill / start_new_session) are mutating + human.
+        f"Phase 5 daemons .............. {_HUMAN}   notes:",
+        # Phase 6 — hookstatus config renders (machine); audible sound is human.
+        f"Phase 6 hooks + sound ........ {_verdict(hooks.ok)} hookstatus; 🔊 sound {_HUMAN}   notes: {hooks.detail}",
+        # Phase 7 — interactive PTY layer is human-only.
+        f"Phase 7 interactive .......... {_HUMAN}   notes:",
+        # Per-branch smoke matrix is a human pass.
+        f"Per-branch matrix (13) ....... {_HUMAN}   reds:",
+    ]
+
+
+def _watch_lines(platform_name: str) -> List[str]:
+    """Build the tracked-gap watch-item lines for this platform.
+
+    Reads the live gap registry; on any registry error, degrades to a single
+    note line (never crashes the record — it is primarily an env artifact).
+    """
+    lines = ["Watch items (tracked cross-OS gaps for this platform):"]
+    try:
+        gaps = gaps_for_platform(platform_name)
+    except CrossOsGapError as exc:
+        logger.warning("[cross_os.run_record] gap registry unavailable: %s", exc)
+        lines.append(f"  - registry unavailable — {exc}")
+        return lines
+
+    if not gaps:
+        lines.append(f"  - none tracked for {platform_name}")
+        return lines
+
+    for gap in gaps:
+        lines.append(f"  - gap #{gap.number} [{gap.status}] {gap.symptom} — owner {gap.owner}")
+    return lines
+
+
+def build_run_record(run_heavy_e2e: bool = False, platform_name: str | None = None) -> str:
+    """Build the full machine pre-flight Run Record text block.
+
+    Auto-fills the env header + the machine-provable phase rows (0/4/6, plus 2
+    when ``run_heavy_e2e``); leaves every human-only row blank/marked. The output
+    mirrors the "## Run Record" template in tests/CROSS_OS_TESTING.md.
+    """
+    plat = platform_name or sys.platform
+
+    header = [
+        "NOTE: machine pre-flight DRAFT — rows marked '(machine)' are auto-captured pre-flight",
+        "only; they are NOT the checklist's human green. A human must complete every '— human'",
+        "row and run the real Layer-3 acceptance pass before this record counts.",
+        "",
+    ]
+
+    body: List[str] = []
+    body.append(_RULE)
+    body.extend(_env_lines())
+    body.append(_RULE)
+    body.extend(_phase_lines(run_heavy_e2e))
+    body.append(_RULE)
+    body.extend(_watch_lines(plat))
+    body.append("")
+    body.append("New gaps found (file + assign):")
+    body.append("")
+    body.append(f"Overall verdict: {_HUMAN} (PASS / PARTIAL / FAIL — after the real pass)")
+    body.append(_RULE)
+
+    return "\n".join([*header, *body]) + "\n"
+
+
+def default_record_path() -> Path:
+    """Return the default record path in CWD (mirrors the doc's log naming)."""
+    return Path.cwd() / f"aipass-crossos-record-{_os_name().lower()}.txt"
+
+
+def generate_run_record(path: str | None = None, run_heavy_e2e: bool = False) -> Path:
+    """Build and write the Run Record; return the written path.
+
+    Args:
+        path: Destination file (``--record`` value). If None, a sensible default
+            in CWD is used.
+        run_heavy_e2e: When True, run and record the heavy Phase-2 e2e result.
+
+    Raises:
+        RunRecordError: if the file cannot be written (OSError) — never crashes.
+    """
+    content = build_run_record(run_heavy_e2e=run_heavy_e2e)
+    target = Path(path) if path else default_record_path()
+    try:
+        parent = target.parent
+        if parent and not parent.exists():
+            parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        logger.error("[cross_os.run_record] could not write record to %s: %s", target, exc)
+        raise RunRecordError(f"could not write Run Record to {target}: {exc}") from exc
+
+    json_handler.log_operation(
+        "cross_os_run_record",
+        {"path": str(target), "e2e": run_heavy_e2e},
+    )
+    logger.info("[cross_os.run_record] wrote machine pre-flight record to %s", target)
+    return target
@@ -11,7 +11,8 @@ 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
@@ -32,8 +33,10 @@ RULES:
 import importlib.util
 import json
 import logging
+import os
 import re
 import shutil
+import tempfile
 import uuid
 from datetime import date
 from pathlib import Path
@@ -42,6 +45,29 @@ from aipass.aipass.apps.handlers.init import scaffold_content as sc

 logger = logging.getLogger(__name__)

+_STALE_MANAGED_FILES: list[Path] = [
+    Path(".aipass") / "aipass_global_prompt.md",
+]
+
+
+def is_throwaway_path(path: str | Path) -> bool:
+    """True if path is under a temp dir or Claude Code scratchpad."""
+    resolved = str(Path(path).resolve())
+    tmp_roots = [tempfile.gettempdir()]
+    if os.name == "posix":
+        tmp_roots.append("/tmp")
+    for root in tmp_roots:
+        try:
+            r = str(Path(root).resolve())
+        except OSError:
+            logger.info("is_throwaway_path: could not resolve %s", root)
+            continue
+        if resolved == r or resolved.startswith(r + os.sep):
+            return True
+    if "scratchpad" in resolved.lower():
+        return True
+    return False
+

 def _sanitize_name(raw: str) -> str:
    """Sanitize a project name for use in filenames.
@@ -69,14 +95,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 = []
@@ -218,8 +236,13 @@ def _claude_settings(aipass_home: str | None = None) -> str:
        ],
    }

-    if aipass_home:
+    if aipass_home and not is_throwaway_path(aipass_home):
        data["env"] = {"AIPASS_HOME": aipass_home}
+    elif aipass_home:
+        logger.warning(
+            "AIPASS_HOME '%s' is a throwaway path — not writing to settings",
+            aipass_home,
+        )
    return json.dumps(data, indent=2, ensure_ascii=False) + "\n"


@@ -323,10 +346,14 @@ 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"
@@ -477,6 +504,7 @@ def update_project(target: Path) -> dict:
    updated: list[str] = []
    already_current: list[str] = []
    skipped: list[str] = []
+    removed: list[str] = []
    aipass_home: str | None = None

    # Managed directories — create if missing (graceful recovery).
@@ -488,14 +516,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"
@@ -591,11 +626,20 @@ def update_project(target: Path) -> dict:
            venv_link.symlink_to(aipass_venv)
            updated.append(f".venv (symlink to AIPass runtime: {aipass_venv})")

+    # --- Cruft cleanup: remove known-stale AIPass-managed artifacts ---
+    for rel in _STALE_MANAGED_FILES:
+        stale_path = target / rel
+        if stale_path.is_file():
+            stale_path.unlink()
+            removed.append(str(stale_path))
+            logger.info("Removed stale managed file: %s", stale_path)
+
    return {
        "project_name": name,
        "target": str(target),
        "updated_files": updated,
        "already_current": already_current,
        "skipped_files": skipped,
+        "removed_files": removed,
        "aipass_home": aipass_home,
    }
@@ -0,0 +1,155 @@
+# =================== AIPass ====================
+# Name: provider_wire.py
+# Description: Auto-wire provider settings from manifest into user config
+# Version: 1.0.0
+# Created: 2026-07-11
+# Modified: 2026-07-11
+# =============================================
+
+"""provider_wire — auto-wire provider settings.
+
+Implements the additive merge of manifest into ~/.claude/settings.json.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List
+
+from aipass.aipass.apps.handlers.json import json_handler
+
+# =============================================================================
+# HOOK & ENV DESCRIPTIONS
+# =============================================================================
+
+HOOK_DESCRIPTIONS: Dict[str, str] = {
+    "pre_edit_gate.py": "blocks edits outside agent's branch",
+    "subagent_stop_gate.py": "validates agent output on exit",
+    "auto_fix_diagnostics.py": "auto-fixes lint issues after edits",
+    "global_prompt_loader.py": "injects branch context on each turn",
+    "identity_injector.py": "injects agent identity on each turn",
+    "email_notification.py": "notifies on incoming agent mail",
+    "branch_prompt_loader.py": "loads branch-specific prompts",
+    "pre_compact.py": "saves state before context compaction",
+}
+
+ENV_DESCRIPTIONS: Dict[str, str] = {
+    "AIPASS_HOME": "tells agents where AIPass lives",
+    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "prevents conflict with .trinity/ memory system",
+}
+
+
+# =============================================================================
+# AUTO-WIRE
+# =============================================================================
+
+
+def auto_wire_provider(manifest_path: Path, interactive: bool = True) -> List[str]:
+    """Auto-wire provider settings from manifest into ~/.claude/settings.json.
+
+    Additive merge only — never removes or overwrites existing keys/values.
+    Returns list of action descriptions (for logging/display).
+    """
+    actions: List[str] = []
+
+    manifest = json_handler.load_path(manifest_path)
+    if manifest is None:
+        return actions
+    claude_section = manifest.get("cli", {}).get("claude", {})
+    if not claude_section:
+        return actions
+
+    settings_path = Path.home() / ".claude" / "settings.json"
+    if settings_path.exists():
+        settings = json_handler.load_path(settings_path) or {}
+    else:
+        settings = {}
+
+    if settings_path.exists():
+        date_stamp = datetime.now(tz=timezone.utc).strftime("%Y-%m-%d")
+        backup_path = settings_path.with_suffix(f".json.bak.{date_stamp}")
+        shutil.copy2(settings_path, backup_path)
+        actions.append(f"Backed up settings to {backup_path.name}")
+
+    manifest_hooks = claude_section.get("hooks", [])
+
+    for hook in manifest_hooks:
+        command = hook.get("command", "")
+        event = hook.get("event", "")
+        if not command or not event:
+            continue
+
+        if "hooks" not in settings:
+            settings["hooks"] = {}
+        if event not in settings["hooks"]:
+            settings["hooks"][event] = []
+        event_hooks = settings["hooks"][event]
+        if not isinstance(event_hooks, list):
+            event_hooks = [event_hooks]
+            settings["hooks"][event] = event_hooks
+
+        hook_matcher = hook.get("matcher", "")
+        already_wired = any(
+            isinstance(h, dict) and command in json.dumps(h) and h.get("matcher", "") == hook_matcher
+            for h in event_hooks
+        )
+        if not already_wired:
+            cmd_entry: Dict[str, object] = {
+                "type": "command",
+                "command": command,
+            }
+            if hook.get("timeout"):
+                cmd_entry["timeout"] = hook["timeout"]
+            wrapper: Dict[str, object] = {}
+            if hook.get("matcher"):
+                wrapper["matcher"] = hook["matcher"]
+            wrapper["hooks"] = [cmd_entry]
+            event_hooks.append(wrapper)
+            label = command.rsplit(" ", 1)[-1] if " " in command else command
+            actions.append(f"Wired hook {label} -> {event}")
+
+    manifest_env = claude_section.get("env", {})
+    if manifest_env:
+        if "env" not in settings:
+            settings["env"] = {}
+        repo_root = str(manifest_path.parent.parent)
+        project_root = str(Path.cwd())
+        for key, value in manifest_env.items():
+            if key not in settings["env"]:
+                resolved = value.replace("{{REPO_ROOT}}", repo_root)
+                resolved = resolved.replace("{{PROJECT_ROOT}}", project_root)
+                settings["env"][key] = resolved
+                actions.append(f"Set env {key}={resolved}")
+
+    manifest_perms = claude_section.get("permissions", {})
+    manifest_deny = manifest_perms.get("deny", [])
+    manifest_ask = manifest_perms.get("ask", [])
+
+    if manifest_deny or manifest_ask:
+        if "permissions" not in settings:
+            settings["permissions"] = {}
+        if "deny" not in settings["permissions"]:
+            settings["permissions"]["deny"] = []
+        if "ask" not in settings["permissions"]:
+            settings["permissions"]["ask"] = []
+
+        existing_deny = set(settings["permissions"]["deny"])
+        for rule in manifest_deny:
+            if rule not in existing_deny:
+                settings["permissions"]["deny"].append(rule)
+                actions.append(f"Added deny rule: {rule}")
+
+        existing_ask = set(settings["permissions"]["ask"])
+        for rule in manifest_ask:
+            if rule not in existing_ask:
+                settings["permissions"]["ask"].append(rule)
+                actions.append(f"Added ask rule: {rule}")
+
+    json_handler.save_path(settings_path, settings)
+    actions.append("Updated ~/.claude/settings.json")
+
+    json_handler.log_operation("auto_wire_provider", {"actions": len(actions)})
+    return actions
@@ -1,9 +1,9 @@
 # =================== AIPass ====================
 # Name: progress.py
-# Description: Rich progress and glyph helpers for aipass doctor
-# Version: 1.0.0
+# Description: Rich progress and glyph helpers for aipass doctor + init
+# Version: 1.1.0
 # Created: 2026-04-16
-# Modified: 2026-04-16
+# Modified: 2026-07-05
 # =============================================

 """
@@ -15,6 +15,9 @@ No bare print() — all output via logger or caller's console.

 from __future__ import annotations

+from contextlib import contextmanager
+from typing import Iterator
+
 from rich.progress import Progress, SpinnerColumn, TextColumn

 from aipass.aipass.apps.handlers.json import json_handler
@@ -49,6 +52,26 @@ def make_doctor_progress() -> Progress:
    )


+@contextmanager
+def activity_spinner(description: str) -> Iterator[Progress]:
+    """Transient spinner for a blocking, non-streaming action.
+
+    Wrap Python work that would otherwise look frozen — scaffold build, ping
+    sweep — so the user sees it is alive. Do NOT wrap a subprocess that streams
+    its own output to the terminal (installer, spawn): the two renderers fight.
+    Yields the Progress so a caller can retitle the task mid-flight if needed.
+
+    Args:
+        description: What is happening, e.g. "Building project scaffold…".
+    """
+    logger.info("[progress] activity spinner: %s", description)
+    json_handler.log_operation("activity_spinner", {"description": description})
+    prog = Progress(SpinnerColumn(), TextColumn("{task.description}"), transient=True)
+    with prog:
+        prog.add_task(description, total=None)
+        yield prog
+
+
 # =============================================================================
 # CHECK FORMATTER
 # =============================================================================
@@ -81,3 +104,26 @@ def format_check(
        line = f"{line}\n{indent}[dim yellow]{remediation}[/dim yellow]"

    return line
+
+
+def render_step_header(current: int, total: int, label: str, width: int = 18) -> str:
+    """Render a one-line stage header with an inline progress bar.
+
+    Example: 'Step 3/10 [██████░░░░░░░░░░░░] — User profile'. Pure formatting —
+    a static string, so it composes with the interactive prompts between stages
+    (a live Rich bar would have to stop/start around every input()).
+
+    Args:
+        current: 1-based index of the stage now starting.
+        total: Total number of stages (clamps to >= 1).
+        label: Human label for the stage.
+        width: Character width of the bar.
+
+    Returns:
+        Rich markup string ready for console.print().
+    """
+    total = max(total, 1)
+    current = max(0, min(current, total))
+    filled = round(width * current / total)
+    bar = "█" * filled + "░" * (width - filled)
+    return f"[bold cyan]Step {current}/{total}[/bold cyan] [green]{bar}[/green] — [bold]{label}[/bold]"
@@ -17,11 +17,23 @@ import sys
 from pathlib import Path
 from typing import Dict, List, NamedTuple

-from aipass.cli.apps.modules import console
+from aipass.cli.apps.modules import console, error as cli_error, success
 from aipass.prax import logger

 from aipass.aipass.shared.registry_discovery import find_registry as _discover_registry

+from aipass.aipass.apps.handlers.cross_os import (
+    CrossOsGapError,
+    PreflightResult,
+    RunRecordError,
+    check_hookstatus,
+    check_routing,
+    check_versions,
+    gaps_for_platform,
+    generate_run_record,
+)
+from aipass.aipass.apps.handlers.cross_os import run_e2e as run_e2e_preflight
+from aipass.aipass.apps.handlers.cross_os.preflight import E2E_UNRUNNABLE_PREFIX
 from aipass.aipass.apps.handlers.json import json_handler
 from aipass.aipass.apps.handlers.sandbox_check.sandbox_checker import (
    check_broker_alive,
@@ -48,7 +60,8 @@ from aipass.aipass.apps.modules.doctor_fix import (
 )
 from aipass.aipass.apps.modules.doctor_wire import (
    _auto_wire_provider,
-    prompt_auto_wire,
+    _prompt_auto_wire as prompt_auto_wire,
+    check_wire_verify,
    reconcile_stale_deny,
 )
 from aipass.aipass.apps.handlers.system_detect.system_detector import (
@@ -139,6 +152,118 @@ def _check_system() -> List[CheckResult]:
    return results


+def _check_global_aipass_home() -> List[CheckResult]:
+    """Check ~/.claude/settings.json env.AIPASS_HOME for stale or temp paths."""
+    from aipass.aipass.apps.handlers.init.bootstrap import is_throwaway_path
+
+    results: List[CheckResult] = []
+    settings_path = Path.home() / ".claude" / "settings.json"
+    if not settings_path.exists():
+        return results
+    try:
+        data = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.info("[doctor] global settings.json unreadable: %s", exc)
+        return results
+    home_val = data.get("env", {}).get("AIPASS_HOME", "")
+    if not home_val:
+        return results
+    home_path = Path(home_val)
+    if not home_path.exists():
+        results.append(
+            CheckResult(
+                "global AIPASS_HOME",
+                GLYPH_FAIL,
+                f"path does not exist: {home_val}",
+                "Fix: edit ~/.claude/settings.json env.AIPASS_HOME to the real repo root",
+            )
+        )
+    elif is_throwaway_path(home_val):
+        results.append(
+            CheckResult(
+                "global AIPASS_HOME",
+                GLYPH_FAIL,
+                f"points to throwaway path: {home_val}",
+                "Fix: edit ~/.claude/settings.json env.AIPASS_HOME to the real repo root",
+            )
+        )
+    else:
+        results.append(CheckResult("global AIPASS_HOME", GLYPH_PASS, home_val, ""))
+    return results
+
+
+def _check_owner_seating() -> List[CheckResult]:
+    """Check owner/identity health via the frozen sync-registry --check contract."""
+    try:
+        proc = subprocess.run(
+            ["drone", "@spawn", "sync-registry", "--check", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except FileNotFoundError:
+        logger.info("[doctor] drone not on PATH — skipping owner seating check")
+        return [CheckResult("owner", GLYPH_WARN, "drone not found", "Install drone to check owner seating")]
+    except subprocess.TimeoutExpired:
+        logger.warning("[doctor] sync-registry --check timed out")
+        return [CheckResult("owner", GLYPH_WARN, "check timed out", "")]
+
+    stdout = proc.stdout.strip()
+    if not stdout:
+        if proc.returncode == 0:
+            return [CheckResult("owner", GLYPH_PASS, "clean (no details)", "")]
+        return [CheckResult("owner", GLYPH_WARN, "no output from check", "")]
+
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError:
+        logger.warning("[doctor] sync-registry --check returned non-JSON: %s", stdout[:200])
+        return [CheckResult("owner", GLYPH_WARN, "unparseable check output", "")]
+
+    issues = data.get("issues", [])
+    owner_name = data.get("owner")
+    owner_uid = data.get("owner_uid", "")
+    uid_short = owner_uid[:8] if owner_uid else ""
+
+    if data.get("clean", False) and not issues:
+        detail = f"@{owner_name} OK (seated, uid {uid_short})" if owner_name else "OK"
+        return [CheckResult("owner", GLYPH_PASS, detail, "")]
+
+    results: List[CheckResult] = []
+    for issue in issues:
+        flag = issue.get("flag", "unknown")
+        detail = issue.get("detail", flag)
+        results.append(CheckResult(f"owner/{flag}", GLYPH_FAIL, detail, "Run 'aipass doctor --fix'"))
+
+    if not results:
+        label = f"@{owner_name} ISSUES" if owner_name else "UNSEATED"
+        results.append(CheckResult("owner", GLYPH_FAIL, label, "Run 'aipass doctor --fix'"))
+
+    return results
+
+
+def _fix_owner_seating() -> List[CheckResult]:
+    """Delegate owner/identity repair to spawn's sync-registry --fix."""
+    try:
+        proc = subprocess.run(
+            ["drone", "@spawn", "sync-registry", "--fix"],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except FileNotFoundError:
+        logger.info("[doctor] drone not on PATH — skipping owner fix")
+        return [CheckResult("owner fix", GLYPH_WARN, "drone not found", "")]
+    except subprocess.TimeoutExpired:
+        logger.warning("[doctor] sync-registry --fix timed out")
+        return [CheckResult("owner fix", GLYPH_WARN, "fix timed out", "")]
+
+    if proc.returncode == 0:
+        return [CheckResult("owner fix", GLYPH_PASS, "registry reconciled", "")]
+    detail = proc.stderr.strip()[:120] if proc.stderr else "non-zero exit"
+    return [CheckResult("owner fix", GLYPH_FAIL, detail, "")]
+
+
 def _check_identity() -> List[CheckResult]:
    """Run Identity group checks."""
    results: List[CheckResult] = []
@@ -161,6 +286,8 @@ def _check_identity() -> List[CheckResult]:
                )
            )

+    results.extend(_check_global_aipass_home())
+
    if reg_path is None:
        results.append(CheckResult("registry", GLYPH_FAIL, "not found", "Run 'aipass init' to create registry"))
        return results
@@ -210,6 +337,8 @@ def _check_identity() -> List[CheckResult]:
    else:
        results.append(CheckResult("passport", GLYPH_WARN, "not found", ""))

+    results.extend(_check_owner_seating())
+
    return results


@@ -369,7 +498,7 @@ def _check_provider_manifest(interactive: bool = False, fix: bool = False) -> Li
        if fix:
            actions = _auto_wire_provider(manifest_path, interactive=False)
            for action in actions:
-                console.print(f"[green]✓[/green] {action}")
+                success(action)
            wired = bool(actions)
        else:
            wired = prompt_auto_wire(manifest_path, missing_hooks, missing_env, missing_deny, missing_ask)
@@ -399,11 +528,23 @@ def _check_services(verbose: bool = False) -> List[CheckResult]:
            results.append(CheckResult("drone", GLYPH_PASS, detail, ""))
        else:
            results.append(
-                CheckResult("drone", GLYPH_FAIL, "exit non-zero", "Ensure aipass is installed: pip install -e .")
+                CheckResult(
+                    "drone",
+                    GLYPH_FAIL,
+                    "exit non-zero",
+                    "Ensure aipass is installed: clone the repo and run setup.sh",
+                )
            )
    except FileNotFoundError as exc:
        logger.warning("[doctor] drone not found: %s", exc)
-        results.append(CheckResult("drone", GLYPH_FAIL, "not found", "Ensure aipass is installed: pip install -e ."))
+        results.append(
+            CheckResult(
+                "drone",
+                GLYPH_FAIL,
+                "not found",
+                "Ensure aipass is installed: clone the repo and run setup.sh",
+            )
+        )
    except subprocess.TimeoutExpired as exc:
        logger.warning("[doctor] drone systems timed out: %s", exc)
        results.append(CheckResult("drone", GLYPH_WARN, "timed out", ""))
@@ -444,6 +585,9 @@ def _check_services(verbose: bool = False) -> List[CheckResult]:
    manifest_checks = _check_provider_manifest()
    results.extend(manifest_checks)

+    # wire_verify guard — catch empty/orphaned/duplicate provider hook entries
+    results.extend(CheckResult(*r) for r in check_wire_verify())
+
    # 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))
@@ -649,6 +793,197 @@ def _check_sandbox() -> List[CheckResult]:
    return results


+# --- Cross-OS pre-flight group ---
+
+
+def _cross_os_gap_rows() -> List[CheckResult]:
+    """OS-gap cross-reference rows (slice 1): tracked gaps for this platform.
+
+    Machine pre-flight — surfaces OS-specific gaps from tests/CROSS_OS_TESTING.md
+    for this box. Never claims the checklist's human green. WARN per gap, a single
+    PASS when none apply, a single WARN when the registry can't be read (never
+    silent).
+    """
+    platform_name = sys.platform
+    try:
+        gaps = gaps_for_platform(platform_name)
+    except CrossOsGapError as exc:
+        logger.warning("[doctor] cross-OS gap registry unavailable: %s", exc)
+        return [
+            CheckResult(
+                "cross-os registry (pre-flight)",
+                GLYPH_WARN,
+                f"pre-flight: gap registry unavailable — {exc}",
+                "Ensure tests/CROSS_OS_TESTING.md has a 'Known cross-OS gap registry' table",
+            )
+        ]
+
+    if not gaps:
+        return [
+            CheckResult(
+                "cross-os (pre-flight)",
+                GLYPH_PASS,
+                f"pre-flight: no tracked cross-OS gaps for {platform_name}",
+                "",
+            )
+        ]
+
+    return [
+        CheckResult(
+            f"cross-os gap #{gap.number} (pre-flight)",
+            GLYPH_WARN,
+            f"pre-flight: {gap.symptom}",
+            f"tracked gap [{gap.status}] — owner {gap.owner}; human Layer-3 pass still required",
+        )
+        for gap in gaps
+    ]
+
+
+def _preflight_row(label: str, result: PreflightResult, remediation: str) -> CheckResult:
+    """Map a non-mutating PreflightResult to a labelled pre-flight CheckResult.
+
+    ok -> PASS, else FAIL. The detail is always prefixed 'pre-flight:' so a row
+    can never be mistaken for the checklist's human acceptance green.
+    """
+    glyph = GLYPH_PASS if result.ok else GLYPH_FAIL
+    return CheckResult(f"{label} (pre-flight)", glyph, f"pre-flight: {result.detail}", "" if result.ok else remediation)
+
+
+def _e2e_row(result: PreflightResult) -> CheckResult:
+    """Map the heavy e2e PreflightResult to a CheckResult (PASS/FAIL/WARN).
+
+    ok -> PASS. Un-runnable infra cases (dir missing, no pytest, timeout) -> WARN.
+    Real test failures -> FAIL.
+    """
+    if result.ok:
+        glyph, remediation = GLYPH_PASS, ""
+    elif result.detail.startswith(E2E_UNRUNNABLE_PREFIX):
+        glyph = GLYPH_WARN
+        remediation = "Ensure a project .venv with pytest (or system pytest) and tests/e2e are present"
+    else:
+        glyph, remediation = GLYPH_FAIL, "Run 'pytest tests/e2e -q' from the repo root to inspect the failures"
+    return CheckResult("e2e suite (pre-flight)", glyph, f"pre-flight: {result.detail}", remediation)
+
+
+def _check_cross_os(run_e2e: bool = False) -> List[CheckResult]:
+    """Cross-OS pre-flight group (Layer-3-lite): gap cross-reference + machine routes.
+
+    Combines the slice-1 OS-gap rows with the non-mutating routing / --version /
+    hookstatus probes (Phase 4 / 1.3 / 6.3). None of these wake a citizen. When
+    ``run_e2e`` is set, also runs the heavy Phase-2 e2e suite. Every row is
+    labelled pre-flight and still needs the human Layer-3 pass.
+    """
+    results = _cross_os_gap_rows()
+
+    results.append(
+        _preflight_row(
+            "routing", check_routing(), "Ensure aipass is installed (setup.sh) so 'drone systems' and routes resolve"
+        )
+    )
+    results.append(
+        _preflight_row(
+            "versions", check_versions(), "Ensure 'drone' and 'aipass' are on PATH (clone the repo, run setup.sh)"
+        )
+    )
+    results.append(
+        _preflight_row("hookstatus", check_hookstatus(), "Check @hooks routing: 'drone @hooks status' should exit 0")
+    )
+
+    if run_e2e:
+        results.append(_e2e_row(run_e2e_preflight()))
+
+    return results
+
+
+def run_cross_os(run_e2e: bool = False) -> int:
+    """Render only the cross-OS pre-flight group (`aipass doctor --cross-os`).
+
+    Returns the error (FAIL) count; warnings do not fail, matching run_doctor.
+    When ``run_e2e`` is set (``--cross-os --e2e``), the heavy e2e suite runs too.
+    """
+    console.print()
+    console.print("[bold cyan]aipass doctor --cross-os[/bold cyan]")
+    console.print("[dim]machine pre-flight (Layer-3-lite) — augments, never replaces, the human acceptance pass[/dim]")
+    if run_e2e:
+        console.print("[dim]--e2e: running the heavy Phase-2 e2e wiring suite (builds a wheel + fresh venv)…[/dim]")
+    console.print()
+
+    checks = _check_cross_os(run_e2e=run_e2e)
+    pass_count = 0
+    warn_count = 0
+    error_count = 0
+
+    console.print("  [bold]Cross-OS[/bold]")
+    for check in checks:
+        line = format_check(check.label, check.glyph, check.detail, check.remediation)
+        console.print(line)
+        if check.glyph == GLYPH_PASS:
+            pass_count += 1
+        elif check.glyph == GLYPH_WARN:
+            warn_count += 1
+        else:
+            error_count += 1
+    console.print()
+
+    console.print("[dim]─────────────────────────────────[/dim]")
+    console.print(
+        f"  [green]✓ pass: {pass_count}[/green]  "
+        f"[yellow]! warnings: {warn_count}[/yellow]  "
+        f"[red]✗ errors: {error_count}[/red]"
+    )
+    console.print()
+
+    logger.info("[doctor] cross-os run — pass=%d warn=%d error=%d", pass_count, warn_count, error_count)
+    return error_count
+
+
+def _record_path_arg(args: list[str]) -> str | None:
+    """Extract the optional PATH value following ``--record`` (None if absent).
+
+    ``--record`` may stand alone (default path) or be followed by a path; a
+    following token that starts with ``-`` is another flag, not the path.
+    """
+    if "--record" not in args:
+        return None
+    idx = args.index("--record")
+    if idx + 1 < len(args):
+        candidate = args[idx + 1]
+        if not candidate.startswith("-"):
+            return candidate
+    return None
+
+
+def run_cross_os_record(path: str | None = None, run_e2e: bool = False) -> int:
+    """Generate a machine pre-flight Run Record (`aipass doctor --cross-os --record`).
+
+    Thin console wrapper: generation (env capture + machine-provable rows, human
+    rows left blank/marked) lives in the cross_os handler. Returns 0 on success,
+    1 if the file could not be written (never crashes).
+    """
+    console.print()
+    console.print("[bold cyan]aipass doctor --cross-os --record[/bold cyan]")
+    console.print(
+        "[dim]machine pre-flight DRAFT — auto-fills what the machine can prove; "
+        "a human still runs the real Layer-3 pass[/dim]"
+    )
+    if run_e2e:
+        console.print("[dim]--e2e: running the heavy Phase-2 e2e suite (builds a wheel + fresh venv)…[/dim]")
+    console.print()
+
+    try:
+        written = generate_run_record(path, run_heavy_e2e=run_e2e)
+    except RunRecordError as exc:
+        cli_error(str(exc))
+        logger.error("[doctor] cross-os run record failed: %s", exc)
+        return 1
+
+    success(f"Run Record written: {written}")
+    console.print("[dim]Complete the '— human' rows and run the real Layer-3 acceptance pass before it counts.[/dim]")
+    console.print()
+    logger.info("[doctor] cross-os run record written to %s", written)
+    return 0
+
+
 # --- Main doctor run ---


@@ -686,6 +1021,14 @@ def run_doctor(verbose: bool = False, interactive: bool = False, fix: bool = Fal
            services = groups.get("Services", [])
            groups["Services"] = [r for r in services if r.label != "rm deny migration"] + stale_results

+        wire_recheck = [CheckResult(*r) for r in check_wire_verify()]
+        services = groups.get("Services", [])
+        groups["Services"] = [r for r in services if r.label != "wire verify"] + wire_recheck
+
+        owner_fix = _fix_owner_seating()
+        identity = groups.get("Identity", [])
+        groups["Identity"] = [r for r in identity if not r.label.startswith("owner")] + owner_fix
+
    pass_count = 0
    warn_count = 0
    error_count = 0
@@ -738,10 +1081,16 @@ def print_help() -> None:
    console.print("[yellow]USAGE:[/yellow]")
    console.print("  [green]aipass doctor[/green]           [dim]# Run all checks[/dim]")
    console.print("  [green]aipass doctor --verbose[/green] [dim]# Show sub-check detail[/dim]")
-    console.print("  [green]aipass doctor --fix[/green]     [dim]# Auto-wire + remediation report[/dim]")
+    console.print("  [green]aipass doctor --fix[/green]     [dim]# Auto-wire, owner seat repair + remediation[/dim]")
    console.print("  [green]aipass doctor --fix --json[/green][dim]# Remediation as JSON (for spawn)[/dim]")
+    console.print("  [green]aipass doctor --cross-os[/green][dim]# OS-gap + routing/version/hooks pre-flight[/dim]")
+    console.print("  [green]aipass doctor --cross-os --e2e[/green][dim]# …also run the heavy e2e suite[/dim]")
+    console.print(
+        "  [green]aipass doctor --cross-os --record [PATH][/green]"
+        "[dim]# write a machine pre-flight Run Record draft (human completes it)[/dim]"
+    )
    console.print()
-    console.print("[yellow]OUTPUT:[/yellow]  [green]✓[/green] pass  [yellow]![/yellow] warn  [red]✗[/red] error")
+    console.print("[yellow]OUTPUT:[/yellow]  pass / warn / error (color-coded)")
    console.print("[yellow]EXIT:[/yellow]    0 = pass/warn  |  1 = errors found")
    console.print()

@@ -770,6 +1119,21 @@ def handle_command(command: str, args: list[str]) -> bool:
        print_introspection()
        return True

+    if "--cross-os" in args:
+        e2e = "--e2e" in args
+        if "--record" in args:
+            record_path = _record_path_arg(args)
+            rc = run_cross_os_record(record_path, run_e2e=e2e)
+            json_handler.log_operation("doctor_cross_os_record", {"path": record_path, "e2e": e2e, "rc": rc})
+            if rc != 0:
+                raise SystemExit(1)
+            return True
+        error_count = run_cross_os(run_e2e=e2e)
+        json_handler.log_operation("doctor_cross_os", {"error_count": error_count, "e2e": e2e})
+        if error_count > 0:
+            raise SystemExit(1)
+        return True
+
    verbose = "--verbose" in args or "-v" in args
    fix_mode = "--fix" in args
    json_mode = "--json" in args
@@ -18,36 +18,20 @@ Provides:

 from __future__ import annotations

-import json
-import shutil
-from datetime import datetime, timezone
+import subprocess
+import sys
 from pathlib import Path
-from typing import Dict, List
+from typing import List, NamedTuple

-from aipass.cli.apps.modules import console
+from aipass.cli.apps.modules import console, success
 from aipass.prax import logger

 from aipass.aipass.apps.handlers.json import json_handler
-
-# =============================================================================
-# HOOK & ENV DESCRIPTIONS (for interactive "no" warning)
-# =============================================================================
-
-HOOK_DESCRIPTIONS: Dict[str, str] = {
-    "pre_edit_gate.py": "blocks edits outside agent's branch",
-    "subagent_stop_gate.py": "validates agent output on exit",
-    "auto_fix_diagnostics.py": "auto-fixes lint issues after edits",
-    "global_prompt_loader.py": "injects branch context on each turn",
-    "identity_injector.py": "injects agent identity on each turn",
-    "email_notification.py": "notifies on incoming agent mail",
-    "branch_prompt_loader.py": "loads branch-specific prompts",
-    "pre_compact.py": "saves state before context compaction",
-}
-
-ENV_DESCRIPTIONS: Dict[str, str] = {
-    "AIPASS_HOME": "tells agents where AIPass lives",
-    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "prevents conflict with .trinity/ memory system",
-}
+from aipass.aipass.apps.handlers.provider_wire import (  # noqa: F401
+    HOOK_DESCRIPTIONS,
+    ENV_DESCRIPTIONS,
+    auto_wire_provider as _auto_wire_provider,
+)


 # =============================================================================
@@ -57,130 +41,12 @@ ENV_DESCRIPTIONS: Dict[str, str] = {
 from aipass.aipass.apps.handlers.provider_reconcile import reconcile_stale_deny  # noqa: E402, F401


-# =============================================================================
-# AUTO-WIRE
-# =============================================================================
-
-
-def _auto_wire_provider(manifest_path: Path, interactive: bool = True) -> List[str]:
-    """Auto-wire provider settings from manifest into ~/.claude/settings.json.
-
-    Additive merge only — never removes or overwrites existing keys/values.
-    Returns list of action descriptions (for logging/display).
-    """
-    actions: List[str] = []
-
-    manifest = json_handler.load_path(manifest_path)
-    if manifest is None:
-        return actions
-    claude_section = manifest.get("cli", {}).get("claude", {})
-    if not claude_section:
-        return actions
-
-    # Read existing settings
-    settings_path = Path.home() / ".claude" / "settings.json"
-    if settings_path.exists():
-        settings = json_handler.load_path(settings_path) or {}
-    else:
-        settings = {}
-
-    # Backup
-    if settings_path.exists():
-        date_stamp = datetime.now(tz=timezone.utc).strftime("%Y-%m-%d")
-        backup_path = settings_path.with_suffix(f".json.bak.{date_stamp}")
-        shutil.copy2(settings_path, backup_path)
-        actions.append(f"Backed up settings to {backup_path.name}")
-
-    # Hooks — add bridge entries to provider settings
-    manifest_hooks = claude_section.get("hooks", [])
-
-    for hook in manifest_hooks:
-        command = hook.get("command", "")
-        event = hook.get("event", "")
-        if not command or not event:
-            continue
-
-        if "hooks" not in settings:
-            settings["hooks"] = {}
-        if event not in settings["hooks"]:
-            settings["hooks"][event] = []
-        event_hooks = settings["hooks"][event]
-        if not isinstance(event_hooks, list):
-            event_hooks = [event_hooks]
-            settings["hooks"][event] = event_hooks
-
-        hook_matcher = hook.get("matcher", "")
-        already_wired = any(
-            isinstance(h, dict) and command in json.dumps(h) and h.get("matcher", "") == hook_matcher
-            for h in event_hooks
-        )
-        if not already_wired:
-            cmd_entry: Dict[str, object] = {
-                "type": "command",
-                "command": command,
-            }
-            if hook.get("timeout"):
-                cmd_entry["timeout"] = hook["timeout"]
-            wrapper: Dict[str, object] = {}
-            if hook.get("matcher"):
-                wrapper["matcher"] = hook["matcher"]
-            wrapper["hooks"] = [cmd_entry]
-            event_hooks.append(wrapper)
-            label = command.rsplit(" ", 1)[-1] if " " in command else command
-            actions.append(f"Wired hook {label} -> {event}")
-
-    # Env vars
-    manifest_env = claude_section.get("env", {})
-    if manifest_env:
-        if "env" not in settings:
-            settings["env"] = {}
-        repo_root = str(manifest_path.parent.parent)
-        project_root = str(Path.cwd())
-        for key, value in manifest_env.items():
-            if key not in settings["env"]:
-                resolved = value.replace("{{REPO_ROOT}}", repo_root)
-                resolved = resolved.replace("{{PROJECT_ROOT}}", project_root)
-                settings["env"][key] = resolved
-                actions.append(f"Set env {key}={resolved}")
-
-    # Permissions
-    manifest_perms = claude_section.get("permissions", {})
-    manifest_deny = manifest_perms.get("deny", [])
-    manifest_ask = manifest_perms.get("ask", [])
-
-    if manifest_deny or manifest_ask:
-        if "permissions" not in settings:
-            settings["permissions"] = {}
-        if "deny" not in settings["permissions"]:
-            settings["permissions"]["deny"] = []
-        if "ask" not in settings["permissions"]:
-            settings["permissions"]["ask"] = []
-
-        existing_deny = set(settings["permissions"]["deny"])
-        for rule in manifest_deny:
-            if rule not in existing_deny:
-                settings["permissions"]["deny"].append(rule)
-                actions.append(f"Added deny rule: {rule}")
-
-        existing_ask = set(settings["permissions"]["ask"])
-        for rule in manifest_ask:
-            if rule not in existing_ask:
-                settings["permissions"]["ask"].append(rule)
-                actions.append(f"Added ask rule: {rule}")
-
-    # Write settings back
-    json_handler.save_path(settings_path, settings)
-    actions.append("Updated ~/.claude/settings.json")
-
-    return actions
-
-
 # =============================================================================
 # INTERACTIVE WIRE PROMPTS
 # =============================================================================


-def prompt_auto_wire(
+def _prompt_auto_wire(
    manifest_path: Path,
    missing_hooks: List[str],
    missing_env: List[str],
@@ -205,16 +71,20 @@ def prompt_auto_wire(
    console.print(f"\n[bold]{', '.join(parts)} missing[/bold]")
    console.print("[dim]Review details: .claude/hooks/README.md[/dim]")

-    try:
-        answer = input("Auto-wire provider settings? [y/N]: ").strip().lower()
-    except (EOFError, KeyboardInterrupt) as exc:
-        logger.info("[doctor] auto-wire prompt interrupted: %s", type(exc).__name__)
+    if not sys.stdin.isatty():
+        logger.info("[doctor] non-interactive stdin — auto-wire prompt skipped, treating as decline")
        answer = "n"
+    else:
+        try:
+            answer = input("Auto-wire provider settings? [y/N]: ").strip().lower()
+        except (EOFError, KeyboardInterrupt) as exc:
+            logger.info("[doctor] auto-wire prompt interrupted: %s", type(exc).__name__)
+            answer = "n"

    if answer in ("y", "yes"):
        actions = _auto_wire_provider(manifest_path, interactive=True)
        for action in actions:
-            console.print(f"[green]✓[/green] {action}")
+            success(action)
        return bool(actions)

    _print_manual_wire_warning(missing_hooks, missing_env, missing_deny, missing_ask)
@@ -304,3 +174,51 @@ def handle_command(command: str, args: list[str]) -> bool:

    json_handler.log_operation("doctor_wire_noop", {"command": command})
    return False
+
+
+# =============================================================================
+# WIRE VERIFY GUARD (doctor check row)
+# =============================================================================
+
+
+class WireCheckResult(NamedTuple):
+    """Single doctor check result (mirrors doctor.CheckResult without importing it)."""
+
+    label: str
+    glyph: str
+    detail: str
+    remediation: str
+
+
+_GLYPH_PASS = "[green]✓[/green]"
+_GLYPH_FAIL = "[red]✗[/red]"
+_GLYPH_WARN = "[yellow]![/yellow]"
+
+
+def check_wire_verify() -> list[WireCheckResult]:
+    """Run the hooks wire_verify guard — catch empty/orphaned/duplicate provider entries."""
+    try:
+        proc = subprocess.run(
+            ["drone", "@hooks", "verify"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if proc.returncode == 0:
+            return [WireCheckResult("wire verify", _GLYPH_PASS, "provider hooks wired correctly", "")]
+        lines = [ln.strip() for ln in proc.stdout.splitlines() if ln.strip()]
+        detail = lines[-1] if lines else "errors detected"
+        return [
+            WireCheckResult(
+                "wire verify",
+                _GLYPH_FAIL,
+                detail,
+                "Run 'aipass doctor --fix' to re-wire, then re-run doctor to confirm",
+            )
+        ]
+    except FileNotFoundError as exc:
+        logger.warning("[doctor] drone not found for wire_verify: %s", exc)
+        return [WireCheckResult("wire verify", _GLYPH_WARN, "drone not found", "")]
+    except subprocess.TimeoutExpired as exc:
+        logger.warning("[doctor] wire_verify timed out: %s", exc)
+        return [WireCheckResult("wire verify", _GLYPH_WARN, "timed out", "")]
@@ -21,7 +21,7 @@ Usage:

 from __future__ import annotations

-from aipass.cli.apps.modules import console, warning
+from aipass.cli.apps.modules import console, success, warning
 from aipass.prax import logger

 from aipass.aipass.apps.handlers.json import json_handler
@@ -64,7 +64,7 @@ def do_handoff(

    if launched:
        console.print()
-        console.print(f"[green]✓[/green] Session started via tmux/wt — CLI: [cyan]{cli}[/cyan]")
+        success(f"Session started via tmux/wt — CLI: {cli}")
        console.print(f"[dim]Session name: aipass-handoff | cwd: {cwd}[/dim]")
        console.print()
    else:
@@ -1,25 +1,25 @@
 # =================== AIPass ====================
 # Name: init_flow.py
-# Description: 12-stage guided first-run setup — aipass init command
-# Version: 1.0.0
+# Description: 10-stage guided first-run setup — aipass init command
+# Version: 1.2.0
 # Created: 2026-04-16
-# Modified: 2026-04-16
+# Modified: 2026-07-04
 # =============================================

 """
 aipass init — guided first-run setup

-12 resumable stages. State persists to .aipass/init_progress.json.
+10 resumable stages. State persists to .aipass/init_progress.json.
 Ctrl-C at any stage resumes next time from that stage.

 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 --dry-run            # walk all 12 stages, no destructive ops
-                                         #   - skips drone @spawn create (stage 8)
-                                         #   - skips tmux/wt handoff (stage 11)
+    aipass init run --name YourName --cli claude
+    aipass init run --dry-run            # walk all 10 stages, no destructive ops
+                                         #   - skips drone @spawn create (stage 6)
+                                         #   - skips tmux/wt handoff (stage 9)
                                         #   - does NOT write .aipass/init_progress.json
 """

@@ -35,13 +35,13 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List

-from aipass.cli.apps.modules import console, warning
+from aipass.cli.apps.modules import console, error as cli_error, success, warning
 from aipass.prax import logger

 from aipass.aipass.apps.handlers.json import json_handler
+from aipass.aipass.apps.handlers.ui.progress import activity_spinner, render_step_header
 from aipass.aipass.apps.handlers.system_detect.system_detector import (
    detect_cpu,
-    detect_docker,
    detect_git,
    detect_install_method,
    detect_os,
@@ -62,7 +62,7 @@ except ImportError as _qe:
    HAS_QUESTIONARY = False

 COMMAND = "init"
-TOTAL_STAGES = 12
+TOTAL_STAGES = 10

 _BRANCH_ROOT = Path(__file__).resolve().parents[2]

@@ -92,6 +92,12 @@ CLI_CHOICES = ["claude", "codex", "other"]
 FLAG_CHOICES = ["default", "skip-permissions"]
 STYLE_CHOICES = ["building-my-own-project", "improving-aipass", "just-exploring"]

+TEMPLATE_EMPTY = "empty project"
+TEMPLATE_AIPASS = "aipass_framework"
+TEMPLATE_CHOICES = [TEMPLATE_EMPTY, TEMPLATE_AIPASS]
+# first_agent, ping_sweep, handoff, done — skipped for empty (non-framework) projects
+AIPASS_SPECIFIC_STAGES = {6, 7, 9, 10}
+

 # --- LOCAL JSON HELPERS ---
 def _read_local_json() -> dict:
@@ -204,7 +210,7 @@ def _choose(msg: str, choices: List[str], default: str | None = None) -> str:
                return choices[idx]
        except ValueError as exc:
            logger.info("[init_flow] invalid menu input %r: %s", raw, exc)
-        console.print("[red]Invalid choice.[/red]")
+        cli_error("Invalid choice.")


 # --- STAGE FUNCTIONS ---
@@ -228,15 +234,47 @@ def stage_1_welcome(dry_run: bool = False) -> Dict[str, Any]:
    if dry_run:
        console.print("[yellow]\\[dry-run][/yellow] No state will be written, no subprocesses launched.")
    console.print()
-    console.print("[bold cyan]Step 1/12[/bold cyan] — Welcome")
+    console.print(render_step_header(1, TOTAL_STAGES, "Welcome"))
    _save_stage(1, dry_run=dry_run)
    return {}


+def _print_os_gap_heads_up() -> None:
+    """Print tracked cross-OS gaps that apply to this OS (machine pre-flight, not a guarantee).
+
+    Lightweight: one doc read + parse. Failures are non-fatal — init must not
+    crash here. This is NOT the human acceptance pass; it just surfaces tracked
+    gaps at the moment the user is on the box.
+    """
+    try:
+        from aipass.aipass.apps.handlers.cross_os import CrossOsGapError, gaps_for_platform
+    except ImportError as exc:
+        logger.warning("[init_flow] cross_os handler unavailable: %s", exc)
+        return
+
+    try:
+        gaps = gaps_for_platform(sys.platform)
+    except CrossOsGapError as exc:
+        logger.warning("[init_flow] cross-OS gap registry unavailable: %s", exc)
+        warning("cross-OS gap registry unavailable — skipping OS heads-up.")
+        return
+
+    if not gaps:
+        return
+
+    console.print()
+    console.print(
+        f"[dim]Heads-up — {len(gaps)} tracked cross-OS gap(s) may apply on this OS "
+        "(machine pre-flight, not a guarantee):[/dim]"
+    )
+    for gap in gaps:
+        console.print(f"  [yellow]![/yellow] [dim]gap #{gap.number}: {gap.symptom} [{gap.status}][/dim]")
+
+
 def stage_2_system_detect(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
    """Detect OS, Python, shell, RAM, CPU, install method, and optional tools."""
    console.print()
-    console.print("[bold cyan]Step 2/12[/bold cyan] — System detection")
+    console.print(render_step_header(2, TOTAL_STAGES, "System detection"))

    from rich.table import Table

@@ -249,7 +287,6 @@ def stage_2_system_detect(non_interactive: bool = False, dry_run: bool = False)
    install = detect_install_method()
    has_tmux = detect_tmux()
    has_wt = detect_wt()
-    has_docker = detect_docker()

    table = Table(show_header=False, box=None)
    table.add_column("key", style="cyan")
@@ -264,7 +301,6 @@ def stage_2_system_detect(non_interactive: bool = False, dry_run: bool = False)
    table.add_row("tmux", "yes" if has_tmux else "no")
    if sys.platform == "win32":
        table.add_row("wt.exe", "yes" if has_wt else "no")
-    table.add_row("docker", "yes" if has_docker else "no")
    console.print(table)

    console.print()
@@ -272,50 +308,21 @@ def stage_2_system_detect(non_interactive: bool = False, dry_run: bool = False)
    install_labels = {"dev": "development (editable source)", "pip": "pip", "clone": "git clone", "unknown": "unknown"}
    console.print(f"Install type: [cyan]{install_labels.get(install, install)}[/cyan]")

+    _print_os_gap_heads_up()
+
    system_data: Dict[str, Any] = {
        "os": os_info["os_name"],
        "python": py["version"],
        "shell": sh["name"],
        "ram_gb": ram["total_gb"],
        "install": install,
-        "has_docker": has_docker,
        "has_tmux": has_tmux,
    }
    _save_stage(2, system_data, dry_run=dry_run)
    return system_data


-def stage_3_doctor(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
-    """Run aipass doctor health checks inline."""
-    console.print()
-    console.print("[bold cyan]Step 3/12[/bold cyan] — System health check")
-
-    error_count = 0
-    provider_gaps: Dict[str, Any] = {}
-    try:
-        from aipass.aipass.apps.modules import doctor
-
-        error_count = doctor.run_doctor(interactive=not non_interactive)
-        try:
-            for r in doctor._check_provider_manifest():
-                if r.glyph != doctor.GLYPH_PASS:
-                    provider_gaps[r.label] = r.detail
-        except Exception as exc:
-            logger.warning("[init_flow] provider manifest check failed: %s", exc)
-    except Exception as exc:
-        logger.warning("[init_flow] doctor run failed: %s", exc)
-        warning(f"Doctor check skipped: {exc}")
-
-    if error_count > 0:
-        warning(f"{error_count} issue(s) found above — review when convenient.")
-    else:
-        console.print("[green]✓[/green] Health check passed.")
-
-    _save_stage(3, {"doctor_errors": error_count}, dry_run=dry_run)
-    return {"doctor_errors": error_count, "provider_gaps": provider_gaps}
-
-
-def stage_4_user_profile(
+def stage_3_user_profile(
    non_interactive: bool = False,
    name_override: str | None = None,
    system_data: dict | None = None,
@@ -323,7 +330,7 @@ def stage_4_user_profile(
 ) -> Dict[str, Any]:
    """Collect user name and OS, save to profile."""
    console.print()
-    console.print("[bold cyan]Step 4/12[/bold cyan] — User profile")
+    console.print(render_step_header(3, TOTAL_STAGES, "User profile"))

    from aipass.aipass.apps.modules import profile as profile_mod

@@ -351,19 +358,19 @@ def stage_4_user_profile(
    else:
        profile_mod.save_profile(existing)

-    console.print(f"[green]✓[/green] Hello, {name}!")
-    _save_stage(4, {"name": name}, dry_run=dry_run)
+    success(f"Hello, {name}!")
+    _save_stage(3, {"name": name}, dry_run=dry_run)
    return {"name": name}


-def stage_5_style_questions(
+def stage_4_style_questions(
    non_interactive: bool = False,
    style_override: str | None = None,
    dry_run: bool = False,
 ) -> Dict[str, Any]:
    """Ask what the user wants to do — routes tone of later stages."""
    console.print()
-    console.print("[bold cyan]Step 5/12[/bold cyan] — What brings you here?")
+    console.print(render_step_header(4, TOTAL_STAGES, "What brings you here?"))

    if style_override and style_override in STYLE_CHOICES:
        style = style_override
@@ -372,8 +379,8 @@ def stage_5_style_questions(
    else:
        style = _choose("What are you looking to do?", STYLE_CHOICES, default=STYLE_CHOICES[0])

-    console.print(f"[green]✓[/green] Got it: {style}")
-    _save_stage(5, {"style": style}, dry_run=dry_run)
+    success(f"Got it: {style}")
+    _save_stage(4, {"style": style}, dry_run=dry_run)
    return {"style": style}


@@ -410,29 +417,29 @@ 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.")
+        console.print("  Stage 9 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]")
+        console.print("[cyan]Installing Claude Code[/cyan] [dim](this can take a minute)…[/dim]")
        if _install_claude_code():
-            console.print("[green]✓[/green] Claude Code installed successfully.")
+            success("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]")
+        console.print("[dim]Skipped. Stage 9 handoff will need 'claude' on PATH.[/dim]")


-def stage_6_tool_choice(
+def stage_5_tool_choice(
    non_interactive: bool = False,
    cli_override: str | None = None,
    dry_run: bool = False,
 ) -> Dict[str, Any]:
    """Choose CLI tool and launch flag variant."""
    console.print()
-    console.print("[bold cyan]Step 6/12[/bold cyan] — CLI tool choice")
+    console.print(render_step_header(5, TOTAL_STAGES, "CLI tool choice"))

    if cli_override and cli_override in CLI_CHOICES:
        cli_choice = cli_override
@@ -453,8 +460,8 @@ def stage_6_tool_choice(
            default="default",
        )

-    console.print(f"[green]✓[/green] {cli_choice} ({flag_variant})")
-    _save_stage(6, {"cli": cli_choice, "flag_variant": flag_variant}, dry_run=dry_run)
+    success(f"{cli_choice} ({flag_variant})")
+    _save_stage(5, {"cli": cli_choice, "flag_variant": flag_variant}, dry_run=dry_run)

    if dry_run:
        console.print(f"[yellow]\\[dry-run][/yellow] would save preferred_cli={cli_choice} to profile")
@@ -471,37 +478,10 @@ def stage_6_tool_choice(
    return {"cli": cli_choice, "flag_variant": flag_variant}


-def stage_7_docker_offer(
-    non_interactive: bool = False,
-    no_docker: bool = False,
-    has_docker: bool | None = None,
-    dry_run: bool = False,
-) -> Dict[str, Any]:
-    """Offer Docker sandbox test if Docker is detected."""
-    console.print()
-    console.print("[bold cyan]Step 7/12[/bold cyan] — Docker")
-
-    if has_docker is None:
-        has_docker = detect_docker()
-
-    if not has_docker or no_docker or non_interactive:
-        reason = "not detected" if not has_docker else ("--no-docker" if no_docker else "non-interactive")
-        console.print(f"[dim]Docker offer skipped ({reason}).[/dim]")
-        _save_stage(7, {"docker": "skipped"}, dry_run=dry_run)
-        return {"docker": "skipped"}
-
-    raw = _prompt("Test in a Docker sandbox? [y/N]", "N")
-    use_docker = raw.lower() in ("y", "yes")
-    result = "yes" if use_docker else "no"
-    console.print(f"[green]✓[/green] Docker: {result}")
-    _save_stage(7, {"docker": result}, dry_run=dry_run)
-    return {"docker": result}
-
-
-def stage_8_first_agent(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
+def stage_6_first_agent(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
    """Create the user's first AI agent via drone @spawn."""
    console.print()
-    console.print("[bold cyan]Step 8/12[/bold cyan] — Create your first agent")
+    console.print(render_step_header(6, TOTAL_STAGES, "Create your first agent"))
    console.print("Let's create your first AI agent (citizen).")

    if non_interactive:
@@ -514,41 +494,41 @@ def stage_8_first_agent(non_interactive: bool = False, dry_run: bool = False) ->
        agent_path = f"{package_dir}/{agent_name}"
    else:
        agent_path = f"src/{agent_name}"
-    console.print(f"Running: [cyan]drone @spawn create {agent_path}[/cyan]")
+    console.print(f"[cyan]Creating your first agent[/cyan] [dim](drone @spawn create {agent_path})…[/dim]")

-    success = False
+    spawned = False
    if dry_run:
        console.print(f"[yellow]\\[dry-run][/yellow] would run: drone @spawn create {agent_path}")
-        success = True
+        spawned = True
    else:
        try:
            proc = subprocess.run(["drone", "@spawn", "create", agent_path], timeout=60)
-            success = proc.returncode == 0
+            spawned = proc.returncode == 0
        except FileNotFoundError as exc:
-            logger.warning("[init_flow] drone not found in stage 8: %s", exc)
+            logger.warning("[init_flow] drone not found in stage 6: %s", exc)
            warning("drone not found — skipping agent creation.")
        except subprocess.TimeoutExpired as exc:
-            logger.warning("[init_flow] spawn timed out in stage 8: %s", exc)
+            logger.warning("[init_flow] spawn timed out in stage 6: %s", exc)
            warning("spawn timed out — agent may still be created.")

-    if success:
-        console.print(f"[green]✓[/green] Agent created at {agent_path}")
+    if spawned:
+        success(f"Agent created at {agent_path}")

-    _save_stage(8, {"agent_name": agent_name, "agent_path": agent_path, "success": success}, dry_run=dry_run)
+    _save_stage(6, {"agent_name": agent_name, "agent_path": agent_path, "success": spawned}, dry_run=dry_run)
    return {"agent_name": agent_name, "agent_path": agent_path}


-def stage_9_ping_sweep(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
+def stage_7_ping_sweep(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
    """Ping all registered branches via test-convention emails."""
    console.print()
-    console.print("[bold cyan]Step 9/12[/bold cyan] — Pinging agents")
+    console.print(render_step_header(7, TOTAL_STAGES, "Pinging agents"))

    from aipass.aipass.apps.handlers import ping_sweep

    branches = ping_sweep._discover_branches()
    if not branches:
        console.print("[dim]  No branches registered yet — skipping ping sweep.[/dim]")
-        _save_stage(9, {"results": {}, "skipped": True}, dry_run=dry_run)
+        _save_stage(7, {"results": {}, "skipped": True}, dry_run=dry_run)
        return {"ping_results": {}}

    # Standalone projects can't ping agents via drone (drone only knows AIPass's registry).
@@ -560,7 +540,7 @@ def stage_9_ping_sweep(non_interactive: bool = False, dry_run: bool = False) ->
        else:
            console.print(f"[dim]  Found {len(branches)} agent(s) in this project.[/dim]")
            console.print("[dim]  Ping skipped — agents will be reachable after handoff (next step).[/dim]")
-        _save_stage(9, {"results": {}, "skipped_standalone": True}, dry_run=dry_run)
+        _save_stage(7, {"results": {}, "skipped_standalone": True}, dry_run=dry_run)
        return {"ping_results": {}}

    console.print(f"[dim]  Found {len(branches)} agent(s). Checking reachability...[/dim]")
@@ -568,7 +548,8 @@ def stage_9_ping_sweep(non_interactive: bool = False, dry_run: bool = False) ->
        "[dim]  (Agents with a running session will auto-ack; new agents will time out — that's normal.)[/dim]"
    )

-    results = ping_sweep.sweep_all_branches(timeout=10)
+    with activity_spinner("Pinging agents…"):
+        results = ping_sweep.sweep_all_branches(timeout=10)

    for branch, status in results.items():
        if status == "ack":
@@ -582,33 +563,35 @@ def stage_9_ping_sweep(non_interactive: bool = False, dry_run: bool = False) ->

    summary = ping_sweep.sweep_summary(results)
    console.print(f"  {summary}")
-    _save_stage(9, {"results": results}, dry_run=dry_run)
+    _save_stage(7, {"results": results}, dry_run=dry_run)
    return {"ping_results": results}


-def stage_10_smoke_test(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
+def stage_8_smoke_test(non_interactive: bool = False, dry_run: bool = False) -> Dict[str, Any]:
    """Verify drone and aipass binaries are on PATH."""
    console.print()
-    console.print("[bold cyan]Step 10/12[/bold cyan] — Smoke test")
+    console.print(render_step_header(8, TOTAL_STAGES, "Smoke test"))

    drone_bin = shutil.which("drone")
    aipass_bin = shutil.which("aipass")

    if drone_bin:
-        console.print(f"[green]✓[/green] drone: {drone_bin}")
+        success(f"drone: {drone_bin}")
    else:
-        warning("drone not on PATH — run: pip install -e .")
+        warning("drone not on PATH — clone the repo and run setup.sh")

    if aipass_bin:
-        console.print(f"[green]✓[/green] aipass: {aipass_bin}")
+        success(f"aipass: {aipass_bin}")
    else:
-        warning("aipass not on PATH — run: pip install -e .")
+        warning("aipass not on PATH — clone the repo and run setup.sh")

-    _save_stage(10, {"drone": drone_bin, "aipass": aipass_bin}, dry_run=dry_run)
+    console.print("[dim]Full cross-OS pre-flight: aipass doctor --cross-os[/dim]")
+
+    _save_stage(8, {"drone": drone_bin, "aipass": aipass_bin}, dry_run=dry_run)
    return {"drone": drone_bin, "aipass": aipass_bin}


-def stage_11_handoff(
+def stage_9_handoff(
    cli_choice: str = "claude",
    flag_variant: str = "default",
    agent_path: str = "src/my_agent",
@@ -618,7 +601,7 @@ def stage_11_handoff(
 ) -> Dict[str, Any]:
    """Launch user's chosen CLI — inline (same terminal) or new window."""
    console.print()
-    console.print("[bold cyan]Step 11/12[/bold cyan] — Handoff")
+    console.print(render_step_header(9, TOTAL_STAGES, "Handoff"))

    init_prompt = "I just completed aipass init. I am ready to start. What should I do first?"

@@ -652,12 +635,12 @@ def stage_11_handoff(
        inline = choice != "2"

        if inline:
-            _save_stage(11, {"command": command, "launched": True, "inline": True}, dry_run=dry_run)
-            _save_stage(12, dry_run=dry_run)
+            _save_stage(9, {"command": command, "launched": True, "inline": True}, dry_run=dry_run)
+            _save_stage(10, dry_run=dry_run)
            if accumulated:
                _write_init_report(accumulated.get("agent_path", agent_path), accumulated, dry_run=dry_run)
            console.print()
-            console.print("[bold green]✓ Setup complete![/bold green]")
+            success("Setup complete!")
            console.print()
            from aipass.aipass.apps.handlers.handoff_platform import launch_inline

@@ -674,10 +657,24 @@ def stage_11_handoff(
            )

    if not inline:
-        _save_stage(11, {"command": command, "launched": launched}, dry_run=dry_run)
+        _save_stage(9, {"command": command, "launched": launched}, dry_run=dry_run)
    return {"handoff_command": command, "launched": launched}


+def _collect_provider_gaps() -> Dict[str, Any]:
+    """Gather provider-manifest gaps for the init report — standalone, no full doctor run."""
+    gaps: Dict[str, Any] = {}
+    try:
+        from aipass.aipass.apps.modules import doctor
+
+        for r in doctor._check_provider_manifest():
+            if r.glyph != doctor.GLYPH_PASS:
+                gaps[r.label] = r.detail
+    except Exception as exc:
+        logger.warning("[init_flow] provider manifest check failed: %s", exc)
+    return gaps
+
+
 def _write_init_report(agent_path: str, accumulated: Dict[str, Any], dry_run: bool = False) -> None:
    """Drop init_report.json into the agent's dropbox."""
    if dry_run or not agent_path:
@@ -702,7 +699,7 @@ def _write_init_report(agent_path: str, accumulated: Dict[str, Any], dry_run: bo
            " drone @devpulse watchdog agent @target"
        ),
    }
-    provider_gaps = accumulated.get("provider_gaps", {})
+    provider_gaps = _collect_provider_gaps()
    if provider_gaps:
        report["provider_gaps"] = provider_gaps
        report["provider_action"] = (
@@ -714,12 +711,12 @@ def _write_init_report(agent_path: str, accumulated: Dict[str, Any], dry_run: bo
    logger.info("[init_flow] init report written to %s", report_path)


-def stage_12_done(accumulated: Dict[str, Any] | None = None, dry_run: bool = False) -> Dict[str, Any]:
+def stage_10_done(accumulated: Dict[str, Any] | None = None, dry_run: bool = False) -> Dict[str, Any]:
    """Print completion summary and drop init report."""
    console.print()
-    console.print("[bold cyan]Step 12/12[/bold cyan] — Done!")
+    console.print(render_step_header(10, TOTAL_STAGES, "Done!"))
    console.print()
-    console.print("[bold green]✓ Setup complete![/bold green]")
+    success("Setup complete!")
    console.print()
    console.print("  [cyan]aipass help[/cyan]     [dim]# Ask any question[/dim]")
    console.print("  [cyan]aipass doctor[/cyan]   [dim]# Check system health[/dim]")
@@ -727,7 +724,7 @@ def stage_12_done(accumulated: Dict[str, Any] | None = None, dry_run: bool = Fal
    console.print()
    if accumulated:
        _write_init_report(accumulated.get("agent_path", ""), accumulated, dry_run=dry_run)
-    _save_stage(12, dry_run=dry_run)
+    _save_stage(10, dry_run=dry_run)
    return {}


@@ -773,23 +770,36 @@ def run_init(
    name: str | None = None,
    cli: str | None = None,
    style: str | None = None,
-    no_docker: bool = False,
    dry_run: bool = False,
+    template: str | None = None,
 ) -> int:
-    """Run the 12-stage init flow. Returns 0 on success."""
+    """Run the 10-stage init flow. Returns 0 on success."""
    # Pre-flight: refuse to run inside existing projects or agent dirs
    err = _preflight_check()
    if err:
-        console.print(f"[red]✗[/red] {err}")
+        cli_error(str(err))
        return 1

-    # Ensure scaffold exists (creates registry, .aipass, etc. if missing)
+    # Template selection — before scaffold
+    if template is None:
+        if non_interactive:
+            template = TEMPLATE_EMPTY
+        else:
+            template = _choose(
+                "Choose a project template:",
+                TEMPLATE_CHOICES,
+                default=TEMPLATE_EMPTY,
+            )
+
+    # Ensure scaffold exists — only for aipass_framework
    cwd = Path.cwd()
-    if not list(cwd.glob("*_REGISTRY.json")):
+    if template == TEMPLATE_AIPASS and not list(cwd.glob("*_REGISTRY.json")):
        from aipass.aipass.apps.handlers.init.bootstrap import init_project

        if not dry_run:
-            init_project(cwd)
+            with activity_spinner("Building project scaffold…"):
+                init_project(cwd)
+            success("Project scaffold ready")
        else:
            console.print("[yellow]\\[dry-run][/yellow] would create project scaffold")

@@ -797,29 +807,27 @@ def run_init(
    last_done = 0 if dry_run else _get_last_completed_stage()

    if last_done >= TOTAL_STAGES:
-        console.print("[green]✓[/green] Setup already complete.")
+        success("Setup already complete.")
        console.print("[dim]Run 'aipass doctor' to check status.[/dim]")
        return 0

    if last_done > 0:
        warning(f"Resuming from stage {last_done + 1}...")

-    accumulated: Dict[str, Any] = {}
+    accumulated: Dict[str, Any] = {"template": template}

    stage_fns = [
        (1, lambda: stage_1_welcome(dry_run=dry_run)),
        (2, lambda: stage_2_system_detect(non_interactive, dry_run=dry_run)),
-        (3, lambda: stage_3_doctor(non_interactive, dry_run=dry_run)),
-        (4, lambda: stage_4_user_profile(non_interactive, name, accumulated, dry_run=dry_run)),
-        (5, lambda: stage_5_style_questions(non_interactive, style, dry_run=dry_run)),
-        (6, lambda: stage_6_tool_choice(non_interactive, cli, dry_run=dry_run)),
-        (7, lambda: stage_7_docker_offer(non_interactive, no_docker, accumulated.get("has_docker"), dry_run=dry_run)),
-        (8, lambda: stage_8_first_agent(non_interactive, dry_run=dry_run)),
-        (9, lambda: stage_9_ping_sweep(non_interactive, dry_run=dry_run)),
-        (10, lambda: stage_10_smoke_test(non_interactive, dry_run=dry_run)),
+        (3, lambda: stage_3_user_profile(non_interactive, name, accumulated, dry_run=dry_run)),
+        (4, lambda: stage_4_style_questions(non_interactive, style, dry_run=dry_run)),
+        (5, lambda: stage_5_tool_choice(non_interactive, cli, dry_run=dry_run)),
+        (6, lambda: stage_6_first_agent(non_interactive, dry_run=dry_run)),
+        (7, lambda: stage_7_ping_sweep(non_interactive, dry_run=dry_run)),
+        (8, lambda: stage_8_smoke_test(non_interactive, dry_run=dry_run)),
        (
-            11,
-            lambda: stage_11_handoff(
+            9,
+            lambda: stage_9_handoff(
                accumulated.get("cli", "claude"),
                accumulated.get("flag_variant", "default"),
                accumulated.get("agent_path", "src/my_agent"),
@@ -828,12 +836,15 @@ def run_init(
                accumulated=accumulated,
            ),
        ),
-        (12, lambda: stage_12_done(accumulated=accumulated, dry_run=dry_run)),
+        (10, lambda: stage_10_done(accumulated=accumulated, dry_run=dry_run)),
    ]

    for stage_num, fn in stage_fns:
        if stage_num <= last_done:
            continue
+        if stage_num in AIPASS_SPECIFIC_STAGES and template != TEMPLATE_AIPASS:
+            logger.info("[init_flow] skipping stage %d (not aipass_framework)", stage_num)
+            continue
        try:
            result = fn() or {}
            accumulated.update(result)
@@ -846,6 +857,11 @@ def run_init(
            warning(f"Stage {stage_num} error: {exc} — continuing.")
            _save_stage(stage_num, {"error": str(exc)}, dry_run=dry_run)

+    if template != TEMPLATE_AIPASS:
+        console.print()
+        success("Project initialized.")
+        console.print("[dim]Run 'aipass init agent <name>' to add an agent.[/dim]")
+
    return 0


@@ -856,12 +872,12 @@ def print_introspection() -> None:
    last = progress.get("last_completed_stage", 0)
    console.print()
    console.print("[bold cyan]init_flow Module[/bold cyan]")
-    console.print("12-stage guided first-run setup, resumable")
+    console.print("10-stage guided first-run setup, resumable")
    console.print()
    if last == 0:
        console.print("[dim]Setup not started. Run: aipass init run[/dim]")
    elif last >= TOTAL_STAGES:
-        console.print("[green]✓[/green] Setup complete.")
+        success("Setup complete.")
    else:
        console.print(f"[yellow]In progress:[/yellow] stage {last}/{TOTAL_STAGES} completed.")
        console.print(f"[dim]Run 'aipass init run' to resume from stage {last + 1}.[/dim]")
@@ -876,12 +892,13 @@ 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 --template <name>[/green]    [dim]# select template[/dim]")
    console.print("  [green]aipass init run --dry-run[/green]            [dim]# walk all stages, no writes[/dim]")
+    console.print("  [green]aipass init --list[/green]                   [dim]# list available templates[/dim]")
    console.print()
-    console.print("[yellow]STAGES:[/yellow] 12 stages, each saved — resume on ctrl-C")
+    console.print("[yellow]STAGES:[/yellow] 10 stages, each saved — resume on ctrl-C")
    console.print()


@@ -894,7 +911,7 @@ def _handle_init_scaffold(args: list[str]) -> int:
    project_name = args[1] if len(args) > 1 else None
    try:
        result = init_project(target, project_name)
-        console.print(f"\n[green]✓[/green] Project initialized at [bold]{target}[/bold]")
+        success(f"Project initialized at {target}")
        console.print()

        # Find the package directory to show in guidance
@@ -921,7 +938,7 @@ def _handle_init_scaffold(args: list[str]) -> int:
        return 0
    except Exception as exc:
        logger.warning("[init_flow] scaffold failed: %s", exc)
-        console.print(f"[red]✗[/red] Init failed: {exc}")
+        cli_error(f"Init failed: {exc}")
        return 1


@@ -935,23 +952,39 @@ def _handle_init_update(args: list[str]) -> int:
        updated = result.get("updated_files", [])
        current = result.get("already_current", [])
        if updated:
-            console.print(f"[green]✓[/green] Updated {len(updated)} file(s):")
+            success(f"Updated {len(updated)} file(s):")
            for f in updated:
-                console.print(f"  [green]+[/green] {f}")
+                console.print(f"  + {f}")
        else:
-            console.print("[green]✓[/green] All files already current.")
+            success("All files already current.")
        if current:
            console.print(f"  ({len(current)} already up to date)")
-        # Heal registry: prune stale entries (e.g. cross-project ../paths)
+        # Owner/identity check + heal via the frozen sync-registry contract
        try:
-            sync_proc = subprocess.run(
-                ["drone", "@spawn", "sync-registry", "--fix"],
+            check_proc = subprocess.run(
+                ["drone", "@spawn", "sync-registry", "--check"],
                capture_output=True,
                text=True,
                timeout=30,
            )
-            if sync_proc.returncode == 0:
-                console.print("  [green]Registry synced.[/green]")
+            if check_proc.returncode != 0:
+                warning("Owner/identity issues detected — auto-repairing…")
+                fix_proc = subprocess.run(
+                    ["drone", "@spawn", "sync-registry", "--fix"],
+                    capture_output=True,
+                    text=True,
+                    timeout=60,
+                )
+                if fix_proc.returncode == 0:
+                    success("Registry owner/identity reconciled.")
+                else:
+                    logger.warning("[init_flow] sync-registry --fix exit %s", fix_proc.returncode)
+            else:
+                success("Owner/identity OK.")
+        except FileNotFoundError:
+            logger.info("[init_flow] drone not on PATH — skipping owner check")
+        except subprocess.TimeoutExpired:
+            logger.warning("[init_flow] sync-registry timed out during update")
        except Exception as sync_exc:
            logger.warning("[init_flow] registry sync during update skipped: %s", sync_exc)

@@ -959,14 +992,14 @@ def _handle_init_update(args: list[str]) -> int:
        return 0
    except Exception as exc:
        logger.warning("[init_flow] update failed: %s", exc)
-        console.print(f"[red]✗[/red] Update failed: {exc}")
+        cli_error(f"Update failed: {exc}")
        return 1


 def _handle_init_agent(args: list[str]) -> int:
    """Handle `aipass init agent <name>` — create a new agent via spawn."""
    if not args:
-        console.print("[red]✗[/red] Usage: aipass init agent <name>")
+        cli_error("Usage: aipass init agent <name>")
        return 1
    agent_name = args[0]
    import subprocess as _sp
@@ -1008,6 +1041,15 @@ def handle_command(command: str, args: list[str]) -> bool:
        sys.exit(_handle_init_update(args[1:]))
        return True

+    if args[0] == "--list":
+        console.print()
+        console.print("[bold cyan]Available project templates:[/bold cyan]")
+        for t in TEMPLATE_CHOICES:
+            marker = " [dim](default)[/dim]" if t == TEMPLATE_EMPTY else ""
+            console.print(f"  • {t}{marker}")
+        console.print()
+        return True
+
    if args[0] == "run" or args[0].startswith("--"):
        run_args = args[1:] if args[0] == "run" else args
        non_interactive = "--non-interactive" in run_args
@@ -1022,7 +1064,7 @@ def handle_command(command: str, args: list[str]) -> bool:
        name = _flag_value("--name")
        cli = _flag_value("--cli")
        style = _flag_value("--style")
-        no_docker = "--no-docker" in run_args
+        template = _flag_value("--template")
        dry_run = "--dry-run" in run_args

        result = run_init(
@@ -1030,8 +1072,8 @@ def handle_command(command: str, args: list[str]) -> bool:
            name=name,
            cli=cli,
            style=style,
-            no_docker=no_docker,
            dry_run=dry_run,
+            template=template,
        )
        json_handler.log_operation(
            "init_run",
@@ -1040,14 +1082,30 @@ def handle_command(command: str, args: list[str]) -> bool:
        sys.exit(result)
        return True

+    # Template name as positional arg
+    if args[0] in TEMPLATE_CHOICES:
+        result = run_init(template=args[0])
+        sys.exit(result)
+        return True
+
    # Positional args = target path and/or project name for scaffold
    err = _preflight_check()
    if err:
-        console.print(f"[red]✗[/red] {err}")
+        cli_error(str(err))
        sys.exit(1)
    sys.exit(_handle_init_scaffold(args))
    return True


 if __name__ == "__main__":
+    # Windows terminals/pipes default to cp1252, which can't encode the Unicode
+    # Rich emits (✓/✗, box-drawing). Reconfigure live streams to UTF-8 in place
+    # so a direct `python -m ...init_flow` run doesn't crash printing its banner.
+    # Guarded to win32 — mirrors apps/aipass.py (S190 / gap #1).
+    if sys.platform == "win32":
+        os.environ.setdefault("PYTHONUTF8", "1")
+        for _stream in (sys.stdout, sys.stderr):
+            if hasattr(_stream, "reconfigure"):
+                _stream.reconfigure(encoding="utf-8", errors="replace")
+
    handle_command("init", sys.argv[1:])
--- a/Show More
+++ b/Show More